|
| Sun ONE Directory Server 5.2 Plug-In API Programming Guide |
This chapter covers changes to the plug-in API since the 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
We strongly recommend you work closely with Sun Professional Services consultants to develop and to maintain your Directory Server plug-ins.
Deprecated and Changed Features
This section lists features deprecated since the 4.x releases. Where possible, we recommend replacement functionality.
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 Sun ONE Directory Server Plug-In API Reference for information on data types available.
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.
Refer to the Sun ONE Directory Server Plug-In API Reference for descriptions of the replacement functions.
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.
Refer to the Sun ONE Directory Server Plug-In API Reference for descriptions of the replacement functions.
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 returning 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.
Refer to the Sun ONE Directory Server Plug-In API Reference for descriptions of the replacement functions.
Logging
Table 2-4 lists deprecated and replacement functions for logging.
Refer to "Getting Started With Directory Server Plug-Ins" 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
slapi_pw_find() has been deprecated. Use slapi_pw_find_valueset() instead.
SASL Binds
slapi_get_supported_saslmechanisms() is not thread-safe and has been deprecated. Use slapi_get_supported_saslmechanisms_copy() instead.
New Features
This section summarizes features added since the previous release. It does not include features reserved for internal use.
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
A variety of new plug-in types have been created, many for internal use. Plug-in types not reserved for internal use are supported. If your preferred plug-in type lacks documentation, do not hesitate to offer your feedback through the Send Comments link at http://docs.sun.com/.
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/nspr412.html
Attributes
Table 2-6 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()
Refer to the Sun ONE Directory Server Plug-In API Reference for descriptions.
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()
Refer to the Sun ONE Directory Server Plug-In API Reference for descriptions.
Controls
The following functions have been added.
slapi_build_control()
slapi_build_control_from_berval()
slapi_dup_control()
Refer to the Sun ONE Directory Server Plug-In API Reference for descriptions.
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
Refer to the Sun ONE Directory Server Plug-In API Reference for descriptions.
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()
Refer to the Sun ONE Directory Server Plug-In API Reference for descriptions.
Entries
Table 2-7 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()
Refer to the Sun ONE Directory Server Plug-In API Reference for descriptions.
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()
Refer to the Sun ONE Directory Server Plug-In API Reference for descriptions.
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 "Performing Internal Operations" for a demonstration of how to use the updated interface.
Memory Management
Table 2-8 lists new functions that have been added to manage memory.
Refer to the Sun ONE Directory Server Plug-In API Reference for descriptions.
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()
Refer to the Sun ONE Directory Server Plug-In API Reference for descriptions.
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()
Refer to the Sun ONE Directory Server Plug-In API Reference for descriptions.
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
Refer to the Sun ONE Directory Server Plug-In API Reference for descriptions.
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()
Refer to the Sun ONE Directory Server Plug-In API Reference for descriptions.
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()
Refer to the Sun ONE Directory Server Plug-In API Reference for descriptions.
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()
Refer to the Sun ONE Directory Server Plug-In API Reference for descriptions.
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()
Refer to the Sun ONE Directory Server Plug-In API Reference for descriptions.
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()
Refer to the Sun ONE Directory Server Plug-In API Reference for descriptions.