Chapter 15 Parameter Reference

This chapter describes the parameters available in the Slapi_PBlock parameter block, the type of data associated with each parameter, and the plug-in functions in which those parameters are accessible.

To get the values of these parameters, call the slapi_pblock_get() function. To set the values of these parameters, call the slapi_pblock_set() function. Using these parameters, you can get and set the following information:

• Parameters for Registering Plug-In Functions
• Parameters Accessible to All Plug-Ins
• Parameters for the Configuration Function
• Parameters for the Bind Function
• Parameters for the Search Function
• Parameters for the Add Function
• Parameters for the Compare Function
• Parameters for the Delete Function
• Parameters for the Modify Function
• Parameters for the Modify RDN Function
• Parameters for the Abandon Function
• Parameters for Database Import
• Parameters for Database Export
• Parameters for Database Archive
• Parameters for Database Restore
• Parameters for Database Indexing
• Parameters for Extended Operations
• Parameters for Internal LDAP Operations
• Parameters for Matching Rule Plug-Ins

Note. With the exception of the parameters for matching rule plug-in functions, you do not need to get the value of any of these parameters.

The parameters for registering plug-in functions are organized in the following sections:

• Database Plug-Ins
• Pre-Operation/Data Validation Plug-Ins
• Post-Operation/Data Notification Plug-Ins
• Extended Operation Plug-Ins
• Matching Rule Plug-Ins

The parameters listed in this section are used to register database plug-in functions.

Each parameter corresponds to an operation performed by the back-end database. When integrating your own database with the Directory Server, you need to write and register your own plug-in functions that handle these operations.

To register your plug-in function, write an initialization function that sets the values of the following parameters to your functions.

Parameter ID	Description
SLAPI_PLUGIN_DB_BIND_FN	This function is called in response to an LDAP bind request.
SLAPI_PLUGIN_DB_UNBIND_FN	This function is called in response to an LDAP unbind request.
SLAPI_PLUGIN_DB_SEARCH_FN	This function is called in response to an LDAP search request. The function should collect a set of candidates for the search results.
SLAPI_PLUGIN_DB_COMPARE_FN	This function is called in response to an LDAP compare request.
SLAPI_PLUGIN_DB_MODIFY_FN	This function is called in response to an LDAP modify request.
SLAPI_PLUGIN_DB_MODRDN_FN	This function is called in response to an LDAP modify RDN request.
SLAPI_PLUGIN_DB_ADD_FN	This function is called in response to an LDAP add request.
SLAPI_PLUGIN_DB_DELETE_FN	This function is called in response to an LDAP delete request.
SLAPI_PLUGIN_DB_ABANDON_FN	This function is called in response to an LDAP abandon operation request.
SLAPI_PLUGIN_DB_CONFIG_FN	This function is called when the server is parsing the slapd.conf configuration file. If the Directory Server encounters a directive that it does not recognize, it passes the directive to the back-end by using this routine.
SLAPI_PLUGIN_CLOSE_FN	This function is called when the server is shutting down. You can use this function to prepare your back-end database for shutdown.
SLAPI_PLUGIN_DB_FLUSH_FN	The front-end periodically calls this function. The function is intended to flush any open caches and to save information to disk.
SLAPI_PLUGIN_START_FN	This function is called on start-up and is intended to initialize the database and prepare it for use.
SLAPI_PLUGIN_DB_ENTRY_FN	This function is called when the server is sending an entry back to the client.
SLAPI_PLUGIN_DB_REFERRAL_FN	This function is called when the server is sending a set of referrals to the client.
SLAPI_PLUGIN_DB_RESULT_FN	This function is called when the server is sending a set of search results to the client.
SLAPI_PLUGIN_DB_LDIFDB_FN	This function is called when the server reads an LDIF file into the database.
SLAPI_PLUGIN_DB_DBLDIF_FN	This function is called when the server exports the datbase to an LDIF file.
SLAPI_PLUGIN_DB_ARCHIVEDB_FN	This function is called when the server restores an archive to the database.
SLAPI_PLUGIN_DB_DBARCHIVE_FN	This function is called when the server backs up the database to an archive.
SLAPI_PLUGIN_DB_NEXT_SEARCH_ENTRY_FN	This function is called for each candidate in the search result set. The function should test each candidate against the search filter and send matching entries back to the client.
SLAPI_PLUGIN_DB_SIZE_FN	Specifies the function called to get the size of the database and set as SLAPI_DBSIZE in the parameter block.
SLAPI_PLUGIN_DB_TEST_FN	Specifies the function called to test the back-end and the database.
SLAPI_PLUGIN_DB_DB2INDEX_FN	(Netscape Directory Server 4.0 only) Specifies the function called to generate indexes for the existing database.

