ホーム › System.Search › ISearchQueryHelper

ISearchQueryHelper

COM

IIDab310581-ac80-11d1-8df3-00c04fb6ef63継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

ユーザー入力からクエリを構築し、クエリを Windows Search SQL に変換し、Windows Search インデックスへの接続を初期化するための接続文字列を取得するメソッドを提供します。

解説(Remarks)

このインターフェイスは ISearchCatalogManager::GetQueryHelper を呼び出すことで取得します。このインターフェイスは ISearchCatalogManager のヘルパークラスとして実装してください。

このインターフェイスは、Advanced Query Syntax (AQS) または Natural Query Syntax (NQS) を使用した SQL クエリの生成を容易にします。クライアントは OLE DB または Microsoft ActiveX Data Objects (ADO) を使用して、生成した SQL クエリを Windows Search エンジンに送信できます。

ISearchQueryHelper::GenerateSQLFromUserQuery は地域のロケール設定を使用します。一方、ISearchQueryHelper は地域のロケール設定を使用しません。そのため、日付形式などの地域固有の設定については、ISearchQueryHelper::GenerateSQLFromUserQuery が返す SQL と ISearchQueryHelper が返す SQL の間に不一致が生じます。

ISearchQueryHelper 向けの Microsoft.Search.Interop アセンブリを使用して Windows Search にクエリを実行する静的コンソールアプリケーション用のクラスを作成する方法を示すサンプルについては、DSearch サンプルを参照してください。

メソッド 21

vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。

vtbl 3 HRESULT get_ConnectionString(LPWSTR* pszConnectionString)

Windows Search インデックスへの OLE DB 接続文字列を返します。

pszConnectionString

LPWSTR*

out

有効な OLE DB 接続文字列である、NULL 終端の Unicode 文字列へのポインターを受け取ります。この接続文字列は、Windows Search インデックスへの接続を初期化し、ISearchQueryHelper::GenerateSQLFromUserQuery が返した SQL クエリを送信するために使用できます。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

接続文字列とは、データストアへの接続に必要な初期化プロパティを文字列で表したものです。この文字列には、データソース、データソース名、ユーザー ID とパスワードなどを含めることができます。

ISearchQueryHelper 向けの Microsoft.Search.Interop アセンブリを使用して Windows Search にクエリを実行する静的コンソールアプリケーション用のクラスを作成する方法については、DSearch コードサンプルを参照してください。

vtbl 4 HRESULT put_QueryContentLocale(DWORD lcid)

クエリの言語コード識別子 (LCID) を設定します。

lcid

DWORD

クエリの LCID を設定します。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

ロケール識別子は、インストール済みのシステム定義ロケールの 1 つを一意に識別するために必要な構成要素を備えています。LCID は、数値形式、日付形式、通貨形式、大文字と小文字のマッピング、辞書順のソート順、トークン化など、多くの設定を制御します。これらの設定により Windows オペレーティングシステムと Windows Search API は優れたローカライズ対応を実現していますが、あるロケールのドキュメントを別のロケール向けに設定されたシステムで検索した場合、予期しない結果になることがあります。

IFilter オブジェクトは、ドキュメントのテキストプロパティとコンテンツを処理する際に、そのドキュメントの言語をコンテンツインデクサーに通知します。Search API はこの情報を使用して、適切なワードブレーカーとノイズワードリストを適用できます。

ロケールは、クエリ文字列から抽出された文字列値のワードブレーク、正規化、およびステミングに使用されます。このメソッドを使用しない場合 (つまりコンテンツロケールが設定されていない場合)、ISearchQueryHelper::get_QueryContentLocale はアクティブな入力ロケールを返します。

vtbl 5 HRESULT get_QueryContentLocale(DWORD* plcid)

クエリの言語コード識別子 (LCID) を取得します。

plcid

DWORD*

out

使用されているロケール識別子へのポインターを受け取ります。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

