14.37. Synchronization Callbacks and Data Types

These typedef declarations are used for both directions of Directory Server and Active Directory synchronization and can be used for adding or modifying entries in both servers.

Table 14.18. WinSync Types

typedef Description
winsync_can_add_to_ad_cb Used to determine if a Directory Server entry should be added to the Active Directory server.
winsync_get_new_dn_cb Specifies a DN for a new entry being synced from the Active Directory server over to the Directory Server.
winsync_plugin_init_cb Initializes the synchronization plug-in.
winsync_pre_add_cb Called whenever a new entry is being added to the Directory Server.
winsync_pre_ad_mod_mods_cb Specifies modifications that must be synced over to the Active Directory server.
winsync_pre_mod_cb Sets the main entry points that allow the sync plug-in to intercept modifications between local and remote entries.
winsync_search_params_cb Sets the search parameters for the Active Directory and Directory Server instances, based on the sync agreement.

14.37.1. winsync_can_add_to_ad_cb

Sets a callbacks to determine if an entry in the Directory Server should be added to the Active Directory server if the entry does not already exist in the Windows domain.
Syntax

  

#include "slapi-plugin.h"
typedef int (*winsync_can_add_to_ad_cb)(void *cookie, const Slapi_Entry *local_entry, const Slapi_DN *remote_dn);
Parameters

This function takes the following parameters:

Parameter Description
cookie Private data used by the plug-in. This is the value returned by the Windows Sync plug-in init function (if any) and passed to all plug-in functions.
local_entry The Directory Server copy of the entry being checked by the server.
remote_dn The remote copy of the entry to add to the Active Directory server.
Returns

If the server is allowed to add the entry to the Active Directory server, then winsync_can_add_to_ad_cb declaration returns 16.

14.37.2. winsync_get_new_dn_cb

Specifies a DN for a new entry being synced from the Active Directory server over to the Directory Server instance.
When a new entry is created on the Active Directory server and it synced over to the Directory Server, it may be necessary to generate a new DN for the entry. This can result in a naming conflict between the name on one server and the generated name from the synchronization plug-in. This callback function allows the sync plug-in to set the new DN for the entry.
The map_entry_dn_inbound function is called to identify the DN for the new entry is needed. The winsync_plugin_call_pre_ds_add_* callbacks can also be used to set the DN for the new entry before it is stored in the Directory Server.
This data type is also used when an attribute with a DN as a value, such as owner or secretary, is synchronized.
Syntax

  

#include "slapi-plugin.h"
typedef void (*winsync_get_new_dn_cb)(void *cookie, const Slapi_Entry *rawentry, Slapi_Entry *ad_entry, char **new_dn_string,
  const Slapi_DN *ds_suffix, const Slapi_DN *ad_suffix);
Parameters

This function takes the following parameters:

Parameter Description
cookie Private data used by the plug-in. This is the value returned by the Windows Sync plug-in init function (if any) and passed to all plug-in functions.
rawentry The unprocessed Active Directory entry, as it is read directly from Active Directory. This entry is read-only.
ad_entry The processed Active Directory entry.
new_dn_string The given value of the DN for the new entry. The default value is created by the sync code using memory allocated by slapi_ch_malloc(). slapi_ch_free_string() is called to free this memory when it is not longer needed.
ds_suffix The Directory Server suffix being synchronized.
ad_suffix The Active Directory suffix being synchronized.
Returns

There are two possible returns:

  • For a Directory Server user, this returns 12.
  • For a Directory Server group, this returns 13.
See Also

  • winsync_plugin_call_pre_ds_add_*
  • map_entry_dn_inbound

14.37.3. winsync_plugin_init_cb

Initializes the synchronization plug-in.
Whenever synchronization begins, the sync plug-in defines this callback to initialize the other sync callbacks.
The Directory Server and Active Directory subtrees are passed in from the sync agreement as read-only attributes. The return value is private data for the sync plug-in which is passed with each sync callback. If the sync plug-in returns a value, the plug-in must define a winsync_plugin_destroy_agmt_cb callback so that the private data can be freed. This private data is passed to every other callback function as the void *cookie argument.
Syntax

  

#include "slapi-plugin.h"
typedef void * (*winsync_plugin_init_cb)(const Slapi_DN *ds_subtree, const Slapi_DN *ad_subtree);
Parameters

