Package 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, Ddeml.CONVCONTEXT, Ddeml.CONVINFO, Ddeml.DDEML_MSG_HOOK_DATA, Ddeml.HSZPAIR, Ddeml.MONCBSTRUCT, Ddeml.MONCONVSTRUCT, Ddeml.MONERRSTRUCT, Ddeml.MONHSZSTRUCT, Ddeml.MONLINKSTRUCT, Ddeml.MONMSGSTRUCT, DispatchListener, DispatchVTable, DsGetDC.DOMAIN_CONTROLLER_INFO, DsGetDC.DS_DOMAIN_TRUSTS, DsGetDC.PDOMAIN_CONTROLLER_INFO, Guid.GUID, IPHlpAPI.FIXED_INFO, IPHlpAPI.IP_ADDR_STRING, IPHlpAPI.IP_ADDRESS_STRING, IPHlpAPI.MIB_IF_ROW2, IPHlpAPI.MIB_IFROW, IPHlpAPI.MIB_TCP6ROW_OWNER_PID, IPHlpAPI.MIB_TCP6TABLE_OWNER_PID, IPHlpAPI.MIB_TCPROW_OWNER_PID, IPHlpAPI.MIB_TCPSTATS, IPHlpAPI.MIB_TCPTABLE_OWNER_PID, IPHlpAPI.MIB_UDP6ROW_OWNER_PID, IPHlpAPI.MIB_UDP6TABLE_OWNER_PID, IPHlpAPI.MIB_UDPROW_OWNER_PID, IPHlpAPI.MIB_UDPSTATS, IPHlpAPI.MIB_UDPTABLE_OWNER_PID, Kstat2.Kstat2NV, Kstat2.Kstat2NV.UNION.IntegersArr, Kstat2.Kstat2NV.UNION.StringsArr, LibC.Statvfs, LibC.Sysinfo, LibKstat.Kstat, LibKstat.KstatCtl, LibKstat.KstatIntr, LibKstat.KstatIO, LibKstat.KstatNamed, LibKstat.KstatNamed.UNION.STR, LibKstat.KstatTimer, 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, LMShare.SHARE_INFO_2, LMShare.SHARE_INFO_502, LowLevelMonitorConfigurationAPI.MC_TIMING_REPORT, MacFileUtils.FileManager.FSRef, Netapi32.SESSION_INFO_10, Ntifs.GenericReparseBuffer, Ntifs.MountPointReparseBuffer, Ntifs.REPARSE_DATA_BUFFER, Ntifs.SymbolicLinkReparseBuffer, 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.DESCKIND, OaIdl.ELEMDESC, OaIdl.ElemDescArg, OaIdl.EXCEPINFO, OaIdl.FUNCDESC, OaIdl.FUNCKIND, OaIdl.IDLDESC, OaIdl.INVOKEKIND, OaIdl.LIBFLAGS, OaIdl.PARAMDESC, OaIdl.PARAMDESCEX, OaIdl.SAFEARRAY, OaIdl.SAFEARRAYBOUND, OaIdl.SAFEARRAYByReference, OaIdl.ScodeArg, OaIdl.SYSKIND, OaIdl.TLIBATTR, OaIdl.TYPEATTR, OaIdl.TYPEDESC, OaIdl.TYPEKIND, OaIdl.VARDESC, OaIdl.VARKIND, OleAuto.DISPPARAMS, Pdh.PDH_COUNTER_PATH_ELEMENTS, Pdh.PDH_RAW_COUNTER, Pdh.PDH_TIME_INFO, Perfstat.perfstat_cpu_t, Perfstat.perfstat_cpu_total_t, Perfstat.perfstat_disk_t, Perfstat.perfstat_id_t, Perfstat.perfstat_memory_total_t, Perfstat.perfstat_netinterface_t, Perfstat.perfstat_partition_config_t, Perfstat.perfstat_process_t, Perfstat.perfstat_protocol_t, Perfstat.perfstat_protocol_t.AnonymousStructICMP, Perfstat.perfstat_protocol_t.AnonymousStructICMPv6, Perfstat.perfstat_protocol_t.AnonymousStructIP, Perfstat.perfstat_protocol_t.AnonymousStructIPv6, Perfstat.perfstat_protocol_t.AnonymousStructNFS, Perfstat.perfstat_protocol_t.AnonymousStructNFSclient, Perfstat.perfstat_protocol_t.AnonymousStructNFSserver, Perfstat.perfstat_protocol_t.AnonymousStructNFSv2, Perfstat.perfstat_protocol_t.AnonymousStructNFSv2client, Perfstat.perfstat_protocol_t.AnonymousStructNFSv2server, Perfstat.perfstat_protocol_t.AnonymousStructNFSv3, Perfstat.perfstat_protocol_t.AnonymousStructNFSv3client, Perfstat.perfstat_protocol_t.AnonymousStructNFSv3server, Perfstat.perfstat_protocol_t.AnonymousStructNFSv4, Perfstat.perfstat_protocol_t.AnonymousStructNFSv4client, Perfstat.perfstat_protocol_t.AnonymousStructNFSv4server, Perfstat.perfstat_protocol_t.AnonymousStructRPC, Perfstat.perfstat_protocol_t.AnonymousStructRPCclient, Perfstat.perfstat_protocol_t.AnonymousStructRPCclientdgram, Perfstat.perfstat_protocol_t.AnonymousStructRPCclientstream, Perfstat.perfstat_protocol_t.AnonymousStructRPCserver, Perfstat.perfstat_protocol_t.AnonymousStructRPCserverdgram, Perfstat.perfstat_protocol_t.AnonymousStructRPCserverstream, Perfstat.perfstat_protocol_t.AnonymousStructTCP, Perfstat.perfstat_protocol_t.AnonymousStructUDP, Perfstat.perfstat_value_t, PhysicalMonitorEnumerationAPI.PHYSICAL_MONITOR, Psapi.MODULEINFO, Psapi.PERFORMANCE_INFORMATION, Psapi.PSAPI_WORKING_SET_EX_INFORMATION, Resource.Rlimit, SetupApi.SP_DEVICE_INTERFACE_DATA, SetupApi.SP_DEVINFO_DATA, ShellAPI.APPBARDATA, ShellAPI.SHELLEXECUTEINFO, ShellAPI.SHFILEOPSTRUCT, ShTypes.STRRET, Sspi.PSecHandle, Sspi.PSecPkgInfo, Sspi.SEC_WINNT_AUTH_IDENTITY, Sspi.SecBuffer, Sspi.SecBufferDesc, Sspi.SecHandle, Sspi.SecPkgContext_Flags, Sspi.SecPkgContext_KeyInfo, Sspi.SecPkgContext_Lifespan, Sspi.SecPkgContext_NegotiationInfo, Sspi.SecPkgContext_PackageInfo, Sspi.SecPkgContext_SessionKey, Sspi.SecPkgContext_Sizes, Sspi.SecPkgCredentials_Names, Sspi.SecPkgInfo, Sspi.SECURITY_INTEGER, Structure.FFIType, SystemB.Group, SystemB.HostCpuLoadInfo, SystemB.HostLoadInfo, SystemB.IFdata, SystemB.IFdata64, SystemB.IFmsgHdr, SystemB.IFmsgHdr2, SystemB.Passwd, SystemB.ProcBsdInfo, SystemB.ProcTaskAllInfo, SystemB.ProcTaskInfo, SystemB.RUsageInfoV2, SystemB.Statfs, SystemB.Timeval, SystemB.Timezone, SystemB.VMMeter, SystemB.VMStatistics, SystemB.VMStatistics64, SystemB.VnodeInfoPath, SystemB.VnodePathInfo, SystemB.XswUsage, Tlhelp32.MODULEENTRY32W, Tlhelp32.PROCESSENTRY32, Tlhelp32.THREADENTRY32, Union, UnknownListener, UnknownVTable, Variant.VARIANT._VARIANT, Variant.VARIANT._VARIANT.__VARIANT.BRECORD, Variant.VariantArg, VerRsrc.VS_FIXEDFILEINFO, Wdm.KEY_BASIC_INFORMATION, WinBase.COMMTIMEOUTS, WinBase.DCB, WinBase.FILE_ATTRIBUTE_TAG_INFO, WinBase.FILE_BASIC_INFO, WinBase.FILE_COMPRESSION_INFO, WinBase.FILE_DISPOSITION_INFO, WinBase.FILE_ID_INFO, WinBase.FILE_ID_INFO.FILE_ID_128, WinBase.FILE_STANDARD_INFO, WinBase.FILETIME, WinBase.FOREIGN_THREAD_START_ROUTINE, WinBase.MEMORYSTATUSEX, WinBase.OVERLAPPED, WinBase.PROCESS_INFORMATION, WinBase.SECURITY_ATTRIBUTES, WinBase.STARTUPINFO, WinBase.SYSTEM_INFO, WinBase.SYSTEM_INFO.PI, WinBase.SYSTEMTIME, WinBase.TIME_ZONE_INFORMATION, WinBase.WIN32_FIND_DATA, Wincon.CONSOLE_SCREEN_BUFFER_INFO, Wincon.COORD, Wincon.INPUT_RECORD, Wincon.KEY_EVENT_RECORD, Wincon.MOUSE_EVENT_RECORD, Wincon.SMALL_RECT, Wincon.WINDOW_BUFFER_SIZE_RECORD, WinCrypt.CERT_CHAIN_CONTEXT, WinCrypt.CERT_CHAIN_ELEMENT, WinCrypt.CERT_CHAIN_PARA, WinCrypt.CERT_CHAIN_POLICY_PARA, WinCrypt.CERT_CHAIN_POLICY_STATUS, WinCrypt.CERT_CONTEXT, WinCrypt.CERT_EXTENSION, WinCrypt.CERT_EXTENSIONS, WinCrypt.CERT_INFO, WinCrypt.CERT_PUBLIC_KEY_INFO, WinCrypt.CERT_REVOCATION_CRL_INFO, WinCrypt.CERT_REVOCATION_INFO, WinCrypt.CERT_SIMPLE_CHAIN, WinCrypt.CERT_STRONG_SIGN_PARA, WinCrypt.CERT_STRONG_SIGN_SERIALIZED_INFO, WinCrypt.CERT_TRUST_LIST_INFO, WinCrypt.CERT_TRUST_STATUS, WinCrypt.CERT_USAGE_MATCH, WinCrypt.CRL_CONTEXT, WinCrypt.CRL_ENTRY, WinCrypt.CRL_INFO, WinCrypt.CRYPT_ALGORITHM_IDENTIFIER, WinCrypt.CRYPT_ATTRIBUTE, WinCrypt.CRYPT_BIT_BLOB, WinCrypt.CRYPT_KEY_PROV_INFO, WinCrypt.CRYPT_KEY_PROV_PARAM, WinCrypt.CRYPT_SIGN_MESSAGE_PARA, WinCrypt.CRYPT_VERIFY_MESSAGE_PARA, WinCrypt.CRYPTPROTECT_PROMPTSTRUCT, WinCrypt.CTL_CONTEXT, WinCrypt.CTL_ENTRY, WinCrypt.CTL_INFO, WinCrypt.CTL_USAGE, WinCrypt.DATA_BLOB, WinDef.POINT, WinDef.RECT, Winevt.EVT_RPC_LOGIN, Winevt.EVT_VARIANT, WinGDI.BITMAP, WinGDI.BITMAPINFO, WinGDI.BITMAPINFOHEADER, WinGDI.DIBSECTION, WinGDI.ICONINFO, WinGDI.PIXELFORMATDESCRIPTOR, WinGDI.RGBQUAD, WinGDI.RGNDATA, WinGDI.RGNDATAHEADER, Wininet.INTERNET_CACHE_ENTRY_INFO, Winioctl.STORAGE_DEVICE_NUMBER, Winnetwk.NETRESOURCE, Winnetwk.REMOTE_NAME_INFO, Winnetwk.UNIVERSAL_NAME_INFO, WinNT.ACE_HEADER, WinNT.ACL, WinNT.BATTERY_REPORTING_SCALE, WinNT.CACHE_DESCRIPTOR, WinNT.EVENTLOGRECORD, WinNT.FILE_NOTIFY_INFORMATION, WinNT.GENERIC_MAPPING, WinNT.GROUP_AFFINITY, WinNT.IO_COUNTERS, WinNT.LARGE_INTEGER, WinNT.LARGE_INTEGER.LowHigh, WinNT.LUID, WinNT.LUID_AND_ATTRIBUTES, WinNT.MEMORY_BASIC_INFORMATION, WinNT.OSVERSIONINFO, WinNT.OSVERSIONINFOEX, WinNT.POWER_ACTION_POLICY, WinNT.PRIVILEGE_SET, WinNT.PROCESSOR_GROUP_INFO, WinNT.PROCESSOR_POWER_INFORMATION, WinNT.PSID, WinNT.SECURITY_DESCRIPTOR, WinNT.SECURITY_DESCRIPTOR_RELATIVE, WinNT.SECURITY_QUALITY_OF_SERVICE, WinNT.SID_AND_ATTRIBUTES, WinNT.SYSTEM_BATTERY_STATE, WinNT.SYSTEM_LOGICAL_PROCESSOR_INFORMATION, WinNT.SYSTEM_LOGICAL_PROCESSOR_INFORMATION_EX, WinNT.SYSTEM_LOGICAL_PROCESSOR_INFORMATION.AnonymousStructNumaNode, WinNT.SYSTEM_LOGICAL_PROCESSOR_INFORMATION.AnonymousStructProcessorCore, WinNT.SYSTEM_POWER_CAPABILITIES, WinNT.SYSTEM_POWER_INFORMATION, WinNT.SYSTEM_POWER_LEVEL, WinNT.SYSTEM_POWER_POLICY, WinNT.TOKEN_ELEVATION, WinNT.TOKEN_GROUPS, WinNT.TOKEN_OWNER, WinNT.TOKEN_PRIMARY_GROUP, WinNT.TOKEN_PRIVILEGES, WinNT.TOKEN_USER, WinPerf.PERF_COUNTER_BLOCK, WinPerf.PERF_COUNTER_DEFINITION, WinPerf.PERF_DATA_BLOCK, WinPerf.PERF_INSTANCE_DEFINITION, WinPerf.PERF_OBJECT_TYPE, WinRas.RAS_STATS, WinRas.RASCONN, WinRas.RASCONNSTATUS, WinRas.RASCREDENTIALS, WinRas.RASDEVSPECIFICINFO, WinRas.RASDIALEXTENSIONS, WinRas.RASDIALPARAMS, WinRas.RASEAPINFO, WinRas.RASENTRY, WinRas.RASIPADDR, WinRas.RASIPV4ADDR, WinRas.RASIPV6ADDR, WinRas.RASPPPIP, WinRas.RASTUNNELENDPOINT, Winspool.JOB_INFO_1, Winspool.LPPRINTER_DEFAULTS, Winspool.NOTIFY_DATA_DATA, Winspool.PRINTER_INFO_1, Winspool.PRINTER_INFO_2, Winspool.PRINTER_INFO_4, Winspool.PRINTER_NOTIFY_INFO, Winspool.PRINTER_NOTIFY_INFO_DATA, Winspool.PRINTER_NOTIFY_OPTIONS, Winspool.PRINTER_NOTIFY_OPTIONS_TYPE, Winsvc.ChangeServiceConfig2Info, Winsvc.ENUM_SERVICE_STATUS, Winsvc.ENUM_SERVICE_STATUS_PROCESS, Winsvc.SC_ACTION, Winsvc.SERVICE_STATUS, Winsvc.SERVICE_STATUS_PROCESS, Winsvc.SERVICE_TABLE_ENTRY, WinUser.BLENDFUNCTION, WinUser.COPYDATASTRUCT, WinUser.CWPSTRUCT, WinUser.FLASHWINFO, WinUser.GUITHREADINFO, WinUser.HARDWAREINPUT, WinUser.INPUT, WinUser.KBDLLHOOKSTRUCT, WinUser.KEYBDINPUT, WinUser.LASTINPUTINFO, WinUser.MONITORINFO, WinUser.MONITORINFOEX, WinUser.MOUSEINPUT, WinUser.MSG, WinUser.MSLLHOOKSTRUCT, WinUser.RAWINPUTDEVICELIST, WinUser.SIZE, WinUser.WINDOWINFO, WinUser.WINDOWPLACEMENT, WinUser.WNDCLASSEX, Wtsapi32.WTS_CLIENT_ADDRESS, Wtsapi32.WTS_PROCESS_INFO_EX, Wtsapi32.WTS_SESSION_INFO, Wtsapi32.WTSINFO, 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.XGenericEvent, X11.XGenericEventCookie, 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 annotate the class with Structure.FieldOrder or implement getFieldOrder(), whichever you choose it must contain the field names (Strings) indicating the proper order of the fields. If you chose to implement getFieldOrder() notice that 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: 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 *.

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

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

  • Field Details

  • Constructor Details

    • 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)

  • Method Details

    • fields

      Map<String,Structure.StructField> 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.
      Returns:
      Map of field names to field representations.

    • getTypeMapper

      TypeMapper getTypeMapper()
      Returns:
      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.
      Parameters:
      encoding - desired encoding

    • getStringEncoding

      protected String getStringEncoding()
      Encoding to use to convert String to native const char*. Defaults to Native.getDefaultStringEncoding().
      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.
      Parameters:
      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.

    • 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.
      Parameters:
      m - Base memory to use to back this structure.
      offset - offset into provided memory where structure mapping should start.

    • useMemory

      void useMemory(Pointer m, int offset, 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

    • size

      public int size()
      Returns the size in memory occupied by this Structure.
      Returns:
      Native size of this structure, in bytes.

    • 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. The returned pointer may not have meaning for Structure.ByValue structure representations.
      Returns:
      Native pointer representation of this structure.

    • busy

      static Set<Structure> busy()

    • reading

      static Map<Pointer,Structure> 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.
      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)

    • setFieldValue

      void setFieldValue(Field field, Object value)
      Parameters:
      field - field to set
      value - value to set

    • updateStructureByReference

      static <T extends Structure> T updateStructureByReference(Class<T> type, T 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

    • 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.
      Parameters:
      name - which field to synch
      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.
      Parameters:
      name - field to write
      value - value to write
      Throws:
      IllegalArgumentException - if no field exists with the given name

    • writeField

      protected void writeField(Structure.StructField structField)
      Parameters:
      structField - internal field representation to synch to native memory

    • getFieldOrder

      protected List<String> getFieldOrder()
      Returns this Structure's field names in their proper order.
      When defining a new Structure you shouldn't override this method, but use Structure.FieldOrder annotation to define your field order(this also works with inheritance)
      If you want to do something non-standard you can override the method and define it as followed 
      
 protected List getFieldOrder() {
     return Arrays.asList(...);
 }
      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 LinkedList(super.getFieldOrder());
     fields.addAll(Arrays.asList(...));
     return fields;
 }
      Field order must be explicitly indicated, since the field order as returned by Class.getFields() is not guaranteed to be predictable.
      Returns:
      ordered list of field names

    • sortFields

      protected void sortFields(List<Field> fields, List<String> 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<Field> getFieldList()
      Look up all fields in this class and superclasses.
      Returns:
      ordered list of public Field available on this Structure class.

    • createFieldsOrder

      public static List<String> createFieldsOrder(List<String> baseFields, String... extraFields)

    • createFieldsOrder

      public static List<String> createFieldsOrder(List<String> baseFields, List<String> extraFields)

    • createFieldsOrder

      public static List<String> createFieldsOrder(String field)
      Parameters:
      field - The (single) field name
      Returns:

    • createFieldsOrder

      public static List<String> createFieldsOrder(String... fields)
      Parameters:
      fields - The structure field names in correct order
      Returns:
      An un-modifiable list of the fields

    • getFields

      protected List<Field> 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.

    • 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.
      Parameters:
      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

    • size

      static int size(Class<? extends Structure> type)
      Efficiently calculate the size of the given Structure subclass.
      Parameters:
      type - Structure subclass to check
      Returns:
      native size of the given Structure subclass

    • size

      static <T extends Structure> int size(Class<T> type, T 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

    • calculateSize

      int calculateSize(boolean force, boolean avoidFFIType)
      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.

    • getStructAlignment

      protected int getStructAlignment()
      Returns:
      current alignment setting for this structure

    • getNativeAlignment

      protected int getNativeAlignment(Class<?> type, Object value, 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.

    • toString

      public String toString(boolean debug)
      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.
      Parameters:
      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.
      Parameters:
      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

    • dataEquals

      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

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object
      Returns:
      whether the given structure's type and pointer match.

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object
      Returns:
      hash code for this structure's pointer.

    • cacheTypeInfo

      protected void cacheTypeInfo(Pointer p)
      Cache native type information for use in native code.
      Parameters:
      p - Native pointer to the type information

    • getFieldTypeInfo

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

    • getTypeInfo

      Pointer getTypeInfo()
      Returns:
      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.
      Parameters:
      auto - whether to automatically synch with native memory.

    • setAutoRead

      public void setAutoRead(boolean auto)
      Set whether the structure is read from native memory after 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 after 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 prior to 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 prior to a native function call.
      Returns:
      whether automatic synch to native memory is enabled.

    • getTypeInfo

      static Structure.FFIType getTypeInfo(Object obj)
      Exposed for testing purposes only.
      Parameters:
      obj - object to query
      Returns:
      native pointer to type information

    • newInstance

      public static <T extends Structure> T newInstance(Class<T> 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 <T extends Structure> T newInstance(Class<T> 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

    • 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.
      Parameters:
      nativeType - field type to examine
      Returns:
      native size (in bytes) of the requested field type

    • getNativeSize

      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<? extends Structure> cls)
      Indicate whether the given Structure class can be created by JNA.
      Parameters:
      cls - Structure subclass to check