Package com.sun.jna

Class Structure

    • Field Detail

      • ALIGN_DEFAULT

        public static final int ALIGN_DEFAULT
        Use the platform default alignment.
        See Also:
        Constant Field Values

      • ALIGN_NONE

        public static final int ALIGN_NONE
        No alignment, place all fields on nearest 1-byte boundary
        See Also:
        Constant Field Values

      • ALIGN_GNUC

        public static final int ALIGN_GNUC
        validated for 32-bit x86 linux/gcc; align field size, max 4 bytes
        See Also:
        Constant Field Values

      • ALIGN_MSVC

        public static final int ALIGN_MSVC
        validated for w32/msvc; align on field size
        See Also:
        Constant Field Values

      • CALCULATE_SIZE

        protected static final int CALCULATE_SIZE
        Align to an 8-byte boundary.
        See Also:
        Constant Field Values

      • layoutInfo

        static final Map<Class<?>,​com.sun.jna.Structure.LayoutInfo> layoutInfo

    • Constructor Detail

      • Structure

        protected Structure()

      • Structure

        protected Structure​(TypeMapper mapper)

      • Structure

        protected Structure​(int alignType)

      • Structure

        protected Structure​(int alignType,
                    TypeMapper mapper)

      • Structure

        protected Structure​(Pointer p)
        Create a structure cast onto pre-allocated memory.

      • Structure

        protected Structure​(Pointer p,
                    int alignType)

    • Method Detail

      • fields

        Map<String,​Structure.StructField> fields()
        Return all fields in this structure (ordered). This represents the layout of the structure, and will be shared among Structures of the same class except when the Structure can have a variable size. NOTE: ensureAllocated() must be called prior to calling this method.
        Returns:
        Map of field names to field representations.

      • getTypeMapper

        TypeMapper getTypeMapper()
        Returns:
        the type mapper in effect for this Structure.

      • setStringEncoding

        protected void setStringEncoding​(String encoding)
        Set the desired encoding to use when writing String fields to native memory.
        Parameters:
        encoding - desired encoding

      • setAlignType

        protected void setAlignType​(int alignType)
        Change the alignment of this structure. Re-allocates memory if necessary. If alignment is ALIGN_DEFAULT, the default alignment for the defining class will be used.
        Parameters:
        alignType - desired alignment type

      • autoAllocate

        protected Memory autoAllocate​(int size)
        Obtain auto-allocated memory for use with struct represenations.
        Parameters:
        size - desired size
        Returns:
        newly-allocated memory

      • useMemory

        protected void useMemory​(Pointer m)
        Set the memory used by this structure. This method is used to indicate the given structure is nested within another or otherwise overlaid on some other memory block and thus does not own its own memory.
        Parameters:
        m - Memory to with which to back this Structure.

      • useMemory

        protected void useMemory​(Pointer m,
                         int offset)
        Set the memory used by this structure. This method is used to indicate the given structure is based on natively-allocated data, nested within another, or otherwise overlaid on existing memory and thus does not own its own memory allocation.
        Parameters:
        m - Base memory to use to back this structure.
        offset - offset into provided memory where structure mapping should start.

      • useMemory

        void useMemory​(Pointer m,
               int offset,
               boolean force)
        Set the memory used by this structure. This method is used to indicate the given structure is based on natively-allocated data, nested within another, or otherwise overlaid on existing memory and thus does not own its own memory allocation.
        Parameters:
        m - Native pointer
        offset - offset from pointer to use
        force - ByValue structures normally ignore requests to use a different memory offset; this input is set true when setting a ByValue struct that is nested within another struct.

      • ensureAllocated

        protected void ensureAllocated()
        Ensure this memory has its size and layout calculated and its memory allocated.

      • allocateMemory

        protected void allocateMemory()
        Attempt to allocate memory if sufficient information is available. Returns whether the operation was successful.

      • allocateMemory

        protected void allocateMemory​(int size)
        Provided for derived classes to indicate a different size than the default. Returns whether the operation was successful. Will leave memory untouched if it is non-null and not allocated by this class.
        Parameters:
        size - how much memory to allocate

      • size

        public int size()
        Returns the size in memory occupied by this Structure.
        Returns:
        Native size of this structure, in bytes.

      • clear

        public void clear()
        Clears the native memory associated with this Structure.

      • getPointer

        public Pointer getPointer()
        Return a Pointer object to this structure. Note that if you use the structure's pointer as a function argument, you are responsible for calling write() prior to the call and read() after the call. These calls are normally handled automatically by the Function object when it encounters a Structure argument or return value. The returned pointer may not have meaning for Structure.ByValue structure representations.
        Returns:
        Native pointer representation of this structure.

      • conditionalAutoRead

        void conditionalAutoRead()
        Performs auto-read only if uninitialized.

      • read

        public void read()
        Reads the fields of the struct from native memory

      • fieldOffset

        protected int fieldOffset​(String name)
        Returns the calculated offset of the given field.
        Parameters:
        name - field to examine
        Returns:
        return offset of the given field

      • readField

        public Object readField​(String name)
        Force a read of the given field from native memory. The Java field will be updated from the current contents of native memory.
        Parameters:
        name - field to be read
        Returns:
        the new field value, after updating
        Throws:
        IllegalArgumentException - if no field exists with the given name

      • getFieldValue

        Object getFieldValue​(Field field)
        Obtain the value currently in the Java field. Does not read from native memory.
        Parameters:
        field - field to look up
        Returns:
        current field value (Java-side only)

      • setFieldValue

        void setFieldValue​(Field field,
                   Object value)
        Parameters:
        field - field to set
        value - value to set

      • updateStructureByReference

        static <T extends Structure> T updateStructureByReference​(Class<T> type,
                                                          T s,
                                                          Pointer address)
        Only keep the original structure if its native address is unchanged. Otherwise replace it with a new object.
        Parameters:
        type - Structure subclass
        s - Original Structure object
        address - the native struct *
        Returns:
        Updated Structure.ByReference object

      • readField

        protected Object readField​(Structure.StructField structField)
        Read the given field and return its value. The Java field will be updated from the contents of native memory.
        Parameters:
        structField - field to be read
        Returns:
        value of the requested field

      • write

        public void write()
        Writes the fields of the struct to native memory

      • writeField

        public void writeField​(String name)
        Write the given field to native memory. The current value in the Java field will be translated into native memory.
        Parameters:
        name - which field to synch
        Throws:
        IllegalArgumentException - if no field exists with the given name

      • writeField

        public void writeField​(String name,
                       Object value)
        Write the given field value to the field and native memory. The given value will be written both to the Java field and the corresponding native memory.
        Parameters:
        name - field to write
        value - value to write
        Throws:
        IllegalArgumentException - if no field exists with the given name

      • writeField

        protected void writeField​(Structure.StructField structField)
        Parameters:
        structField - internal field representation to synch to native memory

      • getFieldOrder

        protected List<String> getFieldOrder()
        Returns this Structure's field names in their proper order.
        When defining a new Structure you shouldn't override this method, but use Structure.FieldOrder annotation to define your field order(this also works with inheritance)
        If you want to do something non-standard you can override the method and define it as followed 
        
 protected List getFieldOrder() {
     return Arrays.asList(...);
 }
        IMPORTANT When deriving from an existing Structure subclass, ensure that you augment the list provided by the superclass, e.g. 
        
 protected List getFieldOrder() {
     List fields = new LinkedList(super.getFieldOrder());
     fields.addAll(Arrays.asList(...));
     return fields;
 }
        Field order must be explicitly indicated, since the field order as returned by Class.getFields() is not guaranteed to be predictable.
        Returns:
        ordered list of field names

      • sortFields

        protected void sortFields​(List<Field> fields,
                          List<String> names)
        Sort the structure fields according to the given array of names.
        Parameters:
        fields - list of fields to be sorted
        names - list of names representing the desired sort order

      • getFieldList

        protected List<Field> getFieldList()
        Look up all fields in this class and superclasses.
        Returns:
        ordered list of public Field available on this Structure class.

      • createFieldsOrder

        public static List<String> createFieldsOrder​(String field)
        Parameters:
        field - The (single) field name
        Returns:

      • createFieldsOrder

        public static List<String> createFieldsOrder​(String... fields)
        Parameters:
        fields - The structure field names in correct order
        Returns:
        An un-modifiable list of the fields

      • getFields

        protected List<Field> getFields​(boolean force)
        Returns all field names (sorted) provided so far by getFieldOrder()
        Parameters:
        force - set if results are required immediately
        Returns:
        null if not yet able to provide fields, and force is false.
        Throws:
        Error - if force is true and field order data not yet specified and can't be generated automatically.

      • calculateSize

        protected int calculateSize​(boolean force)
        Calculate the amount of native memory required for this structure. May return CALCULATE_SIZE if the size can not yet be determined (usually due to fields in the derived class not yet being initialized). If the force parameter is true will throw an IllegalStateException if the size can not be determined.
        Parameters:
        force - whether to force size calculation
        Returns:
        calculated size, or CALCULATE_SIZE if the size can not yet be determined.
        Throws:
        IllegalStateException - an array field is not initialized or the size can not be determined while force is true.
        IllegalArgumentException - when an unsupported field type is encountered

      • size

        static int size​(Class<? extends Structure> type)
        Efficiently calculate the size of the given Structure subclass.
        Parameters:
        type - Structure subclass to check
        Returns:
        native size of the given Structure subclass

      • size

        static <T extends Structure> int size​(Class<T> type,
                                      T value)
        Efficiently calculate the size of the given Structure subclass.
        Parameters:
        type - Structure subclass to check
        value - optional instance of the given class
        Returns:
        native size of the Structure subclass

      • calculateSize

        int calculateSize​(boolean force,
                  boolean avoidFFIType)
        Parameters:
        force - whether to force size calculation.
        avoidFFIType - set false in certain situations to avoid recursive type lookup.
        Returns:
        calculated size, or CALCULATE_SIZE if there is not yet enough information to perform the size calculation.

      • getStructAlignment

        protected int getStructAlignment()
        Returns:
        current alignment setting for this structure

      • getNativeAlignment

        protected int getNativeAlignment​(Class<?> type,
                                 Object value,
                                 boolean isFirstElement)
        Overridable in subclasses. Calculate the appropriate alignment for a field of a given type within this struct.
        Parameters:
        type - field type
        value - field value, if available
        isFirstElement - is this field the first element in the struct?
        Returns:
        the native byte alignment

      • toString

        public String toString()
        If jna.dump_memory is true, will include a native memory dump of the Structure's backing memory.
        Overrides:
        toString in class Object
        Returns:
        String representation of this object.

      • toString

        public String toString​(boolean debug)
        Parameters:
        debug - If true, will include a native memory dump of the Structure's backing memory.
        Returns:
        String representation of this object.

      • toArray

        public Structure[] toArray​(Structure[] array)
        Returns a view of this structure's memory as an array of structures. Note that this Structure must have a public, no-arg constructor. If the structure is currently using auto-allocated Memory backing, the memory will be resized to fit the entire array.
        Parameters:
        array - Structure[] object to populate
        Returns:
        array of Structure mapped onto the available memory

      • toArray

        public Structure[] toArray​(int size)
        Returns a view of this structure's memory as an array of structures. Note that this Structure must have a public, no-arg constructor. If the structure is currently using auto-allocated Memory backing, the memory will be resized to fit the entire array.
        Parameters:
        size - desired number of elements
        Returns:
        array of Structure (individual elements will be of the appropriate type, as will the Structure[]).

      • dataEquals

        public boolean dataEquals​(Structure s)
        Return whether the given Structure's native backing data is identical to this one.
        Parameters:
        s - Structure to compare
        Returns:
        equality result

      • dataEquals

        public boolean dataEquals​(Structure s,
                          boolean clear)
        Return whether the given Structure's backing data is identical to this one, optionally clearing and re-writing native memory before checking.
        Parameters:
        s - Structure to compare
        clear - whether to clear native memory
        Returns:
        equality result

      • equals

        public boolean equals​(Object o)
        Overrides:
        equals in class Object
        Returns:
        whether the given structure's type and pointer match.

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object
        Returns:
        hash code for this structure's pointer.

      • cacheTypeInfo

        protected void cacheTypeInfo​(Pointer p)
        Cache native type information for use in native code.
        Parameters:
        p - Native pointer to the type information

      • getFieldTypeInfo

        Structure.FFIType getFieldTypeInfo​(Structure.StructField f)
        Override to supply native type information for the given field.
        Parameters:
        f - internal field representation
        Returns:
        Native pointer to the corresponding type information

      • getTypeInfo

        Pointer getTypeInfo()
        Returns:
        native type information for this structure.

      • setAutoSynch

        public void setAutoSynch​(boolean auto)
        Set whether the structure is automatically synchronized to native memory before and after a native function call. Convenience method for 
        
        boolean auto = ...;
        setAutoRead(auto);
        setAutoWrite(auto);
        For extremely large or complex structures where you only need to access a small number of fields, you may see a significant performance benefit by avoiding automatic structure reads and writes. If auto-read and -write are disabled, it is up to you to ensure that the Java fields of interest are synched before and after native function calls via readField(String) and writeField(String,Object). This is typically most effective when a native call populates a large structure and you only need a few fields out of it. After the native call you can call readField(String) on only the fields of interest.
        Parameters:
        auto - whether to automatically synch with native memory.

      • setAutoRead

        public void setAutoRead​(boolean auto)
        Set whether the structure is read from native memory after a native function call.
        Parameters:
        auto - whether to automatically synch from native memory.

      • getAutoRead

        public boolean getAutoRead()
        Returns whether the structure is read from native memory after a native function call.
        Returns:
        whether automatic synch from native memory is enabled.

      • setAutoWrite

        public void setAutoWrite​(boolean auto)
        Set whether the structure is written to native memory prior to a native function call.
        Parameters:
        auto - whether to automatically synch to native memory.

      • getAutoWrite

        public boolean getAutoWrite()
        Returns whether the structure is written to native memory prior to a native function call.
        Returns:
        whether automatic synch to native memory is enabled.

      • getTypeInfo

        static Structure.FFIType getTypeInfo​(Object obj)
        Exposed for testing purposes only.
        Parameters:
        obj - object to query
        Returns:
        native pointer to type information

      • newInstance

        public static <T extends Structure> T newInstance​(Class<T> type,
                                                  Pointer init)
                                           throws IllegalArgumentException
        Create a new Structure instance of the given type, initialized with the given memory.
        Parameters:
        type - desired Structure type
        init - initial memory
        Returns:
        the new instance
        Throws:
        IllegalArgumentException - if the instantiation fails

      • autoRead

        public static void autoRead​(Structure[] ss)

      • autoRead

        public void autoRead()

      • autoWrite

        public static void autoWrite​(Structure[] ss)

      • autoWrite

        public void autoWrite()

      • getNativeSize

        protected int getNativeSize​(Class<?> nativeType)
        Return the native size of the given Java type, from the perspective of this Structure.
        Parameters:
        nativeType - field type to examine
        Returns:
        native size (in bytes) of the requested field type

      • getNativeSize

        protected int getNativeSize​(Class<?> nativeType,
                            Object value)
        Return the native size of the given Java type, from the perspective of this Structure.
        Parameters:
        nativeType - field type to examine
        value - instance of the field type
        Returns:
        native size (in bytes) of the requested field type

      • validate

        static void validate​(Class<? extends Structure> cls)
        Indicate whether the given Structure class can be created by JNA.
        Parameters:
        cls - Structure subclass to check