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 {@link ByReference} and {@link ByValue} may be usedto 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 {@link Native#getStructureAlignment} and {@link Native#getTypeMapper}. Alternatively you can explicitly provide alignment, field order, or type mapping by calling the respective Structure functions in your subclass's constructor.
Structure fields corresponding to native struct fields
must be public. If your structure is to have no fields of its own, it must be declared abstract.
You
must define {@link #getFieldOrder} to return a List offield 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 {@link #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 {@link #getFieldOrder} is now required toensure 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 {@link #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 {@link #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.
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 ( {@link com.sun.jna.win32.W32APITypeMapper example here)} if you prefer to use String in place of {@link WString} ifyour native code predominantly uses
wchar_t *
.
NOTE: In general, instances of this class are
not synchronized.
@author Todd Fast, todd.fast@sun.com
@author twall@users.sf.net