Published: July 16, 2012
Establishes a connection to an active session.
Connections are established with each address book provider in the session profile when a client calls the IMAPISession::OpenAddressBook method. OpenAddressBook then calls each provider's Logon method.
The profile name pointed to by the lpszProfileName parameter is displayed in the character set of the user's client as indicated by the presence or absence of the MAPI_UNICODE flag in the ulFlags parameter.
In your implementation of the Logon method, call the IMAPISupport::SetProviderUID method to register a unique identifier, or MAPIUID structure. Each of your objects will have an entry identifier that includes this MAPIUID. MAPI uses the MAPIUID to match an object with its provider. For example, when a client calls the IMAPISession::OpenEntry method to open a messaging user, OpenEntry examines the MAPIUID portion of the entry identifier that was passed in and matches it with a MAPIUID registered by an address book provider.
If a client logs on to your provider more than once, you may want to register a different MAPIUID for each logon. Registering unique MAPIUID structures enables MAPI to correctly route requests to the appropriate provider instance. However, you may want to have every logon object share one MAPIUID. In this case, you must be able to handle the routing yourself instead of relying on MAPI. For more information about how to create a MAPIUID, see Registering Service Provider Unique Identifiers.
The support object that MAPI passes to your Logon method in the lpMAPISup parameter provides access to many of the methods included in the IMAPISupport : IUnknown interface. MAPI creates a support object that is customized to your type of provider. For example, if you need to log on to an underlying messaging system or directory service when you establish your connection, you can call the IMAPISupport::OpenProfileSection method to retrieve security credentials for this particular logon session.
If Logon is successful, be sure that you call the support object's IUnknown::AddRef method to increment its reference count. This enables your provider to hold onto the support object pointer for the rest of the session. If you do not call this AddRef method, MAPI will unload your provider.
You can include the profile name passed in the lpszProfileName parameter in error dialog boxes, logon screens, or other user interfaces. To use the profile name, copy it to storage that you have allocated.
Create a logon object and return a pointer to it in the lppABLogon parameter. MAPI uses this logon object to make calls to the methods in your IABLogon implementation.
If you require a password during logon, display a logon dialog box only if the AB_NO_DIALOG flag is not set. If the user cancels the logon process, typically by clicking the Cancel button in the dialog box, return MAPI_E_USER_CANCEL from Logon.
Typically, when an address book provider cannot log on, MAPI disables the message service to which the failing provider belongs—that is, MAPI will not try to establish connections for any of the other providers that belong to the service for the rest of the session's lifetime. However, if your provider cannot establish a connection and you want not to disable the entire service, return either MAPI_E_FAILONEPROVIDER or MAPI_E_UNCONFIGURED. MAPI will not disable the message service to which the provider belongs.
Return MAPI_E_FAILONEPROVIDER if an error occurs that is not serious enough to prevent the other providers in the message service from establishing connections. Return MAPI_E_UNCONFIGURED if the necessary configuration information is missing from the profile and you cannot display a dialog box to prompt the user. MAPI will respond by calling your provider's message service entry point function with MSG_SERVICE_CONFIGURE set as the ulContext parameter to give the service a chance to configure itself, either programmatically or using a property sheet. When the message service entry point function has finished, MAPI retries the logon.