Writing Directory Server Plug-Ins

This section focuses on the basics of coding a Directory Server plug-in. This section covers the key tasks. These tasks include specifying the header file, writing an initialization function, setting parameter block values, and registering plug-in functions.

Include the slapi-plugin.h Header File

The plug-in API is defined in install-path/include/slapi-plugin.h. Observe that the header file includes ldap.h, the entry point for the standard and extended LDAP C APIs, and ldap_msg.h, the list of error message identifiers used by Directory Server.

In general, interfaces that Directory Server exposes are specified in install-path/include/. For details about specific features of the API, refer to Part II, Directory Server Plug-In API Reference.

To use the API, include slapi-plugin.h in the declaration section of your plug-in source:

#include "slapi-plugin.h"

As a rule, use appropriate macros in your Makefile or project file to tell the linker to look for header files in install-path/include/.

Write Your Plug-In Functions

Directory Server calls plug-in functions in the context of a Directory Server operation, for example when a bind, add, search, modify, or delete is performed. Do not export these functions. The functions become available in the appropriate scope when registered with Directory Server at startup. This guide covers how to write such functions.

A plug-in function prototype looks like the prototype of any other locally used function. Many plug-in functions are passed a parameter block.

int prebind_auth(Slapi_PBlock * pb); /* External authentication. */

You can also use additional helper functions that are not registered with Directory Server. This guide does not cover additional helper functions, but some of the sample plug-ins delivered with the product include such functions.

Use Appropriate Return Codes

In general, return 0 from your plug-in functions when they complete successfully. For some functions that search for matches, 0 means a successful match, and -1 means that no match is found. For preoperation functions, 0 means that Directory Server should continue processing the operation. When you want the server to stop processing the operation after your preoperation function completes, return a positive value such as 1.

When plug-in functions do not complete successfully, send a result to the client if appropriate, log an error message, and return a non-zero value, such as the LDAP result code from install-path/include/ldap-standard.h, for example.

Write an Initialization Function

All plug-ins must include an initialization function. The initialization function registers the plug-in version compatibility, the plug-in description, the plug-in functions, and any other data required by the plug-in. The initialization function takes a pointer to a Slapi_PBlock structure as a parameter. Refer to Example 3–1.

The initialization function returns 0 if everything registers successfully. The initialization function returns -1 if registration fails for any configuration information or function. A return code of -1 from a plug-in initialization function prevents the server from starting.

Directory Server can call the initialization function more than once during startup.

Set Configuration Information Through the Parameter Block

Directory Server passes a parameter block pointer to the plug-in initialization function. This parameter block holds configuration information. The parameter block can hold other data from Directory Server. The parameter block is the structure into which you add configuration information and pointers to plug-in functions using calls to slapi_pblock_set().

To read parameter values, use slapi_pblock_get(). To write parameter values, use slapi_pblock_set(). Using other functions can cause the server to crash.

Specifying Compatibility

You specify compatibility with the plug-in API version as defined in slapi-plugin.h, which is described in Part II, Directory Server Plug-In API Reference. If you are creating a new plug-in, for example, use SLAPI_PLUGIN_CURRENT_VERSION or SLAPI_PLUGIN_VERSION_03. For example, to specify that a plug-in supports the current version, version 3, of the plug-in API, use the following:

slapi_pblock_set(pb,SLAPI_PLUGIN_VERSION, SLAPI_PLUGIN_VERSION_03);

Here, pb is the parameter block pointer passed to the initialization function. SLAPI_PLUGIN_VERSION signifies that you are setting plug-in API version compatibility in the parameter block.

Specifying the Plug-In Description

Specify the plug-in description in a Slapi_PluginDesc structure, as specified in slapi-plugin.h and described in Part II, Directory Server Plug-In API Reference. Call slapi_pblock_set() to register the description:

slapi_pblock_set(pb, SLAPI_PLUGIN_DESCRIPTION,(void *) &desc);

Here, desc is a Slapi_PluginDesc structure that contains the plug-in description. See Example 3–1.

Set Pointers to Functions Through the Parameter Block

Register plug-in functions according to what operation Directory Server performs. Also register plug-in functions according to when the operation is performed. Directory Server typically calls plug-in functions before, during, or after a standard operation.

Macros that specify when Directory Server should call plug-ins have the form SLAPI_PLUGIN_*_FN. As the sample plug-ins demonstrate, the macro used to register a plug-in function depends entirely on what the function is supposed to do. For example, to register a plug-in function foo() to be called at Directory Server startup, do the following:

slapi_pblock_set(pb, SLAPI_PLUGIN_START_FN, (void *) foo);

Here, pb is the parameter block pointer passed to the initialization function. SLAPI_PLUGIN_START_FN signifies that Directory Server calls foo() at startup. Note that foo() returns 0 on success.

Locate Examples

Sample plug-ins are located in install-path/examples/.