# Class SafeArray

2014/06/06 15:54

 In this topic

 Package com.ms.com Previous ThisPackage Next

## Class SafeArray

public final class SafeArray
{
// Constructors
public SafeArray(int vt);
public SafeArray(int vt, int celems);
public SafeArray(int vt, int celems1, int celems2);
public SafeArray(int vt, int lbounds[], int celems[]);
public SafeArray(String s);
public native int getPhysicalSafeArray();

// Methods
public native String asString();
public Object clone();
public void destroy();
protected void finalize();
public void fromBooleanArray(boolean ja[]);
public void fromByteArray(byte ja[]);
public void fromCharArray(char ja[]);
public void fromDoubleArray(double ja[]);
public void fromFloatArray(float ja[]);
public void fromIntArray(int ja[]);
public void fromShortArray(short ja[]);
public void fromStringArray(String ja[]);
public void fromVariantArray(Variant ja[]);
public native boolean getBoolean(int sa_idx);
public boolean getBoolean(int sa_idx1, int sa_idx2);
public void getBooleans(int sa_idx, int nelems, boolean ja[], int
ja_start);
public byte getByte(int sa_idx);
public byte getByte(int sa_idx1, int sa_idx2);
public void getBytes(int sa_idx, int nelems, byte ja[],
int ja_start);
public char getChar(int sa_idx);
public char getChar(int sa_idx1, int sa_idx2);
public void getChars(int sa_idx, int nelems, char ja[],
int ja_start);
public native double getDouble(int sa_idx);
public double getDouble(int sa_idx1, int sa_idx2);
public void getDoubles(int sa_idx, int nelems, double ja[],
int ja_start);
public int getElemSize();
public int getFeatures();
public native float getFloat(int sa_idx);
public float getFloat(int sa_idx1, int sa_idx2);
public void getFloats(int sa_idx, int nelems, float ja[],
int ja_start);
public native int getInt(int sa_idx);
public int getInt(int sa_idx1, int sa_idx2);
public void getInts(int sa_idx, int nelems, int ja[],
int ja_start);
public int getLBound();
public int getLBound(int dim);
public int getNumDim();
public int getNumLocks();
public short getShort(int sa_idx);
public short getShort(int sa_idx1, int sa_idx2);
public void getShorts(int sa_idx, int nelems, short ja[],
int ja_start);
public String getString(int sa_idx);
public String getString(int sa_idx1, int sa_idx2);
public void getStrings(int sa_idx, int nelems, String ja[],
int ja_start);
public int getUBound();
public int getUBound(int dim);
public Variant getVariant(int sa_idx);
public Variant getVariant(int sa_idx1, int sa_idx2);
public void getVariants(int sa_idx, int nelems, Variant ja[], int
ja_start);
public int getvt();
public void reinit(SafeArray sa);
public void reinterpretType(int vt);
public native void setBoolean(int idx, boolean val);
public void setBoolean(int idx1, int idx2, boolean val);
public void setBooleans(int sa_idx, int nelems, boolean ja[], int
ja_start);
public void setByte(int idx, byte val);
public void setByte(int idx1, int idx2, byte val);
public void setBytes(int sa_idx, int nelems, byte ja[],
int ja_start);
public void setChar(int idx, char val);
public void setChar(int idx1, int idx2, char val);
public void setChars(int sa_idx, int nelems, char ja[],
int ja_start);
public native void setDouble(int idx, double val);
public void setDouble(int idx1, int idx2, double val);
public void setDoubles(int sa_idx, int nelems, double ja[],
int ja_start);
public native void setFloat(int idx, float val);
public void setFloat(int idx1, int idx2, float val);
public void setFloats(int sa_idx, int nelems, float ja[],
int ja_start);
public native void setInt(int idx, int val);
public void setInt(int idx1, int idx2, int val);
public void setInts(int sa_idx, int nelems, int ja[],
int ja_start);
public void setShort(int idx, short val);
public void setShort(int idx1, int idx2, short val);
public void setShorts(int sa_idx, int nelems, short ja[],
int ja_start);
public void setString(int idx, String val);
public void setString(int idx1, int idx2, String val);
public void setStrings(int sa_idx, int nelems, String ja[],
int ja_start);
public void setVariant(int idx, Variant val);
public void setVariant(int idx1, int idx2, Variant val);
public void setVariants(int sa_idx, int nelems, Variant ja[], int
ja_start);
public boolean[] toBooleanArray();
public byte[] toByteArray();
public char[] toCharArray();
public double[] toDoubleArray();
public float[] toFloatArray();
public int[] toIntArray();
public short[] toShortArray();
public String toString();
public String[] toStringArray();
public Variant[] toVariantArray();
}

This class wraps a Microsoft® ActiveX® Automation SAFEARRAY data structure. It bridges Java with the Automation object by wrapping a pointer to the native SAFEARRAY data structure. It does not duplicate the array data in Java form. This approach minimizes translation overhead but imposes extra rules on SafeArray usage.

The rules for using this class are simple, but they must be followed:

1. A Java method that receives a SafeArray object as a parameter can use that object only for the duration of the method call. If a longer-term copy is needed, either the SafeArray object must be converted to a Java array, or the clone method must be used to create an independent copy of the object.

2. If a Java method returns a SafeArray object, that object is owned by the caller; the Java method must no longer use that SafeArray instance. The simplest way to follow this rule is to have the called method construct a new SafeArray object each time it is called.

In addition to maintaining a pointer to a native SAFEARRAY data structure, a SafeArray instance separately maintains the exact variant type of SAFEARRAY data structure elements. The variant type is determined by an argument to the SafeArray class constructor or is bound into the .java file by the jactivex tool. The system class com.ms.com.Variant defines public constants (Variant.VariantXXX) for all of the valid variant types. It is important to note that neither the VariantByref nor the VariantArray modifier should be set in the element variant type; setting either of these modifiers will cause a run-time error to occur.

The SAFEARRAY data structure does not have reference counts, so the process of creating and destroying SAFEARRAY data structures cannot be made completely transparent to the Java programmer. Therefore, the SafeArray class can only be loaded by a trusted applet.

SafeArrays of type VT_UNKNOWN or VT_DISPATCH can be manipulated by using variant-typed manipulators and then extracting the COM object from the variant, as in the following example.

   SafeArray sa;
Object elem = sa.getVariant(index).toObject();

However, support for this technique is limited to cases where the variant was obtained from an object whose threading model is either free or both. In most other cases, a WrongThreadException is thrown. The conflicting requirements of COM's apartment threading model and Java's non-message-based model preclude an efficient representation of SafeArrays of Objects.

Note for JavaTLB users: The JavaTLB tool (which has been superceded by the jactivex tool) emits an older class file format that does not provide the exact variant type. This means in some cases, the SAFEARRAY data structure will not provide enough information to determine an exact variant type. In this case, the Java runtime will choose a default variant type based on the following heuristics:

• SAFEARRAY data structures with elements of type VT_BSTR, VT_UNKNOWN, VT_DISPATCH or VT_VARIANT are explicitly flagged as such in the SAFEARRAY data structure; thus, these will always marshal correctly.

