PSCoerceToCanonicalValue 関数 (propsys.h)

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

構文

PSSTDAPI PSCoerceToCanonicalValue(
  [in]      REFPROPERTYKEY key,
  [in, out] PROPVARIANT    *ppropvar
);

パラメーター

[in] key

型: REFPROPERTYKEY

値を強制するプロパティを識別する PROPERTYKEY 構造体への参照。

[in, out] ppropvar

型: PROPVARIANT*

エントリには、元の値を含む PROPVARIANT 構造体へのポインターが含まれます。 この関数が正常に返されると、 には正規値が含まれます。

戻り値

種類: HRESULT

可能な戻り値は次のとおりです。

注釈

この関数は、システムの IPropertyDescription::CoerceToCanonicalValue の実装に関するラッパーです。

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

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

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

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

1. 次の値は、VT_EMPTYに変換されます。
   • VT_NULL型の値。
   • ポインターが NULL であるVT_LPWSTR型、VT_BSTR型、またはVT_LPSTR型の値。
   • VT_LPWSTR型、VT_BSTR型、またはVT_LPSTR型の値が空であるか、完全にスペースで構成されます。
   • 1601/01/02 より前のVT_FILETIME型の値。
2. 値がステップ 1 の後VT_EMPTY型でない場合は、プロパティの説明で指定された型に変換されます。 プロパティの説明の型は、 IPropertyDescription::GetPropertyType を呼び出すことによって取得できます。 プロパティ スキーマがプロパティの説明の型にどのように影響するかについては、「 typeInfo」を参照してください。 変換は次のように実行されます。
   • 型VT_LPWSTR、VT_BSTR、またはVT_LPSTRの値は、VT_VECTOR | InitPropVariantFromStringAsVector を使用してVT_LPWSTRします。
   • その他のすべての変換は、PropVariantChangeType を使用して実行されます
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 に変換します。

    

例

次の例は、より大きなプログラムの一部として含めるために、 PSCoerceToCanonicalValue を使用して、PKEY_Keywordsに必要な型に値を強制する方法を示しています。

// PROPVARIANT propvar;
// Assume variable propvar is initialized and valid.

HRESULT hr = PSCoerceToCanonicalValue(PKEY_Keywords, &propvar);

if (SUCCEEDED(hr))
{
    // The conversion succeeded and propvar now is of the correct type for 
    // PKEY_Keywords, or VT_EMPTY.
    PropVariantClear(&propvar);
}
else
{
    // The conversion failed and propvar is now VT_EMPTY.
}

要件

こちらもご覧ください

IPropertyDescription

IShellItem2::GetPropertyStore

PropVariantChangeType

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

typeInfo