PropVariantToStringAlloc 関数 (propvarutil.h)

[アーティクル]
03/01/2024

PROPVARIANT 構造体から文字列プロパティ値を抽出します。

構文

PSSTDAPI PropVariantToStringAlloc(
  [in]  REFPROPVARIANT propvar,
  [out] PWSTR          *ppszOut
);

パラメーター

[in] propvar

型: REFPROPVARIANT

ソース PROPVARIANT 構造体への参照。

[out] ppszOut

種類: PWSTR*

この関数が戻るときに、には、抽出されたプロパティ値 (存在する場合) へのポインターが含まれます。

戻り値

型: HRESULT

この関数が成功すると、 S_OKが返されます。そうでない場合は、HRESULT エラーコードを返します。

注釈

このヘルパー関数は、呼び出し元のアプリケーションが PROPVARIANT が文字列値を保持することを想定している場所で使用されます。

ソース PROPVARIANT の型がVT_LPWSTRまたはVT_BSTR場合、この関数は新しく割り当てられたバッファーに文字列を抽出します。それ以外の場合は、 PROPVARIANT 構造体の値を文字列に変換しようとします。変換できない場合、 PropVariantToStringAlloc はエラーコードを返し、 ppszOut を NULL に設定 します。可能な変換の一覧については、「 PropVariantChangeType 」を参照してください。注: VT_EMPTY は、"" を含む割り当てられたバッファーに正常に変換されます。

呼び出し元のアプリケーションは、 CoTaskMemFree を使用して 、不要になったときに ppszOut が指す文字列を解放します。

PropVariantChangeType によって提供される変換に加えて、PropVariantToStringAlloc には次の特殊なケースが適用されます。

ベクター値 PROPVARIANT は、"; " を使用して各要素を分離することで、文字列に変換されます。たとえば、 PropVariantToStringAlloc は、3 つの整数 {3、1、4} のベクターを文字列 "3" に変換します。1;4". セミコロンは現在のロケールに依存しません。
VT_BLOB、VT_STREAM、VT_STREAMED_OBJECT、およびVT_UNKNOWNの値は、サポートされていないエンコードを使用して文字列に変換されます。この方法で作成された文字列をデコードすることはできず、将来形式が変更される可能性があります。

例

// IPropertyStore *ppropstore;

// Assume variable ppropstore is initialized and valid

PROPVARIANT propvar = {0};

HRESULT hr = ppropstore->GetValue(PKEY_Title, &propvar);

if (SUCCEEDED(hr))

{

    // PKEY_Title is expected to produce a VT_LPWSTR or VT_EMPTY value.

    // PropVariantToStringAlloc will convert VT_EMPTY to "".

    LPWSTR pszTitle;

    hr = PropVariantToString(propvar, &pszTitle);

    if (SUCCEEDED(hr))

    {

        // pszTitle is now valid

    }

    else

    {

        // pszTitle is always NULL

    }

    PropVariantClear(&propvar);

}

要件

要件	値
サポートされている最小のクライアント	WINDOWS XP と SP2、Windows Vista [デスクトップアプリのみ]
サポートされている最小のサーバー	Windows Server 2003 SP1 [デスクトップアプリのみ]
対象プラットフォーム	Windows
ヘッダー	propvarutil.h
Library	Propsys.lib
[DLL]	Propsys.dll (バージョン 6.0 以降)
再頒布可能パッケージ	Windows デスクトップ検索 (WDS) 3.0