PropVariantToStringWithDefault 関数 (propvarutil.h)

[アーティクル]
08/25/2023

PROPVARIANT 構造体の文字列プロパティ値を抽出します。値が存在しない場合は、指定された既定値が返されます。

構文

PSSTDAPI_(PCWSTR) PropVariantToStringWithDefault(
  [in] REFPROPVARIANT propvarIn,
  [in] LPCWSTR        pszDefault
);

パラメーター

[in] propvarIn

型: REFPROPVARIANT

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

[in] pszDefault

種類: LPCWSTR

現在値が存在しない場合に使用する、既定の Unicode 文字列値へのポインター。 NULL を指定できます。

戻り値

種類: PCWSTR

文字列値または既定値、または既定値を返します。

注釈

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

ソース PROPVARIANT に型VT_LPWSTRまたはVT_BSTRがある場合、このヘルパー関数はソース PROPVARIANT 内の値へのポインターを返します。ソース PROPVARIANT に型VT_EMPTYがある場合、または変換できない場合、 PropVariantToStringWithDefault は pszDefault によって提供される既定値を返します。

この関数は、パラメーターで指定されたデータへのポインターを返します。したがって、アプリケーションは、結果が使用されなくなるまで、パラメーターに指定されたデータが有効なままであることを確認する必要があります。

例

次の例は、より大きなプログラムの一部として含めるために、 PropVariantToStringWithDefault を使用して 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.
     // The application developer decided to treat VT_EMPTY or invalid values as ""
     PCWSTR pszTitle = PropVariantToStringWithDefault(propvar, L"");
     // pszTitle is now valid.
     PropVariantClear(&propvar);
}
// ... later in the program ...
hr = ppropstore->GetValue(PKEY_Comment, &propvar);
if (SUCCEEDED(hr))
{
         // PKEY_Comment is expected to produce a VT_LPWSTR or VT_EMPTY value.
         // The application developer decided to treat VT_EMPTY as NULL
         PCWSTR pszComment = PropVariantToStringWithDefault(propvar, NULL);
         if (pszComment)
         {
                 // pszComment is valid
         }
         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