IMAPITable::SeekRow
適用対象: Outlook 2013 | Outlook 2016
テーブル内の特定の位置にカーソルを移動します。
HRESULT SeekRow(
BOOKMARK bkOrigin,
LONG lRowCount,
LONG FAR * lplRowsSought
);
パラメーター
bkOrigin
[in]シーク操作の開始位置を示すブックマーク。 ブックマークは、IMAPITable::CreateBookmark メソッドを使用して作成することも、次の定義済みの値のいずれかを渡すことができます。
BOOKMARK_BEGINNING
テーブルの先頭からシーク操作を開始します。
BOOKMARK_CURRENT
カーソルがあるテーブル内の行からシーク操作を開始します。
BOOKMARK_END
テーブルの末尾からシーク操作を開始します。
lRowCount
[in] bkOrigin パラメーターによって識別されるブックマークから始まる、移動する行数の符号付きカウント。
lplRowsSought
[out] lRowCount が入力の有効なポインターである場合、 lplRowsSought はシーク操作で処理された行の数を指します。その符号は、検索の方向を示します。これは前方または後方の方向を示します。 lRowCount が負の場合、lplRowsSought は負になります。
戻り値
S_OK
シーク操作が成功しました。
MAPI_E_BUSY
行シーク操作の開始を妨げる別の操作が進行中です。 進行中の操作の完了を許可するか、停止する必要があります。
MAPI_E_INVALID_BOOKMARK
bkOrigin パラメーターで指定されたブックマークは、削除されたか、要求された最後の行を超えているため無効です。
MAPI_W_POSITION_CHANGED
呼び出しは成功しましたが、 bkOrigin パラメーターで指定されたブックマークが、最後に使用されたときと同じ行に設定されなくなりました。 ブックマークが使用されていない場合は、作成時と同じ位置に表示されなくなります。 この警告が返されたら、呼び出しは成功として処理する必要があります。 この警告をテストするには、 HR_FAILED マクロを使用します。 詳細については、「 エラー処理にマクロを使用する」を参照してください。
注釈
IMAPITable::SeekRow メソッドは、カーソルの新しいBOOKMARK_CURRENT位置を確立します。 lRowCount パラメーターは、カーソルが移動する行数と移動方向を示します。
結果の位置がテーブルの最後の行を超える場合、カーソルは最後の行の後に配置されます。 結果の位置がテーブルの最初の行の前にある場合、カーソルは最初の行の先頭に配置されます。
実装に関するメモ
bkOrigin が指す行がテーブルに存在しなくなり、ブックマークの新しい位置を確立できない場合は、MAPI_E_INVALID_BOOKMARKを返します。 by_bkOrigin_no指す行が存在し、ブックマークの新しい位置を確立できる場合は、MAPI_W_POSITION_CHANGEDを返します。
テーブル ビューから折りたたまれた行を指すブックマークは引き続き使用できます。 呼び出し元がこのようなブックマークにカーソルを移動しようとすると、カーソルを次の表示行に移動し、MAPI_W_POSITION_CHANGEDを返します。
使用時または行が折りたたまれた時点で、ビューから折りたたまれた位置のブックマークを移動できます。 行が折りたたまれた時点でブックマークを移動する場合は、最後の使用後にブックマークが移動したかどうかを示すブックマークを少し保持します。
呼び出し側への注意
SeekRow の後方移動を示すには、lRowCount に負の値を渡します。 テーブルの先頭を検索するには、 lRowCount に 0 を渡し、 bkOrigin でBOOKMARK_BEGINNING値を渡します。
テーブルに多数の行がある場合、 SeekRow 操作が遅くなる可能性があります。 lplRowsSought パラメーターの内容で行数を返す必要がある場合も、パフォーマンスが影響を受ける可能性があります。
SeekRow は、 lRowCount が指す変数で、実際に検索された正または負の行数を返します。 通常の操作では、検索がテーブルの先頭または末尾に達しない限り、lRowCount に渡される lplRowsSought の値と同じ値を返す必要があります。
lRowCount を 50 より大きい数値に設定しないでください。 より多くの行をシークするには、 IMAPITable::SeekRowApprox メソッドを 使用します。
MFCMAPI リファレンス
MFCMAPI のサンプル コードについては、次の表を参照してください。
| ファイル | 関数 | コメント |
|---|---|---|
| MAPIProcessor.cpp |
CMAPIProcessor::P rocessMailboxTable |
MFCMAPI では、 IMAPITable::SeekRow メソッドを使用して、処理前にテーブルの先頭を見つけます。 |