Função SafeArrayGetElement (oleauto.h)

Recupera um único elemento da matriz.

Sintaxe

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

Parâmetros

[in] psa

Um descritor de matriz criado por SafeArrayCreate.

[in] rgIndices

Um vetor de índices para cada dimensão da matriz. A dimensão mais à direita (menos significativa) é rgIndices[0]. A dimensão mais à esquerda é armazenada em rgIndices[psa->cDims – 1].

[out] pv

O elemento da matriz.

Retornar valor

Essa função pode retornar um desses valores.

Código de retorno	Descrição
S_OK	Êxito.
DISP_E_BADINDEX	O índice especificado não é válido.
E_INVALIDARG	Um dos argumentos não é válido.
E_OUTOFMEMORY	Não foi possível alocar memória para o elemento .

Comentários

Essa função chama SafeArrayLock e SafeArrayUnlock automaticamente, antes e depois de recuperar o elemento. O chamador deve fornecer uma área de armazenamento do tamanho correto para receber os dados. Se o elemento de dados for uma cadeia de caracteres, objeto ou variante, a função copiará o elemento da maneira correta.

Exemplos

O exemplo a seguir é obtido do exemplo de SPoly de Conceitos Básicos do COM (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;
}

Requisitos

Requisito	Valor
Plataforma de Destino	Windows
Cabeçalho	oleauto.h
Biblioteca	OleAut32.lib
DLL	OleAut32.dll