com.sun.jna.platform.win32

Class OaIdl.SAFEARRAY

java.lang.Object

com.sun.jna.Structure

com.sun.jna.platform.win32.OaIdl.SAFEARRAY

All Implemented Interfaces:

Closeable, AutoCloseable

Direct Known Subclasses:

OaIdl.SAFEARRAY.ByReference

Enclosing interface:

OaIdl

public static class OaIdl.SAFEARRAY
extends Structure
implements Closeable

Implementation of SAFEARRAY. Implements Closable, which in this case delegates to destroy, to free native memory on close.

VARTYPE for the SAFEARRAY can be:

• VT_BOOL
• VT_BSTR
• VT_CY
• VT_DATE
• VT_DECIMAL
• VT_DISPATCH
• VT_ERROR
• VT_I1
• VT_I2
• VT_I4
• VT_INT
• VT_R4
• VT_R8
• VT_RECORD
• VT_UI1
• VT_UI2
• VT_UI4
• VT_UINT
• VT_UNKNOWN
• VT_VARIANT

General comment: All indices in the helper methods use java int.

The native type for the indices is LONG, which is defined as:

A 32-bit signed integer. The range is �2147483648 through 2147483647 decimal.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	OaIdl.SAFEARRAY.ByReference

Nested classes/interfaces inherited from class com.sun.jna.Structure

Structure.ByValue, Structure.StructField

Field Summary

Fields

Modifier and Type	Field and Description
WinDef.ULONG	cbElements
WinDef.USHORT	cDims
WinDef.ULONG	cLocks
WinDef.USHORT	fFeatures
static List<String>	FIELDS
WinDef.PVOID	pvData
OaIdl.SAFEARRAYBOUND[]	rgsabound The rgsabound.

Fields inherited from class com.sun.jna.Structure

ALIGN_DEFAULT, ALIGN_GNUC, ALIGN_MSVC, ALIGN_NONE, CALCULATE_SIZE

Constructor Summary

Constructors

Constructor and Description
SAFEARRAY()
SAFEARRAY(Pointer pointer)

Method Summary

Modifier and Type	Method and Description
Pointer	accessData() Lock array and retrieve pointer to data
void	close() Implemented to satisfy Closeable interface, delegates to destroy.
static OaIdl.SAFEARRAY	createSafeArray(int... size) Create a SAFEARRAY with supplied VARIANT as element type.
static OaIdl.SAFEARRAY	createSafeArray(WTypes.VARTYPE vartype, int... size) Create a SAFEARRAY with supplied element type.
void	destroy() Destroy the underlying SAFEARRAY and free memory
int	getDimensionCount() Return number of dimensions of the SAFEARRAY
Object	getElement(int... indices) Retrieve the value at the referenced index from the SAFEARRAY.
long	getElemsize() Get size of one element in bytes
protected List<String>	getFieldOrder() Return this Structure's field names in their proper order.
int	getLBound(int dimension) Retrieve lower bound for the selected dimension.
int	getUBound(int dimension) Retrieve upper bound for the selected dimension.
WTypes.VARTYPE	getVarType() Return VARTYPE of the SAFEARRAY
void	lock() Increments the lock count of an array, and places a pointer to the array data in pvData of the array descriptor.
Pointer	ptrOfIndex(int... indices) Retrieve pointer to data element from array.
void	putElement(Object arg, int... indices) Set value at indices in array to arg.
void	read() Reads the fields of the struct from native memory
void	redim(int cElements, int lLbound) Changes the right-most (least significant) bound of the specified safe array.
void	unaccessData() Unlock array and invalidate the pointer retrieved via SafeArrayAccessData
void	unlock() Decrements the lock count of an array so it can be freed or resized

Methods inherited from class com.sun.jna.Structure

allocateMemory, allocateMemory, autoAllocate, autoRead, autoRead, autoWrite, autoWrite, cacheTypeInfo, calculateSize, clear, createFieldsOrder, createFieldsOrder, createFieldsOrder, createFieldsOrder, dataEquals, dataEquals, ensureAllocated, equals, fieldOffset, getAutoRead, getAutoWrite, getFieldList, getFields, getNativeAlignment, getNativeSize, getNativeSize, getPointer, getStringEncoding, getStructAlignment, hashCode, newInstance, newInstance, readField, readField, setAlignType, setAutoRead, setAutoSynch, setAutoWrite, setFieldOrder, setStringEncoding, size, sortFields, toArray, toArray, toString, toString, useMemory, useMemory, write, writeField, writeField, writeField

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

FIELDS

public static final List<String> FIELDS

cDims

public WinDef.USHORT cDims

fFeatures

public WinDef.USHORT fFeatures

cbElements

public WinDef.ULONG cbElements

cLocks

