Published: July 16, 2012
Establishes search criteria for the container.
The IMAPIContainer::SetSearchCriteria method establishes search criteria for a container that supports searches, typically a search-results folder. A search-results folder contains links to the messages that meet the search criteria; the actual messages are still stored in their original locations. The only unique data that is contained in a search-results folder is its contents table. The contents table of a search-results folder has the merged contents of the message store after the search restriction has been applied.
A search operation works only on this merged contents table; it does not search through other search-results folders. The search results return only the messages that match the search criteria; the folder hierarchy is not returned.
Control is returned to the client when the search has finished.
Address book containers establish search criteria by applying restrictions to their contents tables. For more information about search criteria and address book containers, see Implementing Advanced Searching.
You should support open, copy, move, and delete operations on the messages within search-results folders, not on the search-results folder itself. Do not allow messages to be created within or copied into a search-results folder.
To search for message recipients, set lpRestriction to point to a subobject restriction with the ulSubObject member in the SSubRestriction structure set to PR_MESSAGE_RECIPIENTS (PidTagMessageRecipients). To search for attachments, set the ulSubObject member to PR_MESSAGE_ATTACHMENTS (PidTagMessageAttachments). Set the lpRes member to point to a property restriction that describes the search criteria for the recipients or attachments.
For example, to look for file attachments that have the extension .mss, set ulSubObject to PR_MESSAGE_ATTACHMENTS and lpRes to a property restriction that matches PR_ATTACH_EXTENSION (PidTagAttachExtension) with .mss.
Setting the FOREGROUND_SEARCH flag in the ulSearchFlags parameter could cause a decrease in system performance.
You can use SetSearchCriteria to change the search criteria of a search already in progress. You can specify new restrictions, new lists of folders to search, and a new search priority, such as upgrading a search to a higher priority. Changes in search priority do not cause an existing search to restart, but other changes to search criteria can.
When you are through using a search-results folder, you can either delete the folder or let it remain open for later use. If you do delete the search-results folder, only message links are deleted. The actual messages remain in their parent folders.
For more information about search-results folders, see MAPI Search Folders.