Implementing Service Provider Logon

Last modified: July 23, 2011

Applies to: Outlook

MAPI calls a method in your provider object to begin the logon process by using the pointer that you return from your entry point function. The method varies as follows, depending on the type of your service provider:

Perform the following tasks in whatever logon method you implement:

  1. Increment the reference count on the support object that is passed as an input parameter by calling its IUnknown::AddRef method.

  2. Call the support object's IMAPISupport::OpenProfileSection method to access your profile section.

  3. Call the profile section's IMAPIProp::SetProps method to set the following properties:

  4. Check that the properties you need for configuration are either stored in the profile or are available from the user. For more information about checking your configuration, see Verifying Service Provider Configuration.

  5. Call the support object's IMAPISupport::SetProviderUID method to register a unique identifier, or MAPIUID, if your provider is an address book or message store provider. Transport providers register MAPIUID structures when MAPI calls their IXPLogon::AddressTypes method. For more information about registering a MAPIUID, see Registering Service Provider Unique Identifiers.

  6. Instantiate a logon object and return with one of the following values:

    • S_OK to indicate a successful logon.

    • MAPI_E_UNCONFIGURED to indicate that one or more of the configuration properties were unavailable.

    • MAPI_E_USER_CANCEL to indicate that the user canceled the configuration dialog box, causing configuration properties to be unavailable.

    • MAPI_E_FAILONEPROVIDER to indicate that your provider could not be configured, but that MAPI should allow it to be used regardless. Logon methods should return this value to report a nonfatal error, such as when the provider requires a password and cannot prompt the user for it because the user interface is disabled.

The preceding list of tasks describes a minimum implementation for a service provider logon method. You can include additional functionality, if necessary. For example, some providers call IMAPISupport::ModifyStatusRow to update the status table in their logon method.

Note Note

To achieve the best performance at logon time, avoid calling either IMAPISupport::PrepareSubmit or IMAPISupport::SpoolerNotify. Before these calls can complete and return control to your logon method, the MAPI spooler must be started.