Chapter 3 Parameter Block Reference

Chapter 3
Parameter Block Reference

This 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
Access Log	All plug-in functions
Add	Pre- and post-operation add functions
Backend Information	All plug-in functions
Bind	Pre- and post-operation bind functions
Compare	Pre- and post-operation compare functions
Connection Information	All plug-in functions
Delete	Pre- and post-operation delete functions
Directory Configuration Information	All plug-in functions
Extended Operations	Extended operation functions
Internal Operations	All plug-in functions
Modify	Pre- and post-operation modify functions
Operation Information	All plug-in functions
Plug-In Registration	Plug-in initialization functions and specific types as mentioned in this section
Rename (Modify RDN)	Pre- and post-operation modify RDN functions
Results	All plug-in functions
Search	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 Log

The following parameter allows you to configure access log output.

Table 3-2 Access Log Parameters
Parameter ID	Data Type	Description
SLAPI_OPERATION_NOTES	unsigned int	Flag specifying that unindexed searches be indicated in the access log. Setting this parameter to SLAPI_OP_NOTE_UNINDEXED causes the string Notes=U to be appended to access log entries reflecting unindexed searches.

Add

The 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 Information

The following parameters allow you to access information about directory backends through the parameter block.

Table 3-4 Backend Information Parameters
Parameter ID	Data Type	Description
SLAPI_BACKEND	Slapi_Backend *	Backend serving the current operation. May be NULL if no backend is associated with the current operation.
SLAPI_BE_LASTMOD	int	Whether the backend tracks modification time and who made the modification: 0 if modifications are not tracked 1 if modifications are tracked
SLAPI_BE_READONLY	int	Value of nsslapd-readonly in the server configuration file: 0 if the backend is writable. 1 if the backend is read-only.
SLAPI_BE_TYPE	char *	Value of nsslapd-database in the server configuration file.
SLAPI_DBSIZE	unsigned int	Size of the backend database in KB.

Bind

The following parameters allow you to access information about the bind operation through the parameter block.

Table 3-5 Bind Function Parameters
Parameter ID	Data Type	Description
SLAPI_BIND_CREDENTIALS	struct berval *	Bind request credentials such as a password or SASL mechanism credentials, depending on the bind method.
SLAPI_BIND_METHOD	int	Authentication method used. LDAP_AUTH_NONE (anonymous) LDAP_AUTH_SASL (SASL) LDAP_AUTH_SIMPLE (password) LDAP_AUTH_SSL (certificate)
SLAPI_BIND_RET_SASLCREDS	struct berval *	SASL server credentials to send to the client.
SLAPI_BIND_SASLMECHANISM	char *	SASL mechanism used for bind.
SLAPI_BIND_TARGET	char *	DN used to bind.

Compare

The following parameters allow you to access an entry or attribute to use in a comparison through the parameter block.

Table 3-6 Compare Function Parameters
Parameter ID	Data Type	Description
SLAPI_COMPARE_TARGET	char *	DN of the entry to use in the comparison.
SLAPI_COMPARE_TYPE	char *	Attribute type to use in the comparison.
SLAPI_COMPARE_VALUE	struct berval *	Attribute value to use in the comparison.

Connection Information

The 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. SLAPD_AUTH_NONE (anonymous) SLAPD_AUTH_SASL (extensible SASL) SLAPD_AUTH_SIMPLE (password) SLAPD_AUTH_SSL (certificate)
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. 0 false. 1 true.
SLAPI_CONN_IS_SSL_SESSION	int	Whether the connection is over SSL. 0 false. 1 true.
SLAPI_CONN_SERVERNETADDR	PRNetAddr *	IP address client is connected to.

1PRNetAddr is an NSPR 4.x data structure.

Delete

The 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 Information

The following parameters allow you to access information about configuration of the directory instance through the parameter block.

Table 3-9 Directory Configuration Information Parameters
Parameter ID	Data Type	Description
SLAPI_ARGC	int	Number of command-line arguments passed to the server at startup.
SLAPI_ARGV	char **	Array of command-line arguments passed to the server at startup.
SLAPI_CONFIG_DIRECTORY	char *	File system directory containing configuration files for the instance.
SLAPI_CONFIG_FILENAME	char *	Configuration file used, such as dse.ldif.

Extended Operations

The following parameters allow you to access information about an extended operation through the parameter block.

Table 3-10 Extended Operation Parameters
Parameter ID	Data Type	Description
SLAPI_EXT_OP_REQ_OID	char *	Object identifier (OID) of the extended operation specified in the request.
SLAPI_EXT_OP_REQ_VALUE	struct berval *	Value specified in the request.
SLAPI_EXT_OP_RET_OID	char *	Object identifier (OID) to return to the client.
SLAPI_EXT_OP_RET_VALUE	struct berval *	Value to send to the client.

Internal Operations

The following parameters allow you to access information about internal operations through the parameter block.

