Complete Contents
Getting Started
Chapter 1 Understanding Server Plug-Ins
Chapter 2 Writing and Compiling Plug-Ins
Chapter 3 Calling the Front-End API Functions
Chapter 4 Quick Start
Chapter 5 Writing Database Plug-Ins
Chapter 6 Writing Pre/Post-Operation Plug-Ins
Chapter 7 Defining Functions for LDAP Operations
Chapter 8 Defining Functions for Database Operations
Chapter 9 Defining Functions for Authentication
Chapter 10 Writing Entry Store/Fetch Plug-Ins
Chapter 11 Writing Extended Operation Plug-Ins
Chapter 12 Writing Matching Rule Plug-Ins
Chapter 13 Data Type and Structure Reference
Chapter 14 Function Reference
Chapter 15 Parameter Reference
Glossary
Previous Next Contents Bookshelf


Chapter 7 Defining Functions for LDAP Operations

This chapter explains how to write pre-operation, database, and post-operation functions for specific LDAP operations.

In general, these functions must comply with the prototype specified in "Working with Parameter Blocks" on page  30 (in other words, the functions should pass a single Slapi_PBlock argument).

You can define plug-in functions to do the following:


Specifying Start and Close Functions
For each pre-operation and post-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 slapd.conf file).


Reading Configuration Files
When the Directory Server starts up, the front-end reads in and parses the slapd.conf configuration file. If the front-end encounters an unknown directive, it calls the database plug-in function for handling configuration (the function specified by the SLAPI_PLUGIN_DB_CONFIG_FN parameter in the parameter block).

The Directory Server passes the unknown directive to that plug-in function. Because the server is set up in this way, you can add your own directives to the slapd.conf configuration file and write a plug-in function to interpret these directives.

The front-end passes the directive to the configuration function in the form of parameters in the parameter block.
Parameter ID
Data Type
Description
SLAPI_CONFIG_FILENAME

char *

Name of the configuration file that is being read (for example, slapd.conf).
SLAPI_CONFIG_LINENO

int

Line number of the current directive in the configuration file.
SLAPI_CONFIG_ARGC

int

Number of arguments in the current directive.
SLAPI_CONFIG_ARGV

char **

Array of the arguments from the current directive.


Processing an LDAP Bind Operation
When the Directory Server receives an LDAP bind request from a client, the front-end determines the DN that the client is attempting to bind as and the authentication method being used. The front-end also gets the credentials used for authentication, and (if SASL is used for authentication), the SASL mechanism used.

Defining Functions for the Bind Operation

In the parameter block, the following parameters specify plug-in functions that are called in the process of executing a bind operation:

You register your plug-in functions by calling slapi_pblock_set() to set these parameters in your initialization function. (For details, see "Registering Your Plug-In Functions" on page  36.)

Your pre-operation and post-operation bind functions should return 0 if successful. If the pre-operation function returns a non-zero value, the database bind function and the post-operation bind function are never called.

For information on defining a database bind function or a function that handles authentication, see Chapter  9, "Defining Functions for Authentication".

Getting and Setting Parameters for the Bind Operation

The front-end makes this information available to pre-operation, database, and post-operation plug-in functions in the form of parameters in a parameter block.
Parameter ID
Data Type
Description
SLAPI_BIND_TARGET

char *

DN of the entry to bind as.
SLAPI_BIND_METHOD

int

Authentication method used (for example, LDAP_AUTH_SIMPLE or LDAP_AUTH_SASL).
SLAPI_BIND_CREDENTIALS

struct berval *

Credentials from the bind request.
SLAPI_BIND_RET_SASLCREDS

struct berval *

Credentials that you want sent back to the client. (Set this before calling slapi_send_ldap_result().)
SLAPI_BIND_SASLMECHANISM

char *

SASL mechanism used (for example, LDAP_SASL_EXTERNAL).

Note that if the SLAPI_BIND_SASLMECHANISM parameter is empty, simple authentication was used and simple credentials were provided.


Processing an LDAP Unbind Operation
When the Directory Server receives an LDAP unbind request from a client, the front-end calls the database unbind function for each back-end. No operation-specific parameters are placed in the parameter block that is passed to the database function.

In the parameter block, the following parameters specify plug-in functions that are called in the process of executing a bind operation:

You set these parameters to the names of your functions by calling slapi_pblock_set().

Your plug-in functions should return 0 if successful. If the pre-operation function returns a non-zero value, the database unbind function and the post-operation unbind function are never called.


