Compartilhar via


Função PropVariantToString (propvarutil.h)

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

Confira também

InitPropVariantFromString

PropVariantChangeType

PropVariantGetStringElem

PropVariantToBSTR

PropVariantToStringAlloc

PropVariantToStringVector

VariantToString