SafeArrayPutElement Function

Stores the data element at a given location in the array.

HRESULT SafeArrayPutElement(  
  SAFEARRAY *  psa,  
  long *  rgIndices, 
  void *  pv         
);

psa

Pointer to an array descriptor created by SafeArrayCreate.

rgIndices

Pointer to 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

Pointer to 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.

The return value obtained from the returned HRESULT is one of the following.

Value

Meaning

S_OK

Success.

DISP_E_BADINDEX

The specified index was invalid.

E_INVALIDARG

One of the arguments is invalid.

E_OUTOFMEMORY

Memory could not be allocated for the element.

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.

NoteNote

Multiple locks can be on an array. Elements can be put into an array while the array is locked by other operations.

For an example that demonstrates calling SafeArrayPutElement, see the COM Fundamentals Lines sample (CLines::Add in Lines.cpp) shipped with the Platform SDK.

Show:
© 2014 Microsoft