This quick start procedure discusses how to design and implement a directory synchronization agent for use with the Microsoft Exchange Server directory.
This procedure uses code from the DIRSYNC sample application, which demonstrates how to transfer mailboxes and custom recipient information between foreign systems and a container on Microsoft Exchange Server. In its current form, the DIRSYNC sample application also shows how to use the directory access functions to build a transfer agent.
Communication with the foreign system is the functionality you will add to the existing DIRSYNC sample application. Depending on the tasks it will perform, your directory synchronization agent will need to export data and format it as required by DIRSYNC, or read the data exported by DIRSYNC and format it correctly for import into the foreign system.
You can use the code in DSYNCOMM.C as the basis for parts of your directory synchronization agent. Export and import functionality can reside in one program or be divided into two agents, as described here.
An agent that imports data from a foreign system consists of:
An agent that exports data to a foreign system consists of:
The export and import functions of DSYNCOMM write to and read from a file on the disk in the required DIRSYNC format. The agent you write that communicates with the foreign system must interpret this format when reading data exported from Microsoft Exchange Server, and convert data into this format after exporting it from the foreign system.
The following illustration shows this design strategy (with focus on data import), in which two separate processes run concurrently. You write the component labeled Dirsync Agent, which extracts data from the foreign system's directory system (or other database) and writes it to a file on disk in DIRSYNC format. Then, DIRSYNC calls DSYNCOMM functions to read data from this file and import it into the Microsoft Exchange Server directory.
Data Import Using a File
The process is similar for data export, but carried out in reverse. DSYNCOMM functions are used to export directory data into a file. The Dirsync Agent reformats that data as required by the foreign system and writes it into the foreign system's database.
Using structures makes disk access unnecessary and enables directory synchronization with only one running process. You use the functions in DSYNCOMM.C to communicate with the directory service of Microsoft Exchange Server, but you transfer directory data using structures instead of a file.
You will need to write your own functions to read from and write to the foreign system. In the following illustration, this functionality is represented by the component labeled Dirsync Agent, whose code is linked to that of DIRSYNC. The Dirsync Agent temporarily stores exported data in memory as structures of the type DAPI_ENTRY. This data is then imported into the Microsoft Exchange Server directory with the DSYNCOMM import functions. This design is shown (with focus on data import) in the following illustration.
Data Import Using Structures
The process is similar for data export, but carried out in reverse. The DSYNCOMM functions export directory data into structures. The functions of the Dirsync Agent read that data, reformat it into the form required by the foreign system, and write it into the foreign system.
The DIRSYNC sample application contains code showing directory synchronization. Its two modules are compiled from the DIRSYNC.C and DSYNCOMM.C files:
The DSYNCOMM.C file contains functions that are called by the code in DIRSYNC.C. The DSYNCOMM functions communicate with the foreign system by reading from and writing to a file in a specific format. These functions were designed so that developers can replace them with their own functions. For example, they could be rewritten to make database read/write calls.
DSYNCOMM uses three primary functions for importing data.
DSYNCOMM Export Functions
Function | Description |
---|---|
HrOpenExport | Performs all necessary initialization before exporting records for directory synchronization. |
HrWriteExport | Exports a single record for directory synchronization. It is called repeatedly: once for each record to be exported. |
HrCloseExport | Performs all necessary cleanup after exporting records for directory synchronization. |
DSYNCOMM uses three primary functions for exporting data.
DSYNCOMM Import Functions
Function | Description |
---|---|
HrOpenImport | Performs all necessary initialization before importing records for directory synchronization. |
HrReadImport | Imports a single record for directory synchronization. It is called repeatedly: once for each record to be imported. When there are no more records to import, HrReadImport should return EDK_E_END_OF_FILE. |
HrCloseImport | Performs all necessary cleanup after importing records for directory synchronization. |