Função PropVariantToString (propvarutil.h)

Artigo
03/15/2023

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

Sintaxe

PSSTDAPI PropVariantToString(
  [in]  REFPROPVARIANT propvar,
  [out] PWSTR          psz,
  [in]  UINT           cch
);

Parâmetros

[in] propvar

Tipo: REFPROPVARIANT

Referência a uma estrutura PROPVARIANT de origem .

[out] psz

Tipo: PWSTR

Aponta para um buffer de cadeia de caracteres. Quando essa função retorna, o buffer é inicializado com um valor de cadeia de caracteres Unicode terminada em NULL .

[in] cch

Tipo: UINT

Tamanho do buffer apontado por psz, em caracteres.

Valor retornado

Tipo: HRESULT

Essa função pode retornar um desses valores.

Código de retorno	Descrição
S_OK	O valor foi extraído e o buffer de resultado foi encerrado nulo .
STRSAFE_E_INSUFFICIENT_BUFFER	Falha na operação de cópia devido a espaço em buffer insuficiente. O buffer de destino contém uma versão truncada e terminada em nulo do resultado pretendido. Em situações em que o truncamento é aceitável, isso pode não ser necessariamente visto como uma condição de falha.
Algum outro valor de erro	A extração falhou por algum outro motivo.

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. Por exemplo, um aplicativo que obtém valores de um repositório de propriedades pode usá-lo para extrair com segurança um valor de cadeia de caracteres para propriedades de cadeia de caracteres.

Se o PROPVARIANT de origem tiver tipo VT_LPWSTR ou VT_BSTR, essa função extrairá a cadeia de caracteres e a colocará no buffer fornecido. 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, PropVariantToString retornará um código de falha e definirá psz como '\0'. Consulte PropVariantChangeType para obter uma lista de conversões possíveis. Observe que VT_EMPTY é convertido com êxito em "".

Além do NULL de terminação, no máximo os caracteres cch-1 são gravados no buffer apontado por psz. Se o valor no PROPVARIANT de origem for maior do que caberá no buffer, uma cópia terminada null truncada da cadeia de caracteres será gravada no buffer e essa função retornará STRSAFE_E_INSUFFICIENT_BUFFER. A cadeia de caracteres resultante sempre será terminada em NULL .

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

PROPVARIANTscom valor vetor são convertidos em cadeias de caracteres separando cada elemento com "; ". Por exemplo, PropVariantToString 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

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

// 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.

    // PropVariantToString will convert VT_EMPTY to "".

    // The application decided that it only needs the first 127 characters of the title, so the buffer 

    // has size 128 to account for the terminating NULL.

    WCHAR szTitle[128];

    hr = PropVariantToString(propvar, szTitle, ARRAYSIZE(szTitle));

    if (SUCCEEDED(hr) || hr == STRSAFE_E_INSUFFICIENT_BUFFER)

    {

        // szTitle is now valid and contains up to 127 characters from propvar and a terminating NULL

    }

    else

    {

        // the extraction failed

    }

    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