Chapter 10

Writing Extended Operation Plug-ins

---

This chapter explains how to write plug-in functions to handle extended operations. Extended operations are are defined in the LDAP v3 protocol.

The chapter contains the following sections:

• How Extended Operation Plug-ins Work (page 125)
• Writing Extended Operation Functions (page 126)
• Registering Extended Operation Functions (page 127)
• Specifying Start and Close Functions (page 129)

How Extended Operation Plug-ins Work

You can define your own operation that you want the Red Hat Directory Server (Directory Server) to perform. If you create a custom extended operation, you assign an object identifier (OID) to identify that operation. LDAP clients request the operation by sending an extended operation request. Within the request, the client specifies:

• The OID of the extended operation.
• Data specific to the extended operation.

When the Directory Server receives the request, the server calls the plug-in registered with the specified OID. The plug-in function has access to both the OID and the data in the client's request. The plug-in function can send back to the client a response containing an OID plus any additional data that might be needed.

In order to use extended operations, you need to configure both the Directory Server and the client so they understand the specific extended operation that you want performed.

Writing Extended Operation Functions

Like other plug-in functions, extended operation functions pass a single parameter block (Slapi_PBlock) and return an integer value, as shown in the following example declaration:

int my_ext_func( Slapi_PBlock *pb );
 

Extended operation functions should return a value of 0 if they are successful and a non-zero value if they are unsuccessful.

When the Directory Server receives an extended operation request, the front-end calls the extended operation function with the OID value specified in the request. The front-end makes the following information available to the extended function in the form of parameters in a parameter block.

Table 10-1 Extended Function Parameter Block Arguments  

Parameter ID	Data Type	Description
SLAPI_EXT_OP_REQ_OID	char *	Object ID (OID) of the extended operation specified in the request.
SLAPI_EXT_OP_REQ_VALUE	struct berval*	Value specified in the request.
SLAPI_EXT_OP_RET_OID	char *	Object ID (OID) that you want sent back to the client.
SLAPI_EXT_OP_RET_VALUE	struct berval*	Value that you want sent back to the client.

Typically, your function should perform an operation on the value specified in the SLAPI_EXT_OP_REQ_VALUE parameter. After the extended operation completes, your function should return a single value, according to the following:

• If your function has sent a result code back to the client, you should return the value SLAPI_PLUGIN_EXTENDED_SENT_RESULT. This indicates that the front-end does not need to send a result code.
• If your function has not sent a result code back to the client (for example, if the result is LDAP_SUCCESS), your function should return an LDAP result code. The front-end will send this result code back to the client.
• If your function cannot handle the extended operation with the specified OID, your function should return the value SLAPI_PLUGIN_EXTENDED_NOT_HANDLED. The front-end will send an LDAP_PROTOCOL_ERROR result code (with an "unsupported extended operation error message") back to the client.

Note	For a sample plug-in function (uncompiled C code) that implements an extended operation, check this file: server_root /plugins/slapd/slapi/examples/testextendedop.c

Registering Extended Operation Functions

As is the case with other server plug-in functions (see "Passing Data with Parameter Blocks," on page 38), extended operation functions are specified in a parameter block that you can set on server startup.

In your initialization function, you can call the slapi_pblock_set() function to set the SLAPI_PLUGIN_EXT_OP_FN parameter to your function and the SLAPI_PLUGIN_EXT_OP_OIDLIST parameter to the list of OIDs of the extended operations supported by your function.

You can write your initialization function so that the OID is passed in from the directive. (See "Passing Extra Arguments to Plug-ins," on page 52, for details.) For example, the following initialization function sets the SLAPI_PLUGIN_EXT_OP_OIDLIST parameter to the additional parameters specified.

Code Example 10-1 Sample Initialization Function for Passing an OID  

int extended_init( Slapi_PBlock *pb )
{
int i;
char **argv;
char **oids;
/* Get the additional arguments specified in the directive */
if ( slapi_pblock_get( pb, SLAPI_PLUGIN_ARGV, &argv ) != 0 ) {
slapi_log_error( SLAPI_LOG_PLUGIN, "extended_init",
"Server could not get argv.\n" );
return( -1 );
}
if ( argv == NULL ) {
slapi_log_error( SLAPI_LOG_PLUGIN, "extended_init",
"Required argument <oiD> is missing\n" );
return( -1 );
}
/* Get the number of additional arguments and copy them. */
for ( i = 0; argv[i] != NULL; i++ )
;
oids = (char **) slapi_ch_malloc( (i+1) * sizeof(char *) );
for ( i = 0; argv[i] != NULL; i++ ) {
oids[i] = slapi_ch_strdup( argv[i] );
}
oids[i] = NULL;
/* Specify the version of the plug-in */
if ( slapi_pblock_set( pb, SLAPI_PLUGIN_VERSION,
SLAPI_PLUGIN_VERSION_01 ) != 0 ||
/* Specify the OID of the extended operation */
slapi_pblock_set( pb, SLAPI_PLUGIN_EXT_OP_OIDLISTs,
(void*) oids ) != 0 ||
/* Specify the function that the server should call */
slapi_pblock_set( pb, SLAPI_PLUGIN_EXT_OP_FN,
(void*) extended_op ) != 0 ) {
slapi_log_error( SLAPI_LOG_PLUGIN, "extended_init",
"An error occurred.\n" );
return( -1 );
}
slapi_log_error( SLAPI_LOG_PLUGIN, "extended_init",
"Plug-in sucessfully registered.\n" );
return(0);
}

Depending on the Directory Server version, add a directive in the appropriate form to specify the name and location of your plug-in function and to specify the object identification (OID) of the operation.

In current releases of Directory Server, shut down the server, add the plug-in parameters to the dse.ldif file, and restart the server (see Chapter 3, "Configuring Plug-ins"). For example, your plug-in entry might look like this:

dn: cn=Test ExtendedOp,cn=plugins,cn=config

objectClass: top

objectClass: nsSlapdPlugin

objectClass: extensibleObject

cn: Test ExtendedOp

nsslapd-pluginPath: /opt/redhat-ds/servers/plugins/slapd/slapi/

	examples/libtest-plugin.so

nsslapd-pluginInitfunc: testexop_init

nsslapd-pluginType: extendedop

nsslapd-pluginEnabled: on

nsslapd-plugin-depends-on-type: database

nsslapd-pluginId: test-extendedop

nsslapd-pluginarg0: 1.2.3.4
 

For an example plug-in function that implements an extended operation, take a look at this source file:

server_root /plugins/slapd/slapi/examples/testextendedop.c
 

Specifying Start and Close Functions

For each extended operation plug-in, you can specify the name of a function to be called after the server starts and before the server is shut down.

Use the following parameters to specify these functions:

SLAPI_PLUGIN_START_FN	Specifies the function called after the Directory Server starts up.
SLAPI_PLUGIN_CLOSE_FN	Specifies the function called before the Directory Server shuts down.

If you register multiple plug-ins with different start and close functions, the functions are called in the order that the plug-ins are registered (in other words, in the order that the plugin directives appear in the server configuration file).