SafeArrayPutElement

Article
06/30/2006

This function assigns a single element to the array.

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

Parameters

psa
[in] Pointer to an array descriptor created by SafeArrayCreate.
rgIndices
[in] 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
[out] 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

The following table shows the HRESULT values that can be returned by this function.

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 invalid (and under some circumstances NULL) pointers to this function causes an 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

OS Versions: Windows CE 2.0 and later.
Header: Oleauto.h.
Link Library: Oleaut32.lib.