• If not explicitly flagged, a SAFEARRAY data structure whose element size is 1 is presumed to be of type VT_UI1. Similarly, if the element size is 2, the SAFEARRAY is presumed to be of type VT_I2. If the element size is 4, type VT_I4 is presumed, and if the element size is 8, VT_R8 is presumed. Otherwise, a ClassCastException is thrown.

• If a variant type other than the default is needed, the interface .java files must either be rebuilt using the jactivex tool or the reinterpretType method must be used to override the default variant type.

### Constructors

#### SafeArray

public SafeArray(int vt);

Creates a SafeArray instance that wraps the NULL pointer. The main purpose of this constructor is to pass NULL to Component Object Model (COM) methods that accept SAFEARRAYs.

The variant type of the element must be one of the Variant.VariantXXX constants. Neither the VariantByref nor the VariantArray modifier should be set in the element variant type; setting either of these modifiers will cause a run-time error to occur.

 Parameter Description vt The variant type of the element.

#### SafeArray

public SafeArray(int vt, int celems);

Creates a one-dimensional SafeArray object. Valid indices range from zero (inclusive) to celems (exclusive). Note that this convention follows the C language practice of indicating the number of elements rather than the Microsoft® Visual Basic® convention of indicating the upper bound.

The variant type of the element must be one of the Variant.VariantXXX constants. Neither the VariantArray nor the VariantByref modifier may be set.

 Parameter Description vt The variant type of the element. celems The number of elements.

#### SafeArray

public SafeArray(int vt, int celems1, int celems2);

Creates a two-dimensional SafeArray object. The constructor follows the C language practice of indicating the number of elements rather than the Microsoft® Visual Basic® convention of indicating the upper bound.

The expression:

new SafeArray(Variant.VariantVariant, 21, 11);

is equivalent to the Visual Basic declaration:

Option Base 0
Dim A(20, 10)

The variant type of the element must be one of the Variant.VariantXXX constants. Neither the VariantByref nor the VariantArray modifier should be set in the element variant type; setting either of these modifiers will cause a run-time error to occur.

 Parameter Description vt The variant type of the element. celems1 The number of elements in the first dimension. celems2 The number of elements in the second dimension.

#### SafeArray

public SafeArray(int vt, int lbounds[], int celems[]);

Creates a SafeArray object of arbitrary shape. The lbounds array indicates the lower bound of each dimension. The celems array (which must have the same length as lbounds) gives the number of elements that are in each dimension. If lbounds is null, all the lower bound values default to zero. The variant type of the element must be one of the Variant.VariantXXX constants. Neither the VariantArray nor VariantByref modifier may be set.

The following Java code creates a 3-dimensional SafeArray:

int lbounds[] = {-1,-3, -4};
int celems[] = {10, 20, 30};
SafeArray A = new SafeArray(Variant.VariantVariant, lbounds,
celems);

This Visual Basic declaration creates an array with the same shape as the SafeArray created above:

Dim A(-1 To 8, -3 To 16, -4 To 25)
 Parameter Description vt The variant type of the element. lbounds The lower bounds of each dimension. celems The number of elements in each dimension.

#### SafeArray

public SafeArray(String s);

Creates a VT_UI1 SafeArray object from a string. Each character of the string occupies two elements of the array to form a single Unicode character. The array is not null terminated. This constructor corresponds to the standard Automation conversion from VT_BSTR to VT_ARRAY|VT_UI1.

 Parameter Description s The string used to initialize the new SafeArray object.

#### getPhysicalSafeArray

public native int getPhysicalSafeArray();

Retrieves the linear address of the actual SAFEARRAY data structure, which is packaged as a Java integer. This method is provided only to aid in debugging. Other than displaying information, there are no useful operations that can be performed with this value from Java.

Return Value:

Returns the linear address of the represented SAFEARRAY.

### Methods

#### asString

public native String asString();

Converts a VT_UI1 SafeArray to a string. This method corresponds to the VariantChangeType conversion from VT_ARRAY|VT_UI1 to VT_BSTR.

Return Value:

Returns the converted value.

#### clone

public Object clone();

Creates an exact and independent duplicate of the SafeArray object. This method is a wrapper around the Microsoft® Win32® SafeArrayCopy function.

Return Value:

Returns a new SafeArray object that contains an independent duplicate.

#### destroy

public void destroy();

Forcefully invokes the Win32 function SafeArrayDestroy.

Caution This is a potentially dangerous routine that should be used with extreme caution. It is not necessary to invoke this method when following standard COM memory ownership rules. This is because the Java/COM integration subsystem and the Java garbage collector work together to ensure correct disposal of SafeArrays.

Return Value:

No return value.

#### finalize

protected void finalize();

Performs cleanup tasks before garbage collection.

Return Value:

No return value.

#### fromBooleanArray

public void fromBooleanArray(boolean ja[]);

Initializes SafeArray elements from a Java array. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter what the index of the lower bound of the SafeArray is, the first element is initialized from element zero of the Java array.

If the Java array is shorter than the number of SafeArray elements, the remaining SafeArray elements are left unmodified. If the Java array is longer than the number of SafeArray elements, the extra elements are ignored.

Note If you are modifying a large number of elements, it may be more efficient to use fromCharArray rather than fromBooleanArray. Since boolean SafeArrays use two bytes per element, the fromBooleanArray method cannot optimize itself to a memory copy (memcpy).

Return Value:

No return value.

 Parameter Description ja The Java array that contains the new values.

#### fromByteArray

public void fromByteArray(byte ja[]);

Initializes SafeArray elements from a Java array. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter what the index of the lower bound of the SafeArray is, the first element is initialized from element zero of the Java array.

If the Java array is shorter than the number of SafeArray elements, the remaining SafeArray elements are left unmodified. If the Java array is longer than the number of SafeArray elements, the extra elements are ignored.

Note This method attempts all the usual type conversions. To achieve optimal performance, ensure that the element size of the source and destination arrays match exactly, so that the method optimizes to a straight memory copy (memcpy).

Return Value:

No return value.

 Parameter Description ja The Java array that contains the new values.

#### fromCharArray

public void fromCharArray(char ja[]);

Initializes SafeArray elements from a Java array. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter what the index of the lower bound of the SafeArray is, the first element is initialized from element zero of the Java array.

If the Java array is shorter than the number of SafeArray elements, the remaining SafeArray elements are left unmodified. If the Java array is longer than the number of SafeArray elements, the extra elements are ignored.

Note This method attempts all the usual type conversions. To achieve optimal performance, ensure that the element size of the source and destination arrays match exactly, so that the method optimizes to a straight memory copy (memcpy).

Return Value:

No return value.

 Parameter Description ja The Java array that contains the new values.

#### fromDoubleArray

public void fromDoubleArray(double ja[]);

Initializes SafeArray elements from a Java array. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter what the index of the lower bound of the SafeArray is, the first element is initialized from element zero of the Java array.

If the Java array is shorter than the number of SafeArray elements, the remaining SafeArray elements are left unmodified. If the Java array is longer than the number of SafeArray elements, the extra elements are ignored.

