Top Description Fields Constructors Methods
com.sun.jna

public abstract Class Union

extends Structure
Class Inheritance
Imports
java.lang.reflect.Field, java.util.ArrayList, .List
Represents a native union. When writing to native memory, the field corresponding to the type passed to setType 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. 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.

Field Summary

Modifier and TypeField and Description
private Structure.StructField
activeField

Inherited from com.sun.jna.Structure:
ALIGN_DEFAULTALIGN_GNUCALIGN_MSVCALIGN_NONECALCULATE_SIZEfieldOrderlayoutInfo

Constructor Summary

AccessConstructor and 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(TypeMapper mapper)

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.

Method Summary

Modifier and TypeMethod and Description
private Structure.StructField

Returns:

StructField of matching type
findField(Class<?>
type to search for
type)

Returns the field in this union with the same type as type, if any, null otherwise.

protected List<String>
getFieldOrder()

Overrides com.sun.jna.Structure.getFieldOrder.

Unions do not need a field order, so automatically provide a value to satisfy checking in the Structure superclass.
protected int
getNativeAlignment(Class<?>
field type
type, Object
field value, if available
value, boolean
is this field the first element in the struct?
isFirstElement)

Overrides com.sun.jna.Structure.getNativeAlignment.

All fields are considered the "first" element.
public Object

Returns:

the Structure field with the given type
getTypedValue(Class<?>
class type of the Structure field to read
type)

Reads the Structure field of the given type from memory, sets it as the active type and returns it.

public Object

Returns:

the new field value, after updating
readField(String
field to be read
fieldName)

Overrides com.sun.jna.Structure.readField.

Force a read of the given field from native memory.
protected Object
readField(Structure.StructField
field to be read
field)

Overrides com.sun.jna.Structure.readField.

Avoid reading pointer-based fields and structures unless explicitly selected.
public void
setType(Class<?>
desired active type for the union
type)

Indicates by type which field will be used to write to native memory.

public void
setType(String
desired field to use for the active union type
fieldName)

Indicates which field will be used to write to native memory.

public Object

Returns:

this Union object
setTypedValue(Object
instance of a class which is part of the union
object)

Set the active type and its value.

public void
writeField(String
which field to synch
fieldName)

Overrides com.sun.jna.Structure.writeField.

Write the given field value to native memory.
public void
writeField(String
field to write
fieldName, Object
value to write
value)

Overrides com.sun.jna.Structure.writeField.

Write the given field value to the field and native memory.
protected void
writeField(Structure.StructField
internal field representation to synch to native memory
field)

Overrides com.sun.jna.Structure.writeField.

Only the currently selected field will be written.
Inherited from com.sun.jna.Structure:
allocateMemoryallocateMemoryautoAllocateautoReadautoReadautoWriteautoWritebusycacheTypeInfocalculateSizecalculateSizeclearconditionalAutoReadcreateFieldsOrdercreateFieldsOrdercreateFieldsOrdercreateFieldsOrderdataEqualsdataEqualsensureAllocatedequalsfieldOffsetfieldsgetAutoReadgetAutoWritegetFieldListgetFieldsgetFieldTypeInfogetFieldValuegetNativeSizegetNativeSizegetPointergetStringEncodinggetStructAlignmentgetTypeInfogetTypeInfogetTypeMapperhashCodenewInstancenewInstancereadreadingsetAlignTypesetAutoReadsetAutoSynchsetAutoWritesetFieldValuesetStringEncodingsizesizesizesortFieldstoArraytoArraytoStringtoStringupdateStructureByReferenceuseMemoryuseMemoryuseMemoryvalidatewrite

Field Detail

activeFieldback to summary
private Structure.StructField activeField

Constructor Detail

Unionback to summary
protected Union()

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

Unionback to summary
protected Union(Pointer p)

Create a Union of the given size, using default alignment.

Unionback to summary
protected Union(Pointer p, int alignType)

