Search-Results Folders

A search-results folder holds links to messages in generic folders rather than the actual messages. Clients create a search-results folder by calling IMAPIFolder::CreateFolder with FOLDER_SEARCH as the ulFolderType parameter. Clients fill a search-results folder by setting up and applying search criteria, or rules that serve to 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. Also specified is a list of folders indicating the search domain and a set of flags controlling details of how the search is performed.

SetSearchCriteria identifies the messages that match the specified restriction. The selected messages, the ones that satisfy the criteria, appear as links in the search-results folder. When the client calls IMAPIContainer::GetContentsTable to access the search-results folder's contents table, the selected messages appear in the table. Contents tables for search-results folders contain the same columns as contents tables for generic folders. However, for search-results folders, PR_PARENT_ENTRYID is the entry identifer 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 the IMAPIContainer::SetSearchCriteria call.
• Messages cannot be moved or copied into or out of search-results folders.
• Search-results folders cannot contain subfolders.
• Clients cannot set search criteria on a search-results folder, making it 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 has no impact on the messages inside; they remain in their generic folders.