Implementing Service Provider Logon

This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

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:

• IABProvider::Logon for address book providers

• IMSProvider::Logon for message store providers

• IXPProvider::TransportLogon for transport providers

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:

   • PR_DISPLAY_NAME (PidTagDisplayName)

   • PR_ENTRYID (PidTagEntryId)

   • PR_PROVIDER_DISPLAY (PidTagProviderDisplay)

   • PR_RECORD_KEY (PidTagRecordKey)

     Note
     Do not attempt to set the profile section's PR_RESOURCE_FLAGS or PR_PROVIDER_DLL_NAME properties. At logon time, these properties are read-only.

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
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.

See Also

Concepts

Starting a Service Provider