IMAPIContainer::GetSearchCriteria

Last modified: January 16, 2009

Applies to: Office 2010 | Outlook 2010 | Visual Studio

In this article
Notes to Implementers
Notes to Callers
MFCMAPI Reference

Obtains the search criteria for the container.

HRESULT GetSearchCriteria(
  ULONG ulFlags,
  LPSRestriction FAR * lppRestriction,
  LPENTRYLIST FAR * lppContainerList,
  ULONG FAR * lpulSearchState
);

ulFlags

[in] A bitmask of flags that controls the type of the passed-in strings. The following flag can be set:

MAPI_UNICODE

The passed-in strings are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

lppRestriction

[out] A pointer to a pointer to an SRestriction structure that defines the search criteria. If a client application passes NULL in the lppRestriction parameter, GetSearchCriteria does not return an SRestriction structure.

lppContainerList

[out] A pointer to a pointer to an array of entry identifiers that represent containers to be included in the search. If a client passes NULL in the lppContainerList parameter, GetSearchCriteria does not return an array of entry identifiers.

lpulSearchState

[out] A pointer to a bitmask of flags used to indicate the current state of the search. If a client passes NULL in the lpulSearchState parameter, GetSearchCriteria returns no flags. The following flags can be set:

SEARCH_FOREGROUND

The search should run at high priority relative to other searches. If this flag is not set, the search runs at normal priority relative to other searches.

SEARCH_REBUILD

The search is in the CPU-intensive mode of its operation, trying to locate messages that match the criteria. If this flag is not set, the CPU-intensive part of the search's operation is over. This flag has meaning only if the search is active (that is, if the SEARCH_RUNNING flag is set).

SEARCH_RECURSIVE

The search is looking in specified containers and all their child containers for matching entries. If this flag is not set, only the containers explicitly included in the last call to the IMAPIContainer::SetSearchCriteria method are being searched.

SEARCH_RUNNING

The search is active and the container's contents table is being updated to reflect changes in the message store or address book. If this flag is not set, the search is inactive and the contents table is static.

S_OK

The search criteria was successfully obtained.

MAPI_E_BAD_CHARWIDTH

Either the MAPI_UNICODE flag was set and the implementation does not support Unicode, or MAPI_UNICODE was not set and the implementation supports only Unicode.

MAPI_E_NOT_INITIALIZED

Search criteria were never established for the container.

The IMAPIContainer::GetSearchCriteria method obtains the search criteria for a container that supports searches, typically a search-results folder. You create search criteria by calling a container's IMAPIContainer::SetSearchCriteria method.

Address book containers may need to support GetSearchCriteria only if they provide the advanced search capabilities associated with the PR_SEARCH (PidTagSearch) property. For more information about how to implement the advanced search feature for address book containers, see Implementing Advanced Searching.

When you are finished with the data structures pointed to by the lppRestriction and lppContainerList parameters, call MAPIFreeBuffer once for each structure to be released.

For MFCMAPI sample code, see the following table.

File

Function

Comment

HierarchyTableDlg.cpp

CHierarchyTableDlg::OnEditSearchCriteria

MFCMAPI uses the IMAPIContainer::GetSearchCriteria method to obtain search criteria from a folder to display.

Show:
© 2014 Microsoft