ロケール識別子は、インストール済みのシステム定義ロケールの 1 つを一意に識別するために必要な構成要素を備えています。取得されるロケールは、クエリ文字列から抽出された文字列値のワードブレーク、正規化、およびステミングに使用されます。ロケール識別子が ISearchQueryHelper::put_QueryContentLocale で設定されていない場合は、アクティブな入力ロケールが取得されます。

vtbl 6 HRESULT put_QueryKeywordLocale(DWORD lcid)

Advanced Query Syntax (AQS) のキーワードを解析する際に使用するロケールの言語コード識別子 (LCID) を設定します。

lcid

DWORD

Advanced Query Syntax (AQS) のキーワードを解析する際に使用するロケールの LCID を設定します。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

vtbl 7 HRESULT get_QueryKeywordLocale(DWORD* plcid)

Advanced Query Syntax (AQS) のキーワードを解析する際に使用するロケールの言語コード識別子 (LCID) を取得します。

plcid

DWORD*

out

Advanced Query Syntax (AQS) のキーワードを解析する際に使用するロケールの LCID へのポインターを受け取ります。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

vtbl 8 HRESULT put_QueryTermExpansion(SEARCH_TERM_EXPANSION expandTerms)

クエリ語をどのように展開するかを指定する値を設定します。

expandTerms

SEARCH_TERM_EXPANSION

検索語の展開方法を指定する SEARCH_TERM_EXPANSION 列挙型の値。設定しない場合の既定値は SEARCH_TERM_PREFIX_ALL です。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

ISearchQueryHelper::put_QueryTermExpansion メソッドを使用すると、正規表現の展開と同様に、一部のクエリ語をワイルドカード文字で展開できます。

SEARCH_TERM_EXPANSION 列挙型ではステム展開を指定できますが、Windows Search は現時点では ISearchQueryHelper インターフェイスでのステム展開の使用をサポートしていません。

vtbl 9 HRESULT get_QueryTermExpansion(SEARCH_TERM_EXPANSION* pExpandTerms)

クエリ語をどのように展開するかを指定する値を取得します。

pExpandTerms

SEARCH_TERM_EXPANSION*

out

クエリ語の展開方法を指定する SEARCH_TERM_EXPANSION 列挙型の値へのポインターを受け取ります。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

vtbl 10 HRESULT put_QuerySyntax(SEARCH_QUERY_SYNTAX querySyntax)

クエリの構文を設定します。

querySyntax

SEARCH_QUERY_SYNTAX

検索クエリの構文を指定するフラグ。指定可能な値の一覧については、SEARCH_QUERY_SYNTAX 列挙型の説明を参照してください。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

使用できる構文は、Simple、Natural Query Syntax (NQS)、および Advanced Query Syntax (AQS) です。設定しない場合、既定のクエリ構文は SEARCH_ADVANCED_QUERY_SYNTAX です。

vtbl 11 HRESULT get_QuerySyntax(SEARCH_QUERY_SYNTAX* pQuerySyntax)

クエリの構文を取得します。

pQuerySyntax

SEARCH_QUERY_SYNTAX*

out

SEARCH_QUERY_SYNTAX 列挙型の値へのポインターを受け取ります。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

vtbl 12 HRESULT put_QueryContentProperties(LPWSTR pszContentProperties)

検索語がプロパティを明示的に指定していない場合に、クエリに含めるプロパティを設定します。

pszContentProperties

LPWSTR

1 つ以上のプロパティをカンマ区切りで記述した、NULL 終端の Unicode 文字列へのポインター。列指定子はカンマで区切ります。例: "Content,DocAuthor"

すべてのプロパティを使用するには、ppszContentProperties に NULL を設定します。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

検索語には、プロパティが明示的に前置される場合とされない場合があります ("author:Irina" のように指定する場合と、単に "Irina" と指定する場合)。ISearchQueryHelper::put_QuerySyntax で SEARCH_ADVANCED_QUERY_SYNTAX または NO_QUERY_SYNTAX が設定されている場合、プロパティキーワードが前置されていないすべての検索語は、ppszContentProperties のプロパティ一覧と照合されます。

