Função PSCoerceToCanonicalValue (propsys.h)

Converte o valor de uma propriedade no valor canônico, de acordo com a descrição da propriedade.

Sintaxe

PSSTDAPI PSCoerceToCanonicalValue(
  [in]      REFPROPERTYKEY key,
  [in, out] PROPVARIANT    *ppropvar
);

Parâmetros

[in] key

Tipo: REFPROPERTYKEY

Referência a uma estrutura PROPERTYKEY que identifica a propriedade cujo valor deve ser coagido.

[in, out] ppropvar

Tipo: PROPVARIANT*

Na entrada, contém um ponteiro para uma estrutura PROPVARIANT que contém o valor original. Quando essa função retorna com êxito, contém o valor canônico.

Retornar valor

Tipo: HRESULT

Os possíveis valores retornados incluem o seguinte:

Código de retorno	Descrição
S_OK	A função foi bem-sucedida. O valor da propriedade especificado por ppropvar agora está em uma forma canônica.
INPLACE_S_TRUNCATED	O valor da propriedade especificado por ppropvar agora está em uma forma truncada e canônica.
E_INVALIDARG	O parâmetro ppropvar é inválido. A estrutura PROPVARIANT foi limpa.
TYPE_E_TYPEMISMATCH	A coerção do tipo do valor para o tipo da descrição da propriedade não foi possível. A estrutura PROPVARIANT foi limpa.
Qualquer outro código de falha	A coerção do tipo do valor para o tipo da descrição da propriedade não foi possível. A estrutura PROPVARIANT foi limpa.

Comentários

Essa função é um wrapper em torno da implementação do sistema de IPropertyDescription::CoerceToCanonicalValue.

A maioria das descrições de propriedade especifica o tipo que seus valores devem usar. Por exemplo, a descrição da propriedade de System.Title especifica que os valores System.Title devem ser do tipo VT_LPWSTR. Essa função impõe valores a esse tipo e, em seguida, coagi o resultado a uma forma canônica.

É importante observar que, se essa função falhar, ela já terá chamado PropVariantClear na estrutura PROPVARIANT de entrada. Somente se essa função for bem-sucedida será o aplicativo de chamada responsável por chamar PropVariantClear em ppropvar quando a estrutura não for mais necessária.

A coerção executada por essa função também é executada pelo sistema de propriedades durante chamadas para IPropertyStore::GetValue e IPropertyStore::SetValue. Os aplicativos podem depender do sistema de propriedades para executar as coerções ou podem usar essa função para executar a coerção em um momento da escolha do aplicativo.

A coerção é executada em quatro etapas, da seguinte maneira:

1. Os valores a seguir são convertidos em VT_EMPTY.
   • Valores do tipo VT_NULL.
   • Valores do tipo VT_LPWSTR, VT_BSTR ou VT_LPSTR cujo ponteiro é NULL.
   • Valores do tipo VT_LPWSTR, VT_BSTR ou VT_LPSTR vazios ou consistem inteiramente em espaços.
   • Os valores do tipo VT_FILETIME antes da meia-noite de 01/01/1601/02.
2. Se o valor não for do tipo VT_EMPTY após a Etapa 1, ele será convertido no tipo especificado pela descrição da propriedade. O tipo de uma descrição de propriedade pode ser obtido chamando IPropertyDescription::GetPropertyType. Para obter informações sobre como o esquema de propriedade influencia o tipo de uma descrição de propriedade, consulte typeInfo. As conversões são executadas da seguinte maneira:
   • Valores do tipo VT_LPWSTR, VT_BSTR ou VT_LPSTR são convertidos em VT_VECTOR | VT_LPWSTR usando InitPropVariantFromStringAsVector.
   • Todas as outras conversões são executadas usando PropVariantChangeType
