Interfaces

For configuring a connector, several interfaces are available.

These can be broken down into some categories. There are interfaces used for configuring the connector, interfaces used at runtime, and finally password interfaces.

Configuration

Configuration interfaces are used during initial creation of the connector and for reconfiguring it.

There are two different interfaces for retrieving connector capabilities:

• IMAExtensible2GetCapabilities
• IMAExtensible2GetCapabilitiesEx

The first is used when you know exactly what your connector can support and you do not need any input from the administrator. The second interface provides information gathered from the administrator in the sync engine UI. As an example, this can be seen in the PowerShell connector from Microsoft. In this connector, all possible options can be configured by the administrator:

Then there are interfaces for defining the pages that appear during creation and reconfiguration. These are defined as parameter objects that should be drawn by the sync engine UI:

• IMAExtensible2GetParameters
• IMAExtensible2GetParametersEx

There is also an interface for returning the connected directory's schema to the sync engine. This interface is called on creation of the connector and when the administrator selects refresh schema in the sync engine UI.

• IMAExtensible2GetSchema

LDAP DN-style interfaces

When you configured the DN-style in the capabilities to be LDAP, then you have two additional interfaces you can implement and support:

• IMAExtensible2GetPartitions
• IMAExtensible2GetHierarchy

These interfaces are used to define the tree structure implied by LDAP. The partitions are the top-level structure and hierarchies are the children to partitions.

Import and export

There are four interfaces for working with import and export. Two file-based and two call-based. Of these, the call-based are preferred. The file-based interfaces were only added to allow backward compatibility with ECMA1. An ECMA1 connector (not using a hybrid approach of file-import and call-export) should be possible to recompile with ECMA2. For all other scenarios, the call-based interfaces should be used. File-based interfaces are not described any further - these are deprecated and not further developed.

• IMAExtensible2CallImport
• IMAExtensible2CallExport
• IMAExtensible2FileImport
• IMAExtensible2FileExport

The interfaces have three common methods:

• Open
• Get/Put
• Close

The purpose is to put everything you need to establish a connection in the Open method. Get/Put is used for the main processing. Close is used to clean-up and properly close the connection.

It might seem overly complicated and I have frequently seen code samples putting everything in the Get/Put method. The reason for why there are three is what happens when exceptions are thrown or the connector is forcefully stopped from the UI. In this case, the sync engine calls the Close method to give the connector the possibility to gracefully clean up and not leave open connections. That said, if your connector is only working with processing files and only supports full import, then there might not be anything to clean-up and easier to only implement a single method.

The interfaces also have these two properties:

• ImportDefaultPageSize/ExportDefaultPageSize
• ImportMaxPageSize/ExportMaxPageSize

These two properties determine the default value that should appear in the page (import)/batch (export) size property in the run profile and the max value the administrator can set it to:

Password management

The final category of interfaces is for password management. This interface is called to synchronize passwords from either PCNS or when set/changed using WMI.

• IMAExtensible2Password