Plug-In Programmer's Guide Netscape Directory Server

Previous      Contents      Index      DocHome      Next

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:

• Distribution Routines
• Functions for Access Control
• Functions for Internal Operations and Plug-In Callback
• Functions for Setting Internal Operation Flags
• Functions for Handling Attributes
• Functions for Managing Backend Operations
• Functions for Dealing with Controls
• Functions for Syntax Plug-In
• Functions for Managing Memory
• Functions for Managing DNs
• Functions for Managing Entries
• Functions Related to Entry Flags
• Functions for Dealing with Filters
• Functions Specific to Extended Operation
• Functions Specific to Bind Methods
• Functions for Thread-Safe LDAP Connections
• Functions for Logging
• Functions for Handling Matching Rules
• Functions for LDAPMod Manipulation
• Functions for Monitoring Operations
• Functions for Managing Parameter Block
• Functions for Handling Passwords
• Functions for Managing RDN
• Functions for Managing Roles
• Functions for Managing DNs
• Functions for Sending Entries and Results to the Client
• Functions Related to UTF-8
• Functions for Handling Values
• Functions for Handling Valueset
• Functions Specific to Virtual Attribute Service
• Functions for Managing Locks and Synchronization
• Functions for Managing Computed Attributes
• Functions for Manipulating Bits
• Functions for Registering Object Extensions
• Functions Related to Data Interoperability
• Functions for Registering Additional Plug-Ins

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.

