IABProvider::Logon

The IABProvider::Logon method establishes a connection to an active session.

Quick Info

HRESULT Logon(
  LPMAPISUP lpMAPISup,          
  ULONG ulUIParam,              
  LPTSTR lpszProfileName,       
  ULONG ulFlags,                
  ULONG FAR * lpulcbSecurity,   
  LPBYTE FAR * lppbSecurity,    
  LPMAPIERROR FAR * lppMAPIError,   
  LPABLOGON FAR * lppABLogon    
);

Parameters

lpMAPISup

[in] Pointer to the address book provider's support object.

ulUIParam

[in] Handle of the parent window for the logon dialog box that Logon displays if permitted. The ulUIParam parameter contains the value of the parameter of the same name passed to MAPI in the preceding call to the MAPILogonEx function.

lpszProfileName

[in] Pointer to the name of the session profile.

ulFlags

[in] Bitmask of flags that controls how the logon is performed. The following flags can be set:

AB_NO_DIALOG: The provider should not display a dialog box during logon. If this flag is not set, the provider can display a dialog box to prompt the user for missing configuration information.
MAPI_DEFERRED_ERRORS: Allows Logon to return successfully, possibly before the logon process is complete.
MAPI_UNICODE: All strings should be in Unicode format. If the MAPI_UNICODE flag is not set, the strings should be in ANSI format.

lpulcbSecurity

[in, out] Pointer to the size, in bytes, of the security credentials structure pointed to by the lppbSecurity parameter. On input, the value must be nonzero; on output, the value must be zero. In both cases the pointers must be valid.

lppbSecurity

[in, out] Pointer to a pointer to security credentials. On input, the value must be nonzero; on output, the value must be zero. In both cases the pointer must be valid.

lppMAPIError

[out] Pointer to a pointer to a MAPIERROR structure. The lppMAPIError parameter can be set to NULL if there is no MAPIERROR structure to return.

lppABLogon

[out] Pointer to a pointer to the provider's logon object.

Return Values

S_OK: A connection to an active session was successfully established.
MAPI_E_FAILONEPROVIDER: The provider cannot log on, but MAPI can continue to log on the other providers in the message service to which the provider belongs.
MAPI_E_UNCONFIGURED: The provider does not have enough information to complete the logon. MAPI calls the provider's message service entry 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 the logon dialog box.

Remarks

Connections are established with each of the address book providers in the session profile when a client calls the IMAPISession::OpenAddressBook method. OpenAddressBook then calls each provider's IABProvider::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.

Notes to Implementers

In your implementation of IABProvider::Logon, call IMAPISupport::SetProviderUID to register a unique identifier, or MAPIUID. 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 IMAPISession::OpenEntry to open a messaging user, OpenEntry examines the MAPIUID portion of the entry identifier 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 choose to register a different MAPIUID for each logon. Registering unique MAPIUIDs enables MAPI to correctly route requests to the appropriate provider instance. However, you may choose to have every logon object share one MAPIUID. In this case, you must be able to handle the routing yourself rather than relying on MAPI. For more information on creating one or more MAPIUIDs, see Registering Service Provider Unique Identifiers.

The support object that MAPI passes to your IABProvider::Logon method in the lpMAPISup parameter provides access to many of the methods included in the IMAPISupport interface. MAPI creates a support object specially tailored 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 IMAPISupport::OpenProfileSection to retrieve security credentials for this particular logon session.

If IABProvider::Logon is successful, be sure to call the support object's IUnknown::AddRef method to increment its reference count. This allows your provider to hold onto the support object pointer for the remainder 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 belonging to the service for the rest of the session's lifetime. However, if your provider fails to establish a connection and you wish 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 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.