Netscape NETSCAPE DIRECTORY SERVER 6.1 - PLUG-IN User manual

Plug-In Programmer’s Guide
Netscape Directory Server
Version6.1
August 2002

Netscape Communications Corporation (“Netscape”) and its licensors retain all ownership rights to the software programs offered
by Netscape (referred to herein as “Software”) and related documentation. Use of the Software and related documentation is
governed by the license agreement for the Software and applicable copyright law.
Your right to copy this documentation is limited by copyright law. Making unauthorized copies, adaptations or compilation works is
prohibited and constitutes a punishable violation of the law. Netscape may revise this documentation from time to time without
notice.
THIS DOCUMENTATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. IN NO EVENT SHALL NETSCAPE BE
LIABLE FOR INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES OF ANY KIND ARISING FROM ANY
ERROR IN THIS DOCUMENTATION, INCLUDING WITHOUT LIMITATION ANY LOSS OR INTERRUPTION OF BUSINESS,
PROFITS, USE, OR DATA.
The Software and documentation are copyright © 2001 Sun Microsystems, Inc. Portions copyright 1999, 2002 Netscape
Communications Corporation. All rights reserved.
Portions of the Software copyright © 1995 PEER Networks, Inc. All rights reserved. The Software contains the Taligent International
Classes from Taligent, Inc. and IBM Corp. Portions of the Software copyright ©1992-1998 Regents of the University of Michigan. All
rights reserved. The software contains encryption software from RSA Security Inc. Copyright © 1994 RSA Data Security, Inc. All
rights reserved.
Netscape and the Netscape N logo are registered trademarks of Netscape Communications Corporation in the United States and
other countries. Other Netscape logos, product names, and service names are also trademarks of Netscape Communications
Corporation, which may be registered in other countries. Other product and brand names are the exclusive property of their
respective owners.
The downloading, exporting, or reexporting of Netscape software or any underlying information or technology must be in full
compliance with all United States and other applicable laws and regulations. Any provision of Netscape software or documentation
to the U.S. government is with restricted rights as described in the license agreement for that Software.

3
Contents
Preface .......................................................................11
WhatYouShouldAlreadyKnow......................................................... 11
UsingDirectoryServerPlug-InAPIs...................................................... 11
DocumentConventions ................................................................. 13
WheretoFindDirectoryServerInformation ............................................... 14
Part 1 Introduction to Directory Server Plug-Ins . . . . . . . . . . . ...................... 17
Chapter 1 AnOverviewofDirectoryServerPlug-Ins................................19
WhatAreDirectoryServerPlug-Ins? ..................................................... 19
HowDirectoryServerPlug-InsWork ..................................................... 20
CallingDirectoryServerPlug-InFunctions ............................................. 21
TheDirectoryServerArchitecture ..................................................... 21
TypesofDirectoryServerPlug-Ins ....................................................... 24
Chapter 2 Writing and Compiling Plug-Ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
WritingaPlug-InFunction .............................................................. 27
IncludingtheAPIHeaderFile......................................................... 28
PassingDatawithParameterBlocks ................................................... 28
WorkingwithParameterBlocks ....................................................... 29
GettingDatafromtheParameterBlock .............................................. 29
SettingDataintheParameterBlock ................................................. 30
CallingFront-EndFunctions .......................................................... 31
Plug-inReturnValues................................................................ 31
WritingPlug-inInitializationFunctions ................................................... 32
InitializationFunctionsforWindowsPlatforms ....................................... 32
SpecifyingDirectoryServerCompatibility .............................................. 33
SpecifyingInformationAboutthePlug-In .............................................. 33

