Chapter 15 Function Reference

This chapter contains reference information on Netscape Directory Server (Directory Server) server plug-in API. The server plug-in API includes the following functions:

Each section summarizes the front-end functions in a table followed by the function details.

Distribution Routines

This section contains reference information on distribution routines.

Table 15-1 Distribution Routines


Function	Description
distribution_plugin_entry_point()	Allows for backend distribution.

distribution_plugin_entry_point()

Allows for backend distribution.

Syntax

#include "slapi-plugin.h"
int distribution_plugin_entry_point (Slapi_PBlock *pb,
Slapi_DN *target_dn, char **mtn_be_names, int be_count,
Slapi_DN * node_dn);

Parameters

This function takes the following parameters:

pb	Pointer to the parameter block of the operation.
target_dn	Pointer to the target DN of the operation.
mtn_be_names	Pointer to the list of names of backends declared for this node.
be_count	The number of backends declared under a specified DIT node.
node_dn	DN of the node where the distribution function is set.

Returns

This function should return the index of the backend in the mtn_be_names table that is used to resolve the current operation. For search operations, SLAPI_BE_ALL_BACKENDS can be returned to specify that backends must be searched. The use of SLAPI_BE_ALL_BACKENDS for non-search operations is not supported and may give random results.

Description

Backend distribution is the capability to span the LDAP subtree contents under a specified DIT node into multiple backends in the same server and/or database links to other servers. Under such a configuration, this function is responsible for deciding where the database or database link under the DIT node will be applied. This function will be called for ever operation reaching a DIT node, including subtree search operations that are started above the node.

This function can only be called if the server has been configured to take advantage of such capability.

Functions for Access Control

This section contains reference information on access control routines.

Table 15-2 Access Control Routines


Function	Description
slapi_access_allowed()	Determines if the user who is requesting the current operation has the access rights to perform an operation on a given entry, attribute, or value.
slapi_acl_check_mods()	Determines if a user has the rights to perform the specified modifications on an entry.
slapi_acl_verify_aci_syntax()	Determines whether or not the access control items (ACIs) on an entry are valid.

slapi_access_allowed()

Determines if a user (who is requesting the current operation) has the access rights to perform an operation on a given entry, attribute, or value.

Syntax

#include "slapi-plugin.h"
int slapi_access_allowed( Slapi_PBlock *pb, Slapi_Entry *e,
char *attr, struct berval *val, int access );

Parameters

This function takes the following parameters:

pb	Parameter block passed into this function.
e	Entry for which you want to check the access rights.
attr	Attribute for which you want to check the access rights.
val	Pointer to the berval structure containing the value for which you want to check the access rights.
access	Type of access rights for which you want to check; for example, to check for write access, pass SLAPI_ACL_WRITE as the value of this argument.

The value of the access argument can be one of the following:

SLAPI_ACL_ADD	Permission to add a specified entry.
SLAPI_ACL_COMPARE	Permission to compare the specified values of an attribute in an entry.
SLAPI_ACL_DELETE	Permission to delete a specified entry.
SLAPI_ACL_READ	Permission to read a specified attribute.
SLAPI_ACL_SEARCH	Permission to search on a specified attribute or value.
SLAPI_ACL_WRITE	Permission to write a specified attribute or value or permission to rename a specified entry.

Returns

This function returns one of the following values:

LDAP_SUCCESS if the user has the specified rights to the entry, attribute, or value.
LDAP_INSUFFICIENT_ACCESS if the user does not have the specified rights to the entry, attribute, or value.
If a problem occurs during processing, the function will return one of the following error codes:

LDAP_OPERATIONS_ERROR
      

An error occurred while executing the operation.

This error can occur if, for example, the type of access rights you've specified are not recognized by the server (in other words, you did not pass a value from the previous table).

LDAP_INVALID_SYNTAX
      

Invalid syntax was specified.

This error can occur if the ACL associated with an entry, attribute, or value uses the wrong syntax.

LDAP_UNWILLING_TO_PERFORM
      

The Directory Server is unable to perform the specified operation.

This error can occur if, for example, you are requesting write access to a read-only database.

Description

