Sun Java(TM) System Directory Server 5.2 2005Q1 Plug-In Developer's Guide |
Chapter 2
Changes to the Plug-In API Since Directory Server 4.xThis chapter describes the changes made to the plug-in API since the Directory Server 4.x releases. If you maintain Directory Server plug-ins originally developed for a previous release, we recommend upgrading such plug-ins to accommodate new features.
Sun Professional Services consultants can help. For information about what Sun Professional Services has to offer, refer to the following web site:
http://www.sun.com/service/sunone/software
We strongly recommend you work closely with Sun Professional Services consultants to develop and to maintain your Directory Server plug-ins.
For information about a function, refer to the Directory Server Plug-in Developer's Reference.
Deprecated and Changed FeaturesThis section lists features deprecated since the 4.x releases. Where possible, we recommend replacement functionality.
For information about a function, refer to the Directory Server Plug-in Developer's Reference.
Handling Deprecation
SLAPI_DEPRECATED has been defined in slapi-plugin.h to highlight what has been superseded. If you cannot change core plug-in code, you may decide to recompile after including slapi-plugin-compat4.h to access deprecated features for this release. For example:
#include "slapi-plugin-compat4.h"
In general, you must at minimum recompile your plug-ins to have them work with Directory Server 5.2. Where possible, replace deprecated code with new alternatives before recompiling and testing.
Registering Plug-Ins
Plug-in directives have been deprecated. Use configuration entries instead. Refer to Plugging Libraries into Directory Server for details on using configuration entries to load and configure plug-ins.
Function Parameters
Many existing function parameters have become const to reflect that parameter values are not changed when reading information.
Data Types
Consider using opaque data types wherever possible. Refer to the Directory Server Plug-in Developer's Reference for information on data types.
Plug-In Types
The SLAPI_PLUGIN_DATABASE plug-in (database) type has been deprecated.
Access Control
slapi_acl_verify_aci_syntax() now takes a pointer to a Slapi_PBlock as its first parameter. You must modify plug-in code to account for this change.
Attributes
Table 2-1 lists deprecated and replacement functions for handling attributes.
Controls
slapi_get_supported_controls() is not thread-safe and has been deprecated. Use slapi_get_supported_controls_copy() instead.
SLAPI_OPERATION_* identifiers have changed to unsigned long values.
Entries
Table 2-2 lists deprecated and replacement functions for handling entries.
Error Codes
slapi-plugin.h now includes ldap_msg.h, which lists unique error numbers used by Directory Server.
Functions for dealing with backends that return int error codes can now also return SLAPI_FAIL_RETRY. The old values are also still used.
Directory Server now distinguishes between SLAPI_BIND_FAIL, indicating that the bind failed and the server prepares a result to send, and SLAPI_BIND_ANONYMOUS, indicating that the bind succeeded as an anonymous bind.
Extended Operations
slapi_get_supported_extended_ops() is not thread-safe and has been deprecated. Use slapi_get_supported_extended_ops_copy() instead.
Filters
slapi_filter_get_type() has been deprecated. Use slapi_filter_get_attribute_type() instead, which works for all simple filter choices.
Internal Operations
Table 2-3 lists deprecated and replacement functions for handling internal operations.
Logging
Table 2-4 lists deprecated and replacement functions for logging.
Refer to Logging Plug-In Messages and all example code delivered with the product for demonstrations of how to use the new logging interface.
Parameter Block Arguments
Table 2-5 lists deprecated and replacement parameter block arguments.
Password Handling
Table 2-6 lists deprecated and replacement functions for password handling.
Table 2-6 Replacement Functions for Password Handling
Deprecated Function
Replacement Function
slapi_pw_find()
slapi_pw_find_valueset()
SASL Binds
Table 2-7 lists deprecated and replacement functions for SASL binds.
Table 2-7 Replacement Functions for SASL Binds
Deprecated Function
Replacement Function
slapi_get_supported_saslmechanisms()
slapi_get_supported_saslmechanisms_copy()
New FeaturesThis section summarizes features added since the previous release. It does not include features reserved for internal use.
For information about a function, refer to the Directory Server Plug-in Developer's Reference.
Plug-In API Version 3
The header file slapi-plugin.h identifies the current plug-in API as version 3. Plug-ins supporting API version 3 indicate the version in their description using SLAPI_PLUGIN_VERSION_03 or currently SLAPI_PLUGIN_CURRENT_VERSION.
Plug-In Types
New plug-in types have been added since the 4.x releases. For a list of supported plug-in types, refer to Table 1-1.
Plug-In Configuration Entries
Configuration entries rather than directives are now used to configure Directory Server plug-ins. Refer to Plugging Libraries into Directory Server for details on using configuration entries to load and configure plug-ins.
Use of NSPR 4.x
The Netscape Portable Runtime (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.
For information on the version of NSPR used at the time of this writing, refer to:
http://www.mozilla.org/projects/nspr/release-notes/
Attributes
Table 2-8 lists new flags defined for use with existing functions for handling attributes.
The old flags are still available. Refer to comments in slapi-plugin.h for hints on how to use the flags.
The following functions have been added to handle attributes and their values.
slapi_attr_add_value()
slapi_attr_first_value()
slapi_attr_get_numvalues()
slapi_attr_get_valueset()
slapi_attr_init()
slapi_attr_next_value()
slapi_attr_set_valueset()
slapi_attr_syntax_normalize()
slapi_attr_types_equivalent()
Backends
The following functions have been added to handle Slapi_Backend structures.
slapi_be_exist()
slapi_be_get_name()
slapi_be_get_readonly()
slapi_be_getsuffix()
slapi_be_gettype()
slapi_be_is_flag_set()
slapi_be_issuffix()
slapi_be_logchanges()
slapi_be_private()
slapi_be_select()
slapi_be_select_by_instance_name()
slapi_free_suffix_list()
slapi_get_first_backend()
slapi_get_next_backend()
slapi_get_suffix_list()
slapi_is_root_suffix()
Controls
The following functions have been added.
slapi_build_control()
slapi_build_control_from_berval()
slapi_dup_control()
Data Structures
The following data are now defined in slapi-plugin.h to wrap key objects used by Directory Server plug-ins.
Slapi_Attr
Slapi_Backend
Slapi_ComponentId
Slapi_Connection
Slapi_DN
Slapi_Entry
Slapi_Filter
Slapi_MatchingRuleEntry
Slapi_Mod
Slapi_Mods
Slapi_Operation
Slapi_PBlock
Slapi_RDN
Slapi_Value
Slapi_ValueSet
Distinguished Names (DNs)
The following functions have been added to handle Slapi_DN structures.
slapi_dn_normalize_to_end()
slapi_dn_plus_rdn()
slapi_moddn_get_newdn()
slapi_sdn_compare()
slapi_sdn_copy()
slapi_sdn_done()
slapi_sdn_dup()
slapi_sdn_free()
slapi_sdn_get_backend_parent()
slapi_sdn_get_dn()
slapi_sdn_get_ndn()
slapi_sdn_get_ndn_len()
slapi_sdn_get_parent()
slapi_sdn_get_rdn()
slapi_sdn_is_rdn_component()
slapi_sdn_isempty()
slapi_sdn_isgrandparent()
slapi_sdn_isparent()
slapi_sdn_issuffix()
slapi_sdn_new()
slapi_sdn_new_dn_byref()
slapi_sdn_new_dn_byval()
slapi_sdn_new_dn_passin()
slapi_sdn_new_ndn_byref()
slapi_sdn_new_ndn_byval()
slapi_sdn_scope_test()
slapi_sdn_set_dn_byref()
slapi_sdn_set_dn_byval()
slapi_sdn_set_dn_passin()
slapi_sdn_set_ndn_byref()
slapi_sdn_set_ndn_byval()
slapi_sdn_set_parent()
slapi_sdn_set_rdn()
Entries
Table 2-9 lists new flags defined for use with existing functions for handling entries.
The old flags are still available. Refer to comments in slapi-plugin.h for hints on how to use the flags.
The following functions have been added to handle entries.
slapi_entry2str_with_options()
slapi_entry_add_string()
slapi_entry_add_value()
slapi_entry_attr_add()
slapi_entry_attr_get_long()
slapi_entry_attr_get_uint()
slapi_entry_attr_get_ulong()
slapi_entry_attr_remove()
slapi_entry_attr_set_int()
slapi_entry_attr_set_uint()
slapi_entry_attr_set_ulong()
slapi_entry_delete_string()
slapi_entry_get_dn_const()
slapi_entry_get_ndn()
slapi_entry_get_sdn()
slapi_entry_get_sdn_const()
slapi_entry_get_uniqueid()
slapi_entry_has_children()
slapi_entry_init()
slapi_entry_set_sdn()
slapi_entry_size()
slapi_is_rootdse()
Filters
The following functions have been added to handle Slapi_Filter structures.
slapi_filter_apply()
slapi_filter_compare()
slapi_filter_get_attribute_type()
slapi_filter_has_extension()
slapi_filter_test_simple()
slapi_find_matching_paren()
slapi_vattr_filter_test()
Internal Operations
The following new functions are intended for use with the updated interface.
slapi_add_entry_internal_set_pb()
slapi_add_internal_set_pb()
slapi_delete_internal_set_pb()
slapi_modify_internal_set_pb()
slapi_rename_internal_set_pb()
slapi_search_internal_get_entry()
slapi_search_internal_set_pb()
Refer to Chapter 7, "Performing Internal Operations," for a demonstration of how to use the updated interface.
Memory Management
Table 2-10 lists new functions that have been added to manage memory.
Modification Structures
The following functions have been added to handle Slapi_Mod structures.
slapi_mod_add_value()
slapi_mod_done()
slapi_mod_dump()
slapi_mod_free()
slapi_mod_get_first_value()
slapi_mod_get_next_value()
slapi_mod_get_num_values()
slapi_mod_get_operation()
slapi_mod_get_type()
slapi_mod_init()
slapi_mod_init_byref()
slapi_mod_init_byval()
slapi_mod_init_passin()
slapi_mod_isvalid()
slapi_mod_new()
slapi_mod_remove_value()
slapi_mod_set_operation()
slapi_mod_set_type()
The following functions have been added to handle Slapi_Mods structures.
slapi_entry2mods()
slapi_mods2entry()
slapi_mods_add()
slapi_mods_add_ldapmod()
slapi_mods_add_mod_values()
slapi_mods_add_modbvps()
slapi_mods_add_smod()
slapi_mods_add_string()
slapi_mods_done()
slapi_mods_dump()
slapi_mods_free()
slapi_mods_get_first_smod()
slapi_mods_get_next_mod()
slapi_mods_get_next_smod()
slapi_mods_get_num_mods()
slapi_mods_init()
slapi_mods_init_byref()
slapi_mods_init_passin()
slapi_mods_insert_after()
slapi_mods_insert_at()
slapi_mods_insert_before()
slapi_mods_insert_smod_at()
slapi_mods_insert_smod_before()
slapi_mods_iterator_backone()
slapi_mods_new()
slapi_mods_remove()
Object Extensions
Object extensions offer a new way of passing data through Directory Server from plug-in to plug-in. The following macros define extensible objects.
SLAPI_EXT_CONNECTION
SLAPI_EXT_OPERATION
SLAPI_EXT_ENTRY
SLAPI_EXT_MTNODE
The following new functions and associated constructor and destructor callbacks comprise the object extension interface.
slapi_extension_constructor_fnptr
slapi_extension_destructor_fnptr
slapi_get_object_extension()
slapi_register_object_extension()
slapi_set_object_extension()
Operations
slapi_op_get_type() and slapi_op_is_flag_set() have been added.
Parameter Block Arguments
The following parameter block arguments are new.
SLAPI_CLIENT_DNS
SLAPI_CONFIG_DIRECTORY
SLAPI_CONN_CERT
SLAPI_CONN_CLIENTNETADDR
SLAPI_CONN_IS_REPLICATION_SESSION
SLAPI_CONN_IS_SSL_SESSION
SLAPI_CONN_SERVERNETADDR
SLAPI_CONTROLS_ARG
SLAPI_DESTROY_CONTENT
SLAPI_IS_INTERNAL_OPERATION
SLAPI_IS_REPLICATED_OPERATION
SLAPI_ORIGINAL_TARGET
SLAPI_ORIGINAL_TARGET_DN
SLAPI_PLUGIN_ENTRY_FETCH_FUNC
SLAPI_PLUGIN_ENTRY_STORE_FUNC
SLAPI_PLUGIN_IDENTITY
SLAPI_PLUGIN_INTERNAL_POST_ADD_FN
SLAPI_PLUGIN_INTERNAL_POST_DELETE_FN
SLAPI_PLUGIN_INTERNAL_POST_MODIFY_FN
SLAPI_PLUGIN_INTERNAL_POST_MODRDN_FN
SLAPI_PLUGIN_INTERNAL_PRE_ADD_FN
SLAPI_PLUGIN_INTERNAL_PRE_DELETE_FN
SLAPI_PLUGIN_INTERNAL_PRE_MODIFY_FN
SLAPI_PLUGIN_INTERNAL_PRE_MODRDN_FN
SLAPI_PLUGIN_POSTSTART_FN
SLAPI_PLUGIN_PWD_STORAGE_SCHEME_CMP_FN
SLAPI_PLUGIN_PWD_STORAGE_SCHEME_DB_PWD
SLAPI_PLUGIN_PWD_STORAGE_SCHEME_DEC_FN
SLAPI_PLUGIN_PWD_STORAGE_SCHEME_ENC_FN
SLAPI_PLUGIN_PWD_STORAGE_SCHEME_NAME
SLAPI_PLUGIN_PWD_STORAGE_SCHEME_USER_PWD
SLAPI_RESULT_CODE
SLAPI_RESULT_MATCHED
SLAPI_RESULT_TEXT
Relative Distinguished Names (RDNs)
The following functions have been added to handle Slapi_RDN structures.
slapi_rdn_add()
slapi_rdn_compare()
slapi_rdn_contains()
slapi_rdn_contains_attr()
slapi_rdn_done()
slapi_rdn_free()
slapi_rdn_get_first()
slapi_rdn_get_index()
slapi_rdn_get_index_attr()
slapi_rdn_get_next()
slapi_rdn_get_nrdn()
slapi_rdn_get_num_components()
slapi_rdn_get_rdn()
slapi_rdn_init()
slapi_rdn_init_dn()
slapi_rdn_init_rdn()
slapi_rdn_init_sdn()
slapi_rdn_isempty()
slapi_rdn_new()
slapi_rdn_new_dn()
slapi_rdn_new_rdn()
slapi_rdn_new_sdn()
slapi_rdn_remove()
slapi_rdn_remove_attr()
slapi_rdn_remove_index()
slapi_rdn_set_dn()
slapi_rdn_set_rdn()
slapi_rdn_set_sdn()
slapi_sdn_add_rdn()
UTF8 Encoding
The following functions have been added to handle UTF8 encoding and decoding.
slapi_has8thBit()
slapi_UTF8CASECMP()
slapi_UTF8ISLOWER()
slapi_UTF8ISUPPER()
slapi_UTF8NCASECMP()
slapi_UTF8STRTOLOWER()
slapi_UTF8STRTOUPPER()
slapi_UTF8TOLOWER()
slapi_UTF8TOUPPER()
Values
The following functions have been added to handle Slapi_Value structures.
slapi_value_compare()
slapi_value_dup()
slapi_value_free()
slapi_value_get_berval()
slapi_value_get_int()
slapi_value_get_length()
slapi_value_get_long()
slapi_value_get_string()
slapi_value_get_uint()
slapi_value_get_ulong()
slapi_value_init()
slapi_value_init_berval()
slapi_value_init_string()
slapi_value_init_string_passin()
slapi_value_new()
slapi_value_new_berval()
slapi_value_new_string()
slapi_value_new_string_passin()
slapi_value_new_value()
slapi_value_set()
slapi_value_set_berval()
slapi_value_set_int()
slapi_value_set_string()
slapi_value_set_string_passin()
slapi_value_set_value()
slapi_valuearray_free()
Value Sets
The following functions have been added to handle Slapi_Valueset structures.
slapi_valueset_add_value()
slapi_valueset_count()
slapi_valueset_done()
slapi_valueset_find()
slapi_valueset_first_value()
slapi_valueset_free()
slapi_valueset_init()
slapi_valueset_new()
slapi_valueset_next_value()
slapi_valueset_set_from_smod()
slapi_valueset_set_valueset()
Virtual Attributes
The following functions have been added to handle virtual attributes.
slapi_entry_vattr_find()
slapi_vattr_attr_free()
slapi_vattr_attrs_free()
slapi_vattr_is_registered()
slapi_vattr_list_attrs()
slapi_vattr_values_free()
slapi_vattr_values_get_ex()