IMAPITable::SortTable
適用於:Outlook 2013 |Outlook 2016
IMAPITable::SortTable 方法會根據排序準則排序數據表的數據列。
HRESULT SortTable(
LPSSortOrderSet lpSortCriteria,
ULONG ulFlags
);
參數
lpSortCriteria
[in] SSortOrderSet 結構的指標,其中包含要套用的排序準則。 傳遞包含零個數據行的 SortOrderSet 結構,表示數據表不需要以任何特定順序排序。
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 成員中所指定,大於實作可處理的數目。
系統會根據不在可用或使用中集合中的屬性,要求排序作業,如 SortOrderSet中的屬性標記所指示,而且實作不支援排序不在可用集合中的屬性。
一個屬性會在排序順序集中指定多次,如同一屬性標籤的多個實例所表示,而且實作無法執行這類排序作業。
使用 MVI_FLAG 要求以多重值屬性數據行為基礎的排序作業,而且實作不支援對多重值屬性進行排序。
SSortOrderSet 中屬性的屬性標記會指定實作不支援的屬性或類型。
唯有針對支援這種排序類型的附件數據表,才指定從 PR_RENDERING_POSITION (PidTagRenderingPosition) 屬性向前執行的數據表以外的排序作業。
註解
IMAPITable::SortTable 方法會排序數據表檢視中的數據列。 有些數據表同時支援各種排序索引鍵數據行的標準和分類排序,而其他數據表的支援則較為有限。 通訊錄提供者通常不支持數據表排序。 訊息存放區提供者通常支援排序,使其維持完整數據表 (數據表時所產生資料夾的排序順序,) 排序。
某些數據表允許在任何數據表數據行上進行排序。 其他數據表則不會;未包含在數據表檢視中的數據行不會受到 SortTable 呼叫的影響。 某些數據表需要只使用數據表目前數據行集中的數據行來建置排序索引鍵。
當數據表無法完成排序作業時,可以從 SortTable 傳回MAPI_E_NO_SUPPORT或MAPI_E_TOO_COMPLEX。 此外,存放區提供者不保證會接受針對階層數據表指定的排序順序集。
當 lpSortCriteria 參數所指向的 SSortOrderSet 結構中有零個數據行時,數據表會傳回目前的數據行集。 呼叫數據表的 IMAPITable::QuerySortOrder 方法,即可擷取目前的排序順序。
數據表的所有書籤都會失效,而且應該在呼叫 SortTable 時刪除,而且表示目前數據指標位置的BOOKMARK_CURRENT書籤應該設定為數據表的開頭。
如果您要排序的數據行包含未設定MVI_FLAG旗標的多重值屬性,則數據行的值會被視為完全排序的元組。 兩個多重值數據行的比較會依序比較數據行元素、報告第一個不等比較的數據行關聯性,而且只有在要比較的數據行以相同順序包含相同的值時,才會傳回相等。 如果一個數據行的值少於另一個數據行,則回報的關聯性是 Null 值與另一個值的關聯性。
呼叫者注意事項
除非您設定其中一個旗標,否則 SortTable 會以同步方式運作。 如果您設定TBL_BATCH旗標,除非您要求數據,否則 SortTable 會延後排序作業。 如果已設定TBL_ASYNC旗標, SortTable 會以異步方式運作,可能會在作業完成之前傳回。
如果您的排序必須立即完成,請呼叫 IMAPITable::Abort 方法來停止進行中的異步操作。 如果 SortTable 因為數據表上的一或多個異步操作正在進行中而無法繼續,則會傳回MAPI_E_BUSY。
為了達到最佳效能,請呼叫 SetColumns 來自定義數據表的數據行集, 並呼叫SortTable 以執行排序之前,限制限制數據表中的數據列數目。
每當 SortTable 失敗時,在失敗之前生效的排序順序仍然有效。