MAPILogonEx

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

Quick Info

Header file: MAPIX.H
Implemented by: MAPI
Called by: Client applications 

HRESULT MAPILogonEx(
  ULONG ulUIParam,                
  LPTSTR lpszProfileName,         
  LPTSTR lpszPassword,            
  FLAGS flFlags,                  
  LPMAPISESSION FAR * lppSession  
);

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_EXPLICIT_PROFILE
The default profile should not be used, and the user should be required to supply a profile.
MAPI_EXTENDED
Log on with extended capabilities. This flag should always be set. The older MAPILogon function is no longer available.
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 if it is acting as an agent, if configuration work must be done, or if 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 does 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:

An agent should always log on using the MAPI_NO_MAIL flag.

See Also

MAPI Initialization Functions, IMAPISession::GetMsgStoresTable, IMAPISession::OpenMsgStore