Pre-Operation/Data Validation Plug-Ins

The parameters listed in this section are used to register pre-operation/data validation plug-in functions.

To register your plug-in function, write an initialization function that sets the values of the following parameters to your functions.

Parameter ID	Description
SLAPI_PLUGIN_PRE_BIND_FN	This function is called before an LDAP bind operation is completed.
SLAPI_PLUGIN_PRE_UNBIND_FN	This function is called before an LDAP unbind operation is completed.
SLAPI_PLUGIN_PRE_SEARCH_FN	This function is called before an LDAP search operation is completed.
SLAPI_PLUGIN_PRE_COMPARE_FN	This function is called before an LDAP compare operation is completed.
SLAPI_PLUGIN_PRE_MODIFY_FN	This function is called before an LDAP modify operation is completed.
SLAPI_PLUGIN_PRE_MODRDN_FN	This function is called before an LDAP modify RDN operation is completed.
SLAPI_PLUGIN_PRE_ADD_FN	This function is called before an LDAP add operation is completed.
SLAPI_PLUGIN_PRE_DELETE_FN	This function is called before an LDAP delete operation is completed.
SLAPI_PLUGIN_PRE_ABANDON_FN	This function is called before an LDAP abandon operation is completed.
SLAPI_PLUGIN_PRE_ENTRY_FN	This function is called before an entry is sent back to the client.
SLAPI_PLUGIN_PRE_REFERRAL_FN	This function is called before a set of referrals is sent back to the client.
SLAPI_PLUGIN_PRE_RESULT_FN	This function is called before a set of search results is sent back to the client.
SLAPI_PLUGIN_START_FN	This function is called after the server starts up. You can specify a start function for each pre-operation plug-in.
SLAPI_PLUGIN_CLOSE_FN	This function is called before the server shuts down. You can specify a close function for each pre-operation plug-in.

Post-Operation/Data Notification Plug-Ins

The parameters listed in this section are used to register post-operation/data notification plug-in functions.

Parameter ID	Description
SLAPI_PLUGIN_POST_BIND_FN	This function is called after an LDAP bind operation is completed.
SLAPI_PLUGIN_POST_UNBIND_FN	This function is called after an LDAP unbind operation is completed.
SLAPI_PLUGIN_POST_SEARCH_FN	This function is called after an LDAP search operation is completed.
SLAPI_PLUGIN_POST_COMPARE_FN	This function is called after an LDAP compare operation is completed.
SLAPI_PLUGIN_POST_MODIFY_FN	This function is called after an LDAP modify operation is completed.
SLAPI_PLUGIN_POST_MODRDN_FN	This function is called after an LDAP modify RDN operation is completed.
SLAPI_PLUGIN_POST_ADD_FN	This function is called after an LDAP add operation is completed.
SLAPI_PLUGIN_POST_DELETE_FN	This function is called after an LDAP delete operation is completed.
SLAPI_PLUGIN_POST_ABANDON_FN	This function is called after an LDAP abandon operation is completed.
SLAPI_PLUGIN_POST_ENTRY_FN	This function is called after an entry is sent back to the client.
SLAPI_PLUGIN_POST_REFERRAL_FN	This function is called after a set of referrals is sent back to the client.
SLAPI_PLUGIN_POST_RESULT_FN	This function is called after a set of search results is sent back to the client.
SLAPI_PLUGIN_START_FN	This function is called after the server starts up. You can specify a start function for each post-operation plug-in.
SLAPI_PLUGIN_CLOSE_FN	This function is called before the server shuts down. You can specify a close function for each post-operation plug-in.