Table 3-11 Internal Operation Parameters
Parameter ID	Data Type	Description
SLAPI_PLUGIN_INTOP_RESULT	int	Result code of internal operation.
SLAPI_PLUGIN_INTOP_SEARCH_ENTRIES	Slapi_Entry **	Array of entries found by internal search.
SLAPI_PLUGIN_INTOP_SEARCH_REFERRALS	char **	Array of referrals found by internal search in LDAP URL format.

Modify

The 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 Information

The following parameters allow you to access information about the current operation through the parameter block.

Table 3-13 Operation Information Parameters
Parameter ID	Data Type	Description
SLAPI_CONTROLS_ARG	LDAPControl **	Array of controls passed before the operation is created.
SLAPI_IS_INTERNAL_OPERATION	int	Whether the operation originated internally, or as the result of a client request. 0 client request. 1 internal operation.
SLAPI_IS_REPLICATED_OPERATION	int	Whether the operation is part of replication with another server. 0 false. 1 true.
SLAPI_OPERATION	Slapi_Operation *	Operation currently in progress.
SLAPI_OPERATION_ID	int	Identifier for the operation.
SLAPI_OPERATION_MSGID	long	Message identifier for the operation.
SLAPI_OPINITIATED_TIME	time_t	Time when the server began processing the operation.
SLAPI_REQCONTROLS	LDAPControl **	Array of controls specified in the request.
SLAPI_REQUESTOR_DN	char *	DN of the user requesting the operation.
SLAPI_REQUESTOR_ISROOT	int	Whether the bind DN of the user requesting the operation corresponds to the root DN, the value of nsslapd-rootdn on cn=config for the instance. 0 false. 1 true.
SLAPI_TARGET_DN	char *	DN to which the operation applies.

Plug-In Registration

The 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. SLAPI_PLUGIN_CURRENT_VERSION (presently SLAPI_PLUGIN_VERSION_03) SLAPI_PLUGIN_VERSION_01 (3.x and later servers) SLAPI_PLUGIN_VERSION_02 (4.x and later servers) SLAPI_PLUGIN_VERSION_03 (5.x servers)

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.

Table 3-15 Generic Function Registration Parameters
Parameter ID	Data Type	Description
SLAPI_PLUGIN_CLOSE_FN	void *	Function called at server shutdown.
SLAPI_PLUGIN_START_FN	void *	Function called at server startup. May be called more than once.

Extended Operations

Parameters for registering an extendedop plug-in function and object identifier list follow.

Table 3-16 Extended Operation Registration Parameters
Parameter ID	Data Type	Description
SLAPI_PLUGIN_EXT_OP_FN	void *	Function called upon request for an LDAP v3 extended operation.
SLAPI_PLUGIN_EXT_OP_OIDLIST	char **	NULL-terminated list of object identifiers (OIDs) handled by the plug-in.

Internal Postoperation

Parameters for registering an internalpostoperation plug-in functions follow.

Table 3-17 Internal Postoperation Registration Parameters
Parameter ID	Data Type	Description
SLAPI_PLUGIN_INTERNAL_POST_ADD_FN	void *	Function called after an internal add operation completes.
SLAPI_PLUGIN_INTERNAL_POST_DELETE_FN	void *	Function called after an internal delete operation completes.
SLAPI_PLUGIN_INTERNAL_POST_MODIFY_FN	void *	Function called after an internal modify operation completes.
SLAPI_PLUGIN_INTERNAL_POST_MODRDN_FN	void *	Function called after an internal rename (modify RDN) operation completes.

Internal Preoperation

Parameters for registering an internalpreoperation plug-in functions follow.

Table 3-18 Internal Preoperation Registration Parameters
Parameter ID	Data Type	Description
SLAPI_PLUGIN_INTERNAL_PRE_ADD_FN	void *	Function called before an internal add operation is performed.
SLAPI_PLUGIN_INTERNAL_PRE_DELETE_FN	void *	Function called before an internal delete operation is performed.
SLAPI_PLUGIN_INTERNAL_PRE_MODIFY_FN	void *	Function called before an internal modify operation is performed.
SLAPI_PLUGIN_INTERNAL_PRE_MODRDN_FN	void *	Function called before an internal rename (modify RDN) operation is performed.

Entry Storage and Retrieval

Parameters for registering ldbmentryfetchstore plug-in functions follow.

Table 3-19 Entry Store/Fetch Function Registration Parameters
Parameter ID	Data Type	Description
SLAPI_PLUGIN_ENTRY_FETCH_FUNC	void *	Function called upon retrieval of an entry from the backend.
SLAPI_PLUGIN_ENTRY_STORE_FUNC	void *	Function called before storing an entry through the backend.

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. 0 false. 1 true.
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.