4 Netscape Directory Server Plug-In Programmer’s Guide • August 2002
RegisteringYourPlug-InFunctions .................................................... 34
ReturningaValuetotheDirectoryServer............................................... 35
ExampleofanInitializationFunction .................................................. 35
CompilingaDirectoryServerPlug-In..................................................... 36
Chapter 3 Configuring Plug-Ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
CreatingaPlug-InConfigurationFile ..................................................... 39
Plug-InDependencies................................................................ 41
SpecificPlug-inDependencies ...................................................... 41
Plug-InTypeDependencies ........................................................ 42
SpecifyingtheOrderofPlug-InDirectives .............................................. 42
SummaryofPlug-InDirectives........................................................ 42
LoadingthePlug-InConfigurationFile ................................................... 44
PassingExtraArgumentstoPlug-Ins ..................................................... 45
SettingtheLogLeveloftheServer........................................................ 46
Chapter 4 AQuickExample ................................................... 47
AnExamplePre-OperationPlug-In....................................................... 47
WritingthePlug-InExample.......................................................... 48
Compiling the Plug-In Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
RegisteringthePlug-InExample....................................................... 52
RunningthePlug-InExample ......................................................... 53
Part 2 BasicPlug-InProgrammingTechniques ..................................55
Chapter 5 Front-End API Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
LoggingMessages...................................................................... 58
AddingNotestoAccessLogEntries ...................................................... 58
SendingDatatotheClient............................................................... 59
DeterminingifanOperationWasAbandoned ............................................. 59
WorkingwithEntries,Attributes,andValues .............................................. 60
CreatingaNewEntry ................................................................ 61
ConvertingBetweenEntriesandStrings ................................................ 61
GettingandSettingtheDNofanEntry................................................. 62
VerifyingCompliancewiththeSchema................................................. 62
GettingtheAttributesandValuesofanEntry ........................................... 63
IteratingThroughtheAttributesinanEntry.......................................... 63
FindingaSpecificAttributeinanEntry .............................................. 63
Adding and Removing Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
WorkingwithDNsandRDNs ........................................................... 64
DeterminingifaDNistheRootDN ................................................... 64

5
WorkingwithDNSuffixes............................................................ 65
ServerSuffixes ................................................................... 65
GettingtheParentDNofaDN ........................................................ 65
NormalizingaDN................................................................... 65
WorkingwithSearchFilters ............................................................. 66
DeterminingifanEntryMatchesaFilter................................................ 67
GettingtheFilterType ............................................................... 67
GettingtheSearchCriteria............................................................ 68
ConvertingaStringtoaFilter ......................................................... 69
CreatingComplexFiltersbyCombiningFilters.......................................... 69
CheckingPasswords.................................................................... 69
Chapter 6 WritingPre/Post-OperationPlug-Ins ....................................71
HowPre/Post-OperationPlug-InsWork .................................................. 71
TypesPre-OperationandPost-OperationFunctions ........................................ 73
TypesofPre-OperationFunctions ..................................................... 73
TypesofPost-OperationFunctions..................................................... 74
RegisteringPre/Post-OperationFunctions................................................. 76
Chapter 7 Defining Functions for LDAP Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
SpecifyingStartandCloseFunctions...................................................... 78
ProcessinganLDAPBindOperation...................................................... 78
DefiningFunctionsfortheBindOperation.............................................. 78
GettingandSettingParametersfortheBindOperation ................................... 79
ProcessinganLDAPUnbindOperation ................................................... 79
ProcessinganLDAPSearchOperation .................................................... 80
Getting the List of Candidates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
IteratingThroughCandidates ......................................................... 82
ProcessinganLDAPCompareOperation.................................................. 84
ProcessinganLDAPAddOperation...................................................... 84
ProcessinganLDAPModifyOperation ................................................... 86
ProcessinganLDAPModifyRDNOperation .............................................. 87
ProcessinganLDAPDeleteOperation .................................................... 89
ProcessinganLDAPAbandonOperation ................................................. 89
Chapter 8 Defining Functions for Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
UnderstandingAuthenticationMethods .................................................. 91
HowtheDirectoryServerIdentifiesClients................................................ 92
HowtheAuthenticationProcessWorks ................................................... 92
WritingYourOwnAuthenticationPlug-in ................................................ 95
WritingaPre-OperationBindPlug-in..................................................... 95
DefiningYourAuthenticationFunction ................................................ 97

