SafeArrayPutElement function
Stores the data element at the specified location in the array.
Syntax
HRESULT SafeArrayPutElement(
_In_ SAFEARRAY *psa,
_In_ LONG *rgIndices,
_In_ void *pv
);
Parameters
- psa [in]
-
An array descriptor created by SafeArrayCreate.
- rgIndices [in]
-
A vector of indexes for each dimension of the array. The right-most (least significant) dimension is rgIndices[0]. The left-most dimension is stored at
rgIndices[psa->cDims – 1]. - pv [in]
-
The data to assign to the array. The variant types VT_DISPATCH, VT_UNKNOWN, and VT_BSTR are pointers, and do not require another level of indirection.
Return value
This function can return one of these values.
| Return code | Description |
|---|---|
|
Success. |
|
The specified index is not valid. |
|
One of the arguments is not valid. |
|
Memory could not be allocated for the element. |
Remarks
This function automatically calls SafeArrayLock and SafeArrayUnlock before and after assigning the element. If the data element is a string, object, or variant, the function copies it correctly when the safe array is destroyed. If the existing element is a string, object, or variant, it is cleared correctly. If the data element is a VT_DISPATCH or VT_UNKNOWN, AddRef is called to increment the object's reference count.
For an example that demonstrates calling SafeArrayPutElement, see the COM Fundamentals Lines sample (CLines::Add in Lines.cpp).
Requirements
|
Header |
|
|---|---|
|
Library |
|
|
DLL |
|