IMAPITable：：QueryRows

發行項
03/15/2024

適用於：Outlook 2013 |Outlook 2016

從數據表傳回一或多個數據列，從目前的數據指標位置開始。

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 參數設定為零。

註解

IMAPITable：：QueryRows 方法會從數據表取得一或多個數據列。 IRowCount 參數的值會影響擷取的起點。如果 IRowCount 為正數，則會從目前位置開始，以正向方向讀取數據列。如果 IRowCount 為負數， QueryRows 會 將指定的數據列數往後移動，以重設起點。重設數據指標之後，數據列會以正向順序讀取。

lppRows 參數所指向之 SRowSet 結構中的 cRows 成員會指出傳回的數據列數目。如果傳回零個資料列：

數據指標已位於數據表的開頭， 而 IRowCount 的值為負數。 -或-
數據指標已位於數據表結尾， 而 IRowCount 的值為正數。

每個數據列的數據行數目及其順序都相同。如果數據列的屬性不存在，或讀取屬性時發生錯誤，則數據列中屬性的 SPropValue 結構會包含下列值：

PT_ERROR ulPropTag 成員中的屬性類型。
MAPI_E_NOT_FOUND 值成員。

用於 lppRows 參數所指向之數據列集中 SPropValue 結構的記憶體，必須針對每個數據列個別配置和釋放。使用 MAPIFreeBuffer 釋放屬性值結構，並釋放數據列集。不過，當 QueryRows 的呼叫傳回零，表示數據表的開頭或結尾時，只需要釋放 SRowSet 結構本身。如需如何在 SRowSet 結構中配置和釋放記憶體的詳細資訊，請參閱管理 ADRLIST 和 SRowSet 結構的記憶體。

傳回的數據列及其傳回順序取決於是否已成功呼叫 IMAPITable：：Restrict 和 IMAPITable：：SortTable。限制從檢視篩選數據列，導致 QueryRows 只傳回符合限制中指定之準則的數據列。 SortTable 會建立標準或分類的排序順序，影響 QueryRows 傳回的數據列順序。傳回的數據列會依照 SSortOrderSet 結構中指定的順序傳遞至 SortTable。

每個數據列傳回的數據行及其傳回順序取決於是否已成功呼叫 IMAPITable：：SetColumns。 SetColumns 會建立資料行集，指定要包含在數據表中數據行中的屬性，以及應包含這些屬性的順序。如果已進行 SetColumns 呼叫，則每個數據列中的特定數據行和這些數據行的順序會符合呼叫中指定的數據行集。如果未進行 任何 SetColumns 呼叫，數據表會傳回其預設數據行集。

如果未進行任何呼叫， QueryRows 會 傳回數據表中的所有數據列。每個數據列都包含預設順序的預設數據行集。

當在呼叫 IMAPITable：：SetColumns 中建立的數據行集包含設定為 PR_NULL 的數據行時，lppRows 中傳回的數據列集內的 SPropValue 陣列會包含空位置。

實作者注意事項

您可以允許呼叫端要求不支援的數據列包含在資料行集中。發生這種情況時，請將PT_ERROR放在屬性標籤的屬性類型部分，並將MAPI_E_NOT_FOUND放在不支援之資料行的屬性值中。

將數據列計數視為要求，而不是需求。如果查詢方向沒有數據列，您可以傳回從零個數據列到所要求數位的任何位置。

只傳回使用者從分類數據表檢視要求數據列時會看到的數據列，讓呼叫端能夠對數據範圍做出有效的假設，並避免額外的工作。

呼叫者注意事項

通常，您最後會使用 lRowCount 參數中指定的數據列數目。不過，當記憶體或實作限制是問題，或作業提前到達數據表的開頭或結尾時， QueryRows 會傳回比要求少的數據列。

如果 QueryRows 傳回MAPI_E_BUSY，請呼叫 IMAPITable：：WaitForCompletion 方法，並在異步操作完成時重試 QueryRows 的呼叫。

呼叫 QueryRows 時，請注意異步通知的時機可能會導致您從 QueryRows 取得的數據列集無法正確表示基礎數據。例如，在刪除訊息之後，但在收到對應的通知之前，呼叫 QueryRows 至資料夾的內容資料表，會導致數據列集中傳回已刪除的數據列。在更新使用者的數據檢視之前，請一律等候通知送達。

如需從數據表擷取數據列的詳細資訊，請參閱從數據表數據列擷取數據。