6 Netscape Directory Server Plug-In Programmer’s Guide • August 2002
GettingandCheckingtheBindParameters........................................... 97
GettingtheEntryandCheckingtheCredentials....................................... 98
WhattoDoIfAuthenticationFails .................................................. 99
WhattoDoIfAuthenticationSucceeds .............................................. 99
RegisteringtheSASLMechanism..................................................... 100
ExampleofaPre-OperationBindPlug-In .............................................. 101
ExampleofaPre-OperationBindFunction .......................................... 101
ExampleofanInitializationFunction ............................................... 104
RegisteringthePlug-In ........................................................... 105
Using SASL with an LDAP Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Part 3 AdvancedProgrammingTechniques ....................................111
Chapter 9 WritingEntryStore/FetchPlug-Ins.................................... 113
HowEntryStore/FetchPlug-InsWork................................................... 113
WritingEntryStore/FetchFunctions .................................................... 114
RegisteringEntryStore/FetchFunctions ................................................. 115
Chapter 10 WritingExtendedOperationPlug-Ins................................. 117
HowExtendedOperationPlug-InsWork................................................. 117
WritingExtendedOperationFunctions .................................................. 118
RegisteringExtendedOperationFunctions ............................................... 119
SpecifyingStartandCloseFunctions..................................................... 121
Chapter 11 WritingMatchingRulePlug-Ins ..................................... 123
UnderstandingMatchingRules ......................................................... 123
ExtensibleMatchFilters ............................................................. 124
ExtensibleMatchFiltersintheDirectoryServer ........................................ 125
UnderstandingMatchingRulePlug-Ins .................................................. 125
FunctionsDefinedinMatchingRulePlug-Ins .......................................... 125
HowMatchingRulesAreIdentified................................................... 126
HowtheServerAssociatesPlug-InswithOIDs ......................................... 127
FindingaPlug-InforIndexing..................................................... 127
FindingaPlug-InforSearching .................................................... 128
HowtheServerUsesParameterBlocks ................................................ 129
IndexingBasedonMatchingRules ...................................................... 129
HowtheServerSetsUptheIndex .................................................... 129
HowtheServerUpdatestheIndex.................................................... 130
WritingtheIndexerFactoryFunction ................................................. 131
GettingandSettingParametersinIndexerFactoryFunctions............................. 132
WritingtheIndexerFunction ........................................................ 133

7
GettingandSettingParametersinIndexerFunctions .................................... 134
HandlingExtensibleMatchFilters....................................................... 134
HowtheServerHandlestheFilter .................................................... 135
QueryOperatorsinMatchingRules................................................... 136
WritingaFilterFactoryFunction ..................................................... 137
GettingandSettingParametersinFilterFactoryFunctions ............................... 138
WritingaFilterIndexFunction....................................................... 139
GettingandSettingParametersinFilterIndexFunctions ................................ 140
WritingaFilterMatchingFunction ................................................... 141
HandlingSortingbyMatchingRules .................................................... 142
WritingaDestructorFunction .......................................................... 143
WritinganInitializationFunction ....................................................... 143
RegisteringMatchingRuleFunctions .................................................... 145
SpecifyingStartandCloseFunctions..................................................... 146
Chapter 12 Using the Custom Distribution Logic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
AboutDistributingFlatNamespaces..................................................... 147
CreatingaDistributionFunction ........................................................ 148
AddingtheDistributionFunctiontoYourDirectory ....................................... 150
Adding Multiple Databases to a Single Suffix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
UsingtheConsole ............................................................... 151
FromtheCommand-Line ......................................................... 151
Adding Distribution Logic to a Suffix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
UsingtheConsole ............................................................... 152
FromtheCommand-Line ......................................................... 152
UsingtheDistributionLogicExamples................................................... 153
CustomDistributionChecklist .......................................................... 154
Chapter 13 Using Data Interoperability Plug-Ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
Installing Directory Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
UnderstandingDeploymentConfiguration ............................................ 156
Installing Two Instances of Directory Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
EnablingtheDIOPFeatureinDirectoryServer............................................ 161
UsingtheDIOPFeature................................................................ 162
SampleDIOPPlug-In.................................................................. 164
DebuggingthePlug-In .............................................................. 166
Plug-InAPIReference ................................................................. 167
PreservingtheDefaultBehavioroftheServer .......................................... 167
BypassingAccessControlChecks..................................................... 167