Call this function to determine if a user has access rights to a specified entry, attribute, or value. The function performs this check for users who request the operation that invokes this plug-in.

For example, suppose you are writing a pre-operation plug-in for the add operation. You can call this function to determine if users have the proper access rights before they can add an entry to the directory.

As part of the process of determining if the user has access rights, the function does the following:

Checks to see if the user requesting the operation is the root DN.If so, the function returns LDAP_SUCCESS. (The root DN has permission to perform any operation.)
Gets information about the operation being requested, the connection to the client, and the backend database where directory information is stored.
If for some reason the function cannot determine which operation is being requested, the function returns LDAP_OPERATIONS_ERROR.
If no connection to a client exists (in other words, if the request for the operation was made by the server or its backend), the function returns LDAP_SUCCESS. (The server and its backend are not restricted by access control lists.)
If the backend database is read-only and the request is checking for write access (SLAPI_ACL_WRITE), the function returns LDAP_UNWILLING_TO_PERFORM.
Determines if the user requesting the operation is attempting to modify his or her own entry.

ACLs can be set up to allow users the rights to modify their own entries. The slapi_access_allowed() function checks for this condition.

The caller must ensure that the backend specified in the pblock is set prior to calling this function. For example:

be = slapi_be_select( slapi_entry_get_sdn_const( seObjectEntry ));
if ( NULL == be ) {
cleanup("backend selection failed for entry: \"%s\"\n",
szObjectDN);
slapi_send_ldap_result( pb, LDAP_NO_SUCH_OBJECT, NULL,
" Object could not be found", 0, NULL );
return( SLAPI_PLUGIN_EXTENDED_SENT_RESULT );
}
slapi_pblock_set( pb, SLAPI_BACKEND, be );
nAccessResult = slapi_access_allowed( pb, seObjectEntry,
"*", bval, SLAPI_ACL_DELETE);

slapi_acl_check_mods()

Determines if a user has the rights to perform the specified modifications on an entry.

Syntax

#include "slapi-plugin.h"
int slapi_acl_check_mods( Slapi_PBlock *pb, Slapi_Entry *e,
LDAPMod **mods, char **errbuf );

Parameters

This function takes the following parameters:

pb	Parameter block passed into this function.
e	Entry for which you want to check the access rights.
mods	Array of LDAPMod structures that represent the modifications to be made to the entry.
errbuf	Pointer to a string containing an error message if an error occurs during the processing of this function.

Returns

This function returns one of the following values:

LDAP_SUCCESS if the user has write permission to the values in the specified attributes.
LDAP_INSUFFICIENT_ACCESS if the user does not have write permission to the values of the specified attribute.
If a problem occurs during processing, the function will return one of the following error codes:

LDAP_OPERATIONS_ERROR
      

An error occurred while executing the operation.

This error can occur if, for example, the type of access rights you've specified are not recognized by the server (in other words, you did not pass a value from the previous table).

LDAP_INVALID_SYNTAX
      

Invalid syntax was specified.

This error can occur if the ACL associated with an entry, attribute, or value uses the wrong syntax.

LDAP_UNWILLING_TO_PERFORM
      

The Directory Server is unable to perform the specified operation.

This error can occur if, for example, you are requesting write access to a read-only database.

Description

Call this function to determine if a user has access rights to modify the specified entry. The function performs this check for users who request the operation that invokes this plug-in.

Suppose you are writing a database plug-in. You can call this function to determine if users have the proper access rights before they can add, modify, or delete entries from the database.

As part of the process of determining if the user has access rights, the slapi_access_allowed() function does the following:

Checks if access control for the directory is disabled (for example, if the dse.ldif file contains the directive accesscontrol off).

If access control is disabled, the function returns LDAP_SUCCESS.

For each value in each attribute specified in the LDAPMod array, the function determines if the user has permissions to write to that value. Essentially, the function calls slapi_access_allowed() with SLAPI_ACL_WRITE as the access right to check.
If for some reason the function cannot determine which operation is being requested, the function returns LDAP_OPERATIONS_ERROR.
If no connection to a client exists (in other words, if the request for the operation was made by the server or its backend), the function returns LDAP_SUCCESS. (The server and its backend are not restricted by access control lists.)
If the backend database is read-only and the request is checking for write access (SLAPI_ACL_WRITE), the function returns LDAP_UNWILLING_TO_PERFORM.

