IConditionFactory
COM公式ドキュメント
クエリ文字列を解析して取得した条件ツリーを作成または解決するためのメソッドを提供します。
解説(Remarks)
StructuredQuerySample では、コンソールから行を読み取り、システムスキーマを使用して解析し、生成された条件ツリーを表示する方法を示しています。
メソッド 4
vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。
別の条件 (このノードのサブノード) の論理否定 (NOT) となる条件ノードを作成します。(IConditionFactory.MakeNot)
| pcSub | ICondition* | in | 否定する ICondition サブノードへのポインター。 |
| fSimplify | BOOL | in | 可能であれば結果を論理的に単純化する場合は TRUE、それ以外の場合は FALSE。クエリビルダーのシナリオでは、通常 fSimplify に VARIANT_FALSE を設定します。 |
| ppcResult | ICondition** | out | 新しい ICondition ノードへのポインターを受け取ります。 |
戻り値
型: HRESULT
このメソッドが成功すると S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。
解説(Remarks)
条件ノードを論理的に単純化すると、通常はより小さく、走査や処理が容易な条件ツリーになります。たとえば、pcSub 自体がサブ条件 C を持つ否定条件である場合、二重否定は論理的に解決され、ppcResult には C が設定されます。単純化を行わない場合、生成されるツリーは NOT — NOT — C のようになります。
条件ツリーに基づいてクエリを実行する必要があるアプリケーションでは、通常このパラメーターに TRUE を設定すると効果的です。
サブ条件のコレクションの論理積 (AND) または論理和 (OR) となる条件ノードを作成します。
| ct | CONDITION_TYPE | in | 条件ノードの CONDITION_TYPE。CONDITION_TYPE には CT_AND_CONDITION または CT_OR_CONDITION のいずれかを指定する必要があります。 |
| peuSubs | IEnumUnknown* | in | ICondition オブジェクトの列挙へのポインター。空の列挙とする場合は NULL。 |
| fSimplify | BOOL | in | 可能であれば結果を論理的に単純化する場合は TRUE。この場合、結果は必ずしも指定した種類になるとは限りません。結果を指定どおりの構造にする必要がある場合は FALSE。 条件ツリーに基づいてクエリを実行する予定のアプリケーションでは、通常このパラメーターに TRUE を設定すると効果的です。 |
| ppcResult | ICondition** | out | 新しい ICondition ノードへのポインターのアドレスを受け取ります。 |
戻り値
型: HRESULT
このメソッドが成功すると S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。
解説(Remarks)
TRUE と FALSE を表す特別な条件ツリーはありません。ただし、サブ条件を持たない AND ノードで構成される条件ツリーは常に TRUE であり、サブ条件を持たない OR ノードで構成される条件ツリーは常に FALSE です。
プロパティ値と定数値の比較を表すリーフ条件ノードを作成します。
| pszPropertyName | LPWSTR | in | 比較するプロパティの名前。プロパティを指定しない場合は NULL。リーフノードのロケール名は LOCALE_NAME_USER_DEFAULT です。 |
| cop | CONDITION_OPERATION | in | CONDITION_OPERATION 列挙型の値。 |
| pszValueType | LPWSTR | in | 値のセマンティック型の名前。プレーンな文字列の場合は NULL。 |
| ppropvar | PROPVARIANT* | in | プロパティ値との比較対象となる定数値。 |
| pPropertyNameTerm | IRichChunk* | in | プロパティを表す入力文字列の範囲を示す IRichChunk へのポインター。NULL を指定できます。 |
| pOperationTerm | IRichChunk* | in | 演算を表す入力文字列の範囲を示す IRichChunk へのポインター。NULL を指定できます。 |
| pValueTerm | IRichChunk* | in | 値を表す入力文字列の範囲を示す IRichChunk へのポインター。NULL を指定できます。 |
| fExpand | BOOL | in | TRUE で、かつ pszPropertyName が仮想プロパティを示す場合、生成されるノードはリーフノードではなく、リーフ条件ノードの論理和になります。各リーフ条件ノードは、その仮想プロパティの 1 つの展開に対応します。 |
| ppcResult | ICondition** | out | 新しい ICondition リーフノードへのポインターを受け取ります。 |
戻り値
型: HRESULT
このメソッドが成功すると S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。
解説(Remarks)
リーフノードの語句 (プロパティ、値、演算) の詳細については、 ICondition::GetInputTerms を参照してください。
仮想プロパティは、キーが "MapsToRelation" で値がプロパティ名 (そのプロパティの 1 つの展開) であるメタデータ項目を 1 つ以上持ちます。メタデータの詳細については、MetaData を参照してください。
条件ツリーに対して次のようなさまざまな変換を実行します。相対的な日付/時刻式を含む条件を、絶対的な日付/時刻 (VT_FILETIME) を含む条件に解決する。認識されたその他の名前付きエンティティを、実際の値を持つ条件ツリーに変換する。条件ツリーを単純化する。仮想プロパティまたは複合プロパティを、他のプロパティの OR ツリーに置き換える。条件が適用されなかったプロパティキーワードを含むクエリから生成された条件ツリーを削除する。
| pc | ICondition* | in | 解決する ICondition オブジェクトへのポインター。 |
| sqro | STRUCTURED_QUERY_RESOLVE_OPTION | in | STRUCTURED_QUERY_RESOLVE_OPTION フラグを 0 個以上指定します。Windows 7 以降では、SQRO_ADD_VALUE_TYPE_FOR_PLAIN_VALUES フラグが sqro に自動的に追加されます。 |
| pstReferenceTime | SYSTEMTIME* | inoptional | 基準の日付と時刻として使用する SYSTEMTIME 値へのポインター。sqro に SQRO_DONT_RESOLVE_DATETIME が設定されている場合は、null ポインターを渡すことができます。 |
| ppcResolved | ICondition** | out | すべての時刻フィールドが VT_FILETIME 型の値に解決された、新しい ICondition へのポインターを受け取ります。この新しい条件ツリーは pc を解決したものです。 |
戻り値
型: HRESULT
このメソッドが成功すると S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。
解説(Remarks)
Parse メソッドによって生成され、GetQuery によって返される条件ツリーでは、リーフがプロパティとそのプロパティに対する制約を対応付けており、結果として部分的にのみ完成した条件ツリーになります。IConditionFactory::Resolve メソッドは、解決 (resolution) と呼ばれる処理によってこのような条件ツリーを完成させます。入力の条件ツリーは一切変更されません。出力の条件ツリーは、未解決の日付/時刻値を持つリーフノードを含まなかった入力条件の一部を共有する場合があります。
StructuredQuerySample では、コンソールから行を読み取り、システムスキーマを使用して解析し、生成された条件ツリーを表示する方法を示しています。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)
HSP用 COM定義
#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。
#define global IID_IConditionFactory "{A5EFE073-B16F-474F-9F3E-9F8B497A3E08}" #usecom global IConditionFactory IID_IConditionFactory "{E03E85B0-7BE3-4000-BA98-6C13DE9FA486}" #comfunc global IConditionFactory_MakeNot 3 sptr,int,sptr #comfunc global IConditionFactory_MakeAndOr 4 int,sptr,int,sptr #comfunc global IConditionFactory_MakeLeaf 5 wstr,int,wstr,var,sptr,sptr,sptr,int,sptr #comfunc global IConditionFactory_Resolve 6 sptr,int,var,sptr ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※#usecom 末尾は CoCreateInstance 用のクラスID(コクラスCLSID, SDKから自動取得)。 ; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IConditionFactory "{A5EFE073-B16F-474F-9F3E-9F8B497A3E08}" #usecom global IConditionFactory IID_IConditionFactory "{E03E85B0-7BE3-4000-BA98-6C13DE9FA486}" #comfunc global IConditionFactory_MakeNot 3 sptr,int,sptr #comfunc global IConditionFactory_MakeAndOr 4 int,sptr,int,sptr #comfunc global IConditionFactory_MakeLeaf 5 wstr,int,wstr,sptr,sptr,sptr,sptr,int,sptr #comfunc global IConditionFactory_Resolve 6 sptr,int,sptr,sptr ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※#usecom 末尾は CoCreateInstance 用のクラスID(コクラスCLSID, SDKから自動取得)。 ; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。