IXPProvider::TransportLogon

The IXPProvider::TransportLogon method establishes a session in which a user logs on to a transport provider.

Quick Info

See IXPProvider : IUnknownBN7R1W.

HRESULT TransportLogon(

Parameters

lpMAPISup

[in] Pointer to the transport provider s support object for callback functions within MAPI for this session. This object remains valid until the transport provider releases it.

ulUIParam

[in] Handle of the parent window for any dialog boxes or windows this method displays. The ulUIParam parameter can be non-null, for example when the LOGON_SETUP flag is set in the lpulFlags parameter.

lpszProfileName

[in] Pointer to the profile name of the user. The lpszProfileName parameter is used primarily when a dialog box must be presented.

lpulFlags

[in, out] Bitmask of flags that controls how the logon session is established. The following flags can be set on input by the MAPI spooler:

LOGON_NO_CONNECT

The user account is logging on to this transport provider for purposes other than transmission and reception of messages. The transport provider should not attempt to make any connections.

LOGON_NO_DIALOG

No dialog box should be displayed even if the currently saved user credentials are invalid or insufficient for logon.

LOGON_NO_INBOUND

The transport provider does not need to initialize for reception of messages and should not accept incoming messages. The MAPI spooler can use the IXPLogon::TransportNotify2OI457V method to signal the transport provider to enable inbound message processing.

LOGON_NO_OUTBOUND

The transport provider does not need to initialize for sending messages, as the MAPI spooler does not provide any. If a client application requires a connection to a remote provider during the composition of a message so that it can make IXPLogon::AddressTypes1JYXH3N or IXPLogon::RegisterOptionsD9M544 method calls, the transport provider should make the connection. The MAPI spooler can use TransportNotify to signal the transport provider when outbound operations can begin.

MAPI_UNICODE

The passed-in string for the profile name is in Unicode format. If the MAPI_UNICODE flag is not set, the string is in ANSI format.

The following flags can be set on output by the transport provider:

LOGON_SP_IDLE

Requests that the MAPI spooler frequently call the transport provider s IXPLogon::Idle15L.GJQ method for idle-time processing.

LOGON_SP_POLL

Requests that the MAPI spooler frequently call the IXPLogon::PollCC7S3H method on the returned logon object to check for new messages. If this flag is not set, the MAPI spooler only checks for new messages when the transport provider calls the IMAPISupport::SpoolerNotifyRYSE6K method. A transport provider effectively becomes send-only by not setting this flag and by not notifying the MAPI spooler of message receipt.

LOGON_SP_RESOLVE

Requests that the MAPI spooler resolve to full addresses all message addresses for recipients not supported by this transport provider, so that the transport provider can construct a reply path for all recipients.

MAPI_UNICODE

The returned strings in the MAPIERROR4GS6AI structure, if any, are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

lppMAPIError

[out] Pointer to a pointer to the returned MAPIERROR structure, if any, containing version, component, and context information for the error. The lppMAPIError parameter can be set to NULL if there is no MAPIERROR structure to return.

lppXPLogon

[out] Pointer to the pointer to the returned transport provider logon object.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_FAILONEPROVIDER

This provider cannot log on, but this error should not disable the service.

MAPI_E_UNCONFIGURED

The profile does not contain enough information for the logon to complete. MAPI calls the provider s message service entry point function.

MAPI_E_UNKNOWN_CPID

The server is not configured to support the client's code page.

MAPI_E_UNKNOWN_LCID

The server is not configured to support the client's locale information.

MAPI_E_USER_CANCEL

The user canceled the operation, typically by clicking the Cancel button in a dialog box.

Remarks

The MAPI spooler calls the IXPProvider::TransportLogon method to establish a logon session for a user.

Most transport providers use the IMAPISupport::OpenProfileSectionJSWD36 method provided with the support object pointed to by the lpMAPISup parameter for saving and retrieving user identity information, server addresses, and credentials. Using OpenProfileSection enables a transport provider to 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 needed to access resources for that session. MAPI hides information associated with a resource from outside access. The profile section made available through lpMAPISup is segregated 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 for 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 might need to do additional work at logon to establish the proper 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 thus generally precedes 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 inbound and outbound 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 connection is to 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 to support any scheduled connections and 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 regular intervals; rather, it is called only during true idle time, so providers should not work on any assumption about how frequently their Idle methods will be called. Providers that support idle-time operations should supply the correct configuration user interface 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 for the MAPI spooler to use for further 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 failing provider belongs. MAPI will not call any providers belonging to that service for the rest of the life 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 entire service for the life 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 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.

See Also