IMAPIContainer::SetSearchCriteria
The IMAPIContainer::SetSearchCriteria
method establishes search criteria for the container.
Quick Info
See IMAPIContainer
: IMAPIProp.
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 Searching16QMCV..
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.
See Also