Netscape Directory Server Plug-In Programmer's Guide: Preface

Plug-In Programmer's Guide
Netscape Directory Server

Preface

This book describes how to write server plug-ins in order to customize and extend the capabilities of the Netscape 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".

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 the plug-in directives have changed. In the Directory Server 4.x release, the plugin directives were in the database section of the slapd.ldbm.conf file. In this release of Directory Server, you must add your plugin directives to 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. Note that 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 now 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 a _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 Windows NT and a number of different UNIX platforms; the information here applies to all versions. File and directory paths are given in Unix format (with forward slashes separating directory names). For Windows versions, the directory paths are the same, except that you use backslashes instead of slashes to separate directories.

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, and placeholders, and words used in the literal sense.

Variables are enclosed in angle brackets.

Boldface type is used for glossary terms.

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:

Netscape Directory Server Installation Guide. Contains procedures for installing your Directory Server as well as procedures for migrating from a previous installation of Directory Server.

Netscape Directory Server Deployment Guide. Contains procedures for the day-to-day maintenance of your directory service. Includes information on configuring server-side plug-ins.

Netscape 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.

Netscape Directory Server Configuration, Command, and File Reference. Contains information about using the command-line scripts shipped with Directory Server.

Netscape Directory Server Schema Reference. Contains information about the Directory Server schema.

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://enterprise.netscape.com/docs

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

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

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 a `_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()

Last Updated October 30, 2003