Platform SDK: Exchange Server

Using MAPI in Multithreaded Applications

A thread is the basic entity to which a 32-bit operating system allocates CPU time. A thread has its own registers, stack, priority, and storage, but shares an address space and process resources such as access tokens. Threads also share memory, with one thread reading what another thread has written.

MAPI clients and service providers such as Microsoft Exchange Server use the following generic threading models.

Threading model	Description
Single threading model	All objects are used on the single thread.
Apartment threading model	An object is used only on the thread that created it.
Free threading (thread-party) model	An object is used on any thread.

MAPI and MAPI service providers use the free threading model, supporting thread-safe objects that can be used on any thread at any time. The current version of OLE uses the apartment threading model. The apartment threading model supports objects that must be explicitly transferred when a thread that did not create an object uses that object.

The mechanism used by OLE to transfer objects from one thread to another is known as marshaling. Marshaling involves a stub object and a proxy object. These objects package the parameters of the interface in the object to be marshaled, transfer these parameters to the other thread, and unpackage them upon arrival. Conflict between the two multithreaded models arises when a free-threading MAPI object is sent to another process using OLE LRPC (Lightweight Remote Procedure Call). LRPC changes the object's semantics from free threading to apartment threading by interposing stub and proxy interfaces with apartment threading behavior between the object and its caller. Awareness of the situations in MAPI that lead to this conflict helps prevent problems between clients and service providers.

A MAPI object can be accessed in the following ways:

Through direct calls to its methods using an interface pointer returned by a service provider or MAPI linked to the client's process, such as the session object returned from MAPILogonEx.
Through indirect calls to its methods using an interface pointer returned by any service provider, such as the folder object copied from another folder in IMAPIFolder::CopyFolder.
Through a callback function, such as the IMAPIAdviseSink::OnNotify method passed to a service provider or to MAPI in an Advise call or the methods that can show progress on a lengthy operation.