Union (JNA API)
Description: declaration: package: com.sun.jna, class: Union

Package com.sun.jna

# 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(java.lang.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(java.lang.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.

- ## Nested Class Summary

  ## Nested classes/interfaces inherited from class com.sun.jna.Structure

  `Structure.ByReference, Structure.ByValue, Structure.FFIType, Structure.FieldOrder, Structure.StructField, Structure.StructureSet`

- ## Field Summary

  ### Fields inherited from class com.sun.jna.Structure

  `ALIGN_DEFAULT, ALIGN_GNUC, ALIGN_MSVC, ALIGN_NONE, CALCULATE_SIZE, fieldOrder, layoutInfo`

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `Union()`
  Create a Union whose size and alignment will be calculated automatically.
  `protected`
  `Union(Pointer p)`
  Create a Union of the given size, using default alignment.
  `protected`
  `Union(Pointer p, int alignType)`
  Create a Union of the given size and alignment type.
  `protected`
  `Union(Pointer p, int alignType, TypeMapper mapper)`
  Create a Union of the given size and alignment type.
  `protected`
  `Union(TypeMapper mapper)`
  Create a Union of the given size and alignment type.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected List<String>`
  `getFieldOrder()`
  Unions do not need a field order, so automatically provide a value to satisfy checking in the Structure superclass.
  `protected int`
  `getNativeAlignment(Class<?> type, Object value, boolean isFirstElement)`
  All fields are considered the "first" element.
  `Object`
  `getTypedValue(Class<?> type)`
  Reads the Structure field of the given type from memory, sets it as the active type and returns it.
  `protected Object`
  `readField(Structure.StructField field)`
  Avoid reading pointer-based fields and structures unless explicitly selected.
  `Object`
  `readField(String fieldName)`
  Force a read of the given field from native memory.
  `void`
  `setType(Class<?> type)`
  Indicates by type which field will be used to write to native memory.
  `void`
  `setType(String fieldName)`
  Indicates which field will be used to write to native memory.
  `Object`
  `setTypedValue(Object object)`
  Set the active type and its value.
  `protected void`
  `writeField(Structure.StructField field)`
  Only the currently selected field will be written.
  `void`
  `writeField(String fieldName)`
  Write the given field value to native memory.
  `void`
  `writeField(String fieldName, Object value)`
  Write the given field value to the field and native memory.

  ### Methods inherited from class com.sun.jna.Structure

  `allocateMemory, allocateMemory, autoAllocate, autoRead, autoRead, autoWrite, autoWrite, busy, cacheTypeInfo, calculateSize, calculateSize, clear, conditionalAutoRead, createFieldsOrder, createFieldsOrder, createFieldsOrder, createFieldsOrder, dataEquals, dataEquals, ensureAllocated, equals, fieldOffset, fields, getAutoRead, getAutoWrite, getFieldList, getFields, getFieldTypeInfo, getFieldValue, getNativeSize, getNativeSize, getPointer, getStringEncoding, getStructAlignment, getTypeInfo, getTypeInfo, getTypeMapper, hashCode, newInstance, newInstance, read, reading, setAlignType, setAutoRead, setAutoSynch, setAutoWrite, setFieldValue, setStringEncoding, size, size, size, sortFields, toArray, toArray, toString, toString, updateStructureByReference, useMemory, useMemory, useMemory, validate, write`

  ### Methods inherited from class java.lang.Object

  `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

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