Create a Union of the given size and alignment type.

Unionback to summary
protected Union(TypeMapper mapper)

Create a Union of the given size and alignment type.

Unionback to summary
protected Union(Pointer p, int alignType, TypeMapper mapper)

Create a Union of the given size and alignment type.

Method Detail

findFieldback to summary
private Structure.StructField findField(Class<?> type)

Returns the field in this union with the same type as type, if any, null otherwise.

Parameters
type:Class<?>

type to search for

Returns:Structure.StructField

StructField of matching type

getFieldOrderback to summary
protected List<String> getFieldOrder()

Overrides com.sun.jna.Structure.getFieldOrder.

Unions do not need a field order, so automatically provide a value to satisfy checking in the Structure superclass.

Returns:List<String>

Doc from com.sun.jna.Structure.getFieldOrder.

ordered list of field names

Annotations
@Override
getNativeAlignmentback to summary
protected int getNativeAlignment(Class<?> type, Object value, boolean isFirstElement)

Overrides com.sun.jna.Structure.getNativeAlignment.

All fields are considered the "first" element.

Parameters
type:Class<?>

Doc from com.sun.jna.Structure.getNativeAlignment.

field type

value:Object

Doc from com.sun.jna.Structure.getNativeAlignment.

field value, if available

isFirstElement:boolean

Doc from com.sun.jna.Structure.getNativeAlignment.

is this field the first element in the struct?

Returns:int

Doc from com.sun.jna.Structure.getNativeAlignment.

the native byte alignment

Annotations
@Override
getTypedValueback to summary
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<?>

class type of the Structure field to read

Returns:Object

the Structure field with the given type

readFieldback to summary
public Object readField(String fieldName)

Overrides com.sun.jna.Structure.readField.

Force a read of the given field from native memory.

Parameters
fieldName:String

Doc from com.sun.jna.Structure.readField.

field to be read

Returns:Object

the new field value, after updating

Annotations
@Override
Exceptions
IllegalArgumentException:
if no field exists with the given name
readFieldback to summary
protected Object readField(Structure.StructField field)

Overrides com.sun.jna.Structure.readField.

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.

Parameters
field:Structure.StructField

Doc from com.sun.jna.Structure.readField.

field to be read

Returns:Object

Doc from com.sun.jna.Structure.readField.

value of the requested field

Annotations
@Override
setTypeback to summary
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:Class<?>

desired active type for the union

Exceptions
IllegalArgumentException:
if the type does not correspond to any declared union field.
setTypeback to summary
public void setType(String fieldName)

Indicates which field will be used to write to native memory.

Parameters
fieldName:String

desired field to use for the active union type

Exceptions
IllegalArgumentException:
if the name does not correspond to any declared union field.
setTypedValueback to summary
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:Object

instance of a class which is part of the union

Returns:Object

this Union object

writeFieldback to summary
public void writeField(String fieldName)

Overrides com.sun.jna.Structure.writeField.

Write the given field value to native memory. The given field will become the active one.

Parameters
fieldName:String

Doc from com.sun.jna.Structure.writeField.

which field to synch

Annotations
@Override
Exceptions
IllegalArgumentException:
if no field exists with the given name
writeFieldback to summary
public void writeField(String fieldName, Object value)

Overrides com.sun.jna.Structure.writeField.

Write the given field value to the field and native memory. The given field will become the active one.

Parameters
fieldName:String

Doc from com.sun.jna.Structure.writeField.

field to write

value:Object

Doc from com.sun.jna.Structure.writeField.

value to write

Annotations
@Override
Exceptions
IllegalArgumentException:
if no field exists with the given name
writeFieldback to summary
protected void writeField(Structure.StructField field)

Overrides com.sun.jna.Structure.writeField.

Only the currently selected field will be written.

Parameters
field:Structure.StructField

Doc from com.sun.jna.Structure.writeField.

internal field representation to synch to native memory

Annotations
@Override