Função VariantToBuffer (propvarutil.h)

Extrai o conteúdo de um buffer armazenado em uma estrutura VARIANT do tipo VT_ARRRAY | VT_UI1.

Sintaxe

PSSTDAPI VariantToBuffer(
  [in]  REFVARIANT varIn,
  [out] void       *pv,
  [in]  UINT       cb
);

Parâmetros

[in] varIn

Tipo: REFVARIANT

Referência a uma estrutura VARIANT de origem.

[out] pv

Tipo: VOID*

Ponteiro para um buffer de comprimento cb bytes. Quando essa função retorna, contém os primeiros bytes cb do valor do buffer extraído.

[in] cb

Tipo: UINT

O tamanho do buffer pv , em bytes. O buffer deve ter o mesmo tamanho que os dados a serem extraídos ou menores.

Retornar valor

Tipo: HRESULT

Retorna um dos seguintes valores:

Código de retorno	Descrição
S_OK	Dados extraídos com êxito.
E_INVALIDARG	Variant não era do tipo VT_ARRRAY | VT_UI1.
E_FAIL	O valor do buffer VARIANT tinha menos de cb bytes.

Comentários

Essa função é usada quando o aplicativo de chamada espera que um VARIANT mantenha um valor de buffer. O aplicativo de chamada deve marcar que o valor tenha o comprimento esperado antes de chamar essa função.

Se a VARIANT de origem tiver VT_ARRAY de tipo | VT_UI1, essa função extrai os primeiros bytes cb da estrutura e os coloca no buffer apontado por pv.

Se o valor armazenado tiver menos de cb bytes, VariantToBuffer falhará e o buffer não será modificado.

Se o valor tiver mais de cb bytes, VariantToBuffer terá êxito e truncará o valor.

Exemplos

O exemplo a seguir, a ser incluído como parte de um programa maior, demonstra como usar VariantToBuffer para acessar uma estrutura que foi armazenada em uma VARIANT.

// VARIANT var;
// Assume variable var is initialized and valid. 
// The application expects var to hold a WIN32_FIND_DATAW structure 
// with sizeof(WIN32_FIND_DATAW) bytes.

HRESULT hr = E_UNEXPECTED;

// Verify that the value length is acceptable before you call VariantToBuffer.
if (VariantGetElementCount(var) == sizeof(WIN32_FIND_DATAW))
{
    WIN32_FIND_DATAW wfd;

    hr = VariantToBuffer(var, &wfd, sizeof(wfd));

    if (SUCCEEDED(hr))
    {
        // wfd is now initialized.
    }
}

Requisitos

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

Confira também

InitVariantFromBuffer

PropVariantToBuffer