Memory Concerns

You must free the errbuf buffer by calling slapi_ch_free() when you are finished using the error message.

See Also

slapi_ch_free()

Functions for Internal Operations and Plug-in Callback

This section contains reference information on routines for internal operations and plug-in callbacks. These functions can be used for internal operations based on DN as well as on unique ID. These functions should be used by all new plug-ins, and, preferably, old plug-ins should be changed to use them to take advantage of new plug-in configuration capabilities and to use an extensible interface.

Table 15-3 Internal Operations and Plug-in Callback Routines


Function	Description
slapi_add_internal_pb()	Performs an LDAP add operation based on a parameter block to add a new directory entry.
slapi_delete_internal_pb()	Performs an LDAP delete operation based on a parameter block to remove a directory entry.
slapi_free_search_results_internal()	Frees search results.
slapi_modify_internal_pb()	Performs an LDAP modify operation based on a parameter block to modify a directory entry.
slapi_modrdn_internal_pb()	Performs an LDAP modify RDN operation based on a parameter block to rename a directory entry.
slapi_search_internal_callback_pb()	Performs an LDAP search operation based on a parameter block to search the directory.
slapi_search_internal_get_entry()	Performs an internal search operation to read one entry.
slapi_search_internal_pb()	Performs an LDAP search operation based on a parameter block to search the directory.

slapi_add_internal_pb()

Adds an LDAP add operation based on a parameter block to add a new directory entry.

Syntax

#include "slapi-plugin.h"
int slapi_add_internal_pb(Slapi_PBlock *pb);

Parameters

This function takes the following parameter:

pb	A parameter block that has been initialized using slapi_add_internal_set_pb().

Returns

This function returns one of the following values:

0 if successful.
-1 if an error occurs. If -1 is returned, the SLAPI_PLUGIN_INTOP_RESULT field of the parameter block should be consulted to determine the precise LDAP result code.

Description

The function performs an internal add operation based on a parameter block. The parameter block should be initialized by calling slapi_add_internal_set_pb() or slapi_add_entry_internal_set_pb().

Memory Concerns

None of the parameters that are passed slapi_add_internal_set_pb() are altered or consumed by this function. The entry parameter that is passed to slapi_add_entry_internal_set_pb() is consumed by a successful call to this function.

slapi_delete_internal_pb()

Performs an LDAP delete operation based on a parameter block to remove a directory entry.

Syntax

#include "slapi-plugin.h"
int slapi_delete_internal_pb(Slapi_PBlock *pb);

Parameters

This function takes the following parameter:

pb	A parameter block that has been initialized using slapi_delete_internal_set_pb().

Returns

This function returns one of the following values:

0 if successful.
-1 if an error occurs. If -1 is returned, the SLAPI_PLUGIN_INTOP_RESULT field of the parameter block should be consulted to determine the precise LDAP result code.

Description

This function performs an internal delete operation based on a parameter block. The parameter block should be initialized by calling slapi_delete_internal_set_pb().

Memory Concerns

None of the parameters that are passed to slapi_delete_internal_set_pb() are altered or consumed by this function.

slapi_free_search_results_internal()

Frees search results returned by the slapi_search_internal_pb() and slapi_search_internal_callback_pb() functions.

Syntax

#include "slapi-plugin.h"
void slapi_free_search_results_internal(Slapi_PBlock *pb);

Parameters

This function takes the following parameters:

pb	Parameter block returned by the slapi_search_internal_pb() and slapi_search_internal_callback_pb() functions.

Description

This function must be called when you are finished with the entries before freeing the pblock.

slapi_modify_internal_pb()

Performs an LDAP modify operation based on a parameter block to modify a directory entry.

Syntax

#include "slapi-plugin.h"
int slapi_modify_internal_pb(Slapi_PBlock *pb);

Parameters

This function takes the following parameter:

pb	A parameter block that has been initialized using slapi_modify_internal_set_pb().

