SafeArrayGetElement

This function retrieves a single element of the array.

At a Glance

Syntax

HRESULT SafeArrayGetElement(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 location to place the element of the array.

Return Values

One of the values obtained from the returned HRESULT and described in the following table is returned.

Remarks

This function calls SafeArrayLock and SafeArrayUnlock automatically, before and after retrieving the element. The caller must provide a storage area of the correct size to receive the data. If the data element is a string, object, or variant, the function copies the element in the correct way. Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.

Example

STDMETHODIMP CEnumPoint::Next(
   ULONG celt,
   VARIANT FAR rgvar[],
   ULONG FAR* pceltFetched)
{
   unsigned int i;
   long ix;
   HRESULT hresult;

   for(i = 0; i < celt; ++i)
      VariantInit(&rgvar[i]);

   for(i = 0; i < celt; ++i){
      if(m_iCurrent == m_celts){
      HRESULT = ReportResult(0, S_FALSE, 0, 0);
         goto LDone;
   }

      ix = m_iCurrent++;
      HRESULT = SafeArrayGetElement(m_psa, &ix, &rgvar[i]);
      if(FAILED(hresult))
         goto LError0;
   }
   HRESULT = NOERROR;

LDone:;
   *pceltFetched = i;
   return hresult;

LError0:;
   for(i = 0; i < celt; ++i)
      VariantClear(&rgvar[i]);
   return hresult;
}