IMAPITable::QueryRows
適用対象: Outlook 2013 | Outlook 2016
現在のカーソル位置から始まるテーブルから 1 つ以上の行を返します。
HRESULT QueryRows(
LONG lRowCount,
ULONG ulFlags,
LPSRowSet FAR * lppRows
);
パラメーター
lRowCount
[in]返される行の最大数。
ulFlags
[in]行の返し方を制御するフラグのビットマスク。 次のフラグを設定できます。
TBL_NOADVANCE
行の取得の結果としてカーソルが進むのを防ぎます。 TBL_NOADVANCE フラグが設定されている場合、カーソルは返された最初の行を指します。 TBL_NOADVANCE フラグが設定されていない場合、カーソルは最後に返された行の後の行を指します。
lppRows
[out]テーブル行を保持する SRowSet 構造体へのポインターへのポインター。
戻り値
S_OK
行が正常に返されました。
MAPI_E_BUSY
行取得操作の開始を妨げる別の操作が進行中です。 進行中の操作の完了を許可するか、停止する必要があります。
MAPI_E_INVALID_PARAMETER
IRowCount パラメーターは 0 に設定されます。
注釈
IMAPITable::QueryRows メソッドは、テーブルから 1 つ以上のデータ行を取得します。 IRowCount パラメーターの値は、取得の開始点に影響します。 IRowCount が正の場合、行は現在の位置から順方向に読み取られます。 IRowCount が負の場合、QueryRows は指定された行数を後方に移動して開始点をリセットします。 カーソルがリセットされると、行は順方向に読み取られます。
lppRows パラメーターが指す SRowSet 構造体の cRows メンバーは、返される行数を示します。 0 行が返された場合:
カーソルは既にテーブルの先頭に配置されており、 IRowCount の値は負の値です。 -または-
カーソルは既にテーブルの末尾に配置されており、 IRowCount の値は正です。
列の数とその順序は、各行で同じです。 行のプロパティが存在しない場合、またはプロパティの読み取り中にエラーが発生した場合、行内の プロパティの SPropValue 構造体には次の値が含まれます。
ulPropTag メンバーのプロパティ型のPT_ERROR。
Value メンバーのMAPI_E_NOT_FOUND。
lppRows パラメーターによって指される行セット内の SPropValue 構造体に使用されるメモリは、行ごとに個別に割り当てられ、解放される必要があります。 MAPIFreeBuffer を使用して、プロパティ値の構造体を解放し、行セットを解放します。 ただし、QueryRows の呼び出しで 0 が返される場合は、テーブルの先頭または末尾を示しますが、SRowSet 構造体自体のみを解放する必要があります。 SRowSet 構造体でメモリを割り当てて解放する方法の詳細については、「ADRLIST 構造体と SRowSet 構造体のメモリの管理」を参照してください。
返される行と返される順序は、IMAPITable::Restrict および IMAPITable::SortTable への呼び出しが成功したかどうかによって異なります。 ビューから行を絞り込み、QueryRows は制限で指定された条件に一致する行のみを返します。 SortTable は 、 QueryRows によって返される行のシーケンスに影響を与える、標準の並べ替え順序または分類された並べ替え順序を確立します。 返される行は、SortTable に渡される SSortOrderSet 構造体で指定された順序になります。
各行に返される列と、返される順序は、 IMAPITable::SetColumns への呼び出しが成功したかどうかによって異なります。 SetColumns は 、テーブル内の列に含めるプロパティと、列を含める順序を指定して、列セットを確立します。 SetColumns 呼び出しが行われた場合、各行の特定の列とそれらの列の順序は、呼び出しで指定された列セットと一致します。 SetColumns 呼び出しが行われなかった場合、テーブルは既定の列セットを返します。
これらの呼び出しが行われなかった場合、 QueryRows はテーブル内のすべての行を返します。 各行には、既定の順序で設定された既定の列が含まれています。
IMAPITable::SetColumns の呼び出しで確立された列セットに、PR_NULLに設定された列が含まれている場合、lppRows で返される行セット内の SPropValue 配列には空のスロットが含まれます。
実装に関するメモ
呼び出し元がサポートされていない列を列セットに含めることを要求できます。 この場合は、プロパティ タグのプロパティ型の部分にPT_ERRORを配置し、サポートされていない列のプロパティ値にMAPI_E_NOT_FOUNDします。
行数は、要件ではなく要求として扱います。 クエリの方向に行がない場合は、0 行から要求された数まで、任意の場所を返すことができます。
分類されたテーブル ビューから行が要求されたときにユーザーに表示される行のみを返します。これにより、呼び出し元はデータのスコープに関して有効な仮定を行い、余分な作業を回避できます。
呼び出し側への注意
通常、 lRowCount パラメーターで指定した行の数だけ行が返されます。 ただし、メモリまたは実装の制限が問題である場合、または操作がテーブルの先頭または末尾に早く到達すると、 QueryRows は要求よりも少ない行を返します。
QueryRows がMAPI_E_BUSYを返す場合は、IMAPITable::WaitForCompletion メソッドを呼び出し、非同期操作が完了したら QueryRows の呼び出しを再試行します。
QueryRows を呼び出すときは、非同期通知のタイミングによって、QueryRows から返される行セットが基になるデータを正確に表さない可能性があることに注意してください。 たとえば、メッセージの削除後にフォルダーのコンテンツ テーブルに 対する QueryRows の呼び出しが、対応する通知を受け取る前に、削除された行が行セットに返されます。 ユーザーのデータビューを更新する前に、通知が届くのを常に待ちます。
テーブルから行を取得する方法の詳細については、「テーブル行 からのデータの取得」を参照してください。
MFCMAPI リファレンス
MFCMAPI のサンプル コードについては、次の表を参照してください。
| ファイル | 関数 | コメント |
|---|---|---|
| ContentsTableListCtrl.cpp |
DwThreadFuncLoadTable |
MFCMAPI では、 IMAPITable::QueryRows メソッドを使用して、ビューに読み込むテーブル内の行を取得します。 |