public abstract class Structure extends Object
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. Structures may have variable size, but only
by providing an array field (e.g. byte[]).
See the overview for supported type mappings for struct fields.
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)
.
Alternatively you can explicitly provide alignment, field order, or type
mapping by calling the respective Structure functions in your subclass's
constructor.
getFieldOrder()
to return a List of
field names (Strings) indicating the proper order of the fields. When
dealing with multiple levels of subclasses of Structure, you must add to
the list provided by the superclass getFieldOrder()
the fields defined in the current class.
In the past, most VMs would return them in a predictable order, but the JVM
spec does not require it, so getFieldOrder()
is now required to
ensure JNA knows the proper order).
Structure fields may additionally have the following modifiers:volatile
JNA will not write the field unless specifically
instructed to do so via writeField(String)
. This allows you to
prevent inadvertently overwriting memory that may be updated in real time
on another (possibly native) thread.
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. This
modifier is invalid to use on J2ME.
char *
is generally more common than wchar_t *
.
You may provide a type mapper (example here)
if you prefer to use String in place of WString
if
your native code predominantly uses wchar_t *
.
NOTE: In general, instances of this class are not synchronized.
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) static class |
Structure.FFIType
This class auto-generates an ffi_type structure appropriate for a given
structure for use by libffi.
|
(package private) static class |
Structure.StructField |
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 Map |
fieldOrder |
(package private) static boolean |
isARM |
(package private) static boolean |
isPPC |
(package private) static boolean |
isSPARC |
(package private) static Map |
layoutInfo |
(package private) static int |
MAX_GNUC_ALIGNMENT
Align to an 8-byte boundary.
|
Modifier | Constructor and Description |
---|---|
protected |
Structure() |
protected |
Structure(int alignType) |
protected |
Structure(int alignType,
TypeMapper mapper) |
protected |
Structure(Pointer p)
Create a structure cast onto pre-allocated memory.
|
protected |
Structure(Pointer p,
int alignType) |
protected |
Structure(Pointer p,
int alignType,
TypeMapper mapper) |
protected |
Structure(TypeMapper mapper) |
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.
|
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)
Cache native type information for use in native code.
|
(package private) int |
calculateAlignedSize(int calculatedSize) |
(package private) int |
calculateSize(boolean force,
boolean avoidFFIType) |
void |
clear() |
protected void |
ensureAllocated()
Ensure this memory has its size and layout calculated and its
memory allocated.
|
boolean |
equals(Object o)
This structure is equal to another based on the same data type
and memory contents.
|
protected int |
fieldOffset(String name)
Returns the calculated offset of the given field.
|
(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.
|
protected List |
getFieldList()
Look up all fields in this class and superclasses.
|
protected abstract List |
getFieldOrder()
Return this Structure's field names in their proper order.
|
protected List |
getFields(boolean force)
Returns all field names (sorted) provided so far by
getFieldOrder() |
(package private) Pointer |
getFieldTypeInfo(Structure.StructField f)
Override to supply native type information for the given field.
|
(package private) Object |
getFieldValue(Field field)
Obtain the value currently in the Java field.
|
protected int |
getNativeAlignment(Class type,
Object value,
boolean isFirstElement)
Overridable in subclasses.
|
protected int |
getNativeSize(Class nativeType)
Return the native size of the given Java type, from the perspective of
this Structure.
|
protected int |
getNativeSize(Class nativeType,
Object value)
Return the native size of the given Java type, from the perspective of
this Structure.
|
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.
|
(package private) TypeMapper |
getTypeMapper()
Return the type mapper in effect for this Structure.
|
int |
hashCode()
Since
equals(java.lang.Object) depends on the contents of memory, use that
as the basis for 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.
|
protected void |
setFieldOrder(String[] fields)
Deprecated.
Use the required method getFieldOrder() instead to
indicate the order of fields in this structure.
|
(package private) void |
setFieldValue(Field field,
Object value) |
protected void |
setTypeMapper(TypeMapper mapper)
Deprecated.
You should use one of
Structure(TypeMapper)
or Structure(Pointer,int,TypeMapper) constructors instead. |
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() |
String |
toString(boolean debug) |
(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) |
static final boolean isPPC
static final boolean isSPARC
static final boolean isARM
public static final int ALIGN_DEFAULT
public static final int ALIGN_NONE
public static final int ALIGN_GNUC
public static final int ALIGN_MSVC
static final int MAX_GNUC_ALIGNMENT
protected static final int CALCULATE_SIZE
static final Map layoutInfo
static final Map fieldOrder
protected Structure()
protected Structure(TypeMapper mapper)
protected Structure(int alignType)
protected Structure(int alignType, TypeMapper mapper)
protected Structure(Pointer p)
protected Structure(Pointer p, int alignType)
protected Structure(Pointer p, int alignType, TypeMapper mapper)
Map fields()
ensureAllocated()
must be called prior to
calling this method.TypeMapper getTypeMapper()
protected void setTypeMapper(TypeMapper mapper)
Structure(TypeMapper)
or Structure(Pointer,int,TypeMapper)
constructors instead.null
, the default mapper for the
defining class will be used.protected void setAlignType(int alignType)
ALIGN_DEFAULT
, the default
alignment for the defining class will be used.protected Memory autoAllocate(int size)
protected void useMemory(Pointer m)
protected void useMemory(Pointer m, int offset)
protected void ensureAllocated()
protected void allocateMemory()
protected void allocateMemory(int size)
public int size()
public void clear()
public Pointer getPointer()
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.static Set busy()
static Map reading()
public void read()
protected int fieldOffset(String name)
public Object readField(String name)
IllegalArgumentException
- if no field exists with the given nameObject getFieldValue(Field field)
static Structure updateStructureByReference(Class type, Structure s, Pointer address)
type
- Structure subclasss
- Original Structure objectaddress
- the native struct *
Structure.ByReference
objectObject readField(Structure.StructField structField)
public void write()
public void writeField(String name)
IllegalArgumentException
- if no field exists with the given namepublic void writeField(String name, Object value)
IllegalArgumentException
- if no field exists with the given namevoid writeField(Structure.StructField structField)
protected abstract List getFieldOrder()
protected List getFieldOrder() {
return Arrays.asList(new String[] { ... });
}
IMPORTANT
When deriving from an existing Structure subclass, ensure that
you augment the list provided by the superclass, e.g.
protected List getFieldOrder() {
List fields = new ArrayList(super.getFieldOrder());
fields.addAll(Arrays.asList(new String[] { ... }));
return fields;
}
Field order must be explicitly indicated, since the
field order as returned by Class.getFields()
is not
guaranteed to be predictable.protected final void setFieldOrder(String[] fields)
protected void sortFields(List fields, List names)
protected List getFieldList()
protected List getFields(boolean force)
getFieldOrder()
force
- set if results are required immediatelyError
- if force is true and field order data not yet specified
and can't be generated automatically.int calculateSize(boolean force, boolean avoidFFIType)
int calculateAlignedSize(int calculatedSize)
protected int getStructAlignment()
protected int getNativeAlignment(Class type, Object value, boolean isFirstElement)
public String toString(boolean debug)
public Structure[] toArray(Structure[] 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.public Structure[] toArray(int size)
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.public boolean equals(Object o)
public int hashCode()
equals(java.lang.Object)
depends on the contents of memory, use that
as the basis for the hash code.protected void cacheTypeInfo(Pointer p)
Pointer getFieldTypeInfo(Structure.StructField f)
Pointer getTypeInfo()
public void setAutoSynch(boolean auto)
boolean auto = ...;
setAutoRead(auto);
setAutoWrite(auto);
public void setAutoRead(boolean auto)
public boolean getAutoRead()
public void setAutoWrite(boolean auto)
public boolean getAutoWrite()
public static Structure newInstance(Class type) throws IllegalArgumentException
type
- IllegalArgumentException
- if the instantiation failspublic static void autoRead(Structure[] ss)
public void autoRead()
public static void autoWrite(Structure[] ss)
public void autoWrite()
protected int getNativeSize(Class nativeType)