SafeArrayGetElement

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

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.

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

See Also

Reference

Automation Functions
SafeArrayCreate
SafeArrayLock
SafeArrayUnlock