IPropertyDescription：：CoerceToCanonicalValue 方法 (propsys.h)

根据属性说明，将值强制为规范值。

语法

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

参数

[in, out] ppropvar

类型： PROPVARIANT*

输入时，包含指向包含原始值的 PROPVARIANT 结构的指针。 此方法返回时，包含规范值。

返回值

类型： HRESULT

如果失败代码未INPLACE_S_TRUNCATED或E_INVALIDARG，则无法从值的类型强制设置为属性说明的类型，并且 已清除 PROPVARIANT 结构。

可能的结果包括：

注解

有关详细信息， 请参阅属性的 .propdesc 文件中 typeInfo 元素的 type 属性。

大多数属性说明指定其值应使用的类型。 例如， System.Title 的属性说明指定 System.Title 值应使用 VT_LPWSTR。 此方法将值强制转换为此类型，并将结果强制转换为规范形式。

请务必注意，如果此方法失败，它将已在输入 PROPVARIANT 结构上调用 PropVariantClear。 仅当此方法成功时，调用应用程序才负责在不再需要结构时调用 ppropvar 上的 PropVariantClear。

此方法执行的强制也由属性系统在 IPropertyStore：：GetValue 和 IPropertyStore：：SetValue 调用期间执行。 应用程序可能依赖于属性系统来执行强制，或者可以使用此方法在应用程序选择时执行强制。

强制通过四个步骤执行，如下所示：

1. 以下值将 VT_EMPTY转换为 。
   • 类型的 VT_NULL值。
   • 或 类型的 VT_LPWSTR, VT_BSTR值， VT_LPSTR 其指针为 NULL。
   • 类型 VT_LPWSTR, VT_BSTR为 、或 VT_LPSTR 的值为空或完全由空格组成。
   • 类型 VT_FILETIME 在 1601/01/02 午夜之前的值。
2. 如果值不是步骤 1 之后的类型 VT_EMPTY ，则会将其转换为属性说明指定的类型。 可以使用 IPropertyDescription：：GetPropertyType 获取属性说明的类型。 有关属性架构如何影响属性说明类型的信息，请参阅 typeInfo 。 转换的执行方式如下：
   • 使用 InitPropVariantFromStringAsVector 将类型 、 或 VT_LPSTR 的值VT_LPWSTR, VT_BSTR转换为 VT_VECTOR | VT_LPWSTR 。
   • 所有其他转换均使用 PropVariantChangeType 执行
3. 在步骤 2 和 3 之后，根据值的类型强制转换为规范形式。 下表汇总了规范形式。

   值类型	规范形式
   VT_EMPTY	始终是规范的。
   VT_LPWSTR	无前导空格或尾随空格。 字符串为非空。 字符串为非 NULL。 例如 L"Alice"。 如果这是一个树属性 (也就是说，如果 typeInfo 元素的 isTreeProperty 属性) 为 TRUE ，则它不得 (/) 具有前导斜杠或尾随正斜杠，文本和正斜杠之间不得有空格，并且不得有两个连续的正斜杠 (/) 。 例如： L"Friend/Bob" 强制删除不必要的字符，如果没有内容，则会导致 VT_EMPTY 出现。
   VT_VECTOR | VT_LPWSTR	向量中的每个字符串都必须遵守上面列出的 规则 VT_LPWSTR 。 此外，向量必须没有重复项且没有 null 指针。 如果这是一个树属性，则任何值都不能是另一个值的上级值。 例如， L"Friend" 是 L“Friend/Bob”的祖先。 如果没有内容，强制删除重复字符和上级字符，并将导致 VT_EMPTY。

    
4. 如果适用，将针对属性说明类型枚举检查值。 以下检查适用。

   枚举类型	值类型	规范形式
   离散或范围	VT_EMPTY	始终规范
   离散	VT_LPWSTR	该字符串与属性允许的枚举字符串之一匹配。 比较不区分大小写。 如果没有，请将值转换为 VT_EMPTY。
   离散	Numeric	该数字与属性允许的枚举值之一匹配。 如果没有，请将值转换为 VT_EMPTY。
   离散	VT_VECTOR | VT_LPWSTR	向量中的每个字符串都匹配属性允许的枚举字符串之一。 比较不区分大小写。 如果没有，请从向量中删除该字符串。 如果生成的向量为空，请将值转换为 VT_EMPTY。
   离散	VT_VECTOR | 数字	向量中的每个数字都与属性允许的枚举值之一匹配。 如果没有，请从向量中删除该数字。 如果生成的向量为空，请将值转换为 VT_EMPTY。
   不等	VT_LPWSTR	字符串存在于 属性允许的范围内。 比较区分大小写。 如果没有，请将值转换为 VT_EMPTY。
   不等	Numeric	该数字存在于属性允许的范围内。 如果没有，请将该值转换为VT_EMPTY。
   不等	VT_VECTOR | VT_LPWSTR	向量中的每个字符串都存在于 属性允许的范围内。 比较区分大小写。 如果没有，请从向量中删除该字符串。 如果生成的向量为空，请将值转换为 VT_EMPTY。
   不等	VT_VECTOR |数字	向量中的每个数字都存在于 属性允许的范围内。 如果没有，请从向量中删除该数字。 如果生成的向量为空，请将值转换为VT_EMPTY。

    

要求

另请参阅

IPropertyDescription

属性说明架构