IMAPIContainer::SetSearchCriteria

The IMAPIContainer::SetSearchCriteria method establishes search criteria for the container.

Quick Info

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

Parameters

lpRestriction

[in] Pointer to an SRestriction structure defining the search criteria. If NULL is passed in the lpRestriction parameter, then the search criteria used most recently for this container are used again. NULL should not be passed in lpRestriction for the container's first search.

lpContainerList

[in] Pointer to an array of entry identifiers representing containers to be included in the search. If a client passes NULL in the lpContainerList parameter, then the entry identifiers used most recently to search this container are used for the new search. A client should not pass NULL in lpContainerList for the first search within a container.

ulSearchFlags

[in] Bitmask of flags that controls how the search is performed. The following flags can be set:

BACKGROUND_SEARCH: The search should run at normal priority relative to other searches. This flag cannot be set at the same time as the FOREGROUND_SEARCH flag.
FOREGROUND_SEARCH: The search should run at high priority relative to other searches. This flag cannot be set at the same time as the BACKGROUND_SEARCH flag.
RECURSIVE_SEARCH: The search should include the containers specified in the lpContainerList parameter and all of their child containers. This flag cannot be set at the same time as the SHALLOW_SEARCH flag.
RESTART_SEARCH: The search should be initiated, if this is the first call to SetSearchCriteria, or restarted, if the search is inactive. This flag cannot be set at the same time as the STOP_SEARCH flag.
SHALLOW_SEARCH: The search should only look in the containers specified in the lpContainerList parameter for matching entries. This flag cannot be set at the same time as the RECURSIVE_SEARCH flag.
STOP_SEARCH: The search should be aborted. This flag cannot be set at the same time as the RESTART_SEARCH flag.

Return Values

S_OK: The search criteria was successfully set.
MAPI_E_TOO_COMPLEX: The service provider does not support the search criteria specified.

Remarks

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 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 only works on this merged contents table; it does not search through other search-results folders. The search results only return the messages that match the search criteria; the folder hierarchy is not returned.

Control is returned to the client when the search has finished.

Notes to Implementers

Address book containers establish search critieria 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.

Notes to Callers

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. To search for attachments, set the ulSubObject member to PR_MESSAGE_ATTACHMENTS. Set the lpRes member to point to a property restriction describing the search criteria for the recipients or attachments.

For example, to look for file attachments with the extension .MSS, set ulSubObject to PR_MESSAGE_ATTACHMENTS and lpRes to a property restriction that matches PR_ATTACH_EXTENSION with MSS.

Setting the FOREGROUND_SEARCH flag in the ulSearchFlags parameter might cause a performance degradation.

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 on search-results folders, see Search-Results Folders.