Note This method attempts all the usual type conversions. To achieve optimal performance, ensure that the element size of the source and destination arrays match exactly so that the method optimizes to a straight memory copy (memcpy).

Return Value:

No return value.

 Parameter Description ja The Java array that contains the new values.

#### fromFloatArray

public void fromFloatArray(float ja[]);

Initializes SafeArray elements from a Java array. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter what the index of the lower bound of the SafeArray is, the first element is initialized from element zero of the Java array.

If the Java array is shorter than the number of SafeArray elements, the remaining SafeArray elements are left unmodified. If the Java array is longer than the number of SafeArray elements, the extra elements are ignored.

Note This method attempts all the usual type conversions. To achieve optimal performance, ensure that the element size of the source and destination arrays match exactly so that the method optimizes to a straight memory copy (memcpy).

Return Value:

No return value.

 Parameter Description ja The Java array that contains the new values.

#### fromIntArray

public void fromIntArray(int ja[]);

Initializes SafeArray elements from a Java array. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter what the index of the lower bound of the SafeArray is, the first element is initialized from element zero of the Java array.

If the Java array is shorter than the number of SafeArray elements, the remaining SafeArray elements are left unmodified. If the Java array is longer than the number of SafeArray elements, the extra elements are ignored.

Note This method attempts all the usual type conversions. To achieve optimal performance, ensure that the element size of the source and destination arrays match exactly, so that the method optimizes to a straight memory copy (memcpy).

Return Value:

No return value.

 Parameter Description ja The Java array that contains the new values.

#### fromShortArray

public void fromShortArray(short ja[]);

Initializes SafeArray elements from a Java array. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter what the index of the lower bound of the SafeArray is, the first element is initialized from element zero of the Java array.

If the Java array is shorter than the number of SafeArray elements, the remaining SafeArray elements are left unmodified. If the Java array is longer than the number of SafeArray elements, the extra elements are ignored.

Note This method attempts all the usual type conversions. To achieve optimal performance, ensure that the element size of the source and destination arrays match exactly so that the method optimizes to a straight memory copy (memcpy).

Return Value:

No return value.

 Parameter Description ja The Java array that contains the new values.

#### fromStringArray

public void fromStringArray(String ja[]);

Initializes SafeArray elements from a Java array. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter what the index of the lower bound of the SafeArray is, the first element is initialized from element zero of the Java array.

If the Java array is shorter than the number of SafeArray elements, the remaining SafeArray elements are left unmodified. If the Java array is longer than the number of SafeArray elements, the extra elements are ignored.

Return Value:

No return value.

 Parameter Description ja The Java array that contains the new values.

#### fromVariantArray

public void fromVariantArray(Variant ja[]);

Initializes SafeArray elements from a Java array. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter what the index of the lower bound of the SafeArray is, the first element is initialized from element zero of the Java array.

If the Java array is shorter than the number of SafeArray elements, the remaining SafeArray elements are left unmodified. If the Java array is longer than the number of SafeArray elements, the extra elements are ignored.

Note Although Variant methods can operate on any SafeArray type, it is usually much more efficient to use the specific method for the element type. This is true even if the SafeArray is a SafeArray of Variants.

Return Value:

No return value.

 Parameter Description ja The Java array that contains the new values.

#### getBoolean

public native boolean getBoolean(int sa_idx);

Extracts an element of a one-dimensional SafeArray as a boolean.

Return Value:

Returns the converted element value.

 Parameter Description sa_idx The element index, which ranges from the index of the lower bound to the index of the upper bound.

Exceptions:

IndexOutOfBoundsException if the SafeArray is not one-dimensional or if sa_idx is not between the lower bound and the upper bound of the array (inclusive).

ClassCastException if the SafeArray element cannot be converted to the correct type by using the Win32 VariantChangeType function.

#### getBoolean

public boolean getBoolean(int sa_idx1, int sa_idx2);

Extracts an element of a two-dimensional SafeArray as a boolean.

Return Value:

Returns the converted element value.

 Parameter Description sa_idx1 The first dimension index of the element that is extracted, which ranges from LBound(1) to UBound(1). sa_idx2 The second dimension index of the element that is extracted, which ranges from LBound(2) to UBound(2).

Exceptions:

IndexOutOfBoundsException if the SafeArray is not two-dimensional or if neither index is between the lower bound and the upper bound of the array (inclusive).

ClassCastException if the SafeArray element cannot be converted to the correct type by using the Win32 VariantChangeType function.

#### getBooleans

public void getBooleans(int sa_idx, int nelems, boolean ja[], int ja_start);

Extracts multiple elements as booleans. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter where in the SafeArray the first element is located, that location is called index zero for the purposes of this method. The first element retrieved from the SafeArray is retrieved from the location that is sa_idx elements away from index zero.

Note If you extract a large number of elements, it may be more efficient to use getChars rather than getBooleans. Since boolean SafeArray objects use two bytes per element, the getBooleans method cannot optimize itself to a memory copy (memcpy).

Return Value:

No return value.

 Parameter Description sa_idx The index of the first element to retrieve. This index is always zero-based. nelems The number of elements to retrieve. ja The Java array that receives the values. ja_start The index of the first element in ja that receives a value.

#### getByte

public byte getByte(int sa_idx);

Extracts an element of a one-dimensional SafeArray as a byte.

Return Value:

Returns the converted element value.

 Parameter Description sa_idx The element index, which ranges from the index of the lower bound to the index of the upper bound.

Exceptions:

IndexOutOfBoundsException if the SafeArray is not one-dimensional or if sa_idx lies outside the defined range (LBound() to UBound()).

ClassCastException if the SafeArray element cannot be converted to the correct type by using the Win32 VariantChangeType function.

#### getByte

public byte getByte(int sa_idx1, int sa_idx2);

Extracts an element of a two-dimensional SafeArray as a byte.

Return Value:

Returns the converted element value.

 Parameter Description sa_idx1 The first dimension index of the element that is extracted, which ranges from LBound(1) to UBound(1). sa_idx2 The second dimension index of the element that is extracted, which ranges from LBound(2) to UBound(2).

Exceptions:

IndexOutOfBoundsException if the SafeArray is not two-dimensional or if either index lies outside the defined range.

ClassCastException if the SafeArray element cannot be converted to the correct type by using the Win32 VariantChangeType function.

#### getBytes

public void getBytes(int sa_idx, int nelems, byte ja[], int ja_start);

Extracts multiple elements as bytes. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter where in the SafeArray the first element is located, that location is called index zero for the purposes of this method. The first element retrieved from the SafeArray is retrieved from the location that is sa_idx elements away from index zero.

Note This method attempts all the usual type conversions. To achieve optimal performance, ensure that the element size of the source and destination arrays match exactly, so that the method optimizes to a straight memory copy (memcpy).

Return Value:

No return value.

 Parameter Description sa_idx The index of the first element to retrieve. This index is always zero-based. nelems The number of elements to retrieve. ja Java The array that receives the values. ja_start The index of the first element in ja that receives a value.

#### getChar

