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 java.util.Map layoutInfo

• fieldOrder

  static final java.util.Map fieldOrder

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)

• Structure

  protected Structure(Pointer p,
           int alignType,
           TypeMapper mapper)

Method Detail

• fields

  java.util.Map 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.

• getTypeMapper

  TypeMapper getTypeMapper()

  Return the type mapper in effect for this Structure.

• setStringEncoding

  protected void setStringEncoding(java.lang.String encoding)

  Set the desired encoding to use when writing String fields to native memory.

• getStringEncoding

  protected java.lang.String getStringEncoding()

  Encoding to use to convert String to native const char*. Defaults to Native.getDefaultStringEncoding().

• 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 based on natively-allocated data, nested within another, or otherwise overlaid on existing memory and thus does not own its own memory allocation.

• 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.

• size

  public int size()

  Returns the size in memory occupied by this Structure.

• 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.

• busy

  static java.util.Set busy()

• reading

  static java.util.Map reading()

• 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(java.lang.String name)

  Returns the calculated offset of the given field.

• 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

• getFieldValue

  java.lang.Object getFieldValue(java.lang.reflect.Field field)

  Obtain the value currently in the Java field. Does not read from memory.

• setFieldValue

  void setFieldValue(java.lang.reflect.Field field,
                   java.lang.Object value)

• 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

  protected 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

• writeField

  protected void writeField(Structure.StructField structField)

• getFieldOrder

  protected abstract java.util.List getFieldOrder()

  Return this Structure's field names in their proper order. For example,

  
   protected List getFieldOrder() {
       return Arrays.asList(new String[] { ... });
   }
   

  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 ArrayList(super.getFieldOrder());
       fields.addAll(Arrays.asList(new String[] { ... }));
       return fields;
   }
   

  Field order must be explicitly indicated, since the field order as returned by Class.getFields() is not guaranteed to be predictable.

• setFieldOrder

  protected final void setFieldOrder(java.lang.String[] fields)

  Deprecated. Use the required method getFieldOrder() instead to indicate the order of fields in this structure.
  Force a compile-time error on the old method of field definition

• sortFields

  protected void sortFields(java.util.List fields,
                java.util.List names)

  Sort the structure fields according to the given array of names.

• getFieldList

  protected java.util.List getFieldList()

  Look up all fields in this class and superclasses.

• getFields

  protected java.util.List 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:

  java.lang.Error - if force is true and field order data not yet specified and can't be generated automatically.

• size

  static int size(java.lang.Class type)

  Efficiently calculate the size of the given Structure subclass.

• size

  static int size(java.lang.Class type,
         Structure value)

  Efficiently calculate the size of the given Structure subclass.

• calculateSize

  int calculateSize(boolean force,
                  boolean avoidFFIType)

• 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

• toString

  public java.lang.String toString(boolean debug)

• 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 memory contents.

  Overrides:

  equals in class java.lang.Object

• hashCode

  public int hashCode()

  Since equals(java.lang.Object) depends on the contents of memory, use that as the basis for the hash code.

  Overrides:

  hashCode in class java.lang.Object

• cacheTypeInfo

  protected void cacheTypeInfo(Pointer p)

  Cache native type information for use in native code.

• getFieldTypeInfo

  Pointer getFieldTypeInfo(Structure.StructField f)

  Override to supply native type information for the given field.

• 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);
          

  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.

• 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,
                      Pointer init)
                               throws java.lang.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:

  java.lang.IllegalArgumentException - if the instantiation fails

• newInstance

  public static Structure newInstance(java.lang.Class type)
                               throws java.lang.IllegalArgumentException

  Create a new Structure instance of the given type

  Parameters:

  type - desired Structure type

  Returns:

  the new instance

  Throws:

  java.lang.IllegalArgumentException - if the instantiation fails

• typeInfoField

  Structure.StructField typeInfoField()

  Keep track of the largest aggregate field of the union to use for FFI type information.

• 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(java.lang.Class nativeType)

  Return the native size of the given Java type, from the perspective of this Structure.

• getNativeSize

  protected int getNativeSize(java.lang.Class nativeType,
                  java.lang.Object value)

  Return the native size of the given Java type, from the perspective of this Structure.

• validate

  static void validate(java.lang.Class cls)

  Indicate whether the given Structure class can be created by JNA.