Returns

This function returns one of the following values:

0 if successful.
-1 if an error occurs. If -1 is returned, the SLAPI_PLUGIN_INTOP_RESULT field of the parameter block should be consulted to determine the precise LDAP result code.

Description

This function performs an internal modify operation based on a parameter block. The parameter block should be initialized by calling slapi_modify_internal_set_pb().

Memory Concerns

None of the parameters that are passed to slapi_modify_internal_set_pb() are altered or consumed by this function.

slapi_modrdn_internal_pb()

Performs an LDAP modify RDN operation based on a parameter block to rename a directory entry.

Syntax

#include "slapi-plugin.h"
int slapi_modrdn_internal_pb(Slapi_PBlock *pb);

Parameters

This function takes the following parameter:

pb	A parameter block that has been initialized using slapi_rename_internal_set_pb().

Returns

This function returns one of the following values:

0 if successful.
-1 if an error occurs. If -1 is returned, the SLAPI_PLUGIN_INTOP_RESULT field of the parameter block should be consulted to determine the precise LDAP result code.

Description

This function performs an internal modify RDN operation based on a parameter block. The parameter block should be initialized by calling slapi_rename_internal_set_pb().

Memory Concerns

None of the parameters that are passed to slapi_modrdn_internal_set_pb() are altered or consumed by this function.

slapi_search_internal_callback_pb()

Performs an LDAP search operation based on a parameter block to search the directory. Unlike slapi_search_internal_pb(), this function allows you to specify callback functions that are invoked when the search operation finds matching entries or entries with referrals.

Syntax

#include "slapi-plugin.h"
int slapi_search_internal_callback_pb(Slapi_PBlock *pb,
void *callback_data,plugin_result_callback prc,
plugin_search_entry_callback psec,
plugin_referral_entry_callback prec);

Parameters

This function takes the following parameters:

pb	A parameter block that has been initialized using slapi_seq_internal_callback_set_pb().
callback_data	A pointer to arbitrary plug-in or operation-specific data that you would like to pass to your callback functions.
prc	Callback function that the server calls to send result codes. The function must have the prototype specified by plugin_result_callback.
psec	Callback function that the server calls when finding a matching entry in the directory. The function must have the prototype specified by plugin_search_entry_callback.
prec	Callback function that the server calls when finding an entry that contains LDAPv3 referrals. The function must have the prototype specified by plugin_referral_entry_callback.

Returns

This function returns one of the following values:

0 if successful.
-1 if an error occurs. If -1 is returned, the SLAPI_PLUGIN_INTOP_RESULT field of the parameter block should be consulted to determine the precise LDAP result code.

Description

Like slapi_search_internal_pb(), this function allows you to search the directory from a plug-in function. Unlike a search operation requested by a client, no result code, search entries, or referrals are sent to a client by slapi_search_internal_callback_pb(). However, you can write your own callback functions that are invoked when these events occur:

You can write a callback function that is invoked when the search operation normally sends a result code to the client.

This function must have the prototype specified by plugin_result_callback. You specify this function in the prc argument of slapi_search_internal_callback_pb().

You can write a callback function that is invoked when the search operation normally sends a search entry to the client.

This function must have the prototype specified by plugin_search_entry_callback. You specify this function in the psec argument of slapi_search_internal_callback_pb().

You can write a callback function that is invoked when the search operation normally sends LDAPv3 search result references.

This function must have the prototype specified by plugin_referral_entry_callback. You specify this function in the prec argument of slapi_search_internal_callback_pb(). You can also pass arbitrary plug-in or operation-specific data to these callback functions. Specify the data that you want to pass as the callback_data argument of slapi_search_internal_callback_pb().

Memory Concerns

The entries passed to the search entry callback function do not need to be freed. If you need to access an entry after returning from the callback function, call slapi_entry_dup() to make a copy.

The referral URLs passed to the referral entry callback function do not need to be freed. If you need to access a referral string after returning from the callback function, call slapi_ch_strdup() to make a copy.

You do not need to call slapi_free_search_results_internal() after calling slapi_search_internal_callback_pb().

slapi_search_internal_get_entry()

