Função VariantToBooleanArray (propvarutil.h)

Artigo
03/05/2024

Extrai uma matriz de valores boolianos de uma estrutura VARIANT .

Sintaxe

PSSTDAPI VariantToBooleanArray(
  [in]  REFVARIANT var,
  [out] BOOL       *prgf,
  [in]  ULONG      crgn,
  [out] ULONG      *pcElem
);

Parâmetros

[in] var

Tipo: REFVARIANT

Referência a uma estrutura VARIANT de origem.

[out] prgf

Tipo: BOOL*

Ponteiro para um buffer que contém valores boolianos crgn . Quando essa função retorna, o buffer foi inicializado com elementos BOOL *pcElem extraídos da estrutura VARIANT de origem.

[in] crgn

Tipo: ULONG

O número de elementos no buffer apontado por prgf.

[out] pcElem

Tipo: ULONG*

Quando essa função retorna, contém um ponteiro para a contagem de elementos BOOL extraídos da estrutura VARIANT de origem.

Retornar valor

Tipo: HRESULT

Retorna S_OK se tiver êxito ou um valor de erro, caso contrário, incluindo o seguinte:

Código de retorno	Descrição
TYPE_E_BUFFERTOOSMALL	A VARIANT de origem continha mais do que valores crgn .
E_INVALIDARG	A VARIANT não era do tipo apropriado.

Comentários

Essa função auxiliar é usada quando o aplicativo de chamada espera que um VARIANT mantenha uma matriz que consiste em um número fixo de valores boolianos.

Se a VARIANT de origem for do tipo VT_ARRAY | VT_BOOL, essa função extrai até valores BOOLcrgn e os coloca no buffer apontado por prgf. Se VARIANT contiver mais elementos do que caberá no buffer prgf , 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 VariantToBooleanArray para acessar uma matriz de valores BOOL armazenados em uma estrutura VARIANT .

// VARIANT var;
// Assume variable var is initialized and valid
BOOL rgFlags[4]; // The application is expecting var to hold 4 BOOLs in an array.
ULONG cFlags;

HRESULT hr = VariantToBooleanArray(var, rgFlags, ARRAYSIZE(rgFlags), &cFlags);

if (SUCCEEDED(hr))
{
    if (cFlags == ARRAYSIZE(rgFlags))
    {
        // The application got 4 flag values which are now stored in rgFlags.
    }
    else
    {
        // The application got cFlags which are stored in the first cFlags 
        // elements of rgFlags.
    }
}

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