IMAPIContainer::GetSearchCriteria

The IMAPIContainer::GetSearchCriteria method obtains the search criteria for the container.

Quick Info

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

Parameters

ulFlags

[in] 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] Pointer to a pointer to an SRestriction structure defining the search criteria. If a client application passes NULL in the lppRestriction parameter, GetSearchCriteria does not return an SRestriction structure.

lppContainerList

[out] Pointer to a pointer to an array of entry identifiers representing 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] 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 does not return any flags. The following flags can be set for lpulSearchState:

SEARCH_FOREGROUND: The search is running at high priority relative to other searches. If this flag is not set, the search is running at normal priority relative to other searches.
SEARCH_REBUILD: The search is in the CPU-intensive mode of its operation, attempting 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 only has meaning 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 of 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.

Return Values

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 only supports Unicode.
MAPI_E_NOT_INITIALIZED: Search criteria were never established for the container.

Remarks

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

Notes to Implementers

Address book containers only need to support GetSearchCriteria if they provide the advanced search capabilities associated with the PR_SEARCH property. For more information on implementing the advanced search feature for address book containers, see Implementing Advanced Searching.

Notes to Callers

When you are finished with the data structures pointed to by the lppRestriction and lppContainerList parameters, call MAPIFreeBuffer to release the structures — one call to release each structure.