Syntax
MAPILogon(UIParam, User$, Password$, Flags, Reserved)
Remarks
Begins a session with the messaging system. You can log in to the messaging system in two ways, using simple MAPI mail calls:
Any MAPI function call made outside an established MAPI session generates a log-in dialog box, which the calling application can suppress. In this case, when the call returns, the session is terminated and the messaging system returns to its state before the call was made. For example, a user logged off from the messaging system before the call would also be logged off after the call was completed.
If you want to maintain a session over a number of simple MAPI calls,
you can use the MAPILogon function to provide a session handle to the messaging system. This session handle can be used in subsequent MAPI calls to explicitly provide user credentials to the messaging system. A flag is available to display a log-in dialog box if the credentials presented fail to validate the session. You can pass an empty password, although it may not validate the mail session.
MAPILogon returns a session handle. A negative value for the handle indicates an error. Currently, 0 (zero) is a valid session handle.
Argument | Explanation |
UIParam | The parent window handle for the dialog box. A value of 0 (zero) specifies that any dialog box displayed is application modal. |
User$ | A client account-name string, limited to 256 characters or fewer. An empty string ("") indicates that a log-in dialog box with an empty name field should be generated (if the appropriate flag is set). |
Password$ | A credential string, limited to 256 characters or fewer. An empty string ("") indicates that a log-in dialog box with an empty password field should be generated (if the appropriate flag is set) or that the messaging system does not require password credentials. |
Argument | Explanation |
Flags | A bitmask of flags. Unspecified flags should always be set to MAPI_LOGON_UI = 1 Set MAPI_LOGON_UI if the function should display a dialog box Set MAPI_NEW_SESSION to establish a session other than the current one. For instance, if a mail client is already running, another MAPI e-mail client can piggyback on the session created by the mail client application. Do not set this flag if you want the default session (if it still exists). Set MAPI_FORCE_DOWNLOAD to force a download of all new messages from the mail server to a user's Inbox during the log-in process. Use this flag so an application can deal with the user's complete set of messages when it logs in. When this flag is set, a progress indicator is displayed, and is automatically removed when the process is complete. Use of this flag may increase processing time. |
Reserved | Reserved for future use. This argument must be 0 (zero). |
The following table lists the possible return values of the MAPILogon function and their meanings.
Value | Name | Meaning |
–2 | MAPI_E_FAILURE | One or more unspecified errors occurred during log-in. No session handle was returned. |
–5 | MAPI_E_INSUFFICIENT_MEMORY | There was insufficient memory to proceed. No session handle was returned. |
–3 | MAPI_E_LOGIN_FAILURE | There was no default log-in, and the user failed to log in successfully when the log-in dialog box was displayed. No session handle was returned. |
–8 | MAPI_E_TOO_MANY_SESSIONS | The user had too many sessions open at once. No session handle was returned. |
Value | Name | Meaning |
–1 | MAPI_USER_ABORT | The user canceled the process. No session handle was returned. |
0 | SUCCESS_SUCCESS | The function returned successfully. |
Example
The following example begins a Mail session and downloads new mail into the Inbox.
Sub MAIN MAPI_LOGON_UI = 1 MAPI_FORCE_DOWNLOAD = 4096 Flags = MAPI_LOGON_UI + MAPI_FORCE_DOWNLOAD Session = MAPILogon(0, "", "", Flags, 0) result = MAPILogoff(Session, 0, 0, 0) End Sub