Creating a Directory Synchronization Agent

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.

Design Tasks

Determine what foreign system will be the source or recipient of directory data.
Decide whether your directory synchronization agent will be used to import from the foreign system into Microsoft Exchange Server, export from Microsoft Exchange Server to the foreign system, or transfer data in both directions.
Decide whether your directory synchronization agent will be run upon demand or on a configurable schedule. DIRSYNC currently is a command-line application, so you could write a batch procedure to make it run periodically.
Decide whether to make your directory synchronization agent run as a service of Windows NT Server. One purpose for this is to make the agent controllable through the Windows NT service control manager.
Choose a user interface. This agent you build starting with DIRSYNC can remain a command-line application, or you can incorporate DIRSYNC code into a Windows program.

Implementation Tasks

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:

A module that reads data from the foreign system. This module then transfers data in one of two ways: see the sections Transferring Data Using Files and Transferring Data Using Structures. These sections refer to this export functionality (which you will need to write from scratch) as the Dirsync Agent.
A module that reads the exported data and writes it to the Microsoft Exchange Server directory. For this, you can use the DSYNCOMM import functions (see Functions of DSYNCOMM in the About Sample Source Code section).

An agent that exports data to a foreign system consists of:

A module that reads from the Microsoft Exchange Server directory. This module then transfers data in one of two ways: see the sections Transferring Data Using Files and Transferring Data Using Structures. For this, you can use the DSYNCOMM export functions (see Functions of DSYNCOMM in the About Sample Source Code section).
A module that reads the exported data and writes it to the foreign system. You will need to write this functionality from scratch.

Transferring Data Using Files

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.

Transferring Data Using Structures

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.

About Sample Source Code

The DIRSYNC sample application contains code showing directory synchronization. Its two modules are compiled from the DIRSYNC.C and DSYNCOMM.C files:

DIRSYNC This file contains sample code showing directory synchronization using directory access functions. It implements both the inbound and outbound direction. That is, it can import from an external mail system or other software system into the Microsoft Exchange Server directory and exporting from the Microsoft Exchange Server directory to an external mail system or other software system. It compiles to an executable file that is run from the command line.
DSYNCOMM The functions in this file communicate with the foreign system. These routines perform directory synchronization by reading and writing to a file in a format that can be used for directory exchange. They were designed so that developers can easily replace them with their own functions. For example, they could be rewritten to communicate directly with a foreign mail system's messaging interface, or to make read/write calls to a database. The functions in this file are called by the code in DIRSYNC.C.

Functions of DSYNCOMM

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.