About the Replication API

Article
06/14/2014

About the Replication API

The Replication API provides the functionality for a MAPI message store provider to synchronize Outlook items between a server and a private .pst-based local store that is created for that provider.

Note
A MAPI message store provider must implement the Replication API according to the instructions in About the Replication State Machine. The provider must use the API only on a personal store created for itself, and not on personal stores created for other providers, because personal stores created for other providers may have already set up their own replication mechanisms with the respective server. For example, an offline folder file (.ost) maintains its own replication relationship with a Microsoft Exchange server.

A MAPI message store provider must implement the Replication API according to the instructions in About the Replication State Machine. The provider must use the API only on a personal store created for itself, and not on personal stores created for other providers, because personal stores created for other providers may have already set up their own replication mechanisms with the respective server. For example, an offline folder file (.ost) maintains its own replication relationship with a Microsoft Exchange server.

To use the Replication API, a MAPI message store provider must first open and wrap a .pst-based local store by calling NSTServiceEntry. The provider can then use the major interfaces of the API, IOSTX and IPSTX, to carry out replication. IPSTX is provided by querying on IMsgStore, and IOSTX is provided by IPSTX::GetSyncObject.

The IOSTX Interface

The IOSTX interface is the primary interface that performs synchronization in the Replication API. IOSTX moves the local store through a series of states, retrieving information in each state about changes in the local store, as well as informing the local store of changes on the server. The Replication API also specifies many data structures that support the synchronization.

A store provider, as a client to this API, uses the Replication API to wrap the local store and move through these states, pushing changes on the local store (such as changes to the folder hierarchy or the addition of new items) to the server, and also retrieving information about changes on the server and providing that information to the IOSTX interface. The IOSTX interface adopts Incremental Change Synchronization (ICS) provided by Microsoft Exchange Server. For more information about ICS, see ICS Evaluation Criteria. Through IOSTX, the client uses ICS to monitor and synchronize incremental changes to the hierarchy or content on a local store.

The IPSTX Interface

IPSTX and five other IPSTXn interfaces that inherit from IPSTX provide helper functionality that can be used when performing replication through the IOSTX interface. For example, IPSTX::EmulateSpooler allows you to make the local store emulate the Outlook Protocol Manager to spool outgoing messages to a server.

For more information about state transitions during replication, see About the Replication State Machine.

The Replication API

The Replication API provides the following defintions, data types, and interfaces. For a sample implementation of a store provider for wrapped Personal Folders files (PST), see About the Sample Wrapped PST Store Provider.

Definitions:

Constants for the Replication API

Functions:

Data types: