com.jniwrapper.win32.automation.types
Class SafeArray

java.lang.Object
  com.jniwrapper.Parameter
      com.jniwrapper.win32.automation.types.SafeArray

All Implemented Interfaces:

AutoDeleteParameter, PointerParameter

public class SafeArray

extends Parameter

implements AutoDeleteParameter, PointerParameter

This class is the special helper class for working with SafeArray.SafeArrayStructure, which corresponds to the SAFEARRAY data type. Instance of SafeArray can be considered as the pointer to the SafeArrayStructure structure. -breakiterator NOTE: the instance of this class is freed automatically, by the NativeResourceCollector if there is no more locks for a given instance.

See Also:

Microsoft Automation SDK documentation

Nested Class Summary

static class	SafeArray.SafeArrayAttributes
class	SafeArray.SafeArrayStructure This class represents SAFEARRAY Data Type.

Field Summary

Fields inherited from class com.jniwrapper.Parameter

LICENSE_TYPE, V

Constructor Summary

SafeArray()
Initializes empty instance.

SafeArray(byte[] bytes)
Creates the array of bytes (UInt8) directly from the specified Java byte array.

SafeArray(java.lang.Class parameterClass)
Initializes a new instance of safe array of elements, specified by parameterClass parameter.

SafeArray(double[] array)
Creates a SafeArray of DoubleFloat elements from a specified array of double's.

SafeArray(float[] array)
Creates a SafeArray of Float elements from a specified array of float's.

SafeArray(int[] array)
Creates a SafeArray of Int elements from a specified array of int's.

SafeArray(int[] counts, java.lang.Class parameterClass)
Creates multidimensional array for specified data type and the specified array bounds of SafeArrayBound type.

SafeArray(int count, java.lang.Class parameterClass)
Creates one-dimensional array for specified data type and element counts.

SafeArray(int count, int lowerBound, java.lang.Class parameterClass)
Creates one-dimensional array for specified data type, lower bound and element counts.

SafeArray(long[] array)
Creates a SafeArray of LongInt elements from a specified array of long's.

SafeArray(Parameter[] array)
Creates a SafeArray object from a specified array of parameters.

SafeArray(Pointer.Void psa, java.lang.Class parameterClass)
Constructs an array from a pointer

SafeArray(SafeArrayBound[] bounds, byte[] bytes)
Creates the array of bytes (UInt8) directly from the specified Java byte array.

SafeArray(SafeArrayBound[] bounds, byte[] bytes, java.lang.Class parameterClass)
Creates the array of bytes directly from the specified Java byte array.

SafeArray(SafeArrayBound[] bounds, java.lang.Class parameterClass)
Creates multi-dimensional array for specified data type and the specified array bounds of SafeArrayBound type.

SafeArray(SafeArrayBound bound, java.lang.Class parameterClass)
Creates one-dimensional array for specified data type and the specified array bound of SafeArrayBound type.

SafeArray(java.lang.String[] array)
Creates a SafeArray of BStr elements from a specified array of strings.

Method Summary

