IMAPIContainer::GetSearchCriteria

This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

Obtains the search criteria for the container.

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

Parameters

• 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.

Return Value

• 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.

Remarks

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.

Notes to Implementers

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.

Notes to Callers

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.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

See Also

Reference

IMAPIContainer::SetSearchCriteria

IMAPIFolder::CreateFolder

MAPIFreeBuffer

PidTagSearch Canonical Property

IMAPIContainer : IMAPIProp

Concepts

MFCMAPI as a Code Sample