8 Netscape Directory Server Plug-In Programmer’s Guide • August 2002
Part 4 Reference...........................................................169
Chapter 14 DataTypeandStructureReference .................................. 171
SummaryofDataTypesandStructures .................................................. 171
Chapter 15 FunctionReference ............................................... 215
DistributionRoutines.................................................................. 216
FunctionsforAccessControl ........................................................... 218
FunctionsforInternalOperationsandPlug-InCallback .................................... 224
FunctionsforSettingInternalOperationFlags ............................................ 232
FunctionsforHandlingAttributes....................................................... 243
FunctionsforManagingBackendOperations ............................................. 262
FunctionsforDealingwithControls ..................................................... 281
FunctionsforSyntaxPlug-In............................................................ 288
FunctionsforManagingMemory........................................................ 291
FunctionsforManagingDNs ........................................................... 298
FunctionsforManagingEntries ......................................................... 307
FunctionsRelatedtoEntryFlags ........................................................ 345
FunctionsforDealingwithFilters ....................................................... 348
FunctionsSpecifictoExtendedOperation ................................................ 367
FunctionsSpecifictoBindMethods...................................................... 368
FunctionsforThread-SafeLDAPConnections ............................................ 369
FunctionsforLogging ................................................................. 372
FunctionsforHandlingMatchingRules.................................................. 375
FunctionsforLDAPModManipulation .................................................. 383
FunctionsforMonitoringOperations .................................................... 419
FunctionsforManagingParameterBlock................................................. 421
FunctionsforHandlingPasswords ...................................................... 425
FunctionsforManagingRDN........................................................... 428
FunctionsforManagingRoles .......................................................... 450
FunctionsforManagingDNs ........................................................... 451
FunctionsforSendingEntriesandResultstotheClient..................................... 476
FunctionsRelatedtoUTF-8............................................................. 481
FunctionsforHandlingValues.......................................................... 494
FunctionsforHandlingValueset ........................................................ 514
FunctionsSpecifictoVirtualAttributeService ............................................ 524
FunctionsforManagingLocksandSynchronization ....................................... 532
FunctionsforManagingComputedAttributes ............................................ 537
FunctionsforManipulatingBits......................................................... 540
FunctionsforRegisteringObjectExtensions .............................................. 545
FunctionsRelatedtoDataInteroperability................................................ 548
FunctionsforRegisteringAdditionalPlug-Ins............................................. 552

9
Chapter 16 ParameterBlockReference .........................................555
ParametersforRegisteringPlug-InFunctions ............................................. 556
Pre-Operation/DataValidationPlug-Ins .............................................. 556
Post-Operation/DataNotificationPlug-Ins ............................................ 558
MatchingRulePlug-Ins ............................................................. 559
EntryPlug-Ins ..................................................................... 560
ParametersAccessibletoAllPlug-Ins .................................................... 560
InformationAbouttheDatabase...................................................... 561
InformationAbouttheConnection.................................................... 562
InformationAbouttheOperation..................................................... 565
InformationAboutExtendedOperations .............................................. 566
InformationAbouttheTransaction ................................................... 566
InformationAboutAccessControlLists ............................................... 567
NotesintheAccessLog ............................................................. 567
InformationAboutthePlug-In ....................................................... 568
TypesofPlug-Ins ................................................................ 568
VersionInformation.............................................................. 569
InformationAboutCommand-LineArguments ........................................ 570
InformationAboutAttributes ........................................................ 570
AttributeNames................................................................. 570
AttributeFlags .................................................................. 571
AttributeComparisons ........................................................... 571
InformationAboutTargets .......................................................... 572
ParametersfortheBindFunction........................................................ 572
ParametersfortheSearchFunction ...................................................... 573
ParametersPassedtotheSearchFunction.............................................. 573
ParametersforExecutingtheSearch .................................................. 574
ParametersfortheSearchResults..................................................... 575
ParametersthatReturnDataTypes................................................. 575
ParametersthatConvertStringstoEntries................................................ 576
ParametersfortheAddFunction........................................................ 577
ParametersfortheCompareFunction.................................................... 578
ParametersfortheDeleteFunction ...................................................... 578
ParametersfortheModifyFunction ..................................................... 579
ParametersfortheModifyRDNFunction ................................................ 579
ParametersfortheAbandonFunction.................................................... 580
ParametersfortheMatchingRuleFunction............................................... 581
QueryOperatorsinExtensibleMatchFilters ........................................... 582
ParametersforLDBMBackendPre-andPost-OperationFunctions .......................... 583
Pre-OperationPlug-Ins.............................................................. 583
Post-OperationPlug-Ins ............................................................. 584
ParametersfortheDatabase ............................................................ 584
InformationAbouttheDatabase...................................................... 584