public char getChar(int sa_idx);

Extracts an element of a one-dimensional SafeArray as a character.

Return Value:

Returns the converted element value.

 Parameter Description sa_idx The element index, which ranges from the index of the lower bound to the index of the upper bound.

Exceptions:

IndexOutOfBoundsException if the SafeArray is not one-dimensional or if sa_idx lies outside the defined range (LBound() to UBound()).

ClassCastException if the SafeArray element cannot be converted to the correct type by using the Win32 VariantChangeType function.

#### getChar

public char getChar(int sa_idx1, int sa_idx2);

Extracts an element of a two-dimensional array as a character.

Return Value:

Returns the converted element value.

 Parameter Description sa_idx1 The first dimension index of the element that is extracted, which ranges from LBound(1) to UBound(1). sa_idx2 The second dimension index of the element that is extracted, which ranges from LBound(2) to UBound(2).

Exceptions:

IndexOutOfBoundsException if the array is not two-dimensional or if either index lies outside the defined range.

ClassCastException if the SafeArray element cannot be converted to the correct type by using the Win32 VariantChangeType function.

#### getChars

public void getChars(int sa_idx, int nelems, char ja[], int ja_start);

Extracts multiple elements of a SafeArray as characters. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter where in the SafeArray the first element is located, that location is called index zero for the purposes of this method. The first element retrieved from the SafeArray is retrieved from the location that is sa_idx elements away from index zero.

Note This method attempts all the usual type conversions. To achieve optimal performance, ensure that the element size of the source and destination arrays match exactly, so that the method optimizes to a straight memory copy (memcpy).

Return Value:

No return value.

 Parameter Description sa_idx The index of the first element to retrieve. This index is always zero-based. nelems The number of elements to retrieve. ja The Java array that receives the values. ja_start The index of the first element in ja that receives a value.

#### getDouble

public native double getDouble(int sa_idx);

Extracts an element of a one-dimensional SafeArray as a double.

Return Value:

Returns the converted element value.

 Parameter Description sa_idx The element index, which ranges from the index of the lower bound to the index of the upper bound.

Exceptions:

IndexOutOfBoundsException if the array is not one-dimensional or if sa_idx lies outside the defined range (LBound() to UBound()).

ClassCastException if the SafeArray element cannot be converted to the correct type by using the Win32 VariantChangeType function.

#### getDouble

public double getDouble(int sa_idx1, int sa_idx2);

Extracts an element of a two-dimensional SafeArray as a double.

Return Value:

Returns the converted element value.

 Parameter Description sa_idx1 The first dimension index of the element that is extracted, which ranges from LBound(1) to UBound(1). sa_idx2 The second dimension index of the element that is extracted, which ranges from LBound(2) to UBound(2).

Exceptions:

IndexOutOfBoundsException if the array is not two-dimensional or if either index lies outside the defined range.

ClassCastException if the SafeArray element cannot be converted to the correct type by using the Win32 VariantChangeType function.

#### getDoubles

public void getDoubles(int sa_idx, int nelems, double ja[], int ja_start);

Extracts multiple elements of a SafeArray as doubles. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter where in the SafeArray the first element is located, that location is called index zero for the purposes of this method. The first element retrieved from the SafeArray is retrieved from the location that is sa_idx elements away from index zero.

Note This method attempts all the usual type conversions. To achieve optimal performance, ensure that the element size of the source and destination arrays match exactly, so that the method optimizes to a straight memory copy (memcpy).

Return Value:

No return value.

 Parameter Description sa_idx The index of the first element to retrieve. This index is always zero-based. nelems The number of elements to retrieve. ja The Java array that receives the values. ja_start The index of the first element in ja that receives a value.

#### getElemSize

public int getElemSize();

Retrieves the size of a single element.

Return Value:

Returns the size of a single element, measured in bytes.

#### getFeatures

public int getFeatures();

Retrieves the contents of the fFeatures bitmask. This bitmask (defined as part of the OLE SAFEARRAY data structure) provides various types of information about the SAFEARRAY.

Return Value:

Returns the fFeatures field.

#### getFloat

public native float getFloat(int sa_idx);

Extracts an element of a one-dimensional SafeArray as a float.

Return Value:

Returns the converted element value.

 Parameter Description sa_idx The element index, which ranges from the index of the lower bound to the index of the upper bound.

Exceptions:

IndexOutOfBoundsException if the array is not one-dimensional or if sa_idx lies outside the defined range (LBound()..UBound()).

ClassCastException if the SafeArray element cannot be converted to the correct type by using the Win32 VariantChangeType function.

#### getFloat

public float getFloat(int sa_idx1, int sa_idx2);

Extracts an element of a two-dimensional SafeArray as a float.

Return Value:

Returns the converted element value.

 Parameter Description sa_idx1 The first dimension index of the element that is extracted, which ranges from LBound(1) to UBound(1). sa_idx2 The second dimension index of the element that is extracted, which ranges from LBound(2) to UBound(2).

Exceptions:

IndexOutOfBoundsException if the SafeArray is not two-dimensional or if either index lies outside the defined range.

ClassCastException if the SafeArray element cannot be converted to the correct type by using the Win32 VariantChangeType function.

#### getFloats

public void getFloats(int sa_idx, int nelems, float ja[], int ja_start);

Extracts multiple elements of a SafeArray as floats. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter where in the SafeArray the first element is located, that location is called index zero for the purposes of this method. The first element retrieved from the SafeArray is retrieved from the location that is sa_idx elements away from index zero.

Note This method attempts all the usual type conversions. To achieve optimal performance, ensure that the element size of the source and destination arrays match exactly, so that the method optimizes to a straight memory copy (memcpy).

Return Value:

No return value.

 Parameter Description sa_idx The index of the first element to retrieve. This index is always zero-based. nelems The number of elements to retrieve. ja The Java array that receives the values. ja_start The index of the first element in ja that receives a value.

#### getInt

public native int getInt(int sa_idx);

Extracts an element of a one-dimensional SafeArray as an integer.

Return Value:

Returns the converted element value.

 Parameter Description sa_idx The element index, which ranges from the index of the lower bound to the index of the upper bound.

Exceptions:

ClassCastException if the SafeArray element cannot be converted to the correct type using the Win32 VariantChangeType function.

IndexOutOfBoundsException if the array is not one-dimensional or if sa_idx lies outside the defined range (LBound() to UBound()).

#### getInt

public int getInt(int sa_idx1, int sa_idx2);

Extracts an element of a two-dimensional array as an integer.

Return Value:

Returns the converted element value.

 Parameter Description sa_idx1 The first dimension index of the element that is extracted, which ranges from LBound(1) to UBound(1). sa_idx2 The second dimension index of the element that is extracted, which ranges from LBound(2) to UBound(2).

Exceptions:

ClassCastException if the SafeArray element cannot be converted to the correct type by using the Win32 VariantChangeType function.

IndexOutOfBoundsException if the array is not two-dimensional or if either index lies outside the defined range.

#### getInts

public void getInts(int sa_idx, int nelems, int ja[], int ja_start);

