IMAPITable::SortTable
適用対象: Outlook 2013 | Outlook 2016
IMAPITable::SortTable メソッドは、並べ替え条件に応じてテーブルの行を並べ替えます。
HRESULT SortTable(
LPSSortOrderSet lpSortCriteria,
ULONG ulFlags
);
パラメーター
lpSortCriteria
[in]適用する並べ替え条件を含む SSortOrderSet 構造体へのポインター。 0 個の列を含む SSortOrderSet 構造体を渡すと、テーブルを特定の順序で並べ替える必要がないことを示します。
ulFlags
[in] IMAPITable::SortTable 操作のタイミングを制御するフラグのビットマスク。 次のフラグを設定できます。
TBL_ASYNC
操作を非同期的に開始し、操作が完了する前に を返します。
TBL_BATCH
テーブル内のデータが必要になるまで、並べ替えの完了を延期します。
戻り値
S_OK
並べ替え操作が成功しました。
MAPI_E_BUSY
並べ替え操作の開始を妨げる別の操作が進行中です。 進行中の操作の完了を許可するか、停止する必要があります。
MAPI_E_NO_SUPPORT
テーブルは、要求された並べ替えの種類をサポートしていません。
MAPI_E_TOO_COMPLEX
lpSortCriteria パラメーターが指す特定の並べ替え条件が複雑すぎるため、テーブルは操作を実行できません。 SortTable は、次の条件でMAPI_E_TOO_COMPLEXを返すことができます。
実装で並べ替えることができないプロパティ列に対して、並べ替え操作が要求されます。
実装では、SSortOrderSet 構造体の ulOrder メンバーで要求された並べ替え順序はサポートされていません。
SSortOrderSet の cSorts メンバーで指定されているように、並べ替えられる列の数は、実装で処理できる数よりも多くなります。
並べ替え操作は、 SSortOrderSet のプロパティ タグで示されているように、使用可能なセットまたはアクティブ なセットに含まれていないプロパティに基づいて要求され、実装では、使用可能なセットにないプロパティの並べ替えをサポートしていません。
同じプロパティ タグの複数のインスタンスで示されているように、並べ替え順序セットに 1 つのプロパティが複数回指定され、実装でこのような並べ替え操作を実行することはできません。
複数値プロパティ列に基づく並べ替え操作は、MVI_FLAGを使用して要求され、実装では複数値プロパティの並べ替えがサポートされていません。
SSortOrderSet のプロパティのプロパティ タグは、実装でサポートされていないプロパティまたは型を指定します。
PR_RENDERING_POSITION (PidTagRenderingPosition) プロパティからテーブルを進める並べ替え操作以外の並べ替え操作は、この種類の並べ替えをサポートする添付ファイル テーブルに対してのみ指定されます。
注釈
IMAPITable::SortTable メソッドは、テーブル ビュー内の行を並べ替えます。 一部のテーブルでは、さまざまな並べ替えキー列の標準並べ替えと分類された並べ替えの両方がサポートされていますが、他のテーブルのサポートは制限されています。 アドレス帳プロバイダーは通常、テーブルの並べ替えをサポートしていません。 通常、メッセージ ストア プロバイダーは、完全なテーブル (制限のないテーブル) が並べ替えられたときに、フォルダーの並べ替え順序を保持する範囲での並べ替えをサポートします。
一部のテーブルでは、任意のテーブル列で並べ替えを行うことができます。 その他のテーブルには対応していません。テーブル ビューに含まれていない列は、 SortTable 呼び出しの影響を受けません。 一部のテーブルでは、テーブルの現在の列セット内の列のみを使用して並べ替えキーを作成する必要があります。
並べ替え操作を完了できない場合、テーブルは SortTable からMAPI_E_NO_SUPPORTまたはMAPI_E_TOO_COMPLEXを返すことができます。 さらに、ストア プロバイダーは、階層テーブルに対して指定された並べ替え順序セットを遵守することは保証されません。
lpSortCriteria パラメーターが指す SSortOrderSet 構造体に 0 個の列がある場合、テーブルは現在の列セットを返します。 現在の並べ替え順序は、テーブルの IMAPITable::QuerySortOrder メソッドを呼び出すことによって取得できます。
テーブルのすべてのブックマークは無効になり、 SortTable の呼び出しが行われたときに削除し、現在のカーソル位置を示すBOOKMARK_CURRENTブックマークをテーブルの先頭に設定する必要があります。
MVI_FLAG フラグが設定されていない複数値プロパティを含む列を並べ替える場合、列の値は完全に順序付けられたタプルとして扱われます。 2 つの複数値列の比較では、列要素を順番に比較し、最初の不等値の列の関係をレポートし、比較する列に同じ値が同じ順序で含まれている場合にのみ等値を返します。 1 つの列の値が他の列よりも少ない場合、報告される関係は、もう一方の値に対する null 値の関係です。
呼び出し側への注意
SortTable は、いずれかのフラグを設定しない限り、同期的に動作します。 TBL_BATCH フラグを設定した場合、 SortTable は データを要求しない限り、並べ替え操作を延期します。 TBL_ASYNC フラグが設定されている場合、 SortTable は非同期的に動作し、操作が完了する前にを返す可能性があります。
並べ替えをすぐに行う必要がある場合は、 IMAPITable::Abort メソッドを呼び出して、進行中の非同期操作を停止します。 テーブルに対する 1 つ以上の非同期操作が進行中のため SortTable を続行できない場合は、MAPI_E_BUSYが返されます。
最適なパフォーマンスを得るには、SetColumns を呼び出してテーブルの列セットをカスタマイズし、SortTable を呼び出して並べ替えを実行する前に、テーブル内の行数を制限するように Restrict を呼び出します。
SortTable が失敗しても、失敗前に有効だった並べ替え順序は引き続き有効です。