| 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 |
| 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 |
bervalRepresents 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_contextAn 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.
LDAPControlRepresents 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. |
|
|
|
|
|
|
LDAPModRepresents 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);
}
mrFilterMatchFnSpecifies 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_callbackSpecifies 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_callbackSpecifies 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_callbackSpecifies 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_typeSpecifies 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_tSpecifies 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_tSpecifies 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_tSpecifies 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_AttrOpaque structure representing a directory entry attribute.
#include "slapi-plugin.h" typedef struct slapi_attr Slapi_Attr;
Slapi_BackendOpaque structure representing a server backend.
#include "slapi-plugin.h" typedef struct backend Slapi_Backend;
Slapi_ComponentIdOpaque 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;
ExampleThe 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_tSpecifies 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_tSpecifies 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_CondVarOpaque 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_ConnectionOpaque structure representing a connection to the server.
#include "slapi-plugin.h" typedef struct conn Slapi_Connection;
Slapi_DNOpaque 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_EntryOpaque structure representing a directory entry.
#include "slapi-plugin.h" typedef struct slapi_entry Slapi_Entry;
slapi_extension_constructor_fnptrSpecifies 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_fnptrSpecifies 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_FilterOpaque structure representing a search filter.
#include "slapi-plugin.h" typedef struct slapi_filter Slapi_Filter;
Slapi_MatchingRuleEntryOpaque structure representing an LDAP v3 matching rule handled by the plug-in.
#include "slapi-plugin.h" typedef struct slapi_matchingRuleEntry Slapi_MatchingRuleEntry;
Slapi_ModOpaque 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_ModsOpaque 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_MutexOpaque structure representing a mutex lock used by the plug-in.
#include "slapi-plugin.h" typedef struct slapi_mutex Slapi_Mutex;
Slapi_OperationOpaque 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_PBlockOpaque 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_PluginDescRepresents 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_fnptrSpecifies 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_RDNOpaque 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_ValueOpaque 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_ValueSetOpaque 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;
|
 Copyright © 2001, 2013, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|