PropVariantToStrRet 関数 (propvarutil.h)
PROPVARIANT 構造体から文字列を抽出し、STRRET 構造体に配置します。
構文
PSSTDAPI PropVariantToStrRet(
[in] REFPROPVARIANT propvar,
[out] STRRET *pstrret
);
パラメーター
[in] propvar
型: REFPROPVARIANT
ソース PROPVARIANT 構造体への参照。
[out] pstrret
種類: STRRET*
STRRET 構造体を指します。 この関数が戻ると、構造体は、抽出された文字列のコピーを格納するように初期化されています。
戻り値
種類: HRESULT
この関数が成功すると、 S_OKが返されます。 そうでない場合は、HRESULT エラー コードを返します。
注釈
このヘルパー関数は、 PROPVARIANT 構造体の文字列値を STRRET 構造体に変換するアプリケーションで使用されます。 たとえば、 IShellFolder::GetDisplayNameOf を実装するアプリケーションでは、この関数が役立つ場合があります。
ソース PROPVARIANT に型VT_LPWSTRまたはVT_BSTRがある場合、この関数は文字列を抽出して STRRET 構造体に配置します。 それ以外の場合は、 PROPVARIANT 構造体の値を文字列に変換しようとします。 変換できない場合、 PropVariantToString はエラー コードを返します。 可能な変換の一覧については、「 PropVariantChangeType 」を参照してください。 注意として、VT_EMPTYは正常に "" に変換されます。
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_FileName, &propvar);
if (SUCCEEDED(hr))
{
// PKEY_FileName is expected to produce a VT_LPWSTR or VT_EMPTY value.
// PropVariantToStrRet will convert VT_EMPTY to "".
// If this were an implementation of IShellFolder::GetDisplayNameOf, strName would be a parameter and the caller would free the memory associated with the STRRET
STRRET strName;
hr = PropVariantToStrRet(propvar, &strName);
if (SUCCEEDED(hr))
{
// strName is now valid
if (strName.uType == STRRET_WSTR)
{
CoTaskMemFree(strName.pOleStr);
}
}
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 |