Last modified: July 23, 2011
Applies to: Outlook
Establishes a session in which a client application logs on to a transport provider.
The MAPI spooler calls the IXPProvider::TransportLogon method to establish a logon session for a user.
Most transport providers use the IMAPISupport::OpenProfileSection method provided with the support object pointed to by the lpMAPISup parameter for saving and retrieving user identity information, server addresses, and credentials. By using OpenProfileSection, a transport provider can save arbitrary information and associate it with a logon to a particular resource. For example, a provider can use OpenProfileSection to save the account name and password associated with a particular session and any server names or other necessary information that are required to access resources for that session. MAPI hides information associated with a resource from outside access. The profile section made available through lpMAPISup is managed by the MAPI spooler so data related to this user context is separated from data for other contexts.
The transport provider must call the IUnknown::AddRef method on the support object and keep a copy of the pointer to this object as part of the provider logon object.
The profile display name in lpszProfileName is provided so the transport provider can use it in error messages or logon dialog boxes. If the provider retains this name, it must be copied to storage allocated by the provider.
Transport providers that are tightly coupled with other service providers may have to do additional work at logon to establish the good credentials required for operations between companion providers.
Usually, transport providers are opened when the user first logs on to a profile. Because the first logon to a profile therefore generally comes before logon to any message store, the MAPI spooler usually calls TransportLogon with both the LOGON_NO_INBOUND and LOGON_NO_OUTBOUND flags set in lpulFlags. Later, when the appropriate message stores are available in the profile session, the MAPI spooler calls TransportNotify to initiate incoming and outgoing operations for the transport provider.
Passing the LOGON_NO_CONNECT flag in lpulFlags signals offline operation of the transport provider. This flag indicates no external connections should be made; if the transport provider cannot establish a session without an external connection, it should return an error value for the logon.
A transport provider should set the LOGON_SP_IDLE flag in lpulFlags at initialization time if it is designed to use time that the system otherwise spends idle. Such time is often used to handle automatic operations, such as automatic message downloading, timed message downloading, or timed message submission. If this flag is set, the MAPI spooler calls Idle when system idle time occurs to initiate such operations. The MAPI spooler does not call Idle at set intervals; rather, it is called only during true idle time. Therefore, providers should not work on any assumption about how frequently their Idle methods will be called. Providers that support idle-time operations should supply a configuration user interface for it in their provider property sheet.
If the transport provider logon succeeds, the provider should return in the lppXPLogon parameter a pointer to a logon object. The MAPI spooler will use this object for additional provider access. If TransportLogon displays a logon dialog box and the user cancels logon typically by clicking the Cancel button in the dialog box the provider should return MAPI_E_USER_CANCEL.
For most error values returned from TransportLogon, MAPI disables the message services to which the provider belongs. MAPI will not call any providers that belong to that service for the rest of the MAPI session. In contrast, when TransportLogon returns the MAPI_E_FAILONEPROVIDER error value from its logon, MAPI does not disable the message service to which the provider belongs. TransportLogon should return MAPI_E_FAILONEPROVIDER if it encounters an error that does not warrant disabling the service for the rest of the session.
If a provider returns MAPI_E_UNCONFIGURED from its logon, MAPI will call the provider's message service entry function and then retry the logon. MAPI passes MSG_SERVICE_CONFIGURE as the context, to give the service a chance to configure itself. If the client has chosen to allow a user interface on the logon, the service can present its configuration property sheet so that the user can enter configuration information.
If the provider finds that all the required information is not in the profile, it should return MAPI_E_UNCONFIGURED so that MAPI calls the provider's message service entry point function.