Compartilhar via


Função PropVariantToStringWithDefault (propvarutil.h)

Extrai o valor da propriedade de cadeia de caracteres de uma estrutura PROPVARIANT . Se nenhum valor existir, o valor padrão especificado será retornado.

Sintaxe

PSSTDAPI_(PCWSTR) PropVariantToStringWithDefault(
  [in] REFPROPVARIANT propvarIn,
  [in] LPCWSTR        pszDefault
);

Parâmetros

[in] propvarIn

Tipo: REFPROPVARIANT

Referência a uma estrutura PROPVARIANT de origem .

[in] pszDefault

Tipo: LPCWSTR

Ponteiro para um valor de cadeia de caracteres Unicode padrão, para uso em que nenhum valor existe no momento. Pode ser NULL.

Retornar valor

Tipo: PCWSTR

Retorna o valor da cadeia de caracteres ou o padrão ou o padrão.

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 e gostaria de usar um valor padrão se não o fizer. Por exemplo, um aplicativo que obtém valores de um repositório de propriedades pode usá-lo para extrair com segurança o valor da cadeia de caracteres para propriedades de cadeia de caracteres.

Se o PROPVARIANT de origem tiver tipo VT_LPWSTR ou VT_BSTR, essa função auxiliar retornará um ponteiro para o valor no PROPVARIANT de origem. Se o PROPVARIANT de origem tiver o tipo VT_EMPTY ou uma conversão não for possível, PropVariantToStringWithDefault retornará o padrão fornecido por pszDefault.

Observe que essa função retornará ponteiros para os dados fornecidos nos parâmetros. Portanto, o aplicativo deve garantir que os dados fornecidos aos parâmetros permaneçam válidos até que o resultado não esteja mais em uso.

Exemplos

O exemplo a seguir, a ser incluído como parte de um programa maior, demonstra como usar PropVariantToStringWithDefault 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.
     // The application developer decided to treat VT_EMPTY or invalid values as ""
     PCWSTR pszTitle = PropVariantToStringWithDefault(propvar, L"");
     // pszTitle is now valid.
     PropVariantClear(&propvar);
}
// ... later in the program ...
hr = ppropstore->GetValue(PKEY_Comment, &propvar);
if (SUCCEEDED(hr))
{
         // PKEY_Comment is expected to produce a VT_LPWSTR or VT_EMPTY value.
         // The application developer decided to treat VT_EMPTY as NULL
         PCWSTR pszComment = PropVariantToStringWithDefault(propvar, NULL);
         if (pszComment)
         {
                 // pszComment is valid
         }
         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

PropVariantToStringAlloc

VariantToString