JNA API 3.2.7
com.sun.jna

Class Structure

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class and Description
      static interface  Structure.ByReference
      Tagging interface to indicate the address of an instance of the Structure type is to be used within a Structure definition rather than nesting the full Structure contents.
      static interface  Structure.ByValue
      Tagging interface to indicate the value of an instance of the Structure type is to be used in function invocations rather than its address.
      (package private) static class  Structure.FFIType
      This class auto-generates an ffi_type structure appropriate for a given structure for use by libffi.
      (package private) class  Structure.StructField 
    • Field Summary

      Fields 
      Modifier and Type Field and Description
      static int ALIGN_DEFAULT
      Use the platform default alignment.
      static int ALIGN_GNUC
      validated for 32-bit x86 linux/gcc; align field size, max 4 bytes
      static int ALIGN_MSVC
      validated for w32/msvc; align on field size
      static int ALIGN_NONE
      No alignment, place all fields on nearest 1-byte boundary
      protected static int CALCULATE_SIZE 
      (package private) static boolean isPPC 
      (package private) static boolean isSPARC 
    • Method Summary

      Methods 
      Modifier and Type Method and Description
      protected void allocateMemory()
      Attempt to allocate memory if sufficient information is available.
      protected void allocateMemory(int size)
      Provided for derived classes to indicate a different size than the default.
      protected Memory autoAllocate(int size) 
      void autoRead() 
      static void autoRead(Structure[] ss) 
      void autoWrite() 
      static void autoWrite(Structure[] ss) 
      (package private) static java.util.Set busy() 
      protected void cacheTypeInfo(Pointer p) 
      (package private) int calculateAlignedSize(int calculatedSize) 
      (package private) int calculateSize(boolean force)
      Calculate the amount of native memory required for this structure.
      void clear() 
      protected void ensureAllocated() 
      boolean equals(java.lang.Object o)
      This structure is equal to another based on the same data type and visible data fields.
      (package private) java.util.Map fields()
      Return all fields in this structure (ordered).
      boolean getAutoRead()
      Returns whether the structure is read from native memory prior to a native function call.
      boolean getAutoWrite()
      Returns whether the structure is written to native memory after a native function call.
      (package private) java.lang.Object getField(Structure.StructField structField)
      Obtain the value currently in the Java field.
      protected java.util.List getFieldOrder() 
      protected java.util.List getFields(boolean force) 
      protected int getNativeAlignment(java.lang.Class type, java.lang.Object value, boolean isFirstElement)
      Overridable in subclasses.
      Pointer getPointer()
      Return a Pointer object to this structure.
      protected int getStructAlignment() 
      (package private) Pointer getTypeInfo()
      Obtain native type information for this structure.
      (package private) static Pointer getTypeInfo(java.lang.Object obj)
      Exposed for testing purposes only.
      int hashCode()
      Since equals(java.lang.Object) depends on the native address, use that as the hash code.
      static Structure newInstance(java.lang.Class type)
      Create a new Structure instance of the given type
      void read()
      Reads the fields of the struct from native memory
      java.lang.Object readField(java.lang.String name)
      Force a read of the given field from native memory.
      (package private) java.lang.Object readField(Structure.StructField structField)
      Read the given field and return its value.
      (package private) static java.util.Map reading() 
      protected void setAlignType(int alignType)
      Change the alignment of this structure.
      void setAutoRead(boolean auto)
      Set whether the structure is read from native memory prior to a native function call.
      void setAutoSynch(boolean auto)
      Set whether the structure is automatically synchronized to native memory before and after a native function call.
      void setAutoWrite(boolean auto)
      Set whether the structure is written to native memory after a native function call.
      (package private) void setField(Structure.StructField structField, java.lang.Object value) 
      protected void setFieldOrder(java.lang.String[] fields)
      Provided for VMs where the field order as returned by Class.getFields() is not predictable.
      protected void setTypeMapper(TypeMapper mapper)
      Change the type mapping for this structure.
      int size() 
      protected void sortFields(java.util.List fields, java.util.List names)
      Sort the structure fields according to the given array of names.
      Structure[] toArray(int size)
      Returns a view of this structure's memory as an array of structures.
      Structure[] toArray(Structure[] array)
      Returns a view of this structure's memory as an array of structures.
      java.lang.String toString() 
      (package private) static Structure updateStructureByReference(java.lang.Class type, Structure s, Pointer address)
      Only keep the original structure if its native address is unchanged.
      protected void useMemory(Pointer m)
      Set the memory used by this structure.
      protected void useMemory(Pointer m, int offset)
      Set the memory used by this structure.
      void write()
      Writes the fields of the struct to native memory
      void writeField(java.lang.String name)
      Write the given field to native memory.
      void writeField(java.lang.String name, java.lang.Object value)
      Write the given field value to the field and native memory.
      (package private) void writeField(Structure.StructField structField) 
      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, wait, wait, wait
    • Field Detail

      • isPPC

        static final boolean isPPC
      • isSPARC

        static final boolean isSPARC
      • 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
    • Constructor Detail

      • Structure

        protected Structure()
      • Structure

        protected Structure(TypeMapper mapper)
      • Structure

        protected Structure(Pointer p)
        Create a structure cast onto preallocated memory.
      • Structure

        protected Structure(Pointer p,
                 int alignment)
    • Method Detail

      • fields

        java.util.Map fields()
        Return all fields in this structure (ordered).
      • setTypeMapper

        protected void setTypeMapper(TypeMapper mapper)
        Change the type mapping for this structure. May cause the structure to be resized and any existing memory to be reallocated. If null, the default mapper for the defining class will be used.
      • 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.
      • autoAllocate

        protected Memory autoAllocate(int size)
      • 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.
      • 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 nested within another or otherwise overlaid on some other memory block and thus does not own its own memory.
      • ensureAllocated

        protected void ensureAllocated()
      • 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.
      • size

        public int size()
      • clear

        public void clear()
      • 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.
      • busy

        static java.util.Set busy()
      • reading

        static java.util.Map reading()
      • read

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

        public java.lang.Object readField(java.lang.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.
        Returns:
        the new field value, after updating
        Throws:
        java.lang.IllegalArgumentException - if no field exists with the given name
      • getField

        java.lang.Object getField(Structure.StructField structField)
        Obtain the value currently in the Java field. Does not read from memory.
      • updateStructureByReference

        static Structure updateStructureByReference(java.lang.Class type,
                                           Structure 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

        java.lang.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.
      • write

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

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

        public void writeField(java.lang.String name,
                      java.lang.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.
        Throws:
        java.lang.IllegalArgumentException - if no field exists with the given name
      • getFieldOrder

        protected java.util.List getFieldOrder()
      • setFieldOrder

        protected void setFieldOrder(java.lang.String[] fields)
        Provided for VMs where the field order as returned by Class.getFields() is not predictable.
      • sortFields

        protected void sortFields(java.util.List fields,
                      java.util.List names)
        Sort the structure fields according to the given array of names.
      • getFields

        protected java.util.List getFields(boolean force)
      • calculateSize

        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.

        Throws:
        java.lang.IllegalStateException - an array field is not initialized
        java.lang.IllegalArgumentException - when an unsupported field type is encountered
      • calculateAlignedSize

        int calculateAlignedSize(int calculatedSize)
      • getStructAlignment

        protected int getStructAlignment()
      • getNativeAlignment

        protected int getNativeAlignment(java.lang.Class type,
                             java.lang.Object value,
                             boolean isFirstElement)
        Overridable in subclasses.
      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.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.
      • 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.
      • equals

        public boolean equals(java.lang.Object o)
        This structure is equal to another based on the same data type and visible data fields.
        Overrides:
        equals in class java.lang.Object
      • hashCode

        public int hashCode()
        Since equals(java.lang.Object) depends on the native address, use that as the hash code.
        Overrides:
        hashCode in class java.lang.Object
      • cacheTypeInfo

        protected void cacheTypeInfo(Pointer p)
      • getTypeInfo

        Pointer getTypeInfo()
        Obtain 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);
                
      • setAutoRead

        public void setAutoRead(boolean auto)
        Set whether the structure is read from native memory prior to a native function call.
      • getAutoRead

        public boolean getAutoRead()
        Returns whether the structure is read from native memory prior to a native function call.
      • setAutoWrite

        public void setAutoWrite(boolean auto)
        Set whether the structure is written to native memory after a native function call.
      • getAutoWrite

        public boolean getAutoWrite()
        Returns whether the structure is written to native memory after a native function call.
      • getTypeInfo

        static Pointer getTypeInfo(java.lang.Object obj)
        Exposed for testing purposes only.
      • newInstance

        public static Structure newInstance(java.lang.Class type)
                                     throws java.lang.IllegalArgumentException
        Create a new Structure instance of the given type
        Parameters:
        type -
        Returns:
        the new instance
        Throws:
        java.lang.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()
JNA API 3.2.7

Copyright © 2007-2010 Timothy Wall. All Rights Reserved.