Performs an internal search operation to read one entry; it performs a base object search.

Syntax

#include "slapi-plugin.h"
int slapi_search_internal_get_entry( Slapi_DN *dn,
char ** attrlist, Slapi_Entry **ret_entry, void *caller_identity);

Parameters

This function takes the following parameter:

dn	The DN of the entry to be read.
attrlist	A NULL terminated array of attribute types to return from entries that match filter. If you specify a NULL, all attributes will be returned.
ret_entry	The address of a Slapi_Entry pointer to receive the entry if it is found.
caller_identity	A plug-in or component identifier. This value can be obtained from the SLAPI_PLUGIN_IDENTITY field of the parameter block that is passed to your plug-in initialization function.

Returns

This function returns the LDAP result code for the search operation.

Description

This function performs an internal search operation to read one entry; that is, it preforms a base object search. If an entry named by dn is found, the ret_entry pointer will be set to point to a copy of the entry that contains the attribute values specified by the attrlist parameter.

Memory Concerns

The returned entry (*ret_entry) should be freed by calling slapi_entry_free().

See Also

slapi_search_internal_pb()

slapi_entry_free()

slapi_search_internal_pb()

Performs an LDAP search operation based on a parameter block to search the directory.

Syntax

#include "slapi-plugin.h"
int slapi_search_internal_pb(Slapi_PBlock *pb);

Parameters

This function takes the following parameter:

pb	A parameter block that has been initialized using slapi_search_internal_set_pb().

Returns

This function returns one of the following values:

0 if successful.
-1 if an error occurs. If -1 is returned, the SLAPI_PLUGIN_INTOP_RESULT field of the parameter block should be consulted to determine the precise LDAP result code.

Description

This function performs an internal search based on a parameter block. The parameter block should be initialized by calling the slapi_search_internal_set_pb() function.

Memory Concerns

slapi_free_search_results_internal() should be called to dispose of any entires and other items that were allocated by a call to slapi_search_internal_pb().

Functions for Setting Internal Operation Flags

This section contains reference information on routines for setting internal-operation flags.

Table 15-4 Internal Operation Flag Routines


Function	Description
slapi_add_entry_internal_set_pb()	Sets up a parameter block so that it can be used by slapi_add_internal_pb() for an internal add operation.
slapi_add_internal_set_pb()	Sets up a parameter block so that it can be used by slapi_add_internal_pb() for an internal add operation; the entry is constructed from a DN and a set of attributes.
slapi_delete_internal_set_pb()	Sets up a parameter block so that it can be used by slapi_delete_internal_pb() for an internal delete operation.
slapi_modify_internal_set_pb()	Sets up a parameter block so that it can be used by slapi_modify_internal_pb() for an internal modify operation.
slapi_rename_internal_set_pb()	Sets up a parameter block so that it can be used by slapi_modrdn_internal_pb() for an internal rename operation.
slapi_search_internal_set_pb()	Sets up a parameter block so that it can be used by slapi_search_internal_pb() for an internal search operation.
slapi_seq_internal_callback_pb()	Performs an internal sequential access operation.
slapi_seq_internal_set_pb()	Sets up a parameter block for use by slapi_seq_internal_callback_pb() for an internal sequential-access operation.

slapi_add_entry_internal_set_pb()

Sets up a parameter block so that it can be used by slapi_add_internal_pb() for an internal add operation.

Syntax

#include "slapi-plugin.h"
void slapi_add_entry_internal_set_pb(Slapi_PBlock *pb,
Slapi_Entry *e, LDAPControl **controls,
Slapi_ComponentId *plugin_identity, int operation_flags);

Parameters

This function takes the following parameters:

pb	Parameter block populated with add parameters.
e	Entry to be added.
controls	List of controls associated with the operation.
plugin_identity	Plug-in identity; a cookie that identifies the plug-in to the Directory Server during an internal operation. This cookie is used by the server to retrieve the plug-in configuration in order to determine whether to allow the operation and which actions to take during the operation processing. Plug-in identity is passed to the plug-in initialization function in the SLAPI_PLUGIN_IDENTITY pblock parameter. A plug-in must save this information and pass it to every internal operation issued by the plug-in.
operation_flags	Actions taken during operation processing.

