Compartilhar via

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

  • Artigo

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:

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.

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:
  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

Requisito Valor
Cliente mínimo com suporte Windows Vista [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows Server 2008 [somente aplicativos da área de trabalho]
Plataforma de Destino Windows
Cabeçalho propsys.h

Confira também

IPropertyDescription

Esquema de descrição da propriedade