void	acceptIOPerformer(IOPerformer performer, DataBuffer buffer, int initialOffset, boolean isReadOperation, boolean invokedByCallback)
void	changeSize(int newSize) Changes array size (only last dimension can be changed)
java.lang.Object	clone()
void	create(byte[] bytes) Creates the array of bytes (UInt8) directly from the specified Java byte array.
void	create(int[] counts, java.lang.Class parameterClass) Creates multidimensional array for specified data type and the specified array bounds of SafeArrayBound type.
void	create(int count, java.lang.Class parameterClass) Creates one-dimensional array for specified data type and element counts.
void	create(int count, int lowerBound, java.lang.Class parameterClass) Creates one-dimensional array for specified data type, lower bound and element counts.
protected void	create(SafeArrayBound bound)
protected void	create(SafeArrayBound[] bounds)
void	create(SafeArrayBound[] bounds, byte[] bytes) Creates the array of bytes (UInt8) directly from the specified Java byte array.
void	create(SafeArrayBound[] bounds, byte[] bytes, java.lang.Class parameterClass) Creates the array of bytes directly from the specified Java byte array.
void	create(SafeArrayBound[] bounds, java.lang.Class parameterClass) Creates multidimensional array for specified data type and the specified array bounds of SafeArrayBound type.
void	create(SafeArrayBound bound, java.lang.Class parameterClass) Creates one-dimensional array for specified data type and the specified array bound of SafeArrayBound type.
Parameter	get(int index) Returns an element of the one-dimensional array by the specified index.
Parameter	get(int[] indices) Returns an element of the multi-dimensional array by the specified indices.
Parameter	get(int[] indices, boolean useAPI) Returns an element of the multi-dimensional array by the specified indices.
ComplexArray	getBounds() Returns the bounds of the complex array.
byte[]	getBytes() Retrieves Java byte array from this array.
int	getCount() Returns the number of elements in the one-dimensional array.
int	getCount(int dims) Returns the number of elements in the multi-dimensional array.
ExternalArrayPointer	getData() Returns the pointer to the data.
java.lang.String	getDebugInfo()
int	getDimensions() Returns the number of dimensions in the array.
SafeArray.SafeArrayAttributes	getFeatures()
long	getHandle() Returns the address of this SafeArray object.
int	getLength() Returns the length of SafeArray parameter.
int	getLocks() Returns number of locks on this array.
int	getLowerBound() Returns the lower bound of the array.
int	getLowerBound(int dims) Returns the lower bound of the array with specified numbers of dimensions.
static VarType	getSafeArrayType(Parameter psa) Determines VarType of a specified safe array parameter
int	getUpperBound() Returns the upper bound of the array.
int	getUpperBound(int dims) Returns the upper bound of the array with specified numbers of dimensions.
int	getVarType() Returns the type of data, stored in the array.
boolean	isAutoDelete() Returns true if resource is auto deleteable else return false.
boolean	isNull() Check if this object is null.
void	read(DataBuffer stackBuffer, int offset, boolean invokedByCallback)
void	release() Releases native resources of this object.
void	set(int[] indices, Parameter value) Sets the element at a given index in the multi-dimensional array.
void	set(int[] indices, Parameter value, boolean useAPI) Sets the element at a given index in the multi-dimensional array.
void	set(int index, Parameter value) Sets the element at a given index in the one-dimensional array.
void	setAutoDelete(boolean isAutoDelete) Make resource auto deleteable or manually deleteable.
protected void	setHandle(long value)
void	unlock()
void	write(DataBuffer stackBuffer, int offset, boolean invokedByCallback)

Methods inherited from class com.jniwrapper.Parameter

, a, a, asReturnValue, b, dataBufferAssigned, equals, getAlignedLength, getAlignmentRequirement, getDataBuffer, getDataBufferOffset, hashCode, indent, pop, push, read, read, setDataBuffer, toByteArray, write

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SafeArray

public SafeArray()

Initializes empty instance. NOTE: This constructor does not create the instance on the native side.

SafeArray

public SafeArray(java.lang.Class parameterClass)

Initializes a new instance of safe array of elements, specified by parameterClass parameter. -breakiterator NOTE: This constructor does not create the instance on the native side.

Parameters:

parameterClass - specifies elements to be stored in the safe array.

SafeArray

public SafeArray(int count,
                 int lowerBound,
                 java.lang.Class parameterClass)

Creates one-dimensional array for specified data type, lower bound and element counts.

Parameters:

count - element count.

lowerBound - lower bound.

parameterClass - data type srored in the safe array.

SafeArray

public SafeArray(int count,
                 java.lang.Class parameterClass)

Creates one-dimensional array for specified data type and element counts.

Parameters:

count - element count.

parameterClass - data type srored in the safe array.

SafeArray

public SafeArray(SafeArrayBound bound,
                 java.lang.Class parameterClass)

Creates one-dimensional array for specified data type and the specified array bound of SafeArrayBound type.

Parameters:

bound - bound for the array.

parameterClass - data type srored in the safe array.

SafeArray

public SafeArray(Parameter[] array)

Creates a SafeArray object from a specified array of parameters.

Parameters:

array - of parameters. All elements of array should be initialized and should have the same type.

SafeArray

public SafeArray(java.lang.String[] array)

Creates a SafeArray of BStr elements from a specified array of strings.

Parameters:

array - string array

SafeArray

public SafeArray(int[] array)

Creates a SafeArray of Int elements from a specified array of int's.

Parameters:

array - array of int's

SafeArray

public SafeArray(long[] array)

Creates a SafeArray of LongInt elements from a specified array of long's.

Parameters:

array - array of long's

SafeArray

public SafeArray(float[] array)

Creates a SafeArray of Float elements from a specified array of float's.

Parameters:

array - array of float's

SafeArray

public SafeArray(double[] array)

Creates a SafeArray of DoubleFloat elements from a specified array of double's.

Parameters:

array - array of double's

SafeArray

public SafeArray(SafeArrayBound[] bounds,
                 java.lang.Class parameterClass)

Creates multi-dimensional array for specified data type and the specified array bounds of SafeArrayBound type.

