SafeArrayGetElement (Windows CE 5.0)

Article
09/14/2012

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

Returns the HRESULT values shown in the following table.

Value	Description
S_OK	Success.
DISP_E_BADINDEX	The specified index is invalid.
E_INVALIDARG	An argument 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