Extracts multiple elements of the SafeArray as integers. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter where in the SafeArray the first element is located, that location is called index zero for the purposes of this method. The first element retrieved from the SafeArray is retrieved from the location that is sa_idx elements away from index zero.

Note This method attempts all the usual type conversions. To achieve optimal performance, ensure that the element size of the source and destination arrays match exactly, so that the method optimizes to a straight memory copy (memcpy).

Return Value:

No return value.

 Parameter Description sa_idx The index of the first element to retrieve. This index is always zero-based. nelems The number of elements to retrieve. ja The Java array that receives the values. ja_start The index of the first element in ja that receives a value.

#### getLBound

public int getLBound();

Retrieves the smallest valid index of the array's first dimension. This method is identical to the Visual Basic LBound function.

Return Value:

Returns the smallest valid index.

#### getLBound

public int getLBound(int dim);

Retrieves the smallest valid index of an arbitrary dimension. (Dimensions are numbered, starting with 1.) This method is identical to the Visual Basic LBound function.

Return Value:

Returns the smallest valid index.

 Parameter Description dim The dimension.

#### getNumDim

public int getNumDim();

Obtains the number of SafeArray dimensions.

Return Value:

Returns the number of dimensions in the SafeArray (2 for two-dimensional SafeArrays, for example).

#### getNumLocks

public int getNumLocks();

Retrieves the number of outstanding locks on the SafeArray object. This value (which is usually zero) is only useful for debugging purposes.

Return Value:

Returns the outstanding lock count.

#### getShort

public short getShort(int sa_idx);

Extracts an element of a one-dimensional SafeArray as a short integer.

Return Value:

Returns the converted element value.

 Parameter Description sa_idx The element index, which ranges from the index of the lower bound to the index of the upper bound.

Exceptions:

IndexOutOfBoundsException if the array is not one-dimensional or if sa_idx lies outside the defined range (LBound() to UBound()).

ClassCastException if the SafeArray element cannot be converted to the correct type by using the Win32 VariantChangeType function.

#### getShort

public short getShort(int sa_idx1, int sa_idx2);

Extracts an element of a two-dimensional SafeArray as a short integer.

Return Value:

Returns the converted element value.

 Parameter Description sa_idx1 The first dimension index of the element that is extracted, which ranges from LBound(1) to UBound(1). sa_idx2 The second dimension index of the element that is extracted, which ranges from LBound(2) to UBound(2).

Exceptions:

IndexOutOfBoundsException if the array is not two-dimensional or if either index lies outside the defined range.

ClassCastException if the SafeArray element cannot be converted to the correct type by using the Win32 VariantChangeType function.

#### getShorts

public void getShorts(int sa_idx, int nelems, short ja[], int ja_start);

Extracts multiple elements as short integers. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter where in the SafeArray the first element is located, that location is called index zero for the purposes of this method. The first element retrieved from the SafeArray is retrieved from the location that is sa_idx elements away from index zero.

Note This method attempts all the usual type conversions. To achieve optimal performance, ensure that the element size of the source and destination arrays match exactly, so that the method optimizes to a straight memory copy (memcpy).

Return Value:

No return value.

 Parameter Description sa_idx The index of the first element to retrieve. This index is always zero-based. nelems The number of elements to retrieve. ja The Java array that receives the values. ja_start The index of the first element in ja that receives a value.

#### getString

public String getString(int sa_idx);

Extracts an element of a one-dimensional SafeArray as a string.

Return Value:

Returns the converted element value.

 Parameter Description sa_idx The element index, which ranges from the index of the lower bound to the index of the upper bound.

Exceptions:

IndexOutOfBoundsException if the array is not one-dimensional or if sa_idx does not lie between the lower bound and the upper bound of the array (inclusive).

ClassCastException if the SafeArray element cannot be converted to the correct type by using the Win32 VariantChangeType function.

#### getString

public String getString(int sa_idx1, int sa_idx2);

Extracts an element of a two-dimensional SafeArray as a string.

Return Value:

Returns the converted element value.

 Parameter Description sa_idx1 The first dimension index of the element that is extracted, which ranges from LBound(1) to UBound(1). sa_idx2 The second dimension index of the element that is extracted, which ranges from LBound(2) to UBound(2).

Exceptions:

IndexOutOfBoundsException if the array is not two-dimensional or if either index does not lie between the lower bound and the upper bound of the array (inclusive).

ClassCastException if the SafeArray element cannot be converted to the correct type by using the Win32 VariantChangeType function.

#### getStrings

public void getStrings(int sa_idx, int nelems, String ja[], int ja_start);

Extracts multiple elements of a SafeArray as strings. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter where in the SafeArray the first element is located, that location is called index zero for the purposes of this method. The first element retrieved from the SafeArray is retrieved from the location that is sa_idx elements away from index zero.

Return Value:

No return value.

 Parameter Description sa_idx The index of the first element to retrieve. This index is always zero-based. nelems The number of elements to retrieve. ja The Java array that receives the values. ja_start The index of the first element in ja that receives a value.

#### getUBound

public int getUBound();

Returns the largest valid index of the array's first dimension. This method is identical to the Microsoft® Visual Basic® UBound function.

Return Value:

Returns the largest valid index.

#### getUBound

public int getUBound(int dim);

Retrieves the largest valid index of an arbitrary dimension. (Dimensions are numbered starting with 1.) This method is identical to the Visual Basic UBound function.

Return Value:

Returns the largest valid index.

 Parameter Description dim The dimension.

#### getVariant

public Variant getVariant(int sa_idx);

Extracts an element of a one-dimensional SafeArray as a Variant.

Note Although the Variant methods can operate on any SafeArray type, it is usually much more efficient to use the specific method for the SafeArray type rather than to extract first as a Variant,and then to coerce the Variant. This is true even if the SafeArray is a SafeArray of Variant.

Return Value:

Returns the converted element value.

 Parameter Description sa_idx The element index, which ranges from the index of the lower bound to the index of the upper bound.

Exceptions:

IndexOutOfBoundsException if the array is not one-dimensional or if sa_idx does not lie between the lower bound of the array and the upper bound of the array (inclusive).

ClassCastException if the SafeArray element cannot be converted to the correct type by using the Win32 VariantChangeType function.

#### getVariant

public Variant getVariant(int sa_idx1, int sa_idx2);

Extracts an element of a two-dimensional SafeArray as a Variant.

Note Although the Variant methods can operate on any SafeArray type, it is usually much more efficient to use the specific method for the SafeArray type rather than to extract first as a Variant, and then to coerce the Variant. This is true even if the SafeArray is a SafeArray of Variants.

Return Value:

Returns the converted element value.

 Parameter Description sa_idx1 The first dimension index of the element that is extracted, which ranges from LBound(1) to UBound(1). sa_idx2 The second dimension index of the element that is extracted, which ranges from LBound(2) to UBound(2).

Exceptions:

IndexOutOfBoundsException if the array is not two-dimensional or if either index lies outside the defined range.

ClassCastException if the SafeArray element cannot be converted to the correct type by using the Win32 VariantChangeType function.

#### getVariants