Parameters:

bounds - array of bounds for the multi-dimensional array.

parameterClass - data type srored in the safe array.

SafeArray

public SafeArray(int[] counts,
                 java.lang.Class parameterClass)

Creates multidimensional array for specified data type and the specified array bounds of SafeArrayBound type.

Parameters:

counts - number of elements in each bound for the multi-dimensional array.

parameterClass - data type srored in the safe array.

SafeArray

public SafeArray(byte[] bytes)

Creates the array of bytes (UInt8) directly from the specified Java byte array.

Parameters:

bytes - bytes to be stored in the resulting array

SafeArray

public SafeArray(SafeArrayBound[] bounds,
                 byte[] bytes)

Creates the array of bytes (UInt8) directly from the specified Java byte array.

Parameters:

bounds - multidimensional array bounds

bytes - bytes to be stored in the resulting array

SafeArray

public SafeArray(SafeArrayBound[] bounds,
                 byte[] bytes,
                 java.lang.Class parameterClass)

Creates the array of bytes directly from the specified Java byte array.

Parameters:

bounds - multidimensional array bounds

bytes - bytes to be stored in the resulting array

parameterClass - specifies the class of parameters

SafeArray

public SafeArray(Pointer.Void psa,
                 java.lang.Class parameterClass)

Constructs an array from a pointer

Parameters:

psa - pointer to a safe array

parameterClass - type of data in the safe array

Method Detail

create

public void create(int count,
                   int lowerBound,
                   java.lang.Class parameterClass)

Creates one-dimensional array for specified data type, lower bound and element counts. This method destroys previous array content, if that one is allocated before.

Parameters:

count - element count.

lowerBound - lower bound.

parameterClass - data type srored in the safe array.

create

public void create(int count,
                   java.lang.Class parameterClass)

Creates one-dimensional array for specified data type and element counts. This method destroys previous array content, if that one is allocated before.

Parameters:

count - element count.

parameterClass - data type srored in the safe array.

create

public void create(SafeArrayBound bound,
                   java.lang.Class parameterClass)

Creates one-dimensional array for specified data type and the specified array bound of SafeArrayBound type. This method destroys previous array content, if that one is allocated before.

Parameters:

bound - bound for the array.

parameterClass - data type srored in the safe array.

create

public void create(SafeArrayBound[] bounds,
                   java.lang.Class parameterClass)

Creates multidimensional array for specified data type and the specified array bounds of SafeArrayBound type. This method destroys previous array content, if that one is allocated before.

Parameters:

bounds - array of bounds for the multi-dimensional array.

parameterClass - data type srored in the safe array.

create

public void create(int[] counts,
                   java.lang.Class parameterClass)

Creates multidimensional array for specified data type and the specified array bounds of SafeArrayBound type. This method destroys previous array content, if that one is allocated before.

Parameters:

counts - number of elements in each bound for the multi-dimensional array.

parameterClass - data type srored in the safe array.

create

public void create(byte[] bytes)

Creates the array of bytes (UInt8) directly from the specified Java byte array. This method destroys previous array content, if that one is allocated before.

Parameters:

bytes - bytes to be stored in the resulting array

create

public void create(SafeArrayBound[] bounds,
                   byte[] bytes)

Creates the array of bytes (UInt8) directly from the specified Java byte array. This method destroys previous array content, if that one is allocated before.

Parameters:

bounds - multidimensional array bounds

bytes - bytes to be stored in the resulting array

create

public void create(SafeArrayBound[] bounds,
                   byte[] bytes,
                   java.lang.Class parameterClass)

Creates the array of bytes directly from the specified Java byte array.

Parameters:

bounds - multidimensional array bounds

bytes - bytes to be stored in the resulting array

parameterClass - specifies the class of parameters

acceptIOPerformer

public void acceptIOPerformer(IOPerformer performer,
                              DataBuffer buffer,
                              int initialOffset,
                              boolean isReadOperation,
                              boolean invokedByCallback)

getHandle

public long getHandle()

Returns the address of this SafeArray object.

Returns:

the address of this SafeArray object.

setHandle

protected void setHandle(long value)

getBounds

public ComplexArray getBounds()

Returns the bounds of the complex array.

Returns:

the bounds of the complex array

isNull

public boolean isNull()

Check if this object is null.

Specified by:

isNull in interface PointerParameter

getVarType

public int getVarType()

Returns the type of data, stored in the array. See VarType.

Returns:

the type of data, stored in the array.

getFeatures

public SafeArray.SafeArrayAttributes getFeatures()

getData

public ExternalArrayPointer getData()

