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 。
[out] ppszDisplay
類型： PWSTR*
當函式傳回時，包含所要求屬性值之 Null 終止 Unicode 字串表示的指標。
傳回值
類型： HRESULT
傳回下列其中一個值。
| 傳回碼 | 描述 |
|---|---|
|
已成功建立格式化字串。 S_OK 與空傳回字串一起表示有空的輸入字串或格式化為空字串的非空白值。 |
|
未建立格式化字串。 S_FALSE與空傳回字串一起表示空字串是由VT_EMPTY所產生。 |
|
表示配置失敗。 |
備註
此函式會呼叫架構子系統的 IPropertySystem：：FormatForDisplayAlloc 實作。 該呼叫會提供屬性值的 Unicode 字串表示，並根據一或多個 PROPDESC_FORMAT_FLAGS提供額外的格式設定。 如果架構子系統無法辨識 PROPERTYKEY，IPropertySystem：：FormatForDisplayAlloc 會嘗試根據值的 VARTYPE 來格式化值。
呼叫 PSFormatForDisplayAlloc 之前，您必須使用 CoInitialize 或 OleInitialize 初始化元件物件模型 (COM) 。
函式會透過 CoTaskMemAlloc 配置記憶體，並透過 ppszDisplay 參數傳回該記憶體的指標。 呼叫的應用程式必須在不再需要資源時使用 CoTaskMemFree 來釋放該資源。
此函式的目的是將數據轉換成適合向用戶顯示的字串。 此值會根據目前的地區設定、用戶的語言、 PROPDESC_FORMAT_FLAGS和屬性索引鍵所指定的屬性描述來格式化。 如需屬性描述架構如何影響值格式的資訊，請參閱下列主題：
一般而言， PROPDESC_FORMAT_FLAGS 是用來修改屬性描述所指定的格式。輸出字串可以包含 Unicode 方向字元。 這些非步調字元會影響 Unicode 雙向演算法，以便在從左至右 (LTR) 語言在由右至左 (RTL) 視窗上繪製時，或是在 LTR 視窗上繪製 RTL 時正確顯示值。 這些字元包括下列各項： "\x200e", "\x200f", "\x202a", "\x202b", "\x202c", "\x202d", "\x202e".
下列屬性使用特殊格式，而且不受 PROPDESC_FORMAT_FLAGS影響。 請注意，所參考的範例適用於目前地區設定設為英文的字串;一般而言，輸出會當地語系化，但未加以註標。
| 屬性 | [格式] |
|---|---|
| System.FileAttributes | 下列檔案屬性會轉換成字母，並附加以建立字串 (例如，0x1801 (FILE_ATTRIBUTE_READONLY 的值 |FILE_ATTRIBUTE_COMPRESSED |FILE_ATTRIBUTE_OFFLINE) 转换为 “RCO”) ：
|
| System.Photo.ISOSpeed | 例如，“ISO-400”。 |
| System.Photo.ShutterSpeed |
APEX 值會使用此公式轉換成曝光時間：
例如，“2 秒”。或 「1/125 sec.」。。 |
| System.Photo.ExposureTime | 例如，“2 秒”。或 「1/125 sec」。。 |
| System.Photo.Aperture |
APEX 值會使用此公式轉換成 F 數位：
例如，“f/5.6”。 |
| System.Photo.FNumber | 例如，“f/5.6”。 |
| System.Photo.SubjectDistance | 例如，“15 m” 或 “250 mm”。 |
| System.Photo.FocalLength | 例如，“50 公厘”。 |
| 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 |什麼 | 分號分隔值。 不論地區設定為何，都會使用分號。 |
範例
下列範例要包含在較大的程式中，示範如何使用 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 |
| 程式庫 | Propsys.lib |
| Dll | Propsys.dll (6.0 版或更新版本) |
| 可轉散發套件 | Windows 桌面搜尋 (WDS) 3.0 |