SafeArrayGetElement (Compact 2013)

3/26/2014

This function retrieves a single element of the array.

Syntax

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 Value

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

Header	oleauto.h
Library	oleaut32.lib

See Also

Reference

Automation Functions
SafeArrayCreate
SafeArrayLock
SafeArrayUnlock