PSFormatPropertyValue 函数 (propsys.h)

获取存储在属性存储中的属性值的格式化 Unicode 字符串表示形式。 此函数为输出字符串分配内存。

语法

PSSTDAPI PSFormatPropertyValue(
  [in]  IPropertyStore        *pps,
  [in]  IPropertyDescription  *ppd,
  [in]  PROPDESC_FORMAT_FLAGS pdff,
  [out] LPWSTR                *ppszDisplay
);

参数

[in] pps

类型： IPropertyStore*

指向 IPropertyStore 的指针，该存储区表示从中获取属性值的属性存储。

[in] ppd

类型： IPropertyDescription*

指向 IPropertyDescription 的指针，该指针表示正在检索其值的属性。

[in] pdff

类型： PROPDESC_FORMAT_FLAGS

指定要应用于属性字符串的格式的一个或多个 PROPDESC_FORMAT_FLAGS 。 有关可能的值 ，请参阅PROPDESC_FORMAT_FLAGS 。

[out] ppszDisplay

类型： LPWSTR*

当函数返回时，包含一个指针，指向以 null 结尾的 Unicode 字符串格式的值。

返回值

类型： HRESULT

如果此函数成功，则返回 S_OK。 否则，将返回 HRESULT 错误代码。

注解

此函数使用 ppd 参数调用 IPropertyDescription：：FormatForDisplay。 该调用提供属性值的 Unicode 字符串表示形式，以及基于一个或多个 PROPDESC_FORMAT_FLAGS的其他格式。

在调用 PSFormatPropertyValue 之前，必须使用 CoInitialize 或 OleInitialize 初始化组件对象模型 (COM) 。

函数分配内存，并在 ppszDisplay 中返回指向该内存的指针。 当不再需要 ppszDisplay 指定的字符串时，调用应用程序必须使用 CoTaskMemFree 释放该字符串。

此函数的目的是将数据转换为适合向用户显示的字符串。 根据当前区域设置、用户语言、 PROPDESC_FORMAT_FLAGS以及属性键指定的属性说明设置值的格式。 有关属性说明架构如何影响值格式的信息，请参阅以下主题：

• displayInfo
• stringFormat
• booleanFormat
• numberFormat
• NMDATETIMEFORMAT
• enumeratedList

输出字符串可以包含 Unicode 方向字符。 这些非节奏字符会影响 Unicode 双向算法，以便在从右到右 (LTR) 语言在从右到左 (RTL) 窗口中绘制 RTL 时正确显示值。 这些字符包括以下内容： "\x200e", "\x200f", "\x202a", "\x202b", "\x202c", "\x202d", "\x202e".

以下属性使用特殊格式，不受 PROPDESC_FORMAT_FLAGS影响。 请注意，引用的示例适用于当前区域设置设置为英语的字符串;通常，输出是本地化的，除非有指出。

如果属性键不对应于任何已注册的属性架构中的属性说明，则此函数将根据值的类型选择格式。

示例

以下示例将作为更大程序的一部分包含，演示如何使用 PSFormatPropertyValue 设置分级值的格式。

// IPropertyStore *pStore;
// Assume the variable pps is initialized and valid.
IPropertyDescription *pPropDesc;

HRESULT hr = PSGetPropertyDescription(PKEY_Rating, IID_PPV_ARGS(&pPropDesc));

if (SUCCEEDED(hr))
{
    PWSTR pszValue;

    hr = PSFormatPropertyValue(pStore, pPropDesc, PDFF_DEFAULT, &pszValue);

    if (SUCCEEDED(hr))
    {
        // pszValue contains a formatted string similar to "3 stars".
        CoTaskMemFree(pszValue);
    }
    pPropDesc->Release();
}

要求

另请参阅

PSFormatForDisplay

PSFormatForDisplayAlloc

属性说明架构