Extended Operation Plug-Ins

The parameters listed below are used to register extended operation plug-in functions.

Parameter ID	Data Type	Description
SLAPI_PLUGIN_EXT_OP_FN	void *	Your plug-in function for handling an extended operation.
SLAPI_PLUGIN_EXT_OP_OIDLIST	char **	NULL-terminated array of OIDs identifying the extended operations handled by the plug-in function.
SLAPI_PLUGIN_START_FN	void *	This function is called after the server starts up. You can specify a start function for each extended operation plug-in.
SLAPI_PLUGIN_CLOSE_FN	void *	This function is called before the server shuts down. You can specify a close function for each extended operation plug-in.

Matching Rule Plug-Ins

The parameters listed in below are used to register matching rule plug-in functions.

Parameter ID	Description
SLAPI_PLUGIN_MR_FILTER_CREATE_FN	Factory function for creating filter functions. This function must be thread-safe, since the server may call it concurrently with other functions.
SLAPI_PLUGIN_MR_INDEXER_CREATE_FN	Factory function for creating indexer functions. This function must be thread-safe, since the server may call it concurrently with other functions.
SLAPI_PLUGIN_MR_FILTER_MATCH_FN	Filter function.
SLAPI_PLUGIN_MR_FILTER_INDEX_FN	Filter function that uses an index to accelerate the processing of a search request.
SLAPI_PLUGIN_MR_FILTER_RESET_FN	Function for resetting the filter function.
SLAPI_PLUGIN_MR_INDEX_FN	Indexer function.
SLAPI_PLUGIN_DESTROY_FN	Function for freeing a filter function or indexer function.
SLAPI_PLUGIN_CLOSE_FN	Function called before server shutdown (use this function to clean up before shutdown).

• Information About the Database
• Information About the Connection
• Information About the Operation
• Notes in the Access Log
• Information About the Plug-In

The parameters listed below specify information about the back-end database. These parameters are available for all types of plug-ins. Note that these specific parameters can not be set by calling slapi_pblock_set(). You can, however, get these parameters by calling slapi_pblock_get().

Parameter ID	Data Type	Description
SLAPI_BE_MONITORDN	char *	(Netscape Directory Server 3.x releases only) DN used to monitor the back-end database. Note that this is no longer supported in the Netscape Directory Server 4.0 release.
SLAPI_BE_TYPE	char *	Type of back-end database (this is the type specified by the database directive in the slapd.conf file).
SLAPI_BE_READONLY	int	Specifies whether or not the back-end database is read-only (this is determined by the readonly directive in the slapd.conf file). 1 means that the database back-end is read-only. 0 means that the database back-end is writable.
SLAPI_DBSIZE	int	Specifies the size of the back-end database. If you are using your own database instead of the default database, your SLAPI_DB_SIZE_FN function should set the value of this parameter.

Information About the Connection

The parameters listed below specify information about the connection. These parameters are available for all types of plug-ins.

Parameter ID	Data Type	Description
SLAPI_CONN_ID	int	ID identifying the current connection.
SLAPI_CONN_DN	char *	DN of the user authenticated on the current connection. If you call slapi_pblock_get() to get this DN, you should call slapi_ch_free() to free the resulting DN when done.
SLAPI_CONN_AUTHTYPE	char *	Method used to authenticate the current user. This parameter can have one of the following values: SLAPD_AUTH_NONE specifies that no authentication mechanism was used (for example, in cases of anonymous authentication). SLAPD_AUTH_SIMPLE specifies that simple authentication (user name and password) was used to authenticate the current user. SLAPD_AUTH_SSL specifies that SSL (certificate-based authentication) was used to authenticate the current user. SLAPD_AUTH_SASL specifies that a SASL (simple authentication and security layer) mechanism was used to authenticate the current user.