public WinDef.ULONG cLocks

pvData

public WinDef.PVOID pvData

rgsabound

public OaIdl.SAFEARRAYBOUND[] rgsabound

The rgsabound.

Constructor Detail

SAFEARRAY

public SAFEARRAY()

SAFEARRAY

public SAFEARRAY(Pointer pointer)

Method Detail

read

public void read()

Description copied from class: Structure

Reads the fields of the struct from native memory

Overrides:

read in class Structure

getFieldOrder

protected List<String> getFieldOrder()

Description copied from class: Structure

Return this Structure's field names in their proper order. For example,

 protected List getFieldOrder() {
     return Arrays.asList(new String[] { ... });
 }
 

IMPORTANT When deriving from an existing Structure subclass, ensure that you augment the list provided by the superclass, e.g.

 protected List getFieldOrder() {
     List fields = new ArrayList(super.getFieldOrder());
     fields.addAll(Arrays.asList(new String[] { ... }));
     return fields;
 }
 

Field order must be explicitly indicated, since the field order as returned by Class.getFields() is not guaranteed to be predictable.

Specified by:

getFieldOrder in class Structure

Returns:

ordered list of field names

createSafeArray

public static OaIdl.SAFEARRAY createSafeArray(int... size)

Create a SAFEARRAY with supplied VARIANT as element type.

This helper creates a basic SAFEARRAY with a base type of VT_VARIANT. The array will have as many dimensions as parameters are passed in. The lowerbound for each dimension is set to zero, the count to the parameter value.

Parameters:

size - array of dimension size

Returns:

SAFEARRAYWrapper or NULL if creation fails.

createSafeArray

public static OaIdl.SAFEARRAY createSafeArray(WTypes.VARTYPE vartype,
                                              int... size)

Create a SAFEARRAY with supplied element type.

The array will have as many dimensions as parameters are passed in. The lowerbound for each dimension is set to zero, the count to the parameter value.

Parameters:

vartype - type of array contents (see Variant.VT_* constants)

size - array of dimension size

Returns:

SAFEARRAYWrapper or NULL if creation fails.

putElement

public void putElement(Object arg,
                       int... indices)

Set value at indices in array to arg.

The supplied argument is copied into the array. If the value is no longer needed, it needs to be freed if not handled automatically.

Parameters:

indices - the index, order follows java/C convention

arg - the arg

getElement

public Object getElement(int... indices)

Retrieve the value at the referenced index from the SAFEARRAY.

The function creates a copy of the value. The values are allocated with native functions and need to be freed accordingly.

Parameters:

indices - the index, order follows java/C convention

Returns:

the variant

ptrOfIndex

public Pointer ptrOfIndex(int... indices)

Retrieve pointer to data element from array.

Caller is responsible for (un)locking the array via OleAuto.SafeArrayLock(com.sun.jna.platform.win32.OaIdl.SAFEARRAY) and OleAuto.SafeArrayUnlock(com.sun.jna.platform.win32.OaIdl.SAFEARRAY) or the helper methods: lock() and unlock().

Parameters:

indices - the index, order follows java/C convention

Returns:

the pointer to the data element

destroy

public void destroy()

Destroy the underlying SAFEARRAY and free memory

close

public void close()

Implemented to satisfy Closeable interface, delegates to destroy.

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

getLBound

public int getLBound(int dimension)

Retrieve lower bound for the selected dimension.

As in the all the accessor functions, that index is converted to java conventions.

Parameters:

dimension - zerobased index

Returns:

lower bound for the selected dimension

getUBound

public int getUBound(int dimension)

Retrieve upper bound for the selected dimension.

As in the all the accessor functions, that index is converted to java conventions.

Parameters:

dimension - zerobased index

Returns:

upper bound for the selected dimension

getDimensionCount

public int getDimensionCount()

Return number of dimensions of the SAFEARRAY

Returns:

number of dimensions of the SAFEARRAY

accessData

public Pointer accessData()

Lock array and retrieve pointer to data

Returns:

Pointer to arraydata

unaccessData

public void unaccessData()

Unlock array and invalidate the pointer retrieved via SafeArrayAccessData

lock

public void lock()

Increments the lock count of an array, and places a pointer to the array data in pvData of the array descriptor.

unlock

public void unlock()

Decrements the lock count of an array so it can be freed or resized

redim

public void redim(int cElements,
                  int lLbound)

Changes the right-most (least significant) bound of the specified safe array.

Parameters:

cElements -

lLbound -

getVarType

public WTypes.VARTYPE getVarType()

Return VARTYPE of the SAFEARRAY

Returns:

VARTYPE of the SAFEARRAY

getElemsize

public long getElemsize()

Get size of one element in bytes

Returns:

element size in bytes