IMAPIContainer：：SetSearchCriteria

發行項
03/15/2024

適用於：Outlook 2013 |Outlook 2016

建立容器的搜尋準則。

HRESULT SetSearchCriteria(
  LPSRestriction lpRestriction,
  LPENTRYLIST lpContainerList,
  ULONG ulSearchFlags
);

參數

lpRestriction

[in]定義搜尋準則之 SRestriction 結構的指標。如果在 lpRestriction 參數中傳遞 NULL，則會再次使用最近用於此容器的搜尋準則。在容器中進行第一次搜尋時，不應在 lpRestriction 中傳遞 NULL。

lpContainerList

[in]項目標識子陣列的指標，代表要包含在搜尋中的容器。如果用戶端在 lpContainerList 參數中傳遞 NULL，則最近用來搜尋此容器的專案標識碼會用於新的搜尋。用戶端不應該在 lpContainerList 中傳遞 NULL，以進行容器中的第一個搜尋。

ulSearchFlags

[in]控制搜尋執行方式的旗標位掩碼。您可以設定下列旗標：

BACKGROUND_SEARCH

相對於其他搜尋，搜尋應該以一般優先順序執行。這個旗標無法與FOREGROUND_SEARCH旗標同時設定。

FOREGROUND_SEARCH

相對於其他搜尋，搜尋應該以高優先順序執行。這個旗標無法與BACKGROUND_SEARCH旗標同時設定。

NON_CONTENT_INDEXED_SEARCH

搜尋不應使用內容索引來尋找相符的專案。此旗標僅適用於 Exchange 商店。

RECURSIVE_SEARCH

搜尋應該包含 lpContainerList 參數中指定的容器及其所有子容器。這個旗標無法與SHALLOW_SEARCH旗標同時設定。

RESTART_SEARCH

如果這是第一次呼叫 SetSearchCriteria，則應該起始搜尋，如果搜尋為非使用中，則應重新啟動搜尋。這個旗標不能與STOP_SEARCH旗標同時設定。

SHALLOW_SEARCH

搜尋應該只會在 lpContainerList 參數中指定的容器中查看比對專案。這個旗標無法與RECURSIVE_SEARCH旗標同時設定。

STOP_SEARCH

搜尋應該會停止。這個旗標無法與RESTART_SEARCH旗標同時設定。

傳回值

S_OK

搜尋準則已成功設定。

MAPI_E_TOO_COMPLEX

服務提供者不支援指定的搜尋準則。

註解

IMAPIContainer：：SetSearchCriteria 方法會為支持搜尋的容器建立搜尋準則，通常是 search-results 資料夾。 search-results 資料夾包含符合搜尋準則之訊息的連結;實際訊息仍會儲存在其原始位置。 search-results 資料夾中唯一包含的數據是其內容數據表。在套用搜尋限制之後，search-results 資料夾的內容表具有訊息存放區的合併內容。

搜尋作業只適用於這個合併的內容數據表;它不會搜尋其他搜尋結果資料夾。搜尋結果只會傳回符合搜尋準則的訊息;不會傳回資料夾階層。

搜尋完成時，控制權會傳回給用戶端。

實作者注意事項

通訊簿容器會藉由將限制套用至其內容數據表來建立搜尋準則。如需搜尋準則和通訊簿容器的詳細資訊，請參閱實作進階搜尋。

您應該支援在 search-results 資料夾內的訊息上開啟、複製、移動和刪除作業，而不是在 search-results 資料夾本身。不允許在 search-results 資料夾內建立或複製訊息。

呼叫者注意事項

若要搜尋郵件收件者，請將 lpRestriction 設定為指向 SSubRestriction 結構中 ulSubObject 成員設為 PR_MESSAGE_RECIPIENTS (PidTagMessageRecipients) 的子物件限制。若要搜尋附件，請將 ulSubObject 成員設定為 PR_MESSAGE_ATTACHMENTS (PidTagMessageAttachments) 。將 lpRes 成員設定為指向屬性限制，以描述收件者或附件的搜尋準則。

例如，若要尋找擴展名為 .mss 的檔案附件，請將 ulSubObject 設定為 PR_MESSAGE_ATTACHMENTS ，並將 lpRes 設定為符合 PR_ATTACH_EXTENSION (PidTagAttachExtension) 與 .mss 的屬性限制。

在 ulSearchFlags 參數中設定 FOREGROUND_SEARCH 旗標可能會導致系統效能降低。

您可以使用 SetSearchCriteria 來變更已在進行中搜尋的搜尋準則。您可以指定新的限制、要搜尋的新資料夾清單，以及新的搜尋優先順序，例如將搜尋升級為較高的優先順序。搜尋優先順序的變更不會導致現有搜尋重新啟動，但搜尋準則的其他變更可以。

當您使用 search-results 資料夾時，可以刪除該資料夾，或讓它保持開啟狀態以供稍後使用。如果您刪除 search-results 資料夾，則只會刪除訊息連結。實際的訊息會保留在其父資料夾中。

如需 search-results 資料夾的詳細資訊，請參閱 MAPI 搜尋資料夾。

MFCMAPI 參考

如需 MFCMAPI 範例程式代碼，請參閱下表。

檔案	Function	Comment
HierarchyTableDlg.cpp	CHierarchyTableDlg：：OnEditSearchCriteria	MFCMAPI 會使用 IMAPIContainer：：SetSearchCriteria 方法，在使用者編輯資料夾之後撰寫資料夾的搜尋準則。