Chapter 11 Writing Extended Operation Plug-Ins

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

LDAP clients can request the operation by sending an extended operation request. Within the request, the client specifies:

• the OID of the extended operation that should be performed
• data specific to the extended operation

• an OID
• any additional data

int my_ext_func( Slapi_PBlock *pb );

These functions should return 0 if successful and a non-zero value if unsuccessful.

When the Directory Server receives an extended operation request, the front-end calls the extended operation function with the same OID as specified in the request.

The front-end makes the following information available in the form of parameters in a parameter block.

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 some operation on the value specified in the SLAPI_EXT_OP_REQ_VALUE parameter.

Your function should return one of the following values:

• 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.

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 the Plug-Ins" on page  45 for details.) For example, the following initialization function sets the SLAPI_PLUGIN_EXT_OP_OIDLIST parameter to the additional parameters specified i

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);

}

In the slapd.conf configuration file. Add a directive in the following form to specify the name and location of your plug-in function and to specify the object identification (OID) of the operation:

plugin extendedop <library_name> <function_name> <OID>

<library_name> is the name and path to your shared library or dynamic link library, <function_name> is the name of your plug-in function, and <OID> is the object identifier of the extended operation.

For example, the following directive registers the function named my_ext_op() as the extended operation plug-in function for the operation with the OID 1.2.3.4.

plugin extendedop /usr/nslib/myext.so my_ext_op 1.2.3.4

Note. Each extended operation plug-in is associated with a back-end. Make sure that the plugin directive that registers the plug-in is within the database section for that back-end in the slapd.conf file. (The plugin directive should be after the database directive and before the next database directive, if any.)

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 slapd.conf file).