Chapter 3 Changes to the Plug-In API From Directory Server 4 to Directory Server 5.2
This chapter describes the changes to the plug-in API from the Directory Server 4 release to and including the Directory Server 5.2 release. If you maintain Directory Server plug-ins originally developed for such releases or for a previous release, upgrade the plug-ins to use the new and updated features.
For reference information, see Part II, Directory Server Plug-In API Reference.
Tip –
You can use Sun Services consultants to develop and to maintain your Directory Server plug-ins.
This chapter covers the following topics:
Deprecated and Changed Features From 4 to 5.2
This section addresses features deprecated or changed since Directory Server 4 was released up to and including Directory Server 5.2. Where possible, use the replacement functionality.
For information about a function, see Part II, Directory Server Plug-In API Reference.
Handling Deprecation (4 to 5.2)
SLAPI_DEPRECATED has been defined in slapi-plugin.h to highlight what features have been superseded. If you cannot change core plug-in code, you might decide to recompile after including slapi-plugin-compat4.h to access deprecated features in this release.
#include "slapi-plugin-compat4.h"
In general, you must at minimum recompile your plug-ins so they work with Directory Server 5. Where possible, replace deprecated code with new alternatives before recompiling and testing.
Plug-In Directive Changes (4 to 5.2)
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 Parameter Changes (4 to 5.2)
Many of the existing function parameters have become const to reflect that parameter values are not changed when reading information.
Data Type Changes (4 to 5.2)
Consider using opaque data types wherever possible. For information about data types, see Chapter 15, Data Type and Structure Reference.
Plug-In Type Changes (4 to 5.2)
The SLAPI_PLUGIN_DATABASE plug-in type (database) has been deprecated.
Access Control Changes (4 to 5.2)
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.
Attribute Handling Changes (4 to 5.2)
The following table shows deprecated functions and their replacements for handling attributes.
Table 3–1 Replacement Functions for Handling Attributes|
Deprecated Function |
Replacement Function |
|---|---|
|
slapi_attr_get_values() |
slapi_attr_get_bervals_copy() |
|
slapi_attr_get_oid() |
slapi_attr_get_oid_copy() |
|
slapi_compute_add_search_rewriter() |
slapi_compute_add_search_rewriter_ex() |
Control Handling Changes (4 to 5.2)
slapi_get_supported_controls() is not thread-safe. The function has been deprecated. Use slapi_get_supported_controls_copy() instead.
SLAPI_OPERATION_* identifiers have changed to unsigned long values.
Entry Handling Changes (4 to 5.2)
The following table shows deprecated functions and their replacements for handling entries.
Table 3–2 Replacement Functions for Handling Entries|
Deprecated Function |
Replacement Function |
|---|---|
|
slapi_entry_add_values() |
slapi_entry_add_values_sv() slapi_entry_add_valueset() |
|
slapi_entry_attr_hasvalue() |
slapi_entry_attr_has_syntax_value() |
|
slapi_entry_attr_merge() |
slapi_entry_attr_merge_sv() slapi_entry_merge_values_sv() |
|
slapi_entry_attr_replace() |
slapi_entry_attr_replace_sv() |
|
slapi_entry_delete_values() |
slapi_entry_delete_values_sv() |
Error Handling Changes (4 to 5.2)
slapi-plugin.h now includes ldap_msg.h, which lists unique error numbers used by Directory Server.
Functions for dealing with back ends that return int error codes can now also return SLAPI_FAIL_RETRY. The old values are also still used.
Directory Server now distinguishes between two results. SLAPI_BIND_FAIL indicates that the bind failed and the server prepared a result to send. SLAPI_BIND_ANONYMOUS indicates that the bind succeeded as an anonymous bind.
Extended Operations Function Changes (4 to 5.2)
slapi_get_supported_extended_ops() is not thread-safe. The function has been deprecated. Use slapi_get_supported_extended_ops_copy() instead.
Filter Handling Changes (4 to 5.2)
slapi_filter_get_type() has been deprecated. Use slapi_filter_get_attribute_type() instead. The replacement function works for all simple filter choices.
Internal Operation Changes (4 to 5.2)
The following table shows deprecated functions and their replacements for handling internal operations.
Table 3–3 Replacement Functions for Handling Internal Operations|
Deprecated Function |
Replacement Function |
|---|---|
|
slapi_add_entry_internal() |
slapi_add_internal_pb() |
|
slapi_add_internal() |
slapi_add_internal_pb() |
|
slapi_delete_internal() |
slapi_delete_internal_pb() |
|
slapi_modify_internal() |
slapi_modify_internal_pb() |
|
slapi_modrdn_internal() |
slapi_modrdn_internal_pb() |
|
slapi_search_internal() |
slapi_search_internal_pb() |
|
slapi_search_internal_callback() |
slapi_search_internal_callback_pb() |
Logging Function Changes (4 to 5.2)
The following table shows deprecated functions and their replacements for logging.
Table 3–4 Replacement Functions for Logging|
Deprecated Function |
Replacement Function |
|---|---|
|
slapi_log_error() |
slapi_log_error_ex() slapi_log_info_ex() slapi_log_warning_ex() |
|
slapi_is_loglevel_set() |
No replacement is available |
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 Argument Changes (4 to 5.2)
The following table shows deprecated parameter block arguments and their replacement arguments.
Table 3–5 Replacement Parameter Block Arguments|
Deprecated Argument |
Replacement Argument |
|---|---|
|
SLAPI_CHANGENUMBER |
No replacement is available |
|
SLAPI_CONN_AUTHTYPE |
SLAPI_CONN_AUTHMETHOD |
|
SLAPI_CONN_CLIENTIP |
SLAPI_CONN_CLIENTNETADDR |
|
SLAPI_CONN_SERVERIP |
SLAPI_CONN_SERVERNETADDR |
|
SLAPI_LOG_OPERATION |
No replacement is available |
|
SLAPI_PLUGIN_DB_ABANDON_FN SLAPI_PLUGIN_DB_ABORT_FN SLAPI_PLUGIN_DB_ADD_FN SLAPI_PLUGIN_DB_ARCHIVE2DB_FN SLAPI_PLUGIN_DB_BEGIN_FN SLAPI_PLUGIN_DB_BIND_FN SLAPI_PLUGIN_DB_COMMIT_FN SLAPI_PLUGIN_DB_COMPARE_FN SLAPI_PLUGIN_DB_CONFIG_FN SLAPI_PLUGIN_DB_DB2ARCHIVE_FN SLAPI_PLUGIN_DB_DB2INDEX_FN SLAPI_PLUGIN_DB_DB2LDIF_FN SLAPI_PLUGIN_DB_DELETE_FN SLAPI_PLUGIN_DB_ENTRY_FN SLAPI_PLUGIN_DB_ENTRY_RELEASE_FN SLAPI_PLUGIN_DB_FLUSH_FN SLAPI_PLUGIN_DB_FREE_RESULT_SET_FN SLAPI_PLUGIN_DB_LDIF2DB_FN SLAPI_PLUGIN_DB_MODIFY_FN SLAPI_PLUGIN_DB_MODRDN_FN SLAPI_PLUGIN_DB_NEXT_SEARCH_ENTRY_EXT_FN SLAPI_PLUGIN_DB_NEXT_SEARCH_ENTRY_FN SLAPI_PLUGIN_DB_NO_ACL SLAPI_PLUGIN_DB_REFERRAL_FN SLAPI_PLUGIN_DB_RESULT_FN SLAPI_PLUGIN_DB_SEARCH_FN SLAPI_PLUGIN_DB_SEQ_FN SLAPI_PLUGIN_DB_SIZE_FN SLAPI_PLUGIN_DB_TEST_FN SLAPI_PLUGIN_DB_UNBIND_FN |
No replacement, as the database plug-in type is deprecated |
|
SLAPI_REQUESTOR_ISUPDATEDN |
No replacement is available |
Password Handling Changes (4 to 5.2)
slapi_pw_find() has been deprecated. Use slapi_pw_find_valueset() instead.
SASL Bind Changes (4 to 5.2)
slapi_get_supported_saslmechanisms() has been deprecated. Use slapi_get_supported_saslmechanisms_copy() instead.
New Features From Directory Server 4 to 5.2
This section summarizes features that were added since the Directory Server 4 was released up to and including Directory Server 5. This section does not include features that are reserved for internal use.
For information about a function, see Chapter 16, Function Reference, Part I.
New Plug-In API Version 3 (4 to 5.2)
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 with SLAPI_PLUGIN_VERSION_03 or currently SLAPI_PLUGIN_CURRENT_VERSION.
New Plug-In Types (4 to 5.2)
New plug-in types have been added since the version 4 releases. For a list of supported plug-in types, refer to How Plug-Ins Interact With the Server.
New Plug-In Configuration Entries (4 to 5.2)
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.
New NSPR 4 API
The Netscape Portable Runtime (NSPR) API allows compliant applications to use system facilities. The system facilities include threads, thread synchronization, I/O, interval timing, atomic operations, and other low-level services. NSPR allows access to these facilities in a platform-independent manner.
For information about the version of NSPR used currently, refer to http://www.mozilla.org/projects/nspr/release-notes/.
New Attribute Handling Functions and Flags (4 to 5.2)
The following table shows new flags defined for use with existing functions for handling attributes.
Table 3–6 New Flags for Handling Attributes|
Function |
Flags Added |
|---|---|
|
slapi_attr_get_flags() |
SLAPI_ATTR_FLAG_COLLECTIVE SLAPI_ATTR_FLAG_NOUSERMOD SLAPI_ATTR_FLAG_OBSOLETE SLAPI_ATTR_FLAG_STD_ATTR |
|
slapi_attr_type_cmp() |
SLAPI_TYPE_CMP_BASE SLAPI_TYPE_CMP_EXACT SLAPI_TYPE_CMP_SUBTYPE |
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()
New Backend Handling Functions (4 to 5.2)
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()
New Control Handling Functions (4 to 5.2)
slapi_build_control() slapi_build_control_from_berval() slapi_dup_control()
New Opaque Data Structures (4 to 5.2)
The following data structures 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
New Distinguished Name Handling Functions (4 to 5.2)
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()
New Entry Handling Functions and Flags (4 to 5.2)
The slapi_str2entry() function contains the following new flags defined for handling entries:
SLAPI_STR2ENTRY_EXPAND_OBJECTCLASSES SLAPI_STR2ENTRY_IGNORE_STATE SLAPI_STR2ENTRY_INCLUDE_VERSION_STR SLAPI_STR2ENTRY_NOT_WELL_FORMED_LDIF SLAPI_STR2ENTRY_TOMBSTONE_CHECK
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()
New Filter Handling Functions (4 to 5.2)
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()
New Internal Operation Functions (4 to 5.2)
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 1, Before You Start Writing Plug-Ins to see how to use the updated interface.
New Memory Management Functions (4 to 5.2)
The following table shows functions that have been added to manage memory.
Table 3–7 New Functions for Managing Memory
New Modification Structure Functions (4 to 5.2)
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()
New Object Extensions (4 to 5.2)
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_ENTRY SLAPI_EXT_MTNODE SLAPI_EXT_OPERATION
The following new functions and associated constructor and destructor callbacks are part of the object extension interface:
slapi_extension_constructor_fnptr slapi_extension_destructor_fnptr slapi_get_object_extension() slapi_register_object_extension() slapi_set_object_extension()
New Operation Handling Functions (4 to 5.2)
slapi_op_get_type()
slapi_op_is_flag_set()
New Parameter Block Arguments (4 to 5.2)
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
New Relative Distinguished Name Handling Functions (4 to 5.2)
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()
New UTF8 Encoding Functions (4 to 5.2)
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()
New Value Handling Functions (4 to 5.2)
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()
New Value Set Handling Functions (4 to 5.2)
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()
New Virtual Attribute Functions (4 to 5.2)
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()
- © 2010, Oracle Corporation and/or its affiliates