JavaScript is required to for searching.
Skip Navigation Links
Exit Print View
Oracle Directory Server Enterprise Edition Developer's Guide 11 g Release 1 (
search filter icon
search icon

Document Information


Part I Directory Server Plug-In API Guide

1.  Before You Start Writing Plug-Ins

When to Implement a Server Plug-In

Maintaining Plug-Ins

How Plug-Ins Interact With the Server

Example Uses

Where to Go From Here

Prepare Your Development Environment

Learn About Plug-In Development

Upgrade Existing Plug-Ins

Try a Sample Plug-In

Find Details

2.  Changes to the Plug-In API Since Directory Server 5.2

3.  Getting Started With Directory Server Plug-Ins

4.  Working With Entries Using Plug-Ins

5.  Extending Client Request Handling Using Plug-Ins

6.  Handling Authentication Using Plug-Ins

7.  Performing Internal Operations With Plug-Ins

8.  Writing Entry Store and Entry Fetch Plug-Ins

9.  Writing Extended Operation Plug-Ins

10.  Writing Matching Rule Plug-Ins

11.  Writing Password Storage Scheme Plug-Ins

12.  Writing Password Quality Check Plug-Ins

13.  Writing Computed Attribute Plug-Ins

Part II Directory Server Plug-In API Reference

14.  Data Type and Structure Reference

15.  Function Reference, Part I

16.  Function Reference, Part II

17.  Parameter Block Reference

A.  NameFinder Application

Prerequisite Software

Deploying NameFinder

Configuring NameFinder to Access Your Directory

Customizing NameFinder


How Plug-Ins Interact With the Server

All client requests to Directory Server instances undergo particular processing sequences. The exact sequence depends on the operation that the client has requested. Yet overall, the sequences are similar. The way plug-ins handle requests is independent of how the client encodes the request. In other words, client request data appears essentially the same to plug-ins regardless of the client access protocol used to communicate with Directory Server.

In general, client request processing proceeds as follows. First, the Directory Server front end decodes the request. The core server handles the decoded request, calling the necessary back end functions to find or store entries, for example. The primary function of the Directory Server back end is to retrieve and store entries. Unless abandoned, however, a client request results in a response originating in the back end. The front end formats the response and sends it to the client.

The following figure illustrates how client request data moves through Directory Server.

Figure 1-1 Client Request Processing

image:Diagram shows how Directory Server receives, processes, and responds to a client application request.

As a rule, plug-ins register functions to be called by Directory Server at specific steps of processing the client request. A plug-in has a specific type, such as preoperation or postoperation. A preoperation plug-in registers functions that handle incoming requests before the requests are processed in the server. For example, a preoperation plug-in can register a pre-bind function that is called before the core server begins processing the client bind. The pre-bind function might redefine how the client authenticates to Directory Server, enabling authentication against an external database. A postoperation plug-in registers functions that are called after a request is processed. For example, a postoperation plug-in might register a post-modification function that is called to log the information about the modification request. Example Uses provides examples for other plug-in types.

The two internal operation plug-in types form an exception to the rule that functions are called to perform client request processing. Internal operation plug-ins implement functions that are triggered for internal Directory Server operations. Internal operations are initiated not by client requests, but by Directory Server or by another plug-in called by Directory Server. Exercise caution when manipulating internal operation data.

The following table summarizes when Directory Server calls documented plug-in function types.

Table 1-1 Server Plug-In Types

Plug-In Type
When Called
Entry store-fetch
Immediately before writing a directory entry to or immediately after reading a directory entry from the directory database

type: ldbmentryfetchstore

Extended operation
For processing an LDAP v3 extended operation

type: extendedop

Internal postoperation
After completing an operation initiated by Directory Server, for which no corresponding client request exists

type: internalpostoperation

Internal preoperation
Before performing an operation initiated by Directory Server, for which no corresponding client request exists

type: internalpreoperation

Matching rule
When finding search result candidates based on an extensible match filter for search operations only

type: matchingrule

Depends on the functions that are registered. (This type is generic and is used to register other types)

type: object

Password check
When performing a strong check on a userPassword value to add or modify

type: passwordcheck

Password storage scheme
When storing an encoded userPassword value that cannot be decrypted

type: pwdstoragescheme

After completing an operation requested by a client

type: postoperation

Before performing an operation requested by a client

type: preoperation

The following figure illustrates where in the processing sequence Directory Server calls some of the plug-in types described in Table 1-1.

Figure 1-2 Plug-In Entry Points

image:Diagram identifies points in client request processing where plug-ins may be called.

Notice that postoperation return codes do not affect Directory Server processing.

The plug-in type and plug-in configuration information are typically specified statically in a configuration entry.

You can include multiple plug-ins in a single shared library, but you must specify individual, server-specific configuration entries for each plug-in that is registered statically. This means that if you want preoperation and postoperation functions, you typically write two plug-ins. Then you register each plug-in with Directory Server. Both plug-ins can be contained in the same shared library. Both plug-ins can communicate private data across the same operation or connection, as well, using the interface provided. You can also write one plug-in that initializes other plug-ins, if that configuration is required for your deployment.

The sample plug-ins delivered with the product follow the principle of building all plug-ins into one library, then registering plug-ins individually.

The following figure shows multiple plug-ins that reside in the same library.

Figure 1-3 Multiple Plug-Ins in a Shared Library

image:Diagram shows multiple plug-ins of different types may be linked in a single shared library.

Each plug-in includes a registration routine that is called by Directory Server at startup. The registration routine explicitly registers each plug-in function with Directory Server.


Caution - Plug-in libraries are linked with Directory Server. Plug-ins execute in the same memory address space as Directory Server. Plug-ins have direct access to data structures used by Directory Server. As a result, plug-ins can corrupt memory used by Directory Server. Such memory corruption can result in database corruption. Due to this danger, never use an untested plug-in on a production Directory Server.

Furthermore, Directory Server runs as a multi threaded process. Code you write for a plug-in must be reentrant. Multiple threads can call your entry point simultaneously. These threads can be rescheduled at any time.