com.sun.jna

## Class Union

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

Direct Known Subclasses:
  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, Variant.VARIANT, Variant.VARIANT._VARIANT.__VARIANT, WinBase.SYSTEM_INFO.UNION, Winevt.EVT_VARIANT.field1_union, Wininet.INTERNET_CACHE_ENTRY_INFO.UNION, WinNT.LARGE_INTEGER.UNION, WinNT.SYSTEM_LOGICAL_PROCESSOR_INFORMATION.AnonymousUnionPayload, WinRas.RASTUNNELENDPOINT.UNION, 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.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
`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
`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.
`java.lang.Object` `readField(java.lang.String fieldName)` Force a read of the given field from native memory.
`protected java.lang.Object` `readField(Structure.StructField field)` Avoid reading pointer-based fields and structures unless explicitly selected.
`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.
`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.
`protected void` `writeField(Structure.StructField field)` Only the currently selected field will be written.

### 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, setFieldOrder, setFieldValue, setStringEncoding, size, size, size, sortFields, toArray, toArray, toString, toString, typeInfoField, 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.

Specified by:
  `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

Copyright © 2007-2016 Timothy Wall. All Rights Reserved.