Skip Navigation Links | |
Exit Print View | |
Oracle Directory Server Enterprise Edition Developer's Guide 11 g Release 1 (11.1.1.5.0) |
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
Writing Directory Server Plug-Ins
Include the slapi-plugin.h Header File
Write an Initialization Function
Set Configuration Information Through the Parameter Block
Specifying the Plug-In Description
Set Pointers to Functions Through the Parameter Block
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
Retrieving Arguments Passed to Plug-Ins
Modify the Directory Server Configuration
Log Three Levels of Message Severity
Set the Appropriate Log Level in the Directory Server Configuration
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
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.
On the directory host, look in the install-path/examples/ directory. The example code that is covered in this section is hello.c.
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 */ "11.1.1.3.0", /* 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 */ int hello() { slapi_log_info_ex( 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 __declspec(dllexport) #endif int hello_init(Slapi_PBlock * pb) { int rc = 0; /* 0 means success */ rc |= slapi_pblock_set( /* Plug-in API version */ pb, SLAPI_PLUGIN_VERSION, SLAPI_PLUGIN_CURRENT_VERSION ); rc |= slapi_pblock_set( /* Plug-in description */ pb, SLAPI_PLUGIN_DESCRIPTION, (void *) &desc; ); rc |= slapi_pblock_set( /* Startup function */ pb, SLAPI_PLUGIN_START_FN, (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 as a shared object, libtest-plugin.so or libtest-plugin.sl, 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.
Use the dsconf(1M) command to add information about the plug-in to the 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:11.1.1.3.0 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/libtest-plugin.so. 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.
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
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