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

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

3.  Getting Started With Directory Server Plug-Ins

A Hello World Plug-In

Find the Code

Review the Plug-In

Build the Plug-In

Plug In the Plug-In

Updating Directory Server Configuration

Restarting Directory Server

Checking the Log

Writing Directory Server Plug-Ins

Include the slapi-plugin.h Header File

Write Your Plug-In Functions

Use Appropriate Return Codes

Write an Initialization Function

Set Configuration Information Through the Parameter Block

Specifying Compatibility

Specifying the Plug-In Description

Set Pointers to Functions Through the Parameter Block

Locate Examples

Building Directory Server Plug-Ins

Include the Header File for the Plug-In API

Link the Plug-In as a Shared Object or Dynamic Link Library

Locate the Example Build Rules

Plugging Libraries Into Directory Server

Specify Plug-In Configuration Settings

Understanding Plug-In Types and Dependencies

Ordering Plug-In Calls

Retrieving Arguments Passed to Plug-Ins

Searching Plug-In Libraries

Modify the Directory Server Configuration

Restart Directory Server

Logging Plug-In Messages

Log Three Levels of Message Severity

Fatal Error Messages

Warning Messages

Informational Messages

Set the Appropriate Log Level in the Directory Server Configuration

Find Messages in the Log

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


A Hello World Plug-In

This section demonstrates a plug-in that logs a famous greeting. You can follow the process outlined in this section to understand the concepts that are covered in this chapter.

Find the Code

On the directory host, look in the install-path/examples/ directory. The example code that is covered in this section is hello.c.

Review the Plug-In

The following example logs Hello, World! at Directory Server startup.

Example 3-1 Hello, World! Plug-In (hello.c)

#include "slapi-plugin.h"

Slapi_PluginDesc desc = { 
    "Hello, World",                    /* plug-in identifier      */
    "Oracle Corporation (test)",       /* vendor name             */
    "",                      /* plug-in revision number */
    "My first plug-in"                 /* plug-in description     */

/* Log a greeting at server startup if info logging is on for plug-ins */
        SLAPI_LOG_INFO_AREA_PLUGIN,    /* Log if info logging is  */
        SLAPI_LOG_INFO_LEVEL_DEFAULT,  /* set for plug-ins.       */
        SLAPI_LOG_NO_MSGID,            /* No client at startup    */
        SLAPI_LOG_NO_CONNID,           /* No conn.  at startup    */
        SLAPI_LOG_NO_OPID,             /* No op.    at startup    */
        "hello() in My first plug-in", /* Origin of this message  */
        "Hello, World!\n"              /* Informational message   */
    return 0;

/* Register the plug-in with the server */
#ifdef _WIN32
hello_init(Slapi_PBlock * pb)
    int rc = 0;                        /* 0 means success         */
    rc |= slapi_pblock_set(            /* Plug-in API version     */
    rc |= slapi_pblock_set(            /* Plug-in description     */
        (void *) &desc;
    rc |= slapi_pblock_set(            /* Startup function        */
        (void *) hello
    return rc;

To log the greeting, the plug-in includes a function to be called at Directory Server startup. The plug-in also includes an initialization function to register the plug-in description, supported API version, and startup function with Directory Server.

The startup function specifies that the message is from a plug-in, SLAPI_LOG_INFO_AREA_PLUGIN. The startup function also specifies that the message should be logged when informational logging is activated, SLAPI_LOG_INFO_LEVEL_DEFAULT. For this log message, no client connection information is available, SLAPI_LOG_NO_MSGID, SLAPI_LOG_NO_CONNID, SLAPI_LOG_NO_OPID. Directory Server calls the function at startup before any clients have connected. The function specifies where the log message originates, "hello() in My first plug-in". Finally, the function provides the famous log message.

The initialization function is named hello_init(). This function modifies the parameter block, pb, with the function slapi_pblock_set(). The function thus registers the plug-in API version supported, the plug-in description, and the functions offered to Directory Server by this plug-in. As required for all plug-in initialization functions, hello_init() returns 0 on success, -1 on failure. The function slapi_pblock_set() returns 0 if successful, -1 otherwise. Therefore, you do not need to set the return code to -1 explicitly in A Hello World Plug-In.

Build the Plug-In

Build the plug-in as a shared object, or, or dynamic link library, testplugin.dll, depending on your platform. On Solaris SPARC systems, you do the following.

$ gmake -f Makefile

On Solaris x64 systems where you boot a 64–bit kernel, you do the following.

$ gmake -f Makefile64

Use the Makefile or Makefile64 in install-path/examples/ to compile and to link the code. This file builds and links all plug-in examples into the same library. Refer to Searching Plug-In Libraries for details when building a plug-in for use with a 64-bit Directory Server instance.

Plug In the Plug-In

Use the dsconf(1M) command to add information about the plug-in to the server configuration.

Updating Directory Server Configuration

Configure the server to log plug-in messages:

$ dsconf set-log-prop -h localhost -p 1389 error level:err-plugins

Configure the server to load the plug-in:

$ dsconf create-plugin -h localhost -p 1389 \
 -H lib-path -F hello_init -Y object "Hello World"
$ dsconf set-plugin-prop "Hello World" feature:"Hello, World" version: 
 vendor:"Oracle Corporation (test)" desc:"My first plug-in"
$ dsconf enable-plugin -h localhost -p 1389 "Hello World"
Directory Server needs to be restarted for changes to take effect

Here, lib-path must correspond to the absolute path to the plug-in library, such as /local/myplugins/examples/ Directory Server requires an absolute path, not a relative path. Before setting lib-path on a 64–bit system, read Searching Plug-In Libraries.

Note - Plug-ins delivered with Directory Server have signatures, which are stored as ds-pluginSignature attribute values. Plug-ins also have digests, which are stored as ds-pluginDigest attribute values. The values allow you to differentiate plug-ins that are delivered with Directory Server from custom plug-ins.

Restarting Directory Server

After changing the Directory Server configuration, you must restart Directory Server for the server to register the plug-in. Use the dsadm(1M) command.

For example, to restart a server instance in /local/ds/, type the following:

$ dsadm restart /local/ds
Waiting for server to stop...
Server stopped
Server started: pid=4362

Checking the Log

After Directory Server has started, search the error log, instance-path/logs/errors, for Hello, World! You should find an entry similar to the following line, which is wrapped for the printed page:

[02/Jan/2006:16:56:07 +0100] - INFORMATION - 
 hello() in My first plug-in - conn=-1 op=-1 msgId=-1 -  Hello, World!

At this point, reset the log level to the default to avoid logging unnecessary messages:

$ dsconf set-log-prop -h localhost -p 1389 error level:default