Processing an LDAP Search Operation
The server processes an LDAP search operation in two stages:

The rest of this section explains these stages in more detail.

Getting the List of Candidates

In the parameter block, the SLAPI_PLUGIN_DB_SEARCH_FN parameter specifies the database search function.

When the Directory Server receives an LDAP search request, the front-end gets information about the search (such as the scope and base DN). The front-end normalizes the base DN (by calling the slapi_dn_normalize() function) and determines if the base DN identifies a DSA-specific entry (DSE). If so, the front-end handles the search request directly and does not pass it to the database search function.

If the base DN is not a DSE, the front-end finds the back-end that services the suffix specified in the base DN. The front-end then passes the search criteria to the search function for that back-end.

The front-end makes this information available to pre-operation, database, and post-operation plug-in functions in the form of parameters in a parameter block. .
Parameter ID
Data Type
Description
SLAPI_SEARCH_TARGET

char *

DN of the base entry in the search operation (the starting point of the search).
SLAPI_SEARCH_SCOPE

int

The scope of the search. The scope can be one of the following values:
SLAPI_SEARCH_DEREF

int

Method for handling aliases in a search. This method can be one of the following values:
SLAPI_SEARCH_SIZELIMIT

int

Maximum number of entries to return in the search results.
SLAPI_SEARCH_TIMELIMIT

int

Maximum amount of time (in seconds) allowed for the search operation.
SLAPI_SEARCH_FILTER

Slapi_Filter *

Slapi_Filter struct (an opaque data structure) representing the filter to be used in the search.
SLAPI_SEARCH_STRFILTER

char *

String representation of the filter to be used in the search.
SLAPI_SEARCH_ATTRS

char **

Array of attribute types to be returned in the search results.
SLAPI_SEARCH_ATTRSONLY

int

Specifies whether the search results return attribute types only or attribute types and values. (0 means return both attributes and values; 1 means return attribute types only)

Your search function should return 0 if successful. Call the slapi_pblock_set() function to assign the set of search results to the SLAPI_SEARCH_RESULT_SET parameter in the parameter block.

The front-end then uses this function in conjunction with the "next entry" function (see "Iterating through Candidates" on page  104) to iterate through the result set. The front-end sends each result back to the client and continues updates the SLAPI_NENTRIES parameter with the current number of entries sent back to the client.

If a result is actually a referral, the front-end sends the referral back to the client and updates the SLAPI_SEARCH_REFERRALS parameter with the list of referral URLs.

Finally, after sending the last entry to the client, the front-end sends an LDAP result message specifying the number of entries found.

Iterating through Candidates

In the parameter block, the SLAPI_PLUGIN_DB_NEXT_SEARCH_ENTRY_FN parameter specifies the database function used to iterate through the list of candidates and determine if each candidate matches the search criteria.

In addition to the parameters specified in "Processing an LDAP Search Operation" on page  101, the "next entry" function has access to the following parameters (which are set by the front-end and the back-end during the course of executing a search operation): .
Parameter ID
Data Type
Description
SLAPI_SEARCH_RESULT_SET

void *

Set of search results.
SLAPI_SEARCH_RESULT_ENTRY

void *

Entry returned from iterating through the results set. This "next entry" function actually sets this parameter.
SLAPI_NENTRIES

int

Number of search results found
SLAPI_SEARCH_REFERRALS

struct berval **

Array of the URLs to other LDAP servers that the current server is referring the client to

The "next entry" function should get the next result specified in the set of results in the parameter SLAPI_SEARCH_RESULT_SET. The function should set this next entry as the value of the SLAPI_SEARCH_RESULT_ENTRY parameter in the parameter block, and the "next entry" function should return 0 if successful.

The "next entry" function should set the SLAPI_SEARCH_RESULT_ENTRY parameter to NULL and return -1 if one of the following situations occurs:

If no more entries exist in the set of results, the "next entry" function should set the SLAPI_SEARCH_RESULT_ENTRY parameter to NULL and return 0.


Processing an LDAP Compare Operation
In the parameter block, the SLAPI_PLUGIN_DB_COMPARE_FN parameter specifies the database compare function.

When the Directory Server receives an LDAP compare request from a client, the front-end gets the DN of the entry being compared and the attribute and value being used in the comparison.

The front-end makes this information available to pre-operation, database, and post-operation plug-in functions in the form of parameters in a parameter block.
Parameter ID
Data Type
Description
SLAPI_COMPARE_TARGET