3. Após as Etapas 2 e 3, o valor é coagido a uma forma canônica com base em seu tipo. Os formulários canônicos são resumidos na tabela a seguir.

   Tipo de valor	Formulário Canônico
   VT_EMPTY	Sempre canônico.
   VT_LPWSTR	Nenhum espaço à esquerda ou à direita. A cadeia de caracteres não é vazia e não é NULL. Por exemplo, L"Alice". Se essa for uma propriedade de árvore (ou seja, se o atributo isTreeProperty do elemento typeInfo for TRUE), ele não deverá ter barras (/) à esquerda ou à direita (/), não deve ter espaços entre o texto e as barras de avanço e não deve ter duas barras (/) consecutivas. Por exemplo, L"Friend/Bob". A coerção remove caracteres desnecessários e resulta em VT_EMPTY se não houver conteúdo.
   VT_VECTOR | VT_LPWSTR	Cada cadeia de caracteres no vetor deve seguir as regras para VT_LPWSTR listadas acima. Além disso, o vetor não deve ter duplicatas e não ter ponteiros nulos. Se essa for uma propriedade de árvore, nenhum valor poderá ser o ancestral de outro valor. Por exemplo, L"Friend" é um ancestral de L"Friend/Bob". Se não houver conteúdo, a coerção removerá caracteres duplicados e ancestrais e resultará em VT_EMPTY.

    
4. Se aplicável, o valor é verificado em relação à enumeração de tipo de descrição da propriedade. As verificações na tabela a seguir se aplicam.

   Tipo de enumeração	Tipo de valor	Formulário Canônico
   Discreto ou Ranged	VT_EMPTY	Sempre canônico
   Discreto	VT_LPWSTR	A cadeia de caracteres corresponde a uma das cadeias de caracteres enumeradas permitidas para a propriedade . Comparações não diferenciam maiúsculas de minúsculas. Caso contrário, converta o valor em VT_EMPTY.
   Discreto	Numérico	O número corresponde a um dos valores enumerados permitidos para a propriedade . Caso contrário, converta o valor em VT_EMPTY.
   Discreto	VT_VECTOR | VT_LPWSTR	Cada cadeia de caracteres no vetor corresponde a uma das cadeias de caracteres enumeradas permitidas para a propriedade . Comparações não diferenciam maiúsculas de minúsculas. Caso contrário, remova essa cadeia de caracteres do vetor. Se o vetor resultante estiver vazio, converta o valor em VT_EMPTY.
   Discreto	VT_VECTOR | Numérico	Cada número no vetor corresponde a um dos valores enumerados permitidos para a propriedade. Caso contrário, remova esse número do vetor. Se o vetor resultante estiver vazio, converta o valor em VT_EMPTY.
   Variou	VT_LPWSTR	A cadeia de caracteres existe no intervalo permitido para a propriedade . As comparações diferenciam maiúsculas de minúsculas. Caso contrário, converta o valor em VT_EMPTY.
   Variou	Numérico	O número existe no intervalo permitido para a propriedade . Caso contrário, converta o valor em VT_EMPTY.
   Variou	VT_VECTOR | VT_LPWSTR	Cada cadeia de caracteres no vetor existe no intervalo permitido para a propriedade . As comparações diferenciam maiúsculas de minúsculas. Caso contrário, remova essa cadeia de caracteres do vetor. Se o vetor resultante estiver vazio, converta o valor em VT_EMPTY.
   Variou	VT_VECTOR | Numérico	Cada número no vetor existe no intervalo permitido para a propriedade . Caso contrário, remova esse número do vetor. Se o vetor resultante estiver vazio, converta o valor em VT_EMPTY.

    

Exemplos

O exemplo a seguir, a ser incluído como parte de um programa maior, demonstra como usar PSCoerceToCanonicalValue para forçar um valor para o tipo necessário para PKEY_Keywords.

// PROPVARIANT propvar;
// Assume variable propvar is initialized and valid.

HRESULT hr = PSCoerceToCanonicalValue(PKEY_Keywords, &propvar);

if (SUCCEEDED(hr))
{
    // The conversion succeeded and propvar now is of the correct type for 
    // PKEY_Keywords, or VT_EMPTY.
    PropVariantClear(&propvar);
}
else
{
    // The conversion failed and propvar is now VT_EMPTY.
}

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

IPropertyDescription

IShellItem2::GetPropertyStore

PropVariantChangeType

Esquema de descrição da propriedade

Typeinfo