Accessing Objects by Using the Session

Applies to: Office 2010 | Outlook 2010 | Visual Studio

The session pointer that you receive from your call to MAPILogonEx can be used to access a wide variety of objects. The following table lists the methods that are used to access various objects:

With the OpenEntry method and a valid entry identifier, you can open any address book or message store provider object. There are other OpenEntry methods in MAPI, in addition to the IMAPISession method. OpenEntry is implemented in the following objects:

Some OpenEntry methods require an entry identifier of the object to be opened, as does IMAPISession::OpenEntry; other methods allow NULL to be specified. A NULL entry identifier is interpreted differently depending on the object. For example, when you call IAddrBook::OpenEntry with a NULL entry identifier, MAPI opens the root container of the address book. The message store's OpenEntry method behaves similarly; it opens the root folder of the message store. IMAPIContainer::OpenEntry, implemented by both folders and address book containers, might return MAPI_E_INVALID_PARAMETER or the root container, depending on the implementer.

In addition to disallowing a NULL value for the entry identifier, the session's OpenEntry method differs from other OpenEntry methods because its job is not to open objects. Instead, it examines the entry identifier and forwards the call to another OpenEntry method implemented by the appropriate service provider. For example, if you call IMAPISession::OpenEntry with the entry identifier of a message, MAPI calls the IMSLogon::OpenEntry method of the message store responsible for the message.

In addition to using the session to open objects, clients use it to compare them. The IMAPISession::CompareEntryIDs method compares objects by comparing their entry identifiers. If the MAPIUID structures contained within the entry identifiers belong to the same service provider, MAPI forwards the call to that provider. CompareEntryIDs returns an error value when the two entry identifiers do not match. Although this method can compare entry identifiers that belong to any type of object, CompareEntryIDs works best for higher level objects such as message stores and address book containers. To compare lower level objects, compare directly the objects' search keys (PR_SEARCH_KEY (PidTagSearchKey)) or record keys (PR_RECORD_KEY (PidTagRecordKey)).

Like OpenEntry, CompareEntryIDs is implemented by multiple objects. Choose which OpenEntry and CompareEntryID method to use according to the amount of information that you have about the object or objects to be opened or compared. Use the following guidelines when deciding which interface method to call:

• If you have no information about the target objects, call IMAPISession::OpenEntry or IMAPISession::CompareEntryIDs. This approach enables access to any object, but is the slowest of the three.

• If you know that the target objects are address book entries rather than, for example, folders, call the IAddrBook::OpenEntry or IAddrBook::CompareEntryIDs method. IAddrBook::OpenEntry opens the root container of the address book when NULL is specified as the target object. This approach enables access to any address book object and is faster than using IMAPISession, but slower than using IMAPIContainer.

• If the entry identifier being used is a short-term entry identifier or if you know that the target objects belong to a particular address book container or folder, call the IMAPIContainer::OpenEntry method. This approach yields the fastest performance, but enables access only to objects in a specific container or folder.