SafeArrayPutElement function (oleauto.h)

2021-10-13

Stores the data element at the specified ___location in the array.

Syntax

HRESULT SafeArrayPutElement(
  [in] SAFEARRAY *psa,
  [in] LONG      *rgIndices,
  [in] void      *pv
);

Parameters

[in] psa

An array descriptor created by SafeArrayCreate.

[in] rgIndices

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

[in] pv

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
S_OK	Success.
DISP_E_BADINDEX	The specified index is not valid.
E_INVALIDARG	One of the arguments is not valid.
E_OUTOFMEMORY	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.

Note 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).

Requirements

Requirement	Value
Target Platform	Windows
Header	oleauto.h
Library	OleAut32.lib
DLL	OleAut32.dll

Share via