Sun Java(TM) System Directory Server 5.2 2005Q1 Plug-In Developer's Reference |
Chapter 3
Parameter Block ReferenceThis chapter describes the parameters available in the parameter block (Slapi_PBlock) structure. This chapter lists data types associated with each parameter.
Tip
To read parameter values, use slapi_pblock_get(). To write parameter values, use slapi_pblock_set(). Use of other functions may crash the server.
Refer to the Directory Server Plug-in Developer's Guide and the example plug-ins under ServerRoot/plugins/slapd/slapi/examples/ to better grasp how to use these parameters.
This chapter categorizes parameters as follows.
Table 3-1 Slapi_PBlock Parameter Categories
Category
Accessible to...1
All plug-in functions
Pre- and post-operation add functions
All plug-in functions
Pre- and post-operation bind functions
Pre- and post-operation compare functions
All plug-in functions
Pre- and post-operation delete functions
All plug-in functions
Extended operation functions
All plug-in functions
Pre- and post-operation modify functions
All plug-in functions
Plug-in initialization functions and specific types as mentioned in this section
Pre- and post-operation modify RDN functions
All plug-in functions
Pre- and post-operation search functions
1Object plug-ins may register any type of plug-in function and thus access different parameters depending on the operation.
Access LogThe following parameter allows you to configure access log output.
AddThe following parameters allow you to access an entry to add to the directory through the parameter block.
Table 3-3 Add Function Parameters
Parameter ID
Data Type
Description
SLAPI_ADD_ENTRY
Slapi_Entry *
Entry to add.
SLAPI_ADD_TARGET
char *
DN of the entry to add.
Backend InformationThe following parameters allow you to access information about directory backends through the parameter block.
BindThe following parameters allow you to access information about the bind operation through the parameter block.
CompareThe following parameters allow you to access an entry or attribute to use in a comparison through the parameter block.
Connection InformationThe following parameters allow you to access information about the client connection through the parameter block.
Table 3-7 Connection Information Parameters
Parameter ID
Data Type
Description
SLAPI_CLIENT_DNS
struct berval *
Fully qualified domain name of the client.
SLAPI_CONN_AUTHMETHOD
char *
Authentication method used.
SLAPI_CONN_CLIENTNETADDR
PRNetAddr *
IP address of client.1
SLAPI_CONN_DN
char *
DN of the user authenticated for the current connection.
SLAPI_CONNECTION
Slapi_Connection *
The current connection.
SLAPI_CONN_ID
int
Identifier for the current connection.
SLAPI_CONN_IS_REPLICATION_SESSION
int
Whether the connection is for replication.
SLAPI_CONN_IS_SSL_SESSION
int
Whether the connection is over SSL.
SLAPI_CONN_SERVERNETADDR
PRNetAddr *
IP address client is connected to.
1PRNetAddr is an NSPR 4.x data structure.
DeleteThe following parameters allow you to access an entry to delete through the parameter block.
Table 3-8 Delete Function Parameters
Parameter ID
Data Type
Description
SLAPI_DELETE_TARGET
char *
DN of the entry to delete.
SLAPI_ORIGINAL_TARGET
char *
Non-normalized DN of the entry to delete.
Directory Configuration InformationThe following parameters allow you to access information about configuration of the directory instance through the parameter block.
Extended OperationsThe following parameters allow you to access information about an extended operation through the parameter block.
Internal OperationsThe following parameters allow you to access information about internal operations through the parameter block.
ModifyThe following parameters allow you to access an entry to modify through the parameter block.
Table 3-12 Modify Function Parameters
Parameter ID
Data Type
Description
SLAPI_MODIFY_MODS
LDAPMod **
NULL-terminated array of LDAPMod structures containing modifications to perform on the target entry.
SLAPI_MODIFY_TARGET
char *
DN of the entry to modify.
SLAPI_ORIGINAL_TARGET
char *
Non-normalized DN of the entry to modify.
Operation InformationThe following parameters allow you to access information about the current operation through the parameter block.
Plug-In RegistrationThe following parameters are for use when registering plug-ins and their functions with the server and when accessing information about plug-in type and identity.
The following table lists information accessible to all types of plug-ins.
Table 3-14 Plug-In Information Parameters
Parameter ID
Data Type
Description
SLAPI_PLUGIN
void *
Internal server representation of the plug-in.
SLAPI_PLUGIN_ARGC
int
Number of arguments in the configuration entry.
SLAPI_PLUGIN_ARGV
char *
Array of arguments in the configuration entry.
SLAPI_PLUGIN_IDENTITY
void *
Plug-in identifier set and then required by the server when handling internal operations.
You may cast this to Slapi_ComponentId.
SLAPI_PLUGIN_PRIVATE
void *
Private data you pass to your plug-in functions.
You define this data structure.
SLAPI_PLUGIN_TYPE
int
Type of plug-in function, corresponding to the value of nsslapd-pluginType in the configuration entry for the plug-in. (Use the plug-in type values given here between parentheses in configuration entries.)
- SLAPI_PLUGIN_EXTENDEDOP (extendedop)
- SLAPI_PLUGIN_INTERNAL_POSTOPERATION (internalpostoperation)
- SLAPI_PLUGIN_INTERNAL_PREOPERATION (internalpreoperation)
- SLAPI_PLUGIN_LDBM_ENTRY_FETCH_STORE (ldbmentryfetchstore)
- SLAPI_PLUGIN_MATCHINGRULE (matchingrule)
- SLAPI_PLUGIN_TYPE_OBJECT (object)1
- SLAPI_PLUGIN_POSTOPERATION (postoperation)
- SLAPI_PLUGIN_PREOPERATION (preoperation)
- SLAPI_PLUGIN_PWD_STORAGE_SCHEME (pwdstoragescheme)
- SLAPI_PLUGIN_REVER_PWD_STORAGE_SCHEME (reverpwdstoragescheme)
SLAPI_PLUGIN_VERSION
char *
Plug-in API version supported by the plug-in.
1Object plug-ins may register any type of plug-in function.
Startup and Shutdown
Parameters for registering generic plug-in functions follow. These function types may be registered by any plug-in.
Extended Operations
Parameters for registering an extendedop plug-in function and object identifier list follow.
Internal Postoperation
Parameters for registering an internalpostoperation plug-in functions follow.
Internal Preoperation
Parameters for registering an internalpreoperation plug-in functions follow.
Entry Storage and Retrieval
Parameters for registering ldbmentryfetchstore plug-in functions follow.
Matching Rules
Parameters for registering matchingrule plug-in functions and arguments follow.
Table 3-20 Matching Rule Function and Argument Registration Parameters
Parameter ID
Data Type
Description
SLAPI_MATCHINGRULE_DESC
-
Used to signify registration of the matching rule description with slapi_matchingrule_set().
SLAPI_MATCHINGRULE_NAME
-
Used to signify registration of the matching rule name with slapi_matchingrule_set().
SLAPI_MATCHINGRULE_OBSOLETE
-
Used to signify the matching rule is obsolete when registering with slapi_matchingrule_set().
SLAPI_MATCHINGRULE_OID
-
Used to signify registration of the matching rule object identifier with slapi_matchingrule_set().
SLAPI_MATCHINGRULE_SYNTAX
-
Used to signify registration of the matching rule syntax with slapi_matchingrule_set().
SLAPI_PLUGIN_DESTROY_FN
void *
Function called to free memory allocated to filter object.
SLAPI_PLUGIN_MR_FILTER_CREATE_FN
void *
Filter factory function.
SLAPI_PLUGIN_MR_FILTER_INDEX_FN
void *
Function called to set the indexer function.
SLAPI_PLUGIN_MR_FILTER_MATCH_FN
void *
Function called to check for a match.
SLAPI_PLUGIN_MR_FILTER_RESET_FN
void *
Function called to reset the match filter.
SLAPI_PLUGIN_MR_FILTER_REUSABLE
unsigned int
Whether the filter is reusable.
SLAPI_PLUGIN_MR_INDEXER_CREATE_FN
void *
Index factory function.
SLAPI_PLUGIN_MR_INDEX_FN
void *
Function called to index a single entry.
SLAPI_PLUGIN_MR_KEYS
struct berval **
Array of index keys corresponding to the attribute values.
SLAPI_PLUGIN_MR_OID
char *
Object identifier (OID) corresponding to the extensible match rule.
SLAPI_PLUGIN_MR_QUERY_OPERATOR
int
Type of operator used to check for matches.
SLAPI_OP_EQUAL
SLAPI_OP_GREATER
SLAPI_OP_GREATER_OR_EQUAL
SLAPI_OP_LESS
SLAPI_OP_LESS_OR_EQUAL
SLAPI_OP_SUBSTRING
SLAPI_PLUGIN_MR_TYPE
char *
Matching rule filter type.
SLAPI_PLUGIN_MR_USAGE
unsigned int
Whether to use the rule to index or to sort.
SLAPI_PLUGIN_MR_USAGE_INDEX
SLAPI_PLUGIN_MR_USAGE_SORT
SLAPI_PLUGIN_MR_VALUE
struct berval *
Attribute value to match.
SLAPI_PLUGIN_MR_VALUES
struct berval **
Array of attribute values to match.
SLAPI_PLUGIN_OBJECT
void *
Filter object for extensible match.
You define this data structure to use in a matching rule plug-in.
Postoperation
Parameters for registering postoperation plug-in functions follow.
Preoperation
Parameters for registering preoperation plug-in functions follow.
One-Way and Reversible Password Storage
Parameters for registering pwdstorage and reverpwdstorage plug-in functions follow.
Rename (Modify RDN)The following parameters allow you to access an entry to rename through the parameter block.
ResultsThe following parameters allow you to access results through the parameter block.
Table 3-25 Result Parameters
Parameter ID
Data Type
Description
SLAPI_ADD_RESCONTROL
LDAPControl *
Lets you add a control to the set of controls to send to the client.
Use slapi_pblock_set() to add a control with this parameter.
SLAPI_RES_CONTROLS
LDAPControl **
Array of controls to send to client.
If you use this with slapi_pblock_set() to change the set of controls to send to the client, you must retrieve and free the existing set of controls pointed to by SLAPI_RES_CONTROLS.
SLAPI_RESULT_CODE
int
Result code to send to client.
SLAPI_RESULT_MATCHED
char *
Portion of target DN that matched when sending LDAP_NO_SUCH_OBJECT to the client.
SLAPI_RESULT_TEXT
char *
Message to send to client.
SearchThe following parameters allow you to access search parameters through the parameter block.
Table 3-26 Search Function Parameters
Parameter ID
Data Type
Description
SLAPI_NENTRIES
int
Number of entries returned by the search.
SLAPI_SEARCH_ATTRS
char **
Array of attribute types to return in the search results.
The asterisk, *, can be used to mean all real (non-virtual) attributes.
SLAPI_SEARCH_ATTRSONLY
int
Whether to return both attribute types and attribute values.
SLAPI_SEARCH_DEREF
int
Method for handling aliases.
SLAPI_SEARCH_FILTER
Slapi_Filter *
Filter to be used for the search.
SLAPI_SEARCH_REFERRALS
struct berval **
Array of URLs to other LDAP servers to which the client is referred.
SLAPI_SEARCH_RESULT_ENTRY
void *
Entry returned while iterating through the result set.
You may cast this to Slapi_Entry.
SLAPI_SEARCH_SCOPE
int
Scope of the search.
SLAPI_SEARCH_SIZELIMIT
int
Maximum number of entries to return in the search results.
SLAPI_SEARCH_STRFILTER
char *
String representation of the filter to be used for the search.
SLAPI_SEARCH_TARGET
char *
DN of base entry for the search.
SLAPI_SEARCH_TIMELIMIT
int
Maximum number of seconds to allow for the search.