vtbl 13 HRESULT get_QueryContentProperties(LPWSTR* ppszContentProperties)

検索語がプロパティを明示的に指定していない場合に、クエリに含められるプロパティの一覧を取得します。

ppszContentProperties

LPWSTR*

out

検索対象となるコンテンツプロパティをカンマ区切りで記述した、NULL 終端の Unicode 文字列へのポインターを受け取ります。ppszContentProperties が NULL の場合は、すべてのプロパティが検索されます。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

vtbl 14 HRESULT put_QuerySelectColumns(LPWSTR pszSelectColumns)

SELECT ステートメントで要求する列 (またはプロパティ) を設定します。

pszSelectColumns

LPWSTR

プロパティストア内の 1 つ以上の列を指定する、カンマ区切りで NULL 終端の Unicode 文字列へのポインター。複数の列指定子はカンマで区切ります。例: "System.Document.Author,System.Document.Title"

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

すべてのドキュメントに適用される、定義済みで固定のプロパティセットは存在しません。このため、<columns> の設定では SQL のアスタリスクを使用できません。有効な Shell システムプロパティの一覧については、システムプロパティを参照してください。

vtbl 15 HRESULT get_QuerySelectColumns(LPWSTR* ppszSelectColumns)

クエリの SELECT ステートメントで要求されている列 (またはプロパティ) を取得します。

ppszSelectColumns

LPWSTR*

out

クエリから返される列 (またはプロパティ) を指定する、カンマ区切りで NULL 終端の Unicode 文字列へのポインターを受け取ります。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

アイテムはプロパティストア内で 1 つの行として表現されます。各行には、その行 (オブジェクト) のプロパティを表す複数の列が含まれます。すべてのアイテムが特定のプロパティの値を持つとは限りません。SELECT 操作の対象にするには、プロパティがプロパティストアに存在している必要があります。

vtbl 16 HRESULT put_QueryWhereRestrictions(LPWSTR pszRestrictions)

WHERE 句としてクエリに付加する制限を設定します。

pszRestrictions

LPWSTR

生成される WHERE 句としてクエリに付加される 1 つ以上のクエリ制限を指定する、カンマ区切りで NULL 終端の Unicode 文字列へのポインター。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

pszRestrictions は、Windows Search SQL の有効な WHERE 句 (WHERE キーワードを除いたもの) である必要があります。

複数の制限を指定して pszRestrictions を作成する場合、最初の句に連結される追加の "WHERE" 句は "AND" または "OR" で始める必要があります。例: "and contains(*, 'qqq')"

vtbl 17 HRESULT get_QueryWhereRestrictions(LPWSTR* ppszRestrictions)

WHERE 句としてクエリに付加されている制限を取得します。

ppszRestrictions

LPWSTR*

out

WHERE 句によってクエリに付加される 1 つ以上の制限を指定する、カンマ区切りで NULL 終端の Unicode 文字列へのポインターを受け取ります。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

vtbl 18 HRESULT put_QuerySorting(LPWSTR pszSorting)

クエリ結果セットのソート順を設定します。

pszSorting

LPWSTR

ソート順を指定する、カンマ区切りで NULL 終端の Unicode 文字列。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

ppszSorting は有効な ORDER BY 句 (ORDER BY キーワードを除いたもの) である必要があります。Windows Search SQL は複数のプロパティによるソートをサポートしており、各プロパティに対して昇順 (ASC) または降順 (DESC) を指定できます。たとえば、ppszSorting には次のような内容を指定できます。

System.ItemAuthors ASC, System.ItemDate DESC

vtbl 19 HRESULT get_QuerySorting(LPWSTR* ppszSorting)

クエリ結果セットのソート順を取得します。

ppszSorting

LPWSTR*

out

ソート順を表す、カンマ区切りで NULL 終端の Unicode 文字列へのポインターを受け取ります。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

