MAPI Search Folders
Published: July 16, 2012
A search-results folder holds links to messages in generic folders rather than the actual messages. Clients create a search-results folder by calling the IMAPIFolder::CreateFolder method with FOLDER_SEARCH as the ulFolderType parameter. Clients fill a search-results folder by setting up and applying search criteria — rules that filter out messages with particular characteristics. Search criteria are set up with the IMAPIContainer::SetSearchCriteria method. Clients build one or more SRestriction structures to represent the search criteria to be applied and pass them to SetSearchCriteria. SetSearchCriteria also specifies a list of folders that indicate the search domain and a set of flags that control how the search is performed.
SetSearchCriteria identifies the messages that match the specified restriction. The selected messages (the ones that satisfy the criteria) are displayed as links in the search-results folder. When the client calls the IMAPIContainer::GetContentsTable method to access the contents table of the search-results folder, the selected messages are displayed in the table. Contents tables for search-results folders contain the same columns as contents tables for generic folders. However, for search-results folders, the PR_PARENT_ENTRYID (PidTagParentEntryId) property specifies the entry identifier of the folder where the linked message resides. Search-results folders are not considered parent folders.
Search-results folders have the following limits:
The only way that the contents of a search-results folder can be modified is through a call to SetSearchCriteria. For more information about the implementation of SetSearchCriteria, see Knowledge Base article 260322: How To Search Folders with the SetSearchCriteria Method.
Messages cannot be moved or copied into search-results folders.
Search-results folders cannot contain subfolders.
Clients cannot make a search-results folder the subject of a search.
It is possible, however, to modify the properties of a search-results folder and use it to delete a message. When a message is deleted from a search-results folder, it is actually deleted from the real folder. However, deleting the search-results folder itself has no impact on the messages inside; they remain in their generic folders.