|
JNA API> 3.2.7 | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectcom.sun.jna.Structure
public abstract class Structure
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.
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 | |
---|---|
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 |
---|
static final boolean isPPC
static final boolean isSPARC
public static final int ALIGN_DEFAULT
public static final int ALIGN_NONE
public static final int ALIGN_GNUC
public static final int ALIGN_MSVC
protected static final int CALCULATE_SIZE
Constructor Detail |
---|
protected Structure()
protected Structure(TypeMapper mapper)
protected Structure(Pointer p)
protected Structure(Pointer p, int alignment)
protected Structure(Pointer p, int alignment, TypeMapper mapper)
Method Detail |
---|
java.util.Map fields()
protected void setTypeMapper(TypeMapper mapper)
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 java.util.Set busy()
static java.util.Map reading()
public void read()
public java.lang.Object readField(java.lang.String name)
java.lang.IllegalArgumentException
- if no field exists with the given namejava.lang.Object getField(Structure.StructField structField)
void setField(Structure.StructField structField, java.lang.Object value)
static Structure updateStructureByReference(java.lang.Class type, Structure s, Pointer address)
type
- Structure subclasss
- Original Structure objectaddress
- the native struct *
Structure.ByReference
objectjava.lang.Object readField(Structure.StructField structField)
public void write()
public void writeField(java.lang.String name)
java.lang.IllegalArgumentException
- if no field exists with the given namepublic void writeField(java.lang.String name, java.lang.Object value)
java.lang.IllegalArgumentException
- if no field exists with the given namevoid writeField(Structure.StructField structField)
protected java.util.List getFieldOrder()
protected void setFieldOrder(java.lang.String[] fields)
Class.getFields()
is not predictable.
protected void sortFields(java.util.List fields, java.util.List names)
protected java.util.List getFields(boolean force)
int calculateSize(boolean force)
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.
java.lang.IllegalStateException
- an array field is not initialized
java.lang.IllegalArgumentException
- when an unsupported field type is
encounteredint calculateAlignedSize(int calculatedSize)
protected int getStructAlignment()
protected int getNativeAlignment(java.lang.Class type, java.lang.Object value, boolean isFirstElement)
public java.lang.String toString()
toString
in class java.lang.Object
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(java.lang.Object o)
equals
in class java.lang.Object
public int hashCode()
equals(java.lang.Object)
depends on the native address, use that
as the hash code.
hashCode
in class java.lang.Object
protected void cacheTypeInfo(Pointer p)
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()
static Pointer getTypeInfo(java.lang.Object obj)
public static Structure newInstance(java.lang.Class type) throws java.lang.IllegalArgumentException
type
-
java.lang.IllegalArgumentException
- if the instantiation failspublic static void autoRead(Structure[] ss)
public void autoRead()
public static void autoWrite(Structure[] ss)
public void autoWrite()
|
JNA API> 3.2.7 | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |