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
この関数は、これらの値のいずれかを返すことができます。
| リターン コード | 説明 |
|---|---|
|
値が抽出され、結果バッファーが NULL で終了しました。 |
|
バッファー領域が不足しているため、コピー操作が失敗しました。 変換先バッファーには、意図した結果の、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 |