Information About the Operation

The parameters listed below specify information about the current operation. These parameters are available for all types of plug-ins.

Parameter ID	Data Type	Description
SLAPI_OPINITIATED_TIME	time_t	Time when the server began processing the operation
SLAPI_REQUESTOR_ISROOT	int	Specifies whether or not the user requesting the operation is the "root DN". 1 means that the "root DN" is requesting the operation. 0 means that the user requesting the operation is not the "root DN." The "root DN" is the "superuser" of the directory. This DN is specified by the rootdn directive in the slapd.conf configuration file.
SLAPI_REQUESTOR_ISUPDATEDN	int	Specifies whether or not the user requesting the operation is the "update DN". 1 means that the "update DN" is requesting the operation. 0 means that the user requesting the operation is not the "update DN." The "update DN" is the master entity responsible for updating the directory during replication. This DN is specified by the updatedn directive in the slapd.conf configuration file.
SLAPI_REQUESTOR_DN	char *	Specifies the DN of the user requesting the operation.
SLAPI_TARGET_DN	char *	Specifies the DN to which the operation applies (for example, the DN of the entry being added or removed)
SLAPI_REQCONTROLS	LDAPControl **	Array of the controls specified in the request.

Notes in the Access Log

This feature is available in the Netscape Directory Server 4.0 release and is not available in earlier releases.

The parameters listed below specify notes that can be appended to access log entries. These parameters are available for all types of plug-ins.

Parameter ID	Data Type	Description
SLAPI_OPERATION_NOTES	unsigned int	Flags specifying the notes that you want appended to access log entries. You can set this parameter to the following value: SLAPI_OP_NOTE_UNINDEXED specifies that you want the string "Notes=U" appended to access log entries. You can use this to indicate that a search operation could not use indexes to generate a smaller list of candidates. If no flags are set, no notes are appended to access log entries.

For more information, see "Adding Notes to Access Log Entries" on page  50.

Information About the Plug-In

The parameters listed below specify information about the plug-in that is available to all plug-in functions defined in the current library. These parameters are available for all types of plug-ins.

Parameter ID	Data Type	Description
SLAPI_PLUGIN_PRIVATE	void *	Private data that you want passed to your plug-in functions.
SLAPI_PLUGIN_TYPE	int	Specifies the type of plug-in function (see "Types of Plug-Ins" on page  367)
SLAPI_PLUGIN_ARGV	char **	NULL-terminated array of command-line arguments specified for the plugin directive in the slapd.conf file.
SLAPI_PLUGIN_ARGC	int	Number of command-line arguments specified for the plugin directive in the slapd.conf file.
SLAPI_PLUGIN_VERSION	char *	Specifies the version of the plug-in function (see "Version Information" on page  367).
SLAPI_PLUGIN_OPRETURN	int	Specifies the return value of the LDAP operation that has just been processed.

Types of Plug-Ins

The SLAPI_PLUGIN_TYPE parameter can have one of the following values, which identifies the type of the current plug-in (see Table 2.1 for a more detailed description of the types of server plug-ins):

Defined Constant	Description
SLAPI_PLUGIN_DATABASE	Database plug-in
SLAPI_PLUGIN_EXTENDEDOP	Extended operation plug-in
SLAPI_PLUGIN_PREOPERATION	Pre-operation/data validation plug-in
SLAPI_PLUGIN_POSTOPERATION	Post-operation/data notification plug-in
SLAPI_PLUGIN_MATCHINGRULE	Matching rule plug-in
SLAPI_PLUGIN_SYNTAX	Syntax plug-in

