SafeArrayPutElement
This function assigns a single element to the array.
HRESULT SafeArrayPutElement(
SAFEARRAY FAR *psa,
long FAR *rgIndices,
void FAR *pv );
Parameters
- 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
Void 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.
Return Values
One of the values obtained from the returned HRESULT and described in the following table is returned.
| Value | Description |
|---|---|
| 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. |
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. If the existing element is a string, object, or variant, it is cleared correctly. Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.
Note Multiple locks can be on an array. Elements can be put into an array while the array is locked by other operations.
Example
HRESULT PASCAL __export CPoly::EnumPoints(IEnumVARIANT FAR* FAR* ppenum)
{
unsigned int i;
HRESULT hresult;
VARIANT var;
SAFEARRAY FAR* psa;
CEnumPoint FAR* penum;
POINTLINK FAR* ppointlink;
SAFEARRAYBOUND rgsabound[1];
rgsabound[0].lLbound = 0;
rgsabound[0].cElements = m_cPoints;
psa = SafeArrayCreate(VT_VARIANT, 1, rgsabound);
if(psa == NULL){
HRESULT = ResultFromScode(E_OUTOFMEMORY);
goto LError0;
}
// Code omitted here for brevity.
V_VT(&var) = VT_DISPATCH;
HRESULT = ppointlink->ppoint->QueryInterface(
IID_IDispatch, (void FAR* FAR*)&V_DISPATCH(&var));
if(HRESULT != NOERROR)
goto LError1;
ix[0] = i;
SafeArrayPutElement(psa, ix, &var);
ppointlink = ppointlink->next;
}
HRESULT = CEnumPoint::Create(psa, &penum);
if(HRESULT != NOERROR)
goto LError1;
*ppenum = penum;
return NOERROR;
LError1:;
SafeArrayDestroy(psa);
LError0:;
return hresult;
}
Requirements
| Runs on | Versions | Defined in | Include | Link to |
|---|---|---|---|---|
| Windows CE OS | 2.0 and later | Oleauto.h | Oleaut32.lib |
Note This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.
Last updated on Tuesday, July 13, 2004
© 1992-2000 Microsoft Corporation. All rights reserved.