Preface

---

This book describes how to write server plug-ins in order to customize and extend the capabilities of the Red Hat Directory Server (Directory Server).

• What You Should Already Know
• Using Directory Server Plug-in APIs
• Document Conventions
• Where to Find Directory Server Information

What You Should Already Know

This book assumes you have this basic background:

• A general understanding of the Internet and the World Wide Web (WWW).
• A general understanding of the Lightweight Directory Access Protocol (LDAP) and the Directory Server. This book does not duplicate basic information on server administration or LDAP concepts. For such information, refer to the documents listed in "Where to Find Directory Server Information," on page 24.
• Programming experience in C or C++.

Using Directory Server Plug-in APIs

Note the following:

• When you install Directory Server, the plug-in related files are placed in this directory:

server_root /plugins/slapd/slapi/

• The main header file is located here:

server_root /plugins/slapd/slapi/include/slapi-plugin.h
 

• The location and syntax for you to add the plug-in directives are in the dse.ldif file, which is located in the server_root /slapd- instance_id /config directory. For guidelines, refer to the Readme file located here:

server_root /plugins/slapd/slapi/examples/
 

• Database plug-ins are not supported in this version of Directory Server. Be sure to use the pre-operation, post-operation, and/or extended operation API to register plug-in functions. Some code examples in this book are yet to be updated to reflect this change.
• To comply with Internet Protocol version 6, Directory Server plug-ins can use the SLAPI_CONN_CLIENTEDADDR and SLAPI_CONNSERVERADDR parameters to allow plug-ins to recognize the IP address of the LDAP client and server. These new parameters use the Netscape Portable Runtime (NSPR) PRNetADDr structure for storing the IP addresses. Because of this, the NSPR files are shipped with Directory Server.

The NSPR API allows compliant applications to use system facilities such as threads, thread synchronization, I/O, interval timing, atomic operations, and several other low-level services in a platform-independent manner.

• Several functions have been deprecated in this release of the Directory Server Plug-in API. The deprecated functions are still supported for backward compatibility. They are, however, not documented in this release. The table below lists the deprecated functions and the functions you should use in their place. If you need additional information on functions that have been deprecated, check this file:

server_root /plugins/slapd/slapi/include/slapi-plugin-compat4.h
 

Table 0-1 Deprecated Functions and Their Suggested Replacements  

Deprecated Function	Suggested Replacement Function
The following functions that deal with bervals are deprecated and their use is not recommended. For each deprecated function, you will find in slapi-plugin.h a corresponding function with an _sv extension that uses Slapi_Values instead of bervals. The new functions are more efficient than the old ones.
slapi_entry_attr_merge()	slapi_entry_attr_merge_sv()
slapi_entry_add_values()	slapi_entry_add_values_sv()
slapi_entry_delete_values()	slapi_entry_delete_values_sv()
slapi_entry_attr_replace()	slapi_entry_attr_replace_sv()
slapi_attr_get_values()	slapi_attr_value_find()
slapi_attr_get_oid()	slapi_attr_get_oid_copy()
slapi_pw_find()	slapi_pw_find_sv()
slapi_call_syntax_values2keys()	slapi_call_syntax_values2keys_sv()
slapi_call_syntax_assertion2keys_ava()	slapi_call_syntax_assertion2keys_ava_sv()
slapi_call_syntax_assertion2keys_sub()	slapi_call_syntax_assertion2keys_sub_sv()
slapi_entry_attr_hasvalue()	slapi_entry_attr_has_syntax_value()
The following internal-operation calls are deprecated. The new internal operation functions that are defined in slapi-plugin.h take a Slapi_PBlock for extensibility and support the new plug-in configuration capabilities.
slapi_search_internal_callback()	slapi_search_internal_callback_pb()
slapi_search_internal()	slapi_search_internal_pb()
slapi_modify_internal()	slapi_modify_internal_pb()
slapi_add_internal()	slapi_add_internal_pb()
slapi_delete_internal()	slapi_delete_internal_pb()
slapi_modrdn_internal()	slapi_modrdn_internal_pb()
The following three functions are not multi-thread safe; they return a pointer to unprotected data. Use the new functions in slapi-plugin.h that end in _copy() instead.
slapi_get_supported_controls()	slapi_get_supported_controls_copy()
slapi_get_supported_extended_ops()	slapi_get_supported_extended_ops_copy()
slapi_get_supported_saslmechanism()	slapi_get_supported_saslmechanisms_copy()

Document Conventions

The Directory Server runs on a number of different UNIX platforms; the information here applies to all versions.

This book uses Uniform Resource Locators (URLs) of the form

http://server.domain/path/file .html
 

In these URLs, server represents the name of the server on which you run your application (such as research1 or www), domain represents your Internet domain name (such as example.com), path represents the directory structure on the server, and file .html represents an individual filename.

If your server has Secure Sockets Layer (SSL) enabled, you would use https instead of http in the URL.

This book uses the following font conventions:

• The monospace font is used for sample code and code listings, API and language elements (such as function names and class names), filenames, pathnames, directory names, HTML tags, and any text that must be typed on the screen.
• Italic type is used for book titles, emphasis, placeholders, glossary terms, variables, and words used in the literal sense.

Where to Find Directory Server Information

This book explains how to write your own server plug-ins to customize the Directory Server. You can write plug-ins that validate data before the data is stored in the directory, that notify users when data has changed, or that replace the standard database in the Directory Server with your own database.

The document set for Directory Server also contains the following guides:

• Red Hat Directory Server Deployment Guide. Contains procedures for the day-to-day maintenance of your directory service. Includes information on configuring server-side plug-ins.
• Red Hat Directory Server Installation Guide. Contains procedures for installing your Directory Server as well as procedures for migrating from a previous installation of Directory Server.
• Red Hat Directory Server Administrator's Guide. Contains procedures for the day-to-day maintenance of your directory service. Includes information on configuring server-side plug-ins.
• Red Hat Directory Server Configuration, Command, and File Reference. Contains information about using the command-line scripts shipped with Directory Server.
• Red Hat Directory Server Schema Reference. Contains information about the Directory Server schema.
• Red Hat Directory Server Gateway Customization Guide. Introduces Directory Server Gateway and explains how to implement a gateway instance with basic directory look-up functionality. Also contains information useful for implementing a more powerful gateway instance with directory authentication and administration capability.
• Red Hat Directory Server Org Chart. Introduces the Red Hat Directory Server Org Chart application and explains how to integrate it with an instance of Directory Server.
• Red Hat Directory Server DSML Gateway Guide. Introduces the Red Hat Directory Server DSML Gateway function and explains how to customize it for use as an independent gateway.

For a list of documentation installed with Directory Server, open the server_root /manual/en/slapd/index.htm file, where server_root is the directory in which you installed Directory Server.

For the latest information about Directory Server, including current release notes, complete product documentation, technical notes, and deployment information, check this site:

http://www.redhat.com/docs/manuals/dir-server/
 

For a list of LDAP standards-related documents, check this site:

http://www.mozilla.org/directory/standards.html