Sun ONE Directory Server 5.2 Plug-In API Reference |
Chapter 1 Data Type and Structure Reference
This chapter covers data types and structures for use in plug-in functions. Table 1-1 summarizes the list of available data structures. Table 1-2 summarizes the list of callbacks.
berval
Represents binary data encoded using simplified Basic Encoding Rules (BER).
Use a berval structure when working with binary attribute values such as a JPEG or audio file.
Syntax
/* Defined in ldap.h, which is included by slapi-plugin.h */
#include "slapi-plugin.h"
struct berval {
unsigned long bv_len;
char * bv_val;
};Fields
This structure has the following fields.
Table 1-3    berval Fields
Field
Description
bv_len
Size of the encoded data.
bv_val
Encoded data itself.
computed_attr_context
An opaque structure representing information such as attribute type, current BER-encoded request and parameter block context for attributes that are computed.
Syntax
#include "slapi-plugin.h"
typedef struct _computed_attr_context computed_attr_context;Description
Before the server sends an entry to a client application, it determines whether any of the attributes are computed. If so, it generates those attributes and includes them in the entry.
As part of this process, the server creates a computed_attr_context structure to pass relevant information to functions generating the attribute values.
LDAPControl
Represents a client or server control associated with an LDAP operation as specified by LDAP v3.
Client and server controls may be used to extend the functionality of an LDAP operation.
Syntax
/* Defined in ldap.h, which is included by slapi-plugin.h */
#include "slapi-plugin.h"
typedef struct ldapcontrol {
char * ldctl_oid;
struct berval ldctl_value;
char ldctl_iscritical;
} LDAPControl, * PLDAPControl;Fields
This structure has the following fields.
LDAPMod
Represents a modification to an attribute in a directory entry.
Syntax
/* Defined in ldap.h, which is included by slapi-plugin.h */
#include "slapi-plugin.h"
typedef struct ldapmod {
int mod_op;
char * mod_type;
union {
char ** modv_strvals;
struct berval ** modv_bvals;
} mod_vals;
} LDAPMod;
#define mod_values mod_vals.modv_strvals
#define mod_bvalues mod_vals.modv_bvalsFields
This structure has the following fields.
Example
The following code excerpt sets up an LDAPMod to change an mail address.
mrFilterMatchFn
Specifies a filter matching callback function. The server calls this function when processing a search operation, once for each candidate that matches an extensible match search filter.
Syntax
#include "slapi-plugin.h"
typedef int (*mrFilterMatchFn) (void* filter, Slapi_Entry* entry,
Slapi_Attr* vals);
Parameters
The callback takes the following parameters.
Description
The server calls this filter matching function when processing an extensible match filter using a matching rule plug-in. An extensible match filter specifies either the OID of a matching rule, or an attribute type, or both, that indicates how matching entries are found. For example, a sound-alike matching rule could be implemented to find all entries that sound like a given value.
To handle the extensible match filter for a matching rule, implement both this callback and a filter factor that creates the filter structure, filter. The callback retrieves information about the filter from this structure, such as the attribute type and value, then compares this information with attribute types and values in the candidate entry.
Returns
The callback must return 0 if the filter matches, -1 if the filter does not match. On error, it may return an LDAP error code as specified in the Result Message section of RFC 2251, Lightweight Directory Access Protocol (v3).
plugin_referral_entry_callback
Specifies a referral callback function. The server calls this function when the internal search implemented to trigger this callback finds LDAP v3 referrals.
Syntax
#include "slapi-plugin.h"
typedef int (*plugin_referral_entry_callback)(char * referral,
void *callback_data);Parameters
The callback takes the following parameters.
Description
Pass this as the prec parameter of slapi_search_internal_callback_pb(). Each time the internal search finds a referral entry, it calls this function.
Returns
The server does not use the callback return value.
plugin_result_callback
Specifies a search result callback function. The server calls this function when the internal search implemented to trigger this callback returns an LDAP result.
Syntax
#include "slapi-plugin.h"
typedef void (*plugin_result_callback)(int rc, void *callback_data);Parameters
The callback takes the following parameters.
Description
Pass this as the prc parameter of slapi_search_internal_callback_pb(). The server calls this function once for each search operation, unless the search is abandoned, in which case the function is not called.
plugin_search_entry_callback
Specifies an entry callback function. The server calls this function when the internal search implemented to trigger this callback finds an LDAP entry.
Syntax
#include "slapi-plugin.h"
typedef int (*plugin_search_entry_callback)(Slapi_Entry *e,
void *callback_data);Parameters
The callback takes the following parameters.
Description
Pass this as the psec parameter of slapi_search_internal_callback_pb(). Each time the internal search finds a referral entry, it calls this function.
Returns
The callback must return 0 to continue the search, -1 to interrupt the search.
roles_get_scope_fn_type
Specifies a callback function to determine the role of a scope. The plug-in triggers this callback using slapi_role_get_scope().
Syntax
#include "slapi-plugin.h"
typedef int (*roles_get_scope_fn_type)(Slapi_Entry *role_entry,
Slapi_DN ***scope, int *nb_scope);Parameters
The callback takes the following parameters.
Description
This callback determines the role of a scope identified by role_entry. Register the callback with the server using slapi_register_role_get_scope().
Returns
The callback returns 0 if successful, -1 otherwise.
send_ldap_referral_fn_ptr_t
Specifies a callback triggered before the server sends a result to the client.
Syntax
#include "slapi-plugin.h"
typedef int (*send_ldap_referral_fn_ptr_t)( Slapi_PBlock *pb,
Slapi_Entry *e, struct berval **refs, struct berval ***urls );Parameters
The callback takes the following parameters.
Description
This callback lets you modify referrals returned to the client. Register the callback with the server using slapi_search_internal_callback_pb().
Returns
The callback should return 0 if successful, -1 otherwise.
send_ldap_result_fn_ptr_t
Specifies a callback triggered before the server sends a result to the client.
Syntax
#include "slapi-plugin.h"
typedef void (*send_ldap_result_fn_ptr_t)( Slapi_PBlock *pb,
int err, char *matched, char *text, int nentries,
struct berval **urls );Parameters
The callback takes the following parameters.
Description
This callback lets you modify the result returned to the client. Register the callback with the server using slapi_search_internal_callback_pb().
Returns
The callback should return 0 if successful, -1 otherwise.
send_ldap_search_entry_fn_ptr_t
Specifies a callback triggered before the server sends an entry returned by a search to the client.
Syntax
#include "slapi-plugin.h"
typedef int (*send_ldap_search_entry_fn_ptr_t)( Slapi_PBlock *pb,
Slapi_Entry *e, LDAPControl **ectrls, char **attrs,
int attrsonly );Parameters
The callback takes the following parameters.
Description
This callback lets you modify what is returned to the client. Register the callback with the server using slapi_search_internal_callback_pb().
Returns
The callback should return 0 if successful, -1 otherwise.
Slapi_Attr
Opaque structure representing a directory entry attribute.
Syntax
#include "slapi-plugin.h"
typedef struct slapi_attr Slapi_Attr;See Also
Slapi_Entry
Slapi_Backend
Opaque structure representing a server backend.
Syntax
#include "slapi-plugin.h"
typedef struct backend Slapi_Backend;See Also
"Handling Slapi_Backend Structures," on page 48
Slapi_ComponentId
Opaque structure representing a component identifier used by the server to identify the plug-in when processing internal operations.
Syntax
#include "slapi-plugin.h"
typedef struct slapi_componentid Slapi_ComponentId;Example
The following code excerpt sets a plug-in component identifier used during an internal search.
slapi_compute_callback_t
Specifies a function to determine which function should be called to provide a value for a computed attribute.
Syntax
typedef int (*slapi_compute_callback_t)(computed_attr_context *c,
char* type,Slapi_Entry *e,slapi_compute_output_t outputfn);Parameters
The callback takes the following parameters.
Description
This callback selects the function that provides a computed value for an attribute of type type on an entry e, given context c. The server calls this function to get a a function for calculating attribute values before returning the entry e to the client having requested the operation.
This function is registered with the server using slapi_compute_add_evaluator() in the plug-in initialization function.
Returns
This function should return 0 on success. It should return -1 if does not handle the attribute type passed in type. Otherwise, it should return an LDAP error code.
slapi_compute_output_t
Specifies a callback function to determine the value of a computed attribute.
Syntax
typedef int (*slapi_compute_output_t)(computed_attr_context *c,
Slapi_Attr *a , Slapi_Entry *e);Parameters
The callback takes the following parameters.
Description
This callback provides a computed value for attribute a of entry e, given context c. The slapi_compute_callback_t function you register using slapi_compute_add_evaluator() calls this function to compute a value for a before returning the entry e to the server.
Returns
This function should return 0 on success. It should return -1 if does not handle the attribute type passed in a. Otherwise, it should return an LDAP error code.
Slapi_CondVar
Opaque structure representing a conditional variable used by the plug-in to handle thread synchronization.
Syntax
#include "slapi-plugin.h"
typedef struct slapi_condvar Slapi_CondVar;See Also
slapi_destroy_condvar()
slapi_notify_condvar()
slapi_new_condvar()
slapi_wait_condvar()
Slapi_Connection
Opaque structure representing a connection to the server.
Syntax
#include "slapi-plugin.h"
typedef struct conn Slapi_Connection;Slapi_DN
Opaque structure representing a Distinguished Name (DN). The structure retains the original DN and can also hold a normalized version after slapi_sdn_get_ndn() is called.
Syntax
#include "slapi-plugin.h"
typedef struct slapi_dn Slapi_DN;See Also
"Handling DN Strings," on page 39 and "Handling Slapi_DN Structures," on page 49
Slapi_Entry
Opaque structure representing a directory entry.
Syntax
#include "slapi-plugin.h"
typedef struct slapi_entry Slapi_Entry;See Also
Slapi_Attr
"Handling Entries," on page 39
slapi_extension_constructor_fnptr
Specifies a callback function for an object extension.
Syntax
#include "slapi-plugin.h"
typedef void *(*slapi_extension_constructor_fnptr)
(void *object, void *parent);Parameters
The callback takes the following parameters.
Table 1-16    slapi_extension_constructor_fnptr Parameters
Parameter
Description
object
Extended object
parent
Parent object for the extension
Description
This callback registers an object extension that can be retrieved using slapi_get_object_extension().
Ensure that this callback only creates the object extension if it does not already exist.
The callback is registered with the server using slapi_register_object_extension() as part of the actual plug-in initialization function.
Returns
This callback returns a pointer to the extension. Otherwise it returns NULL.
slapi_extension_destructor_fnptr
Specifies a callback function to free memory allocated for an object extension.
Syntax
#include "slapi-plugin.h"
typedef void (*slapi_extension_destructor_fnptr)(void *extension,
void *object, void *parent);Parameters
The callback takes the following parameters.
Table 1-17    slapi_extension_destructor_fnptr Parameters
Parameter
Description
extension
Object extension
object
Extended object
parent
Parent for the extension
Description
This callback releases memory allocated for an object extension. The function is registered with the server using slapi_register_object_extension() in the plug-in initialization function.
Slapi_Filter
Opaque structure representing a search filter.
Syntax
#include "slapi-plugin.h"
typedef struct slapi_filter Slapi_Filter;See Also
"Handling Filters," on page 42
Slapi_MatchingRuleEntry
Opaque structure representing an LDAP v3 matching rule handled by the plug-in.
Syntax
#include "slapi-plugin.h"
typedef struct slapi_matchingRuleEntry Slapi_MatchingRuleEntry;See Also
"Handling Matching Rules," on page 44
Slapi_Mod
Opaque structure representing a modification of a directory entry attribute.
Parameter blocks use LDAPMod structures rather than Slapi_Mod structures. The latter type is provided as a convenience for plug-ins dealing extensively with modifications.
Syntax
#include "slapi-plugin.h"
typedef struct slapi_mod Slapi_Mod;See Also
LDAPMod
"Handling Modification Structures," on page 44
Slapi_Mods
Opaque structure representing a set of modifications to a directory entry.
Parameter blocks use arrays of LDAPMod structures rather than Slapi_Mods structures. The latter type is provided as a convenience for plug-ins dealing extensively with modifications.
Syntax
#include "slapi-plugin.h"
typedef struct slapi_mods Slapi_Mods;See Also
LDAPMod
"Handling Modification Structures," on page 44
Slapi_Mutex
Opaque structure representing a mutex lock used by the plug-in.
Syntax
#include "slapi-plugin.h"
typedef struct slapi_mutex Slapi_Mutex;See Also
slapi_destroy_mutex()
slapi_lock_mutex()
slapi_new_mutex()
slapi_unlock_mutex()
Slapi_Operation
Opaque structure representing a pending operation from an LDAP client.
The structure records, among other data, the type of operation requested.
Syntax
#include "slapi-plugin.h"
typedef struct op Slapi_Operation;See Also
slapi_op_abandoned(), slapi_op_get_type()
Slapi_PBlock
Opaque structure representing, called a parameter block, containing name-value pairs updated in the context of a server operation.
Syntax
#include "slapi-plugin.h"
typedef struct slapi_pblock Slapi_PBlock;Description
For most types of plug-in functions, the server passes in a parameter block (Slapi_PBlock) including data relevant to the operation being processed. Access the data using slapi_pblock_get().
Plug-in initialization functions register at least the plug-in API version, plug-in descriptions, and other plug-in functions using slapi_pblock_set().
The specific parameters available in a Slapi_PBlock structure depend on the type of plug-in function and the context of the LDAP operation. Refer to the "Parameter Block Reference" for details on the name-value pairs available to specific types of plug-in functions.
See Also
"Accessing and Modifying Parameter Blocks," on page 35
For examples of Slapi_PBlock use, refer to the sample plug-ins under ServerRoot/plugins/slapd/slapi/examples/.
Slapi_PluginDesc
Represents a plug-in description you provide to identify your plug-in.
The plug-in initialization function must register this information with the server.
Syntax
#include "slapi-plugin.h"
typedef struct slapi_plugindesc {
char * spd_id;
char * spd_vendor;
char * spd_version;
char * spd_description;
} Slapi_PluginDesc;Fields
This structure has the following fields.
See Also
For examples of Slapi_PluginDesc use, refer to the sample plug-ins under ServerRoot/plugins/slapd/slapi/examples/.
slapi_plugin_init_fnptr
Specifies a callback function for registering other plug-ins.
Syntax
#include "slapi-plugin.h"
typedef int (*slapi_plugin_init_fnptr)( Slapi_PBlock *pb );Parameters
The callback takes the following parameter.
Table 1-19    slapi_plugin_init_fnptr Parameter
Parameter
Description
pb
Parameter block passed to the initialization function.
Description
This callback mimics a plug-in initialization function, permitting one plug-in to register other plug-ins. The function is registered with the server using slapi_register_plugin() as part of the actual plug-in initialization function.
Returns
This callback returns 0 on success. Otherwise, it returns -1.
See Also
For examples of plug-in initialization functions, refer to the sample plug-ins under ServerRoot/plugins/slapd/slapi/examples/.
Slapi_RDN
Opaque structure representing a Relative Distinguished Name (RDN), the part of the DN that differentiates the entry from other entries having the same parent.
Syntax
#include "slapi-plugin.h"
typedef struct slapi_rdn Slapi_RDN;See Also
"Handling Slapi_RDN Structures," on page 51
Slapi_Value
Opaque structure representing an individual attribute value.
Use Slapi_ValueSet instead when handling all the values of an attribute at once.
Syntax
#include "slapi-plugin.h"
typedef struct slapi_value Slapi_Value;See Also
"Handling Slapi_Value Structures," on page 52
Slapi_ValueSet
Opaque structure representing the set of values of an attribute.
Use Slapi_Value instead when handling an individual attribute value.
Syntax
#include "slapi-plugin.h"
typedef struct slapi_value_set Slapi_ValueSet;See Also
"Handling Slapi_ValueSet Structures," on page 53
vattr_type_thang
Opaque structure representing both real and virtual attributes of an entry.
Syntax
#include "slapi-plugin.h"
typedef struct _vattr_type_thang vattr_type_thang;See Also