NOTE: Strings are used to represent native C strings because usage of
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 *
.
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.
This class auto-generates an ffi_type structure appropriate for a given
structure for use by libffi.
Avoid using a hash-based implementation since the hash code
for a Structure is not immutable.
Provided for derived classes to indicate a different
size than the default.
Return whether the given Structure's native backing data is identical to
this one.
Return whether the given Structure's backing data is identical to
this one, optionally clearing and re-writing native memory before checking.
Ensure this memory has its size and layout calculated and its
memory allocated.
Returns whether the structure is read from native memory prior to
a native function call.
Returns whether the structure is written to native memory after a native
function call.
Return the native size of the given Java type, from the perspective of
this Structure.
Return the native size of the given Java type, from the perspective of
this Structure.
Create a new Structure instance of the given type, initialized with
the given memory.
Set whether the structure is read from native memory prior to
a native function call.
Set whether the structure is automatically synchronized to native memory
before and after a native function call.
Set whether the structure is written to native memory after a native
function call.
Deprecated.
protected void
setStringEncoding
(
String
encoding)
Set the desired encoding to use when writing String fields to native
memory.
size
()
Returns the size in memory occupied by this Structure.
(package private) static int
size
(
Class
type)
Efficiently calculate the size of the given Structure subclass.
(package private) static int
size
(
Class
type,
Structure
value)
Efficiently calculate the size of the given Structure subclass.
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
()
If
jna.dump_memory
is true, will include a native memory dump
of the Structure's backing memory.
String
toString
(boolean debug)
(package private)
Structure.StructField
typeInfoField
()
Keep track of the largest aggregate field of the union to use for
FFI type information.
(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.
(package private) void
useMemory
(
Pointer
m,
int offset,
boolean force)
Set the memory used by this structure.
(package private) static void
validate
(
Class
cls)
Indicate whether the given Structure class can be created by JNA.
write
()
Writes the fields of the struct to native memory
writeField
(
String
name)
Write the given field to native memory.
writeField
(
String
name,
Object
value)
Write the given field value to the field and native memory.
protected void
writeField
(
Structure.StructField
structField)
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
Map fields()
Return all fields in this structure (ordered). This represents the
layout of the structure, and will be shared among Structures of the
same class except when the Structure can have a variable size.
NOTE:
ensureAllocated()
must
be called prior to
calling this method.
Map
of field names to field representations.
setStringEncoding
protected void setStringEncoding(String encoding)
Set the desired encoding to use when writing String fields to native
memory.
Parameters:
encoding
- desired encoding
getStringEncoding
protected String getStringEncoding()
Returns:
Current encoding
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.
alignType
- desired alignment type
autoAllocate
protected Memory autoAllocate(int size)
Obtain auto-allocated memory for use with struct represenations.
Parameters:
size
- desired size
Returns:
newly-allocated memory
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.
Parameters:
m
- Memory to with which to back this
Structure
.
protected void useMemory(Pointer m,
int offset)
Set the memory used by this structure. This method is used to
indicate the given structure is based on natively-allocated data,
nested within another, or otherwise overlaid on existing memory and
thus does not own its own memory allocation.
Parameters:
m
- Base memory to use to back this structure.
offset
- offset into provided memory where structure mapping
should start.
boolean force)
Set the memory used by this structure. This method is used to
indicate the given structure is based on natively-allocated data,
nested within another, or otherwise overlaid on existing memory and
thus does not own its own memory allocation.
Parameters:
m
- Native pointer
offset
- offset from pointer to use
force
- ByValue structures normally ignore requests to use a
different memory offset; this input is set
true
when
setting a ByValue struct that is nested within another struct.
ensureAllocated
protected void ensureAllocated()
Ensure this memory has its size and layout calculated and its
memory allocated.
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.
Parameters:
size
- how much memory to allocate
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.
The returned pointer may not have meaning for
Structure.ByValue
structure representations.
fieldOffset
protected int fieldOffset(String name)
Returns the calculated offset of the given field.
Parameters:
name
- field to examine
Returns:
return offset of the given field
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.
Parameters:
name
- field to be read
Returns:
the new field value, after updating
Throws:
IllegalArgumentException
- if no field exists with the given name
getFieldValue
Object getFieldValue(Field field)
Obtain the value currently in the Java field. Does not read from
native memory.
Parameters:
field
- field to look up
Returns:
current field value (Java-side only)
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
readField
protected 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.
Parameters:
structField
- field to be read
Returns:
value of the requested field
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.
Parameters:
name
- which field to synch
Throws:
IllegalArgumentException
- if no field exists with the given name
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.
Parameters:
name
- field to write
value
- value to write
Throws:
IllegalArgumentException
- if no field exists with the given name
getFieldOrder
protected abstract List getFieldOrder()
Return this Structure's field names in their proper order. For
example,
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.
setFieldOrder
protected final void setFieldOrder(String[] fields)
Deprecated.
Force a compile-time error on the old method of field definition
Parameters:
fields
- ordered array of field names
protected void sortFields(List fields,
List names)
Sort the structure fields according to the given array of names.
Parameters:
fields
- list of fields to be sorted
names
- list of names representing the desired sort order
getFieldList
protected List getFieldList()
Look up all fields in this class and superclasses.
Returns:
ordered list of public
Field
available on
this
Structure
class.
getFields
protected List getFields(boolean force)
Parameters:
force
- set if results are required immediately
Returns:
null if not yet able to provide fields, and force is false.
Throws:
Error
- if force is true and field order data not yet specified
and can't be generated automatically.
calculateSize
protected 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.
force
- whether to force size calculation
Returns:
calculated size, or
CALCULATE_SIZE
if the size can not
yet be determined.
Throws:
IllegalStateException
- an array field is not initialized or the
size can not be determined while
force
is
true
.
IllegalArgumentException
- when an unsupported field type is
encountered
static int size(Class type)
Efficiently calculate the size of the given Structure subclass.
Parameters:
type
- Structure subclass to check
Returns:
native size of the given Structure subclass
static int size(Class type,
Structure value)
Efficiently calculate the size of the given Structure subclass.
Parameters:
type
- Structure subclass to check
value
- optional instance of the given class
Returns:
native size of the Structure subclass
Parameters:
force
- whether to force size calculation.
avoidFFIType
- set false in certain situations to avoid recursive
type lookup.
Returns:
calculated size, or
CALCULATE_SIZE
if there is not yet
enough information to perform the size calculation.
boolean isFirstElement)
Overridable in subclasses.
Calculate the appropriate alignment for a field of a given type within this struct.
Parameters:
type
- field type
value
- field value, if available
isFirstElement
- is this field the first element in the struct?
Returns:
the native byte alignment
toString
public String toString()
If
jna.dump_memory
is true, will include a native memory dump
of the Structure's backing memory.
Overrides:
toString
in class
Object
Returns:
String representation of this object.
Parameters:
debug
- If true, will include a native memory dump of the
Structure's backing memory.
Returns:
String representation of this 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.
array
- Structure[] object to populate
Returns:
array of Structure mapped onto the available memory
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.
size
- desired number of elements
Returns:
array of Structure (individual elements will be of the
appropriate type, as will the Structure[]).
dataEquals
public boolean dataEquals(Structure s)
Return whether the given Structure's native backing data is identical to
this one.
Parameters:
s
- Structure to compare
Returns:
equality result
public boolean dataEquals(Structure s,
boolean clear)
Return whether the given Structure's backing data is identical to
this one, optionally clearing and re-writing native memory before checking.
Parameters:
s
- Structure to compare
clear
- whether to clear native memory
Returns:
equality result
cacheTypeInfo
protected void cacheTypeInfo(Pointer p)
Cache native type information for use in native code.
Parameters:
p
- Native pointer to the type information
getFieldTypeInfo
Pointer getFieldTypeInfo(Structure.StructField f)
Override to supply native type information for the given field.
Parameters:
f
- internal field representation
Returns:
Native pointer to the corresponding type information
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);
For extremely large or complex structures where you only need to
access a small number of fields, you may see a significant performance
benefit by avoiding automatic structure reads and writes. If
auto-read and -write are disabled, it is up to you to ensure that the
Java fields of interest are synched before and after native function
calls via
readField(String)
and
writeField(String,Object)
.
This is typically most effective when a native call populates a large
structure and you only need a few fields out of it. After the native
call you can call
readField(String)
on only the fields of
interest.
auto
- whether to automatically synch with native memory.
setAutoRead
public void setAutoRead(boolean auto)
Set whether the structure is read from native memory prior to
a native function call.
Parameters:
auto
- whether to automatically synch from native memory.
getAutoRead
public boolean getAutoRead()
Returns whether the structure is read from native memory prior to
a native function call.
Returns:
whether automatic synch from native memory is enabled.
setAutoWrite
public void setAutoWrite(boolean auto)
Set whether the structure is written to native memory after a native
function call.
Parameters:
auto
- whether to automatically synch to native memory.
getAutoWrite
public boolean getAutoWrite()
Returns whether the structure is written to native memory after a native
function call.
Returns:
whether automatic synch to native memory is enabled.
public static Structure newInstance(Class type,
Pointer init)
throws IllegalArgumentException
Create a new Structure instance of the given type, initialized with
the given memory.
Parameters:
type
- desired Structure type
init
- initial memory
Returns:
the new instance
Throws:
IllegalArgumentException
- if the instantiation fails
newInstance
public static Structure newInstance(Class type)
throws IllegalArgumentException
Create a new Structure instance of the given type
Parameters:
type
- desired Structure type
Returns:
the new instance
Throws:
IllegalArgumentException
- if the instantiation fails
typeInfoField
Structure.StructField typeInfoField()
Keep track of the largest aggregate field of the union to use for
FFI type information.
Returns:
which field to use to obtain FFI type information
getNativeSize
protected int getNativeSize(Class nativeType)
Return the native size of the given Java type, from the perspective of
this Structure.
Parameters:
nativeType
- field type to examine
Returns:
native size (in bytes) of the requested field type
protected int getNativeSize(Class nativeType,
Object value)
Return the native size of the given Java type, from the perspective of
this Structure.
Parameters:
nativeType
- field type to examine
value
- instance of the field type
Returns:
native size (in bytes) of the requested field type
validate
static void validate(Class cls)
Indicate whether the given Structure class can be created by JNA.
Parameters:
cls
- Structure subclass to check