char *

DN of the entry to be compared.
SLAPI_COMPARE_TYPE

char *

Attribute type to use in the comparison.
SLAPI_COMPARE_VALUE

struct berval *

Attribute value to use in the comparison

The compare function should call slapi_send_ldap_result() to send LDAP_COMPARE_TRUE if the specified value is equal to the value of the entry's attribute or LDAP_COMPARE_FALSE if the values are not equal.

If successful, the compare function should return 0. If an error occurs (for example, if the specified attribute doesn't exist), the compare function should call slapi_send_ldap_result() to send an LDAP error code and should return 1.


Processing an LDAP Add Operation
In the parameter block, the SLAPI_PLUGIN_DB_ADD_FN parameter specifies the database add function.

When the Directory Server receives an LDAP add request from a client, the front-end normalizes the DN of the new entry. The front-end makes this information available to pre-operation, database, and post-operation plug-in functions in the form of parameters in a parameter block.
Parameter ID
Data Type
Description
SLAPI_ADD_TARGET

char *

DN of the entry to be added.
SLAPI_ADD_ENTRY

Slapi_Entry *

The entry to be added (specified as the opaque Slapi_Entry datatype).

The add function should check the following:

If the add function is successful, the function should call slapi_send_ldap_result() to send an LDAP_SUCCESS code back to the client and should return 0.


Processing an LDAP Modify Operation
In the parameter block, the SLAPI_PLUGIN_DB_MODIFY_FN parameter specifies the database modify function.

When the Directory Server receives an LDAP modify request from a client, the front-end gets the DN of the entry to be modified and the modifications to be made. The front-end makes this information available to pre-operation, database, and post-operation plug-in functions in the form of parameters in a parameter block.
Parameter ID
Data Type
Description
SLAPI_MODIFY_TARGET

char *

DN of the entry to be modified.
SLAPI_MODIFY_MODS

LDAPMod **

A NULL-terminated array of LDAPMod structures, which represent the modifications to be performed on the entry.

The modify function should check the following:

If the modify function is successful, the function should call slapi_send_ldap_result() to send an LDAP_SUCCESS code back to the client and should return 0.


Processing an LDAP Modify RDN Operation
In the parameter block, the SLAPI_PLUGIN_DB_MODRDN_FN parameter specifies the database modify RDN function.

When the Directory Server receives an LDAP modify RDN request from a client, the front-end gets the original DN of the entry, the new RDN, and (if the entry is moving to a different location in the directory tree) the DN of the new parent of the entry.

The front-end makes this information available to pre-operation, database, and post-operation plug-in functions in the form of parameters in a parameter block.
Parameter ID
Data Type
Description
SLAPI_MODRDN_TARGET

char *

DN of the entry that you want to rename.
SLAPI_MODRDN_NEWRDN

char *

New RDN to assign to the entry.
SLAPI_MODRDN_DELOLDRDN

int

Specifies whether or not you want to deleted the old RDN. (0 means don't delete the old RDN; 1 means delete the old RDN)
SLAPI_MODRDN_NEWSUPERIOR

char *

DN of the new parent of the entry, if the entry is being moved to a new location in the directory tree.

The modify RDN function should check the following:

If the modify RDN function is successful, the function should call slapi_send_ldap_result() to send an LDAP_SUCCESS code back to the client and should return 0.


Processing an LDAP Delete Operation
In the parameter block, the SLAPI_PLUGIN_DB_DELETE_FN parameter specifies the database delete function.

When the Directory Server receives an LDAP delete request from a client, the front-end gets the DN of the entry to be removed from the directory. The front-end makes this information available to pre-operation, database, and post-operation plug-in functions in the form of parameters in a parameter block.
Parameter ID
Data Type
Description
SLAPI_DELETE_TARGET

char *

DN of the entry to delete.

If the delete function is successful, it should return 0.


Processing an LDAP Abandon Operation
In the parameter block, the SLAPI_PLUGIN_DB_ABANDON_FN parameter specifies the database abandon function.

When the Directory Server receives an LDAP abandon request from a client, the front-end gets the message ID of the operation that should be abandoned. The front-end makes this information available to pre-operation, database, and post-operation plug-in functions in the form of parameters in a parameter block.
Parameter ID
Data Type
Description
SLAPI_ABANDON_MSGID

unsigned long

Message ID of the operation to abandon.

 

© Copyright 1998 Netscape Communications Corporation