PSFormatForDisplayAlloc 函数 (propsys.h)

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

语法

PSSTDAPI PSFormatForDisplayAlloc(
  [in]  REFPROPERTYKEY        key,
  [in]  REFPROPVARIANT        propvar,
  [in]  PROPDESC_FORMAT_FLAGS pdff,
  [out] PWSTR                 *ppszDisplay
);

参数

[in] key

类型： REFPROPERTYKEY

对 PROPERTYKEY 的引用，该属性命名要检索其值的属性。

[in] propvar

类型： REFPROPVARIANT

对 PROPVARIANT 结构的引用，该结构包含 属性的类型和值。

[in] pdff

类型： PROPDESC_FORMAT_FLAGS

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

[out] ppszDisplay

类型： PWSTR*

函数返回时，包含指向以 null 结尾的 Unicode 字符串表示形式的所请求属性值的指针。

返回值

类型： HRESULT

返回以下值之一。

返回代码	说明
S_OK	已成功创建格式化字符串。 S_OK 与空返回字符串一起表示存在空输入字符串或格式化为空字符串的非空值。
S_FALSE	未创建格式化字符串。 S_FALSE与空返回字符串一起指示空字符串来自VT_EMPTY。
E_OUTOFMEMORY	指示分配失败。

注解

此函数调用架构子系统实现 的 IPropertySystem：：FormatForDisplayAlloc。 该调用提供属性值的 Unicode 字符串表示形式，以及基于一个或多个 PROPDESC_FORMAT_FLAGS的其他格式。 如果架构子系统无法识别 PROPERTYKEY ， 则 IPropertySystem：：FormatForDisplayAlloc 会尝试根据值的 VARTYPE 设置值的格式。

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

函数通过 CoTaskMemAlloc 分配内存，并通过 ppszDisplay 参数返回指向该内存的指针。 当不再需要该资源时，调用应用程序必须使用 CoTaskMemFree 释放该资源。

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

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

通常， PROPDESC_FORMAT_FLAGS 用于修改属性说明规定的格式。

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

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

属性	格式
System.FileAttributes	以下文件属性转换为字母并追加以创建字符串 (例如值 0x1801 (FILE_ATTRIBUTE_READONLY |FILE_ATTRIBUTE_COMPRESSED |FILE_ATTRIBUTE_OFFLINE) 转换为“RCO”) ： FILE_ATTRIBUTE_READONLY (0x00000001) - “R” FILE_ATTRIBUTE_SYSTEM (0x00000004) - “S” FILE_ATTRIBUTE_ARCHIVE (0x00000020) -'A' FILE_ATTRIBUTE_COMPRESSED (0x00000800) - “C” FILE_ATTRIBUTE_ENCRYPTED (0x00004000) - “E” FILE_ATTRIBUTE_OFFLINE (0x00001000) - “O” FILE_ATTRIBUTE_NOT_CONTENT_INDEXED (0x00002000) - “I”
System.Photo.ISOSpeed	例如，“ISO-400”。
System.Photo.ShutterSpeed	使用以下公式将 APEX 值转换为曝光时间： Exposure_time = 2^(-APEX_value) 例如，“2 秒”。或“1/125 秒”。
System.Photo.ExposureTime	例如，“2 秒”。或“1/125 秒”。
System.Photo.Aperture	使用以下公式将 APEX 值转换为 F 数： F_Number = 2^(APEX_Value / 2) 例如“f/5.6”。
System.Photo.FNumber	例如“f/5.6”。
System.Photo.SubjectDistance	例如，“15 m”或“250 mm”。
System.Photo.FocalLength	例如，“50 mm”。
System.Photo.FlashEnergy	例如，“500 bpcs”。
System.Photo.ExposureBias	例如，“-2 步”、“0 步”或“+3 步”。
System.Computer.DecoratedFreeSpace	例如，“105 MB 可用，13.2 GB”。
System.ItemType	例如，“应用程序”或“JPEG 映像”。
System.ControlPanel.Category	例如，“外观和个性化”。
System.ComputerName	例如，“LITWARE05 (此计算机) ”或“testbox07”。

 

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

值的类型	格式
VT_BOOLEAN	不支持。
VT_FILETIME	由 PROPDESC_FORMAT_FLAGS 和当前区域设置指定的日期/时间字符串。 默认PDFF_SHORTTIME和PDFF_SHORTDATE。 例如，“2006/11/13 3：22 PM”。
数字 VARTYPE	当前区域设置中的十进制字符串。 例如，“42”。
VT_LPWSTR或其他	转换为字符串。 “\r”、“\t”或“\n”序列将替换为单个空格。
VT_VECTOR |什么	分号分隔值。 无论区域设置如何，都使用分号。

 

示例

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

PROPVARIANT propvar;

HRESULT hr = InitPropVariantFromUInt32(RATING_THREE_STARS_SET, &propvar);

if (SUCCEEDED(hr))
{
    PWSTR pszValue;

    hr = PSFormatForDisplayAlloc(PKEY_Rating, propvar, PDFF_DEFAULT, &pszValue);

    if (SUCCEEDED(hr))
    {
        // pszValue contains a formatted string similar to "3 stars".
         CoTaskMemFree(pszValue);
    }
    PropVariantClear(&propvar);
}

要求

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

另请参阅

PSFormatForDisplay

PSFormatPropertyValue

属性说明架构