IPropertyDescription::CoerceToCanonicalValue メソッド (propsys.h)

  • [アーティクル]

プロパティの説明に従って、値を正規値に強制変換します。

構文

HRESULT CoerceToCanonicalValue(
  [in, out] PROPVARIANT *ppropvar
);

パラメーター

[in, out] ppropvar

型: PROPVARIANT*

エントリには、元の値を含む PROPVARIANT 構造体へのポインターが含まれます。 このメソッドが戻るとき、 には正規値が含まれます。

戻り値

種類: HRESULT

エラー コードがINPLACE_S_TRUNCATEDまたはE_INVALIDARGされていない場合、値の型からプロパティの説明の型への強制適用は不可能であり、 PROPVARIANT 構造体はクリアされています。

次のような結果が得られます。

リターン コード 説明
S_OK
 関数が正常に実行されました。 ppropvar で指定されたプロパティ値が正規形式になりました。
INPLACE_S_TRUNCATED
 ppropvar で指定されたプロパティ値が、切り捨てられた正規形式になりました。
E_INVALIDARG
 ppropvar パラメーターが無効です。 PROPVARIANT 構造体がクリアされました。

注釈

詳細については、プロパティの .propdesc ファイルの typeInfo 要素の type 属性を参照してください。

ほとんどのプロパティの説明では、その値で使用する必要がある型を指定します。 たとえば、System.Title のプロパティの説明では、 System.Title 値で を使用 VT_LPWSTRする必要があることを指定します。 このメソッドは、この型に値を強制し、結果を正規形式に強制します。

このメソッドが失敗した場合、入力 PROPVARIANT 構造体で PropVariantClear が既に呼び出されていることに注意してください。 このメソッドが成功した場合にのみ、構造体が不要になったときに ppropvar で PropVariantClear を呼び出すアプリケーションが呼び出されます。

このメソッドによって実行される強制は、IPropertyStore::GetValue 呼び出しと IPropertyStore::SetValue 呼び出し中にプロパティ システムによっても実行されます。 アプリケーションは、強制を実行するプロパティ システムに依存する場合があります。また、このメソッドを使用して、アプリケーションが選択した時点で強制型変換を実行することもできます。

強制は、次の 4 つの手順で実行されます。

  1. 次の値は に VT_EMPTY変換されます。
    • 型 VT_NULLの値。
    • 型 VT_LPWSTR, VT_BSTR、または VT_LPSTR ポインターが NULL の値。
    • 型 VT_LPWSTR, VT_BSTRの値。または VT_LPSTR 空白であるか、完全にスペースで構成されます。
    • 午前 0 時 1601/01/02 より前の型 VT_FILETIME の値。
  2. 値がステップ 1 以降の型 VT_EMPTY でない場合は、プロパティの説明で指定された型に変換されます。 プロパティの説明の型は、 IPropertyDescription::GetPropertyType を使用して取得できます。 プロパティスキーマがプロパティの説明の型にどのように影響するかについては、「 typeInfo 」を参照してください。 変換は次のように実行されます。
  3. 手順 2 と 3 の後、値は型に基づいて正規形式に強制されます。 正規形式の概要を次の表に示します。
    値の型 標準フォーム
    VT_EMPTY 常に正規。
    VT_LPWSTR
    • 先頭または末尾にスペースがありません。 文字列が空でない。 文字列は NULL 以外です。 たとえば、「 L"Alice" 」のように入力します。
    • これがツリー プロパティである場合 (つまり、typeInfo 要素の isTreeProperty 属性が TRUE の場合)、先頭または末尾にスラッシュ (/) を含めることはできません。また、テキストとスラッシュの間にスペースを含めることはできません。また、2 つの連続するスラッシュ (/) を含めることはできません。 たとえば、L"Friend/Bob" のように指定します。
    • 強制変換は不要な文字を削除し、コンテンツが存在しない場合に発生 VT_EMPTY します。
    VT_VECTOR | VT_LPWSTR
    • ベクター内の各文字列は、上記の規則 VT_LPWSTR に従う必要があります。 さらに、ベクターには重複がなく、null ポインターを持たない必要があります。
    • これがツリー プロパティの場合、値を別の値の先祖にすることはできません。 たとえば、 L"Friend" は L"Friend/Bob" の先祖です。
    • コンテンツがない場合は、強制強制によって重複するおよび先祖の文字が削除され、 が発生 VT_EMPTYします。
     
  4. 該当する場合は、プロパティの説明の型列挙に対して値がチェックされます。 次のチェックが適用されます。
    列挙型 値の型 標準フォーム
    不連続または範囲 VT_EMPTY 常に正規
    離散 VT_LPWSTR 文字列は、 プロパティに対して許可されている列挙文字列の 1 つと一致します。 比較では、大文字と小文字は区別されません。 そうでない場合は、値を に VT_EMPTY変換します。
    離散 数値 この数値は、 プロパティに対して許可されている列挙値のいずれかと一致します。 そうでない場合は、値を に VT_EMPTY変換します。
    離散 VT_VECTOR | VT_LPWSTR ベクター内の各文字列は、 プロパティに対して許可されている列挙文字列のいずれかと一致します。 比較では、大文字と小文字は区別されません。 そうでない場合は、その文字列をベクターから削除します。 結果のベクターが空の場合は、値を に VT_EMPTY変換します。
    離散 VT_VECTOR | 数値 ベクター内の各数値は、 プロパティに対して許可されている列挙値のいずれかと一致します。 そうでない場合は、その数値をベクターから削除します。 結果のベクターが空の場合は、値を に VT_EMPTY変換します。
    範囲 VT_LPWSTR 文字列は、 プロパティに対して許可されている範囲内に存在します。 比較では大文字と小文字が区別されます。 そうでない場合は、値を に VT_EMPTY変換します。
    範囲 数値 この数は、 プロパティに対して許可されている範囲内に存在します。 そうでない場合は、値を VT_EMPTY に変換します。
    範囲 VT_VECTOR | VT_LPWSTR ベクター内の各文字列は、 プロパティに対して許可されている範囲内に存在します。 比較では大文字と小文字が区別されます。 そうでない場合は、その文字列をベクターから削除します。 結果のベクターが空の場合は、値を に VT_EMPTY変換します。
    範囲 VT_VECTOR |数値 ベクター内の各数値は、 プロパティに許可されている範囲内に存在します。 そうでない場合は、その数値をベクターから削除します。 結果のベクターが空の場合は、値を VT_EMPTY に変換します。
     

要件

要件 値
サポートされている最小のクライアント Windows Vista [デスクトップ アプリのみ]
サポートされている最小のサーバー Windows Server 2008 [デスクトップ アプリのみ]
対象プラットフォーム Windows
ヘッダー propsys.h

こちらもご覧ください

IPropertyDescription

プロパティの説明スキーマ