Using Multiple Client Interfaces

Most client applications will use one client API — either the Active Messaging Library, Simple MAPI, CMC or MAPI. However, some clients will need to take advantage of what more than one client API has to offer. These clients should use MAPI for some tasks and a simpler API for others. The MAPI architecture allows client applications to do this fairly easily by providing several API functions for converting between the environments.

One common conversion task involves identifiers. Identifiers are used throughout MAPI to uniquely represent a component, such as a message or a service provider. MAPI uses a binary structure called an entry identifier; the Active Messaging Library uses a hexadecimal entry identifier, Simple MAPI uses a string called a message identifier, and CMC uses a string called a message reference. Identifiers can be simple or compound. Compound identifiers are supported by some message stores and are used with messages. They have two parts: one part that contains the record key of the message store and another part that contains the entry identifier of the message.

MAPI only provides the means to convert between MAPI entry identifiers and all other identifiers. It does not provide the means for converting between Simple MAPI and CMC, Simple MAPI and the Active Messaging Library, or CMC and the Active Messaging Library.

The following API functions are used to translate identifiers used by the different client API sets:

FBinFromHex

HexFromBin

HrSzFromEntryID

HrEntryIDFromSz

HrComposeEID

HrDecomposeEID

HrComposeMsgID

HrDecomposeMsgID

The FBinFromHex and HexFromBin functions are used to translate the binary entry identifiers used in the MAPI programming interface and the hexadecimal entry identifiers used in the Active Messaging Library.

The HrEntryIDFromSz function creates a MAPI entry identifier from a Simple MAPI string identifier and the HrSzFromEntryID function performs the opposite operation, producing a Simple MAPI string identifier from a MAPI entry identifier.

The HrComposeMsgID function also creates a Simple MAPI identifer. However, HrComposeMsgID creates a compound entry identifier, or identifier that can be used by Simple MAPI clients to open a nondefault message store. Compound entry identifiers for messages are built from the record key of the message store and the message's entry identifier. A message store's record key is a unique binary value that can be used for comparison. Calling HrComposeMsgID enables Simple MAPI clients to create the identifiers necessary for working with multiple message stores.

The HrComposeEID function is similar to HrComposeMsgID because it is also used for creating compound entry identifiers. However, whereas HrComposeMsgID is primarily for Simple MAPI clients, HrComposeEID is for CMC clients. Callers of HrComposeEID pass a session pointer, a message store record key, and the entry identifier of an object. HrComposeEID produces a MAPI entry identifier based on both the record key and entry identifier, if possible, or only the entry identifier if the record key is not available.

HrDecomposeEID separates a compound entry identifier into its parts: a message store record key and an entry identifier that represents a MAPI object. Use HrDecomposeEID with care; it is an expensive call. Both HrComposeEID and HrDecomposeEID can handle binary message identifiers that require string versions.

Because HrComposeEID, HrComposeMsgID, HrDecomposeEID, and HrDecomposeMsgID all require a MAPI session pointer as input, client applications that are not started with the MAPI logon function, MAPILogonEx, must translate the current session handle into a MAPI session before calling any of these functions. HrEntryIDFromSz, a function that does not require a session pointer, can also be used to create a compound entry identifier. However, subsequent uses of this entry identifier can fail. If possible, clients should use the HrComposeMsgID or HrComposeEID function instead.

Converting session types is possible with one of two API functions: ScMAPIXFromCMC or ScMAPIXFromSMAPI. To convert CMC sessions into MAPI sessions, use ScMAPIXFromCMC. To convert Simple MAPI sessions, use ScMAPIXFromSMAPI. Both functions take the current session handle as input and return a pointer to a MAPI session object.

When using multiple client APIs, exercise caution in interpreting return values. Client APIs do not share the same set of return values, nor do they return the same type of values. For example, Simple MAPI and CMC functions return unique sets of unsigned long values whereas MAPI functions and methods return values that are of type HRESULT. In all cases, zero means a successful result.

The unsigned long values and the HRESULT values are based on a numeric code which, in many cases, is the same for all caller types. However, there are a few cases where the values are different. The following table lists the differences between the values returned by Simple MAPI and MAPI.