Método IPropertyDescription::CoerceToCanonicalValue (propsys.h)

Impõe o valor ao valor canônico, de acordo com a descrição da propriedade.

Sintaxe

HRESULT CoerceToCanonicalValue(
  [in, out] PROPVARIANT *ppropvar
);

Parâmetros

[in, out] ppropvar

Tipo: PROPVARIANT*

Na entrada, contém um ponteiro para uma estrutura PROPVARIANT que contém o valor original. Quando este método retorna, contém o valor canônico.

Retornar valor

Tipo: HRESULT

Se o código de falha não for INPLACE_S_TRUNCATED ou E_INVALIDARG, a coerção do tipo do valor para o tipo da descrição da propriedade não foi possível e a estrutura PROPVARIANT foi limpa.

Os resultados possíveis incluem o seguinte:

Comentários

Para obter mais informações, consulte o atributo type do elemento typeInfo no arquivo .propdesc da propriedade.

A maioria das descrições de propriedade especifica o tipo que seus valores devem usar. Por exemplo, a descrição da propriedade para System.Title especifica que os valores System.Title devem usar VT_LPWSTR. Esse método coagi valores para esse tipo e coagi o resultado a uma forma canônica.

É importante observar que, se esse método falhar, ele já terá chamado PropVariantClear na estrutura PROPVARIANT de entrada. Somente se esse método for bem-sucedido será o aplicativo de chamada responsável por chamar o PropVariantClear em ppropvar quando a estrutura não for mais necessária.

A coerção executada por esse método também é executada pelo sistema de propriedades durante as chamadas IPropertyStore::GetValue e IPropertyStore::SetValue . Os aplicativos podem depender do sistema de propriedades para executar as coerções ou podem usar esse método 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_BSTRou VT_LPSTR cujo ponteiro é NULL.
   • Valores do tipo VT_LPWSTR, VT_BSTRou VT_LPSTR que estão vazios ou consistem inteiramente em espaços.
   • Valores do tipo VT_FILETIME antes da meia-noite 1601/01/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 usando IPropertyDescription::GetPropertyType. Consulte typeInfo para obter informações sobre como o esquema de propriedade influencia o tipo de uma descrição de propriedade. As conversões são executadas da seguinte maneira:
   • Os valores do tipo VT_LPWSTR, VT_BSTRou 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 está vazia. A cadeia de caracteres não é NULL. Por exemplo, L"Alice". Se essa for uma propriedade de árvore (ou seja, se o atributo do isTreeProperty elemento typeInfo for TRUE), ela não deverá ter barras à esquerda ou à direita (/), não deve ter espaços entre o texto e as barras para frente e não deve ter duas barras (/) consecutivas. Por exemplo, L"Friend/Bob" A coerção remove caracteres desnecessários e resultará em VT_EMPTY se não houver conteúdo.
   VT_VECTOR | VT_LPWSTR	Cada cadeia de caracteres no vetor deve seguir as regras listadas VT_LPWSTR 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 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.

    

Requisitos

Confira também

IPropertyDescription

Esquema de descrição da propriedade