Class Union

java.lang.Object
com.sun.jna.Structure
com.sun.jna.Union
Direct Known Subclasses:
Kstat2.Kstat2NV.UNION, LibKstat.KstatNamed.UNION, Ntifs.REPARSE_DATA_BUFFER.REPARSE_UNION, NTSecApi.LSA_FOREST_TRUST_RECORD.UNION, OaIdl.BINDPTR, OaIdl.CURRENCY, OaIdl.DECIMAL._DECIMAL1, OaIdl.DECIMAL._DECIMAL2, OaIdl.ELEMDESC._ELEMDESC, OaIdl.TYPEDESC._TYPEDESC, OaIdl.VARDESC._VARDESC, Perfstat.perfstat_protocol_t.AnonymousUnionPayload, ShTypes.STRRET.UNION, Variant.VARIANT, Variant.VARIANT._VARIANT.__VARIANT, WinBase.SYSTEM_INFO.UNION, Wincon.INPUT_RECORD.Event, WinCrypt.CERT_STRONG_SIGN_PARA.DUMMYUNION, Winevt.EVT_VARIANT.field1_union, Wininet.INTERNET_CACHE_ENTRY_INFO.UNION, WinNT.LARGE_INTEGER.UNION, WinNT.SYSTEM_LOGICAL_PROCESSOR_INFORMATION.AnonymousUnionPayload, WinRas.RASTUNNELENDPOINT.UNION, Winspool.NOTIFY_DATA, WinUser.INPUT.INPUT_UNION, X11.XClientMessageEvent.Data, X11.XEvent
public abstract class Union extends Structure
Represents a native union. When writing to native memory, the field corresponding to the type passed to setType(Class) will be written to native memory. Upon reading from native memory, Structure, String, or WString fields will not be initialized unless they are the current field as identified by a call to setType(Class). The current field is always unset by default to avoid accidentally attempting to read a field that is not valid. In the case of a String, for instance, an invalid pointer may result in a memory fault when attempting to initialize the String.

  • Constructor Details

    • Union

      protected Union()
      Create a Union whose size and alignment will be calculated automatically.

    • Union

      protected Union(Pointer p)
      Create a Union of the given size, using default alignment.

    • Union

      protected Union(Pointer p, int alignType)
      Create a Union of the given size and alignment type.

    • Union

      protected Union(TypeMapper mapper)
      Create a Union of the given size and alignment type.

    • Union

      protected Union(Pointer p, int alignType, TypeMapper mapper)
      Create a Union of the given size and alignment type.

  • Method Details

    • getFieldOrder

      protected List<String> getFieldOrder()
      Unions do not need a field order, so automatically provide a value to satisfy checking in the Structure superclass.
      Overrides:
      getFieldOrder in class Structure
      Returns:
      ordered list of field names

    • setType

      public void setType(Class<?> type)
      Indicates by type which field will be used to write to native memory. If there are multiple fields of the same type, use setType(String) instead with the field name.
      Parameters:
      type - desired active type for the union
      Throws:
      IllegalArgumentException - if the type does not correspond to any declared union field.

    • setType

      public void setType(String fieldName)
      Indicates which field will be used to write to native memory.
      Parameters:
      fieldName - desired field to use for the active union type
      Throws:
      IllegalArgumentException - if the name does not correspond to any declared union field.

    • readField

      public Object readField(String fieldName)
      Force a read of the given field from native memory.
      Overrides:
      readField in class Structure
      Parameters:
      fieldName - field to be read
      Returns:
      the new field value, after updating
      Throws:
      IllegalArgumentException - if no field exists with the given name

    • writeField

      public void writeField(String fieldName)
      Write the given field value to native memory. The given field will become the active one.
      Overrides:
      writeField in class Structure
      Parameters:
      fieldName - which field to synch
      Throws:
      IllegalArgumentException - if no field exists with the given name

    • writeField

      public void writeField(String fieldName, Object value)
      Write the given field value to the field and native memory. The given field will become the active one.
      Overrides:
      writeField in class Structure
      Parameters:
      fieldName - field to write
      value - value to write
      Throws:
      IllegalArgumentException - if no field exists with the given name

    • getTypedValue

      public Object getTypedValue(Class<?> type)
      Reads the Structure field of the given type from memory, sets it as the active type and returns it. Convenience method for 
       Union u;
 Class type;
 u.setType(type);
 u.read();
 value = u.field;
      Parameters:
      type - class type of the Structure field to read
      Returns:
      the Structure field with the given type

    • setTypedValue

      public Object setTypedValue(Object object)
      Set the active type and its value. Convenience method for 
       Union u;
 Class type;
 u.setType(type);
 u.field = value;
      Parameters:
      object - instance of a class which is part of the union
      Returns:
      this Union object

    • writeField

      protected void writeField(Structure.StructField field)
      Only the currently selected field will be written.
      Overrides:
      writeField in class Structure
      Parameters:
      field - internal field representation to synch to native memory

    • readField

      protected Object readField(Structure.StructField field)
      Avoid reading pointer-based fields and structures unless explicitly selected. Structures may contain pointer-based fields which can crash the VM if not properly initialized.
      Overrides:
      readField in class Structure
      Parameters:
      field - field to be read
      Returns:
      value of the requested field

    • getNativeAlignment

      protected int getNativeAlignment(Class<?> type, Object value, boolean isFirstElement)
      All fields are considered the "first" element.
      Overrides:
      getNativeAlignment in class Structure
      Parameters:
      type - field type
      value - field value, if available
      isFirstElement - is this field the first element in the struct?
      Returns:
      the native byte alignment