Version Information

To set the value of the SLAPI_PLUGIN_VERSION parameter, you can specify one of the following values:

Defined Constant	Description
SLAPI_PLUGIN_CURRENT_VERSION	The current version of the Netscape Directory Server plug-in
SLAPI_PLUGIN_VERSION_01	Version 1 of the plug-in interface, which is supported by the Netscape Directory Server 3.x and 4.x releases
SLAPI_PLUGIN_VERSION_02	Version 2 of the plug-in interface, which is supported by the Netscape Directory Server 4.x release

See "Reading Configuration Files" on page  98 for more information on these parameters.

See "Processing an LDAP Bind Operation" on page  99 for more information on these parameters.

The following parameters are set by the front-end and back-end as part of the process of executing the search. .

Parameter ID	Data Type	Description
SLAPI_SEARCH_RESULT_SET	void *	Set of search results.
SLAPI_SEARCH_RESULT_ENTRY	void *	Entry returned from iterating through the results set.
SLAPI_NENTRIES	int	Number of search results found
SLAPI_SEARCH_REFERRALS	struct berval **	Array of the URLs to other LDAP servers that the current server is referring the client to

See "Processing an LDAP Search Operation" on page  101 and "Iterating through Candidates" on page  104 for more information on these parameters.

See "Processing an LDAP Add Operation" on page  106 for more information on these parameters.

See "Processing an LDAP Compare Operation" on page  105 for more information on these parameters.

See "Processing an LDAP Delete Operation" on page  111 for more information on these parameters.

See "Processing an LDAP Modify Operation" on page  108 for more information on these parameters.

See "Processing an LDAP Modify RDN Operation" on page  109 for more information on these parameters.

See "Processing an LDAP Abandon Operation" on page  112 for more information on these parameters.

See "Importing an LDIF File into the Database" on page  114 for more information on these parameters.

Se e "Importing an LDIF File into the Database" on page  114 for more information on these parameters.

Se e "Saving the Database as an Archive" on page  117 for more information on these parameters.

Se e "Restoring the Database from an Archive" on page  117 for more information on these parameters.

The following table lists the parameters in the parameter block passed to the database indexing function, which is responsible for generating indexes for the database. If you are writing your own plug-in function for performing this work, you can get these values by calling the slapi_pblock_get() function.

Parameter ID	Data Type	Description
SLAPI_DB2INDEX_ATTRS	char **	Specifies a NULL-terminated array of the attribute types that you want indexed.

Se e "Generating Indexes for the Database" on page  118 for more information on these parameters.

The following functions set all three parameters:

• slapi_search_internal()
• slapi_search_internal_callback()

• slapi_add_internal()
• slapi_add_entry_internal()
• slapi_delete_internal()
• slapi_modify_internal()
• slapi_modrdn_internal()

The following parameters are listed in the slapi-plugin.h header file but are not currently used:

• SLAPI_MR_FILTER_ENTRY
• SLAPI_MR_FILTER_TYPE
• SLAPI_MR_FILTER_VALUE
• SLAPI_MR_FILTER_OID
• SLAPI_MR_FILTER_DNATTRS

[?? THE REST OF THIS SECTION IS WIP ??]

[?? Might take this out. Don't know if all this is necessary. ??]

The front-end checks for inconsistencies in this information (for example, if an LDAP v2 client is trying to use the SASL authentication method).

The front-end also checks for LDAP v3 controls in the request. (In LDAP v3, a request can include a control that provides additional information to extend the current operation.) If the control is critical and is not supported by the Directory Server or is not supported for this operation, the front-end returns an LDAP_UNAVAILABLE_CRITICAL_EXTENSION error to the client.

If the request contains controls supported by the Directory Server, the front-end sets the controls as the value of the SLAPI_REQCONTROLS parameter in the parameter block.