Description

This function populates parameters in the pblock structure so that it can be used by slapi_add_internal_pb() for an internal add operation.

slapi_add_internal_set_pb()

Sets up a parameter block so that it can be used by slapi_add_internal_pb() for an internal add operation.

Syntax

#include "slapi-plugin.h"
int slapi_add_internal_set_pb(Slapi_PBlock *pb, const char *dn,
LDAPMod **attrs, LDAPControl **controls,
Slapi_ComponentId *plugin_identity, int operation_flags);

Parameters

This function takes the following parameters:

pb	Parameter block populated with add parameters.
dn	Entry DN.
attrs	Entry attributes.
controls	List of controls associated with the operation.
plugin_identity	Plug-in identity; a cookie that identifies the plug-in to the Directory Server during an internal operation. This cookie is used by the server to retrieve the plug-in configuration in order to determine whether to allow the operation and which actions to take during the operation processing. Plug-in identity is passed to the plug-in initialization function in the SLAPI_PLUGIN_IDENTITY pblock parameter. A plug-in must save this information and pass it to every internal operation issued by the plug-in.
operation_flags	Actions taken during operation processing.

Description

This function is similar to slapi_add_entry_internal_set_pb() except that it constructs the entry from a DN and a set of attributes. The function sets pblock to contain the following data:

SLAPI_TARGET_DN set to DN of the new entry.
SLAPI_CONTROLS_ARG set to request controls, if present.
SLAPI_ADD_ENTRY set to Slapi_Entry to add.

Returns

This function returns LDAP_SUCCESS or one of the LDAP error codes if the entry cannot be constructed from the specified attributes due to constraint violation.

slapi_delete_internal_set_pb()

Sets up a parameter block so that it can be used by slapi_delete_internal_pb() for an internal delete operation.

Syntax

#include "slapi-plugin.h"
void slapi_delete_internal_set_pb (Slapi_PBlock *pb, const char *dn,
LDAPControl **controls, const char *uniqueid,
Slapi_ComponentId *plugin_identity, int operation_flags);

Parameters

This function takes the following parameters:

pb	Parameter block populated with delete parameters.
dn	DN of the entry to be removed. For unique ID operation, this parameter is used to select the correct backend.
controls	List of controls associated with the operation.
uniqueid	Unique identifier of the entry to be removed. All directory entries contain a unique identifier. Unlike the distinguished name (DN), the unique identifier of an entry never changes, providing a good way to refer unambiguously to an entry in a distributed/replicated environment.
plugin_identity	Plug-in identity; a cookie that identifies the plug-in to the Directory Server during an internal operation. This cookie is used by the server to retrieve the plug-in configuration in order to determine whether to allow the operation and which actions to take during the operation processing. Plug-in identity is passed to the plug-in initialization function in the SLAPI_PLUGIN_IDENTITY pblock parameter. A plug-in must save this information and pass it to every internal operation issued by the plug-in.
operation_flags	Actions taken during operation processing.

Description

This function populates pblock to contain data for use by slapi_delete_internal_pb() for an internal delete operation.

For unique identifier-based operation:

SLAPI_TARGET_DN set to the DN that allows to select the right backend.
SLAPI_TARGET_UNIQUEID set to the unique ID of the entry.
SLAPI_CONTROLS_ARG set request controls, if present.

For DN-based search:

SLAPI_TARGET_DN set to the entry DN.
SLAPI_CONTROLS_ARG set to request controls, if present.

slapi_modify_internal_set_pb()

Sets up a parameter block so that it can be used by slapi_modify_internal_pb() for an internal modify operation.

Syntax

#include "slapi-plugin.h"
void slapi_modify_internal_set_pb(Slapi_PBlock *pb, const char *dn,
LDAPMod **mods, LDAPControl **controls, const char *uniqueid,
Slapi_ComponentId *plugin_identity, int operation_flags);

Parameters

This function takes the following parameters:

