Função PropVariantToStringVectorAlloc (propvarutil.h)

Artigo
08/25/2023

Extrai dados de uma estrutura PROPVARIANT em cadeias de caracteres recém-alocadas em um vetor recém-alocado.

Sintaxe

PSSTDAPI PropVariantToStringVectorAlloc(
  [in]  REFPROPVARIANT propvar,
  [out] PWSTR          **pprgsz,
  [out] ULONG          *pcElem
);

Parâmetros

[in] propvar

Tipo: REFPROPVARIANT

Referência a uma estrutura PROPVARIANT de origem .

[out] pprgsz

Tipo: PWSTR**

Quando essa função retorna, contém um ponteiro para um vetor de cadeias de caracteres extraídas da estrutura PROPVARIANT de origem .

[out] pcElem

Tipo: ULONG*

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

Valor retornado

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.
E_INVALIDARG	O PROPVARIANT não era do tipo apropriado.

Comentários

Essa função auxiliar é usada em locais em que o aplicativo de chamada espera que um PROPVARIANT mantenha um vetor de valores de cadeia de caracteres.

Essa função auxiliar funciona para os seguintes tiposPROPVARIANT :

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 extrairá um vetor de valores de cadeia de caracteres em um vetor recém-alocado de cadeias de caracteres recém-alocadas. O aplicativo de chamada é responsável por usar CoTaskMemFree para liberar as cadeias de caracteres contidas no vetor de saída e o próprio vetor de saída, quando elas não forem mais necessárias.

Se um BSTR no PROPVARIANT de origem for NULL, essa função colocará uma cadeia de caracteres recém-alocada contendo "" no vetor de saída.

Exemplos

O exemplo a seguir, a ser incluído como parte de um programa maior, demonstra como usar PropVariantToStringVectorAlloc para acessar um valor de vetor de cadeia de caracteres em um PROPVARIANT.

// IPropertyStore *ppropstore;
// Assume variable ppropstore is initialized and valid
PROPVARIANT propvar = {0};
HRESULT hr = ppropstore->GetValue(PKEY_Keywords, &propvar);
if (SUCCEEDED(hr))
{
         // PKEY_Keywords is expected to produce a VT_VECTOR | VT_LPWSTR, or VT_EMPTY
         // PropVariantToStringVectorAlloc will return an error for VT_EMPTY
         LPWSTR *prgKeywords;
         ULONG cElem;
         hr = PropVariantToStringVectorAlloc (propvar, &prgKeywords, &cElem);
         if (SUCCEEDED(hr))
         {
                 // prgKeywords contains cElem strings
                 for (ULONG i = 0; i < cElem; i++)
                 {
                          CoTaskMemFree(prgKeywords[i]);
                 }
                 CoTaskMemFree(prgKeywords);
         }
         else
         {
                 // propvar either is VT_EMPTY, or contains something other than a vector of  strings
         }
         PropVariantClear(&propvar);
}

Requisitos


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