Win32 API 日本語リファレンス
ホーム › UI.TextServices › ITfFnSearchCandidateProvider

ITfFnSearchCandidateProvider

COM
📘 Microsoft Learn (日本語) · English
IID87a2ad8f-f27b-4920-8501-67602280175d継承元ITfFunction自前メソッド開始 vtbl4

公式ドキュメント

Input Method Editor (IME) との統合検索機能を実現します。

解説(Remarks)

統合検索機能を有効にするには、Input Method Editor (IME) に ITfFnSearchCandidateProvider インターフェイスを実装します。このインターフェイスを実装すると、入力された文字列に対する IME 変換候補の一覧を提供できるため、IME による入力が完了する前から意味のある検索結果を得られるようになります。アプリはこのインターフェイスを使用して文字列の IME 変換結果を取得できます。したがって ITfFnSearchCandidateProvider インターフェイスは、ITfFnGetLinguisticAlternates と併せて、ImmGetConversionList 関数を置き換える TSF ベースの手段となります。通常、IME は ITfFnGetLinguisticAlternates か ITfFnSearchCandidateProvider のいずれかを実装します (どちらも実装しない場合もあります)。

ITfFunctionProvider のインスタンスを取得するには、テキストサービスの CLSID を指定して GetFunctionProvider を呼び出します。ITfFnSearchCandidateProvider インターフェイスのポインターを取得するには、ITfFunctionProvider::GetFunction メソッドを次のように呼び出します。

ITfFunctionProvider::GetFunction(GUID_NULL, IID_ITfFnSearchCandidateProvider, &pSearchCandidate)

メソッド 2

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

vtbl 4 HRESULT GetSearchCandidates(LPWSTR bstrQuery, LPWSTR bstrApplicationId, ITfCandidateList** pplist)

IME 関連のメッセージやイベントを発生させることなく、指定した文字列に対する変換候補の一覧を取得します。

bstrQueryLPWSTRinテキストサービスが変換を試みる読みの文字列を指定します。
bstrApplicationIdLPWSTRinアプリが指定する文字列。テキストサービスが入力履歴に基づいて、アプリやコンテキストごとに異なる候補を提供できるようにします。一般的なコンテキストの場合は、空の BSTR (L””) を渡すことができます。
pplistITfCandidateList**out要求した候補データを受け取る ITfCandidateList。

戻り値

このメソッドは次のいずれかの値を返します。

戻り値 説明
S_OK
 メソッドは成功しました。
S_FALSE
 入力文字列に対して返せる候補がありませんでした。pplist が NULL になる場合があります。
vtbl 5 HRESULT SetResult(LPWSTR bstrQuery, LPWSTR bstrApplicationID, LPWSTR bstrResult)

ユーザーが候補を選択したときに、テキストサービスまたは IME に履歴データを提供します。

bstrQueryLPWSTRinテキストサービスまたは IME が変換する読みの文字列。
bstrApplicationIDLPWSTRinアプリが指定する文字列。テキストサービスまたは IME が入力履歴に基づいて、アプリやコンテキストごとに異なる候補を提供できるようにします。一般的なコンテキストの場合は、空の BSTR (L””) を渡すことができます。
bstrResultLPWSTRinユーザーが選択した候補文字列を表す文字列。GetSearchCandidates メソッドが返した候補文字列のいずれかである必要があります。

戻り値

このメソッドは次のいずれかの値を返します。

値 説明
S_OK
 メソッドは成功しました。

解説(Remarks)

SetResult メソッドの実装および呼び出しは省略可能です。

テキストサービスまたは IME は、bstrQuery の値に対応する GetSearchCandidates の呼び出しがまだ行われていない場合、E_PENDING を返すことができます。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_ITfFnSearchCandidateProvider "{87A2AD8F-F27B-4920-8501-67602280175D}"
#usecom global ITfFnSearchCandidateProvider IID_ITfFnSearchCandidateProvider "{}"
#comfunc global ITfFnSearchCandidateProvider_GetSearchCandidates  4 wstr,wstr,sptr
#comfunc global ITfFnSearchCandidateProvider_SetResult            5 wstr,wstr,wstr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。