IMAPITable::FindRow
適用対象: Outlook 2013 | Outlook 2016
特定の検索条件に一致するテーブル内の次の行を検索し、カーソルをその行に移動します。
HRESULT FindRow(
LPSRestriction lpRestriction,
BOOKMARK BkOrigin,
ULONG ulFlags
);
パラメーター
lpRestriction
[in]検索条件を記述する SRestriction 構造体へのポインター。
BkOrigin
[in] FindRow が検索を開始する必要がある行を識別するブックマーク。 ブックマークは、IMAPITable::CreateBookmark メソッドを使用して作成することも、次の定義済みの値のいずれかを渡すことができます。
BOOKMARK_BEGINNING
テーブルの先頭から検索します。
BOOKMARK_CURRENT
カーソルがあるテーブル内の行から検索します。
BOOKMARK_END
テーブルの末尾から検索します。
ulFlags
[in]検索の方向を制御するフラグのビットマスク。 次のフラグを設定できます。
DIR_BACKWARD
ブックマークによって識別された行から後方に検索します。
戻り値
S_OK
検索操作が成功しました。
MAPI_E_INVALID_BOOKMARK
BkOrigin パラメーターのブックマークは、削除されたか、要求された最後の行を超えているため無効です。
MAPI_E_NOT_FOUND
制限に一致する行が見つかりませんでした。
MAPI_W_POSITION_CHANGED
呼び出しは成功しましたが、操作で使用されるブックマークは、最後に使用されたときと同じ行に設定されなくなりました。ブックマークが使用されていない場合は、作成時と同じ位置に表示されなくなります。 この警告が返されたら、呼び出しは成功として処理する必要があります。 この警告をテストするには、 HR_FAILED マクロを使用します。 エラー処理のマクロの使用に関するページを参照してください。
注釈
IMAPITable::FindRow メソッドは、lpRestriction パラメーターによって指される SRestriction 構造体で説明されている検索条件のセットと一致するように、テーブル内の最初の行を検索します。
通常、 FindRow は 指定したブックマークから前方に検索します。 呼び出し元は、 ulFlags パラメーターで DIR_BACKWARD フラグを設定することで、ブックマークから後方に移動するように検索を設定できます。 前方検索は現在のブックマークから始まります。後方検索は、ブックマークの前の行から始まります。 検索の終了位置は、制限を満たす最初の行が見つかった直前です。
BkOrigin パラメーターのブックマークが指す行がテーブルに存在しなくなり、テーブルがブックマークの新しい位置を確立できない場合、FindRow はMAPI_E_INVALID_BOOKMARKを返します。 BkOrigin が指す行が存在しなくなり、テーブルがブックマークの新しい位置を確立できる場合、FindRow はMAPI_W_POSITION_CHANGEDを返します。
BkOrigin で渡されたブックマークがBOOKMARK_BEGINNINGまたはBOOKMARK_ENDの場合、一致する行が見つからない場合、FindRow はMAPI_E_NOT_FOUNDを返します。 BkOrigin で使用されるブックマークがBOOKMARK_CURRENTされている場合、FindRow はMAPI_W_POSITION_CHANGEDを返すことができますが、現在のカーソル位置が常にあるため、MAPI_E_INVALID_BOOKMARKは返されません。
PR_INSTANCE_KEY (PidTagInstanceKey) プロパティ列はすべてのテーブルに必要であり、PR_INSTANCE_KEYに基づいて行をシークする呼び出しをサポートするには、FindRow のすべての実装が必要です。
実装に関するメモ
FindRow によって実行されるプレフィックス検索の種類は、検索がテーブル組織と同じ方向に従う場合にのみ役立ちます。 必要な動作を実現するために、プロパティ制限構造体で渡される RELOP_GE によって暗黙的に示される比較関数は、テーブルの並べ替え順序の基になるのと同じ比較関数である必要があります。
呼び出し側への注意
FindRow を使用すると、特にアドレス ダイアログ ボックス内のリスト ボックスで、ユーザーが入力した文字列に基づくスクロールをサポートできます。 この種類のスクロールでは、ユーザーは必要な文字列値のプレフィックスを徐々に長く入力し、 FindRow 呼び出しを定期的に発行して、プレフィックスと一致する最初の行にジャンプできます。 カーソルがジャンプする方向は、検索を実行するように設定された方向によって異なります。
FindRow を使用するには、ブックマークを設定する必要があります。 文字列検索は、現在の位置とテーブルの先頭と末尾を示すプリセット ブックマークを含め、任意のブックマークから取得できます。 テーブルに多数の行がある場合、検索操作が遅くなる可能性があります。
制限を使用して、次のようにスクロールする文字列プレフィックスを見つけます。 昇順で並べ替えられた列で前方検索を行い、降順で並べ替えられた列を後方検索する場合は、 lpRestriction パラメーターのプロパティ制限構造を、リレーションシップ RELOP_GE と適切なプロパティ タグとプレフィックスと共に、書式 タグGEプレフィックスを使用して渡します。
制限構造を使用してフィルターを指定する方法の詳細については、「 制限について」を参照してください。
MFCMAPI リファレンス
MFCMAPI のサンプル コードについては、次の表を参照してください。
| ファイル | 関数 | コメント |
|---|---|---|
| ContentsTableListCtrl.cpp |
DwThreadFuncLoadTable |
MFCMAPI では、 IMAPITable::FindRow メソッドを使用して、制限に一致する行を検索します。 |