SafeArrayGetElement

Article
06/30/2006

This function retrieves a single element of the array.

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

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 is invalid.
E_INVALIDARG	One of the arguments is invalid.
E_OUTOFMEMORY	Memory could not be allocated for the element.

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

Requirements

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

Share via