This function takes the following parameters:

Table 14.19. winsync_plugin_init_cb Parameters

Parameter Description
ds_subtree The Directory Server subtree being synchronized.
ad_subtree The Active Directory subtree being synchronized.
Returns

If the plug-in is successfully initialized, the server returns 1.

14.37.4. winsync_pre_add_cb

Called whenever a new entry is being added to the Directory Server after being synced over from the Active Directory server.
Syntax

  

#include "slapi-plugin.h"
typedef void (*winsync_pre_add_cb)(void *cookie, const Slapi_Entry *rawentry, Slapi_Entry *ad_entry, Slapi_Entry *ds_entry);
Parameters

This function takes the following parameters:

Table 14.20. winsync_pre_add_cb Parameters

Parameter Description
cookie Private data used by the plug-in. This is the value returned by the Windows Sync plug-in init function (if any) and passed to all plug-in functions.
rawentry The unprocessed Active Directory entry, as it is read directly from Active Directory. This entry is read-only.
ad_entry The processed Active Directory entry.
ds_entry The entry to be added to the Directory Server. Any modifications to the new entry should be made to this entry. This includes changing the DN, since the DN of this processed entry is used as the target DN for the final new entry in the Directory Server. This processed entry already has the default schema mapping applied.
Returns

There are two possible returns:

  • For a user, this returns 10.
  • For a group, this returns 11.

14.37.5. winsync_pre_ad_mod_mods_cb

Specifies modifications to be synced over to the Active Directory server from the results of an LDAP modify operation.
The plug-in may alter the list of modifications (specified as an array of LDAPMod* objects) before they are sent to Active Directory as an LDAP modify operation.
Syntax

  

#include "slapi-plugin.h"
typedef void (*winsync_pre_ad_mod_mods_cb)(void *cookie, const Slapi_Entry *rawentry, const Slapi_DN *local_dn, const Slapi_Entry *ds_entry, LDAPMod * const *origmods, Slapi_DN *remote_dn, LDAPMod ***modstosend);
Parameters

This function takes the following parameters:

Table 14.21. winsync_pre_ad_mod_mods_cb Parameters

Parameter Description
cookie Private data used by the plug-in. This is the value returned by the Windows Sync plug-in init function (if any) and passed to all plug-in functions.
rawentry The unprocessed Active Directory entry, as it is read directly from Active Directory. This entry is read-only. This can be NULL.
local_dn The original Directory Server DN specified in the modification.
ds_entry The Directory Server entry which is the source of these modifications. The modifications have already been made to this entry.
origmods The list of actual modifications made to the local entry.
remote_dn The DN of the entry on the Active Directory server to which to write the changes; this may be calculated by the sync plug-in.
modstosend The list of modifications which will be written to the Active Directory entry. The changes being sent have the attributes mapped between Directory Server and Active Directory schema so that the changes to be sent fit with Active Directory schema.
Returns

There are two possible returns:

  • If modifications are applied to a user, this returns 14.
  • If modifications are applied to a group, this returns 15.

14.37.6. winsync_pre_mod_cb

These callbacks are called as the result of an LDAP add operation, when the Win Sync code determines that the destination entry already exists. In that case, the Win Sync code converts the add operation to a modify operation, calculates the difference between the entries, and formats those differences as a list of LDAP modify operations, specified in the smods parameter. The PRE_AD functions are used when the destination is the Active Directory entry, and the PRE_DS functions are used when the destination is the Directory Server entry.
Syntax

  

#include "slapi-plugin.h"
typedef void (*winsync_pre_mod_cb)(void *cookie, const Slapi_Entry *rawentry, Slapi_Entry *ad_entry, Slapi_Entry *ds_entry, Slapi_Mods *smods, int *do_modify);
Parameters

This function takes the following parameters:

Table 14.22. winsync_pre_mod_cb Parameters

