Compartilhar via


Função PropVariantToStringAlloc (propvarutil.h)

Extrai um valor de propriedade de cadeia de caracteres de uma estrutura PROPVARIANT .

Sintaxe

PSSTDAPI PropVariantToStringAlloc(
  [in]  REFPROPVARIANT propvar,
  [out] PWSTR          *ppszOut
);

Parâmetros

[in] propvar

Tipo: REFPROPVARIANT

Referência a uma estrutura PROPVARIANT de origem .

[out] ppszOut

Tipo: PWSTR*

Quando essa função retorna, contém um ponteiro para o valor da propriedade extraída se houver um.

Retornar valor

Tipo: HRESULT

Se essa função for bem-sucedida, ela retornará S_OK. Caso contrário, ele retornará um código de erro HRESULT.

Comentários

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

Se o PROPVARIANT de origem tiver tipo VT_LPWSTR ou VT_BSTR, essa função extrairá a cadeia de caracteres em um buffer recém-alocado. Caso contrário, ele tentará converter o valor na estrutura PROPVARIANT em uma cadeia de caracteres. Se uma conversão não for possível, PropVariantToStringAlloc retornará um código de falha e definirá ppszOut como NULL. Consulte PropVariantChangeType para obter uma lista de conversões possíveis. Observe que VT_EMPTY é convertido com êxito em um buffer alocado que contém "".

O aplicativo de chamada é responsável por usar CoTaskMemFree para liberar a cadeia de caracteres apontada por ppszOut quando ela não for mais necessária.

Além das conversões fornecidas por PropVariantChangeType, os casos especiais a seguir se aplicam a PropVariantToStringAlloc.

  • PROPVARIANTs com valor vetor são convertidos em cadeias de caracteres separando cada elemento com "; ". Por exemplo, PropVariantToStringAlloc converte um vetor de 3 inteiros, {3, 1, 4}, na cadeia de caracteres "3; 1; 4". O ponto e vírgula é independente da localidade atual.
  • VT_BLOB, VT_STREAM, VT_STREAMED_OBJECT e valores de VT_UNKNOWN são convertidos em cadeias de caracteres usando uma codificação sem suporte. Não é possível decodificar cadeias de caracteres criadas dessa forma e o formato pode mudar no futuro.

Exemplos

// IPropertyStore *ppropstore;

// Assume variable ppropstore is initialized and valid

PROPVARIANT propvar = {0};

HRESULT hr = ppropstore->GetValue(PKEY_Title, &propvar);

if (SUCCEEDED(hr))

{

    // PKEY_Title is expected to produce a VT_LPWSTR or VT_EMPTY value.

    // PropVariantToStringAlloc will convert VT_EMPTY to "".

    LPWSTR pszTitle;

    hr = PropVariantToString(propvar, &pszTitle);

    if (SUCCEEDED(hr))

    {

        // pszTitle is now valid

    }

    else

    {

        // pszTitle is always NULL

    }

    PropVariantClear(&propvar);

}

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

InitPropVariantFromString

PropVariantChangeType

PropVariantToString

PropVariantToStringVector

VariantToString