Edit

Share via

MAPILOGON callback function (mapi.h)

  • Article

[The use of this function is discouraged. It may be altered or unavailable in subsequent versions of Windows.]

The MAPILogon function begins a Simple MAPI session, loading the default message store and address book providers.

Syntax

MAPILOGON Mapilogon;

ULONG Mapilogon(
  [in]           ULONG_PTR ulUIParam,
  [in, optional] LPSTR lpszProfileName,
  [in, optional] LPSTR lpszPassword,
  [in]           FLAGS flFlags,
                 ULONG ulReserved,
  [out]          LPLHANDLE lplhSession
)
{...}

Parameters

[in] ulUIParam

Parent window handle or zero, indicating that if a dialog box is displayed, it is application modal. If the ulUIParam parameter contains a parent window handle, it is of type HWND (cast to a ULONG_PTR). If no dialog box is displayed during the call, ulUIParam is ignored.

[in, optional] lpszProfileName

Pointer to a null-terminated profile name string, limited to 256 characters or less. This is the profile to use when logging on. If the lpszProfileName parameter is NULL or points to an empty string, and the flFlags parameter is set to MAPI_LOGON_UI, MAPILogon displays a logon dialog box with an empty name field.

[in, optional] lpszPassword

Pointer to a null-terminated credential string, limited to 256 characters or less. If the messaging system does not require password credentials, or if it requires that the user enter them, the lpszPassword parameter should be NULL or point to an empty string. When the user must enter credentials, the flFlags parameter must be set to MAPI_LOGON_UI to allow a logon dialog box to be displayed.

[in] flFlags

Bitmask of option flags. The following flags can be set.

Value Meaning
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 function call returns.
MAPI_NEW_SESSION
An attempt should be made to create a new session rather than acquire the environment's shared session. If the MAPI_NEW_SESSION flag is not set, MAPILogon uses an existing shared session.
MAPI_LOGON_UI
A logon dialog box should be displayed to prompt the user for logon information. If the user needs to provide a password and profile name to enable a successful logon, MAPI_LOGON_UI must be set.
MAPI_PASSWORD_UI
MAPILogon should only prompt for a password and not allow the user to change the profile name. Either MAPI_PASSWORD_UI or MAPI_LOGON_UI should not be set, since the intent is to select between two different dialog boxes for logon.

ulReserved

Reserved; must be zero.

[out] lplhSession

Simple MAPI session handle.

Return value

This function returns one of the following values.

Return code Description
MAPI_E_FAILURE
One or more unspecified errors occurred during logon. No session handle was returned.
MAPI_E_INSUFFICIENT_MEMORY
There was insufficient memory to proceed. No session handle was returned.
MAPI_E_LOGIN_FAILURE
There was no default logon, and the user failed to log on successfully when the logon dialog box was displayed. No session handle was returned.
MAPI_E_TOO_MANY_SESSIONS
The user had too many sessions open simultaneously. No session handle was returned.
MAPI_E_USER_ABORT
The user canceled the logon dialog box. No session handle was returned.
SUCCESS_SUCCESS
The call succeeded and a Simple MAPI session was established.

Remarks

The MAPILogon function begins a session with the messaging system, returning a handle that can be used in subsequent MAPI calls to explicitly provide user credentials to the messaging system. To request the display of a logon dialog box if the credentials presented fail to validate the session, set the flFlags parameter to MAPI_LOGON_UI.

The client application tests for an existing session by calling MAPILogon with a NULL value for the lpszProfileName parameter, a NULL value for the lpszPassword parameter and by not setting the MAPI_LOGON_UI flag in flFlags. If there is an existing session, the call succeeds and returns a valid LHANDLE for the session. Otherwise, the call fails.

Requirements

Requirement Value
Target Platform Windows
Header mapi.h

See also

MAPILogoff

Simple MAPI