Windows apps
Collapse the table of content
Expand the table of content

SafeArrayGetElement Function

Retrieves a single element of the array.

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

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

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.

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

Return value

Meaning

S_OK

Success.

DISP_E_BADINDEX

The specified index is invalid.

E_INVALIDARG

One of the arguments is invalid.

E_OUTOFMEMORY

Memory could not be allocated for the element.

The following example is taken from the COM Fundamentals SPoly sample (Cenumpt.cpp) shipped with the Platform SDK.

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

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

   for(i = 0; i < celt; ++i){
      // Are we at the last element?
      if(m_iCurrent == m_celts){
      hresult = S_FALSE;
         goto LDone;
   }

      ix = m_iCurrent++;
      // m_psa is a global variable that holds the safe array.
      hresult = SafeArrayGetElement(m_psa, &ix, &rgvar[i]);
      if(FAILED(hresult))
         goto LError0;
   }
   hresult = NOERROR;

LDone:;
   if (pceltFetched != NULL)
      *pceltFetched = i;

   return hresult;

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