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:
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.
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.
