2.2. Writing Plug-in Initialization Functions

Before the Directory Server can call the plug-in function, the function must be properly initialized. To do this, you must write an initialization function for the server plug-in. The initialization function should:
  1. Specify the plug-in compatibility version.
  2. Register each of the plug-in functions.
  3. Return a value to the Directory Server.

Note

The initialization function should not do anything more than these three steps. For example, the init function should not attempt to perform an internal search or other internal operation, because the all of the subsystems are not up and running during the init phase.
To perform additional configuration or initialization, use a start function. This function is specified by using slapi_pblock_set() with the SLAPI_PLUGIN_START_FN parameter in the initialization function.
Your initialization function should have a prototype similar to the following: 
int my_init_function( Slapi_PBlock pb );
In the initialization function, the Directory Server passes a single argument of the type Slapi_PBlock*.

2.2.1. Specifying Directory Server Compatibility

Specify the compatibility version of the plug-in so that the Directory Server can determine whether it supports the plug-in.
To specify the plug-in compatibility version, call the slapi_pblock_set() function, and set the SLAPI_PLUGIN_VERSION_03 parameter to the version number associated with the plug-in. For example: 
slapi_pblock_set(pb, SLAPI_PLUGIN_VERSION, SLAPI_PLUGIN_VERSION_03);
Plug-in version 3 (SLAPI_PLUGIN_VERSION_03) is compatible with versions 6.x and later of the Directory Server. Two other plug-in versions are available for backward compatability with older version of Directory Server; otherwise, these versions are deprecated:
  • SLAPI_PLUGIN_VERSION_01 is compatible with versions 3.x and 4.x of the Directory Server.
  • SLAPI_PLUGIN_VERSION_02 is compatible with version 4.x of the Directory Server.

2.2.2. Specifying Information about the Plug-in

You specify information about the plug-in, such as a description, with the Slapi_PluginDesc structure. For details on this data structure, see Section 14.30, “Slapi_PluginDesc”.
It is recommended that you include a plug-in description because the Red Hat Console displays this information as part of the server configuration information.
To specify plug-in information, call the slapi_pblock_set() function, and set the SLAPI_PLUGIN_DESCRIPTION parameter to this structure. For example:
Specifying Plug-in Information 
/* Specify information about the plug-in */
Slapi_PluginDesc mypdesc = { "test-plugin" , "example.com" "0.5" , "sample pre-operation plugin" };
...
/* Set this information in the parameter block */
slapi_pblock_set( pb, SLAPI_PLUGIN_DESCRIPTION, (void*)&mypdesc );
This example code specifies the following plug-in information:
  • The unique identifier for the server plug-in is test-plugin.
  • The vendor of the server plug-in is example.com.
  • The version of the server plug-in is 0.5.
    This version is intended to be used for tracking purposes only; it is not the same as the server compatibility version number specified by the SLAPI_PLUGIN_VERSION parameter (see Section 2.2.1, “Specifying Directory Server Compatibility” for details on this parameter). As you make changes to the plug-in code, you can track the version distributed using the number contained in the Slapi_PluginDesc structure.
  • The description of the server plug-in is contained in the data structure value sample pre-operation plug-in.

2.2.3. Registering Your Plug-in Functions

Whether the plug-in is registered through the initialization function depends on the type of function being registered.
For some plug-in types, you do not need to register the plug-in function from within the initialization function. For example, you register entry store and entry fetch plug-ins by specifying the function names in the plugin directive in the dse.ldif file.
For other plug-in types, such as pre-operation plug-ins and post-operation plug-ins, the Directory Server gets the pointer to the function from a parameter in the initialization function parameter block. In these cases, you use the slapi_pblock_set() function to specify the name of the plug-in function.
The full list parameters that you can use to register the plug-in functions are listed in Chapter 52, Parameters for Registering Plug-in Functions.
For example, if you want to register searchdn_preop_search() as a pre-operation search function, include the following code in the initialization function: 
slapi_pblock_set( pb, SLAPI_PLUGIN_PRE_SEARCH_FN, (void *) searchdn_preop_search )
SLAPI_PLUGIN_PRE_SEARCH_FN is the parameter that specifies the pre-operation plug-in function for the LDAP search operation.

Note

If the plug-in functions are not registered, the Directory Server will not call them. All custom plug-in functions should be registered.
More than one plug-in function can be registered in the initialization function; it is not necessary to write an initialization function for each plug-in function that needs to be registered. However, define a different initialization function for each type of plug-in being registered. An object type plug-in can register any type of plug-in in its init function, so when writing a plug-in that must perform several different types of operations, an object plug-in is probably the best approach.

2.2.4. Returning a Value to the Directory Server

If the initialization function is successful, it should return 0. If an error occurs, it should return -1, in which case the Directory Server will exit.

2.2.5. Example of an Initialization Function

The following is an example of an initialization function that registers the pre-operation plug-in function searchdn_preop_search(). After the initialization function returns, the server will call searchdn_preop_search() before each LDAP search operation is executed. 
#include "slapi-plugin.h"
...
#ifdef _WIN32
__declspec(dllexport)
#endif

int
searchdn_preop_init( Slapi_PBlock *pb )
{
	/*Specify the version of the plug-in (set this to "03" )*/
	if ( slapi_pblock_set( pb, SLAPI_PLUGIN_VERSION, SLAPI_PLUGIN_VERSION_03 ) != 0 ||
	
	/* Set up theserver to call searchdn_preop_search()
	before each LDAP search operation. */
	
	slapi_pblock_set( pb, SLAPI_PLUGIN_PRE_SEARCH_FN, (void *)searchdn_preop_search ) !=0 ) {
	
		/* If a problem occurs, log an error message, return -1.*/
		slapi_log_error(SLAPI_LOG_PLUGIN, "searchdn_preop_init" ,
		"Error registeringfunction.\n" );
		return( -1 );
	}
	
	/*If the plug-in was successfully registered, log a
	message and return 0. */
	slapi_log_error( SLAPI_LOG_PLUGIN, "searchdn_preop_init" ,
	"Plug-in successfully registered.\n" );
	return( 0 );
}