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

プロパティ文字列に適用する形式を指定する 1 つ以上のフラグ。 使用可能な値については 、「PROPDESC_FORMAT_FLAGS 」を参照してください。

[out] ppszDisplay

種類: PWSTR*

関数が戻るときに、 には、null で終わる、要求されたプロパティ値の Unicode 文字列表現へのポインターが含まれます。

戻り値

型: HRESULT

次のいずれかの値を返します。

注釈

この関数は、スキーマ サブシステムの IPropertySystem::FormatForDisplayAlloc の実装を呼び出します。 この呼び出しでは、プロパティ値の Unicode 文字列表現が提供され、1 つ以上の PROPDESC_FORMAT_FLAGSに基づいて書式設定が追加されます。 PROPERTYKEY がスキーマ サブシステムによって認識されない場合、IPropertySystem::FormatForDisplayAlloc は値の VARTYPE に従って値の書式設定を試みます。

PSFormatForDisplayAlloc を呼び出す前に、CoInitialize または OleInitialize を使用してコンポーネント オブジェクト モデル (COM) を初期化する必要があります。

関数は 、CoTaskMemAlloc を介してメモリを割り当て、 ppszDisplay パラメーターを使用してそのメモリへのポインターを返します。 呼び出し元のアプリケーションでは 、不要になったときに CoTaskMemFree を使用してそのリソースを解放する必要があります。

この関数の目的は、データをユーザーに表示するのに適した文字列に変換することです。 値は、現在のロケール、ユーザーの言語、 PROPDESC_FORMAT_FLAGS、およびプロパティ キーで指定されたプロパティの説明に従って書式設定されます。 プロパティ記述スキーマが値の書式設定にどのように影響するかについては、次のトピックを参照してください。

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

出力文字列には Unicode 方向文字を含めることができます。 これらの非スペーシング文字は Unicode 双方向アルゴリズムに影響を与え、左から右 (LTR) 言語が右から左 (RTL) ウィンドウに描画されたとき、または LTR ウィンドウに RTL が描画されたときに値が正しく表示されるようにします。 これらの文字には、次のものが含まれます。 "\x200e", "\x200f", "\x202a", "\x202b", "\x202c", "\x202d", "\x202e".

次のプロパティは特殊な形式を使用し、 PROPDESC_FORMAT_FLAGSの影響を受けません。 引用されている例は、現在のロケールが英語に設定されている文字列に対するものです。通常、出力は、特に記載されている場合を除いてローカライズされます。

プロパティ キーが登録されているプロパティ スキーマのプロパティの説明に対応していない場合、この関数は値の型に基づいて形式を選択します。

例

大規模なプログラムの一部として含める次の例は、 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);
}

要件

こちらもご覧ください

PSFormatForDisplay

PSFormatPropertyValue

プロパティの説明スキーマ