Netscape Directory Server Programmer's Guide: Understanding Server Plug-Ins

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

Chapter 1 Understanding Server Plug-Ins

This chapter introduces the concept of a server plug-in and discusses the different types of plug-ins that you can write.

What Are Server Plug-Ins?

How Server Plug-Ins Work

Types of Server Plug-Ins

What Are Server Plug-Ins?

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

You can write your own plug-in functions to extend the functionality of the directory server in the following ways:

You can validate data before the server performs an LDAP operation on the data.

You can perform some action (that you define) after the server successfully completes an LDAP operation. (For example, you can send mail after an operation successfully completes.)

You can define extended operations (which are part of the LDAP v3 protocol).

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

You can set up the server to use your own type of database for storing data.

On startup, the directory server loads your library and calls your functions during the course of processing various LDAP requests.

How Server Plug-Ins Work

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 calls a registered plug-in function:

before perfoming 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 and when filtering search result candidates based on an attribute

When you register your plug-in, you specify the type of function and the type of plug-in, which both indicate when the function is called (see "Types of Server Plug-Ins" on page 23 for a listing).

How the Server Calls Plug-In Functions

At specific events (such as before an LDAP add operation is peformed), the server calls any plug-in functions registered for that event. For example, before performing an LDAP add operation, the server calls any functions registered as pre-operation add functions.

In most cases, when the server calls your function, it passes a parameter block to your function. This parameter block contains data relevant to the operation. In your server plug-in function, you can access and modify data in this 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 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), passing it the parameter block.

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

What Plug-Ins Return to the Server

If you are writing a function that is invoked before an LDAP operation is performed, you can also 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.

How Database Plug-Ins Work

Internally, the Netscape Directory Server consists of two major subsections:

The front-end receives LDAP requests from clients and processes the 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=Airius.com" suffix contains directory entries that end with that suffix.

If you want to integrate the directory server with your own database, you just need to add your own back-end to the directory server, configure the back-end to handle the suffix for your directory data, and register your own functions for reading and writing data in the back-end.

Figure 1.1 illustrates the directory server architecture.

Figure 1.1 Directory server architecture

Types of Server Plug-Ins

You can write the following types of server plug-ins for the directory server:

Pre-operation/data validation. The server calls pre-operation/data validation plug-in functions before performing an LDAP operation. The main purpose of this type of plug-in is to validate data before the data can be used in an operation.

For example, you can write a plug-in that checks each new entry before adding them to the directory.

Post-operation/data notification. The server calls post-operation/data notification plug-in functions after performing an LDAP operation. The main purpose of this type of plug-in is to invoke a function when a particular operation is executed.

For example, you can write a plug-in that sends email to users if their entries are modified.

Database. You can define a database plug-in to integrate your own database as a back-end to the server. Your plug-in translates requests from the directory server front-end into calls to your database client library. If the directory server front-end requests to add an entry to the directory, your plug-in calls functions in your database client library to insert the data into your database.

For example, you can write a plug-in that integrates a relational database with the directory server.

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

Note that these plug-ins only apply to the default back-end database (ldbm). If you have defined your own database plug-in, you can define the way that data is written to and read from the database in your database plug-in functions.

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 extended operation plug-in functions when the client requests the operation by OID.

Syntax. The server calls syntax plug-in functions when getting a list of possible candidates for a search or when adding or deleting values from certain attribute indexes. Syntax plug-in functions also define the comparison operations used in searches (for example, a syntax plug-in function might 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 with an extensible matching search filter.

You can also write matching rule plug-in functions that the server calls when indexing attributes for the default back-end database. (Note that these are called only if you are using the default back-end database, not if you are using your own database plug-in.)

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

Figure 1.3 illustrates how you can replace the standard database.

Figure 1.3 Using a Plug-In to Replace the Standard Database

© Copyright 1998 Netscape Communications Corporation