Implementing Service Provider Logon

With the pointer that you return from your entry point function, MAPI calls a method in your provider object to begin the logon process. This 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	PR_ENTRYID
   PR_PROVIDER_DISPLAY	PR_RECORD_KEY

   
   

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 MAPIUIDs 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 non-fatal error, such as when the provider requires a password and cannot prompt the user for it because the user interface is disabled.

   For more information about logon objects, see Implementing a Logon Object.

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.