public void getVariants(int sa_idx, int nelems, Variant ja[], int ja_start);

Extracts multiple elements as Variant objects. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter where in the SafeArray the first element is located, that location is called index zero for the purposes of this method. The first element retrieved from the SafeArray is retrieved from the location that is sa_idx elements away from index zero.

Note Although the Variant methods can operate on any SafeArray type, it is usually much more efficient to use the specific method for the SafeArray type rather than to extract first as a Variant, and then to coerce the Variant. This is true even if the SafeArray is a SafeArray of Variants.

Return Value:

No return value.

 Parameter Description sa_idx The index of the first element to retrieve. This index is always zero-based. nelems The number of elements to retrieve. ja The Java array that receives the values. ja_start The index of the first element in ja that receives a value.

#### getvt

public int getvt();

Retrieves the variant type of the SafeArray elements. This corresponds to a public constant, com.ms.com.VariantXXX.

Note If JavaTLB is used to generate the Java method information that passes a SafeArray from COM to Java, the variant type may be inexact. (The element size, however, will always be correct.) JavaTLB has been superceded by the jactivex tool, which binds the exact variant type into the .class file.

Return Value:

Returns the variant type of the element.

#### reinit

public void reinit(SafeArray sa);

Reinitializes the SafeArray object.

Return Value:

No return value.

 Parameter Description sa The SafeArray object that is reinitialized.

#### reinterpretType

public void reinterpretType(int vt);

Forces the SafeArray to interpret elements as another variant type.

Return Value:

No return value.

 Parameter Description vt The new variant type of the element.

#### setBoolean

public native void setBoolean(int idx, boolean val);

Sets an element of a one-dimensional SafeArray.

Return Value:

No return value.

 Parameter Description idx The element index, which ranges from index of the lower bound to the index of the upper bound. val The new element value.

Exceptions:

IndexOutOfBoundsException if the array is not one-dimensional or if idx does not lie between the lower bound and the upper bound of the SafeArray (inclusive).

ClassCastException if the Java value cannot be converted to the SafeArray element type using the Win32 VariantChangeType function.

#### setBoolean

public void setBoolean(int idx1, int idx2, boolean val);

Sets an element of a two-dimensional SafeArray.

Return Value:

No return value.

 Parameter Description idx1 The first dimension index of the element to set, which ranges from LBound(1) to UBound(1). idx2 The second dimension index of the element to set, which ranges from LBound(2) to UBound(2). val The new element value.

Exceptions:

IndexOutOfBoundsException if the SafeArray is not two-dimensional or if either index lies outside the defined range.

ClassCastException if the Java value cannot be converted to the SafeArray element type using the Win32 VariantChangeType function.

#### setBooleans

public void setBooleans(int sa_idx, int nelems, boolean ja[], int ja_start);

Sets multiple elements of a SafeArray. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter where in the SafeArray the first element is located, that location is called index zero for the purposes of this method. The first element to be set in the SafeArray is located sa_idx elements away from index zero.

Note If you are modifying a large number of elements, it may be more efficient to use setChars rather than setBooleans. Since boolean SafeArrays use two bytes per element, the setBooleans method cannot optimize itself to a memory copy (memcpy).

Return Value:

No return value.

 Parameter Description sa_idx The index of the first element to set. This index is always zero-based. nelems The number of elements to set. ja The Java array that contains the new values. ja_start The index of first element in ja to use.

#### setByte

public void setByte(int idx, byte val);

Sets an element of a one-dimensional SafeArray.

Return Value:

No return value.

 Parameter Description idx The index of the element to set, which ranges from the lower bound to the upper bound of the SafeArray. val The new element value.

Exceptions:

IndexOutOfBoundsException if the array is not one-dimensional or if idx does not lie between the lower bound and the upper bound of the SafeArray (inclusive).

ClassCastException if the Java value cannot be converted to the SafeArray element type by using the Win32 VariantChangeType function.

#### setByte

public void setByte(int idx1, int idx2, byte val);

Sets an element of a two-dimensional SafeArray.

Return Value:

No return value.

 Parameter Description idx1 The first dimension index of the element to set, which ranges from LBound(1) to UBound(1). idx2 The second dimension index of the element to set, which ranges from LBound(2) to UBound(2). val The new element value.

Exceptions:

IndexOutOfBoundsException if the array is not two-dimensional or if either index lies outside the defined range.

ClassCastException if the Java value cannot be converted to the SafeArray element type by using the Win32 VariantChangeType function.

#### setBytes

public void setBytes(int sa_idx, int nelems, byte ja[], int ja_start);

Sets multiple elements of a SafeArray. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter where in the SafeArray the first element is located, that location is called index zero for the purposes of this method. The first element to be set in the SafeArray is located sa_idx elements away from index zero.

Note This method attempts all the usual type conversions. To achieve optimal performance, ensure that the element size of the source and destination arrays match exactly, so that the method optimize to a straight memory copy (memcpy).

Return Value:

No return value.

 Parameter Description sa_idx The index of the first element to set. This index is always zero-based. nelems The number of elements to set. ja The Java array that contains the new values. ja_start The index of the first element in ja to use.

#### setChar

public void setChar(int idx, char val);

Sets an element of a one-dimensional SafeArray.

Return Value:

No return value.

 Parameter Description idx The index of the element to set, which ranges from the lower bound to the upper bound of the SafeArray. val The new element value.

Exceptions:

IndexOutOfBoundsException if the SafeArray is not one-dimensional or if idx does not lie between the lower bound and the upper bound of the SafeArray (inclusive).

ClassCastException if the Java value cannot be converted to the SafeArray element type by using the Win32 VariantChangeType function.

#### setChar

public void setChar(int idx1, int idx2, char val);

Sets an element of a two-dimensional SafeArray.

Return Value:

No return value.

 Parameter Description idx1 The first dimension index of the element to set, which ranges from LBound(1) to UBound(1). idx2 The second dimension index of the element to set, which ranges from LBound(2) to UBound(2). val The new element value.

Exceptions:

IndexOutOfBoundsException if the SafeArray is not two-dimensional or if either index lies outside the defined range.

ClassCastException if the Java value cannot be converted to the SafeArray element type by using the Win32 VariantChangeType function.

#### setChars

public void setChars(int sa_idx, int nelems, char ja[], int ja_start);

Sets multiple elements. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter where in the SafeArray the first element is located, that location is called index zero for the purposes of this method. The first element to be set in the SafeArray is located sa_idx elements away from index zero.

Note This method attempts all the usual type conversions. To achieve optimal performance, ensure that the element size of the source and destination arrays match exactly, so that the method optimizes to a straight memory copy (memcpy).

Return Value:

No return value.

 Parameter Description sa_idx The index of the first element to set. This index is always zero-based. nelems The number of elements to set. ja The Java array that contains the new values. ja_start The index of the first element in ja that is used.

#### setDouble

public native void setDouble(int idx, double val);

Sets an element of a one-dimensional SafeArray.

Return Value:

No return value.

 Parameter Description idx The element index, which ranges from the lower bound to the upper bound of the SafeArray. val The new element value.