Parameter Description
cookie Private data used by the plug-in. This is the value returned by the Windows Sync plug-in init function (if any) and passed to all plug-in functions.
rawentry The unprocessed Active Directory entry, as it is read directly from Active Directory. This entry is read-only.
ad_entry The processed Active Directory entry. This DN is set if the modify is against the Active Directory entry.
ds_entry The entry to be added to the Directory Server. This DN is set if the modify is against the Directory Server entry.
smods
Pointer to an initialized Slapi_Mod. These contain the post-processing modifications. These modifications should be updated by the sync plug-in to perform any mappings or other changes.
do_modify Indicates whether an operation will be performed on the entry. If there are changes to be synced to the entry or if the sync plug-in has changed any of the smods, then this value is true, meaning that an operation should be performed on the entry. If all of the smods were removed by the sync plug-in, meaning there is no operation to perform, then the value is false.
Returns

There are four possible returns:

  • If modifications have been performed on an Active Directory user, this returns 6.
  • If modifications have been performed on an Active Directory group, this returns 7.
  • If modifications have been performed on a Directory Server user, this returns 8.
  • If modifications have been performed on a Directory Server group, this returns 9.

14.37.7. winsync_search_params_cb

Allows configurable search parameters for searches of the Directory Server and Active Directory instances during synchronization.
Syntax

  

#include "slapi-plugin.h"
typedef void (*winsync_search_params_cb)(void *cookie, const char *agmt_dn, char **base, int *scope, char **filter, char ***attrs, LDAPControl ***serverctrls);
#define WINSYNC_PLUGIN_DIRSYNC_SEARCH_CB 2 
#define WINSYNC_PLUGIN_PRE_AD_SEARCH_CB 3
#define WINSYNC_PLUGIN_PRE_DS_SEARCH_ENTRY_CB 4
#define WINSYNC_PLUGIN_PRE_DS_SEARCH_ALL_CB 5
  • WINSYNC_PLUGIN_DIRSYNC_SEARCH_CB 2 is called when the Win Sync code does the DirSync search of Active Directory looking for the initial list of entries during the init phase or for new changes during the incremental phase.
  • WINSYNC_PLUGIN_PRE_AD_SEARCH_CB 3 is called when the Win Sync code needs to search for an Active Directory entry to get more information from it during the sync process. This is used to get the rawentry or the ad_entry passed as a parameter to many of the Win Sync functions.
  • WINSYNC_PLUGIN_PRE_DS_SEARCH_ENTRY_CB 4 is called when the Win Sync code needs to search for a Directory Server entry to get more information from it during the sync process. This is used to get the ds_entry passed as a parameter to many of the Win Sync functions.
  • WINSYNC_PLUGIN_PRE_DS_SEARCH_ALL_CB 5 is called when the Win Sync code does the initial internal search of Directory Server to get all of the entries that will be synced to Active Directory.
Parameters

This function takes the following parameters:

Table 14.23. winsync_search_params_cb Parameters

Parameter Description
cookie Private data used by the plug-in. This is the value returned by the Windows Sync plug-in init function (if any) and passed to all plug-in functions.
agmt_dn The original Active Directory base DN which is specified in the sync agreement.
scope The original scope of the search on the Active Directory server. This value is explicitly set. For example: 
*scope = LDAP_SCOPE_SUBTREE;
base The base DN on the Directory Server to search for synchronization. To set this value, free the base first using slapi_ch_free_string() and allocate new memory using one of the slapi memory allocation functions. This value is then freed using slapi_ch_free_string() after use.
filter The filter to use to search for entries in the Directory Server base . To set the filter, free it along with the base using slapi_ch_free_string(). For example: 
slapi_ch_free_string(filter);
*base = slapi_ch_strdup("(objectclass=foobar)");
attrs Pointer to the Slapi_Attr structure representing the first attribute in the entry. This can be either NULL or a null-terminated array of strings. The attributes can be added using slapi_ch_array_add. For example: 
slapi_ch_array_add(attrs, slapi_ch_strdup("myattr"));
attrs are freed using slapi_ch_array_free, so the caller must own the memory.
serverctrls Pointer to the LDAPControl* structure. This can be either NULL or a null-terminated array of controls. To define the LDAPControl, use slapi_add_control_ext: 
slapi_add_control_ext(serverctrls, mynewctrl, 1 / add a copy /);
serverctrls are freed with ldap_controls_free, so the caller must own memory.
Returns

There are four possible returns:

  • For a DirSync search, this returns 2.
  • To search the Active Directory subtree, this returns 3.
  • To search the Directory Server subtree, this returns 4.
  • To search the Directory Server from the base DN, this returns 5.