HP-UX Directory Server 8.1 plug-in reference

2.1.3 Working with parameter blocks
In the functions that you write, you set values in the parameter block that pertain to the operation
you are performing. You can also get data from the parameter block that you can use within the
plug-in functions. This process is described in “Getting data from the parameter block”.
You can also set values in the parameter block during the processing of the plug-in functions.
The Directory Server can then use the new data values to complete an operation which it might
be processing. This process is described in “Setting data in the parameter block”.
Some of the data that you can retrieve from the parameter block includes entries, attributes,
search filters, and distinguished names (DNs). After you have retrieved a piece of data, you can
manipulate it using the front end API functions. For example, you can use front end API functions
to verify that an entry complies with the schema or you can split up a search filter into its
individual components. This process is described in “Calling front end functions”.
2.1.3.1 Getting data from the parameter block
When the Directory Server calls the plug-in function, it passes any relevant data to the function
in a parameter block defined as a data type found in Slapi_PBlock. To access the data in a
parameter block, call the slapi_pblock_get() function found in “slapi_pblock_get()”.
NOTE:
slapi_pblock_get()often returns a pointer to the actual data. When you call custom functions
to modify the value retrieved by slapi_pblock_get(), you are modifying the actual data in
the parameter block, not a copy of the data.
In the following example, the searchdn_preop_search() function gets the DN of the base
DN for the LDAP search operation. It then normalizes the DN, converts all characters to lowercase,
and writes the converted DN to the error log. The actual DN (not a copy of it) is normalized and
converted to lowercase.
#include "slapi-plugin.h"
...
int searchdn_preop_search( Slapi_PBlock *pb )
{
char *dn;
/* Indicate the point when the plug-in starts executing */
slapi_log_error( SLAPI_LOG_PLUGIN, "searchdn_preop_search" ,"*** PREOPERATION SEARCH PLUGIN ***\n" );
/* Get the base DN of the search from the parameter block. */
slapi_pblock_get( pb, SLAPI_SEARCH_TARGET, &dn);
/* Normalize the DN (the actual DN, not a copy of it) and convert it to
* lowercase */
slapi_dn_normalize_case( dn );
/* Log the normalized DN */
slapi_log_error( SLAPI_LOG_PLUGIN, "searchdn_preop_search" ,"Normalized
DN: %s\n" , dn );
return( 0 );
}
In this code example, SLAPI_SEARCH_TARGET identifies the parameter in the parameter block
that contains the base DN of the search. For a complete listing of the parameter block IDs, see
Part V “Parameter block reference”.
2.1.3.2 Setting data in the parameter block
To modify the value of a parameter in the parameter block, call the “slapi_pblock_set()” function.
For example, you can call slapi_pblock_set() to change the value of the SLAPI_PRIVATE
parameter, which stores private data for the plug-in.
In the following example, the ldif_back_init() function sets the value of the SLAPI_PRIVATE
parameter to the context of the database.
#include "slapi-plugin.h";
...
32 Writing and compiling plug-ins