com.sun.jna
Class Structure

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

Direct Known Subclasses:

Structure.FFIType, Union

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

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

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.

setField

void setField(Structure.StructField structField,
              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

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

void writeField(Structure.StructField structField)

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