Loading Message Store Providers
Applies to: Office 2010 | Outlook 2010 | Visual Studio
When a client application opens a message store, MAPI loads the message store provider's DLL into memory. After MAPI loads 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 interfaces, 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 as follows:
The client calls IMAPISession::OpenMsgStore.
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, and then uses the existing IMSProvider : IUnknown interface to complete step 4.
MSProviderInit creates and returns an IMSProvider object.
MAPI calls IMSProvider::Logon, passing the client application's message store entry identifier.
IMSProvider::Logon creates and returns an IMSLogon : IUnknown interface and an IMsgStore : IMAPIProp interface, and then calls the IUnknown::AddRef method on its IMAPISupport : IUnknown interface. 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 interfaces and does not need to call AddRef on its support object.
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, MAPI gives the message store's entry identifier to the MAPI spooler so the MAPI spooler can log on to the message store.
MAPI returns the IMsgStore interface to the client.
The MAPI spooler calls IMSProvider::SpoolerLogon.
IMSProvider::SpoolerLogon returns the same IMSLogon and IMsgStore interfaces 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.