Windows Search SQL は複数のプロパティによるソートをサポートしており、各プロパティに対して昇順 (ASC) または降順 (DESC) を指定できます。たとえば、ppszSorting が指す値には次のような内容が格納されます。

System.ItemAuthors ASC, System.ItemDate DESC

vtbl 20 HRESULT GenerateSQLFromUserQuery(LPWSTR pszQuery, LPWSTR* ppszSQL)

Advanced Query Syntax (AQS) または Natural Query Syntax (NQS) で記述された、クライアントから指定されたクエリ文字列に基づいて Structured Query Language (SQL) クエリを生成します。

pszQuery	LPWSTR	in	AQS または NQS のクエリを格納した、NULL 終端の Unicode 文字列へのポインター。
ppszSQL	LPWSTR*	out	pszQuery パラメーターのクエリに基づく SQL クエリ文字列へのポインターのアドレスを受け取ります。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

このメソッドは次の形式の SQL を生成します。

SELECT <QuerySelectColumns> FROM <CatalogName that created query helper>
    WHERE <Result of interpreting the User query passed into this function according to QuerySyntax>
          [ AND|OR <QueryWhereRestrictions>]

SQL の生成では、ISearchQueryHelper::put_QueryTermExpansion、ISearchQueryHelper::put_QueryContentProperties、および ISearchQueryHelper::put_QueryContentLocale で指定された設定が使用されます。

ISearchQueryHelper::GenerateSQLFromUserQuery は地域のロケール設定を使用します。一方、ISearchQueryHelper は地域のロケール設定を使用しません。そのため、日付形式などの地域固有の設定については、ISearchQueryHelper::GenerateSQLFromUserQuery が返す SQL と ISearchQueryHelper が返す SQL の間に不一致が生じます。たとえば、システムロケールが en-US の環境で日付/時刻のロケールを en-CA など別のロケールに設定し、Toybox -m -i "date:3/7/2008" -Y -s と入力すると、返される SQL が異なります。ISearchQueryHelper::GenerateSQLFromUserQuery が返す SQL では 3/7/2008 が en-CA として解析され (2008 年 7 月 3 日付のアイテムを検索)、ISearchQueryHelper が返す SQL では 3/7/2008 が en-US として解析されます (2008 年 3 月 7 日付のアイテムを検索)。

vtbl 21 HRESULT WriteProperties(INT itemID, DWORD dwNumberOfColumns, PROPERTYKEY* pColumns, SEARCH_COLUMN_PROPERTIES* pValues, FILETIME* pftGatherModifiedTime)

実装されていません。(ISearchQueryHelper.WriteProperties)

itemID	INT	in	対象となる ItemID。ItemID は、DocID などのアイテムの一意の識別子を格納するために使用されます。
dwNumberOfColumns	DWORD	in	書き込むプロパティの数。
pColumns	PROPERTYKEY*	in	プロパティを表す PROPERTYKEY 構造体の配列へのポインター。
pValues	SEARCH_COLUMN_PROPERTIES*	in	プロパティ値を保持する SEARCH_COLUMN_PROPERTIES 構造体の配列へのポインター。
pftGatherModifiedTime	FILETIME*	in	書き込み対象のアイテムの最終更新時刻へのポインター。このタイムスタンプは、後でアイテムが変更されて更新が必要かどうかを判断するために使用されます。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

vtbl 22 HRESULT put_QueryMaxResults(INT cMaxResults)

クエリが返す結果の最大数を設定します。

cMaxResults

INT

返される結果の最大数。負の値を指定すると、すべての結果が返されます。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

vtbl 23 HRESULT get_QueryMaxResults(INT* pcMaxResults)

クエリが返す結果の最大数を取得します。

pcMaxResults

INT*

out

クエリが返す結果の最大数へのポインターを受け取ります。負の値の場合は、すべての結果が返されます。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

HSP用 COM定義

#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。

出力引数:

