Loading Message Store Providers

When a client application opens a message store, MAPI loads the message store provider's DLL into memory. After loading the DLL, a very specific sequence of method calls occurs between the message store provider and MAPI. This method call sequence enables MAPI to get top-level IMSProvider:IUnknown IMSLogon:IUnknown, and IMsgStore:IMAPIProp objects, and allows the message store provider to get a MAPI support object. After the call sequence, the message store provider should be ready to accept logons from clients.

The call sequence when a message provider DLL is loaded is:

1. Client calls IMAPISession::OpenMsgStore.
2. If the message store is not already open, MAPI loads the store provider's DLL and calls the DLL's MSProviderInit entry point. If the message store is already open, MAPI skips steps 2 and 3, then uses the existing IMSProvider object to complete step 4.
3. MSProviderInit creates and returns an IMSProvider object.
4. MAPI calls IMSProvider::Logon, passing the client application's message store entry identifier.
5. IMSProvider::Logon creates and returns an IMSLogon object and an IMsgStore object, then calls the IUnknown::AddRef method on its IMAPISupport:IUnknown object. If the client's message store entry identifier refers to a message store that is already open, the message store provider can return existing IMSLogon and IMsgStore objects, and does not need to call AddRef on its support object.
6. If the client did not set the MAPI_NO_MAIL flag when it logged on and it did not set the MDB_NO_MAIL in step 1, then MAPI gives the message store's entry identifier to the MAPI spooler so the MAPI spooler can log on to the message store.
7. MAPI returns the IMsgStore object to the client.
8. The MAPI spooler calls IMSProvider::SpoolerLogon.
9. IMSProvider::SpoolerLogon returns the same IMSLogon object and IMsgStore object from step 5.

Note  If the logon call to the message store provider fails because an incorrect password was supplied and the message store provider cannot display an interface to ask for the correct password, it should return MAPI_E_FAILONEPROVIDER from the IMSProvider::Logon method. This will allow clients to prompt the user for a password to try logging on to the message store provider again instead of causing MAPI to fail the provider for the entire session.