Função SafeArrayPutElement (oleauto.h)

  • Artigo

Armazena o elemento de dados no local especificado na matriz.

Sintaxe

HRESULT SafeArrayPutElement(
  [in] SAFEARRAY *psa,
  [in] LONG      *rgIndices,
  [in] 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].

[in] pv

Os dados a serem atribuídos à matriz. Os tipos variantes VT_DISPATCH, VT_UNKNOWN e VT_BSTR são ponteiros e não exigem outro nível de indireção.

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 automaticamente SafeArrayLock e SafeArrayUnlock antes e depois de atribuir o elemento. Se o elemento de dados for uma cadeia de caracteres, objeto ou variante, a função o copiará corretamente quando a matriz segura for destruída. Se o elemento existente for uma cadeia de caracteres, um objeto ou uma variante, ele será limpo corretamente. Se o elemento de dados for um VT_DISPATCH ou VT_UNKNOWN, AddRef será chamado para incrementar a contagem de referência do objeto.

Nota Vários bloqueios podem estar em uma matriz. Os elementos podem ser colocados em uma matriz enquanto a matriz é bloqueada por outras operações.
 
Para obter um exemplo que demonstra a chamada de SafeArrayPutElement, consulte o exemplo linhas de conceitos básicos com (CLines::Add em Lines.cpp).

Requisitos

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