PSFormatForDisplay 函式 (propsys.h)

取得 儲存在 PROPVARIANT 結構中之屬性值的格式化 Unicode 字串表示。 呼叫端負責配置輸出緩衝區。

語法

PSSTDAPI PSFormatForDisplay(
  [in]  REFPROPERTYKEY        propkey,
  [in]  REFPROPVARIANT        propvar,
  [in]  PROPDESC_FORMAT_FLAGS pdfFlags,
  [out] LPWSTR                pwszText,
  [in]  DWORD                 cchText
);

參數

[in] propkey

類型： REFPROPERTYKEY

PROPERTYKEY 的參考，這個屬性會命名正在擷取其值的屬性。

[in] propvar

類型： REFPROPVARIANT

包含屬性型別和值的 PROPVARIANT 結構的參考。

[in] pdfFlags

類型： PROPDESC_FORMAT_FLAGS

旗標，指定要套用至屬性字串的格式。 如需可能的值 ，請參閱PROPDESC_FORMAT_FLAGS 。

[out] pwszText

類型： LPWSTR

當函式傳回時，會包含格式化值的指標，做為 Null 終止的 Unicode 字串。 呼叫端應用程式負責在呼叫 PSFormatForDisplay 之前配置緩衝區的記憶體。

[in] cchText

類型： DWORD

指定 WCHARs 中 pwszText 的緩衝區長度，包括終止 Null 字元。

傳回值

類型： HRESULT

傳回下列其中一個值。

傳回碼	描述
S_OK	已成功建立格式化字串。
S_FALSE	未建立格式化字串。 S_FALSE表示從VT_EMPTY產生的空字串。
E_OUTOFMEMORY	表示配置失敗。

備註

此函式會呼叫架構子系統的 IPropertySystem：：FormatForDisplay 實作。 該呼叫會根據一或多個 PROPDESC_FORMAT_FLAGS，提供屬性值的 Unicode 字串表示法，以及額外的格式設定。 如果架構子系統無法辨識 PROPERTYKEY，IPropertySystem：：FormatForDisplay 會嘗試根據值的 VARTYPE 來格式化值。

您必須先使用 CoInitialize 或 OleInitialize 初始化元件物件模型 (COM) ，才能呼叫 PSFormatPropertyValue。

此函式的目的是將數據轉換成適合向用戶顯示的字串。 此值會根據目前的地區設定、用戶的語言、 PROPDESC_FORMAT_FLAGS和屬性索引鍵所指定的屬性描述來格式化。 如需屬性描述架構如何影響值格式的資訊，請參閱下列主題：

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

一般而言， PROPDESC_FORMAT_FLAGS 是用來修改屬性描述所指定的格式。

輸出字串可以包含 Unicode 方向字元。 這些非步調字元會影響 Unicode 雙向演算法，以便在從左至右 (LTR) 語言繪製在由右至左 (RTL) 視窗時，或會在 LTR 視窗中繪製 RTL 時正確顯示值。 這些字元包括下列各項： "\x200e", "\x200f", "\x202a", "\x202b", "\x202c", "\x202d", "\x202e".

下列屬性會使用特殊格式，而且不受 PROPDESC_FORMAT_FLAGS影響。 請注意，所參考的範例適用於目前地區設定設定為英文的字串;一般而言，輸出會當地語系化，但已注注除外。

屬性	[格式]
System.FileAttributes	下列檔案屬性會轉換成字母，並附加以建立字串 (例如，0x1801的值會轉換成 “RCO”) ：
	FILE_ATTRIBUTE_READONLY- 'R'
	FILE_ATTRIBUTE_SYSTEM - 'S'
	FILE_ATTRIBUTE_ARCHIVE -'A'
	FILE_ATTRIBUTE_COMPRESSED - 'C'
	FILE_ATTRIBUTE_ENCRYPTED - 'E'
	FILE_ATTRIBUTE_OFFLINE - 'O'
	FILE_ATTRIBUTE_NOT_CONTENT_INDEXED - 'I'
System.Photo.ISOSpeed	例如，“ISO-400”。
System.Photo.ShutterSpeed	APEX 值會使用此公式轉換成曝光時間： Exposure_time = 2^(-APEX_value) 例如，“2 秒”。或 「1/125 sec.」。。
System.Photo.ExposureTime	例如，“2 秒”。或 「1/125 sec」。。
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 step”、“0 step” 或 “+3 step”。
System.Computer.DecoratedFreeSpace	例如，「105 MB 免費 13.2 GB」。
System.ItemType	例如，“Application” 或 “JPEG Image”。
System.ControlPanel.Category	例如，「外觀和個人化」。
System.ComputerName	例如，“LITWARE05 (这部计算机) ” 或 “testbox07”。

 

如果屬性索引鍵未對應至任何已註冊屬性架構中的屬性描述，則此函式會根據值的型別來選擇格式。

值的型別	格式
VT_BOOLEAN	不支援。
VT_FILETIME	依 PROPDESC_FORMAT_FLAGS 和目前地區設定所指定的日期/時間字串。 PDFF_SHORTTIME和PDFF_SHORTDATE是預設值。 例如，“11/13/2006 3：22 PM”。
數值 VARTYPE	目前地區設定中的十進位字串。 例如，“42”。
VT_LPWSTR或其他	轉換成字串。 “\r”、“\t” 或 “\n” 序列會取代為單一空格。
VT_VECTOR |什麼	分號分隔值。 不論地區設定為何，都會使用分號。

 

範例

下列範例要包含在較大的程式中，示範如何使用 PSFormatForDisplay 來格式化評等值。

PROPVARIANT propvar;

HRESULT hr = InitPropVariantFromUInt32(RATING_THREE_STARS_SET, &propvar);

if (SUCCEEDED(hr))
{
    WCHAR szValue[100];

    hr = PSFormatForDisplay(PKEY_Rating, propvar, PDFF_DEFAULT, szValue, ARRAYSIZE(szValue));

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

規格需求

需求	值
最低支援的用戶端	Windows Vista [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2008 [僅限傳統型應用程式]
目標平台	Windows
標頭	propsys.h
程式庫	Propsys.lib
Dll	Propsys.dll (6.0 版或更新版本)
可轉散發套件	Windows 桌面搜尋 (WDS) 3.0

另請參閱

PSFormatForDisplayAlloc

PSFormatPropertyValue

屬性描述架構