Função PropVariantToUInt16Vector (propvarutil.h)

Artigo
07/16/2024

Extrai dados de uma estrutura PROPVARIANT em um vetor de curto sem sinal .

Sintaxe

PSSTDAPI PropVariantToUInt16Vector(
  [in]  REFPROPVARIANT propvar,
  [out] USHORT         *prgn,
  [in]  ULONG          crgn,
  [out] ULONG          *pcElem
);

Parâmetros

[in] propvar

Tipo: REFPROPVARIANT

Referência a uma estrutura de PROPVARIANT de origem.

[out] prgn

Tipo: USHORT*

Aponta para um buffer que contém crgnvalores de curtos sem sinal. Quando essa função retorna, o buffer foi inicializado com pcElemelementos de curtos não assinados extraídos do propvariant de origem.

[in] crgn

Tipo: ULONG

Tamanho do buffer apontado por prgn em elementos.

[out] pcElem

Tipo: ULONG*

Quando essa função é retornada, contém a contagem de valores de curtos não assinados extraídos da estrutura PROPVARIANT de origem.

Valor de retorno

Tipo: HRESULT

Essa função pode retornar um desses valores.

Código de retorno	Descrição
S_OK	Retorna S_OK se tiver êxito ou um valor de erro de outra forma.
TYPE_E_BUFFERTOOSMALL	O PROPVARIANT de origem continha mais de valores de de crgn. O buffer apontado por prgn.
E_INVALIDARG	O PROPVARIANT não era do tipo apropriado.

Observações

Essa função auxiliar é usada em locais em que o aplicativo de chamada espera que um PROPVARIANT mantenha um vetor de valores de curtos sem sinal com um número fixo de elementos.

Se o PROPVARIANT de origem tiver VT_VECTOR | VT_UI2 ou VT_ARRAY | VT_UI2de tipo, essa função auxiliar extrairá até crgnvalores de curtos sem sinal e os colocará no buffer apontado por prgn. Se o PROPVARIANT contiver mais elementos do que caberá no buffer prgn, essa função retornará um erro e definirá pcElem como 0.

Exemplos

O exemplo a seguir, a ser incluído como parte de um programa maior, demonstra como usar propVariantToUInt16Vector para acessar um valor de vetor curto sem sinal em um PROPVARIANT.

// PROPVARIANT propvar;
// Assume the variable propvar is initialized and valid
USHORT rgShorts[4]; // The application is expecting propvar to hold 4 USHORTs in a vector
ULONG cElems;
HRESULT hr = PropVariantToUInt16Vector(propvar, rgShorts, ARRAYSIZE(rgShorts), &cElems);
if (SUCCEEDED(hr))
{
     if (cElems == ARRAYSIZE(rgShorts))
     {
         // The application got 4 USHORTs which are now stored in rgShorts
     }
     else
     {
         // The application got cElems which are stored in the first cElems elements of rgShorts
     }
}

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows XP com SP2, Windows Vista [somente aplicativos da área de trabalho]
servidor com suporte mínimo	Windows Server 2003 com SP1 [somente aplicativos da área de trabalho]
da Plataforma de Destino	Windows
cabeçalho	propvarutil.h
biblioteca	Propsys.lib
de DLL	Propsys.dll (versão 6.0 ou posterior)
redistribuível	Pesquisa da Área de Trabalho do Windows (WDS) 3.0