Table 3-21 Postoperation Function Registration Parameters
Parameter ID	Data Type	Description
SLAPI_PLUGIN_POST_ABANDON_FN	void *	Function called after an operation is abandoned.
SLAPI_PLUGIN_POST_ADD_FN	void *	Function called after an add operation completes.
SLAPI_PLUGIN_POST_BIND_FN	void *	Function called after a bind operation completes.
SLAPI_PLUGIN_POST_COMPARE_FN	void *	Function called after a compare operation completes.
SLAPI_PLUGIN_POST_DELETE_FN	void *	Function called after a delete operation completes.
SLAPI_PLUGIN_POST_ENTRY_FN	void *	Function called after an entry is sent to the client.
SLAPI_PLUGIN_POST_MODIFY_FN	void *	Function called after a modify operation completes.
SLAPI_PLUGIN_POST_MODRDN_FN	void *	Function called after an rename (modify RDN) operation completes.
SLAPI_PLUGIN_POST_REFERRAL_FN	void *	Function called after a referral is sent to the client.
SLAPI_PLUGIN_POST_RESULT_FN	void *	Function called after a result is sent to the client.
SLAPI_PLUGIN_POST_SEARCH_FN	void *	Function called after a search operation completes. For persistent search operations, this function is called after the client interrupts the search.
SLAPI_PLUGIN_POST_UNBIND_FN	void *	Function called after an unbind operation completes.

Preoperation

Parameters for registering preoperation plug-in functions follow.

Table 3-22 Preoperation Function Registration Parameters
Parameter ID	Data Type	Description
SLAPI_PLUGIN_PRE_ABANDON_FN	void *	Function called before an operation is abandoned.
SLAPI_PLUGIN_PRE_ADD_FN	void *	Function called before an add operation is performed.
SLAPI_PLUGIN_PRE_BIND_FN	void *	Function called before a bind operation is performed.
SLAPI_PLUGIN_PRE_COMPARE_FN	void *	Function called before a compare operation is performed.
SLAPI_PLUGIN_PRE_DELETE_FN	void *	Function called before an delete operation is performed.
SLAPI_PLUGIN_PRE_ENTRY_FN	void *	Function called before an entry is sent to the client.
SLAPI_PLUGIN_PRE_MODIFY_FN	void *	Function called before a modify operation is performed.
SLAPI_PLUGIN_PRE_MODRDN_FN	void *	Function called before an rename (modify RDN) operation is performed.
SLAPI_PLUGIN_PRE_REFERRAL_FN	void *	Function called before a referral is sent to the client.
SLAPI_PLUGIN_PRE_RESULT_FN	void *	Function called before a result is sent to the client.
SLAPI_PLUGIN_PRE_SEARCH_FN	void *	Function called before a search operation is performed.
SLAPI_PLUGIN_PRE_UNBIND_FN	void *	Function called before an unbind operation is performed.

One-Way and Reversible Password Storage

Parameters for registering pwdstorage and reverpwdstorage plug-in functions follow.

Table 3-23 Password Storage Function Registration Parameters
Parameter ID	Data Type	Description
SLAPI_PLUGIN_PWD_STORAGE_SCHEME_CMP_FN	void *	Function called to encode a password for comparison with a stored, encoded password.
SLAPI_PLUGIN_PWD_STORAGE_SCHEME_DB_PWD	char *	Stored, encoded user password.
SLAPI_PLUGIN_PWD_STORAGE_SCHEME_DEC_FN	void *	(reverpwdstorage plug-ins only) Function called to decode an encrypted password.
SLAPI_PLUGIN_PWD_STORAGE_SCHEME_ENC_FN	void *	Function called to encode a password for storage.
SLAPI_PLUGIN_PWD_STORAGE_SCHEME_NAME	char *	Short password storage scheme name used by the server to identify the encoding scheme.
SLAPI_PLUGIN_PWD_STORAGE_SCHEME_USER_PWD	char *	User password in clear text.

Rename (Modify RDN)

The following parameters allow you to access an entry to rename through the parameter block.

Table 3-24 Rename (Modify RDN) Function Parameters
Parameter ID	Data Type	Description
SLAPI_MODRDN_DELOLDRDN	int	Whether to delete the old Relative Distinguished Name (RDN). 0 false. 1 true.
SLAPI_MODRDN_NEWRDN	char *	New RDN to assign to the entry.
SLAPI_MODRDN_NEWSUPERIOR	char *	DN of the new parent of the entry being renamed.
SLAPI_MODRDN_TARGET	char *	DN of the entry to rename.
SLAPI_ORIGINAL_TARGET	char *	Non-normalized DN of the entry to rename.

Results

The 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.

Search

The 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. 0 return both. 1 return only types.
SLAPI_SEARCH_DEREF	int	Method for handling aliases. LDAP_DEREF_ALWAYS LDAP_DEREF_FINDING LDAP_DEREF_NEVER LDAP_DEREF_SEARCHING
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. LDAP_SCOPE_BASE LDAP_SCOPE_ONELEVEL LDAP_SCOPE_SUBTREE
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.

Previous Contents Index Next

Previous Contents Index Next
Sun Java(TM) System Directory Server 5 2004Q2 Plug-In Developer's Reference