Returns the pointer to the data.

Returns:

the pointer to the data

write

public void write(DataBuffer stackBuffer,
                  int offset,
                  boolean invokedByCallback)
           throws MemoryAccessViolationException

Throws:

MemoryAccessViolationException

read

public void read(DataBuffer stackBuffer,
                 int offset,
                 boolean invokedByCallback)
          throws MemoryAccessViolationException

Throws:

MemoryAccessViolationException

getLength

public int getLength()

Returns the length of SafeArray parameter.

Returns:

the length of SafeArray parameter.

getDebugInfo

public java.lang.String getDebugInfo()

getBytes

public byte[] getBytes()

Retrieves Java byte array from this array.

Returns:

Java byte array from this array.

clone

public java.lang.Object clone()

create

protected void create(SafeArrayBound bound)

create

protected void create(SafeArrayBound[] bounds)

getLowerBound

public int getLowerBound()

Returns the lower bound of the array.

Returns:

lower bound of the array.

getLowerBound

public int getLowerBound(int dims)

Returns the lower bound of the array with specified numbers of dimensions.

Parameters:

dims - specifies the number of dimensions.

Returns:

lower bound of the array.

getUpperBound

public int getUpperBound()

Returns the upper bound of the array.

Returns:

lower bound of the array.

getUpperBound

public int getUpperBound(int dims)

Returns the upper bound of the array with specified numbers of dimensions.

Parameters:

dims - specifies the number of dimensions.

Returns:

lower bound of the array.

getCount

public int getCount()

Returns the number of elements in the one-dimensional array.

Returns:

the number of elements in the one-dimensional array.

getCount

public int getCount(int dims)

Returns the number of elements in the multi-dimensional array.

Parameters:

dims - specifies the number of dimensions.

Returns:

the number of elements in the multi-dimensional array.

getDimensions

public int getDimensions()

Returns the number of dimensions in the array.

Returns:

the number of dimensions in the array.

changeSize

public void changeSize(int newSize)

Changes array size (only last dimension can be changed)

Parameters:

newSize - new size of array

setAutoDelete

public void setAutoDelete(boolean isAutoDelete)

Make resource auto deleteable or manually deleteable.

Specified by:

setAutoDelete in interface AutoDeleteParameter

Parameters:

isAutoDelete - if true then resource becomes auto deleteable else you need to delete it manually.

isAutoDelete

public boolean isAutoDelete()

Returns true if resource is auto deleteable else return false.

Specified by:

isAutoDelete in interface AutoDeleteParameter

Returns:

true if resource is auto deleteable else return false

unlock

public void unlock()

release

public void release()

Releases native resources of this object.

get

public Parameter get(int index)

Returns an element of the one-dimensional array by the specified index.

Parameters:

index - index in one-dimensional array.

Returns:

element of the array.

set

public void set(int index,
                Parameter value)

Sets the element at a given index in the one-dimensional array.

Parameters:

index - index in one-dimensional array.

value - data to set.

get

public Parameter get(int[] indices)

Returns an element of the multi-dimensional array by the specified indices.

Parameters:

indices - indexes for each dimension of the array.

The right-most (least significant) dimension is indices[0].

The left-most dimension is stored at indices[cDims � 1].

Returns:

element of the array.

get

public Parameter get(int[] indices,
                     boolean useAPI)

Returns an element of the multi-dimensional array by the specified indices.

Parameters:

indices - indexes for each dimension of the array.

The right-most (least significant) dimension is indices[0].

The left-most dimension is stored at indices[cDims � 1].

useAPI - get element via API call instead of direct reading from memory

Returns:

element of the array.

set

public void set(int[] indices,
                Parameter value)

Sets the element at a given index in the multi-dimensional array.

Parameters:

indices - indexes for each dimension of the array. The right-most (least significant) dimension is indices[0]. The left-most dimension is stored at indices[cDims � 1].

value - data to assign to the array.

set

public void set(int[] indices,
                Parameter value,
                boolean useAPI)

Sets the element at a given index in the multi-dimensional array.

Parameters:

indices - indexes for each dimension of the array. The right-most (least significant) dimension is indices[0]. The left-most dimension is stored at indices[cDims � 1].

value - data to assign to the array.

useAPI - get element via API call instead of direct reading from memory

getLocks

public int getLocks()

Returns number of locks on this array.

Returns:

number of locks on this array

getSafeArrayType

public static VarType getSafeArrayType(Parameter psa)

Determines VarType of a specified safe array parameter

Parameters:

psa - safeArray poitner

Returns:

VarType of the safe array