pb	Parameter block populated with modify parameters.
dn	DN of the entry to be modified. For unique ID operation, this parameter is used to select the correct backend.
mods	Modifications to be applied to the entry.
controls	List of controls associated with the operation.
uniqueid	Unique identifier of the entry to be modified. All directory entries contain a unique identifier. Unlike the distinguished name (DN), the unique identifier of an entry never changes, providing a good way to refer unambiguously to an entry in a distributed/replicated environment.
plugin_identity	Plug-in identity; a cookie that identifies the plug-in to the Directory Server during an internal operation. This cookie is used by the server to retrieve the plug-in configuration in order to determine whether to allow the operation and which actions to take during the operation processing. Plug-in identity is passed to the plug-in initialization function in the SLAPI_PLUGIN_IDENTITY pblock parameter. A plug-in must save this information and pass it to every internal operation issued by the plug-in.
operation_flags	Actions taken during operation processing.

Description

This function populates pblock to contain data for use by slapi_modify_internal_pb() for an internal modify operation.

For unique ID-based operation:

SLAPI_TARGET_DN set to the DN that allows to select the right backend.
SLAPI_TARGET_UNIQUEID set to the unique ID of the entry.
SLAPI_MODIFY_MODS set to the mods.
SLAPI_CONTROLS_ARG set to request controls, if present.

For DN-based search:

SLAPI_TARGET_DN set to the entry DN.
SLAPI_MODIFY_MODS set to the mods.
SLAPI_CONTROLS_ARG set to request controls, if present.

slapi_rename_internal_set_pb()

Sets up a parameter block so that it can be used by slapi_modrdn_internal_pb() for an internal rename operation.

Syntax

#include "slapi-plugin.h"
void slapi_rename_internal_set_pb(Slapi_PBlock *pb,
const char *olddn, const char *newrdn, const char *newsuperior,
int deloldrdn, LDAPControl **controls, const char *uniqueid,
Slapi_ComponentId *plugin_identity, int operation_flags);

Parameters

This function takes the following parameters:

pb	Parameter block populated with rename parameters.
olddn	DN of the entry to be renamed. For unique ID operation, this parameter is used to select the correct backend.
newrdn	New RDN of the entry.
newsuperior	New entry superior, moddn operation only.
deloldrdn	Specifies whether the old RDN should be removed or left as a non-DN attribute.
controls	List of controls associated with the operation.
uniqueid	Unique identifier of the entry to be renamed. All directory entries contain a unique identifier. Unlike the distinguished name (DN), the unique identifier of an entry never changes, providing a good way to refer unambiguously to an entry in a distributed/replicated environment.
plugin_identity	Plug-in identity; a cookie that identifies the plug-in to the Directory Server during an internal operation. This cookie is used by the server to retrieve the plug-in configuration in order to determine whether to allow the operation and which actions to take during the operation processing. Plug-in identity is passed to the plug-in initialization function in the SLAPI_PLUGIN_IDENTITY pblock parameter. A plug-in must save this information and pass it to every internal operation issued by the plug-in.
operation_flags	Actions taken during operation processing.

Description

This function populates pblock with parameters for use by slapi_modrdn_internal_pb() for an internal rename operation. The function sets the parameter block to contain the following data.

For unique ID-based operation:

SLAPI_TARGET_DN set to the DN that allows to select the right backend.
SLAPI_TARGET_UNIQUEID set to the uniqueid of the entry.
SLAPI_MODRDN_NEWRDN set to the new RDN of the entry.
SLAPI_MODRDN_DELOLDRDN indicates whether the old RDN should be kept in the entry.
SLAPI_CONTROLS_ARG set to request controls, if present.

For DN-based search:

SLAPI_TARGET_DN set to the entry DN.
SLAPI_MODRDN_NEWRDN set to the new RDN of the entry.
SLAPI_MODRDN_DELOLDRDN indicates whether the old RDN should be kept in the entry.
SLAPI_CONTROLS_ARG set to request controls, if present.

slapi_search_internal_set_pb()

Sets up a parameter block so that it can be used by slapi_search_internal_pb() for an internal search operation.

Syntax

