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

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

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

    - #### getFieldOrder

          protected java.util.List<java.lang.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​(java.lang.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:
        `java.lang.IllegalArgumentException` - if the type does not correspond to any declared union field.

    - #### setType

          public void setType​(java.lang.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:
        `java.lang.IllegalArgumentException` - if the name does not correspond to any declared union field.

    - #### readField

          public java.lang.Object readField​(java.lang.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:
        `java.lang.IllegalArgumentException` - if no field exists with the given name

    - #### writeField

          public void writeField​(java.lang.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:
        `java.lang.IllegalArgumentException` - if no field exists with the given name

    - #### writeField

          public void writeField​(java.lang.String fieldName,
                                 java.lang.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:
        `java.lang.IllegalArgumentException` - if no field exists with the given name

    - #### getTypedValue

          public java.lang.Object getTypedValue​(java.lang.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 java.lang.Object setTypedValue​(java.lang.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 java.lang.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​(java.lang.Class<?> type,
                                           java.lang.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