Oracle® Fusion Middleware Developer's Guide for Oracle Directory Server Enterprise Edition 11g Release 1 (11.1.1.7.0) Part Number E28970-01 |
|
|
PDF · Mobi · ePub |
This chapter covers data types and structures for use in plug-in functions. Table 14-1 summarizes the list of available data structures. Table 14-2 summarizes the list of callbacks.
Table 14-1 Quick Reference to Data Structures
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 14-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 |
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.
/* Defined in ldap.h, which is included by slapi-plugin.h */ #include "slapi-plugin.h" struct berval { unsigned long bv_len; char * bv_val; };
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.
#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.
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.
/* 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 14-4 LDAPControl
Fields
Field | Description |
---|---|
|
Object identifier (OID) for the control. |
|
|
|
|
LDAPMod
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 14-5 LDAPMod
Fields
Field | Description |
---|---|
|
Operation to perform and data type of attribute values. The
|
|
Attribute type to modify. |
|
Pointer to |
|
Pointer to |
Example 14-1 sets up an LDAPMod
to change an mail address.
Example 14-1 Preparing Modifications to an Entry
#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 14-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.
Example 14-2 Adding Further Modifications
#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); }
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.
#include "slapi-plugin.h" typedef int (*mrFilterMatchFn) (void* filter, Slapi_Entry* entry, Slapi_Attr* vals);
The callback takes the following parameters.
Table 14-6 mrFilterMatchFn
Parameters
Parameter | Description |
---|---|
|
Filter created by your filter factory function. |
|
|
|
Call |
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).
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.
#include "slapi-plugin.h" typedef int (*plugin_referral_entry_callback)(char * referral, void *callback_data);
The callback takes the following parameters.
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.
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.
#include "slapi-plugin.h" typedef void (*plugin_result_callback)(int rc, void *callback_data);
The callback takes the following parameters.
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.
#include "slapi-plugin.h" typedef int (*plugin_search_entry_callback)(Slapi_Entry *e, void *callback_data);
The callback takes the following parameters.
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.
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()
.
#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.
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.
send_ldap_referral_fn_ptr_t
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 14-11 send_ldap_referral_fn_ptr_t
Parameters
Parameter | Description |
---|---|
|
Current parameter block for the operation. |
|
Current entry for the operation. |
|
Pointer to the |
|
Pointer to the array of |
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.
send_ldap_result_fn_ptr_t
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 14-12 send_ldap_result_fn_ptr_t
Parameters
Parameter | Description |
---|---|
|
Current parameter block for the operation. |
|
Result code. |
|
When sending back an |
|
Error message that you want sent back to the client. (Pass |
|
When sending back the result code for an LDAP search operation, use this argument to specify the number of matching entries found. |
|
When sending back an |
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.
send_ldap_search_entry_fn_ptr_t
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 14-13 send_ldap_search_entry_fn_ptr_t
Parameters
Parameter | Description |
---|---|
|
Current parameter block for the operation. |
|
Entry returned by the search. |
|
Array of controls for the operation. |
|
Array of attribute types to return in the search results. |
|
|
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.
Slapi_Attr
Opaque structure representing a directory entry attribute.
#include "slapi-plugin.h" typedef struct slapi_attr Slapi_Attr;
Slapi_Backend
Opaque structure representing a server backend.
#include "slapi-plugin.h" typedef struct backend Slapi_Backend;
Slapi_ComponentId
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;
Example
The following code excerpt sets a plug-in component identifier used during an internal search.
Example 14-3 Setting a Plug-In Identifier for Use with Internal Operations
#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); }
slapi_compute_callback_t
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.
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.
slapi_compute_output_t
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.
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.
Slapi_CondVar
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;
Slapi_Connection
Opaque structure representing a connection to the server.
#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.
#include "slapi-plugin.h" typedef struct slapi_dn Slapi_DN;
Slapi_Entry
Opaque structure representing a directory entry.
#include "slapi-plugin.h" typedef struct slapi_entry Slapi_Entry;
slapi_extension_constructor_fnptr
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.
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
.
slapi_extension_destructor_fnptr
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.
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.
#include "slapi-plugin.h" typedef struct slapi_filter Slapi_Filter;
Slapi_MatchingRuleEntry
Opaque structure representing an LDAP v3 matching rule handled by the plug-in.
#include "slapi-plugin.h" typedef struct slapi_matchingRuleEntry Slapi_MatchingRuleEntry;
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.
#include "slapi-plugin.h" typedef struct slapi_mod Slapi_Mod;
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.
#include "slapi-plugin.h" typedef struct slapi_mods Slapi_Mods;
Slapi_Mutex
Opaque structure representing a mutex lock used by the plug-in.
#include "slapi-plugin.h" typedef struct slapi_mutex Slapi_Mutex;
Slapi_Operation
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;
Slapi_PBlock
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 14, "Data Type and Structure Reference"
For examples of Slapi_PBlock
use, refer to the sample plug-ins under $INSTALL_DIR/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.
#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 14-18 Slapi_PluginDesc
Fields
Field | Description |
---|---|
|
Unique (server wide) identifier for the plug-in. |
|
Name of the vendor supplying the plug-in such as |
|
Plug-in revision number such as |
|
Short description of the plug-in such as |
For examples of Slapi_PluginDesc
use, refer to the sample plug-ins under $INSTALL_DIR/examples/
.
slapi_plugin_init_fnptr
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.
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/
.
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.
#include "slapi-plugin.h" typedef struct slapi_rdn Slapi_RDN;
Slapi_Value
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;
Slapi_ValueSet
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;