共用方式為


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 之前,您必須使用 CoInitializeOleInitialize 初始化元件物件模型 (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”) :
  • 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 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 公厘”。
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

另請參閱

PSFormatForDisplay

PSFormatPropertyValue

屬性描述架構