Note that 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 a 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 that you want to check for (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 DSA (this 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 back-end 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 back-end), the function returns LDAP_SUCCESS. (The server and its back-end are not restricted by access control lists.)
• If the back-end 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.
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 DSA (this 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.

For example, 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 to 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 back-end), the function returns LDAP_SUCCESS. (The server and its back-end are not restricted by access control lists.)
• If the back-end 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_access_allowed()

slapi_ch_free()

slapi_acl_verify_aci_syntax()

---

Determines whether or not the access control items (ACIs) on an entry are valid.

Syntax

#include "slapi-plugin.h"
int slapi_acl_verify_aci_syntax (Slapi_Entry *e,
  char **errbuf);

Parameters

This function takes the following parameters:

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

Returns

This function returns one of the following values:

• 0 if successful.
• -1 if an error occurs.

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 LDAP v3 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 LDAP v3 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 (that is, 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 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 unambiguously refer 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 unambiguously refer 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 unambiguously refer 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.
• LAPI_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 unambiguously refer 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 the list of attributes to return.
• SLAPI_SEARCH_ATTRSONLY indicates whether attribute values should be returned.

Functions for Handling Attributes

---

This section contains reference information on attribute routines.

Table 15-5    Attribute Routines  

Function	Description
slapi_attr_add_value()	Adds a value to an attribute.
slapi_attr_basetype()	Returns the base type of an attribute.
slapi_attr_dup()	Duplicates an attribute.
slapi_attr_first_value()	Gets the first value of an attribute.
slapi_attr_flag_is_set()	Determines if certain flags are set.
slapi_attr_free()	Frees an attribute.
slapi_attr_get_bervals_copy()	Puts the values contained in an attribute into an array of berval structures.
slapi_attr_get_flags()	Gets the flags associated with an attribute.
slapi_attr_get_numvalues()	Puts the count of values of an attribute into an integer.
slapi_attr_get_oid_copy()	Searches for an attribute type and gives its OID string.
slapi_attr_get_type()	Gets the name of the attribute type.
slapi_attr_get_valueset()	Copies attribute values into a valueset.
slapi_attr_init()	Initializes an empty attribute.
slapi_attr_new()	Creates a new attribute.
slapi_attr_next_value()	Gets the next value of an attribute.
slapi_attr_set_valueset()	Initializes a valueset in a Slapi_Attr structure from a specified Slapi_ValueSet structure.
slapi_attr_syntax_normalize()	Returns a copy of the normalized attribute types.
slapi_attr_type2plugin()	Gets information about the plug-in responsible for handling an attribute type.
slapi_attr_type_cmp()	Compares two attributes.
slapi_attr_types_equivalent()	Compares two attribute names to determine if they represent the same attribute.
slapi_attr_value_cmp()	Compares two attribute values.
slapi_attr_value_find()	Determines if an attribute contains a given value.
slapi_valueset_set_from_smod()	Adds the changes in a modification to a valueset.
slapi_valueset_set_valueset()	Initializes a Slapi_ValueSet structure from another Slapi_ValueSet structure.

slapi_attr_add_value()

---

Adds a value to an attribute.

Syntax

#include "slapi-plugin.h"
int slapi_attr_add_value(Slapi_Attr *a, const Slapi_Value *v);

Parameters

This function takes the following parameters:

a	The attribute that will contain the values.
v	Values to be added to the attribute.

Returns

This function always returns 0.

See Also

slapi_attr_first_value()

slapi_attr_next_value()

slapi_attr_get_numvalues()

slapi_attr_value_cmp()

slapi_attr_value_find()

slapi_attr_basetype()

---

Returns the base type of an attribute (for example, if given cn;lang-jp, returns cn).

Syntax

#include "slapi-plugin.h"
char *slapi_attr_basetype( char *type, char *buf,
  size_t bufsiz );

Parameters

This function takes the following parameters:

type	Attribute type from which you want to get the base type.
buf	Buffer to hold the returned base type.
bufsiz	Size of the buffer.

Returns

This function returns NULL if the base type fits in the buffer. If the base type is longer than the buffer, the function allocates memory for the base type and returns a pointer to it.

Description

This function returns the base type of an attribute (for example, if given cn;lang-jp, returns cn).

Memory Concerns

You should free the returned base type when done by calling slapi_ch_free().

See Also

slapi_attr_type2plugin()

slapi_attr_get_type()

slapi_attr_type_cmp()

slapi_attr_types_equivalent()

slapi_attr_dup()

---

Duplicates an attribute.

Syntax

#include "slapi-plugin.h"
Slapi_Attr *slapi_attr_dup(const Slapi_Attr *attr);

Parameters

This function takes the following parameters:

attr	The attribute to be duplicated.

Returns

This function returns the newly created copy of the attribute.

Description

Use this function to make a copy of an attribute.

Memory Concerns

You must free the returned attribute using slapi_attr_free().

See Also

slapi_attr_new()

slapi_attr_init()

slapi_attr_free()

slapi_attr_first_value()

---

Gets the first value of an attribute.

Syntax

#include "slapi-plugin.h"
int slapi_attr_first_value( Slapi_Attr *a, Slapi_Value **v );

Parameters

This function takes the following parameters:

a	Attribute containing the desired value.
v	Holds the first value of the attribute.

Returns

This function returns one of the following values:

• 0, which is the index of the first value.
• -1 if NULL, or if the value hint is not found.

Description

Use this function to get the first value of an attribute. This is part of a set of functions to enumerate over an Slapi_Attr structure.

See Also

slapi_attr_next_value()

slapi_attr_get_numvalues()

slapi_attr_flag_is_set()

---

Determines if certain flags are set for a particular attribute. These flags can identify an attribute as a single-valued attribute, an operational attribute, or as a read-only attribute.

Syntax

#include "slapi-plugin.h"
int slapi_attr_flag_is_set( Slapi_Attr *attr, unsigned long flag );

Parameters

This function takes the following parameters:

attr	Attribute that you want to check.
flag	Flag that you want to check in the attribute.

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

SLAPI_ATTR_FLAG_SINGLE	Flag that determines if the attribute is single-valued.
SLAPI_ATTR_FLAG_OPATTR	Flag that determines if the attribute is an operational attribute.
SLAPI_ATTR_FLAG_READONLY	Flag that determines if the attribute is read-only.

Returns

This function returns one of the following values:

• 1 if the specified flag is set.
• 0 if the specified flag is not set.

Description

This function determines if certain flags are set for a particular attribute. These flags can identify an attribute as a single-valued attribute, an operational attribute, or as a read-only attribute.

See Also

slapi_attr_get_flags()

slapi_attr_free()

---

Frees an attribute.

Syntax

#include "slapi-plugin.h"
void slapi_attr_free( Slapi_Attr **a );

Parameters

This function takes the following parameters:

a	Attribute to be freed.

Description

Use this function to free an attribute when you are finished with it.

See Also

slapi_attr_new()

slapi_attr_init()

slapi_attr_dup()

slapi_attr_get_bervals_copy()

---

Puts the values contained in an attribute into an array of berval structures.

Syntax

#include "slapi-plugin.h"
int slapi_attr_get_bervals_copy( Slapi_Attr *a,
  struct berval ***vals );

Parameters

This function takes the following parameters:

a	Attribute that contains the desired values.
vals	Pointer to an array of berval structure pointers to hold the desired values.

Returns

This function returns one of the following values:

• 0 if values are found.
• -1 if NULL.

Description

This function copies the values from an attribute into an array of berval structure pointers.

Memory Concerns

You should free this array using ber_bvecfree from the LDAP SDK for C.

slapi_attr_get_flags()

---

Gets the flags associated with the specified attribute. These flags can identify an attribute as a single-valued attribute, an operational attribute, or as a read-only attribute.

Syntax

#include "slapi-plugin.h"
int slapi_attr_get_flags( Slapi_Attr *attr, unsigned long *flags );

Parameters

This function takes the following parameters:

attr	Attribute for which you want to get the flags.
flags	When you call slapi_attr_get_flags(), this parameter is set to a pointer to the flags of the specified attribute. Do not free the flags; the flags are part of the actual data in the attribute, not a copy of the data.

To determine which flags have been set, you can bitwise AND the value of the flags argument with one or more of the following:

SLAPI_ATTR_FLAG_SINGLE	Flag that determines if the attribute is single-valued.
SLAPI_ATTR_FLAG_OPATTR	Flag that determines if the attribute is an operational attribute.
SLAPI_ATTR_FLAG_READONLY	Flag that determines if the attribute is read-only.

Returns

This function returns 0 if successful.

Description

This function gets the flags associated with the specified attribute. These flags can identify an attribute as a single-valued attribute, an operational attribute, or as a read-only attribute.

See Also

slapi_attr_flag_is_set()

slapi_attr_get_numvalues()

---

Puts the count of values of an attribute into a provided integer.

Syntax

#include "slapi-plugin.h"
int slapi_attr_get_numvalues( const Slapi_Attr *a, int *numValues);

Parameters

This function takes the following parameters:

a	Attribute containing the values to be counted.
numValues	Integer to hold the counted values.

Returns

This function always returns 0.

Description

This function counts the number of values in an attribute and places that count in an integer.

See Also