com.sun.jna
public abstract class Structure extends Object
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:
volatile
JNA will not write the field unless specifically
instructed to do so via writeField.
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.
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.
Nested Class Summary | |
---|---|
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. |
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. |
static class | Structure.FFIType This class auto-generates an ffi_type structure appropriate for a given
structure for use by libffi. |
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 |
static boolean | isPPC |
static boolean | isSPARC |
static boolean | REQUIRES_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 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. |
static void | autoRead(Structure[] ss) |
void | autoRead() |
static void | autoWrite(Structure[] ss) |
void | autoWrite() |
static Set | busy() |
protected void | cacheTypeInfo(Pointer p) |
int | calculateAlignedSize(int calculatedSize) |
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. |
Map | fields() Return all fields in this structure (ordered). |
boolean | getAutoRead() Returns whether the struture is written to native memory prior to
a native function call. |
boolean | getAutoWrite() Returns whether the structure is read from native memory after a native
function call. |
Object | getField(Structure.StructField structField) Obtain the value currently in the Java field. |
protected List | getFieldOrder() |
protected int | getNativeAlignment(Class type, Object value, boolean isFirstElement) Overridable in subclasses. |
Pointer | getPointer() Return a Pointer object to this structure. |
protected int | getStructAlignment() |
Pointer | getTypeInfo() Obtain native type information for this structure. |
static Pointer | getTypeInfo(Object obj) Exposed for testing purposes only. |
int | hashCode() Since Structure 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. |
Object | readField(Structure.StructField structField) Read the given field and return its value. |
static Map | reading() |
protected void | setAlignType(int alignType) Change the alignment of this structure. |
void | setAutoRead(boolean auto) Set whether the struture is written to native memory prior to
a native function call. |
void | setAutoSynch(boolean auto) Set whether the structure is automatically synched to native memory
before and after a native function call. |
void | setAutoWrite(boolean auto) Set whether the structure is read from native memory after a native
function call. |
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(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.
|
String | toString() |
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. |
void | writeField(Structure.StructField structField) |
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
Parameters: type
Returns: the new instance
Throws: IllegalArgumentException if the instantiation fails
Returns: the new field value, after updating
Throws: IllegalArgumentException if no field exists with the given name
boolean auto = ...;
setAutoRead(auto);
setAutoWrite(auto);
null
, the default mapper for the
defining class will be used.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.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.Parameters: type Structure subclass s Original Structure object address the native struct *
Returns: Updated Structure.ByReference
object
Throws: IllegalArgumentException if no field exists with the given name
Throws: IllegalArgumentException if no field exists with the given name