JNA API 3.2.7

## com.sun.jna
Class Structure

    java.lang.Object
      com.sun.jna.Structure

Direct Known Subclasses:
  Structure.FFIType, Union

    public abstract class Structure

extends Object

Represents a native structure with a Java peer class. When used as a function parameter or return value, this class corresponds to `struct*`. When used as a field within another `Structure`, it corresponds to `struct`. The tagging interfaces `Structure.ByReference` and `Structure.ByValue` may be used to alter the default behavior.

See the overview for supported type mappings.

Structure alignment and type mappings are derived by default from the enclosing interface definition (if any) by using `Native.getStructureAlignment(java.lang.Class)` and `Native.getTypeMapper(java.lang.Class)`.

Structure fields corresponding to native fields must be public. The may additionally have the following modifiers:

- `volatile` JNA will not write the field unless specifically instructed to do so via `writeField(String)`.
- `final` JNA will overwrite the field via `read()`, but otherwise the field is not modifiable from Java. Take care when using this option, since the compiler will usually assume all accesses to the field (for a given Structure instance) have the same value.

NOTE: Strings are used to represent native C strings because usage of `char *` is generally more common than `wchar_t *`.

NOTE: This class assumes that fields are returned in `Class.getFields()` in the same or reverse order as declared. If your VM returns them in no particular order, you're out of luck.

Author:
  Todd Fast, todd.fast@sun.com, twall@users.sf.net

Nested Class Summary
`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
`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`

Constructor Summary
`protected` | `Structure()`
`protected` | `Structure(Pointer p)` Create a structure cast onto preallocated memory.
`protected` | `Structure(Pointer p, int alignment)`
`protected` | `Structure(Pointer p, int alignment, TypeMapper mapper)`
`protected` | `Structure(TypeMapper mapper)`

Method Summary
`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 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(Object o)` This structure is equal to another based on the same data type and visible data fields.
`(package private) 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) Object` | `getField(Structure.StructField structField)` Obtain the value currently in the Java field.
`protected List` | `getFieldOrder()`
`protected List` | `getFields(boolean force)`
`protected int` | `getNativeAlignment(Class type, 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(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(Class type)` Create a new Structure instance of the given type
`void` | `read()` Reads the fields of the struct from native memory
`Object` | `readField(String name)` Force a read of the given field from native memory.
`(package private) Object` | `readField(Structure.StructField structField)` Read the given field and return its value.
`(package private) static 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, Object value)`
`protected void` | `setFieldOrder(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(List fields, 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.
`String` | `toString()`
`(package private) static Structure` | `updateStructureByReference(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(String name)` Write the given field to native memory.
`void` | `writeField(String name, 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

### CALCULATE_SIZE

    protected static final int CALCULATE_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)

### Structure

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

Method Detail

### fields

    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 Set busy()

### reading

    static Map reading()

### read

    public void read()

  Reads the fields of the struct from native memory

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

  Returns:
    the new field value, after updating
  Throws:
    `IllegalArgumentException` - if no field exists with the given name

### getField

    Object getField(Structure.StructField structField)

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

### setField

    void setField(Structure.StructField structField,
                  Object value)

### updateStructureByReference

    static Structure updateStructureByReference(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

    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(String name)

  Write the given field to native memory. The current value in the Java field will be translated into native memory.

  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.

  Throws:
    `IllegalArgumentException` - if no field exists with the given name

### writeField

    void writeField(Structure.StructField structField)

### getFieldOrder

    protected List getFieldOrder()

### setFieldOrder

    protected void setFieldOrder(String[] fields)

  Provided for VMs where the field order as returned by `Class.getFields()` is not predictable.

### sortFields

    protected void sortFields(List fields,
                              List names)

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

### getFields

    protected 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:
    `IllegalStateException` - an array field is not initialized
    `IllegalArgumentException` - when an unsupported field type is encountered

### calculateAlignedSize

    int calculateAlignedSize(int calculatedSize)

### getStructAlignment

    protected int getStructAlignment()

### getNativeAlignment

    protected int getNativeAlignment(Class type,
                                     Object value,
                                     boolean isFirstElement)

  Overridable in subclasses.

### toString

    public String toString()

  Overrides:
    `toString` in class `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(Object o)

  This structure is equal to another based on the same data type and visible data fields.

  Overrides:
    `equals` in class `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 `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(Object obj)

  Exposed for testing purposes only.

### newInstance

    public static Structure newInstance(Class type)
                                 throws IllegalArgumentException

  Create a new Structure instance of the given type

  Parameters:
    `type` -
  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()

JNA API 3.2.7

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