Exceptions:

IndexOutOfBoundsException if the SafeArray is not one-dimensional or if idx does not lie between the lower bound and the upper bound of the SafeArray (inclusive).

ClassCastException if the Java value cannot be converted to the SafeArray element type using the Win32 VariantChangeType function.

#### setDouble

public void setDouble(int idx1, int idx2, double val);

Sets an element of a two-dimensional SafeArray.

Return Value:

No return value.

 Parameter Description idx1 The first dimension index of the element to set, which ranges from LBound(1) to UBound(1). idx2 The second dimension index of the element to set, which ranges from LBound(2) to UBound(2). val The new element value

Exceptions:

IndexOutOfBoundsException if the SafeArray is not two-dimensional or if either index lies outside the defined range.

ClassCastException if the Java value cannot be converted to the SafeArray element type using the Win32 VariantChangeType function.

#### setDoubles

public void setDoubles(int sa_idx, int nelems, double ja[], int ja_start);

Sets multiple elements of a SafeArray. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter where in the SafeArray the first element is located, that location is called index zero for the purposes of this method. The first element to be set in the SafeArray is located sa_idx elements away from index zero.

Note This method attempts all the usual type conversions. To achieve optimal performance, ensure that the element size of the source and destination arrays match exactly so that the method optimizes to a straight memory copy (memcpy).

Return Value:

No return value.

 Parameter Description sa_idx The index of the first element to set. This index is always zero-based. nelems The number of elements to set. ja The Java array that provides the values. ja_start The index of the first element to use in ja.

#### setFloat

public native void setFloat(int idx, float val);

Sets an element of a one-dimensional SafeArray.

Return Value:

No return value.

 Parameter Description idx The element index, which ranges from index of the lower bound to the index of the upper bound. val The new element value.

Exceptions:

IndexOutOfBoundsException if the SafeArray is not one-dimensional or if idx is not between the lower bound and the upper bound of the SafeArray (inclusive).

ClassCastException if the Java value cannot be converted to the SafeArray element type using the Win32 VariantChangeType function.

#### setFloat

public void setFloat(int idx1, int idx2, float val);

Sets an element of a two-dimensional array.

Return Value:

No return value.

 Parameter Description idx1 The first dimension index of the element to set, which ranges from LBound(1) to UBound(1). idx2 The second dimension index of the element to set, which ranges from LBound(2) to UBound(2). val The new element value.

Exceptions:

IndexOutOfBoundsException if the SafeArray is not two-dimensional or if either index lies outside the defined range.

ClassCastException if the Java value cannot be converted to the SafeArray element type using the Win32 VariantChangeType function.

#### setFloats

public void setFloats(int sa_idx, int nelems, float ja[], int ja_start);

Sets multiple elements of a SafeArray. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter where in the SafeArray the first element is located, that location is called index zero for the purposes of this method. The first element set in the SafeArray is located sa_idx elements away from index zero.

Note This method attempts all the usual type conversions. To achieve optimal performance, ensure that the element size of the source and destination arrays match exactly so that the method optimizes to a straight memory copy (memcpy).

Return Value:

No return value.

 Parameter Description sa_idx The index of the first element to set. This index is always zero-based. nelems The number of elements to set. ja The Java array that contains the new values. ja_start The index of the first element in ja to use.

#### setInt

public native void setInt(int idx, int val);

Sets an element of a one-dimensional SafeArray.

Return Value:

No return value.

 Parameter Description idx The element index, which ranges from the index of the lower bound to the index of the upper bound. val The new element value.

Exceptions:

IndexOutOfBoundsException is thrown if the SafeArray is not one-dimensional or if idx does not lie between the lower bound and the upper bound of the SafeArray (inclusive).

ClassCastException if the Java value cannot be converted to the SafeArray element type by using the Win32 VariantChangeType function.

#### setInt

public void setInt(int idx1, int idx2, int val);

Sets an element of a two-dimensional SafeArray.

Return Value:

No return value.

 Parameter Description idx1 The first dimension index of the element to set, which ranges from LBound(1) to UBound(1). idx2 The second dimension index of the element to set, which ranges from LBound(2) to UBound(2). val The new element value.

Exceptions:

IndexOutOfBoundsException if the SafeArray is not two-dimensional or if either index lies outside the defined range.

ClassCastException if the Java value cannot be converted to the SafeArray element type by using the Win32 VariantChangeType function.

#### setInts

public void setInts(int sa_idx, int nelems, int ja[], int ja_start);

Sets multiple elements of a SafeArray. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter where in the SafeArray the first element is located, that location is called index zero for the purposes of this method. The first element retrieved from the SafeArray is retrieved from the location that is sa_idx elements away from index zero.

Note This method attempts all the usual type conversions. To achieve optimal performance, ensure that the element size of the source and destination arrays match exactly, so that the method optimizes to a straight memory copy (memcpy).

Return Value:

No return value.

 Parameter Description sa_idx The index of the first element to set. This index is always zero-based. nelems The number of elements to set. ja The Java array that provides the values. ja_start The index of the first element in ja.

#### setShort

public void setShort(int idx, short val);

Sets an element of a one-dimensional SafeArray.

Return Value:

No return value.

 Parameter Description idx The element index, which ranges from index of the lower bound to the index of the upper bound. val The new element value.

Exceptions:

IndexOutOfBoundsException if the array is not one-dimensional or if idx is not between the lower bound and the upper bound of the SafeArray (inclusive).

ClassCastException if the Java value cannot be converted to the SafeArray element type using the Win32 VariantChangeType function.

#### setShort

public void setShort(int idx1, int idx2, short val);

Sets an element of a two-dimensional SafeArray.

Return Value:

No return value.

 Parameter Description idx1 The first dimension index of the element to set, which ranges from LBound(1) to UBound(1). idx2 The second dimension index of the element to set, which ranges from LBound(2) to UBound(2). val The new element value.

Exceptions:

IndexOutOfBoundsException if the SafeArray is not two-dimensional or if either index lies outside the defined range.

ClassCastException if the Java value cannot be converted to the SafeArray element type using the Win32 VariantChangeType function.

#### setShorts

public void setShorts(int sa_idx, int nelems, short ja[], int ja_start);

Sets multiple elements of a SafeArray. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter where in the SafeArray the first element is located, that location is called index zero for the purposes of this method. The first element set in the SafeArray is located sa_idx elements away from index zero.

Note This method attempts all the usual type conversions. To achieve optimal performance, ensure that the element size of the source and destination arrays match exactly so that the method optimizes to a straight memory copy (memcpy).

Return Value:

No return value.

 Parameter Description sa_idx The index of the first element to set. This index is always zero-based. nelems The number of elements to set. ja The Java array that contains the new values. ja_start The index of the first element in ja to use.

#### setString

public void setString(int idx, String val);

Sets an element of a one-dimensional SafeArray.

Return Value:

No return value.

 Parameter Description idx The element index, which ranges from index of the lower bound to the index of the upper bound. val The new element value.

Exceptions:

ClassCastException if the Java value cannot be converted to the SafeArray element type using the Win32 VariantChangeType function.

