SafeArrayGetElement-Funktion (oleauto.h)

  • Artikel

Ruft ein einzelnes Element des Arrays ab.

Syntax

HRESULT SafeArrayGetElement(
  [in]  SAFEARRAY *psa,
  [in]  LONG      *rgIndices,
  [out] void      *pv
);

Parameter

[in] psa

Ein arraydeskriptor, der von SafeArrayCreate erstellt wurde.

[in] rgIndices

Ein Vektor von Indizes für jede Dimension des Arrays. Die rechteste (am wenigsten signifikante) Dimension ist rgIndices[0]. Die ganz linksste Dimension wird unter rgIndices[psa->cDims – 1]gespeichert.

[out] pv

Das Element des Arrays.

Rückgabewert

Diese Funktion kann einen dieser Werte zurückgeben.

Rückgabecode BESCHREIBUNG
S_OK
 Erfolg.
DISP_E_BADINDEX
 Der angegebene Index ist ungültig.
E_INVALIDARG
 Eines der Argumente ist ungültig.
E_OUTOFMEMORY
 Der Arbeitsspeicher konnte für das Element nicht zugeordnet werden.

Hinweise

Diese Funktion ruft SafeArrayLock und SafeArrayUnlock automatisch vor und nach dem Abrufen des Elements auf. Der Aufrufer muss einen Speicherbereich der richtigen Größe angeben, um die Daten zu empfangen. Wenn das Datenelement eine Zeichenfolge, ein Objekt oder eine Variante ist, kopiert die Funktion das Element auf die richtige Weise.

Beispiele

Das folgende Beispiel stammt aus dem COM Fundamentals SPoly-Beispiel (Cenumpt.cpp).

STDMETHODIMP CEnumPoint::Next(
   ULONG celt,
   VARIANT  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;
}

Anforderungen

Anforderung Wert
Zielplattform Windows
Kopfzeile oleauto.h
Bibliothek OleAut32.lib
DLL OleAut32.dll