Netscape Directory Server Plug-In Programmer's Guide: Chapter 1 An Overview of Directory Server Plug-Ins

Plug-In Programmer's Guide
Netscape Directory Server

Chapter 1 An Overview of Directory Server Plug-Ins

This chapter introduces you to Netscape Directory Server (Directory Server) plug-ins and discusses the different types of plug-ins that you can write. The chapter covers the following topics:

What Are Directory Server Plug-Ins?

How Directory Server Plug-Ins Work

Types of Directory Server Plug-Ins

If you have already written a plug-in for Directory Server, refer to the section Using Directory Server Plug-In APIs for information on migrating your plug-in to the latest version of the Directory Server.

What Are Directory Server Plug-Ins?

If you want to extend the capabilities of the Directory Server, you can write your own Directory Server plug-in. A server plug-in is a shared object or library (or on the Windows NT platform, a dynamic link library) that contains custom functions that you write.

By writing your own plug-in functions, you can extend the functionality of the Directory Server. For example, here are some of the things you can do with Directory Server plug-ins:

You can design an action that the Directory Server performs before the server processes an LDAP action. For example, you can write a custom function to validate data before the server performs an LDAP operation on the data.

You can design an action that the Directory Server performs after the server successfully completes an LDAP operation. For example, you can send mail to a client after an LDAP operation is successfully completed.

You can define extended operations, as defined in the the LDAP v3 protocol.

You can provide alternate matching rules when comparing certain attribute values.

How Directory Server Plug-Ins Work

When properly configured, the Directory Server will load your plug-in on startup. Once loaded, the Directory Server will resolve calls made to your plug-in functions as it processes the LDAP requests contained in your applications.

Internally, the Directory Server has hooks that allow you to register your own functions to be called when specific events occur. For example, the Directory Server has hooks to call a registered plug-in in the following situations:

Before preforming an LDAP operation (for example, before an entry is added to the directory)

When adding, modifying, removing, renaming, or searching for entries in the database

After performing an LDAP operation (for example, after an entry is added to the directory)

Before writing an entry to the database

After reading an entry from the database

When processing an extended operation

When indexing an attribute

When filtering search result candidates based on an attribute

When you register your plug-in functions, you specify the function type and the plug-in type. Together, these specifications indicate when the function is called. For more information on this topic, refer to the section Types of Directory Server Plug-Ins.

Calling Directory Server Plug-In Functions

At specific LDAP events, the Directory Server calls all plug-in functions that are registered for that event. For example, before performing an LDAP add operation (an add event), the server calls all plug-in functions registered as pre-operation add functions. When the add operation is completed, the server will call all registered post-operation add functions.

In most plug-in function calls, the server passes a parameter block to the function. The parameter block contains data relevant to the operation. In most Directory Server plug-in functions you write, you access and modify the data in the parameter block.

For example, when the Directory Server receives an LDAP add request, the server does the following:

Parses the request and retrieves the new DN and the entry to be added.

Places pointers to the DN and the entry in the parameter block.

Calls any registered pre-operation add functions, passing the parameter block to these functions.

Calls the registered database add function (which is responsible for adding the entry to the directory database), and passes to it the parameter block.

Calls any registered post-operation add functions, passing the parameter block to these functions.

If you are writing a function that is invoked before an LDAP operation is performed, you can prevent the operation from being performed. For example, you can write a function that validates data before a new entry is added to the directory. If the data is not valid, you can prevent the LDAP add operation from occurring and return an error message to the LDAP client.

In some situations, you can also set the data that is used by the server to perform an operation. For example, in a pre-operation add function, you can change an entry before it is added to the directory.

The Directory Server Architecture

Internally, the Directory Server consists of two major subsections: The front-end and the back-end.

The front-end receives LDAP requests from clients and processes those requests. When processing requests, the front-end calls functions in the back-end to read and write data. The front-end then sends the results back to the client.

The back-end reads and writes data to the database containing the directory entries. The back-end abstracts the database from the front-end. The data stored in a back-end is identified by the suffixes that the back-end supports. For example, a back-end that supports the "o=example.com" suffix contains directory entries that end with that suffix.

Figure 1-1 illustrates the Directory Server architecture.

Figure 1-1 Directory Server Architecture

Types of Directory Server Plug-Ins

You can write the following types of plug-ins for the Directory Server:

Pre-operation/data validation. The server calls a pre-operation/data validation plug-in function before performing an LDAP operation.

The main purpose of this type of plug-in is to validate data before the data is added to the directory or before it is used in an operation.

Post-operation/data notification. The server calls a post-operation/data notification plug-in function after performing an LDAP operation.

The main purpose of this type of plug-in is to invoke a function after a particular operation is executed. For example, you can write a plug-in that sends email to users if their entries are modified.

Entry storage and entry fetch. The server calls an entry storage plug-in function right before writing data to the database back-end. The server calls entry fetch plug-in functions after retrieving an entry from the database back-end.

For example, you can create an entry storage plug-in that encrypts an entry before it is saved to the database and an entry fetch plug-in that decrypts an entry after it is read from the database.

Extended operation. The server calls an extended operation plug-in function when the client requests an operation by OID. Extended operations are defined in LDAP v3 and are described in more detail in Chapter 10 "Writing Extended Operation Plug-Ins."

Syntax. The server calls a syntax plug-in function when getting a list of possible candidates for a search. The server also calls these functions when adding or deleting values from certain attribute indexes.

Syntax plug-in functions can define the comparison operations used in searches. For example, you could use a syntax plug-in function to define how the "equals" comparison works for case-insensitive strings.

Matching rule. The server calls matching rule plug-in functions when the client sends a search request with an extensible matching search filter. You can also write matching rule plug-in functions that the server calls when indexing attributes for the back-end database.

Figure 1-2 illustrates how some of these different plug-in types fit into the Directory Server architecture.

Figure 1-2 Architecture of the Directory Server and Server Plug-Ins

Last Updated October 30, 2003