PSCoerceToCanonicalValue 函数 (propsys.h)

项目
03/01/2024

根据属性说明将属性的值转换为规范值。

语法

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

参数

[in] key

类型： REFPROPERTYKEY

对 PROPERTYKEY 结构的引用，该结构标识要强制其值的属性。

[in, out] ppropvar

类型： PROPVARIANT*

在条目上，包含指向包含原始值的 PROPVARIANT 结构的指针。此函数成功返回时，包含规范值。

返回值

类型： HRESULT

可能的返回值包括：

返回代码	说明
S_OK	函数成功。 ppropvar 指定的属性值现在采用规范形式。
INPLACE_S_TRUNCATED	ppropvar 指定的属性值现在采用截断的规范形式。
E_INVALIDARG	ppropvar 参数无效。 PROPVARIANT 结构已被清除。
TYPE_E_TYPEMISMATCH	无法强制从值的类型到属性说明的类型。 PROPVARIANT 结构已被清除。
任何其他失败代码	无法强制从值的类型到属性说明的类型。 PROPVARIANT 结构已被清除。

注解

此函数是系统实现 IPropertyDescription：：CoerceToCanonicalValue 的包装器。

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

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

在调用 IPropertyStore：：GetValue 和 IPropertyStore：：SetValue 期间，属性系统也会执行此函数执行的强制操作。应用程序可以依赖于属性系统来执行强制操作，也可以使用此函数在应用程序选择时执行强制操作。

强制操作分四个步骤执行，如下所示：

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

如果适用，则根据属性说明类型枚举检查值。下表中的检查适用。

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

示例

以下示例将作为更大的程序的一部分包含，演示如何使用 PSCoerceToCanonicalValue 将值强制转换为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.
}

要求

要求	值
最低受支持的客户端	Windows XP SP2、Windows Vista [仅限桌面应用]
最低受支持的服务器	Windows Server 2003 SP1 [仅限桌面应用]
目标平台	Windows
标头	propsys.h
Library	Propsys.lib
DLL	Propsys.dll (6.0 或更高版本)
可再发行组件	Windows 桌面搜索 (WDS) 3.0