次の方法で共有

PropVariantToString 関数 (propvarutil.h)

  • [アーティクル]

PROPVARIANT 構造体から文字列値を抽出します。

構文

PSSTDAPI PropVariantToString(
  [in]  REFPROPVARIANT propvar,
  [out] PWSTR          psz,
  [in]  UINT           cch
);

パラメーター

[in] propvar

型: REFPROPVARIANT

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

[out] psz

種類: PWSTR

文字列バッファーを指します。 この関数が返されると、バッファーは NULL で終わる Unicode 文字列値で初期化されます。

[in] cch

型: UINT

psz が指すバッファーのサイズ (文字単位)。

戻り値

種類: HRESULT

この関数は、これらの値のいずれかを返すことができます。

リターン コード 説明
S_OK
 値が抽出され、結果バッファーが NULL で終了しました。
STRSAFE_E_INSUFFICIENT_BUFFER
 バッファー領域が不足しているため、コピー操作が失敗しました。 変換先バッファーには、意図した結果の、null で終わる切り捨てられたバージョンが含まれています。 切り捨てが許容される状況では、これは必ずしもエラー状態と見なされない場合があります。
その他のエラー値
 何らかの理由で抽出に失敗しました。

解説

このヘルパー関数は、呼び出し元アプリケーションが PROPVARIANT が文字列値を保持することを想定している場所で使用されます。 たとえば、プロパティ ストアから値を取得するアプリケーションでは、これを使用して、文字列プロパティの文字列値を安全に抽出できます。

ソース PROPVARIANT の型がVT_LPWSTRまたは VT_BSTRの場合、この関数は文字列を抽出し、指定されたバッファーに配置します。 それ以外の場合は、 PROPVARIANT 構造体の値を文字列に変換しようとします。 変換できない場合、 PropVariantToString はエラー コードを返し、 psz を '\0' に設定します。 可能な変換の一覧については、「 PropVariantChangeType 」を参照してください。 注意として、 VT_EMPTY は正常に "" に変換されます。

終端の NULL に加えて、最大 cch-1 文字は psz が指すバッファーに書き込まれます。 ソース PROPVARIANT の値がバッファーに収まるよりも長い場合は、文字列の切り捨てられた NULL 終了コピーがバッファーに書き込まれ、この関数は STRSAFE_E_INSUFFICIENT_BUFFERを返します。 結果の文字列は常に NULL で終了します。

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

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

例

より大きなプログラムの一部として含める次の例では、 PropVariantToString を使用して PROPVARIANT の文字列値にアクセスする方法を示します。

// 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.

    // PropVariantToString will convert VT_EMPTY to "".

    // The application decided that it only needs the first 127 characters of the title, so the buffer 

    // has size 128 to account for the terminating NULL.

    WCHAR szTitle[128];

    hr = PropVariantToString(propvar, szTitle, ARRAYSIZE(szTitle));

    if (SUCCEEDED(hr) || hr == STRSAFE_E_INSUFFICIENT_BUFFER)

    {

        // szTitle is now valid and contains up to 127 characters from propvar and a terminating NULL

    }

    else

    {

        // the extraction failed

    }

    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

関連項目

InitPropVariantFromString

PropVariantChangeType

PropVariantGetStringElem

PropVariantToBSTR

PropVariantToStringAlloc

PropVariantToStringVector

VariantToString