10 Netscape Directory Server Plug-In Programmer’s Guide • August 2002
InformationAboutOperations ....................................................... 585
InformationAboutBackendStateChange ............................................. 586
ParametersforLDAPFunctions......................................................... 586
ParametersforLDAPOperations ..................................................... 586
ParametersforLDAPControl ........................................................ 587
ParametersforGeneratingLDIFStrings ............................................... 588
ParametersforErrorLogging ........................................................... 589
ParametersforFilters .................................................................. 590
ParametersforComparisonFilters.................................................... 591
ParametersforFilterOperations...................................................... 591
ParametersforPasswordStorage........................................................ 592
PasswordStoragePlug-Ins........................................................... 592
ParametersforPasswordStorage ..................................................... 592
ParametersforResourceLimits ......................................................... 593
ParameterforBinder-BasedResourceLimits ........................................... 593
StatusCodesforResourceLimits ..................................................... 593
ParametersfortheVirtualAttributeService .............................................. 593
Glossary .................................................................... 597
Index ....................................................................... 601

11
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,” on page 14.
• 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/

Using Directory Server Plug-In APIs
12 Netscape Directory Server Plug-In Programmer’s Guide • August 2002
• 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()

Document Conventions
Preface 13
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
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()
Table 0-1 Deprecated Functions and Their Suggested Replacements (Continued)
Deprecated Function Suggested Replacement Function

Where to Find Directory Server Information
14 Netscape Directory Server Plug-In Programmer’s Guide • August 2002
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.

Where to Find Directory Server Information
Preface 15
•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,
checkthissite:http://enterprise.netscape.com/docs

Where to Find Directory Server Information
16 Netscape Directory Server Plug-In Programmer’s Guide • August 2002

17
Part 1
Introduction to Directory Server
Plug-Ins
Chapter 1, “An Overview of Directory Server Plug-Ins”
Chapter 2, “Writing and Compiling Plug-Ins”
Chapter 3, “Configuring Plug-Ins”
Chapter 4, “A Quick Example”

18 Netscape Directory Server Plug-In Programmer’s Guide • August 2002

19
Chapter 1
An Overview of Directory Server
Plug-Ins
This chapter introduces you to Netscape Directory Server (Directory Server)
plug-ins and discusses the different types of plug-ins that you can write. The
chapter covers the following topics:
• What Are Directory Server Plug-Ins?
• How Directory Server Plug-Ins Work
• Types of Directory Server Plug-Ins
If you have already written a plug-in for Directory Server, refer to the section
“Using Directory Server Plug-In APIs” on page 11 for information on migrating
your plug-in to the latest version of the Directory Server.
What Are Directory Server Plug-Ins?
If you want to extend the capabilities of the Directory Server, you can write your
own Directory Server plug-in. A server plug-in is a shared object or library (or on the
Windows NT platform, a dynamic link library) that contains custom functions that
you write.
By writing your own plug-in functions, you can extend the functionality of the
Directory Server. For example, here are some of the things you can do with
Directory Server plug-ins:
• You can design an action that the Directory Server performs before the server
processes an LDAP action. For example, you can write a custom function to
validate data before the server performs an LDAP operation on the data.

How Directory Server Plug-Ins Work
20 Netscape Directory Server Plug-In Programmer’s Guide • August 2002
• You can design an action that the Directory Server performs after the server
successfully completes an LDAP operation. For example, you can send mail to
a client after an LDAP operation is successfully completed.
• You can define extended operations, as defined in the the LDAP v3 protocol.
• You can provide alternate matching rules when comparing certain attribute
values.
How Directory Server Plug-Ins Work
When properly configured, the Directory Server will load your plug-in on startup.
Once loaded, the Directory Server will resolve calls made to your plug-in functions
as it processes the LDAP requests contained in your applications.
Internally, the Directory Server has hooks that allow you to register your own
functions to be called when specific events occur. For example, the Directory Server
has hooks to call a registered plug-in in the following situations:
• Before preforming an LDAP operation (for example, before an entry is added
to the directory)
• When adding, modifying, removing, renaming, or searching for entries in the
database
• After performing an LDAP operation (for example, after an entry is added to
the directory)
• Before writing an entry to the database
• After reading an entry from the database
• When processing an extended operation
• When indexing an attribute
• When filtering search result candidates based on an attribute
When you register your plug-in functions, you specify the function type and the
plug-in type. Together, these specifications indicate when the function is called. For
more information on this topic, refer to the section “Types of Directory Server
Plug-Ins” on page 24.