MAPILogonEx 

The MAPILogonEx function logs a client application on to a session with the messaging system.

Quick Info

HRESULT MAPILogonEx(

Parameters

ulUIParam

[in] Handle to the window to which the logon dialog box is modal. If no dialog box is displayed during the call, the ulUIParam parameter is ignored. This parameter can be zero.

lpszProfileName

[in] Pointer to a string containing the name of the profile to use when logging on. This string is limited to 64 characters.

lpszPassword

[in] Pointer to a string containing the password of the profile. The lpszPassword parameter can be NULL whether or not the lpszProfileName parameter is NULL. This string is limited to 64 characters.

flFlags

[in] Bitmask of flags used to control how logon is performed. The following flags can be set:

MAPI_ALLOW_OTHERS

The shared session should be returned, allowing subsequent clients to acquire the session without providing any user credentials.

MAPI_FORCE_DOWNLOAD

An attempt should be made to download all of the user s messages before returning. If the MAPI_FORCE_DOWNLOAD flag is not set, messages can be downloaded in the background after the call to MAPILogonEx returns.

MAPI_LOGON_UI

A dialog box should be displayed to prompt the user for logon information if required. When the MAPI_LOGON_UI flag is not set, the calling client does not display a logon dialog box and returns an error value if the user is not logged on. MAPI_LOGON_UI and MAPI_PASSWORD_UI are mutually exclusive.

MAPI_NEW_SESSION

An attempt should be made to create a new MAPI session rather than acquire the shared session. If the MAPI_NEW_SESSION flag is not set, MAPILogonEx uses an existing shared session even if the lpszprofileName parameter is not NULL.

MAPI_NO_MAIL

MAPI should not inform the MAPI spooler of the session s existence. The result is that no messages can be sent or received within the session except through a tightly-coupled store and transport pair. A calling client sets this flag when either configuration work must be done or the client is browsing the available message stores.

MAPI_NT_SERVICE

The caller is running as a Windows NT service. Callers that are not running as a Windows NT service should not set this flag; callers that are running as a service must set this flag.

MAPI_PASSWORD_UI

A dialog box should be displayed to prompt the user for the profile password. MAPI_PASSWORD_UI cannot be set if MAPI_LOGON_UI is set because the calling client can only present one of the two dialog boxes. This dialog box does not allow the profile name to be changed; the lpszProfileName parameter must be non-NULL

MAPI_SERVICE_UI_ALWAYS

MAPILogonEx should display a configuration dialog box for each message service in the profile. The dialog boxes are displayed after the profile has been chosen but before any message service is logged on. The MAPI common dialog box for logon also contains a check box that requests the same operation.

MAPI_TIMEOUT_SHORT

The logon should fail if blocked for more than a few seconds.

MAPI_UNICODE

The passed-in strings are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

MAPI_USE_DEFAULT

The messaging subsystem should substitute the profile name of the default profile for the lpszProfileName parameter. The MAPI_EXPLICIT_PROFILE flag is ignored unless lpszProfileName is NULL or empty.

lppSession

[out] Pointer to a pointer to the MAPI session interface.

Return Values

S_OK

The logon succeeded.

MAPI_E_LOGON_FAILED

The logon did not succeed, either because one or more of the parameters to MAPILogonEx were invalid or because there were too many sessions open already.

MAPI_E_TIMEOUT

MAPI serializes all logons through a mutex. This is returned if the MAPI_TIMEOUT_SHORT flag was set and another thread held the mutex.

MAPI_E_USER_CANCEL

The user canceled the operation, typically by clicking the Cancel button in a dialog box.

Remarks

MAPI client applications call the MAPILogonEx function to log on to a session with the messaging system. All strings passed in and returned to and from MAPI calls are null terminated and must be specified in the current character set or code page of the calling client or provider s operating system.

The lpszProfileName parameter is ignored if there is an existing previous session that called MapiLogonEx with the MAPI_ALLOW_OTHERS flag set and if the flag MAPI_NEW_SESSION is not set. If the lpszProfileName parameter is NULL or points to an empty string, and the flFlags parameter includes the MAPI_LOGON_UI flag, the MAPILogonEx function generates a logon dialog box with an empty field for the profile name.

When logging on to a specific profile, a client should pass the MAPI_NEW_SESSION flag into MAPILogonEx in addition to the profile name. Otherwise, if another client has established a shared session by logging on with MAPI_ALLOW_OTHERS, the client will be logged on to the shared session instead of to the profile requested.

The MAPI_EXPLICIT_PROFILE flag will not cause the default profile name to be used when lpszProfileName is NULL or empty unless the MAPI_USE_DEFAULT flag is also present.

The MAPI_NO_MAIL flag has several effects that result in the following when not using the MAPI spooler:

    No messages can be sent or delivered by the MAPI spooler during this session.

    Server based stores might still send or deliver messages.

    Messages sent or delivered by server based stores will not be processed by any hook providers.

    Per-message and per-recipient options for transports will not be available.

    The status table will not contain entries for transport providers, and any transport functionality dependent on status objects (such as configuration) will not be available.

    The message spooler row in the status table will contain the STATUS_FAILURE value.

    Piggybacked logons will be allowed, but those logons will not cause the previous logon to receive status object updates.

See Also

IMAPISession::GetMsgStoresTableCF6D2F, IMAPISession::OpenMsgStoreH_S8WS