14.36. Replication Session Hooks Callbacks

Client applications can have some control over when the Directory Server performs replication by using custom plug-ins that define replication session hooks. The hooks apply to both the master sending the information and the consumer receiving the information. Basically, the master sends a preliminary message to the consumer and the consumer sends a response message. If either side sends a message that does not meet the expected criteria (such as the server version or some schema requirement), then the replication operation is terminated.
The intent of replication session hooks is to require some kind of parity between the servers involved in replication. If there is a situation that could cause conflicts or data corruption — such as different server versions which use different sets of schema — then the session hooks identify that potential problem. This prevents replication when it could hurt server performance.
The session hooks are implemented through callback functions in the Directory Server replication functions.
The call backs are defined in an ordered array that follows the replication operation process from initializing the replication agreement to receiving the response from the consumer. 
static void *test_repl_session_api[] = {
   NULL, /* reserved for api broker use, must be zero */
   test_repl_session_plugin_agmt_init_cb,
   test_repl_session_plugin_pre_acquire_cb,
   test_repl_session_plugin_reply_acquire_cb,
   test_repl_session_plugin_post_acquire_cb,
   test_repl_session_plugin_recv_acquire_cb,
   test_repl_session_plugin_destroy_cb
};
Then, the custom replication plug-in registers the callbacks. In this example, it requires a certain version of the server. 
int test_repl_session_plugin_init(Slapi_PBlock *pb)
{
...
   if( slapi_apib_register(REPL_SESSION_v1_0_GUID, test_repl_session_api) ) {
       slapi_log_error( SLAPI_LOG_FATAL, test_repl_session_plugin_name,
                        "<-- test_repl_session_plugin_start -- failed to register repl_session api -- end\n");
       return -1;
   }
...
}

Note

The callbacks themselves are described in the Plug-in Guide. This example is provided to make administrators and programmers aware that the replication process can be controlled by using these session hooks.
These typedef declarations are used to define replication session hooks for Directory Server and its clients, including applications like Red Hat Enterprise IPA.

Table 14.17. Replication Session Hooks Types

typedef Description
repl_session_plugin_agmt_init_cb Used to initialize the replication agreement to begin replication.
repl_session_plugin_pre_acquire_cb Defines the data about the initiating master server to send to the replica.
repl_session_plugin_reply_acquire_cb Defines the information about the replica to send to the master.
repl_session_plugin_post_acquire_cb Posts the response from the replica to the master server.
repl_session_plugin_recv_acquire_cb Receives the data from the replica.
repl_session_plugin_destroy_agmt_cb Destroys a replication agreement when the operation is complete.

14.36.1. repl_session_plugin_agmt_init_cb

Initializes a replication agreement.
Syntax

  

typedef void * (*repl_session_plugin_agmt_init_cb)(const Slapi_DN *repl_subtree);
Parameters

This function takes the following parameters:

Parameter Description
repl_subtree Gives the subtree that is involved in replication.

14.36.2. repl_session_plugin_pre_acquire_cb

Defines the data about the initiating master server to send to the replica.
Syntax

  

typedef int (*repl_session_plugin_pre_acquire_cb)(void *cookie, const Slapi_DN *repl_subtree,
                                          int is_total, char **data_guid, struct berval **data);
Parameters

This function takes the following parameters:

Parameter Description
cookie Private data used by the plug-in. This is the value returned by the replication plug-in init function (if any) and passed to all plug-in functions.
repl_subtree Gives the subtree that is involved in replication.
data_guid Sends an identifier for the expected data.
data_guid Contains the data.

14.36.3. repl_session_plugin_reply_acquire_cb

Defines the information about the replica to send to the master.
Syntax

  

typedef int (*repl_session_plugin_reply_acquire_cb)(const char *repl_subtree, int is_total,
                                                   char **data_guid, struct berval **data);
Parameters

This function takes the following parameters:

Parameter Description
cookie Private data used by the plug-in. This is the value returned by the replication plug-in init function (if any) and passed to all plug-in functions.
repl_subtree Gives the subtree that is involved in replication.
data_guid Contains the identifier for the expected data.
data_guid Contains the data.

14.36.4. repl_session_plugin_post_acquire_cb

Posts the response from the replica to the master server.
Syntax

  

typedef int (*repl_session_plugin_post_acquire_cb)(void *cookie, const Slapi_DN *repl_subtree,
                                          int is_total, const char *data_guid, const struct berval *data);
Parameters

This function takes the following parameters:

Parameter Description
cookie Private data used by the plug-in. This is the value returned by the replication plug-in init function (if any) and passed to all plug-in functions.
repl_subtree Gives the subtree that is involved in replication.
data_guid Contains the identifier for the expected data.
data_guid Contains the data.

14.36.5. repl_session_plugin_recv_acquire_cb

Receives the data from the replica.
Syntax

  

typedef int (*repl_session_plugin_recv_acquire_cb)(const char *repl_subtree, int is_total,
                                          const char *data_guid, const struct berval *data);
Parameters

This function takes the following parameters:

Parameter Description
cookie Private data used by the plug-in. This is the value returned by the replication plug-in init function (if any) and passed to all plug-in functions.
repl_subtree Gives the subtree that is involved in replication.
data_guid Contains the identifier for the expected data.
data_guid Contains the data.

14.36.6. repl_session_plugin_destroy_agmt_cb

Destroys a replication agreement when the operation is complete.
Syntax

  

typedef void (*repl_session_plugin_destroy_agmt_cb)(void *cookie, const Slapi_DN *repl_subtree);
Parameters

This function takes the following parameters:

Parameter Description
cookie Private data used by the plug-in. This is the value returned by the replication plug-in init function (if any) and passed to all plug-in functions.
repl_subtree Gives the subtree that is involved in replication.