Função PropVariantToStringVector (propvarutil.h)

Artigo
08/25/2023

Extrai um vetor de cadeias de caracteres de uma estrutura PROPVARIANT .

Sintaxe

PSSTDAPI PropVariantToStringVector(
  [in]  REFPROPVARIANT propvar,
  [out] PWSTR          *prgsz,
  [in]  ULONG          crgsz,
  [out] ULONG          *pcElem
);

Parâmetros

[in] propvar

Tipo: REFPROPVARIANT

Referência a uma estrutura PROPVARIANT de origem .

[out] prgsz

Tipo: PWSTR*

Ponteiro para um vetor de ponteiros de cadeia de caracteres. Quando essa função retorna, o buffer foi inicializado com elementos pcElem apontando para cadeias de caracteres recém-alocadas que contêm os dados extraídos do PROPVARIANT de origem.

[in] crgsz

Tipo: ULONG

Tamanho do buffer apontado por prgsz, em elementos.

[out] pcElem

Tipo: ULONG*

Quando essa função retorna, contém a contagem de cadeias de caracteres extraídas da estrutura PROPVARIANT de origem .

Retornar valor

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, caso contrário.
TYPE_E_BUFFERTOOSMALL	OPROPVARIANT de origem continha mais do que valores crgsz . O buffer apontado por prgsz.
E_INVALIDARG	OPROPVARIANT não era do tipo apropriado.

Comentários

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

Essa função funciona para os seguintes tipos PROPVARIANT :

VT_VECTOR | VT_LPWSTR
VT_VECTOR | VT_BSTR
VT_ARRAY | VT_BSTR

Se o PROPVARIANT de origem tiver um tipo com suporte, essa função auxiliar extrairá até valores de cadeia de caracteres crgsz e colocará uma cópia alocada de cada um no buffer apontado por prgsz. Se o PROPVARIANT contiver mais elementos do que caberá no buffer prgsz , essa função retornará um erro e definirá pcElem como 0.

Como cada cadeia de caracteres apontada pelo buffer de saída foi alocada recentemente, o aplicativo de chamada é responsável por usar CoTaskMemFree para liberar cada cadeia de caracteres no buffer de saída quando elas não forem mais necessárias.

Se um BSTR no PROPVARIANT de origem for NULL, ele será convertido em uma cadeia de caracteres recém-alocada contendo "" na saída.

Exemplos

// PROPVARIANT propvar;
// Assume the variable propvar is initialized and valid
LPWSTR rgszStrings; // The application is expecting propvar to hold 4 strings in a vector
ULONG cElems;
HRESULT hr = PropVariantToStringVector(propvar, rgszStrings, ARRAYSIZE(rgszStrings), &cElems);
if (SUCCEEDED(hr))
{
     if (cElems == ARRAYSIZE(rgszStrings))
     {
         // The application got 4 string which are now stored in rgszStrings
     }
     else
     {
         // The application got cElems which are stored in the first cElems elements of rgLongs
     }
 
    // Free the cElems strings that PropVariantToStringVector allocated
    for (ULONG i = 0; i < cElems; i++)
    {
        CoTaskMemFree(rgszStrings[i]);
    }
}

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