IMAPIContainer::GetSearchCriteria

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

Quick Info

See IMAPIContainer : IMAPIProp6IZN.5.

HRESULT GetSearchCriteria(

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 SRestriction1TRSEKP 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::SetSearchCriteriaEKSF1. 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::SetSearchCriteriaEKSF1. method.

Notes to Implementers

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

Notes to Callers

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

See Also