MAPI Sessions

Before your client application can call an underlying messaging system, it must establish a session, or connection, with the MAPI subsystem. Sessions are initiated when a user logs on, a process that consists of accessing a valid profile, validating messaging system and message service credentials, and insuring that all of the profile's message services are properly configured. The client interface you use determines the logon call. MAPI clients call the MAPILogonEx function, Simple MAPI clients call the MAPILogon function, CMC clients call the cmc_logon function, and Collaboration Data Objects (CDO) Library clients call the Session object's Logon method.

MAPI supports the validation of credentials, such as passwords, as an optional feature. The use and implementation of passwords depends on the messaging system being used and the operating system. Some operating systems support security that is based on user accounts; others do not. Passwords can either be saved in the profile or entered by the user with every logon.

The following table lists the MAPI operating systems and whether or not each type implements user account security.

Message service configuration is one of the most important parts of the logon process. The profile is the initial source for configuration information. If information for a particular message service is missing, the logon process attempts to prompt the user to supply it, an attempt which is not always successful for two reasons. Prompting the user requires the display of a dialog box. It is possible for clients to disallow the display of a user interface by passing a flag into the logon call. A second possible reason for failure is the cancellation of the dialog box by the user before the needed information can be added.

When a logon process fails once, the user is informed of the failure and given the opportunity to retry or correct the error condition. Once again, a user interface will be displayed, if possible, and the user will be prompted to enter whatever data is missing. If this second attempt proves unsuccessful, MAPI disables all service providers in the message service for the duration of the session. In effect, the whole message service is disabled, meaning that none of the service providers in the message service can work. This is done because if one provider fails logon, the other providers usually also fail. The logon process can fail due to an invalid path for a necessary resource, an incompatible version of MAPI, an unavailable messaging server, or data corruption.

Clients can specify one of two types of sessions to be established in the logon call: an individual session or a shared session. Individual sessions are private connections; there is a one-to-one relationship between a client application and the session it is using. As a consequence, client applications sharing a session also share a profile. Shared sessions are established once but can be "used" by other client applications who need to use them. The profile and credentials are specified only with the initial logon.

MAPI also supports unified logon, in which a single initial logon to the messaging system results in access to multiple workgroup applications. When working with unified logon, users do not have to enter a name and password for each application they want to use.

Clients can log on multiple times as the same user or as multiple users. MAPI does not prevent this. Some service providers, however, might not be as flexible, returning the error value MAPI_E_SESSION_LIMIT on subsequent logon attempts. Service providers with underlying hardware limitations can be required to enforce a session limit.

The function calls for establishing a session have a collection of flags and parameters that control how the session is created. The client specifies an optional profile name, password, and a window handle that acts as the parent window for any dialog boxes that are displayed. The flags include MAPI_NEW_SESSION to request that a new, individual session be established rather than establishing a connection to a shared session, and two user interface flags, MAPI_LOGON_UI and MAPI_PASSWORD_UI. The user interface flags are set to request either a logon dialog box or a password dialog box.

The following illustration shows how these various parameters and flags establish a MAPI session.

For information about handling sessions from within a client application, see Session Handling.