JNA API 3.3.0

## com.sun.jna
Class Union

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

Direct Known Subclasses:
  NTSecApi.LSA_FOREST_TRUST_RECORD.UNION, WinBase.SYSTEM_INFO.UNION, WinNT.LARGE_INTEGER.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`

Field Summary
`(package private) Structure.StructField` | `biggestField`

Fields inherited from class com.sun.jna.Structure
`ALIGN_DEFAULT, ALIGN_GNUC, ALIGN_MSVC, ALIGN_NONE, CALCULATE_SIZE, isPPC, isSPARC, MAX_GNUC_ALIGNMENT`

Constructor Summary
`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
`(package private) int` | `calculateSize(boolean force)` Adjust the size to be the size of the largest element, and ensure all fields begin at offset zero.
`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.
`(package private) Pointer` | `getTypeInfo()` Avoid calculating type information until we know our biggest field.
`Object` | `readField(String fieldName)` Force a read of the given field from native memory.
`(package private) Object` | `readField(Structure.StructField field)` Avoid reading pointer-based fields and structures unless explicitly selected.
`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.
`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.
`(package private) 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, calculateAlignedSize, clear, ensureAllocated, equals, fields, getAutoRead, getAutoWrite, getField, getFieldOrder, getFields, getPointer, getStructAlignment, getTypeInfo, hashCode, newInstance, read, reading, setAlignType, setAutoRead, setAutoSynch, setAutoWrite, setField, setFieldOrder, setTypeMapper, size, sortFields, toArray, toArray, toString, toString, updateStructureByReference, useMemory, useMemory, write`

Methods inherited from class java.lang.Object
`clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

Field Detail

### biggestField

    Structure.StructField biggestField

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

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

  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.

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

    void writeField(Structure.StructField field)

  Only the currently selected field will be written.

  Overrides:
    `writeField` in class `Structure`

### readField

    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`

### calculateSize

    int calculateSize(boolean force)

  Adjust the size to be the size of the largest element, and ensure all fields begin at offset zero.

  Overrides:
    `calculateSize` in class `Structure`

### getNativeAlignment

    protected int getNativeAlignment(Class type,
                                     Object value,
                                     boolean isFirstElement)

  All fields are considered the "first" element.

  Overrides:
    `getNativeAlignment` in class `Structure`

### getTypeInfo

    Pointer getTypeInfo()

  Avoid calculating type information until we know our biggest field. Return type information for the largest field to ensure all available bits are used.

  Overrides:
    `getTypeInfo` in class `Structure`

JNA API 3.3.0

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