com.sun.jna
Class Structure

java.lang.Object
  com.sun.jna.Structure

Direct Known Subclasses:

CallbackReference.AttachOptions, Carbon.EventHotKeyID, Carbon.EventTypeSpec, DBT.DEV_BROADCAST_DEVICEINTERFACE, DBT.DEV_BROADCAST_DEVNODE, DBT.DEV_BROADCAST_HANDLE, DBT.DEV_BROADCAST_HDR, DBT.DEV_BROADCAST_NET, DBT.DEV_BROADCAST_OEM, DBT.DEV_BROADCAST_PORT, DBT.DEV_BROADCAST_VOLUME, DsGetDC.DOMAIN_CONTROLLER_INFO, DsGetDC.DS_DOMAIN_TRUSTS, DsGetDC.PDOMAIN_CONTROLLER_INFO, Guid.GUID, LMAccess.GROUP_INFO_0, LMAccess.GROUP_INFO_1, LMAccess.GROUP_INFO_2, LMAccess.GROUP_INFO_3, LMAccess.GROUP_USERS_INFO_0, LMAccess.LOCALGROUP_INFO_0, LMAccess.LOCALGROUP_INFO_1, LMAccess.LOCALGROUP_USERS_INFO_0, LMAccess.USER_INFO_0, LMAccess.USER_INFO_1, LMAccess.USER_INFO_23, MacFileUtils.FileManager.FSRef, NTSecApi.LSA_FOREST_TRUST_BINARY_DATA, NTSecApi.LSA_FOREST_TRUST_DOMAIN_INFO, NTSecApi.LSA_FOREST_TRUST_INFORMATION, NTSecApi.LSA_FOREST_TRUST_RECORD, NTSecApi.LSA_UNICODE_STRING, NTSecApi.PLSA_FOREST_TRUST_INFORMATION, NTSecApi.PLSA_FOREST_TRUST_RECORD, OaIdl.ARRAYDESC, OaIdl.CALLCONV, OaIdl.CURRENCY._CURRENCY, OaIdl.DATE, OaIdl.DECIMAL, OaIdl.DECIMAL._DECIMAL1._DECIMAL1_DECIMAL, OaIdl.DECIMAL._DECIMAL2._DECIMAL2_DECIMAL, OaIdl.ELEMDESC, OaIdl.EXCEPINFO, OaIdl.FUNCDESC, OaIdl.FUNCKIND, OaIdl.IDLDESC, OaIdl.INVOKEKIND, OaIdl.PARAMDESC, OaIdl.PARAMDESCEX, OaIdl.SAFEARRAY, OaIdl.SAFEARRAYBOUND, OaIdl.TLIBATTR, OaIdl.TYPEATTR, OaIdl.TYPEDESC, OaIdl.VARDESC, OaIdl.VARKIND, OleAuto.DISPPARAMS, SetupApi.SP_DEVICE_INTERFACE_DATA, SetupApi.SP_DEVINFO_DATA, ShellAPI.APPBARDATA, ShellAPI.SHFILEOPSTRUCT, Sspi.PSecHandle, Sspi.PSecPkgInfo, Sspi.SecBuffer, Sspi.SecBufferDesc, Sspi.SecHandle, Sspi.SecPkgInfo, Sspi.SECURITY_INTEGER, Structure.FFIType, Tlhelp32.PROCESSENTRY32, Union, Variant.VARIANT._VARIANT, Variant.VARIANT._VARIANT.__VARIANT.BRECORD, Variant.VariantArg, VerRsrc.VS_FIXEDFILEINFO, Wdm.KEY_BASIC_INFORMATION, WinBase.FILETIME, WinBase.MEMORYSTATUSEX, WinBase.OVERLAPPED, WinBase.PROCESS_INFORMATION, WinBase.SECURITY_ATTRIBUTES, WinBase.STARTUPINFO, WinBase.SYSTEM_INFO, WinBase.SYSTEM_INFO.PI, WinBase.SYSTEMTIME, WinCrypt.CRYPTPROTECT_PROMPTSTRUCT, WinCrypt.DATA_BLOB, WinDef.POINT, WinDef.RECT, WinGDI.BITMAPINFO, WinGDI.BITMAPINFOHEADER, WinGDI.RGBQUAD, WinGDI.RGNDATA, WinGDI.RGNDATAHEADER, Winioctl.STORAGE_DEVICE_NUMBER, WinNT.ACEStructure, WinNT.ACL, WinNT.CACHE_DESCRIPTOR, WinNT.EVENTLOGRECORD, WinNT.FILE_NOTIFY_INFORMATION, WinNT.LARGE_INTEGER, WinNT.LARGE_INTEGER.LowHigh, WinNT.LUID, WinNT.LUID_AND_ATTRIBUTES, WinNT.OSVERSIONINFO, WinNT.OSVERSIONINFOEX, WinNT.PSID, WinNT.SECURITY_DESCRIPTOR, WinNT.SECURITY_DESCRIPTOR_RELATIVE, WinNT.SID_AND_ATTRIBUTES, WinNT.SYSTEM_LOGICAL_PROCESSOR_INFORMATION, WinNT.SYSTEM_LOGICAL_PROCESSOR_INFORMATION.AnonymousStructNumaNode, WinNT.SYSTEM_LOGICAL_PROCESSOR_INFORMATION.AnonymousStructProcessorCore, WinNT.TOKEN_GROUPS, WinNT.TOKEN_OWNER, WinNT.TOKEN_PRIVILEGES, WinNT.TOKEN_USER, Winspool.PRINTER_INFO_1, Winspool.PRINTER_INFO_4, Winsvc.SERVICE_STATUS, Winsvc.SERVICE_STATUS_PROCESS, WinUser.BLENDFUNCTION, WinUser.FLASHWINFO, WinUser.GUITHREADINFO, WinUser.HARDWAREINPUT, WinUser.INPUT, WinUser.KBDLLHOOKSTRUCT, WinUser.KEYBDINPUT, WinUser.LASTINPUTINFO, WinUser.MOUSEINPUT, WinUser.MSG, WinUser.POINT, WinUser.SIZE, WinUser.WINDOWINFO, WinUser.WNDCLASSEX, X11.XAnyEvent, X11.XButtonEvent, X11.XCirculateEvent, X11.XCirculateRequestEvent, X11.XClientMessageEvent, X11.XColormapEvent, X11.XConfigureEvent, X11.XConfigureRequestEvent, X11.XCreateWindowEvent, X11.XCrossingEvent, X11.XDestroyWindowEvent, X11.XDeviceByReference, X11.XErrorEvent, X11.XExposeEvent, X11.XFocusChangeEvent, X11.XGCValues, X11.XGraphicsExposeEvent, X11.XGravityEvent, X11.XInputClassInfoByReference, X11.XKeyboardControlRef, X11.XKeyboardStateRef, X11.XKeyEvent, X11.XKeymapEvent, X11.XMapEvent, X11.XMappingEvent, X11.XMapRequestEvent, X11.XModifierKeymapRef, X11.XMotionEvent, X11.XNoExposeEvent, X11.XPoint, X11.XPropertyEvent, X11.XRectangle, X11.Xrender.XRenderDirectFormat, X11.Xrender.XRenderPictFormat, X11.XReparentEvent, X11.XResizeRequestEvent, X11.XSelectionClearEvent, X11.XSelectionEvent, X11.XSelectionRequestEvent, X11.XSetWindowAttributes, X11.XSizeHints, X11.XSizeHints.Aspect, X11.XTextProperty, X11.XUnmapEvent, X11.XVisibilityEvent, X11.XVisualInfo, X11.XWindowAttributes, X11.XWMHints