IndexOutOfBoundsException if the array is not one-dimensional or if idx is not between the lower bound and the upper bound of the SafeArray (inclusive).

#### setString

public void setString(int idx1, int idx2, String val);

Sets an element of a two-dimensional SafeArray.

Return Value:

No return value.

 Parameter Description idx1 The first dimension index of the element to set, which ranges from LBound(1) to UBound(1). idx2 The second dimension index of the element to set, which ranges from LBound(2) to UBound(2). val The new element value.

Exceptions:

IndexOutOfBoundsException if the array is not two-dimensional or if either index lies outside the defined range.

ClassCastException if the Java value cannot be converted to the SafeArray element type using the Win32 VariantChangeType function.

#### setStrings

public void setStrings(int sa_idx, int nelems, String ja[], int ja_start);

Sets multiple elements of a SafeArray. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter where in the SafeArray the first element is located, that location is called index zero for the purposes of this method. The first element to be set in the SafeArray is located sa_idx elements away from index zero.

Return Value:

No return value.

 Parameter Description sa_idx The index of the first element to set. This index is always zero-based. nelems The number of elements to set. ja The Java array that contains the new values. ja_start The index of the first element to use in ja.

#### setVariant

public void setVariant(int idx, Variant val);

Sets an element of a one-dimensional SafeArray.

Note Although Variant methods can operate on any SafeArray type, it is usually much more efficient to use the specific method for the element type. This is true even if the SafeArray is a SafeArray of Variants.

Return Value:

No return value.

 Parameter Description idx The element index, which ranges from the index of the lower bound to the index of the upper bound. val The new element value.

Exceptions:

IndexOutOfBoundsException if the array is not one-dimensional or if idx does not lie between the lower bound and the upper bound of the SafeArray (inclusive).

ClassCastException if the Java value cannot be converted to the SafeArray element type by using the Win32 VariantChangeType function.

#### setVariant

public void setVariant(int idx1, int idx2, Variant val);

Sets an element of a two-dimensional SafeArray.

Note Although Variant methods can operate on any SafeArray type, it is usually much more efficient to use the specific method for the element type. This is true even if the SafeArray is a SafeArray of Variants.

Return Value:

No return value.

 Parameter Description idx1 The first element index, which ranges from LBound(1) to UBound(1). idx2 The first element index, which ranges from LBound(2) to UBound(2). val The new element value.

Exceptions:

IndexOutOfBoundsException if the array is not two-dimensional or if either index lies outside the defined range.

ClassCastException if the Java value cannot be converted to the SafeArray element type by using the Win32 VariantChangeType function.

#### setVariants

public void setVariants(int sa_idx, int nelems, Variant ja[], int ja_start);

Sets multiple elements of a SafeArray. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter where in the SafeArray the first element is located, that location is called index zero for the purposes of this method. The first element to be set in the SafeArray is located sa_idx elements away from index zero.

Note Although the Variant methods can operate on any SafeArray type, it is usually much more efficient to use the specific method for the element type. This is true even if the SafeArray is a SafeArray of Variants.

Return Value:

No return value.

 Parameter Description sa_idx The index of the first element to set. This index is always zero-based. nelems The number of elements to set. ja The Java array that provides the values. ja_start The index of the first element to use in ja.

#### toBooleanArray

public boolean[] toBooleanArray();

Converts an entire SafeArray to a Java array. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter where in the SafeArray the first element is located, that location is called index zero for the purposes of this method.

Note If you are extracting a large number of elements, it may be more efficient to use toCharArray rather than toBooleanArray. Since SafeArray objects use two bytes per element, the toBooleanArray method cannot optimize itself to a memory copy (memcpy).

Return Value:

Returns the flattened contents of the array.

#### toByteArray

public byte[] toByteArray();

Converts an entire SafeArray to a Java array. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter where in the SafeArray the first element is located, that location is called index zero for the purposes of this method.

Note This method attempts all the usual type conversions. To achieve optimal performance, ensure that the element size of the source and destination arrays match exactly, so that the method optimizes to a straight memory copy (memcpy).

Return Value:

Returns the flattened contents of the array.

#### toCharArray

public char[] toCharArray();

Converts an entire SafeArray to a Java array. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter where in the SafeArray the first element is located, that location is called index zero for the purposes of this method.

Note This method attempts all the usual type conversions. To achieve optimal performance, ensure that the element size of the source and destination arrays match exactly, so that the method optimizes to a straight memory copy (memcpy).

Return Value:

Returns the flattened contents of the array.

#### toDoubleArray

public double[] toDoubleArray();

Converts an entire SafeArray to a Java array. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter where in the SafeArray the first element is located, that location is called index zero for the purposes of this method.

Note This method attempts all the usual type conversions. To achieve optimal performance, ensure that the element size of the source and destination arrays match exactly, so that the method optimizes to a straight memory copy (memcpy).

Return Value:

Returns the flattened contents of the array.

#### toFloatArray

public float[] toFloatArray();

Converts an entire SafeArray to a Java array. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter where in the SafeArray the first element is located, that location is called index zero for the purposes of this method.

Note This method attempts all the usual type conversions. To achieve optimal performance, ensure that the element size of the source and destination arrays match exactly, so that the method optimizes to a straight memory copy (memcpy).

Return Value:

Returns the flattened contents of the array.

#### toIntArray

public int[] toIntArray();

Converts an entire SafeArray to a Java array. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter where in the SafeArray the first element is located, that location is called index zero for the purposes of this method.

Note This method attempts all the usual type conversions. To achieve optimal performance, ensure that the element size of the source and destination arrays match exactly, so that the method will optimize to a straight memory copy (memcpy).

Return Value:

Returns the flattened contents of the array.

#### toShortArray

public short[] toShortArray();

Converts the entire SafeArray to a Java array. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter where in the SafeArray the first element is located, that location is called index zero for the purposes of this method.

Note This method attempts all the usual type conversions. To achieve optimal performance, ensure that the element size of the source and destination arrays match exactly, so that the method optimizes to a straight memory copy (memcpy).

Return Value:

Returns the flattened contents of the array.

#### toString

public String toString();

Defines the printed representation of a SafeArray object.

Return Value:

Returns the printed representation.

#### toStringArray

public String[] toStringArray();

Converts an entire SafeArray to a Java array. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter what the index of the lower bound of the SafeArray is, the first element is stored in element zero of the Java array.

Return Value:

Returns the flattened contents of the array.

#### toVariantArray

public Variant[] toVariantArray();

Converts an entire SafeArray to a Java array. If the SafeArray is multidimensional, it is treated as if it were a single linear array stored in column order. No matter where in the SafeArray the first element is located, that location is called index zero for the purposes of this method.

Note Although the Variant methods can operate on any SafeArray type, it is usually much more efficient to use the specific method for the SafeArray type rather than to extract first as a Variant, and then coerce the Variant. This is true even if the SafeArray is a SafeArray of Variants.

Return Value:

Returns the flattened contents of the array.

0
1 收藏

2014/06/06 16:20

1 评论
1 收藏
0