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 |
|---|---|
|
O valor foi extraído e o buffer de resultado foi encerrado nulo . |
|
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. |
|
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 |