public abstract class Structure
extends Object

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. 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.

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 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.

NOTE: In general, instances of this class are not synchronized.

Author:

Todd Fast, todd.fast@sun.com, twall@users.sf.net

ALIGN_DEFAULT

public static final int ALIGN_DEFAULT

Use the platform default alignment.

See Also:

Constant Field Values

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

ALIGN_MSVC

public static final int ALIGN_MSVC

validated for w32/msvc; align on field size

See Also:

Constant Field Values

CALCULATE_SIZE

protected static final int CALCULATE_SIZE

Align to an 8-byte boundary.

See Also:

Constant Field Values

layoutInfo

static final Map layoutInfo

fieldOrder

static final Map fieldOrder

Structure

protected Structure()

Structure

protected Structure(TypeMapper mapper)

Structure

protected Structure(int alignType)

Structure

protected Structure(int alignType,
                    TypeMapper mapper)

Structure

protected Structure(Pointer p)

Create a structure cast onto pre-allocated memory.

Structure

protected Structure(Pointer p,
                    int alignType)

Structure

protected Structure(Pointer p,
                    int alignType,
                    TypeMapper mapper)

fields

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.

getTypeMapper

TypeMapper getTypeMapper()

Return the type mapper in effect for this Structure.

setStringEncoding

protected void setStringEncoding(String encoding)

