Structure (JNA API)

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

Direct Known Subclasses:

GDI32.BITMAPINFO, GDI32.BITMAPINFOHEADER, GDI32.RECT, GDI32.RGBQUAD, GDI32.RGNDATA, GDI32.RGNDATAHEADER, Kernel32.FILE_NOTIFY_INFORMATION, Kernel32.OVERLAPPED, Kernel32.SECURITY_ATTRIBUTES, Kernel32.SYSTEMTIME, Shell32.SHFILEOPSTRUCT, Union, User32.BLENDFUNCTION, User32.FLASHWINFO, User32.GUITHREADINFO, User32.KBDLLHOOKSTRUCT, User32.MSG, User32.POINT, User32.SIZE, User32.WINDOWINFO, X11.XGCValues, X11.XPoint, X11.XRectangle, X11.Xrender.XRenderDirectFormat, X11.Xrender.XRenderPictFormat, X11.XSetWindowAttributes, X11.XSizeHints, X11.XTextProperty, X11.XVisualInfo, X11.XWindowAttributes, X11.XWMHints
```
public abstract class Structure
extends java.lang.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.
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

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) 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`

Constructor Summary

Constructors
Modifier Constructor and Description

protected Structure()

protected Structure(int size)

protected Structure(int size, int alignment)

Constructors
Modifier	Constructor and Description
`protected`	`Structure()`
`protected`	`Structure(int size)`
`protected`	`Structure(int size, int alignment)`

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.
`(package private) int`	`calculateAlignedSize(int calculatedSize)`
`(package private) int`	`calculateSize(boolean force)` Calculate the amount of native memory required for this structure.
`void`	`clear()`
`boolean`	`equals(java.lang.Object o)` This structure is only equal to another based on the same native memory address and data type.
`(package private) java.util.Map`	`fields()` Return all fields in this structure (ordered).
`(package private) java.lang.Object`	`getField(Structure.StructField structField)` Obtain the value currently in the Java field.
`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.
`protected void`	`setAlignType(int alignType)` Change the alignment of this structure.
`protected void`	`setTypeMapper(TypeMapper mapper)` Change the type mapping for this structure.
`int`	`size()`
`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 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.
`(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(int size)
```
  - Structure
```
protected Structure(int size,
         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.
  - 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.
  - 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.
  - 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.
  - 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.
    
    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 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.
  - 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.
  - writeField
```
void writeField(Structure.StructField structField)
```
  - 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 a 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 a Memory backing, the memory will be resized to fit the entire array.
  - equals
```
public boolean equals(java.lang.Object o)
```
    This structure is only equal to another based on the same native memory address and data type.
    
    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
  - getTypeInfo
```
Pointer getTypeInfo()
```
    Obtain native type information for this structure.
  - 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

Class Structure

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

isPPC

isSPARC

ALIGN_DEFAULT

ALIGN_NONE

ALIGN_GNUC

ALIGN_MSVC

CALCULATE_SIZE

Constructor Detail

Structure

Structure

Structure

Method Detail

fields

setTypeMapper

setAlignType

useMemory

useMemory

allocateMemory

allocateMemory

size

clear

getPointer

read

readField

getField

updateStructureByReference

readField

write

writeField

writeField

calculateSize

calculateAlignedSize

getStructAlignment

getNativeAlignment

toString

toArray

toArray

equals

hashCode

getTypeInfo

getTypeInfo

newInstance