IPropertyDescription：：CoerceToCanonicalValue 方法 (propsys.h)

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

语法

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

[in, out] ppropvar

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

类型： HRESULT

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

可能的结果包括：

返回代码	说明
S_OK	函数成功。 ppropvar 指定的属性值现在采用规范形式。
INPLACE_S_TRUNCATED	ppropvar 指定的属性值现在采用截断的规范形式。
E_INVALIDARG	ppropvar 参数无效。已清除 PROPVARIANT 结构。

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

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

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

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

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

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

在步骤 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`。

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

枚举类型	值类型	规范形式
离散或范围	`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。