com.sun.jna

Class Structure

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 ByReference and 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 and Native.

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

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
interfaceStructure.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.
interfaceStructure.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.
static classStructure.FFIType
This class auto-generates an ffi_type structure appropriate for a given structure for use by libffi.
classStructure.StructField
Field Summary
static intALIGN_DEFAULT
Use the platform default alignment.
static intALIGN_GNUC
validated for 32-bit x86 linux/gcc; align field size, max 4 bytes
static intALIGN_MSVC
validated for w32/msvc; align on field size
static intALIGN_NONE
No alignment, place all fields on nearest 1-byte boundary
protected static intCALCULATE_SIZE
static booleanisPPC
static booleanisSPARC
static booleanREQUIRES_FIELD_ORDER
Constructor Summary
protected Structure()
protected Structure(TypeMapper mapper)
protected Structure(Pointer p)
Create a structure cast onto pre-allocated memory.
protected Structure(Pointer p, int alignment)
protected Structure(Pointer p, int alignment, TypeMapper mapper)
Method Summary
protected voidallocateMemory()
Attempt to allocate memory if sufficient information is available.
protected voidallocateMemory(int size)
Provided for derived classes to indicate a different size than the default.
static voidautoRead(Structure[] ss)
voidautoRead()
static voidautoWrite(Structure[] ss)
voidautoWrite()
static Setbusy()
protected voidcacheTypeInfo(Pointer p)
intcalculateAlignedSize(int calculatedSize)
intcalculateSize(boolean force)
Calculate the amount of native memory required for this structure.
voidclear()
protected voidensureAllocated()
booleanequals(Object o)
This structure is equal to another based on the same data type and visible data fields.
Mapfields()
Return all fields in this structure (ordered).
booleangetAutoRead()
Returns whether the struture is written to native memory prior to a native function call.
booleangetAutoWrite()
Returns whether the structure is read from native memory after a native function call.
ObjectgetField(Structure.StructField structField)
Obtain the value currently in the Java field.
protected ListgetFieldOrder()
protected intgetNativeAlignment(Class type, Object value, boolean isFirstElement)
Overridable in subclasses.
PointergetPointer()
Return a Pointer object to this structure.
protected intgetStructAlignment()
PointergetTypeInfo()
Obtain native type information for this structure.
static PointergetTypeInfo(Object obj)
Exposed for testing purposes only.
inthashCode()
Since Structure depends on the native address, use that as the hash code.
static StructurenewInstance(Class type)
Create a new Structure instance of the given type
voidread()
Reads the fields of the struct from native memory
ObjectreadField(String name)
Force a read of the given field from native memory.
ObjectreadField(Structure.StructField structField)
Read the given field and return its value.
static Mapreading()
protected voidsetAlignType(int alignType)
Change the alignment of this structure.
voidsetAutoRead(boolean auto)
Set whether the struture is written to native memory prior to a native function call.
voidsetAutoSynch(boolean auto)
Set whether the structure is automatically synched to native memory before and after a native function call.
voidsetAutoWrite(boolean auto)
Set whether the structure is read from native memory after a native function call.
voidsetField(Structure.StructField structField, Object value)
protected voidsetFieldOrder(String[] fields)
Provided for VMs where the field order as returned by Class#getFields() is not predictable.
protected voidsetTypeMapper(TypeMapper mapper)
Change the type mapping for this structure.
intsize()
protected voidsortFields(Field[] fields, String[] names)
Sort the structure fields according to the given array of names.
Structure[]toArray(Structure[] array)
Returns a view of this structure's memory as an array of structures.
Structure[]toArray(int size)
Returns a view of this structure's memory as an array of structures.
StringtoString()
static StructureupdateStructureByReference(Class type, Structure s, Pointer address)
Only keep the original structure if its native address is unchanged.
protected voiduseMemory(Pointer m)
Set the memory used by this structure.
protected voiduseMemory(Pointer m, int offset)
Set the memory used by this structure.
voidwrite()
Writes the fields of the struct to native memory
voidwriteField(String name)
Write the given field to native memory.
voidwriteField(String name, Object value)
Write the given field value to the field and native memory.
voidwriteField(Structure.StructField structField)

Field Detail

ALIGN_DEFAULT

public static final int ALIGN_DEFAULT
Use the platform default alignment.

ALIGN_GNUC

public static final int ALIGN_GNUC
validated for 32-bit x86 linux/gcc; align field size, max 4 bytes

ALIGN_MSVC

public static final int ALIGN_MSVC
validated for w32/msvc; align on field size

ALIGN_NONE

public static final int ALIGN_NONE
No alignment, place all fields on nearest 1-byte boundary

CALCULATE_SIZE

protected static final int CALCULATE_SIZE

isPPC

static final boolean isPPC

isSPARC

static final boolean isSPARC

REQUIRES_FIELD_ORDER

static boolean REQUIRES_FIELD_ORDER

Constructor Detail

Structure

protected Structure()

Structure

protected Structure(TypeMapper mapper)

Structure

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

Structure

protected Structure(Pointer p, int alignment)

Structure

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

Method Detail

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.

autoRead

public static void autoRead(Structure[] ss)

autoRead

public void autoRead()

autoWrite

public static void autoWrite(Structure[] ss)

autoWrite

public void autoWrite()

busy

static Set busy()

cacheTypeInfo

protected void cacheTypeInfo(Pointer p)

calculateAlignedSize

int calculateAlignedSize(int calculatedSize)

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

clear

public void clear()

ensureAllocated

protected void ensureAllocated()

equals

public boolean equals(Object o)
This structure is equal to another based on the same data type and visible data fields.

fields

Map fields()
Return all fields in this structure (ordered).

getAutoRead

public boolean getAutoRead()
Returns whether the struture is written to native memory prior to a native function call.

getAutoWrite

public boolean getAutoWrite()
Returns whether the structure is read from native memory after a native function call.

getField

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

getFieldOrder

protected List getFieldOrder()

getNativeAlignment

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

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.

getStructAlignment

protected int getStructAlignment()

getTypeInfo

Pointer getTypeInfo()
Obtain native type information for this structure.

getTypeInfo

static Pointer getTypeInfo(Object obj)
Exposed for testing purposes only.

hashCode

public int hashCode()
Since Structure depends on the native address, use that as the hash code.

newInstance

public static Structure newInstance(Class type)
Create a new Structure instance of the given type

Parameters: type

Returns: the new instance

Throws: IllegalArgumentException if the instantiation fails

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

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.

reading

static Map reading()

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.

setAutoRead

public void setAutoRead(boolean auto)
Set whether the struture is written to native memory prior to a native function call.

setAutoSynch

public void setAutoSynch(boolean auto)
Set whether the structure is automatically synched to native memory before and after a native function call. Convenience method for

        boolean auto = ...;
        setAutoRead(auto);
        setAutoWrite(auto);
        

setAutoWrite

public void setAutoWrite(boolean auto)
Set whether the structure is read from native memory after a native function call.

setField

void setField(Structure.StructField structField, Object value)

setFieldOrder

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

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.

size

public int size()

sortFields

protected void sortFields(Field[] fields, String[] names)
Sort the structure fields according to the given array of names.

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.

toString

public String toString()

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

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.

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)
Copyright © 2007-2009 Timothy Wall. All Rights Reserved.