com.sun.jna

Class Union

public abstract class Union extends Structure

Represents a native union. When writing to native memory, the field corresponding to the type passed to Union 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 Union. 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
StructFieldbiggestField
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(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
intcalculateSize(boolean force)
Adjust the size to be the size of the largest element, and ensure all fields begin at offset zero.
protected intgetNativeAlignment(Class type, Object value, boolean isFirstElement)
All fields are considered the "first" element.
ObjectgetTypedValue(Class type)
Reads the Structure field of the given type from memory, sets it as the active type and returns it.
PointergetTypeInfo()
Avoid calculating type information until we know our biggest field.
ObjectreadField(String name)
Force a read of the given field from native memory.
ObjectreadField(StructField field)
Avoid reading pointer-based fields and structures unless explicitly selected.
voidsetType(Class type)
Indicates which field will be used to write to native memory.
ObjectsetTypedValue(Object object)
Set the active type and its value.
voidwriteField(String name)
Write the given field value to native memory.
voidwriteField(String name, Object value)
Write the given field value to the field and native memory.
voidwriteField(StructField field)
Only the currently selected field will be written.

Field Detail

biggestField

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

calculateSize

int calculateSize(boolean force)
Adjust the size to be the size of the largest element, and ensure all fields begin at offset zero.

getNativeAlignment

protected int getNativeAlignment(Class type, Object value, boolean isFirstElement)
All fields are considered the "first" element.

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

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.

readField

public Object readField(String name)
Force a read of the given field from native memory.

Returns: the new field value, after updating

Throws: IllegalArgumentException if no field exists with the given name

readField

Object readField(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.

setType

public void setType(Class type)
Indicates which field will be used to write to native memory.

Throws: IllegalArgumentException if the type does not correspond to any declared union field.

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

public void writeField(String name)
Write the given field value to native memory. The given field will become the active one.

Throws: IllegalArgumentException if no field exists with the given name

writeField

public void writeField(String name, Object value)
Write the given field value to the field and native memory. The given field will become the active one.

Throws: IllegalArgumentException if no field exists with the given name

writeField

void writeField(StructField field)
Only the currently selected field will be written.
Copyright © 2007-2009 Timothy Wall. All Rights Reserved.