SafeArrayPutElement

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

Assigns a single element to the array.

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

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 Value

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

Comments

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.

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;
}

QuickInfo

  Windows NT: Use version 3.1 and later.
  Windows: Use Windows 95 and later.
  Header: Declared in oleauto.h.
  Import Library: Link with oleaut32.lib.