#include "slapi-plugin.h"
void slapi_search_internal_set_pb(Slapi_PBlock *pb,
const char *base, int scope, const char *filter, char **attrs,
int attrsonly, LDAPControl **controls, const char *uniqueid,
Slapi_ComponentId *plugin_identity, int operation_flags);

Parameters

This function takes the following parameters:

pb	Parameter block that is populated with search parameters.
base	Search base.
scope	Search scope (LDAP_SCOPE_SUBTREE, etc.).
filter	Search filter.
attrs	Attributes to be returned.
attrsonly	Flag specifying whether to return just attribute names or names and values.
controls	List of controls associated with the operation.
uniqueid	Unique identifier of the entry. Non-NULL value indicates unique ID-based search. In this case, scope and filter are ignored; however, base is still required and is used to select the correct backend. All directory entries contain a unique identifier. Unlike the distinguished name (DN), the unique identifier of an entry never changes, providing a good way to refer unambiguously to an entry in a distributed/replicated environment.
plugin_identity	Plug-in identity; a cookie that identifies the plug-in to the Directory Server during an internal operation. This cookie is used by the server to retrieve the plug-in configuration in order to determine whether to allow the operation and which actions to take during the operation processing. Plug-in identity is passed to the plug-in initialization function in the SLAPI_PLUGIN_IDENTITY pblock parameter. A plug-in must save this information and pass it to every internal operation issued by the plug-in.
operation_flags	Actions taken during operation processing.

Description

This function sets up the parameter block, for subsequent use by slapi_search_internal_pb(), to contain the following data for an internal search operation.

For unique ID-based search:

SLAPI_TARGET_DN set to the DN that allows to select the right backend.
SLAPI_TARGET_UNIQUEID set to the unique ID of the entry.

For DN-based search:

SLAPI_TARGET_DN set to the search base.
SLAPI_SEARCH_SCOPE set to the search scope.
SLAPI_SEARCH_STRFILTER set to the search filter.
SLAPI_CONTROLS_ARG set to request controls, if present.
SLAPI_SEARCH_ATTRS set to the list of attributes to return.
SLAPI_SEARCH_ATTRSONLY indicates whether attribute values should be returned.

slapi_seq_internal_callback_pb()

Performs internal sequential access operation.

Syntax

#include "slapi-plugin.h"
int slapi_seq_internal_callback_pb(Slapi_PBlock *pb,
void *callback_data, plugin_result_callback res_callback,
plugin_search_entry_callback srch_callback,
plugin_referral_entry_callback ref_callback);

Parameters

This function takes the following parameters:

pb	Parameter block initialized with operation parameters. The easiest way to provide required parameters is by calling slapi_seq_internal_set_pb() function. Parameters can also be set directly.
callback_data	Data passed to the callback functions.
res_callback	Function called once the search is complete.
srch_callback	Function called for each entry returned.
ref_callback	Function called for each referral returned.

Description

This function performs internal sequential access operation.

Returns

This function returns 0 on success, -1 on error.

slapi_seq_internal_set_pb()

Sets up a parameter block for use by slapi_seq_internal_callback_pb() for an internal, sequential-access operation.

Syntax

#include "slapi-plugin.h"
void slapi_seq_internal_set_pb(Slapi_PBlock *pb, char *ibase,
int type, char *attrname, char *val, char **attrs, int attrsonly,
LDAPControl **controls, Slapi_ComponentId *plugin_identity,
int operation_flags);

Parameters

This function takes the following parameters:

Description

This function sets up pblock for use by slapi_seq_internal_callback_pb() for an internal, sequential-access operation; the function sets up the parameter block contain the following data:

SLAPI_SEARCH_TARGET set to the search base.
SAPI_SEQ_TYPE set to the sequential-access type (SLAPI_SEQ_FIRST, SLAPI_SEQ_NEXT, and so on.)
SLAPI_SEQ_ATTRNAME defines attribute value assertion relative to which access is performed.
SLAPI_SEQ_VAL defines attribute value assertion relative to which access is performed.
SLAPI_CONTROLS_ARG set to request controls, if present.
SLAPI_SEARCH_ATTRS set to t

e	Entry for which you want to check the ACIs.
errbuf	Pointer to the error message returned if the ACI syntax is invalid.