MAPILogon (VB)

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

Quick Info

MAPILogon(

    UIParam ByVal as Long,
    User as String,
    Password as String,
    Flags as Long,
    Reserved as Long,
    Session as Long) as Long

Parameters

UIParam

[in] Parent window handle or zero, indicating that if a dialog box is displayed, it is application modal. If no dialog box is displayed during the call, the UIParam parameter is ignored.

User

[in] Client account-name string, limited to 256 characters or less. This is the name to use when logging on. If the User parameter is empty, and the Flags parameter is set to MAPI_LOGON_UI, MAPILogon displays a logon dialog box with an empty name field.

Password

[in] 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 Password parameter should be empty. When the user must enter credentials, the Flags parameter must be set to MAPI_LOGON_UI to allow a logon dialog box to be displayed.

Flags

[in] Bitmask of option flags. The following flags can be set:

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_LOGON_UI

A logon dialog box should be displayed to prompt the user for logon information. If the user needs to provide information to enable a successful logon, MAPI_LOGON_UI must be set.

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.

Reserved

Reserved; must be zero.

Session

[out] Simple MAPI session handle.

Return Values

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 process. No session handle was returned.

SUCCESS_SUCCESS

The call succeeded and a 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 Flags parameter to MAPI_LOGON_UI.

The declaration of this function for the 32-bit Visual Basic runtime is:

MAPILogon(

     ByVal UIParam&,
    ByVal User$,
    ByVal Password$,
    ByVal Flags&,
    ByVal Reserved&,
    Session&) As Long