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


Logging Plug-In Messages

This sectioon shows how to do the following:

Log Three Levels of Message Severity

The plug-in API provides log functions for logging fatal error messages, warnings, and information. Error messages and warnings are always logged. Informational logging is turned off by default. You can adjust log levels while Directory Server is running.

Tip - Directory Server, as Directory Server waits for the system to write every log message to disk, slowing the server down.

Use logging when you need logging. Turn logging off when you do not need to use it.

Refer to Chapter 15, Function Reference, Part I for details about each of the logging functions.

Fatal Error Messages

For fatal errors, use slapi_log_error_ex(). In many cases, you might return -1 after you log the message to indicate to Directory Server that a serious problem has occurred.

Example 3-5 Logging a Fatal Error Message

#include "slapi-plugin.h"
#include "example-com-error-ids.h" /* unique
                                      error IDs file       */
foobar(Slapi_PBlock * pb)
    char * error_cause;
    int    apocalypse = 1;         /* Expect the worst.    */

    /* ... */

    if (apocalypse) {              /* Server to crash soon */
            EXCOM_SERVER_MORIBUND, /* Unique error ID      */
            " foobar in baz plug-in",
            "cannot write to file system: %s\n",
        return -1;
    return 0;

In this example, foobar() logs an error as Directory Server is about to crash.

Tip - If the plug-ins are internationalized, use macros, not literal strings, for the last two arguments to slapi_log_*_ex() functions.

Warning Messages

For serious situations that require attention and in which messages should always be logged, use slapi_log_warning_ex().

In the following example, foobar() logs a warning because the disk is nearly full.

Example 3-6 Logging a Warning Message

#include "slapi-plugin.h"
#include "example-com-warning-ids.h" /* unique
                                        warning IDs file  */
    int disk_use_percentage;

    /* ... */

    if (disk_use_percentage >= 95) {
            EXCOM_DISK_FULL_WARN,    /* unique warning ID */
            " foobar in baz plug-in",
            "disk %.0f%% full, find more space\n",
    return 0;

Informational Messages

For informational or debug messages, use slapi_log_info_ex(). This function can be set for default logging, which means that the message is not logged when logging is turned off for plug-ins. Informational logging can also be set to occur only when heavy logging is used. Thus, the message is logged when plug-in logging is both turned on and set to log all informational messages.

Refer to Review the Plug-In for an example of how to log an informational message from a plug-in.

Set the Appropriate Log Level in the Directory Server Configuration

Log levels can be set for plug-in informational messages, as well as for a number of other Directory Server subsystems. You can set the log level through Directory Service Control Center. You can also set the log level from the command line by using the dsconf set-log-prop command.

When you set dsconf set-log-prop error level:err-plugins, the server turns on plug-in informational logging.

Find Messages in the Log

The log file for errors, warnings, and informational messages is instance-path/logs/errors. All messages go to the same log so you can easily determine the order in which events occurred.

As shown in this example, messages consist of a timestamp, followed by an identifier, followed by the other information in the log message. Note that this log message is broken for the printed page.

[02/Jan/2006:16:54:57 +0100] - INFORMATION - 
 start_tls - conn=-1 op=-1 msgId=-1 - 
 Start TLS extended operation request confirmed.

Use the identifiers to filter what you do not need.