IMAPITable：：FindRow
適用於：Outlook 2013 |Outlook 2016
尋找數據表中符合特定搜尋準則的下一個數據列，並將游標移至該數據列。
HRESULT FindRow(
LPSRestriction lpRestriction,
BOOKMARK BkOrigin,
ULONG ulFlags
);
參數
lpRestriction
[in]描述搜尋準則 之 SRestriction 結構的指標。
BkOrigin
[in]識別 FindRow 應該開始搜尋之數據列的書籤。 您可以使用 IMAPITable：：CreateBookmark 方法建立書籤，或者可以傳遞下列其中一個預先定義的值。
BOOKMARK_BEGINNING
從數據表開頭搜尋。
BOOKMARK_CURRENT
從數據指標所在的數據表中的數據列進行搜尋。
BOOKMARK_END
從數據表結尾搜尋。
ulFlags
[in]控制搜尋方向的旗標位掩碼。 您可以設定下列旗標：
DIR_BACKWARD
從書籤所識別的數據列向後搜尋。
傳回值
S_OK
尋找作業成功。
MAPI_E_INVALID_BOOKMARK
BkOrigin 參數中的書籤無效，因為它已移除，或因為超過最後一個要求的數據列。
MAPI_E_NOT_FOUND
找不到符合限制的數據列。
MAPI_W_POSITION_CHANGED
呼叫成功，但作業中使用的書籤不再設定為與上次使用時相同的數據列;如果尚未使用書籤，就不再與建立書籤時的位置相同。 傳回此警告時，應將呼叫視為成功處理。 若要測試此警告，請使用 HR_FAILED 宏。 請參閱 使用宏進行錯誤處理。
註解
IMAPITable：：FindRow 方法會找出數據表中的第一個數據列，以符合 lpRestriction 參數所指向之 SRestriction 結構中所述的一組搜尋準則。
通常， FindRow 會從指定的書籤往前搜尋。 呼叫端可以藉由在 ulFlags 參數中設定 DIR_BACKWARD旗標，將搜尋設定為從書籤往後移動。 向前搜尋會從目前的書籤開始;向後搜尋會從書籤之前的數據列開始。 搜尋的結束位置就在找到符合限制的第一個數據列之前。
如果 BkOrigin 參數中書籤所指向的數據列已不存在數據表中，而且數據表無法建立書籤的新位置， FindRow 會傳回MAPI_E_INVALID_BOOKMARK。 如果 BkOrigin 所指向的數據列已不存在，而且數據表能夠建立書籤的新位置， FindRow 會傳回MAPI_W_POSITION_CHANGED。
如果 傳入 BkOrigin 的書籤是BOOKMARK_BEGINNING或BOOKMARK_END，則如果找不到相符的數據列， FindRow 會傳回MAPI_E_NOT_FOUND。 如果 BkOrigin 中使用的書籤 BOOKMARK_CURRENT，FindRow 可以傳回MAPI_W_POSITION_CHANGED但無法MAPI_E_INVALID_BOOKMARK，因為一律有目前的數據指標位置。
所有數據表都需要 PR_INSTANCE_KEY (PidTagInstanceKey) 屬性數據行，而且 需要 FindRow 的所有實作才能支援根據PR_INSTANCE_KEY搜尋數據列的呼叫。
實作者注意事項
只有在搜尋遵循與數據表組織相同的方向時， FindRow 所執行的前置詞搜尋類型才有用。 為了達到必要的行為，在屬性限制結構中傳遞 的RELOP_GE 所隱含的比較函式應該是數據表排序順序所依據的相同比較函式。
呼叫者注意事項
您可以使用 FindRow ，根據使用者輸入的字串來支援卷動，特別是在位址對話框內的清單框中。 在此類型的捲動中，用戶會輸入所需字串值逐漸較長的前置詞，而且您可以定期發出 FindRow 呼叫，跳至符合前置詞的第一個數據列。 游標的跳轉方向取決於搜尋設定為執行的方向。
若要使用 FindRow，必須設定書籤。 字串搜尋可以源自任何書籤，包括預設書籤，指出目前的位置以及數據表的開頭和結尾。 如果數據表中有大量數據列，搜尋作業可能會變慢。
使用限制來尋找卷動的字串前置詞，如下所示。 若要在以遞增順序排序的數據行上進行向前搜尋，以及在以遞減順序排序的數據行上進行向後搜尋，請使用格式標記GE前置詞，在 lpRestriction 參數中傳遞具有關聯RELOP_GE和適當屬性標記和前置詞的屬性限制結構。
如需使用限制結構來指定篩選的詳細資訊，請參閱 關於限制。
MFCMAPI 參考
如需 MFCMAPI 範例程式代碼，請參閱下表。
| 檔案 | Function | Comment |
|---|---|---|
| ContentsTableListCtrl.cpp |
DwThreadFuncLoadTable |
MFCMAPI 使用 IMAPITable：：FindRow 方法來尋找符合限制的數據列。 |