Set the desired encoding to use when writing String fields to native memory.

getStringEncoding

protected String getStringEncoding()

Encoding to use to convert String to native const char*. Defaults to Native.getDefaultStringEncoding().

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.

autoAllocate

protected Memory autoAllocate(int size)

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.

useMemory

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.

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.

size

public int size()

Returns the size in memory occupied by this Structure.

clear

public void clear()

Clears the native memory associated with this Structure.

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.

busy

static Set busy()

reading

static Map reading()

conditionalAutoRead

void conditionalAutoRead()

Performs auto-read only if uninitialized.

read

public void read()

Reads the fields of the struct from native memory

fieldOffset

protected int fieldOffset(String name)

Returns the calculated 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.

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 memory.

setFieldValue

void setFieldValue(Field field,
                   Object value)

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.

write

public void write()

Writes the fields of the struct to native memory

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.

Throws:

IllegalArgumentException - if no field exists with the given name

writeField

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.

Throws:

IllegalArgumentException - if no field exists with the given name

writeField

protected void writeField(Structure.StructField structField)

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. Use the required method getFieldOrder() instead to indicate the order of fields in this structure.

Force a compile-time error on the old method of field definition

sortFields

protected void sortFields(List fields,
                          List names)

Sort the structure fields according to the given array of names.

getFieldList

protected List getFieldList()

Look up all fields in this class and superclasses.

getFields

protected List getFields(boolean force)

Returns all field names (sorted) provided so far by getFieldOrder()

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.

size

static int size(Class type)

Efficiently calculate the size of the given Structure subclass.

size

static int size(Class type,
                Structure value)

Efficiently calculate the size of the given Structure subclass.

calculateSize

int calculateSize(boolean force,
                  boolean avoidFFIType)

getStructAlignment

protected int getStructAlignment()

getNativeAlignment

protected int getNativeAlignment(Class type,
                                 Object value,
                                 boolean isFirstElement)

Overridable in subclasses.

toString

public String toString()

Overrides:

toString in class Object

toString

public String toString(boolean debug)

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.

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.

equals

public boolean equals(Object o)

This structure is equal to another based on the same data type and memory contents.

Overrides:

equals in class Object

hashCode

public int hashCode()

Since equals(java.lang.Object) depends on the contents of memory, use that as the basis for the hash code.

Overrides:

hashCode in class Object

cacheTypeInfo

protected void cacheTypeInfo(Pointer p)

Cache native type information for use in native code.

getFieldTypeInfo

Pointer getFieldTypeInfo(Structure.StructField f)

Override to supply native type information for the given field.

getTypeInfo

Pointer getTypeInfo()

Obtain native type information for this structure.

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.

setAutoRead

public void setAutoRead(boolean auto)

Set whether the structure is read from native memory prior to a native function call.

getAutoRead

public boolean getAutoRead()

Returns whether the structure is read from native memory prior to a native function call.

setAutoWrite

public void setAutoWrite(boolean auto)

Set whether the structure is written to native memory after a native function call.

getAutoWrite

public boolean getAutoWrite()

Returns whether the structure is written to native memory after a native function call.

getTypeInfo

static Pointer getTypeInfo(Object obj)

Exposed for testing purposes only.

newInstance

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.

autoRead

public static void autoRead(Structure[] ss)

autoRead

public void autoRead()

autoWrite

public static void autoWrite(Structure[] ss)

autoWrite

public void autoWrite()

getNativeSize

protected int getNativeSize(Class nativeType)

Return the native size of the given Java type, from the perspective of this Structure.

getNativeSize

protected int getNativeSize(Class nativeType,
                            Object value)

Return the native size of the given Java type, from the perspective of this Structure.

validate

static void validate(Class cls)

Indicate whether the given Structure class can be created by JNA.