This chapter covers data types and structures for use in plug-in functions. Table 15–1 summarizes the list of available data structures. Table 15–2 summarizes the list of callbacks.
Data Structure or Callback |
Short Description |
---|---|
Binary data encoded using Basic Encoding Rules |
|
Information for use when handling computed attributes |
|
LDAP v3 control associated with an LDAP operation |
|
Set of modifications to a directory entry attribute |
|
Directory entry attribute |
|
Server backend |
|
Server assigned identifier, used for internal operations |
|
Condition variable for thread synchronization |
|
Client connection |
|
Distinguished Name |
|
Directory entry |
|
Search filter |
|
Matching rule handled by the plug-in |
|
A modification to an individual attribute |
|
Set of modifications to a directory entry |
|
Mutex for thread synchronization |
|
Pending LDAP operation |
|
Parameter block containing LDAP operation data |
|
Plug-in description that you provide |
|
Relative Distinguished Name |
|
Individual attribute value |
|
Set of values of an attribute |
|
Attribute that may be virtual |
Table 15–2 Quick Reference to Callbacks
Data Structure or Callback |
Short Description |
---|---|
Handles an extensible match filter |
|
Handles referrals found by internal search |
|
Handles results sent after internal search |
|
Handles entries found by internal search |
|
Determines scope of a role |
|
Modifies referrals before sending them to a client |
|
Modifies a result before sending it to a client |
|
Modifies an entry before sending it to a client |
|
Handles a computed attribute |
|
Calculates a computed attribute |
|
Handles object extension creation |
|
Handles object extension destruction |
|
Handles recursive plug-in registration |
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.
/* Defined in ldap.h, which is included by slapi-plugin.h */ #include "slapi-plugin.h" struct berval { unsigned long bv_len; char * bv_val; };
This structure has the following fields.
Table 15–3 berval Fields
Field |
Description |
---|---|
bv_len |
Size of the encoded data. |
bv_val |
Encoded data itself. |
An opaque structure representing information such as attribute type, current BER-encoded request and parameter block context for attributes that are computed.
#include "slapi-plugin.h" typedef struct _computed_attr_context computed_attr_context;
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.
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.
/* 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;
This structure has the following fields.
Table 15–4 LDAPControl Fields
Field |
Description |
---|---|
ldctl_oid |
Object identifier (OID) for the control. |
ldctl_value |
berval structure containing the value used by the control for the operation. |
ldctl_iscritical |
LDAP_OPT_ON indicates the control is critical to the operation. If the control is critical to the operation but not supported, the server returns LDAP_UNAVAILABLE_CRITICAL_EXTENSION. LDAP_OPT_OFF indicates the control is not critical. |
Represents a modification to an attribute in a directory entry.
/* 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_bvals
This structure has the following fields.
Table 15–5 LDAPMod Fields
Field |
Description |
---|---|
mod_op |
Operation to perform and data type of attribute values. The mod_op field takes the following values specifying the operation to perform.
|
mod_type |
Attribute type to modify. |
mod_values |
Pointer to NULL terminated array of string values for the attribute. |
mod_bvalues |
Pointer to NULL terminated array of berval structures for the attribute. |
Example 15–1 sets up an LDAPMod to change an mail address.
#include "slapi-plugin.h" /* Declare the appropriate structures. */ LDAPMod mod_attr; /* Attribute to modify */ LDAPMod * mods[2]; /* Array of modifications */ char * mail_vals[] = /* New mail address */ {"quentin@example.com", NULL}; /* Set up the LDAPMod structure used to modify the entry. */ mod_attr.mod_type = "mail"; mod_attr.mod_op = LDAP_MOD_REPLACE; mod_attr.mod_values = mail_vals; /* "quentin@example.com" */ mods[0] = &mod_attr; mods[1] = NULL; /* Modify the entry using slapi_modify_internal_set_pb()... */
Example 15–2 optionally adds additional modifications to those present in the parameter block. This code might be part of a pre-operation modify plug-in function, for example.
#include "slapi-plugin.h" /* * Set up an LDAPMod array, modify_mods, of additional modifications. */ if (modify_mods != NULL) { LDAPMod ** mods; Slapi_Mods smods; int i; slapi_pblock_get(pb, SLAPI_MODIFY_MODS, &mods); slapi_mods_init_passin(&smods, mods); for (i = 0; modify_mods[i] != NULL; i++) { /* Do not copy mods. */ slapi_mods_add_ldapmod(&smods, modify_mods[i]); } mods = slapi_mods_get_ldapmods_passout(&smods); slapi_pblock_set(pb, SLAPI_MODIFY_MODS, mods); slapi_mods_done(&smods); /* Release container only. Content is still pointed to by mods. */ slapi_ch_free((void **)&modify_mods); }
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.
#include "slapi-plugin.h" typedef int (*mrFilterMatchFn) (void* filter, Slapi_Entry* entry, Slapi_Attr* vals);
The callback takes the following parameters.
Table 15–6 mrFilterMatchFn Parameters
Parameter |
Description |
---|---|
filter |
Filter created by your filter factory function. |
entry |
Slapi_Entry representing the candidate entry checked by the server. |
vals |
Slapi_Attr representing the first attribute in the entry. Call slapi_entry_next_attr() to iterate through the rest of the attributes. |
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.
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 4511, Lightweight Directory Access Protocol (v3).
Specifies a referral callback function. The server calls this function when the internal search implemented to trigger this callback finds LDAP v3 referrals.
#include "slapi-plugin.h" typedef int (*plugin_referral_entry_callback)(char * referral, void *callback_data);
The callback takes the following parameters.
Table 15–7 plugin_referral_entry_callback Parameters
Parameter |
Description |
---|---|
referral |
URL of a reference found by the search. |
callback_data |
Pointer passed to the internal search operation. Use this to pass your own data between the callback function and the body of the plug-in. |
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.
The server does not use the callback return value.
Specifies a search result callback function. The server calls this function when the internal search implemented to trigger this callback returns an LDAP result.
#include "slapi-plugin.h" typedef void (*plugin_result_callback)(int rc, void *callback_data);
The callback takes the following parameters.
Table 15–8 plugin_result_callback Parameters
Parameter |
Description |
---|---|
rc |
LDAP result code returned by the search. |
callback_data |
Pointer passed to the internal search operation. Use this to pass your own data between the callback function and the body of the plug-in. |
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.
Specifies an entry callback function. The server calls this function when the internal search implemented to trigger this callback finds an LDAP entry.
#include "slapi-plugin.h" typedef int (*plugin_search_entry_callback)(Slapi_Entry *e, void *callback_data);
The callback takes the following parameters.
Table 15–9 plugin_search_entry_callback Parameters
Parameter |
Description |
---|---|
e |
Pointer to the entry found by the search. |
callback_data |
Pointer passed to the internal search operation. Use this to pass your own data between the callback function and the body of the plug-in. |
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.
The callback must return 0 to continue the search, -1 to interrupt the search.
Specifies a callback function to determine the role of a scope. The plug-in triggers this callback using slapi_role_get_scope().
#include "slapi-plugin.h" typedef int (*roles_get_scope_fn_type)(Slapi_Entry *role_entry, Slapi_DN ***scope, int *nb_scope);
The callback takes the following parameters.
Table 15–10 roles_get_scope_fn_type Parameters
Parameter |
Description |
---|---|
role_entry |
Entry defining the role |
scope |
Set this to the Distinguished Name of the entry at the base of the scope |
nb_scope |
Set this to a value such as LDAP_SCOPE_BASE, LDAP_SCOPE_ONELEVEL , or LDAP_SCOPE_SUBTREE |
This callback determines the role of a scope identified by role_entry. Register the callback with the server using slapi_register_role_get_scope() .
The callback returns 0 if successful, -1 otherwise.
Specifies a callback triggered before the server sends a result to the client.
#include "slapi-plugin.h" typedef int (*send_ldap_referral_fn_ptr_t)( Slapi_PBlock *pb, Slapi_Entry *e, struct berval **refs, struct berval ***urls );
The callback takes the following parameters.
Table 15–11 send_ldap_referral_fn_ptr_t Parameters
Parameter |
Description |
---|---|
pb |
Current parameter block for the operation. |
e |
Current entry for the operation. |
refs |
Pointer to the NULL terminated array of berval structures containing the LDAP v3 referrals (search result references) found in the entry. |
urls |
Pointer to the array of berval structures used to collect LDAP referrals for LDAP v2 clients. |
This callback lets you modify referrals returned to the client. Register the callback with the server using slapi_search_internal_callback_pb() .
The callback should return 0 if successful, -1 otherwise.
Specifies a callback triggered before the server sends a result to the client.
#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 );
The callback takes the following parameters.
Table 15–12 send_ldap_result_fn_ptr_t Parameters
Parameter |
Description |
---|---|
pb |
Current parameter block for the operation. |
err |
Result code. |
matched |
When sending back an LDAP_NO_SUCH_OBJECT result code, use this argument to specify the portion of the target DN that could be matched. (Pass NULL in other situations.) |
text |
Error message that you want sent back to the client. (Pass NULL if you do not want an error message sent back.) |
nentries |
When sending back the result code for an LDAP search operation, use this argument to specify the number of matching entries found. |
urls |
When sending back an LDAP_PARTIAL_RESULTS result code to an LDAP v2 client or an LDAP_REFERRAL result code to an LDAP v3 client, use this argument to specify the array of berval structures containing the referral URLs. (Pass NULL in other situations.) |
This callback lets you modify the result returned to the client. Register the callback with the server using slapi_search_internal_callback_pb() .
The callback should return 0 if successful, -1 otherwise.
Specifies a callback triggered before the server sends an entry returned by a search to the client.
#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 );
The callback takes the following parameters.
Table 15–13 send_ldap_search_entry_fn_ptr_t Parameters
This callback lets you modify what is returned to the client. Register the callback with the server using slapi_search_internal_callback_pb() .
The callback should return 0 if successful, -1 otherwise.
Opaque structure representing a directory entry attribute.
#include "slapi-plugin.h" typedef struct slapi_attr Slapi_Attr;
Opaque structure representing a server backend.
#include "slapi-plugin.h" typedef struct backend Slapi_Backend;
Opaque structure representing a component identifier used by the server to identify the plug-in when processing internal operations.
#include "slapi-plugin.h" typedef struct slapi_componentid Slapi_ComponentId;
The following code excerpt sets a plug-in component identifier used during an internal search.
#include "slapi-plugin.h" /* Declare the identifier as global to the plug-in. */ static Slapi_ComponentId * postop_id; /* Assign a value as part of plug-in initialization. */ int testpostop_init(Slapi_PBlock * pb) { int rc = 0; /* Register description, other functions, and so forth. */ rc |= slapi_pblock_set( pb, SLAPI_PLUGIN_START_FN, (void *) testpostop_set_log ); /* Assign a value to the identifier. */ rc |= slapi_pblock_get(pb, SLAPI_PLUGIN_IDENTITY, &postop_id); return (rc); } /* The server uses the identifier when processing * internal operations, such as an internal search. */ int testpostop_set_log(Slapi_PBlock * pb) { Slapi_DN * confdn = NULL; /* DN for configuration entry */ Slapi_Entry * config = NULL; /* Configuration entry */ int rc = 0; confdn = slapi_sdn_new_dn_byval("cn=config"); rc |= slapi_search_internal_get_entry(confdn, NULL, &config, postop_id); /* Use the results of the search. */ return(rc); }
Specifies a function to determine which function should be called to provide a value for a computed attribute.
typedef int (*slapi_compute_callback_t)(computed_attr_context *c, char* type,Slapi_Entry *e,slapi_compute_output_t outputfn);
The callback takes the following parameters.
Table 15–14 slapi_compute_callback_t Parameters
Field |
Description |
---|---|
c |
Context of the callback. |
type |
Attribute type for which the outputfn computes values. |
e |
Entry including computed attributes, returned to client after this callback returns. |
outputfn |
Callback to compute the attribute value. |
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.
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.
Specifies a callback function to determine the value of a computed attribute.
typedef int (*slapi_compute_output_t)(computed_attr_context *c, Slapi_Attr *a , Slapi_Entry *e);
The callback takes the following parameters.
Table 15–15 slapi_compute_output_t Parameters
Parameter |
Description |
---|---|
c |
Context of the callback. |
a |
Attribute for which the callback computes values. |
e |
Entry including computed attributes, returned to client after this callback returns. |
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.
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.
Opaque structure representing a condition variable used by the plug-in to handle thread synchronization.
#include "slapi-plugin.h" typedef struct slapi_condvar Slapi_CondVar;
Opaque structure representing a connection to the server.
#include "slapi-plugin.h" typedef struct conn Slapi_Connection;
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.
#include "slapi-plugin.h" typedef struct slapi_dn Slapi_DN;
Opaque structure representing a directory entry.
#include "slapi-plugin.h" typedef struct slapi_entry Slapi_Entry;
Specifies a callback function for an object extension.
#include "slapi-plugin.h" typedef void *(*slapi_extension_constructor_fnptr) (void *object, void *parent);
The callback takes the following parameters.
Table 15–16 slapi_extension_constructor_fnptr Parameters
Parameter |
Description |
---|---|
object |
Extended object |
parent |
Parent object for the extension |
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.
This callback returns a pointer to the extension. Otherwise it returns NULL.
Specifies a callback function to free memory allocated for an object extension.
#include "slapi-plugin.h" typedef void (*slapi_extension_destructor_fnptr)(void *extension, void *object, void *parent);
The callback takes the following parameters.
Table 15–17 slapi_extension_destructor_fnptr Parameters
Parameter |
Description |
---|---|
extension |
Object extension |
object |
Extended object |
parent |
Parent for the extension |
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.
Opaque structure representing a search filter.
#include "slapi-plugin.h" typedef struct slapi_filter Slapi_Filter;
Opaque structure representing an LDAP v3 matching rule handled by the plug-in.
#include "slapi-plugin.h" typedef struct slapi_matchingRuleEntry Slapi_MatchingRuleEntry;
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.
#include "slapi-plugin.h" typedef struct slapi_mod Slapi_Mod;
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.
#include "slapi-plugin.h" typedef struct slapi_mods Slapi_Mods;
Opaque structure representing a mutex lock used by the plug-in.
#include "slapi-plugin.h" typedef struct slapi_mutex Slapi_Mutex;
Opaque structure representing a pending operation from an LDAP client.
The structure records, among other data, the type of operation requested.
#include "slapi-plugin.h" typedef struct op Slapi_Operation;
Opaque structure representing, called a parameter block, containing name-value pairs updated in the context of a server operation.
#include "slapi-plugin.h" typedef struct slapi_pblock Slapi_PBlock;
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,” on page 335 for details on the name-value pairs available to specific types of plug-in functions.
Chapter 15, Data Type and Structure Reference
For examples of Slapi_PBlock use, refer to the sample plug-ins under $INSTALL_DIR/examples/.
Represents a plug-in description you provide to identify your plug-in.
The plug-in initialization function must register this information with the server.
#include "slapi-plugin.h" typedef struct slapi_plugindesc { char * spd_id; char * spd_vendor; char * spd_version; char * spd_description; } Slapi_PluginDesc;
This structure has the following fields.
Table 15–18 Slapi_PluginDesc Fields
Field |
Description |
---|---|
spd_id |
Unique (server wide) identifier for the plug-in. |
spd_vendor |
Name of the vendor supplying the plug-in such as Sun Microsystems, Inc. |
spd_version |
Plug-in revision number such as 5.2, not to be confused with SLAPI_PLUGIN_VERSION, which specifies the plug-in API version supported by the plug-in. |
spd_description |
Short description of the plug-in such as Sample post-operation plug-in . |
For examples of Slapi_PluginDesc use, refer to the sample plug-ins under $INSTALL_DIR/examples/.
Specifies a callback function for registering other plug-ins.
#include "slapi-plugin.h" typedef int (*slapi_plugin_init_fnptr)( Slapi_PBlock *pb );
The callback takes the following parameter.
Table 15–19 slapi_plugin_init_fnptr Parameter
Parameter |
Description |
---|---|
pb |
Parameter block passed to the initialization function. |
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.
This callback returns 0 on success. Otherwise, it returns -1.
For examples of plug-in initialization functions, refer to the sample plug-ins under $INSTALL_DIR/examples/.
Opaque structure representing a Relative Distinguished Name (RDN), the part of the DN that differentiates the entry from other entries having the same parent.
#include "slapi-plugin.h" typedef struct slapi_rdn Slapi_RDN;
Opaque structure representing an individual attribute value.
Use Slapi_ValueSet instead when handling all the values of an attribute at once.
#include "slapi-plugin.h" typedef struct slapi_value Slapi_Value;
Opaque structure representing the set of values of an attribute.
Use Slapi_Value instead when handling an individual attribute value.
#include "slapi-plugin.h" typedef struct slapi_value_set Slapi_ValueSet;
Opaque structure representing both real and virtual attributes of an entry.
#include "slapi-plugin.h" typedef struct _vattr_type_thang vattr_type_thang;