Finding a Message in a Message Store

There are various tasks related to finding a message in a message store. The tasks are different, depending on the client interface you are using for your client and the message store. Some message stores support searching; others do not. Create a prototype to determine whether or not a particular search strategy will work.

If the message store supports searches, your client can use a search-results folder to locate messages. Clients written with the MAPI client interface can either create a new search-results folder or use a pre-existing one. Clients written with the Active Messaging Library must use a pre-existing search-results folder.

If the message store does not support searches, your client will have to traverse the message store hierarchy, looking through each folder for the target message rather than using search criteria.

Specifically, this topic explains how to:

• Create a search-results folder using the MAPI client interface.
• Locate an existing search-results folder using the Active Messaging Library.
• Perform a search in a searchable message store using the MAPI client interface.

Design Tasks

1. Determine whether or not the message store supports searches, meaning the ability to create search-results folders. Clients using message stores that support searches can use a search-results folder to find a message; clients using non-searchable message stores must traverse the folder hierarchy.
2. For clients using message stores that support searches, determine whether or not the message store supports the type of restrictions you will be imposing. For example, if you want to use a property restriction, make sure that the message store supports the specific property.

Implementation Tasks

1. Retrieve the PR_STORE_SUPPORT_MASK property from the message store by calling its IMAPIProp::GetProps method. If the STORE_SEARCH_OK flag is set, proceed. If this flag is not set, there are two choices:
   • Fail because the message store does not support searches.
   • Attempt the alternate strategy of enumerating the message store hierarchy.
2. Create a search-results folder if possible. See the following procedure.
3. If creating a search-results folder is not possible, locate an existing search-results folder. MAPI creates a default search-results folder called Search Root when it initializes a message store. Creating search-results folders is not allowed if you are using the Active Messaging Library. See the following procedure.
4. Build a restriction that reflects your search criteria. See About Restrictions. If you are searching on a named property, call the IMAPIProp::GetIDsFromNames method to create a searchable property tag from the name.
5. Start the search by calling the search-results folder's IMAPIContainer::SetSearchCriteria method. Pass the BACKGROUND_SEARCH or FOREGROUND_SEARCH flag as appropriate, the restriction, and the entry identifier of the folder in which to search.
6. Retrieve the search results by opening the search-results folder's contents table and querying the rows. You can process this incrementally or wait for an fnevSearchComplete notification from the message store.

    To create a search-results folder using the MAPI client interface

1. Locate and open the target message store. See Opening a Message Store or Opening the Default Message Store.
2. Retrieve the message store's PR_FINDER_ENTRYID property — the entry identifier of the root search-results folder.
3. Open the root search-results folder by calling IMsgStore::OpenEntry with the entry identifier from the PR_FINDER_ENTRYID property.
4. Create a new folder in the root search-result folder by calling the root folder's IMAPIFolder::CreateFolder method. Set the ulFolderType parameter to FOLDER_SEARCH. See Search-Results Folders.

    To locate an existing search-results folder using the Active Messaging Library

1. Locate and open the target message store using the Session.InfoStores collection. An InfoStore object provides access to the root folder for a message store.
2. Retrieve the folder's FolderID property to identify its parent folder and pass this identifier in a call to Session.GetFolder to open the parent folder.
3. Work up through the folder hierarchy by repeating the previous step until the FolderID property is the same in two sequential iterations. When this occurs, you will be at the root folder of the message store.
4. Retrieve the Folders collection and browse for the folder whose name is Search Root. MAPI always creates a folder by that name when it initializes a message store.
5. Retrieve the root search-results folder's Folders collection and browse for your own search-results folder by name.

    To locate an existing search-results folder using the MAPI client interface

1. Locate and open the target message store. See Opening a Message Store or Opening the Default Message Store.
2. Retrieve the message store's PR_FINDER_ENTRYID property — the entry identifier of the root search-results folder.
3. Open the root search-results folder by calling IMsgStore::OpenEntry with the entry identifier from the PR_FINDER_ENTRYID property.
4. Access the folder's hierarchy table by calling IMAPIFolder::GetHierarchyTable.
5. Look for a row in the table that has a PR_FOLDER_TYPE column set to FOLDER_SEARCH and a PR_DISPLAY_NAME column set to Search Root. MAPI always creates a folder by that name when it initializes a message store.

About Sample Source Code

See the following topic:

Sample Messaging Hook Provider