#define global IID_ISearchQueryHelper "{AB310581-AC80-11D1-8DF3-00C04FB6EF63}"
#usecom global ISearchQueryHelper IID_ISearchQueryHelper "{}"
#comfunc global ISearchQueryHelper_get_ConnectionString        3 var
#comfunc global ISearchQueryHelper_put_QueryContentLocale      4 int
#comfunc global ISearchQueryHelper_get_QueryContentLocale      5 var
#comfunc global ISearchQueryHelper_put_QueryKeywordLocale      6 int
#comfunc global ISearchQueryHelper_get_QueryKeywordLocale      7 var
#comfunc global ISearchQueryHelper_put_QueryTermExpansion      8 int
#comfunc global ISearchQueryHelper_get_QueryTermExpansion      9 var
#comfunc global ISearchQueryHelper_put_QuerySyntax             10 int
#comfunc global ISearchQueryHelper_get_QuerySyntax             11 var
#comfunc global ISearchQueryHelper_put_QueryContentProperties  12 wstr
#comfunc global ISearchQueryHelper_get_QueryContentProperties  13 var
#comfunc global ISearchQueryHelper_put_QuerySelectColumns      14 wstr
#comfunc global ISearchQueryHelper_get_QuerySelectColumns      15 var
#comfunc global ISearchQueryHelper_put_QueryWhereRestrictions  16 wstr
#comfunc global ISearchQueryHelper_get_QueryWhereRestrictions  17 var
#comfunc global ISearchQueryHelper_put_QuerySorting            18 wstr
#comfunc global ISearchQueryHelper_get_QuerySorting            19 var
#comfunc global ISearchQueryHelper_GenerateSQLFromUserQuery    20 wstr,var
#comfunc global ISearchQueryHelper_WriteProperties             21 int,int,var,var,var
#comfunc global ISearchQueryHelper_put_QueryMaxResults         22 int
#comfunc global ISearchQueryHelper_get_QueryMaxResults         23 var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。#define global IID_ISearchQueryHelper "{AB310581-AC80-11D1-8DF3-00C04FB6EF63}"
#usecom global ISearchQueryHelper IID_ISearchQueryHelper "{}"
#comfunc global ISearchQueryHelper_get_ConnectionString        3 sptr
#comfunc global ISearchQueryHelper_put_QueryContentLocale      4 int
#comfunc global ISearchQueryHelper_get_QueryContentLocale      5 sptr
#comfunc global ISearchQueryHelper_put_QueryKeywordLocale      6 int
#comfunc global ISearchQueryHelper_get_QueryKeywordLocale      7 sptr
#comfunc global ISearchQueryHelper_put_QueryTermExpansion      8 int
#comfunc global ISearchQueryHelper_get_QueryTermExpansion      9 sptr
#comfunc global ISearchQueryHelper_put_QuerySyntax             10 int
#comfunc global ISearchQueryHelper_get_QuerySyntax             11 sptr
#comfunc global ISearchQueryHelper_put_QueryContentProperties  12 wstr
#comfunc global ISearchQueryHelper_get_QueryContentProperties  13 sptr
#comfunc global ISearchQueryHelper_put_QuerySelectColumns      14 wstr
#comfunc global ISearchQueryHelper_get_QuerySelectColumns      15 sptr
#comfunc global ISearchQueryHelper_put_QueryWhereRestrictions  16 wstr
#comfunc global ISearchQueryHelper_get_QueryWhereRestrictions  17 sptr
#comfunc global ISearchQueryHelper_put_QuerySorting            18 wstr
#comfunc global ISearchQueryHelper_get_QuerySorting            19 sptr
#comfunc global ISearchQueryHelper_GenerateSQLFromUserQuery    20 wstr,sptr
#comfunc global ISearchQueryHelper_WriteProperties             21 int,int,sptr,sptr,sptr
#comfunc global ISearchQueryHelper_put_QueryMaxResults         22 int
#comfunc global ISearchQueryHelper_get_QueryMaxResults         23 sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。