Plug-in Programmer’s Guide
Red Hat Directory Server                                                            
Previous
 Contents
 Index
 Next

Chapter 15

Function Reference

This chapter contains reference information on Red Hat 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 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_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:

If so, the function returns LDAP_SUCCESS. (The root DN has permission to perform any operation.)

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_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 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:

If access control is disabled, the function returns LDAP_SUCCESS.

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 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:

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:

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:

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:

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:

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:

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:

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().
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().
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:

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:

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:

For DN-based search:

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:

For DN-based search:

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:

For DN-based search:

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:

For DN-based search:

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:

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:

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( const 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:

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:

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( const 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 

slapi_attr_first_value()
 
slapi_attr_next_value()

slapi_attr_get_oid_copy()

Searches the syntaxes for an attribute type, and returns a copy of its OID string.

Syntax 

#include "slapi-plugin.h"

int slapi_attr_get_oid_copy( const Slapi_Attr *attr, char **oidp );

Parameters

This function takes the following parameters: 

attr
Attribute that contains the desired type.
 
oidp
Destination string of the copied attribute type OID.

Returns

This function returns one of the following values:

Description

This function replaces the deprecated function, slapi_attr_get_oid. Use this function to search the syntaxes for an attribute type's OID.

Memory Concerns

You should free this string using slapi_ch_free().

slapi_attr_get_type()

Gets the name of the attribute type from a specified attribute.

Syntax 

#include "slapi-plugin.h" 

int slapi_attr_get_type( Slapi_Attr *attr, char **type );

Parameters

This function takes the following parameters:

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

Returns

This function returns 0 if successful.

See Also 

slapi_attr_type2plugin()
 
slapi_attr_type_cmp()
 
slapi_attr_types_equivalent()
 
slapi_attr_basetype()

slapi_attr_get_valueset()

Copies existing values contained in an attribute into a valueset.

Syntax 

#include "slapi-plugin.h"

int slapi_attr_get_valueset(const Slapi_Attr *a, 

  Slapi_ValueSet **vs);

Parameters

This function takes the following parameters: 

a
Attribute containing the values to be placed into a valueset.
 
vs
Receives values from the first parameter.

Returns

This function always returns 0.

See Also 

slapi_entry_add_valueset()
 
slapi_valueset_new()
 
slapi_valueset_free()
 
slapi_valueset_init()
 
slapi_valueset_done()
 
slapi_valueset_add_value()
 
slapi_valueset_first_value()
 
slapi_valueset_next_value()
 
slapi_valueset_count()

slapi_attr_init()

Initializes an empty attribute with a base type.

Syntax 

#include "slapi-plugin.h"

Slapi_Attr *slapi_attr_init(Slapi_Attr *a, const char *type);

Parameters

This function takes the following parameters: 

a
The empty attribute to be initialized.
 
type
Attribute type to be initialized.

Returns

This function returns the newly-initialized attribute.

Description

Use this function to initialize an empty attribute with an attribute type.

See Also 

slapi_attr_new()
 
slapi_attr_free()
 
slapi_attr_dup()

slapi_attr_new()

Creates a new attribute.

Syntax 

#include "slapi-plugin.h"

Slapi_Attr *slapi_attr_new( void );

Parameters

This function takes no parameters.

Returns

This function returns the newly-created attribute.

Description

Use this function to create an empty attribute.

See Also 

slapi_attr_free()
 
slapi_attr_dup()

slapi_attr_next_value()

Gets the next value of an attribute.

Syntax 

#include "slapi-plugin.h"

int slapi_attr_next_value( Slapi_Attr *a, int hint, 

  Slapi_Value **v );

Parameters

This function takes the following parameters: 

a
Attribute contained the desired value.
 
hint
Index of the value to be returned.
 
v
Holds the value of the attribute.

Returns

This function returns one of the following values:

Description

Use this function to get the next value of an attribute. The value of an attribute associated with an index is placed into a value. This is part of a set of functions to enumerate over a Slapi_Attr structure.

See Also 

slapi_attr_first_value()
 
slapi_attr_get_numvalues()

slapi_attr_set_valueset()

Initializes a valueset in a Slapi_Attr structure from a specified Slapi_ValueSet structure.

Syntax 

#include "slapi-plugin.h"

int slapi_attr_set_valueset(Slapi_Attr *a, 

  const Slapi_ValueSet *vs);

Parameters

This function takes the following parameters: 

a
Pointer to the Slapi_Attr structure, the valueset of which you wish to set.
 
vs
Pointer to the Slapi_ValueSet structure from which you want to extract the values.

Returns

This function returns 0 unconditionally.

Description

This function initializes a valueset in a Slapi_Attr structure from a specified Slapi_ValueSet structure; the valueset in Slapi_Attr will be *vs, not a copy.

See Also 

slapi_valueset_set_valueset()

slapi_attr_syntax_normalize()

Searches for an attribute type in the syntaxes, and returns a copy of the normalized attribute types.

Syntax 

#include "slapi-plugin.h"

char * slapi_attr_syntax_normalize( const char *s );

Parameters

This function takes the following parameters: 

s
Attribute type for which you wish to search.

Returns

This function returns the copy of the desired normalized attribute or a normalized copy of what was passed in.

Description

Use this function to search the syntaxes for an attribute type and return its normalized form.

Memory Concerns

You should free the returned string using slapi_ch_free().

See Also 

slapi_ch_free()

slapi_attr_type2plugin()

Gets a pointer to information about the syntax plug-in responsible for handling the specified attribute type.

Syntax 

#include "slapi-plugin.h" 

int slapi_attr_type2plugin( const char *type, void **pi );

Parameters

This function takes the following parameters:

type
Type of attribute for which you want to get the plug-in.
pi
Pointer to the plug-in structure.

Returns

This function returns one of the following values:

Description

Syntax plug-ins are plug-ins that you can write to index and search for specific attribute types.

See Also 

slapi_attr_get_type()
 
slapi_attr_type_cmp()
 
slapi_attr_types_equivalent()

slapi_attr_basetype()

slapi_attr_type_cmp()

Compares two attribute types to determine if they are the same.

Syntax 

#include "slapi-plugin.h" 

int slapi_attr_type_cmp( const char *t1, const char *t2, int opt );

Parameters

This function takes the following parameters:

t1
Name of the first attribute type that you want to compare. 
t2
Name of the second attribute type that you want to compare. 
opt
One of the following values:
  • 0 - Compare the types as-is.
  • 1 - Compare only the base names of the types (for example, if the type is cn;lang-en, the function compares only the cn part of the type).
  • 2 - Ignore any options in the second type that are not in the first type. For example, if the first type is cn and the second type is cn;lang-en, the lang-en option in the second type is not part of the first type. In this case, the function considers the two types to be the same.

Returns

This function returns one of the following values:

See Also 

slapi_attr_type2plugin()
 
slapi_attr_get_type()
 
slapi_attr_types_equivalent()
 
slapi_attr_basetype()

slapi_attr_types_equivalent()

Compares two attribute names to determine if they represent the same attribute.

Syntax 

#include "slapi-plugin.h"

int slapi_attr_types_equivalent( const char *t1, const char *t2 );

Parameters

This function takes the following parameters: 

t1
Pointer to the first attribute type that you want to compare.
 
t2
Pointer to the second attributed type that you want to compare.

Returns

This function returns one of the following values:

See Also 

slapi_attr_add_value()
 
slapi_attr_first_value()
 
slapi_attr_next_value()
 
slapi_attr_get_numvalues()
 
slapi_attr_value_find()

slapi_attr_value_cmp()

Compares two values for a given attribute to determine if they are equal.

Syntax 

#include "slapi-plugin.h" 

int slapi_attr_value_cmp( const Slapi_Attr *attr, const struct 
berval *v1, 

  const struct berval *v2 );

Parameters

This function takes the following parameters: 

attr
Attribute used to determine how these values are compared; for example, if the attribute contains case-insensitive strings, the strings are compared without regard to case. 
v1
Pointer to the berval structure containing the first value that you want to compare. 
v2
Pointer to the berval structure containing the second value that you want to compare.

Returns

This function returns one of the following values:

See Also 

slapi_attr_add_value()
 
slapi_attr_first_value()
 
slapi_attr_next_value()
 
slapi_attr_get_numvalues()
 
slapi_attr_value_find()

slapi_attr_value_find()

Determines is an attribute contains a given value.

Syntax 

#include "slapi-plugin.h"

int slapi_attr_value_find( const Slapi_Attr *a, const struct berval 
*v );

Parameters

This function takes the following parameters: 

a
Attribute that you want to check. 
v
Pointer to the berval structure containing the value for which you want to search.

Returns

This function returns one of the following values:

See Also 

slapi_attr_add_value()
 
slapi_attr_first_value()
 
slapi_attr_next_value()
 
slapi_attr_get_numvalues()
 
slapi_attr_value_cmp()

slapi_valueset_set_from_smod()

Adds the changes in a modification to a valueset.

Syntax 

#include "slapi-plugin.h"

void slapi_valueset_set_from_smod(Slapi_ValueSet *vs, 

  Slapi_Mod *smod);

Parameters

This function takes the following parameters: 

vs
The valueset that will receive changes.
 
smod
Holds the changes to an attribute.

Description

Use this function to create a valueset that contains the changes from smod.

See Also 

slapi_mods_init()
 
slapi_mods_free()
 
slapi_mods_done()

Functions for Managing Backend Operations

This section contains reference information on routines that help you deal with backends.

Table 15-6 Backend Routines  
Function
Description
slapi_be_addsuffix()
Adds the specified suffix to the given backend and increments the backend's suffix count.
slapi_be_delete_onexit()
Sets the flag to denote that the backend will be deleted on exiting.
slapi_be_exist()
Checks if the backend that contains the specified DN exists.
slapi_be_free()
Frees memory and linked resources from the backend structure.
slapi_be_get_instance_info()
Gets the instance information of the specified backend.
slapi_be_get_name()
Returns the name of the specified backend.
slapi_be_get_readonly()
Indicates if the database associated with the backend is in read-only mode.
slapi_be_getentrypoint()
Sets pointer to a callback function that corresponds to the specified entry point into a given backend.
slapi_be_getsuffix()
Returns the n+1 suffix associated with the specified backend.
slapi_be_gettype()
Returns the type of the backend.
slapi_be_is_flag_set()
Checks if a flag is set in the backend configuration.
slapi_be_issuffix()
Verifies that the specified suffix matches a registered backend suffix.
slapi_be_logchanges()
Indicates if the changes applied to the backend should be logged in the changelog.
slapi_be_new()
Creates a new backend structure, allocates memory for it, and initializes values for relevant parameters.
slapi_be_private()
Verifies if the backend is private.
slapi_be_select()
Finds the backend that should be used to service the entry with the specified DN.
slapi_be_select_by_instance_name()
Find the backend used to service the database.
slapi_be_set_flag()
Sets the specified flag in the backend.
slapi_be_set_instance_info()
Sets the instance information of the specified backend with given data.
slapi_be_set_readonly()
Sets a flag to denote that the backend is meant to be read-only.
slapi_be_setentrypoint()
Sets the entry point in the backend to the specified function.
slapi_get_first_backend()
Returns a pointer of the backend structure of the first backend.
slapi_get_first_suffix()
Returns the first root suffix of the DIT.
slapi_get_next_backend()
Returns a pointer to the next backend.
slapi_get_next_suffix()
Returns the DN of the next root suffix of the DIT.
slapi_is_root_suffix()
Checks if a suffix is a root suffix of the DIT.
slapi_register_backend_state_change()
Registers for callbacks when a backend changes state.
slapi_unregister_backend_state_change()
Unregisters backend-state-change callbacks.

slapi_be_addsuffix()

Adds the specified suffix to the given backend and increments the backend's suffix count.

Syntax 

#include "slapi-plugin.h"

void slapi_be_addsuffix(Slapi_Backend *be,const Slapi_DN *suffix);

Parameters

This function takes the following parameters: 

be
Pointer to the structure containing the backend configuration.
 
suffix
Suffix that needs to be added to the backend.

slapi_be_delete_onexit()

Sets the flag to denote that the backend will be deleted on exiting.

Syntax 

#include "slapi-plugin.h"

void slapi_be_delete_onexit(Slapi_Backend *be);

Parameters

This function takes the following parameter: 

be
Pointer to the structure containing the backend configuration.

slapi_be_exist()

Checks if the backend that contains the specified DN exists.

Syntax 

#include "slapi-plugin.h"

int slapi_be_exist(const Slapi_DN *sdn);

Parameters

This function takes the following parameter: 

sdn
Pointer to the DN in the backends for which you are looking.

Returns

This function returns one of the following values:

See Also 

slapi_be_select()

slapi_be_free()

Frees memory and linked resources from the backend structure.

Syntax 

#include "slapi-plugin.h"

void slapi_be_free(Slapi_Backend **be);

Parameters

This function takes the following parameter: 

be
Pointer to the structure containing the backend configuration.

slapi_be_get_instance_info()

Gets the instance information of the specified backend.

Syntax 

#include "slapi-plugin.h"

void * slapi_be_get_instance_info(Slapi_Backend * be);

Parameters

This function takes the following parameter: 

be
Pointer to the structure containing the backend configuration.

Returns

This function returns an opaque pointer to the instance information.

slapi_be_get_name()

Returns the name of the specified backend.

Syntax 

#include "slapi-plugin.h"

char * slapi_be_get_name(Slapi_Backend * be);

Parameters

This function takes the following parameter: 

be
Pointer to the structure containing the backend configuration.

Returns

This function returns the name associated to the specified backend.

Memory Concerns

You should not free the returned pointer.

slapi_be_get_readonly()

Indicates if the database associated with the backend is in read-only mode.

Syntax 

#include "slapi-plugin.h"

int slapi_be_get_readonly(Slapi_Backend *be);

Parameters

This function takes the following parameter: 

be
Pointer to the structure containing the backend configuration.

Returns

This function returns one of the following values:

slapi_be_getentrypoint()

Sets pointer to a callback function that corresponds to the specified entry point into a given backend.

Syntax 

int slapi_be_getentrypoint(Slapi_Backend *be, int entrypoint, 

void **ret_fnptr, Slapi_PBlock *pb);

Parameters

This function takes the following parameters: 

be
Pointer to the structure containing the backend configuration.
 
entrypoint
Entry point in the backend.
 
ret_fnptr
Opaque pointer to store function address.
 
pb
Pointer to the parameter block.

Returns

This function returns 0 if successful, -1 otherwise.

slapi_be_getsuffix()

Returns the n+1 suffix associated with the specified backend.

Syntax 

#include "slapi-plugin.h"

const Slapi_DN *slapi_be_getsuffix(Slapi_Backend *be, int n);

Parameters

This function takes the following parameters: 

be
Pointer to the structure containing the backend configuration.
 
n
Index.

Returns

This function returns the DN of the suffix if it exists, or NULL if there is no n+1 suffix in the backend.

Description

This function returns the n+1 suffix associated with the specified backend. This function is still present for compatibility purposes with previous versions of the Directory Server Plug-in API. Current versions of Directory Server do not support backends containing multiple suffixes; so, if n is not 0, NULL will be returned.

Memory Concerns

You should not free the returned pointer.

slapi_be_gettype()

Returns the type of the backend.

Syntax 

#include "slapi-plugin.h"

const char * slapi_be_gettype(Slapi_Backend *be);;

Parameters

This function takes the following parameter: 

be
Pointer to the structure containing the backend configuration.

Returns

This function returns the type of the backend.

Memory Concerns

You should not free the returned pointer.

slapi_be_is_flag_set()

Checks if a flag is set in the backend configuration.

Syntax 

#include "slapi-plugin.h"

int slapi_be_is_flag_set(Slapi_Backend * be, int flag);

Parameters

This function takes the following parameters: 

be
Pointer to the structure containing the backend configuration.
 
flag
Flag to check; for example, SLAPI_BE_FLAG_REMOTE_DATA.

Returns

This function returns one of the following values:

slapi_be_issuffix()

Verifies that the specified suffix matches a registered backend suffix.

Syntax 

#include "slapi-plugin.h"

int slapi_be_issuffix(const Slapi_Backend *be,

  const Slapi_DN *suffix );

Parameters

This function takes the following parameters: 

be
Pointer to the structure containing the backend configuration.
 
suffix
DN of the suffix for which you are looking.

Returns

This function returns one of the following values:

Description

This function checks if the specified suffix exactly matches a registered suffix on a specified backend.

slapi_be_logchanges()

Indicates whether the changes applied to the backend should be logged in the changelog.

Syntax 

#include "slapi-plugin.h"

int slapi_be_logchanges(Slapi_Backend *be);

Parameters

This function takes the following parameter: 

be
Pointer to the structure containing the backend configuration.

Returns

This function returns one of the following values:

slapi_be_new()

Creates a new backend structure, allocates memory for it, and initializes values for relevant parameters.

Syntax 

#include "slapi-plugin.h"

Slapi_Backend *slapi_be_new( const char *type, const char *name, 

  int isprivate, int logchanges );

Parameters

This function takes the following parameters: 

type
Database type.
 
name
Database name.
 
isprivate
Flag to denote whether the database is private.
 
logchanges
Flag for indicating whether changes are to be logged.

Returns

This function returns a pointer to the newly-created backend.

slapi_be_private()

Verifies if the backend is private.

Syntax 

#include "slapi-plugin.h"

int slapi_be_private( Slapi_Backend *be );

Parameters

This function takes the following parameter: 

be
Pointer to the structure containing the backend configuration.

Returns

This function returns one of the following values:

slapi_be_select()

Finds the backend that should be used to service the entry with the specified DN.

Syntax 

#include "slapi-plugin.h"

Slapi_Backend *slapi_be_select( const Slapi_DN * sdn );

Parameters

This function takes the following parameter: 

sdn
Pointer to the DN of which you wish to get the backend.

Returns

This function returns one of the following values:

Memory Concerns

You should not free the returned pointer.

See Also 

slapi_be_select_by_instance_name()

slapi_be_select_by_instance_name()

Find the backend used to service the database.

Syntax 

#include "slapi-plugin.h"

Slapi_Backend *slapi_be_select_by_instance_name( const char *name 
);

Parameters

This function takes the following parameter: 

name
Pointer to the name of the backend of which you wish to get the structure.

Returns

This function returns one of the following values:

Description

This function finds the backend that should be used to service the database named as the parameter.

Memory Concerns

You should not free the returned pointer.

See Also 

slapi_be_select()

slapi_be_set_flag()

Sets the specified flag in the backend.

Syntax 

#include "slapi-plugin.h"

void slapi_be_set_flag(Slapi_Backend * be, int flag);

Parameters

This function takes the following parameters: 

be
Pointer to the structure containing the backend configuration.
 
flag
Flag (bitmap) that needs to be set.

slapi_be_set_instance_info()

Sets the instance information of the specified backend with given data.

Syntax 

#include "slapi-plugin.h"

void  slapi_be_set_instance_info(Slapi_Backend * be, void * data);

Parameters

This function takes the following parameters: 

be
Pointer to the structure containing the backend configuration.
 
data
Data for setting the instance information.

slapi_be_set_readonly()

Sets a flag to denote that the backend is meant to be read-only.

Syntax 

#include "slapi-plugin.h"

void slapi_be_set_readonly(Slapi_Backend *be, int readonly);

Parameters

This function takes the following parameters: 

be
Pointer to the structure containing the backend configuration.
 
readonly
Flag to specify the read-only status.

slapi_be_setentrypoint()

Sets the entry point in the backend to the specified function.

Syntax 

#include "slapi-plugin.h"

int slapi_be_setentrypoint(Slapi_Backend *be, int entrypoint,

  void *ret_fnptr, Slapi_PBlock *pb);

Parameters

This function takes the following parameters: 

be
Pointer to the structure containing the backend configuration.
 
entrypoint
Entry point in the backend.
 
ret_fnptr
Opaque pointer to store function address.
 
pb
Pointer to the parameter block.

Returns

This function returns 0 if successful, -1 otherwise.

slapi_get_first_backend()

Returns a pointer of the backend structure of the first backend.

Syntax 

#include "slapi-plugin.h"

Slapi_Backend* slapi_get_first_backend(char **cookie);

Parameters

This function takes the following parameter: 

cookie
Output parameter containing the index of the returned backed. This is useful for calls to slapi_get_next_backend(). Contains 0 in output if no backend is returned.

Returns

This function returns one of the following values:

Description

This function returns a pointer to the backend structure of the first backend. If you wish to iterate through all of the backends, use this function in conjunction with slapi_get_next_backend(). For example: 

Slapi_Backend *be = NULL;

char *cookie = NULL;

be = slapi_get_first_backend (&cookie);

while (be )

    {

    ...

    be = slapi_get_next_backend (cookie);

    }

slapi_ch_free ((void**)&cookie);

Memory Concerns

Free the cookie parameter after the iteration using slapi_ch_free().

See Also 

slapi_get_next_backend()

slapi_get_first_suffix()

Returns the first root suffix of the DIT.

Syntax 

#include "slapi-plugin.h"

Slapi_DN * slapi_get_first_suffix(void ** node, int show_private);

Parameters

This function takes the following parameter: 

node
Contains the returned valued, which is the DN of the first root suffix of the DIT.
 
show_private
0 checks only for non-private suffixes.
1 checks for both private and non-private suffixes.

Returns

This function returns the DN of the first root suffix.

Description

This function returns the first root suffix of the DIT. If you wish to iterate through all of the suffixes, use this function in conjunction with slapi_get_next_suffix(). For example: 

void *node = NULL;

Slapi_DN * suffix = slapi_get_first_suffix (&node, 1);

while (suffix)

    {

    ...

    suffix = slapi_get_next_suffix (&node, 1);

    }

Memory Concerns

You should not free the returned pointer.

See Also 

slapi_get_next_suffix()

slapi_get_next_backend()

Returns a pointer to the next backend.

Syntax 

#include "slapi-plugin.h"

Slapi_Backend* slapi_get_next_backend(char *cookie);

Parameters

This function takes the following parameter: 

cookie
Upon input, contains the index from which the search for the next backend is done. Upon output, contains the index of the returned backend.

Returns

This function returns one of the following values:

Description

This function returns a pointer to the next backend. If you wish to iterate through all of the backends, use this function in conjunction with slapi_get_first_backend(). For example: 

Slapi_Backend *be = NULL;

char *cookie = NULL;

be = slapi_get_first_backend (&cookie);

while (be )

    {

    ...

    be = slapi_get_next_backend (cookie);

    }
 
slapi_ch_free ((void**)&cookie);

Memory Concerns

Free the cookie parameter after the iteration using slapi_ch_free().

See Also 

slapi_get_first_backend()
 
slapi_ch_free()

slapi_get_next_suffix()

Returns the DN of the next root suffix of the DIT.

Syntax 

#include "slapi-plugin.h"

Slapi_DN * slapi_get_next_suffix(void ** node, int show_private);

Parameters

This function takes the following parameter: 

show_private
0 checks only for non-private suffixes.
1 checks for both private and non-private suffixes.
 
node
Contains the returned valued, which is the DN of the next root suffix of the DIT.

Returns

This function returns one of the following values:

Description

This function returns the DN of the next root suffix of the DIT. If you wish to iterate through all of the suffixes, use this function in conjunction with slapi_get_first_suffix(). For example: 

void *node = NULL;

Slapi_DN * suffix = slapi_get_first_suffix (&node, 1);

while (suffix)

    {

    ...

    suffix = slapi_get_next_suffix (&node, 1);

    }

Memory Concerns

You should not free the returned pointer.

See Also 

slapi_get_first_suffix()

slapi_is_root_suffix()

Checks if a suffix is a root suffix of the DIT.

Syntax 

#include "slapi-plugin.h"

int slapi_is_root_suffix(Slapi_DN * dn);

Parameters

This function takes the following parameter: 

dn
DN that you wish to check.

Returns

This function returns one of the following values:

slapi_register_backend_state_change()

Registers for callback when a backend state changes.

Syntax 

#include "slapi-plugin.h"

void slapi_register_backend_state_change(void * handle, 
  slapi_backend_state_change_fnptr funct);

Parameters

This function takes the following parameter: 

handle
Pointer or reference to the address of the specified function.

Description

This function enables a plug-in to register for callback when the state of a backend changes. The function will come handy when developing custom plug-ins.

For example, if your plug-in stores any kind of state, such as a configuration cache, it will become invalidated or incomplete whenever the state of a backend changes. Because the plug-in wouldn't be aware of these state changes, it would require restarting the server whenever a backend state changed.

By registering for callback whenever the backend changes its state, your plug-in can keep track of these changes and retain its functionality. You can use slapi_unregister_backend_state_change() to unregister the callback.

See Also 

slapi_unregister_backend_state_change()

slapi_unregister_backend_state_change()

Unregisters backend-state-change callback.

Syntax 

#include "slapi-plugin.h"

int slapi_unregister_backend_state_change(void * handle);

Parameters

This function takes the following parameter: 

handle
Pointer or reference to the address of the specified function.

Returns

This function returns one of the following values:

Description

This function enables a plug-in to unregister backend-state-change callback. Use this function to unregister the callback, which is registered using slapi_register_backend_state_change().

See Also 

slapi_register_backend_state_change()

Functions for Dealing with Controls

This section contains reference information on routines for dealing with controls.

Table 15-7 Routines for Dealing with Controls  
Function
Description
slapi_build_control()
Creates an LDAPControl structure based on a BerElement, an OID, and a criticality flag.
slapi_build_control_from_berval()
Creates an LDAPControl structure based on a struct berval, an OID, and a criticality flag.
slapi_control_present()
Determines whether the specified object identification (OID) identifies a control that is present in a list of controls.
slapi_dup_control()
Makes an allocated copy of an LDAPControl.
slapi_get_supported_controls_copy()
Retrieves an allocated array of object identifiers (OIDs) representing the controls supported by the Directory Server.
slapi_register_supported_control()
Registers the specified control with the server. This function associates the control with an object identification (OID).

slapi_build_control()

Creates an LDAPControl structure based on a BerElement, an OID, and a criticality flag.

Syntax 

#include "slapi-plugin.h"

int slapi_build_control( char *oid, BerElement *ber, 

char iscritical, LDAPControl **ctrlp );

Parameters

This function takes the following parameters: 

oid
The OID (object identifier) for the control that is to be created.
 
ber
A BerElement that contains the control value. Pass NULL if the control has no value.
 
iscritical
The criticality flag. If non-zero, the control will be marked as critical. If 0, it will not be marked as critical.
 
ctrlp
Pointer that will receive the allocated LDAPControl structure.

Returns

This function returns LDAP_SUCCESS (LDAP result code) if successful.

Description

This function creates an LDAPCotnrol structure based on a BerElement, an OID, and a criticality flag. The LDAPControl that is created can be used in LDAP client requests or internal operations.

Memory Concerns

The contents of the ber parameter are consumed by this function. Because of this, the caller should not free the BerElement once a successful call has been made to slapi_build_control().

The LDAPControl pointer that is returned in ctrlp should be freed by calling ldap_control_free(), which is an LDAP API function; see the Red Hat LDAP SDK for C Programmer's Guide.

See Also 

slapi_build_control_from_berval()
 
slapi_build_control()
 
ldap_control_free()

slapi_build_control_from_berval()

Creates an LDAPControl structure based on a struct berval, an OID, and a criticality flag.

Syntax 

#include "slapi-plugin.h"

int slapi_build_control_from_berval( char *oid,

  struct berval *bvp,char iscritical, LDAPControl **ctrlp );

Parameters

This function takes the following parameters: 

oid
The OID (object identifier) for the control that is to be created.
 
bvp
A struct berval that contains the control value. Pass NULL if the control has no value.
 
iscritical
The criticality flag. If non-zero, the control will be marked as critical. If 0, it will not be marked as critical.
 
ctrlp
Pointer that will receive the allocated LDAPControl structure.

Returns

This function returns LDAP_SUCCESS (LDAP result code) if successful.

Description

This function creates an LDAPControl structure based on a struct berval, an OID, and a criticality flag. The LDAPControl that is created can be used in LDAP client requests or internal operations.

Memory Concerns

The contents of the bvp parameter are consumed by this function. Because of this, the caller should not free the bvp->bv_val pointer once a successful call to this function has been made.

The LDAPControl pointer that is returned in ctrlp should be freed by calling ldap_control_free(), which is an LDAP API function; see the Red Hat LDAP SDK for C Programmer's Guide.

See Also 

slapi_build_control()
 
slapi_dup_control()
 
ldap_control_free()

slapi_control_present()

Determines whether the specified object identification (OID) identifies a control that is present in a list of controls.

Syntax 

#include "slapi-plugin.h"

int slapi_control_present( LDAPControl **controls, char *oid, 

  struct berval **val, int *iscritical );

Parameters

This function takes the following parameters: 

controls
List of controls that you want to check.
 
oid
OID of the control that you want to find. 
val
If the control is present in the list of controls, specifies the pointer to the berval structure containing the value of the control. 
iscritical
If the control is present in the list of controls, specifies whether the control is critical to the operation of the server:
  • 0 means that the control is not critical to the operation.
  • 1 means that the control is critical to the operation.

Returns

This function returns one of the following values:

Memory Concerns

The val output parameter is set to point into the controls array. A copy of the control value is not made.

See Also 

slapi_get_supported_controls_copy()
 
slapi_register_supported_control()

slapi_dup_control()

Makes an allocated copy of an LDAPControl.

Syntax 

#include "slapi-plugin.h"

LDAPControl * slapi_dup_control( LDAPControl *ctrl )

Parameters

This function takes the following parameter: 

ctrl
Pointer to an LDAPControl structure whose contents are to be duplicated.

Returns

This function returns one of the following values:

Description

This function duplicates the contents of an LDAPControl structure. All fields within the LDAPControl are copied to a new, allocated structure, and a pointer to the new structure is returned.

Memory Concerns

The structure that is returned should be freed by calling ldap_control_free(), which is an LDAP API function; see the Red Hat LDAP SDK for C Programmer's Guide.

See Also 

ldap_control_free()

slapi_get_supported_controls_copy()

Retrieves an allocated array of object identifiers (OIDs) representing the controls supported by the Directory Server. You can register new controls by calling slapi_register_supported_control().

Syntax 

#include "slapi-plugin.h"

int slapi_get_supported_controls_copy( char ***ctrloidsp,

  unsigned long **ctrlopsp );

Parameters

This function takes the following parameters: 

ctrloidsp
Pointer to a character array that will receive the set of supported control OIDs. Pass NULL for this parameter if you do not wish to receive the OIDs.
 
ctrlopsp
Pointer to an unsigned long array that will receive the supported operation values for each control in the ctrloidsp array. Pass NULL for this parameter if you do not wish to receive the supported operation values.

Returns

This function returns one of the following values:

Description

This function replaces the deprecated slapi_get_supported_controls() function from previous releases, as it was not multithread safe.

When you call slapi_register_supported_control() to register a control, you specify the OID of the control and the IDs of the operations that support the control. The server records this information in two arrays; an array of control OIDs and an array of operations that support the control. You can get copies of these arrays by calling slapi_get_supported_controls_copy().

For each OID returned in the ctrloidsp array, the corresponding array element (with the same index) in the ctrlopsp array identifies the operations that support the control. For a list of the possible IDs for the operations, see slapi_register_supported_control().

Memory Concerns

The returned ctrloidsp array should be freed by calling slapi_ch_array_free(). The returned ctrlopsp array should be freed by calling slapi_ch_free().

See Also 

slapi_register_supported_control()
 
slapi_ch_array_free()

slapi_register_supported_control()

Registers the specified control with the server. This function associates the control with an object identification (OID). When the server receives a request that specifies this OID, the server makes use of this information to determine if the control is supported by the server or its plug-ins.

Syntax 

#include "slapi-plugin.h"

void slapi_register_supported_control( char *controloid,

  unsigned long controlops );

Parameters

This function takes the following parameters: 

controloid
OID of the control you want to register.
 
controlops
Operation to which the control is applicable.
 
SLAPI_OPERATION_BIND
The specified control applies to the LDAP bind operation.
 
SLAPI_OPERATION_UNBIND
The specified control applies to the LDAP unbind operation. 
SLAPI_OPERATION_SEARCH
The specified control applies to the LDAP search operation. 
SLAPI_OPERATION_MODIFY
The specified control applies to the LDAP modify operation. 
SLAPI_OPERATION_ADD
The specified control applies to the LDAP add operation. 
SLAPI_OPERATION_DELETE
The specified control applies to the LDAP delete operation. 
SLAPI_OPERATION_MODDN
The specified control applies to the LDAP modify DN operation. 
SLAPI_OPERATION_MODRDN
The specified control applies to the LDAPv3 modify RDN operation. 
SLAPI_OPERATION_COMPARE
The specified control applies to the LDAP compare operation. 
SLAPI_OPERATION_ABANDON
The specified control applies to the LDAP abandon operation. 
SLAPI_OPERATION_EXTENDED
The specified control applies to the LDAPv3 extended operation. 
SLAPI_OPERATION_ANY
The specified control applies to any LDAP operation.
 
SLAPI_OPERATION_NONE
The specified control applies to none of the LDAP operations.

You can specify a combination of values by bitwise OR-ing the values together. For example: SLAPI_OPERATION_ADD | SLAPI_OPERATION_DELETE

See Also 

slapi_get_supported_controls_copy()
 
slapi_control_present()

Functions for Syntax Plug-in

This section contains reference information on routines for syntax plug-ins.

Table 15-8 Syntax Plug-in Routines  
Function
Description
slapi_call_syntax_assertion2keys_ava_sv()
Calls a function, specified in the syntax plug-in, to compare against directory entries.
slapi_call_syntax_assertion2keys_sub_sv()
Calls a function, specified in the syntax plug-in, to compare against directory entries.
slapi_call_syntax_values2keys_sv()
Manages index values when adding or removing values from an index.

slapi_call_syntax_assertion2keys_ava_sv()

When processing a search, calls the function (defined in the specified syntax plug-in) responsible for returning an array of values (specified by the search filter) to compare against the entries in the directory.

This function applies to searches that use the filter types LDAP_FILTER_EQUALITY and LDAP_FILTER_APPROX.

Syntax 

#include "slapi-plugin.h"

int slapi_call_syntax_assertion2keys_ava_sv( void *vpi, 

  Slapi_Value *val, Slapi_Value ***ivals, int ftype );

Parameters

This function takes the following parameters: 

vpi
Handle to plug-in for this attribute type 
val
Pointer to the Slapi_Value arrays containing the value from the search filter; for example, if the filter is ou=Accounting, the argument val is Accounting.
 
ivals
Pointer to the Slapi_Value arrays containing the values returned by the plug-in function; these values can now be compared against entries in the directory.
 
ftype
Type of filter; for example, LDAP_FILTER_EQUALITY.

Returns

This function returns one of the following values:

Description

When processing a search that uses an attribute-value assertion (AVA) filter (for example, ou=Accounting or ou=~Accounting), the backend needs to compare the value specified in the search filter against the value of the specified attribute in each entry.

The function invokes the syntax plug-in specified by the vpi argument. This is the plug-in associated with the type of attribute used in the search. You can get this handle by calling the slapi_attr_type2plugin() function.

The syntax plug-in function invoked by this function is responsible for comparing the value specified by val against the actual values of the attributes in the directory entries. The syntax plug-in function returns a list of matching entry keys (the ivals argument) to the backend.

slapi_call_syntax_assertion2keys_sub_sv()

When processing a search, calls the function (defined in the specified syntax plug-in) responsible for returning an array of values (specified by the search filter) to compare against the entries in the directory.

This function applies to searches that use the filter type LDAP_FILTER_SUBSTRINGS.

Syntax 

#include "slapi-plugin.h"

int slapi_call_syntax_assertion2keys_sub_sv( void *vpi, 

  char *initial, char **any, char *final, Slapi_Value ***ivals );

Parameters

This function takes the following parameters: 

vpi
Handle to plug-in for this attribute type 
initial
"Starts with" value from the search filter; for example, if the filter is ou=Sales*, the argument initial is Sales.
 
any
Array of "contains" values from the search filter; for example, if the filter is ou=*Corporate*Sales*, the argument any is an array containing Corporate and Sales.
 
final
"Ends with" value from the search filter; for example, if the filter is ou=*Sales, the argument final is Sales.
 
ivals
Pointer to an array of Slapi_Value structures containing the values returned by the plug-in function; these values can now be compared against entries in the directory.

Returns

This function returns one of the following values:

Description

The ldbm backend (the default backend database) calls this function when processing searches in which the filter type is LDAP_FILTER_SUBSTRINGS.

The function invokes the syntax plug-in specified by the vpi argument. This is the plug-in associated with the type of attribute used in the search. You can get this handle by calling the slapi_attr_type2plugin() function.

The syntax plug-in function invoked by this function is responsible for comparing the values (specified by initial, any, and final) against the actual values of the attributes in the directory entries. The syntax plug-in function returns a list of matching entry keys (the ivals argument) to the backend.

slapi_call_syntax_values2keys_sv()

When adding or removing values from an index, calls the function (defined in the specified syntax plug-in) responsible for returning an array of keys matching the specified values.

Syntax 

#include "slapi-plugin.h"

int slapi_call_syntax_values2keys_sv( void *vpi, Slapi_Value **vals, 

  Slapi_Value ***ivals, int ftype );

Parameters

This function takes the following parameters: 

vpi
Handle to plug-in for this attribute type.
 
vals
Pointer to the Slapi_Value structure containing the value to add or delete.
 
ivals
Pointer to an array of Slapi_Value structures containing the values returned by the plug-in function; these values can be compared against entries in the directory.
 
ftype
Type of filter; for example, LDAP_FILTER_EQUALITY.

Returns

This function returns one of the following values:

Description

When adding or removing values from an index, the Directory Server calls the function (defined in the specified syntax plug-in) responsible for returning an array of keys matching the specified values.

Functions for Managing Memory

This section contains reference information on routines for managing memory, such as allocating and freeing memory.

Table 15-9 Memory Management Routines  
Function
Description
slapi_ch_array_free()
Frees an existing array.
slapi_ch_bvdup()
Makes a copy of an existing berval structure.
slapi_ch_bvecdup()
Makes a copy of an array of existing berval structures.
slapi_ch_calloc()
Allocates space for an array of a number of elements of a specified size.
slapi_ch_free()
Frees space allocated by the slapi_ch_malloc(), slapi_ch_realloc(), and slapi_ch_calloc() functions.
slapi_ch_free_string()
Frees space previously allocated to a string.
slapi_ch_malloc()
Allocates space in memory.
slapi_ch_realloc()
Changes the size of a block of allocated memory.
slapi_ch_smprintf()
Creates, formats, and returns a given string.
slapi_ch_strdup()
Makes a copy of an existing string.

slapi_ch_array_free()

Frees an existing array.

Syntax 

#include "slapi-plugin.h"

void slapi_ch_array_free( char **arrayp );

Parameters

This function takes the following parameter: 

arrayp
Pointer to the array to be freed. This parameter can be NULL.

Description

This function frees the char ** pointed to by arrayp.

slapi_ch_bvdup()

Makes a copy of an existing berval structure.

Syntax 

#include "slapi-plugin.h" 

extern struct berval* slapi_ch_bvdup( const struct berval *v );

Parameters

This function takes the following parameter: 

v
Pointer to the berval structure that you want to copy.

Returns

This function returns a pointer to the new copy of the berval structure. If the structure cannot be duplicated, e.g., because of insufficient virtual memory, the slapd program terminates.

Memory Concerns

The contents of the v parameter are not altered by this function. The returned berval structure should be freed by calling ber_bvfree(), which is an LDAP API function; see the Red Hat LDAP SDK for C Programmer's Guide.

See Also 

slapi_ch_bvdup()
 
ber_bvfree()

slapi_ch_bvecdup()

Makes a copy of an array of existing berval structures.

Syntax 

#include "slapi-plugin.h"

extern struct berval** slapi_ch_bvecdup (const struct berval **v);

Parameters

This function takes the following parameter: 

v
Pointer to the array of berval structures that you want to copy.

Returns

This function returns a pointer to an array of the new copy of the berval structures. If the structures cannot be duplicated, e.g., because of insufficient virtual memory, the slapd program terminates.

Memory Concerns

The contents of the v parameter are not altered by this function. The returned berval structure should be freed by calling ber_bvfree(), which is an LDAP API function; see the Red Hat LDAP SDK for C Programmer's Guide.

See Also 

slapi_ch_bvdup()
 
ber_bvfree()

slapi_ch_calloc()

Allocates space for an array of a number of elements of a specified size.

Syntax 

#include "slapi-plugin.h"

char * slapi_ch_calloc( unsigned long nelem, unsigned long size );

Parameters

This function takes the following parameters: 

nelem
Number of elements for which you want to allocate memory. 
size
Size, in bytes, of the element for which you want to allocate memory.

Returns

This function returns a pointer to the newly allocated space of memory. If space cannot be allocated, e.g., no more virtual memory exists, the slapd program terminates.

Memory Concerns

This function terminates the slapd server with an "out of memory" error message if memory cannot be allocated. You should free the returned pointer by calling slapi_build_control().

See Also 

slapi_ch_free()
 
slapi_ch_malloc()
 
slapi_ch_realloc()
 
slapi_ch_strdup()

slapi_ch_free()

Frees space allocated by the slapi_ch_malloc(), slapi_ch_realloc(), and slapi_ch_calloc() functions and sets the pointer to NULL. Call this function instead of the standard free() C function.

Syntax 

#include "slapi-plugin.h"

void slapi_ch_free( void **ptr );

Parameters

This function takes the following parameter: 

ptr
Address of the pointer to the block of memory that you want to free. If NULL, no action occurs.

Memory Concerns

The ptr passed to slapi_ch_free() should be the address of a pointer that was allocated using a slapi call such as slapi_ch_malloc(), slapi_ch_calloc(), slapi_ch_realloc(), or slapi_ch_strdup().

See Also 

slapi_ch_malloc()
 
slapi_ch_calloc()
 
slapi_ch_realloc()
 
slapi_ch_strdup()

slapi_ch_free_string()

Frees space previously allocated to a string.

Syntax 

#include "slapi-plugin.h"

void slapi_ch_free_string( char **s );

Parameters

This function takes the following parameter: 

s
Address of the string that you want to free. If NULL, no action occurs.

Description

This function is similar to slapi_ch_free(), but the argument is the address of a string. This helps with compile time error checking.

See Also 

slapi_ch_free()

slapi_ch_malloc()

Allocates space in memory.

Syntax 

#include "slapi-plugin.h"

char * slapi_ch_malloc( unsigned long size );

Parameters

This function takes the following parameter: 

size
Size of the space for which you want to allocate memory.

Returns

This function returns a pointer to the newly allocated space of memory. If space cannot be allocated, e.g., no more virtual memory exists, the slapd program terminates.

Memory Concerns

This function terminates the slapd server with an "out of memory" error message if memory cannot be allocated.

The returned pointer should be freed by calling slapi_ch_free().

See Also 

slapi_ch_free()
 
slapi_ch_calloc()
 
slapi_ch_realloc()
 
slapi_ch_strdup()

slapi_ch_realloc()

Changes the size of a block of allocated memory.

Syntax 

#include "slapi-plugin.h"

char * slapi_ch_realloc( char *block, unsigned long size );

Parameters

This function takes the following parameters: 

block
Pointer to an existing block of allocated memory.
 
size
New size of the block of memory you want allocated.

Returns

This function returns a pointer to the reallocated space of memory. If space cannot be allocated, e.g., no more virtual memory exists, the slapd program terminates.

Memory Concerns

This function terminates the slapd server with an "out of memory" error message if memory cannot be allocated.

The block parameter passed to slapi_ch_realloc() should be the address of a pointer that was allocated using a slapi call such as slapi_ch_malloc(), slapi_ch_calloc(), or slapi_ch_strdup(). The returned pointer should be freed by calling slapi_ch_free().

See Also 

slapi_ch_free()
 
slapi_ch_calloc()
 
slapi_ch_strdup()

slapi_ch_smprintf()

Creates, writes to, and returns a given string.

Syntax 

#include "slapi-plugin.h"

char *string = slapi_ch_smprintf (format, *arg, ...);

Parameters

This function takes the following parameter: 

string
String that is printed. 
format
A printf-style format string
 
arg
Arguments to pass for the string.

Returns

This function the specified string, write to it using the specified formats and arguments, and returns the string. If space cannot be allocated, e.g., no more virtual memory exists, the slapd program terminates.

Memory Concerns

This function terminates the slapd server with an "out of memory" error message if memory cannot be allocated. The returned string should be freed by calling slapi_ch_free() to avoid memory leaks.

See Also 

slapi_ch_free()
 
slapi_ch_calloc()
 
slapi_ch_malloc()
 
slapi_ch_realloc()

slapi_ch_strdup()

Makes a copy of an existing string.

Syntax 

#include "slapi-plugin.h"

char * slapi_ch_strdup( const char *s );

Parameters

This function takes the following parameter: 

s
Pointer to the string you want to copy.

Returns

This function returns a pointer to a copy of the string. If space cannot be allocated, e.g., no more virtual memory exists, the slapd program terminates.

Memory Concerns

This function terminates the slapd server with an "out of memory" error message if memory cannot be allocated.

The returned pointer should be freed by calling slapi_ch_free().

See Also 

slapi_ch_free()
 
slapi_ch_calloc()
 
slapi_ch_malloc()
 
slapi_ch_realloc()

Functions for Managing DNs

This section contains reference information on routines for handling DNs.

Table 15-10 DN Management Routines  
Function
Description
slapi_add_auth_response_control()
Supplies authentication information from an LDAP bind operation.
slapi_dn_beparent()
Gets a copy of the DN of the parent of an entry.
slapi_dn_ignore_case()
Converts all characters in a DN to lowercase.
slapi_dn_isbesuffix()
Determines if the a DN is the suffix of the local database.
slapi_dn_isparent()
Determines if a DN is the parent of a specific DN.
slapi_dn_isroot()
Determines if the DN is the root DN for the local database.
slapi_dn_issuffix()
Determines if a DN is equal to a specified suffix.
slapi_dn_normalize()
Converts a DN to canonical format.
slapi_dn_normalize_case()
Converts a DN to canonical format and all characters to lower case.
slapi_dn_normalize_to_end()
Normalizes part of a DN value.
slapi_dn_parent()
Gets the DN of the parent of an entry.
slapi_dn_plus_rdn()
Adds an RDN to a DN.
slapi_rdn2typeval()
Converts the second RDN type value to the berval value.

slapi_add_auth_response_control()

Supplies authentication information from an LDAP bind operation based on the bind DN and passes back the actual bind identity.

Syntax 

#include "slapi-plugin.h"

int slapi_add_suth_response_control ( Slapi_PBlock *pb, const char 
*binddn );

Parameters

This function takes the following parameter: 

pb
Parameter block.
 
binddn
The identity of the user specified in the bind operation.

Returns

This function returns one of the following values:

slapi_dn_beparent()

Gets a copy of the distinguished name (DN) of the parent of an entry, unless the specified entry's DN is the suffix of the local database.

If you don't want to check if the entry's DN is the suffix of the local database, call the slapi_dn_beparent() function instead.

Syntax 

#include "slapi-plugin.h"

char *slapi_dn_beparent( Slapi_PBlock *pb, const char *dn );

Parameters

This function takes the following parameters: 

pb
Parameter block.
 
dn
DN of the entry for which you want to find the parent.

Returns

This function returns one of the following values:

See Also 

slapi_dn_parent()

slapi_dn_ignore_case()

Convert all characters in a distinguished name (DN) to lowercase.

Syntax 

#include "slapi-plugin.h"

char *slapi_dn_ignore_case( char *dn );

Parameters

This function takes the following parameter: 

dn
DN that you want to convert to lowercase.

Returns

The DN with lowercase characters. A variable passed in as the dn argument is also converted in-place.

See Also 

slapi_dn_normalize()

slapi_dn_isbesuffix()

Determines whether the specified distinguished name (DN) is the suffix of the local database. Before calling this function, you should call slapi_dn_normalize_case() to normalize the DN and convert all characters to lowercase.

Syntax 

#include "slapi-plugin.h"

int slapi_dn_isbesuffix( Slapi_PBlock *pb, const char *dn );

Parameters

This function takes the following parameters: 

pb
Parameter block.
 
dn
DN that you want to check.

Returns

This function returns one of the following values:

See Also 

slapi_dn_isroot()

slapi_dn_isparent()

Determines whether a particular DN is the parent of another specified DN. Before calling this function, you should call slapi_dn_normalize_case() to normalize the DNs and convert all characters to lowercase.

Syntax 

#include "slapi-plugin.h"

int slapi_dn_isparent( const char *parentdn, const char *childdn );

Parameters

This function takes the following parameters: 

parentdn
Determine if this DN is the parent of childdn. 
childdn
Determine if this DN is the child of parentdn.

Returns

This function returns one of the following values:

See Also 

slapi_dn_issuffix()

slapi_dn_isroot()

Determines whether the specified DN is the root DN for this local database. Before calling this function, you should call slapi_dn_normalize_case() to normalize the DN and convert all characters to lowercase.

Syntax 

#include "slapi-plugin.h"

int slapi_dn_isroot( const char *dn );

Parameters

This function takes the following parameters: 

pb
Parameter block.
 
dn
DN that you want to check.

Returns

This function returns one of the following values:

See Also 

slapi_dn_isbesuffix()

slapi_dn_issuffix()

Determines whether a DN is equal to the specified suffix. Before calling this function, you should call slapi_dn_normalize_case() to normalize the DN and convert all characters to lowercase.

If you want to determine if a DN is the same as the suffix for the local database, call the slapi_dn_isbesuffix() function instead.

Syntax 

#include "slapi-plugin.h"

int slapi_dn_issuffix( const char *dn, const char *suffix );

Parameters

This function takes the following parameters: 

dn
DN that you want to check.
 
suffix
Suffix that you want compared against the DN.

Returns

This function returns one of the following values:

See Also 

slapi_dn_isparent()

slapi_dn_normalize()

Convert a distinguished name (DN) to canonical format (no leading or trailing spaces, no spaces between components, and no spaces around the equals sign). For example, given the following DN: 

cn = Moxie Cross , ou = Engineering , dc = example , dc = com

the function returns: 

cn=Moxie Cross,ou=Engineering,dc=example,dc=com

Syntax 

#include "slapi-plugin.h"

char *slapi_dn_normalize( char *dn );

Parameters

This function takes the following parameter: 

dn
DN that you want to normalize.

Returns

This function returns the normalized DN. A variable passed in as the dn argument is also converted in place.

See Also 

slapi_dn_normalize_to_end()
 
slapi_dn_normalize_case()

slapi_dn_normalize_case()

Converts a distinguished name (DN) to canonical format and converts all characters to lowercase. Calling this function has the same effect as calling the slapi_dn_normalize() function followed by the slapi_dn_ignore_case() function.

Syntax 

#include "slapi-plugin.h"

char *slapi_dn_normalize_case( char *dn );

Parameters

This function takes the following parameter: 

dn
DN that you want to normalize and convert to lowercase.

Returns

This function returns the normalized DN with all lowercase characters. A variable passed in as the dn argument is also converted in place.

See Also 

slapi_dn_normalize()
 
slapi_dn_ignore_case()

slapi_dn_normalize_to_end()

Normalizes part of a DN value, specifically the part going from what is pointed to by dn to that pointed to by end. This routine does not NULL terminate the normalized bit pointed to by dn at the return of the function.

If the argument end happens to be NULL, this routine does basically the same thing as slapi_dn_normalize(), except for NULL terminating the normalized DN.

Syntax 

#include "slapi-plugin.h"

char *slapi_dn_normalize_to_end( char *dn, char *end);

Parameters

This function takes the following parameters: 

dn
DN value to be normalized.
 
end
Pointer to the end of what will be normalized from the DN value in dn. If this argument is NULL, the DN value in dn will be wholly normalized.

Returns

This function returns a pointer to the end of the dn that has been normalized. For example, if the RDN is cn=Jane and the DN is l=US, dc=example,dc=com, the new DN will be cn=Jane,l=US, dc=example,dc=com.

See Also 

slapi_dn_normalize()

slapi_dn_parent()

Gets a copy of the distinguished name (DN) of the parent of an entry. Before calling this function, you should call slapi_dn_normalize_case() to normalize the DN and convert all characters to lowercase.

If you want to check if the DN is the suffix of the local database, call the slapi_dn_beparent() function instead.

Syntax 

#include "slapi-plugin.h"

char *slapi_dn_parent( const char *dn );

Parameters

This function takes the following parameter: 

dn
DN of the entry for which you want to find the parent.

Returns

This function returns one of the following values:

See Also 

slapi_dn_beparent()

slapi_dn_plus_rdn()

Adds an RDN to DN.

Syntax 

#include "slapi-plugin.h"

char *slapi_dn_plus_rdn( const char *dn, const char *rdn);

Parameters

This function takes the following parameters: 

dn
DN value to which a new RDN is to be added.
 
rdn
RDN value that is to be added to the DN value in dn.

Returns

This function returns the new DN formed by adding the RDN value in rdn to the DN value in dn.

See Also 

slapi_sdn_add_rdn()

slapi_rdn2typeval()

Converts the second RDN type value to the berval value.

Syntax 

#include "slapi-plugin.h"

int slapi_rdn2typeval( char *rdn, char **type, struct berval *bv );

Parameters

This function takes the following parameters: 

rdn
Second RDN value
 
type
Pointer to the attribute type of the second RDN.
 
bv
Pointer to the berval value structure.

Returns

This function returns the new RDN value as a berval value in bv. This function can be used for creating the RDN as an attribute value since it returns the value of the RDN in the berval structure.

See Also 

moddn_rdn_add_needed()

Functions for Managing Entries

This section contains reference information on routines for managing entries.

Table 15-11 Entry Routines  
Function
Description
slapi_entry2str()
Generates an LDIF string description.
slapi_entry2str_with_options()
Generates an LDIF string descriptions with options.
slapi_entry_add_rdn_values()
Add components in an entry's RDN.
slapi_entry_add_string()
Adds a string value to an attribute in an entry.
slapi_entry_add_value()
Adds a data value to an attribute in an entry.
slapi_entry_add_values_sv()
Adds an array of data values to an attribute in an entry.
slapi_entry_add_valueset()
Adds a data value to an attribute in an entry.
slapi_entry_alloc()
Allocates memory for a new entry.
slapi_entry_attr_delete()
Deletes an attribute from an entry.
slapi_entry_attr_find()
Checks if an entry contains a specific attribute.
slapi_entry_attr_get_bool()
Gets a given attribute value as a boolean.
slapi_entry_attr_get_charptr()
Gets the first value as a string.
slapi_entry_attr_get_charray()
Gets the values of a multi-valued attribute of an entry.
slapi_entry_attr_get_int()
Gets the first value as an integer.
slapi_entry_attr_get_long()
Gets the first value as a long.
slapi_entry_attr_get_uint()
Gets the first value as an unsigned integer.
slapi_entry_attr_get_ulong()
Gets the first value as an unsigned long.
slapi_entry_attr_has_syntax_value()
Checks if an attribute in an entry contains a value.
slapi_entry_attr_merge_sv()
Adds an array to the attribute values in an entry.
slapi_entry_attr_replace_sv()
Replaces the values of an attribute.
slapi_entry_attr_set_charptr()
Replaces the values of an attribute with a string.
slapi_entry_attr_set_int()
Replaces the value of an attribute with an integer.
slapi_entry_attr_set_long()
Replaces the value of an attribute with a long.
slapi_entry_attr_set_uint()
Replaces the value of an attribute with an unsigned integer.
slapi_entry_attr_set_ulong()
Replaces the value of an attribute with an unsigned long.
slapi_entry_delete_string()
Deletes a string from an attribute.
slapi_entry_delete_values_sv()
Removes a Slapi_Value array from an attribute.
slapi_entry_dup()
Copies an entry, its DN, and its attributes.
slapi_entry_first_attr()
Finds the first attribute in an entry.
slapi_entry_free()
Frees an entry from memory.
slapi_entry_get_dn()
Gets the DN from an entry.
slapi_entry_get_dn_const()
Returns the DN of an entry as a constant.
slapi_entry_get_ndn()
Returns the NDN of an entry.
slapi_entry_get_sdn()
Returns the Slapi_DN from an entry.
slapi_entry_get_sdn_const()
Returns a Slapi_DN from an entry as a constant.
slapi_entry_get_uniqueid()
Gets the unique ID from an entry.
slapi_entry_has_children()
Determines if the specified entry has child entries.
slapi_entry_init()
Initializes the values of an entry.
slapi_entry_merge_values_sv()
Adds an array of data values to an attribute in an entry.
slapi_entry_next_attr()
Finds the next attribute in an entry.
slapi_entry_rdn_values_present()
Checks if values present in an entry's RDN are also present as attribute values.
slapi_entry_schema_check()
Determines if an entry complies with the schema for its object class.
slapi_entry_set_dn()
Sets the DN of an entry.
slapi_entry_set_sdn()
Sets the Slapi_DN value in an entry.
slapi_entry_set_uniqueid()
Sets the unique ID in an entry.
slapi_entry_size()
Returns the size of an entry.
slapi_is_rootdse()
Determines if an entry is the root DSE.
slapi_str2entry()
Converts an LDIF description into an entry.

slapi_entry2str()

Generates an LDIF string description of an LDAP entry.

Syntax 

#include "slapi-plugin.h" 

char *slapi_entry2str( Slapi_Entry *e, int *len );

Parameters

This function takes the following parameters: 

e
Entry that you want to convert into an LDIF string. 
len
Length of the returned LDIF string.

Returns

This function returns one of the following values:

Description

This function generates an LDIF string value conforming to the following format: 

dn: dn\n 

[attr: value\n]*

For example: 

dn: uid=jdoe, ou=People, dc=example,dc=com 

cn: Jane Doe

sn: Doe

...

To convert a string description in LDIF format to an entry of the Slapi_Entry data type, call the slapi_str2entry() function.

Memory Concerns

When you no longer need to use the string, you should free it from memory by calling the slapi_ch_free() function.

See Also 

slapi_entry2str_with_options()
 
slapi_str2entry()

slapi_entry2str_with_options()

Generates a description of an entry as an LDIF string. This function behaves much like slapi_entry2str(); however, you can specify output options with this function.

Syntax 

#include "slapi-plugin.h" 

char *slapi_entry2str_with_options( Slapi_Entry *e, 

  int *len, int options );

Parameters

This function takes the following parameters: 

e
Entry that you want to convert into an LDIF string. 
len
Length of the LDIF string returned by this function. 
options
An option set that specifies how you want the string converted.

The Options Parameter

You can OR together any of the following options when you call this function:

Flag Value
Description
 
SLAPI_DUMP_STATEINFO
This is only used internally by replication. This allows access to the internal data used by multi-master replication.
 
SLAPI_DUMP_UNIQUEID
This option is used when creating an LDIF file to be used to initialize a replica. Each entry will contain the nsuniqueID operational attribute.
 
SLAPI_DUMP_NOOPATTRS
By default, certain operational attributes (such as creatorName, modifiersName, createTimestamp, modifyTimestamp) may be included in the output. With this option, no operational attributes will be included.
 
SLAPI_DUMP_NOWRAP
By default, lines will be wrapped as defined in the LDIF specification. With this option, line wrapping is disabled.

Returns

This function returns one of the following values:

Description

This function generates an LDIF string value conforming to the following syntax: 

dn: dn\n 

[attr: value\n]*

For example: 

dn: uid=jdoe, ou=People, dc=example,dc=com 

cn: Jane Doe

sn: Doe 

...

To convert an entry described in LDIF string format to an LDAP entry using the Slapi_Entry data type, call the slapi_str2entry() function.

Memory Concerns

When you no longer need to use the string, you should free it from memory by calling the slapi_ch_free() function.

See Also 

slapi_entry2str()
 
slapi_str2entry()

slapi_entry_add_rdn_values()

Adds the components in an entry's relative distinguished name (RDN) to the entry as attribute values. (For example, if the entry's RDN is uid=bjensen, the function adds uid=bjensen to the entry as an attribute value.)

Syntax 

#include "slapi-plugin.h" 

int slapi_entry_add_rdn_values( Slapi_Entry *e );

Parameters

This function takes the following parameter: 

e
Entry to which you want to add the RDN attributes.

Returns

This function returns one of the following values:

Memory Concerns

Free the entry from memory by using the slapi_ch_free() function, if the entry was allocated by the user.

See Also 

slapi_entry_free()

slapi_entry_add_string()

Adds a string value to an attribute in an entry.

Syntax 

#include "slapi-plugin.h" 

int slapi_entry_add_string (Slapi_Entry *e, const char *type, 

  const char *value);

Parameters

This function takes the following parameters: 

e
Entry to which you want to add a string value. 
type
Attribute to which you want to add a string value. 
value
String value you want to add.

Returns

This function returns 0 when successful; any other value returned signals failure.

Description

This function adds a string value to the existing attribute values in an entry. If the specified attribute does not exist in the entry, the attribute is created with the string value specified. The function doesn't check for duplicate values; it does not check if the string value being added is already there.

Memory Concerns

This routine makes a copy of the parameter value. value can be NULL.

slapi_entry_add_value()

Adds a specified Slapi_Value data value to an attribute in an entry.

Syntax 

#include "slapi-plugin.h" 

int slapi_entry_add_value (Slapi_Entry *e, const char *type, 

  const Slapi_Value *value);

Parameters

This function takes the following parameters: 

e
Entry to which you want to add a value. 
type
Attribute to which you want to add a value. 
value
The Slapi_value data value you want to add to the entry.

Returns

This function returns 0 when successful; any other value returned signals failure.

Description

This function adds a Slapi_Value data value to the existing attribute values in an entry. If the specified attribute does not exist in the entry, the attribute is created with the Slapi_Value specified. The function doesn't check for duplicate values, meaning it does not check if the value being added is already there.

Memory Concerns

This routine makes a copy of the parameter value. value can be NULL.

slapi_entry_add_values_sv()

Adds and array of Slapi_Value data values to the specified attribute in an entry.

Syntax 

#include "slapi-plugin.h" 

int slapi_entry_add_values_sv( Slapi_Entry *e, const char *type, 

Slapi_Value **vals );

Parameters

This function takes the following parameters: 

e
Entry to which you want to add values. 
type
Attribute type to which you want to add values. 
vals
Array of Slapi_Value data values that you want to add.

Returns

This function returns one of the following values:

Description

This function adds an array of Slapi_Value data values to an attribute. If the attribute does not exist, it is created and given the value contained in the Slapi_Value array.

This function replaces the deprecated slapi_entry_add_values() function. This function uses Slapi_Value attribute values instead of the now obsolete berval attribute values.

Memory Concerns

This routine makes a copy of the parameter vals. vals can be NULL.

See Also 

slapi_entry_add_values()

slapi_entry_add_valueset()

Add a Slapi_ValueSet data value to the specified attribute in an entry.

Syntax 

#include "slapi-plugin.h" 

int slapi_entry_add_valueset(Slapi_Entry *e, const char *type, 

Slapi_ValueSet *vs);

Parameters

This function takes the following parameters: 

e
Entry to which you want to add values. 
type
Attribute type to which you want to add values. 
vs
Slapi_ValueSet data value that you want to add to the entry.

Returns

This function returns 0 when successful; any other value returned signals failure.

Description

This function adds a set of values to an attribute in an entry. The values added are in the form of a Slapi_ValueSet data type. If the entry does not contain the attribute specified, it is created with the specified Slapi_ValueSet value.

Memory Concerns

This routine makes a copy of the parameter vs. vs can be NULL.

slapi_entry_alloc()

Allocates memory for a new entry of the data type Slapi_Entry.

Syntax 

#include "slapi-plugin.h" 

Slapi_Entry *slapi_entry_alloc();

Returns

This function returns a pointer to the newly allocated entry of the data type Slapi_Entry. If space cannot be allocated, e.g., no more virtual memory exists, the slapd program terminates.

Description

This function returns an empty Slapi_Entry structure. You can call other front-end functions to set the DN and attributes of this entry.

When you are no longer using the entry, you should free it from memory by calling the slapi_entry_free() function.

Memory Concerns

When you no longer use the entry, free it from memory by calling the slapi_entry_free() function.

See Also 

slapi_entry_dup()
 
slapi_entry_free()

slapi_entry_attr_delete()

Deletes an attribute (and all its associated values) from an entry.

Syntax 

#include "slapi-plugin.h"

int slapi_entry_attr_delete( Slapi_Entry *e, const char *type );

Parameters

This function takes the following parameters: 

e
Entry from which you want to delete the attribute. 
type
Attribute type that you want to delete.

Returns

This function returns one of the following values:

slapi_entry_attr_find()

Determines if an entry contains the specified attribute. If the entry contains the attribute, the function returns a pointer to the attribute.

Syntax 

#include "slapi-plugin.h" 

int slapi_entry_attr_find( const Slapi_Entry *e, const char *type, 

  Slapi_Attr **attr );

Parameters

This function takes the following parameters: 

e
Entry that you want to check. 
type
Name of the attribute that you want to check. 
attr
Pointer to the attribute, if the attribute is in the entry.

Returns

This function returns one of the following values:

Memory Concerns

Do not free the returned attr. It is a pointer to the internal entry data structure. It is usually wise to make a copy of the returned attr, using slapi_attr_dup(), to avoid dangling pointers if the entry is freed while the pointer to attr is still being used.

See Also 

slapi_attr_dup()

slapi_entry_attr_get_bool()

Gets the value of a given attribute of a given entry as a boolean value.

Syntax 

#include "slapi-plugin.h"

char *slapi_entry_attr_get_bool(const Slapi_Entry* e, 

  const char *type);

Parameters

This function takes the following parameters: 

e
Entry from which you want to get the boolean value. 
type
Attribute type from which you want to get the value.

Returns

This function returns one of the following values:

Comparisons are case-insensitive (TRUE, trUe, and true are all the same), and unique substrings can be matched (t and tr will be interpreted as true). If the attribute value is a number, then non-zero numbers are interpreted as true, and 0 is interpreted as false.

slapi_entry_attr_get_charptr()

Gets the first value of an attribute of an entry as a string.

Syntax 

#include "slapi-plugin.h"

char *slapi_entry_attr_get_charptr(const Slapi_Entry* e, 

  const char *type);

Parameters

This function takes the following parameters: 

e
Entry from which you want to get the string value. 
type
Attribute type from which you want to get the value.

Returns

This function returns one of the following values:

Memory Concerns

When you are done working with this value, free it from memory by calling the slapi_ch_free() function.

slapi_entry_attr_get_charray()

Gets the values of a multi-valued attribute of an entry.

Syntax 

#include "slapi-plugin.h"

char ** slapi_entry_attr_get_charray( const Slapi_Entry* e, 

  const char *type);

Parameters

This function takes the following parameters: 

e
Entry from which you want to get the values.
 
type
Attribute type from which you want to get the values.

Description

This function is very similar to slapi_entry_attr_get_charptr(), except that it returns a char** array for multi-valued attributes. The array and all values are copies. Even if the attribute values are not strings, they will still be null terminated so that they can be used safely in a string context. If there are no values, NULL will be returned. Because the array is NULL terminated, the usage should be similar to the sample shown below: 

char **ary = slapi_entry_attr_get_charray(e, someattr);

int ii;

for (ii = 0; ary && ary[ii]; ++ii) {

	char *strval = ary[ii];

	...

}

slapi_ch_array_free(ary);

Returns

This function returns one of the following values:

Memory Concerns

When you are done working with the values, free them from memory by calling the slapi_ch_array_free() function.

See Also 

slapi_entry_attr_get_charptr()

slapi_entry_attr_get_int()

Gets the first value of an attribute in an entry as an integer.

Syntax 

#include "slapi-plugin.h"

int slapi_entry_attr_get_int(const Slapi_Entry* e, const char 
*type);

Parameters

This function takes the following parameters: 

e
Entry from which you want to get the integer value. 
type
Attribute type from which you want to get the value.

Returns

This function returns one of the following values:

slapi_entry_attr_get_long()

Gets the first value of an attribute in an entry as a long data type.

Syntax 

#include "slapi-plugin.h" 

long slapi_entry_attr_get_long( const Slapi_Entry* e, 

  const char *type);

Parameters

This function takes the following parameters: 

e
Entry from which you want to get the long value. 
type
Attribute type from which you want to get the value.

Returns

This function returns one of the following values:

slapi_entry_attr_get_uint()

Gets the first value of an attribute in an entry as an unsigned integer data type.

Syntax 

#include "slapi-plugin.h" 

unsigned int slapi_entry_attr_get_uint( const Slapi_Entry* e, 

  const char *type);

Parameters

This function takes the following parameters: 

e
Entry from which you want to get the value. 
type
Attribute type from which you want to get the value.

Returns

This function returns one of the following values:

slapi_entry_attr_get_ulong()

Gets the first value of an attribute in an entry as a unsigned long data type.

Syntax 

#include "slapi-plugin.h" 

unsigned long slapi_entry_attr_get_ulong( const Slapi_Entry* e, 

  const char *type);

Parameters

This function takes the following parameters: 

e
Entry from which you want to get the value. 
type
Attribute type from which you want to get the value.

Returns

This function returns one of the following values:

slapi_entry_attr_has_syntax_value()

Determines if an attribute in an entry contains a specified value.

Syntax 

#include "slapi-plugin.h" 

int slapi_entry_attr_has_syntax_value(const Slapi_Entry *e, 

  const char *type, const Slapi_Value *value);

Parameters 

e
Entry that you want to check. 
type
Attribute type that you want to test for the value specified. 
value
Value that you want to find in the attribute.

Returns

This function returns one of the following values:

Memory Concerns

value must not be NULL.

Description

This function replaces the deprecated slapi_entry_attr_hasvalue() function and takes into consideration the syntax of the attribute type.

slapi_entry_attr_merge_sv()

Adds an array of Slapi_Value data values to the existing attribute values in an entry. If the attribute does not exist, it is created with the Slapi_Value specified.

Syntax 

#include "slapi-plugin.h" 

int slapi_entry_attr_merge_sv( Slapi_Entry *e, 

  const char *type, Slapi_Value **vals );

Parameters

This function takes the following parameters: 

e
Entry to which you want to add values. 
type
Attribute to which you want to add values. 
vals
Array of Slapi_Value data values you want to add.

Returns

This function returns 0 if successful; any other value returned signals failure.

Description

This function replaces the deprecated slapi_entry_attr_merge() function. This function uses Slapi_Value attribute values instead of the now obsolete berval attribute values.

Memory Concerns

This function makes a copy of the parameter vals. vals can be NULL.

See Also 

slapi_entry_attr_merge()

slapi_entry_attr_replace_sv()

Replaces the values of an attribute with the Slapi_Value data value you specify.

Syntax 

#include "slapi-plugin.h" 

int slapi_entry_attr_replace_sv( Slapi_Entry *e, 

  const char *type, Slapi_Value **vals );

Parameters

This function takes the following parameters: 

e
Entry in which you want to replace values. 
type
Attribute type which will receive the replaced values. 
vals
Array containing the Slapi_Value values that should replace the existing values of the attribute.

Returns

This function returns 0 when successful; any other value returned signals failure.

Description

This function replaces existing attribute values in a specified entry with a single Slapi_Value data value. The function first deletes the existing attribute from the entry, then replaces it with the new value specified.

This function replaces the deprecated slapi_entry_attr_replace() function. This function uses Slapi_Value attribute values instead of the now obsolete berval attribute values.

Memory Concerns

This function makes a copy of the parameter vals. vals can be NULL.

See Also 

slapi_entry_attr_replace()

slapi_entry_attr_set_charptr()

Replaces the value or values of an attribute in an entry with a specified string value.

Syntax 

#include "slapi-plugin.h" 

void slapi_entry_attr_set_charptr(Slapi_Entry* e, 

  const char *type, const char *value);

Parameters

This function takes the following parameters: 

e
Entry in which you want to set the value. 
type
Attribute type in which you want to set the value. 
value
String value that you want to assign to the attribute.

Memory Concerns

This function makes a copy of the parameter values. values can be NULL; if so, this function is roughly equivalent to slapi_entry_attr_delete().

See Also 

slapi_entry_attr_delete()

slapi_entry_attr_set_int()

Replaces the value or values of an attribute in an entry with a specified integer data value.

Syntax 

#include "slapi-plugin.h" 

void slapi_entry_attr_set_int(Slapi_Entry* e, const char *type, 

  int l);

Parameters

This function takes the following parameters: 

e
Entry in which you want to set the value. 
type
Attribute type in which you want to set the value. 
l
Integer value that you want assigned to the attribute.

Description

This function will replace the value or values of an attribute with the integer value that you specify. If the attribute does not exist, it is created with the integer value that you specify.

slapi_entry_attr_set_long()

Replaces the value or values of an attribute in an entry with a specified long data type value.

Syntax 

#include "slapi-plugin.h"

void slapi_entry_attr_set_long(Slapi_Entry* e, const char *type, 

  long l);

Parameters

This function takes the following parameters: 

e
Entry in which you want to set the value. 
type
Attribute type in which you want to set the value. 
l
Long integer value that you want assigned to the attribute.

slapi_entry_attr_set_uint()

Replaces the value or values of an attribute in an entry with a specified unsigned integer data type value.

Syntax 

#include "slapi-plugin.h" 

void slapi_entry_attr_set_uint(Slapi_Entry* e, const char *type, 

  unsigned int l);

Parameters

This function takes the following parameters: 

e
Entry in which you want to set the value. 
type
Attribute type in which you want to set the value. 
l
Unsigned integer value that you want assigned to the attribute.

Description

This function will replace the value or values of an attribute with the unsigned integer value that you specify. If the attribute does not exist, it is created with the unsigned integer value you specify.

slapi_entry_attr_set_ulong()

Replaces the value or values of an attribute in an entry with a specified unsigned long data type value.

Syntax 

#include "slapi-plugin.h"

void slapi_entry_attr_set_ulong(Slapi_Entry* e, const char *type, 

  unsigned long l);

Parameters

This function takes the following parameters: 

e
Entry in which you want to set the value. 
type
Attribute type in which you want to set the value. 
l
Unsigned long value that you want assigned to the attribute.

Description

This function will replace the value or values of an attribute with the unsigned long value that you specify. If the attribute does not exist, it is created with the unsigned long value that you specify.

slapi_entry_delete_string()

Deletes a string value from an attribute in an entry.

Syntax 

#include "slapi-plugin.h" 

int slapi_entry_delete_string(Slapi_Entry *e, 

  const char *type, const char *value);

Parameters

This function takes the following parameters: 

e
Entry from which you want the string deleted.
 
type
Attribute type from which you want the string deleted.
 
value
Value of string to delete.

Returns

This function returns 0 when successful; any other value returned signals failure.

slapi_entry_delete_values_sv()

Removes an array of Slapi_Value data values from an attribute in an entry.

Syntax 

#include "slapi-plugin.h" 

int slapi_entry_delete_values_sv( Slapi_Entry *e, 

  const char *type, Slapi_Value **vals );

Parameters

This function takes the following parameters: 

e
Entry from which you want to delete values. 
type
Attribute from which you want to delete values.
 
vals
Array of Slapi_Value data values that you want to delete.

Returns

This function returns LDAP_SUCCESS if the specified attribute and the array of Slapi_Value data values are deleted from the entry.

If the specified attribute contains a NULL value, the attribute is deleted from the attribute list, and the function returns LDAP_NO_SUCH_ATTRIBUTE. As well, if the attribute is not found in the list of attributes for the specified entry, the function returns LDAP_NO_SUCH_ATTRIBUTE.

If there is an operational error during the processing of this call such as a duplicate value found, the function will return LDAP_OPERATIONS_ERROR. If this occurs, please report the problem to the Red Hat Technical Support.

Description

This function removes an attribute/valueset from an entry. Both the attribute and its Slapi_Value data values are removed from the entry. If you supply a Slapi_Value whose value is NULL, the function will delete the specified attribute from the entry. In either case, the function returns LDAP_SUCCESS.

This function replaces the deprecated slapi_entry_delete_values() function. This function uses Slapi_Value attribute values instead of the now obsolete berval attribute values.

Memory Concerns

The vals parameter can be NULL, in which case this function does nothing.

See Also 

slapi_entry_delete_values()

slapi_entry_dup()

Makes a copy of an entry, its DN, and its attributes.

Syntax 

#include "slapi-plugin.h" 

Slapi_Entry *slapi_entry_dup( const Slapi_Entry *e );

Parameters

This function takes the following parameter: 

e
Entry that you want to copy.

Returns

This function returns the new copy of the entry. If the structure cannot be duplicated, for example, if no more virtual memory exists, the slapd program terminates.

Description

This function returns a copy of an existing Slapi_Entry structure. You can call other front-end functions to change the DN and attributes of this entry.

Memory Concerns

When you are no longer using the entry, free it from memory by calling the slapi_entry_free() function.

See Also 

slapi_entry_alloc()
 
slapi_entry_free()

slapi_entry_first_attr()

Finds the first attribute in an entry. If you want to iterate through the attributes in an entry, use this function in conjunction with the slapi_entry_next_attr() function.

Syntax 

#include "slapi-plugin.h" 

int slapi_entry_first_attr( const Slapi_Entry *e, Slapi_Attr **attr 
);

Parameters

This function takes the following parameters: 

e
Entry from which you want to get the attribute.
 
attr
Pointer to the first attribute in the entry.

Returns

Returns 0 when successful; any other value returned signals failure.

Memory Concerns

Do not free the returned attr. This is a pointer into the internal entry data structure. If you need a copy, use slapi_attr_dup().

See Also 

slapi_attr_dup()

slapi_entry_free()

Frees an entry, its DN, and its attributes from memory.

Syntax 

#include "slapi-plugin.h" 

void slapi_entry_free( Slapi_Entry *e );

Parameters

This function takes the following parameter: 

e
Entry that you want to free. If NULL, no action occurs.

Description

Call this function to free an entry that you have allocated by using the slapi_entry_alloc() function or the slapi_entry_dup() function.

Memory Concerns

To free entries, always use this function instead of using slapi_ch_free() or free().

See Also 

slapi_entry_alloc()
 
slapi_entry_dup()

slapi_entry_get_dn()

Gets the distinguished name (DN) of the specified entry.

Syntax 

#include "slapi-plugin.h"

char *slapi_entry_get_dn( Slapi_Entry *e );

Parameters

This function takes the following parameter: 

e
Entry from which you want to get the DN.

Returns

This function returns the DN of the entry. This returns a pointer to the actual DN in the entry, not a copy of the DN. You should not free the DN unless you plan to replace it by calling slapi_entry_set_dn().

Memory Concerns

Use slapi_ch_free() if you are replacing the DN with slapi_entry_set_dn().

See Also 

slapi_ch_free()
 
slapi_entry_set_dn()

slapi_entry_get_dn_const()

Returns as a const the DN value of the entry that you specify.

Syntax 

#include "slapi-plugin.h" 

const char *slapi_entry_get_dn_const( 

  const Slapi_Entry *e );

Parameters

This function takes the following parameter: 

e
Entry from which you want to get the DN as a constant.

Returns

This function returns one of the following values:

Memory Concerns

Never free this value.

slapi_entry_get_ndn()

Returns the normalized DN from the entry that you specify.

Syntax 

#include "slapi-plugin.h" 

char *slapi_entry_get_ndn( Slapi_Entry *e );

Parameters

This function takes the following parameter: 

e
Entry from which you want to obtain the normalized DN.

Returns

This function returns the normalized DN from the entry that you specify. If the entry you specify does not contain a normalized DN, one is created through the processing of this function.

Memory Concerns

Never free this value.

slapi_entry_get_sdn()

Returns the Slapi_DN object from the entry that you specify.

Syntax 

#include "slapi-plugin.h" 

Slapi_DN *slapi_entry_get_sdn( Slapi_Entry *e );

Parameters

This function takes the following parameter: 

e
Entry from which you want to get the Slapi_DN object.

Returns

Returns the Slapi_DN object form the entry that you specify.

Memory Concerns

Never free this value. If you need a copy, use slapi_sdn_dup().

See Also 

slapi_sdn_dup()

slapi_entry_get_sdn_const()

Returns as a const the value of the Slapi_DN object from the entry that you specify.

Syntax 

#include "slapi-plugin.h" 

const Slapi_DN *slapi_entry_get_sdn_const ( 

  const Slapi_Entry *e );

Parameters

This function takes the following parameter: 

e
Entry from which you want to get the Slapi_DN object.

Returns

This function returns as a const the value of the Slapi_DN object from the entry that you specify.

Memory Concerns

Never free this value. If you need a copy, use slapi_sdn_dup().

See Also 

slapi_sdn_dup()

slapi_entry_get_uniqueid()

Gets the unique ID value of the entry.

Syntax 

#include "slapi-plugin.h" 

const char *slapi_entry_get_uniqueid( 

  const Slapi_Entry *e );

Parameters

This function takes the following parameter: 

e
Entry from which you want obtain the unique ID.

Returns

This function returns the unique ID value of the entry specified.

Memory Concerns

Never free this value. If you need a copy, use slapi_ch_strdup().

See Also 

slapi_ch_strdup()

slapi_entry_has_children()

This function determines if the specified entry has child entries.

Syntax 

#include "slapi-plugin.h" 

int slapi_entry_has_children(const Slapi_Entry *e);

Parameters

This function takes the following parameter: 

e
Entry that you want to test for child entries.

Returns

This function returns one of the following values:

slapi_entry_init()

Initializes the values of an entry with the DN and attribute value pairs you supply.

Syntax 

#include "slapi-plugin.h" 

void slapi_entry_init(Slapi_Entry *e, char *dn, 

  Slapi_Attr *a);

Parameters

This function takes the following parameters: 

e
The entry you want to initialize.
 
dn
The DN of the entry you are initializing. 
a
Initialization list of attribute value pairs, supplied as a Slapi_Attr data value.

Description

This function initializes the attributes and the corresponding attribute values of an entry. Also, during the course of processing, the unique ID of the entry is set to NULL, and the flag value is set to 0.

Use this function to initialize a Slapi_Entry pointer.

Memory Concerns

This function should always be used after slapi_entry_alloc() and never otherwise. For example: 

Slapi_Entry *e = slapi_entry_alloc();
 
slapi_entry_init(e, NULL, NULL);

To set the DN in the entry: 

slapi_sdn_set_dn_passin(slapi_entry_get_sdn(e), dn);

In this case, the dn argument is not copied but is consumed by the function. To copy the argument, see the following example: 

char *dn = slapi_ch_strdup(some_dn);
 
Slapi_Entry *e = slapi_entry_alloc()
 
slapi_entry_init(e, dn, NULL);l

dn is not freed in this context but will eventually be freed when slapi_entry_free() is called.

See Also 

slapi_entry_free()
 
slapi_entry_alloc()
 
slapi_ch_strdup()

slapi_entry_merge_values_sv()

Merges (adds) and array of Slapi_Value data values to a specified attribute in an entry. If the entry does not contain the attribute specified, the attribute is created with the value supplied.

Syntax 

#include "slapi-plugin.h" 

int slapi_entry_merge_values_sv( Slapi_Entry *e, 

  const char *type, Slapi_Value **vals );

Parameters

This function takes the following parameters: 

e
Entry into which you want to merge values.
 
type
Attribute type that contains the values you want to merge.
 
vals
Values that you want to merge into the entry. Values are of type Slapi_Value.

Returns

This function returns one of the following values:

Description

This function adds additional Slapi_Value data values to the existing values contained in an attribute. If the attribute type does not exist, it is created.

If the specified attribute exists in the entry, the function merges the value specified and returns LDAP_SUCCESS. If the attribute is not found in the entry, the function creates it with the Slapi_Value specified and returns LDAP_NO_SUCH_ATTRIBUTE.

If this function fails, it leaves the values for type within a pointer to e in an indeterminate state. The present valueset may be truncated. 

rc = delete_values_sv_internal( e, 

     type, vals, 1 /* Ignore Errors */ );

Memory Concerns

This function makes a copy of vals. vals can be NULL.

slapi_entry_next_attr()

Finds the next attribute after prevattr in an entry. To iterate through the attributes in an entry, use this function in conjunction with the slapi_entry_first_attr() function.

Syntax 

#include "slapi-plugin.h"

int slapi_entry_next_attr( const Slapi_Entry *e, 

  Slapi_Attr *prevattr, Slapi_Attr **attr );

Parameters

This function takes the following parameters: 

e
Entry from which you want to get the attribute. 
prevattr
Previous attribute in the entry. 
attr
Pointer to the next attribute after prevattr in the entry.

Returns

This function returns one of the following values:

Memory Concerns

Never free the returned attr. Use slapi_attr_dup() to make a copy if a copy is needed.

See Also 

slapi_attr_dup()

slapi_entry_rdn_values_present()

Determines whether the values in an entry's relative distinguished name (RDN) are also present as attribute values. For example, if the entry's RDN is cn=Barbara Jensen, the function determines if the entry has the cn attribute with the value Barbara Jensen.

Syntax 

#include "slapi-plugin.h"

int slapi_entry_rdn_values_present( const Slapi_Entry *e );

Parameters

This function takes the following parameter: 

e
Entry from which you want to get the attribute.

Returns

The function returns one of the following values:

slapi_entry_schema_check()

Determines whether the specified entry complies with the schema for its object class.

Syntax 

#include "slapi-plugin.h"

int slapi_entry_schema_check( Slapi_PBlock *pb, Slapi_Entry *e );

Parameters

This function takes the following parameters: 

pb
Parameter block. 
e
Entry of which you want to check the schema.

Returns

The function returns one of the following values:

Memory Concerns

The pb argument can be NULL. It is only used to get the SLAPI_IS_REPLACED_OPERATION flag. If that flag is present, no schema checking is done.

slapi_entry_set_dn()

Sets the distinguished name (DN) of an entry.

Syntax 

#include "slapi-plugin.h"

void slapi_entry_set_dn( Slapi_Entry *e, char *dn );

Parameters

This function takes the following parameters: 

e
Entry to which you want to assign the DN. 
dn
Distinguished name you want assigned to the entry.

Description

This function sets the DN pointer in the specified entry to the DN that you supply.

Memory Concerns

The dn will be freed eventually when slapi_entry_free() is called.

A copy of dn should be passed. For example: 

char *dn = slapi_ch_strdup(some_dn):

slapi_entry_set_dn(e, dn);

The old dn will be freed as a result of this call. Do not pass in a NULL value.

See Also 

slapi_entry_free()
 
slapi_entry_get_dn()

slapi_entry_set_sdn()

Sets the Slapi_DN value in an entry.

Syntax 

#include "slapi-plugin.h" 

void slapi_entry_set_sdn( Slapi_Entry *e, 

  const Slapi_DN *sdn );

Parameters

This function takes the following parameters: 

e
Entry to which you want to set the value of the Slapi_DN. 
sdn
The specified Slapi_DN value that you want to set.

Description

This function sets the value for the Slapi_DN object in the entry you specify.

Memory Concerns

This function makes a copy of the sdn argument.

slapi_entry_set_uniqueid()

Replaces the unique ID value of an entry with the unique ID value that you supply.

Syntax 

#include "slapi-plugin.h" 

void slapi_entry_set_uniqueid( Slapi_Entry *e, 

  char *uniqueid );

Parameters

This function takes the following parameters: 

e
Entry for which you want to generate a description. 
uniqueid
The unique ID value to which you want to assign the entry.

Description

This function replaces the unique ID value of the entry with the uniqueid value that you specify. In addition, the function adds SLAPI_ATTR_UNIQUEID to the attribute list and gives it the unique ID value supplied. If the entry already contains a SLAPI_ATTR_UNIQUEID attribute, its value is updated with the new value supplied.

Memory Concerns

Do not free the uniqueid after calling this function. The value will eventually be freed when slapi_entry_free() is called.

You should pass in a copy of the value because this function will consume the value passed in. For example: 

char *uniqueid = slapi_ch_strdup(some_uniqueid);

slapi_entry_set_uniqueid(e, uniqueid);

Do not pass in a NULL for uniqueid.

See Also 

slapi_entry_free()

slapi_entry_size()

This function returns the approximate size of an entry, rounded to the nearest 1k. This can be useful for checking cache sizes, estimating storage needs, and so on.

Syntax 

#include "slapi-plugin.h" 

size_t slapi_entry_size(Slapi_Entry *e);

Parameters

This function takes the following parameter: 

e
Entry from which you want the size returned.

Returns

This function returns one of the following values:

Description

When determining the size of an entry, only the sizes of the attribute values are counted; the size of other entry values (such as the size of attribute names, variously-normalized DNs, or any metadata) are not included in the size returned. It is assumed that the size of the metadata, et al., is well enough accounted for by the rounding of the size to the next largest 1k . This holds true especially in larger entries, where the actual size of the attribute values far outweighs the size of the metadata.

When determining the size of the entry, both deleted values and deleted attributes are included in the count.

slapi_is_rootdse()

This function determines if an entry is the root DSE. The root DSE is a special entry that contains information about the Directory Server, including its capabilities and configuration.

Syntax 

#include "slapi-plugin.h" 

int slapi_is_rootdse ( const char *dn );

Parameters

This function takes the following parameter: 

dn
The DN that you want to test to see if it is the root DSE entry.

Returns

This function returns one of the following values:

slapi_str2entry()

Converts an LDIF description of a directory entry (a string value) into an entry of the Slapi_Entry type.

Syntax 

#include "slapi-plugin.h"

Slapi_Entry *slapi_str2entry( char *s, int flags );

Parameters

This function takes the following parameters: 

s
Description of an entry that you want to convert to Slapi_Entry. 
flags
One or more flags specifying how the entry should be generated

The value of the flags argument can be one of the following values: 

SLAPI_STR2ENTRY_REMOVEDUPVALS
Removes any duplicate values in the attributes of the entry. 
SLAPI_STR2ENTRY_ADDRDNVALS
Adds the relative distinguished name (RDN) components (for example, uid=bjensen) as attributes of the entry.

Returns

This function returns one of the following values:

Description

A directory entry can be described by a string in LDIF format; for details, see "Converting between Entries and Strings," on page 69.

Calling the slapi_str2entry() function converts a string description in this format to a Slapi_Entry structure, which you can pass to other API functions.

Note

This function modifies the string argument s. If you still need to use this string value, you should make a copy of this string before calling slapi_str2entry().


If an error occurred during the conversion process, the function returns NULL instead of the entry.

When you are done working with the entry, you should call the slapi_entry_free() function.

To convert an entry to a string description, call the slapi_filter_free() function.

See Also 

slapi_filter_free()

Functions Related to Entry Flags

This section contains reference information on functions that are specific to entry flags.

Table 15-12 Entry Flags  
Function
Description
slapi_entry_clear_flag()
Clears a flag for a specified entry.
slapi_entry_flag_is_set()
Checks if certain flags are set in an entry.
slapi_entry_set_flag()
Sets a flag for an entry.

slapi_entry_clear_flag()

Clears a flag for a specified entry.

Syntax 

#include "slapi-plugin.h"

void slapi_entry_clear_flag( Slapi_Entry *e, unsigned char flag);

Parameters

This function takes the following parameters: 

e
Entry in which you want to clear the flag settings.
 
flag
Flag that you want to clear.

Description

In this release of Directory Server, the only external flag that can be set is SLAPI_ENTRY_FLAG_TOMBSTONE. This flag means that the entry is a tombstone entry. More flags may be exposed in future releases. Do not use your own flags.

See Also 

slapi_entry_flag_is_set()
 
slapi_entry_set_flag()

slapi_entry_flag_is_set()

Determines if certain flags are set for a specified entry.

Syntax 

#include "slapi-plugin.h" 

int slapi_entry_flag_is_set( const Slapi_Entry *e, 

  unsigned char flag );

Parameters

This function takes the following parameters: 

e
Entry in which you want to check the flag settings. 
flag
Flag of which you want to check for presence.

Returns

This function returns one of the following values:

Description

In this release of Directory Server, the only external flag that can be set is SLAPI_ENTRY_FLAG_TOMBSTONE. This flag means that the entry is a tombstone entry. More flags may be exposed in future releases. You should not use your own flags.

See Also 

slapi_entry_clear_flag()
 
slapi_entry_set_flag()

slapi_entry_set_flag()

Sets a flag for a specified entry.

Syntax 

#include "slapi-plugin.h"

void slapi_entry_set_flag( Slapi_Entry *e, unsigned char flag);

Parameters

This function takes the following parameters: 

e
Entry for which you want to set the flags.
 
flag
Flag that you want to set.

Description

In current versions of Directory Server, the only external flag that can be set is SLAPI_ENTRY_FLAG_TOMBSTONE. This flag means that the entry is a tombstone entry. More flags may be exposed in future releases. Do not use your own flags.

See Also 

slapi_entry_clear_flag()
 
slapi_entry_flag_is_set()

Functions for Dealing with Filters

This section contains reference information on filter routines.

Table 15-13 Filter Routines  
Function
Description
slapi_filter_apply()
Applies a function to each simple filter component within a complex filter.
slapi_filter_compare()
Determines if two filters are identical.
slapi_filter_dup()
Duplicates the specified filter.
slapi_filter_free()
Frees the specified filter.
slapi_filter_get_attribute_type()
Gets the attribute type for all simple filter choices.
slapi_filter_get_ava()
Gets the attribute type and the value from the filter.
slapi_filter_get_choice()
Gets the type of the specified filter.
slapi_filter_get_subfilt()
Gets the substring values from the filter.
slapi_filter_get_type()
Gets the attribute type specified in the filter.
slapi_filter_join()
Joins two specified filters.
slapi_filter_join_ex()
Recursively joins two specified filters.
slapi_filter_list_first()
Gets the first filter that makes up the specified filter.
slapi_filter_list_next()
Gets the next filter.
slapi_filter_test()
Determines if the specified entry matches a particular filter.
slapi_filter_test_ext()
Determines if an entry matches a given filter.
slapi_filter_test_simple()
Determines if an entry matches a filter.
slapi_find_matching_paren()
Finds the matching right parentheses in a string, corresponding to the left parenthesis to which the string currently points.
slapi_str2filter()
Converts a string description of a search filter into a filter of the Slapi_Filter type.
slapi_vattr_filter_test()
Tests a filter against a single entry.

slapi_filter_apply()

Applies a function to each simple filter component within a complex filter; a simple filter is anything other than AND, OR, or NOT.

Syntax 

#include "slapi-plugin.h"

int slapi_filter_apply( struct slapi_filter *f, FILTER_APPLY_FN fn, 

  void *arg, int *error_code );

Parameters

This function takes the following parameters: 

f
Filter on which the function is to be applied.
 
fn
Function to apply.
 
arg
Argument to the function (fn).
 
error_code

Pointer to error code of fn, which can be accessed by calling function. Possible values slapi_filter_apply() may set in error_code include SLAPI_FILTER_UNKNOWN_FILTER_TYPE. A FILTER_APPLY_FN should return _STOP or _CONTINUE only.


Returns

This function returns an integer. Possible return values for slapi_filter_apply() include:

slapi_filter_compare()

Determines if two filters are identical.

Syntax 

#include "slapi-plugin.h"

int slapi_filter_compare(struct slapi_filter *f1,

  struct slapi_filter *f2);

Parameters

This function takes the following parameters: 

f1
First filter to compare.
 
f2
Second filter to compare.

Returns

This function returns one of the following values:

Description

This function allows you to determine if two filters are identical and/or are allowed to be in a different order.

slapi_filter_dup()

Creates a duplicate of the specified filter.

Syntax 

#include "slapi-plugin.h"

Slapi_Filter *slapi_filter_dup(Slapi_Filter *f);

Parameters

This function takes the following parameter: 

f
Filter to duplicate.

Returns

This function returns a pointer to the duplicated filter if successful; otherwise, it returns NULL.

slapi_filter_free()

Frees the specified filter and (optionally) the set of filters that comprise it. For example, the set of filters in an LDAP_FILTER_AND type filter.

Syntax 

#include "slapi-plugin.h"

void slapi_filter_free( Slapi_Filter *f, int recurse );

Parameters

This function takes the following parameters: 

f
Filter that you want to free. 
recurse
If 1, recursively frees all filters that comprise this filter. If 0, only frees the filter specified by f.

Description

This function frees the filter in parameter f.

Memory Concerns

Filters created using slapi_str2filter() must be freed after using this function. Filters extracted from a pblock using slapi_pblock_get( pb,SLAPI_SEARCH_FILTER, &filter ) must not be freed.

See Also 

slapi_str2filter()
 
slapi_pblock_get()

slapi_filter_get_attribute_type()

Gets the attribute type for all simple filter choices.

Syntax 

#include "slapi-plugin.h"

int slapi_filter_get_attribute_type( Slapi_Filter *f, char **type 
);

Parameters

This function takes the following parameters: 

f
Filter from which you wish to get the substring values.
 
type
Pointer to the attribute type of the filter.

Returns

This function returns the attribute type of the filter.

Description

This function gets the attribute type for all simple filter choices:

A filter such as (mail-foo), will return the type mail.

Memory Concerns

The attribute type is returned in type and should not be freed after calling this function. It will be freed at the same time as the Slapi_Filter structure when slapi_filter_free() is called.

See Also 

slapi_filter_get_choice()
 
slapi_filter_get_ava()
 
slapi_filter_get_type()
 
slapi_filter_free()

slapi_filter_get_ava()

Applies only to filters of the types LDAP_FILTER_EQUALITY, LDAP_FILTER_GE, LDAP_FILTER_LE, LDAP_FILTER_APPROX. Gets the attribute type and the value from the filter.

Syntax 

#include "slapi-plugin.h"

int slapi_filter_get_ava( Slapi_Filter *f, char **type, 

  struct berval **bval );

Parameters

This function takes the following parameters: 

f
Filter from which you want to get the attribute and value. 
type
Pointer to the attribute type of the filter. 
bval
Pointer to the address of the berval structure containing the value of the filter.

Returns

This function returns one of the following values:

Description

Filters of the type LDAP_FILTER_EQUALITY, LDAP_FILTER_GE, LDAP_FILTER_LE, and LDAP_FILTER_APPROX generally compare a value against an attribute. For example: 

(cn=Barbara Jensen)

This filter finds entries in which the value of the cn attribute is equal to Barbara Jensen.

The attribute type is returned in the parameter type, and the value is returned in the parameter bval.

Memory Concerns

The strings within the parameters type and bval are direct pointers to memory inside the Slapi_Filter and therefore should not be freed after usage. They will be freed when a server entity calls slapi_filter_free() after usage of the Slapi_Filter structure.

See Also 

slapi_filter_get_choice()
 
slapi_filter_get_type()
 
slapi_filter_get_attribute_type()

slapi_filter_get_choice()

Gets the type of the specified filter; for example, LDAP_FILTER_EQUALITY.

Syntax 

#include "slapi-plugin.h"

int slapi_filter_get_choice( Slapi_Filter *f );

Parameters

This function takes the following parameters: 

f
Filter of which you want to get type.

Returns

This function returns one of the following values:

For example: (&(ou=Accounting)(l=Sunnyvale))
For example: (|(ou=Accounting)(l=Sunnyvale))
For example: (!(l=Sunnyvale))
For example: (ou=Accounting)
For example: (ou=Account*Department)
For example: (supportedLDAPVersion>=3)
For example: (supportedLDAPVersion<=2)
For example: (mail=*)
For example: (ou~=Sales)
For example: (o:dn:=Example)

See Also 

slapi_filter_get_type()
 
slapi_filter_get_attribute_type()
 
slapi_filter_get_ava()

slapi_filter_get_subfilt()

Applies only to filters of the type LDAP_FILTER_SUBSTRINGS. Gets the substring values from the filter.

Syntax 

#include "slapi-plugin.h"

int slapi_filter_get_subfilt( Slapi_Filter *f, char **type, 

  char **initial, char ***any, char **final );

Parameters

This function takes the following parameters: 

f
Filter that you want to get the substring values from. 
type
Pointer to the attribute type of the filter. 
initial
Pointer to the initial substring ("starts with") of the filter. 
any
Pointer to an array of the substrings ("contains") for the filter. 
final
Pointer to the final substring ("ends with") of the filter.

Returns

This function returns one of the following values:

Description

Filters of the type LDAP_FILTER_SUBSTRINGS generally compare a set of substrings against an attribute. For example: 

(cn=John*Q*Public)

This filter finds entries in which the value of the cn attribute starts with John, contains Q, and ends with Public.

Call this function to get these substring values as well as the attribute type from this filter. In the case of the example above, calling this function gets the initial substring John, the any substring Q, and the final substring Public in addition to the attribute type cn.

See Also 

slapi_filter_get_attribute_type()
 
slapi_filter_get_ava()
 
slapi_filter_get_choice()

slapi_filter_get_type()

Applies only to filters of the type LDAP_FILTER_PRESENT. Gets the attribute type specified in the filter.

Syntax 

#include "slapi-plugin.h"

int slapi_filter_get_type( Slapi_Filter *f, char **type );

Parameters

This function takes the following parameters: 

f
Filter from which you want to get the substring values. 
type
Pointer to the attribute type of the filter.

Returns

This function returns one of the following values:

Description

Filters of the type LDAP_FILTER_PRESENT generally determine if a specified attribute is assigned a value. For example: 

(mail=*)

This filter finds entries that have a value assigned to the mail attribute.

Call this function to get the attribute type from this filter. In the case of the example above, calling this function gets the attribute type mail.

Memory Concerns

The string returned in the parameter type must not be freed after calling this function. It will be freed when the structure Slapi_Filter is freed by calling slapi_filter_free().

See Also 

slapi_filter_get_attribute_type()
 
slapi_filter_get_ava()
 
slapi_filter_get_choice()

slapi_filter_join()

Joins the two specified filters using one of the following filter types: LDAP_FILTER_AND, LDAP_FILTER_OR, or LDAP_FILTER_NOT. When specifying the filter type LDAP_FILTER_NOT, the second filter should be NULL.

Syntax 

#include "slapi-plugin.h"

Slapi_Filter *slapi_filter_join( int ftype, 

  Slapi_Filter *f1, Slapi_Filter *f2 );

Parameters

This function takes the following parameters: 

ftype
Type of composite filter you want to create. 
f1
First filter that you want to join. 
f2
Second filter that you want to join. If ftype is LDAP_FILTER_NOT, specify NULL for this argument.

Returns

This function returns the new filter constructed from the other two filters.

Description

Filters of the type LDAP_FILTER_AND, LDAP_FILTER_OR, and LDAP_FILTER_NOT generally consist of one or more other filters. For example: 

(&(ou=Accounting)(l=Sunnyvale))
 
(|(ou=Accounting)(l=Sunnyvale))
 
(!(l=Sunnyvale))

Each of these examples contain one or more LDAP_FILTER_EQUALITY filters.

Call the slapi_filter_join() function to create a new filter of the type LDAP_FILTER_AND, LDAP_FILTER_OR, or LDAP_FILTER_NOT.

Memory Concerns

The f1 and f2 filters are neither copied nor freed during the join process, but the resulting filter will have references pointing to these two filters.

See Also

slapi_filter_join() uses slapi_filter_join_ex() with the recurse_always argument being 1.

slapi_filter_join_ex()

Recursively joins the two specified filters using one of the following filter types: LDAP_FILTER_AND, LDAP_FILTER_OR, or LDAP_FILTER_NOT. When specifying the filter type LDAP_FILTER_NOT, the second filter should be NULL.

Syntax 

#include "slapi-plugin.h"

Slapi_Filter *slapi_filter_join_ex( int ftype, Slapi_Filter *f1,

Slapi_Filter *f2, int recurse_always );

Parameters

This function takes the following parameters: 

ftype
Type of composite filter you want to create. 
f1
First filter that you want to join. 
f2
Second filter that you want to join. If ftype is LDAP_FILTER_NOT, specify NULL for this argument. 
recurse_always
Recursively joins filters f1 and f2.

Returns

This function returns the new filter constructed from the other two filters.

Description

Filters of the type LDAP_FILTER_AND, LDAP_FILTER_OR, and LDAP_FILTER_NOT generally consist of one or more other filters. For example: 

(&(ou=Accounting)(l=Sunnyvale))

(|(ou=Accounting)(l=Sunnyvale))

(!(l=Sunnyvale))

Each of these examples contain one or more LDAP_FILTER_EQUALITY filters.

Call the slapi_filter_join() function to create a new filter of the type LDAP_FILTER_AND, LDAP_FILTER_OR, or LDAP_FILTER_NOT.

Memory Concerns

The f1 and f2 filters are neither copied nor freed during the join process, but the resulting filter will have references pointing to these two filters.

See Also

slapi_filter_join() uses slapi_filter_join_ex() with recurse_always argument set to 1.

slapi_filter_list_first()

Applies only to filters of the types LDAP_FILTER_EQUALITY, LDAP_FILTER_GE, LDAP_FILTER_LE, and LDAP_FILTER_APPROX. Gets the first filter that makes up the specified filter.

Syntax 

#include "slapi-plugin.h"

Slapi_Filter *slapi_filter_list_first( Slapi_Filter *f );

Parameters

This function takes the following parameter: 

f
Filter of which you want to get the first component.

Returns

This function returns the first filter that makes up the specified filter f.

Description

To iterate through all filters that make up a specified filter, use this function in conjunction with the slapi_filter_list_next() function.

Filters of the type LDAP_FILTER_AND, LDAP_FILTER_OR, and LDAP_FILTER_NOT generally consist of one or more other filters. For example, if the filter is: 

(&(ou=Accounting)(l=Sunnyvale))

the first filter in this list is: 

(ou=Accounting)

Call the slapi_filter_list_first() function to get the first filter in the list.

Memory Concerns

No duplication of the filter is done, so this filter should not be freed independently of the original filter.

See Also 

slapi_filter_list_next()

slapi_filter_list_next()

Applies only to filters of the types LDAP_FILTER_EQUALITY, LDAP_FILTER_GE, LDAP_FILTER_LE, and LDAP_FILTER_APPROX. Gets the next filter (following fprev) that makes up the specified filter f.

Syntax 

#include "slapi-plugin.h"

Slapi_Filter *slapi_filter_list_next( Slapi_Filter *f, 

  Slapi_Filter *fprev );

Parameters

This function takes the following parameters: 

f
Filter from which you want to get the next component (after fprev). 
fprev
Filter within the specified filter f.

Returns

This function returns the next filter (after fprev) that makes up the specified filter f.

Description

To iterate through all filters that make up a specified filter, use this function in conjunction with the slapi_filter_list_first() function.

Filters of the type LDAP_FILTER_AND, LDAP_FILTER_OR, and LDAP_FILTER_NOT generally consist of one or more other filters. For example, if the filter is: 

(&(ou=Accounting)(l=Sunnyvale))

the next filter after (ou=Accounting) in this list is: 

(l=Sunnyvale)

Call the slapi_filter_list_next() function to get the filters from this list.

Memory Concerns

No duplication of the filter is done, so this filter should not be freed independently of the original filter.

See Also 

slapi_filter_list_first()

slapi_filter_test()

Determines if the specified entry matches a particular filter.

Syntax 

#include "slapi-plugin.h"

int slapi_filter_test( Slapi_PBlock *pb, 

  Slapi_Entry *e, Slapi_Filter *f, int verify_access );

Parameters

This function takes the following parameters: 

pb
Parameter block.
 
e
Entry that you want to test.
 
f
Filter that you want to test the entry against.
 
verify_access
If 1, verifies that the current user has access rights to search the specified entry. If 0, bypasses any access control.

Returns

This function returns one of the following values:

See Also 

slapi_filter_test_simple()
 
slapi_filter_test_ext()

slapi_filter_test_ext()

Determines if an entry matches a given filter.

Syntax 

#include "slapi-plugin.h"

int slapi_filter_test_ext( Slapi_PBlock *pb, Slapi_Entry *e,

  Slapi_Filter *f,int verify_access, int only_test_access)

Parameters

This function takes the following parameters: 

pb
pblock from which the user is extracted.
 
e
The entry on which filter matching must be verified.
 
f
The filter used for filter matching.
 
verify_access
0 when access checking is not to be done.
1 when access checking must be done.
 
only_test_access
0 when filter matching must be done.
1 when filter matching must not be done.

Returns

This function returns one of the following values:

Description

This function allows you to determine if an entry matches a given filter and/or that the current user has the permission to access the entry.

See Also 

slapi_filter_test_simple()
 
slapi_filter_test()

slapi_filter_test_simple()

Determines if an entry matches a filter.

Syntax 

#include "slapi-plugin.h"

int slapi_filter_test_simple( Slapi_Entry *e, Slapi_Filter *f);

Parameters

This function takes the following parameters: 

e
Entry that you wish to test.
 
f
Filter to match the entry against.

Returns

This function returns one of the following values:

Description

This function allows you to check if entry e matches filter f.

See Also 

slapi_filter_test()
 
slapi_filter_test_ext()

slapi_find_matching_paren()

Finds the matching right parentheses in a string, corresponding to the left parenthesis to which the string currently points.

Syntax 

#include "slapi-plugin.h"

char *slapi_find_matching_paren( const char *str )

Parameters

This function takes the following parameter: 

str
String containing the parentheses.

Returns

This function returns a pointer to the matching right parenthesis in the specified string.

slapi_str2filter()

Converts a string description of a search filter into a filter of the Slapi_Filter type.

Syntax 

#include "slapi-plugin.h"

Slapi_Filter *slapi_str2filter( char *str );

Parameters

This function takes the following parameter: 

str
String description of a search filter.

Returns

This function returns one of the following values:

When you are done working with this filter, you should free the Slapi_Filter structure by calling slapi_filter_free().

slapi_vattr_filter_test()

Tests a filter against a single entry.

Syntax 

#include "slapi-plugin.h"

int slapi_vattr_filter_test( Slapi_PBlock *pb, Slapi_Entry *e, 

  struct slapi_filter *f, int verify_access);

Parameters

This function takes the following parameters: 

pb
Parameter block containing information about the filter.
 
e
Entry against which the filter is to be tested.
 
f
Filter against which the entry is to be tested.
 
verify_access
Access control:
  • 0 if access checking is not to be done; that is, bypass any access control.
  • 1 if access checking must be done; that is, verify that the current user has access rights to search the specified entry.

Returns

This function returns one of the following values:

Description

This function supports the case where the filter specifies virtual attributes. Performance for a real-attribute-only filter is the same as that for slapi_filter_test().

See Also 

slapi_filter_test()

Functions Specific to Extended Operation

This section contains reference information on routines for dealing with extended operations.

Table 15-14 Extended Operation Routines  
Function
Description
slapi_get_supported_extended_ops_copy()
Gets a copy of the object IDs (OIDs) of the extended operations.

slapi_get_supported_extended_ops_copy()

Gets a copy of the object IDs (OIDs) of the extended operations.

Syntax 

#include "slapi-plugin.h"

char **slapi_get_supported_extended_ops_copy ( void );

Parameters

This function takes no parameters.

Returns

This function returns a pointer to an array of the OIDs of the extended operations supported by the server.

Description

This function replaces the deprecated slapi_get_supported_extended_ops() function from earlier releases as slapi_get_supported_extended_ops() was not multi-thread safe.

This function gets a copy of the object IDs (OIDs) of the extended operations supported by the server. You can register new extended operations by putting the OID in the SLAPI_PLUGIN_EXT_OP_OIDLIST parameter and calling slapi_block_set().

Memory Concerns

The array returned by this function should be freed by calling the slapi_ch_array_free() function.

See Also 

slapi_pblock_set()
 
slapi_ch_array_free()

Functions Specific to Bind Methods

This section contains reference information on bind routines, including SASL.

Table 15-15 Bind Routines  
Function
Description
slapi_get_supported_saslmechanisms_copy()
Gets an array of the names of the supported Simple Authentication and Security Layer (SASL) methods.
slapi_register_supported_saslmechanism()
Registers the specified Simple Authentication and Security Layer (SASL) method with the server.

slapi_get_supported_saslmechanisms_copy()

Gets an array of the names of the supported Simple Authentication and Security Layer (SASL) mechanisms. You can register new SASL mechanisms by calling the slapi_vattr_values_free() function.

Syntax 

#include "slapi-plugin.h"

char ** slapi_get_supported_saslmechanisms_copy( void );

Returns

This function returns a pointer to an array of the names of SASL mechanisms supported by the server.

slapi_register_supported_saslmechanism()

Registers the specified Simple Authentication and Security Layer (SASL) mechanism with the server.

Syntax 

#include "slapi-plugin.h"

void slapi_register_supported_saslmechanism( char *mechanism );

Parameters

This function takes the following parameter: 

mechanism
Name of the SASL mechanism.

See Also

"Functions for Managing DNs," on page 463.

Functions for Thread-Safe LDAP Connections

This section contains reference information on functions for thread-safe LDAP connections.

Table 15-16 Thread-Safe LDAP Connection Routines  
Function
Description
slapi_ldap_init()
Initializes an LDAP session with another LDAP server.
slapi_ldap_unbind()
Unbinds from another LDAP server and frees the resources contained in the LDAP structure.

slapi_ldap_init()

Initializes an LDAP session with another LDAP server.

Syntax 

#include "slapi-plugin.h"

LDAP *slapi_ldap_init( char *ldaphost, int ldapport, 

  int secure, int shared );

Parameters

This function takes the following parameters: 

ldaphost
Space-delimited list of one or more hostnames (or IP address in dotted notation, such as 141.211.83.36) of the LDAP servers to which you want to connect.
The names can be in hostname:portnumber format, in which case portnumber overrides the port number specified by the ldapport argument. 
ldapport
Port number of the LDAP server. 
secure
Determines whether to establish the connection over SSL. Set this to a non-zero value to establish the connection over SSL. 
shared
Determines whether the LDAP session (the LDAP structure) can be shared by different threads. Set this to a non-zero value to allow multiple threads to share the session.

Returns

This function returns one of the following values:

Description

This function initializes an LDAP session with another LDAP server. If you want to connect to another LDAP server over SSL or if you want to allow multiple threads to use the same connection, call this function instead of the ldap_init() function provided with the Red Hat Directory SDK.

This function allocates an LDAP structure containing information about the session, including the hostname and port of the LDAP server, preferences for the session (such as the maximum number of entries to return in a search), and the error code of the last LDAP operation performed.

You can specify a list of LDAP servers that you want to attempt to connect to. Your client will attempt to connect to the first LDAP server in the list. If the attempt fails, your client will attempt to connect to the next LDAP server in the list.

If you specify a non-zero value for the secure argument, this function initializes the plug-in for SSL and installs the I/O routines for SSL.

If you specify a non-zero value for the shared argument, this function installs the server's threading functions and allows multiple threads to share this session (the returned LDAP structure). The Directory Server processes each request in a separate thread. When handling multiple requests, it is possible for the server to call your plug-in function concurrently for different threads.

If you initialize a session by calling this function, make sure to call the slapi_ldap_unbind() function (not the ldap_unbind() or ldap_unbind_s() functions provided with the Directory Server SDK) when you are done with the session.

As the slapi_ldap_init() function returns a regular LDAP *, you can use the LDAP C SDK connect timeout feature for plug-ins. That is, when connecting to an external LDAP server from a plug-in, you can specify a time limit for establishing the connection. To specify the timeout, call ldap_set_option() with the LDAP_X_OPT_CONNECT_TIMEOUT option after calling slapi_ldap_init(), as illustrated in the sample code below: 

void

my_ldap_function( void ) 

{
 
LDAP *ld; 

int to = 5000;  /* 5000 milliseconds == 5 second timeout */
 
if (( ld = slapi_ldap_init( host, port, 0, 1 )) == NULL ) { 

    /* error trying to create an LDAP session */ 

    return -1;

}

if ( ldap_set_option( ld, LDAP_X_OPT_CONNECT_TIMEOUT, &to ) != 0 ) {

    /* error setting timeout */

    slapi_ldap_unbind( ld );

    return -1;

}

/* use the handle, e.g., call ldap_search_ext() */

slapi_ldap_unbind( ld );

return 0;
 
}

slapi_ldap_unbind()

Unbinds from another LDAP server and frees the resources contained in the LDAP structure.

Syntax 

#include "slapi-plugin.h"

void slapi_ldap_unbind( LDAP *ld );

Parameters

This function takes the following parameter: 

ld
Connection handle, which is a pointer to an LDAP structure containing information about the connection to the LDAP server.

Description

This function unbinds from another LDAP server. Call this function if you initialized the LDAP session with the slapi_ldap_init() function. Do not call the ldap_unbind() or ldap_unbind_s() functions provided with the Red Hat Directory SDK.

Functions for Logging

This section contains reference information on logging routines.

Table 15-17 Logging Routines  
Function
Description
slapi_log_error()
Writes a message to the error log for the Directory Server.
slapi_is_loglevel_set()
Checks if loglevel is selected as a log level.

slapi_log_error()

Writes a message to the error log for the Directory Server. By default, the error log file is server_root/slapd-instance_id/logs/errors.

Syntax 

#include "slapi-plugin.h"

int slapi_log_error( int severity, char *subsystem, 

  char *fmt, ... );

Parameters

This function takes the following parameters: 

severity
Level of severity of the message. In combination with the severity level specified by the administrator, this determines whether the message is written to the log. 
subsystem
Name of the subsystem in which this function is called. The string that you specify here appears in the error log in the following format:
subsystem_name:message
 
fmt, ...
Message that you want written. This message can be in printf()-style format. For example:
..., "%s\n", myString);

The severity argument corresponds to the Log Level setting selected by in the Server Manager under Server Preferences | LDAP. If a Log Level setting is selected, messages with that severity level are written to the error log. The severity argument can have one of the following values: 

SLAPI_LOG_FATAL
Always written to the error log.
This severity level indicates that a fatal error has occurred in the server. 
SLAPI_LOG_TRACE
Written to the error log if the Log Level setting "Trace function calls" is selected.
This severity level is typically used to indicate what function is being called. 
SLAPI_LOG_PACKETS
Written to the error log if the Log Level setting "Packet handling" is selected. 
SLAPI_LOG_ARGS
Written to the error log if the Log Level setting "Heavy trace output" is selected. 
SLAPI_LOG_CONNS
Written to the error log if the Log Level setting "Connection management" is selected. 
SLAPI_LOG_BER
Written to the error log if the Log Level setting "Packets sent/received" is selected. 
SLAPI_LOG_FILTER
Written to the error log if the Log Level setting "Search filter processing" is selected. 
SLAPI_LOG_CONFIG
Written to the error log if the Log Level setting "Config file processing" is selected. 
SLAPI_LOG_ACL
Written to the error log if the Log Level setting "Access control list processing" is selected. 
SLAPI_LOG_SHELL
Written to the error log if the Log Level setting "Log communications with shell back-ends" is selected. 
SLAPI_LOG_PARSE
Written to the error log if the Log Level setting "Log entry parsing" is selected. 
SLAPI_LOG_HOUSE
Written to the error log if the Log Level setting "Housekeeping" is selected. 
SLAPI_LOG_REPL
Written to the error log if the Log Level setting "Replication" is selected. 
SLAPI_LOG_CACHE
Written to the error log if the Log Level setting "Entry cache" is selected. 
SLAPI_LOG_PLUGIN
Written to the error log if the Log Level setting "Plug-ins" is selected.
This severity level is typically used to identify messages from server plug-ins.

Returns

This function returns one of the following values:

slapi_is_loglevel_set()

Checks if loglevel is selected as a log level.

Syntax 

#include "slapi-plugin.h"

int slapi_is_loglevel_set( const int loglevel );

Parameters

This function takes the following parameter: 

loglevel
Log level setting to check.

Returns

The function returns one of the following values:

Description

To specify the level of logging used by the Directory Server, the administrator can use the Server Console or set the nsslapd-errorlog-level attribute. For more information, see Red Hat Directory Server Configuration, Command, and File Reference.

Functions for Handling Matching Rules

This section contains reference information on matching rule routines.

Table 15-18 Matching Rule Routines  
Function
Description
slapi_berval_cmp()
Compares two berval structures to determine if they are equal.
slapi_matchingrule_free()
Frees the specified matching rule structure (and, optionally, its members) from memory.
slapi_matchingrule_get()
Gets information about a matching rule.
slapi_matchingrule_new()
Allocates memory for a new Slapi_MatchingRuleEntry structure.
slapi_matchingrule_register()
Registers the specified matching rule with the server.
slapi_matchingrule_set()
Sets information about the matching rule.
slapi_matchingrule_unregister()
Placeholder for future function. Currently, this function does nothing.
slapi_mr_filter_index()
Calls the indexer function associated with an extensible match filter.
slapi_mr_indexer_create()
Calls the indexer factory function for the plug-in responsible for a specified matching rule.

slapi_berval_cmp()

Compares two berval structures to determine if they are equal.

Syntax 

#include "slapi-plugin.h"

int slapi_berval_cmp (const struct berval *L, 

  const struct berval *R);

Parameters

This function takes the following parameters: 

L
Pointer to the first berval structure that you want to compare. 
R
Pointer to the second structure that you want to compare.

Returns

This function returns one of the following values:

slapi_matchingrule_free()

Frees the specified matching rule structure (and, optionally, its members) from memory.

Syntax 

#include "slapi-plugin.h" 

void slapi_matchingrule_free(Slapi_MatchingRuleEntry **mrEntry, 

  int freeMembers);

Parameters

This function takes the following parameters: 

mrEntry
The Slapi_MatchingRuleEntry structure that you want to free from memory. 
freeMembers
If 1, the function also frees the members of the structure from memory.

Description

This function frees a Slapi_MatchingRuleEntry structure (and, optionally, its members) from memory. Call this function when you are done working with the structure.

slapi_matchingrule_get()

Gets information about a matching rule.

Syntax 

#include "slapi-plugin.h"

int slapi_matchingrule_get(SlPi_MatchingRuleEntry *mr, 

  int arg, void *value);

Parameters

This function takes the following parameters: 

mr
Slapi_MatchingRuleEntry structure from which you want to get data. 
arg
ID specifying the type of information you want to get. 
value
Pointer to a variable to hold the retrieved data.

The arg argument can have one of the following values:

ID
Data Type of the value Argument
Description
 
SLAPI_MATCHINGRULE_NAME
 

char *
Name of the matching rule.
 
SLAPI_MATCHINGRULE_OID
 

char *
OID of the matching rule. 
SLAPI_MATCHINGRULE_DESC
 

char *
Description of the matching rule. 
SLAPI_MATCHINGRULE_SYNTAX
 

char *
Syntax supported by the matching rule.
 
SLAPI_MATCHINGRULE_OBSOLETE
 

int
If 1, the matching rule is obsolete.

Returns

This function returns one of the following values:

Description

This function gets information about a matching rule from the Slapi_MatchingRuleEntry structure. To set information in this structure, call the slapi_matchingrule_set() function.

slapi_matchingrule_new()

Allocates memory for a new Slapi_MatchingRuleEntry structure.

Syntax 

#include "slapi-plugin.h"

Slapi_MatchingRuleEntry *slapi_matchingrule_new();

Returns

This function returns one of the following values:

Description

This function allocates memory for a new Slapi_MatchingRuleEntry structure, which represents a matching rule. After you call this function, you can call the slapi_matchingrule_set() function to set the values in this structure and call the slapi_matchingrule_register() function to register the matching rule.

slapi_matchingrule_register()

Registers the specified matching rule with the server.

Syntax 

#include "slapi-plugin.h"

int slapi_matchingrule_register(Slapi_MatchingRuleEntry *mrEntry);

Parameters

This function takes the following parameter: 

mrEntry
Slapi_MatchingRuleEntry structure representing the matching rule that you want to register.

Returns

This function returns one of the following values:

Description

This function registers the specified matching rule with the server. To create the matching rule and set its values, call the slapi_matchingrule_new() function and the slapi_matchingrule_set() function.

slapi_matchingrule_set()

Sets information about the matching rule.

Syntax 

#include "slapi-plugin.h" 

int slapi_matchingrule_set(Slapi_MatchingRuleEntry *mr, 

  int arg, void *value);

Parameters

This function takes the following parameters: 

mr
Slapi_MatchingRuleEntry structure in which you want to set data. 
arg
ID specifying the type of information you want to set. 
value
The value that you want to set.

The arg argument can have one of the following values:

ID
Data Type of the value Argument
Description
 
SLAPI_MATCHINGRULE_NAME
 

char *
Name of the matching rule.
 
SLAPI_MATCHINGRULE_OID
 

char *
OID of the matching rule. 
SLAPI_MATCHINGRULE_DESC
 

char *
Description of the matching rule. 
SLAPI_MATCHINGRULE_SYNTAX
 

char *
Syntax supported by the matching rule. 
SLAPI_MATCHINGRULE_OBSOLETE
 

int
If 1, the matching rule is obsolete.

Returns

This function returns one of the following values:

Description

This function sets information in an Slapi_MatchingRuleEntry structure. To get information from this structure, call the slapi_matchingrule_get() function.

slapi_matchingrule_unregister()

Placeholder for future function. Currently, this function does nothing.

Syntax 

#include "slapi-plugin.h"

int slapi_matchingrule_unregister(char *oid);

slapi_mr_filter_index()

Calls the indexer function associated with an extensible match filter.

Syntax 

#include "slapi-plugin.h"

int slapi_mr_filter_index (Slapi_Filter *f, Slapi_PBlock *pb);

Parameters

This function takes the following parameters: 

f
Pointer to a Slapi_Filter structure, representing the extensible match filter for which you want to find the indexer function. 
pb
Parameter block containing information about the extensible match filter.

Returns

This function returns the result code returned by the indexer function.

Description

If the filter specified by the f argument is an extensible match filter, this function calls the indexer function associated with the filter.

Before calling this function, make sure that the parameter block pb contains the information needed by the indexer function. You can pass information to the indexer function by using the following parameters:

The indexer function should set the SLAPI_PLUGIN_MR_KEYS parameter of the parameter block pb to an array of the keys that correspond to the values in the SLAPI_PLUGIN_MR_VALUES parameter.

For more information on filter index functions and indexer functions, see Chapter 11, "Writing Matching Rule Plug-ins."

slapi_mr_indexer_create()

Calls the indexer factory function for the plug-in responsible for a specified matching rule.

Syntax 

#include "slapi-plugin.h"

int slapi_mr_indexer_create (Slapi_PBlock *opb);

Parameters

This function takes the following parameter: 

pb
Parameter block containing information about the matching rule and attribute type to be used in indexing or sorting.

Returns

This function returns the result code returned by the indexer factory function.

Description

This function calls the indexer factory function for the plug-in responsible for handing a specified matching rule. The matching rule is identified by the OID in the SLAPI_PLUGIN_MR_OID parameter.

If no plug-ins are associated with this matching rule, the function calls the indexer factory function for each matching rule plug-in until the SLAPI_PLUGIN_MR_INDEX_FN parameter is set to an indexer function.

Before calling this function, make sure that the parameter block pb contains the information needed by the indexer factory function. You can pass information to the indexer factory function by using the following parameters:

The indexer factory function should set the following parameters:

For more information on filter index functions and indexer functions, see Chapter 11, "Writing Matching Rule Plug-ins."

Functions for LDAPMod Manipulation

This section contains reference information on LDAPMod manipulation routines.

Table 15-19 LDAPMod Manipulation Routines  
Function
Description
slapi_entry2mods()
Creates an array of LDAPMod from a Slapi_Entry.
slapi_mod_add_value()
Adds a value to a Slapi_Mod structure.
slapi_mod_done()
Frees internals of Slapi_Mod structure.
slapi_mod_dump()
Dumps the contents of an LDAPMod to the server log.
slapi_mod_free()
Frees a Slapi_Mod structure.
slapi_mod_get_first_value()
Initializes a Slapi_Mod iterator and returns the first attribute value.
slapi_mod_get_ldapmod_byref()
Gets a reference to the LDAPMod in a Slapi_Mod structure.
slapi_mod_get_ldapmod_passout()
Retrieves the LDAPMod contained in a Slapi_Mod structure.
slapi_mod_get_next_value()
Increments the Slapi_Mod iterator and returns the next attribute value.
slapi_mod_get_num_values()
Gets the number of values in a Slapi_Mod structure.
slapi_mod_get_operation()
Gets the operation type of Slapi_Mod structure.
slapi_mod_get_type()
Gets the attribute type of a Slapi_Mod structure.
slapi_mod_init()
Initializes a Slapi_Mod structure.
slapi_mod_init_byref()
Initializes a Slapi_Mod structure that is a wrapper for an existing LDAPMod.
slapi_mod_init_byval()
Initializes a Slapi_Mod structure with a copy of an LDAPMod.
slapi_mod_init_passin()
Initializes a Slapi_Mod from an LDAPMod.
slapi_mod_isvalid()
Determines whether a Slapi_Mod structure is valid.
slapi_mod_new()
Allocates a new Slapi_Mod structure.
slapi_mod_remove_value()
Removes the value at the current Slapi_Mod iterator position.
slapi_mod_set_operation()
Sets the operation type of a Slapi_Mod structure.
slapi_mod_set_type()
Sets the attribute type of a Slapi_Mod.
slapi_mods2entry()
Creates a Slapi_Entry from an array of LDAPMod.
slapi_mods_add()
Appends a new mod with a single attribute value to Slapi_Mods structure.
slapi_mods_add_ldapmod()
Appends an LDAPMod to a Slapi_Mods structure.
slapi_mods_add_mod_values()
Appends a new mod to a Slapi_Mods structure with attribute values provided as an array of Slapi_Value.
slapi_mods_add_modbvps()
Appends a new mod to a Slapi_Mods structure,with attribute values provided as an array of berval.
slapi_mods_add_smod()
Appends a new smod to a Slapi_Mods structure.
slapi_mods_add_string()
Appends a new mod to Slapi_Mods structure with a single attribute value provided as a string.
slapi_mods_done()
Frees internals of a Slapi_Mods structure.
slapi_mods_dump()
Dumps the contents of a Slapi_Mods structure to the server log.
slapi_mods_free()
Frees a Slapi_Mods structure.
slapi_mods_get_first_mod()
Initializes a Slapi_Mods iterator and returns the first LDAPMod.
slapi_mods_get_first_smod()
Initializes a Slapi_Mods iterator and returns the first mod wrapped in a Slapi_Mods structure.
slapi_mods_get_ldapmods_byref()
Gets a reference to the array of LDAPMod in a Slapi_Mods structure.
slapi_mods_get_ldapmods_passout()
Retrieves the array of LDAPMod contained in a Slapi_Mods structure.
slapi_mods_get_next_mod()
Increments the Slapi_Mods iterator and returns the next LDAPMod.
slapi_mods_get_next_smod()
Increments the Slapi_Mods iterator and returns the next mod wrapped in a Slapi_Mods.
slapi_mods_get_num_mods()
Gets the number of mods in a Slapi_Mods structure.
slapi_mods_init()
Initializes a Slapi_Mods.
slapi_mods_init_byref()
Initializes a Slapi_Mods that is a wrapper for an existing array of LDAPMod.
slapi_mods_init_passin()
Initializes a Slapi_Mods structure from an array of LDAPMod.
slapi_mods_insert_after()
Inserts an LDAPMod into a Slapi_Mods structure after the current iterator position.
slapi_mods_insert_at()
Inserts an LDAPMod anywhere in a Slapi_Mods.
slapi_mods_insert_before()
Inserts an LDAPMod into a Slapi_Mods structure before the current iterator position.
slapi_mods_insert_smod_at()
Inserts an smod anywhere in a Slapi_Mods structure.
slapi_mods_insert_smod_before()
Inserts an smod before a Slapi_Mods structure.
slapi_mods_iterator_backbone()
Decrements the Slapi_Mods current iterator position.
slapi_mods_new()
Allocates a new uninitialized Slapi_Mods structure.
slapi_mods_remove()
Removes the mod at the current Slapi_Mods iterator position.

slapi_entry2mods()

Creates an array of LDAPMod from a Slapi_Entry.

Syntax 

#include "slapi-plugin.h"

int slapi_entry2mods(const Slapi_Entry *e,

  char **dn, LDAPMod ***attrs);

Parameters

This function takes the following parameters: 

e
Pointer to a Slapi_Entry.
 
dn
Address of a char* that will be set on return to the entry DN.
 
attrs
Address of an array of LDAPMod that will be set on return to a copy of the entry attributes.

Returns

This function returns one of the following values:

Description

This function creates an array of LDAPMod of type LDAP_MOD_ADD from a Slapi_Entry.

See Also 

slapi_mods2entry()

slapi_mod_add_value()

Adds a value to a Slapi_Mod structure.

Syntax 

#include "slapi-plugin.h"

void slapi_mod_add_value(Slapi_Mod *smod, const struct berval 
*val);

Parameters

This function takes the following parameters: 

smod
Pointer to an initialized Slapi_Mod.
 
val
Pointer to a berval representing the attribute value.

Description

Adds a copy of a given attribute to the Slapi_Mod.

slapi_mod_done()

Frees the internals of Slapi_Mod structure.

Syntax 

#include "slapi-plugin.h"

void slapi_mod_done(Slapi_Mod *mod);

Parameters

This function takes the following parameter: 

mod
Pointer to a Slapi_Mod.

Description

This function frees the internals of a Slapi_Mod, leaving it in the uninitialized state.

Memory Concerns

Use this function on a stack-allocated Slapi_Mod when you have finished with it or want to reuse it.

See Also 

slapi_mod_init()
 
slapi_mod_init_byval()
 
slapi_mod_init_byref()
 
slapi_mod_init_passin()

slapi_mod_dump()

Dumps the contents of an LDAPMod to the server log.

Syntax 

#include "slapi-plugin.h"

void slapi_mod_dump(LDAPMod *mod, int n);

Parameters

This function takes the following parameters: 

mod
Pointer to an LDAPMod.
 
n
Numeric label that will be included in the log.

Description

This function uses the LDAP_DEBUG_ANY log level to dump the contents of an LDAPMod to the server log for debugging.

slapi_mod_free()

Frees a Slapi_Mod structure.

Syntax 

#include "slapi-plugin.h"

void slapi_mod_free(Slapi_Mod **smod);

Parameters

This function takes the following parameter: 

smod
Pointer to an initialized Slapi_Mod.

Description

This function frees a Slapi_Mod structure that was allocated by slapi_mod_new().

See Also 

slapi_mod_new()

slapi_mod_get_first_value()

Initializes a Slapi_Mod iterator and returns the first attribute value.

Syntax 

#include "slapi-plugin.h"

struct berval *slapi_mod_get_first_value(Slapi_Mod *smod);

Parameters

This function takes the following parameter: 

smod
Pointer to an initialized Slapi_Mod.

Returns

This function returns a pointer to the first attribute value in the Slapi_Mod or NULL if no values exist.

Description

Use this function with slapi_mod_get_next_value() to iterate through the attribute values in a Slapi_Mod structure.

See Also 

slapi_mod_get_next_value()

slapi_mod_get_ldapmod_byref()

Gets a reference to the LDAPMod in a Slapi_Mod structure.

Syntax 

#include "slapi-plugin.h"

const LDAPMod *slapi_mod_get_ldapmod_byref(const Slapi_Mod *smod);

Parameters

This function takes the following parameter: 

smod
Pointer to an initialized Slapi_Mod.

Returns

This function returns a pointer to a read-only LDAPMod owned by the Slapi_Mod.

Description

Use this function to get direct access to the LDAPMod contained in a Slapi_Mod.

Memory Concerns

Responsibility for the LDAPMod remains with the Slapi_Mod.

See Also 

slapi_mod_get_ldapmod_passout()

slapi_mod_get_ldapmod_passout()

Retrieves the LDAPMod contained in a Slapi_Mod structure.

Syntax 

#include "slapi-plugin.h"

LDAPMod *slapi_mod_get_ldapmod_passout(Slapi_Mod *smod);

Parameters

This function takes the following parameter: 

smod
Pointer to an initialized Slapi_Mod.

Returns

This function returns a pointer to an LDAPMod owned by the caller.

Description

Use this function to get the LDAPMod out of a Slapi_Mod.

Memory Concerns

Responsibility for the LDAPMod transfers to the caller. The Slapi_Mod is left in the uninitialized state.

See Also 

slapi_mod_get_ldapmod_byref()

slapi_mod_get_next_value()

Increments the Slapi_Mod iterator and return the next attribute value.

Syntax 

#include "slapi-plugin.h"

struct berval *slapi_mod_get_next_value(Slapi_Mod *smod);

Parameters

This function takes the following parameter: 

smod
Pointer to an initialized Slapi_Mod.

Returns

This function returns a pointer to the next attribute value in the Slapi_Mod or NULL if there are no more.

Description

Use this function with slapi_mods_get_first_mod() to iterate through the attribute values in a Slapi_Mod.

See Also 

slapi_mods_get_first_mod()

slapi_mod_get_num_values()

Gets the number of values in a Slapi_Mod structure.

Syntax 

#include "slapi-plugin.h"

int slapi_mod_get_num_values(const Slapi_Mod *smod);

Parameters

This function takes the following parameter: 

smod
Pointer to an initialized Slapi_Mod.

Returns

This function returns the number of attribute values in the Slapi_Mod.

slapi_mod_get_operation()

Gets the operation type of Slapi_Mod structure.

Syntax 

#include "slapi-plugin.h"

int slapi_mod_get_operation(const Slapi_Mod *smod);

Parameters

This function takes the following parameter: 

smod
Pointer to an initialized Slapi_Mod.

Returns

This function returns one of LDAP_MOD_ADD, LDAP_MOD_DELETE, or LDAP_MOD_REPLACE, combined using the bitwise or operator with LDAP_MOD_BYVALUES.

See Also 

slapi_mod_set_operation()

slapi_mod_get_type()

Gets the attribute type of a Slapi_Mod structure.

Syntax 

#include "slapi-plugin.h"

const char *slapi_mod_get_type(const Slapi_Mod *smod);

Parameters

This function takes the following parameter: 

smod
Pointer to an initialized Slapi_Mod.

Returns

This function returns a read-only pointer to the attribute type in the Slapi_Mod.

Description

Gets the LDAP attribute type of a Slapi_Mod.

See Also 

slapi_mod_set_type()

slapi_mod_init()

Initializes a Slapi_Mod structure.

Syntax 

#include "slapi-plugin.h"

void slapi_mod_init(Slapi_Mod *smod, int initCount);

Parameters

This function takes the following parameters: 

smod
Pointer to an uninitialized Slapi_Mod.
 
initCount
Suggested number of attribute values for which to make room. Minimum value is 0.

Description

This function initializes a Slapi_Mod so that it is empty but initially has room for the given number of attribute values.

Memory Concerns

If you are unsure of the room you will need, you may use an initCount of 0. The Slapi_Mod expands as necessary.

See Also 

slapi_mod_done()
 
slapi_mod_init_byval()
 
slapi_mod_init_byref()
 
slapi_mod_init_passin()

slapi_mod_init_byref()

Initializes a Slapi_Mod structure that is a wrapper for an existing LDAPMod.

Syntax 

#include "slapi-plugin.h"

void slapi_mod_init_byref(Slapi_Mod *smod, LDAPMod *mod);

Parameters

This function takes the following parameters: 

smod
Pointer to an uninitialized Slapi_Mod.
 
mod
Pointer to an LDAPMod.

Description

This function initializes a Slapi_Mod containing a reference to an LDAPMod. Use this function when you have an LDAPMod and would like the convenience of the Slapi_Mod functions to access it.

See Also 

slapi_mod_done()
 
slapi_mod_init()
 
slapi_mod_init_byval()
 
slapi_mod_init_passin()

slapi_mod_init_byval()

Initializes a Slapi_Mod structure with a copy of an LDAPMod.

Syntax 

#include "slapi-plugin.h"

void slapi_mod_init_byval(Slapi_Mod *smod, const LDAPMod *mod);

Parameters

This function takes the following parameters: 

smod
Pointer to an uninitialized Slapi_Mod.
 
mod
Pointer to an LDAPMod.

See Also 

slapi_mod_done()
 
slapi_mod_init()
 
slapi_mod_init_byref()
 
slapi_mod_init_byval()

slapi_mod_init_passin()

Initializes a Slapi_Mod from an LDAPMod.

Syntax 

#include "slapi-plugin.h"

void slapi_mod_init_passin(Slapi_Mod *smod, LDAPMod *mod);

Parameters

This function takes the following parameters: 

smod
Pointer to an uninitialized Slapi_Mod.
 
mod
Pointer to an LDAPMod.

Description

This function initializes a Slapi_Mod by passing in an LDAPMod. Use this function to convert an LDAPMod to a Slapi_Mod.

Memory Concerns

Responsibility for the LDAPMod is transferred to the Slapi_Mod. The LDAPMod is destroyed when the Slapi_Mod is destroyed.

See Also 

slapi_mod_done()
 
slapi_mod_init()
 
slapi_mod_init_byval()
 
slapi_mod_init_byref()

slapi_mod_isvalid()

Determines whether a Slapi_Mod structure is valid.

Syntax 

#include "slapi-plugin.h"

int slapi_mod_isvalid(const Slapi_Mod *mod);

Parameters

This function takes the following parameter: 

smod
Pointer to a Slapi_Mod.

Returns

This function returns one of the following values:

Description

Use this function to verify that the contents of Slapi_Mod are valid. It is considered valid if the operation type is one of LDAP_MOD_ADD, LDAP_MOD_DELETE, or LDAP_MOD_REPLACE, combined using the bitwise or operator with LDAP_MOD_BYVALUES; the attribute type is not NULL; and there is at least one attribute value for add and replace operations.

slapi_mod_new()

Allocates a new Slapi_Mod structure.

Syntax 

#include "slapi-plugin.h"

Slapi_Mod* slapi_mod_new( void );

Parameters

This function takes no parameters.

Returns

This function returns a pointer to an allocated, uninitialized Slapi_Mod.

Description

This function allocates a new uninitialized Slapi_Mod. Use this function when you need to a Slapi_Mod allocated from the heap, rather than from the stack.

See Also 

slapi_mod_free()

slapi_mod_remove_value()

Removes the value at the current Slapi_Mod iterator position.

Syntax 

#include "slapi-plugin.h"

void slapi_mod_remove_value(Slapi_Mod *smod);

Parameters

This function takes the following parameter: 

smod
Pointer to an initialized Slapi_Mod.

See Also 

slapi_mod_get_first_value()
 
slapi_mod_get_next_value()

slapi_mod_set_operation()

Sets the operation type of a Slapi_Mod structure.

Syntax 

#include "slapi-plugin.h"

void slapi_mod_set_operation(Slapi_Mod *smod, int op);

Parameters

This function takes the following parameters: 

smod
Pointer to an initialized Slapi_Mod.
 
op
One of LDAP_MOD_ADD, LDAP_MOD_DELETE, or LDAP_MOD_REPLACE, combined using the bitwise or operator with LDAP_MOD_BYVALUES.

See Also 

slapi_mod_get_operation()

slapi_mod_set_type()

Sets the attribute type of a Slapi_Mod.

Syntax 

#include "slapi-plugin.h"

void slapi_mod_set_type(Slapi_Mod *smod, const char *type);

Parameters

This function takes the following parameters: 

smod
Pointer to an initialized Slapi_Mod.
 
type
An attribute type.

Description

Sets the attribute type of the Slapi_Mod to a copy of the given value.

See Also 

slapi_mod_get_type()

slapi_mods2entry()

Creates a Slapi_Entry from an array of LDAPMod.

Syntax 

#include "slapi-plugin.h"

int slapi_mods2entry(Slapi_Entry **e, const char *dn, 

  LDAPMod **attrs);

Parameters

This function takes the following parameters: 

e
Address of a pointer that will be set on return to the created entry.
 
dn
The LDAP DN of the entry.
 
attrs
An array of LDAPMOD of type LDAP_MOD_ADD representing the entry attributes.

Returns

This function returns one of the following values:

Description

This function creates a Slapi_Entry from a copy of an array of LDAPMod of type LDAP_MODD_ADD.

See Also 

slapi_entry2mods()

slapi_mods_add()

Appends a new mod with a single attribute value to Slapi_Mods structure.

Syntax 

#include "slapi-plugin.h"

void slapi_mods_add( Slapi_Mods *smods, int modtype,

  const char *type, unsigned long len, const char *val);

Parameters

This function takes the following parameters: 

smods
Pointer to an initialized Slapi_Mods.
 
modtype
One of LDAP_MOD_ADD, LDAP_MOD_DELETE, or LDAP_MOD_REPLACE.
 
type
The LDAP attribute type.
 
len
The length in bytes of the attribute value.
 
val
The attribute value.

Description

This function appends a new mod with a single attribute value to a Slapi_Mods. The mod is constructed from copies of the values of modtype, type, len, and val.

Memory Concerns

This function must not be used on Slapi_Mods initialized with slapi_mods_init_byref().

See Also 

slapi_mods_add_ldapmod()
 
slapi_mods_add_modbvps()
 
slapi_mods_add_mod_values()
 
slapi_mods_add_string()

slapi_mods_add_ldapmod()

Appends an LDAPMod to a Slapi_Mods structure.

Syntax 

#include "slapi-plugin.h"

void slapi_mods_add_ldapmod(Slapi_Mods *smods, LDAPMod *mod);

Parameters

This function takes the following parameters: 

smods
Pointer to an initialized Slapi_Mods.
 
mod
Pointer to a the LDAPMod to be appended.

Description

Appends an LDAPMod to a Slapi_Mods.

Memory Concerns

Responsibility for the LDAPMod is transferred to the Slapi_Mods. This function must not be used on a Slapi_Mods initialized with slapi_mods_init_byref().

See Also 

slapi_mods_add()
 
slapi_mods_add_modbvps()
 
slapi_mods_add_mod_values()
 
slapi_mods_add_string()

slapi_mods_add_mod_values()

Appends a new mod to a Slapi_Mods structure with attribute values provided as an array of Slapi_Value.

Syntax 

#include "slapi-plugin.h"

void slapi_mods_add_mod_values( Slapi_Mods *smods, int modtype,

  const char *type, Slapi_Value **va );;

Parameters

This function takes the following parameters: 

smods
Pointer to an initialized Slapi_Mods.
 
modtype
One of LDAP_MOD_ADD, LDAP_MOD_DELETE, or LDAP_MOD_REPLACE.
 
type
The LDAP attribute type.
 
va
A null-terminated array of Slapi_Value representing the attribute values.

Description

This function appends a new mod to a Slapi_Mods. The mod is constructed from copies of the values of modtype, type and va. Use this function when you have the attribute values to hand as an array of Slapi_Value.

Memory Concerns

This function must not be used on a Slapi_Mods initialized with slapi_mods_init_byref().

See Also 

slapi_mods_add()
 
slapi_mods_add_smod()
 
slapi_mods_add_ldapmod()
 
slapi_mods_add_modbvps()
 
slapi_mods_add_string()

slapi_mods_add_smod()

Appends a new smod to a Slapi_Mods structure. The mod passed in is not copied or duplicated, but the reference is used directly.

Syntax 

#include "slapi-plugin.h"

void slapi_mods_add_smod( Slapi_Mods *smods, Slapi_Mod *smod );

Parameters

This function takes the following parameters: 

smods
Pointer to an initialized Slapi_Mods.
 
smod
Pointer to an initialized Slapi_Mod.

Description

This function appends a new smod to a Slapi_Mods. The function slapi_mods_get_num_mods() gives the number of mods in the Slapi_Mods structure.

Memory Concerns

This function must not be used on a Slapi_Mods initialized with slapi_mods_init_byref().

See Also 

slapi_mods_insert_at()
 
slapi_mods_add()
 
slapi_mods_add_mod_values()
 
slapi_mods_add_ldapmod()
 
slapi_mods_add_modbvps()
 
slapi_mods_add_string()

slapi_mods_add_modbvps()

Appends a new mod to a Slapi_Mods structure with attribute values provided as an array of berval.

Syntax 

#include "slapi-plugin.h"

void slapi_mods_add_modbvps( Slapi_Mods *smods, int modtype,

  const char *type, struct berval **bvps );

Parameters

This function takes the following parameters: 

smods
Pointer to an initialized Slapi_Mods.
 
modtype
One of LDAP_MOD_ADD, LDAP_MOD_DELETE, or LDAP_MOD_REPLACE.
 
type
The LDAP attribute type.
 
bvps
A null-terminated array of berval representing the attribute values.

Description

This function appends a new mod to Slapi_Mods. The mod is constructed from copies of the values of modtype, type, and bvps. Use this function when you have the attribute values to hand as an array of berval.

Memory Concerns

This function must not be used on a Slapi_Mods initialized with slapi_mods_init_byref().

See Also 

slapi_mods_add()
 
slapi_mods_add_ldapmod()
 
slapi_mods_add_mod_values()
 
slapi_mods_add_string()

slapi_mods_add_string()

Appends a new mod to Slapi_Mods structure with a single attribute value provided as a string.

Syntax 

#include "slapi-plugin.h"

void slapi_mods_add_string( Slapi_Mods *smods, int modtype,

  const char *type, const char *val);

Parameters

This function takes the following parameters: 

smods
Pointer to an initialized Slapi_Mods.
 
modtype
One of LDAP_MOD_ADD, LDAP_MOD_DELETE, or LDAP_MOD_REPLACE.
 
type
The LDAP attribute type.
 
val
The attribute value represented as a null-terminated string.

Description

This function appends a new mod with a single string attribute value to a Slapi_Mods. The mod is constructed from copies of the values of modtype, type, and val.

Memory Concerns

This function must not be used on a Slapi_Mods initialized with slapi_mods_init_byref().

See Also 

slapi_mods_add()
 
slapi_mods_add_ldapmod()
 
slapi_mods_add_modbvps()
 
slapi_mods_add_mod_values()

slapi_mods_done()

Frees internals of a Slapi_Mods structure.

Syntax 

#include "slapi-plugin.h"

void slapi_mods_done(Slapi_Mods *smods);

Parameters

This function takes the following parameter: 

smod
Pointer to a Slapi_Mods.

Description

This function frees the internals of a Slapi_Mods, leaving it in the uninitialized state. Use this function on a stack-allocated Slapi_Mods when you are finished with it, or when you wish to reuse it.

See Also 

slapi_mods_init()
 
slapi_mods_init_byref()
 
slapi_mods_init_passin()

slapi_mods_dump()

Dumps the contents of a Slapi_Mods structure to the server log.

Syntax 

#include "slapi-plugin.h"

void slapi_mods_dump(const Slapi_Mods *smods, const char *text);

Parameters

This function takes the following parameters: 

smods
Pointer to a Slapi_Mods.
 
text
Descriptive text that will be included in the log, preceding the Slapi_Mods content.

Description

This function uses the LDAP_DEBUG_ANY log level to dump the contents of a Slapi_Mods to the server log for debugging.

See Also 

slapi_mods_dump()

slapi_mods_free()

Frees a Slapi_Mods structure.

Syntax 

#include "slapi-plugin.h"

void slapi_mods_free(Slapi_Mods **smods);

Parameters

This function takes the following parameter: 

smods
Pointer to an allocated Slapi_Mods.

Description

This function frees a Slapi_Mods that was allocated by slapi_mods_new().

See Also 

slapi_mods_new()

slapi_mods_get_first_mod()

Initializes a Slapi_Mods iterator and returns the first LDAPMod.

Syntax 

#include "slapi-plugin.h"

LDAPMod *slapi_mods_get_first_mod(Slapi_Mods *smods);

Parameters

This function takes the following parameter: 

smods
Pointer to an initialized Slapi_Mods.

Returns

This function returns one of the following values:

slapi_mods_get_first_smod()

Initializes a Slapi_Mods iterator and returns the first mod wrapped in a Slapi_Mods structure.

Syntax 

#include "slapi-plugin.h"

Slapi_Mod *slapi_mods_get_first_smod(Slapi_Mods *smods,

  Slapi_Mod *smod);

Parameters

This function takes the following parameters: 

smods
A pointer to a an initialized Slapi_Mods.
 
smod
Pointer to a Slapi_Mods that will be used to hold the mod.

Returns

This function returns one of the following values:

Description

Use this function in conjunction with slapi_mods_get_next_smod() to iterate through the mods in a Slapi_Mods using a Slapi_Mods wrapper.

Memory Concerns

Only one thread may be iterating through a particular Slapi_Mods at any given time.

See Also 

slapi_mods_get_next_mod()

slapi_mods_get_ldapmods_byref()

Gets a reference to the array of LDAPMod in a Slapi_Mods structure.

Syntax 

#include "slapi-plugin.h"

LDAPMod **slapi_mods_get_ldapmods_byref(Slapi_Mods *smods);

Parameters

This function takes the following parameter: 

smods
Pointer to an initialized Slapi_Mods.

Returns

This function returns a null-terminated array of LDAPMod owned by the Slapi_Mods.

Description

Use this function to get direct access to the array of LDAPMod contained in a Slapi_Mods.

Memory Concerns

Responsibility for the array remains with the Slapi_Mods.

See Also 

slapi_mods_get_ldapmods_passout()

slapi_mods_get_ldapmods_passout()

Retrieves the array of LDAPMod contained in a Slapi_Mods structure.

Syntax 

#include "slapi-plugin.h"

LDAPMod **slapi_mods_get_ldapmods_passout(Slapi_Mods *smods);

Parameters

This function takes the following parameter: 

smod
Pointer to an initialized Slapi_Mods.

Returns

This function returns a null-terminated array LDAPMod owned by the caller.

Description

Gets the array of LDAPMod out of a Slapi_Mods. Responsibility for the array transfers to the caller. The Slapi_Mods is left in the uninitialized state.

See Also 

slapi_mods_get_ldapmods_byref()

slapi_mods_get_next_mod()

Increments the Slapi_Mods iterator and returns the next LDAPMod.

Syntax 

#include "slapi-plugin.h"

LDAPMod *slapi_mods_get_next_mod(Slapi_Mods *smods);

Parameters

This function takes the following parameter: 

smod
A pointer to an initialized Slapi_Mods.

Returns

This function returns either a pointer to the next LDAPMod or NULL if there are no more.

Description

Use this function in conjunction with slapi_mods_get_first_mod() to iterate through the mods in a Slapi_Mods. This will return an LDAPMod each time until the end.

Memory Concerns

Only one thread may be iterating through a particular Slapi_Mods at any given time.

See Also 

slapi_mods_get_first_mod()

slapi_mods_get_next_smod()

Increments the Slapi_Mods iterator and returns the next mod wrapped in a Slapi_Mods.

Syntax 

#include "slapi-plugin.h"

Slapi_Mod *slapi_mods_get_next_smod(Slapi_Mods *smods,

  Slapi_Mod *smod);

Parameters

This function takes the following parameters: 

smods
Pointer to an initialized Slapi_Mods.
 
smod
Pointer to a Slapi_Mods that will be used to hold the mod.

Returns

This function returns a pointer to the Slapi_Mod, wrapping the next mod, or NULL if there are no more mods.

Description

Use this function in conjunction with slapi_mods_get_first_smod() to iterate through the mods in a Slapi_Mods using a Slapi_Mods wrapper.

Memory Concerns

Only one thread may be iterating through a particular Slapi_Mods at any given time.

See Also 

slapi_mods_get_first_smod()

slapi_mods_get_num_mods()

Gets the number of mods in a Slapi_Mods structure.

Syntax 

#include "slapi-plugin.h"

int slapi_mods_get_num_mods(const Slapi_Mods *smods);

Parameters

This function takes the following parameter: 

smods
Pointer to an initialized Slapi_Mods.

Returns

This function returns the number of mods in Slapi_Mods.

slapi_mods_init()

Initializes a Slapi_Mods.

Syntax 

#include "slapi-plugin.h"

void slapi_mods_init(Slapi_Mods *smods, int initCount);

Parameters

This function takes the following parameters: 

smods
Pointer to an initialized Slapi_Mods.
 
initCount
Suggested number of mods for which to make room. The minimum value is 0.

Description

Initializes a Slapi_Mods so that it is empty but initially has room for the given number of mods.

Memory Concerns

If you are unsure of how much room you will need, you may use an initCount of 0. The Slapi_Mods expands as necessary.

See Also 

slapi_mods_done()

slapi_mods_init_byref()

Initializes a Slapi_Mods that is a wrapper for an existing array of LDAPMod.

Syntax 

#include "slapi-plugin.h"

void slapi_mods_init_byref(Slapi_Mods *smods, LDAPMod **mods);

Parameters

This function takes the following parameters: 

smods
Pointer to an uninitialized Slapi_Mods.
 
mods
A null-terminated array of LDAPMod.

Description

Initializes a Slapi_Mods containing a reference to an array of LDAPMod. This function provides the convenience of using Slapi_Mods functions to access LDAPMod array items.

Memory Concerns

The array is not destroyed when the Slapi_Mods is destroyed. You cannot insert new mods in a Slapi_Mods that has been initialized by reference.

See Also 

slapi_mods_done()

slapi_mods_init_passin()

Initializes a Slapi_Mods structure from an array of LDAPMod.

Syntax 

#include "slapi-plugin.h"

void slapi_mods_init_passin(Slapi_Mods *smods, LDAPMod **mods);

Parameters

This function takes the following parameters: 

smods
Pointer to an uninitialized Slapi_Mods.
 
mods
A null-terminated array of LDAPMod.

Description

This function initializes a Slapi_Mods by passing in an array of LDAPMod. This function converts an array of LDAPMod to a Slapi_Mods.

Memory Concerns

The responsibility for the array and its elements is transferred to the Slapi_Mods. The array and its elements are destroyed when the Slapi_Mods is destroyed.

See Also 

slapi_mods_done()

slapi_mods_insert_after()

Inserts an LDAPMod into a Slapi_Mods structure after the current iterator position.

Syntax 

#include "slapi-plugin.h"

void slapi_mods_insert_after(Slapi_Mods *smods, LDAPMod *mod);

Parameters

This function takes the following parameters: 

smods
Pointer to an initialized Slapi_Mods with a valid iterator position.
 
mod
Pointer to the LDAPMod to be inserted.

Description

This function inserts an LDAPMod in a Slapi_Mods immediately after the current position of the Slapi_Mods iterator. The iterator position is unchanged.

Memory Concerns

Responsibility for the LDAPMod is transferred to the Slapi_Mods. This function must not be used on a Slapi_Mods initialized with slapi_mods_init_byref().

See Also 

slapi_mods_get_first_mod()
 
slapi_mods_get_next_mod()
 
slapi_mods_get_first_smod()
 
slapi_mods_get_next_smod()

slapi_mods_insert_at()

Inserts an smod at position pos in a Slapi_Mods structure.

Syntax 

#include "slapi-plugin.h"

void slapi_mods_insert_at(Slapi_Mods *smods, LDAPMod *mod, int 
pos);

Parameters

This function takes the following parameters: 

smods
Pointer to an initialized Slapi_Mods.
 
mod
Pointer to the LDAPMod to be inserted.
 
pos
Position at which to insert the new mod. Minimum value is 0. Maximum value is the current number of mods.

Description

This function inserts an LDAPMod at a given position pos in Slapi_Mods. Position 0 (zero) refers to the first mod. A position equal to the current number of mods (determined by slapi_mods_get_num_mods()) causes an append mods at and above the specified position are moved up by one, and the given position refers to the newly inserted mod. Shift everything down to make room to insert the new mod.

Memory Concerns

Responsibility for the LDAPMod is transferred to the Slapi_Mods. This function must not be used on a Slapi_Mods initialized with slapi_mods_init_byref().

See Also 

slapi_mods_insert_at()

slapi_mods_add_ldapmod() adds to the end of all mods.

slapi_mods_insert_before()

Inserts an LDAPMod into a Slapi_Mods structure before the current iterator position.

Syntax 

#include "slapi-plugin.h"

void slapi_mods_insert_before(Slapi_Mods *smods, LDAPMod *mod);

Parameters

This function takes the following parameters: 

smods
Pointer to an initialized Slapi_Mods with valid iterator position.
 
mod
Pointer to the LDAPMod to be inserted.

Description

Inserts an LDAPMod into a Slapi_Mods immediately before the current position of the Slapi_Mods iterator. The iterator position is unchanged.

Memory Concerns

The responsibility for the LDAPMod is transferred to the Slapi_Mods. This function must not be used on a Slapi_Mods initialized with slapi_mods_init_byref().

See Also 

slapi_mods_get_first_mod()
 
slapi_mods_get_next_mod()

slapi_mods_insert_smod_at()

Inserts an smod at position pos in a Slapi_Mods structure.

Syntax 

#include "slapi-plugin.h"

void slapi_mods_insert_smod_at(Slapi_Mods *smods, Slapi_Mod *smod,

   int pos);

Parameters

This function takes the following parameters: 

smods
Pointer to an initialized Slapi_Mods.
 
smod
Pointer to the LDAPMod to be inserted.
 
pos
Position at which to insert the new mod. Minimum value is 0. Maximum value is the current number of mods.

Description

This function inserts an smod at a given position pos in Slapi_Mods. Position 0 (zero) refers to the first smod. A position equal to the current number of smods (determined by slapi_mods_get_num_mods() causes an append smod at and above the specified position are moved up by one, and the given position refers to the newly inserted smod. Shift everything down to make room to insert the new mod.

Memory Concerns

Responsibility for the smod is transferred to the Slapi_Mods.

See Also 

slapi_mods_insert_at()

slapi_mods_add_ldapmod() adds to the end of all mods.

slapi_mods_insert_smod_before()

Inserts an smod before a Slapi_Mods structure.

Syntax 

#include "slapi-plugin.h"

void slapi_mods_insert_smod_before(Slapi_Mods *smods, 

   Slapi_Mod *smod);

Parameters

This function takes the following parameters: 

smods
Pointer to an initialized Slapi_Mods.
 
smod
Pointer to the Slapi_Mod to be inserted.

Description

This function inserts an smod immediately before the current position of the Slapi_Mods iterator. The iterator position is unchanged.

Memory Concerns

The Slapi_Mod argument smod is not duplicated or copied, but the reference of the Slapi_Mod (smods) is passed into the Slapi_Mods (smods) structure.The responsibility for the smod is transferred to the Slapi_Mods.

See Also 

slapi_mods_insert_before()
 
slapi_mods_insert_smod_at()

slapi_mods_iterator_backbone()

Decrements the Slapi_Mods current iterator position.

Syntax 

#include "slapi-plugin.h"

void slapi_mods_iterator_backone(Slapi_Mods *smods);

Parameters

This function takes the following parameter: 

smods
Pointer to an initialized Slapi_Mods.

Description

This function moves the iterator back one position.

See Also 

slapi_mods_get_first_mod()
 
slapi_mods_get_next_mod()
 
slapi_mods_get_first_smod()
 
slapi_mods_get_next_smod()

slapi_mods_new()

Allocates a new uninitialized Slapi_Mods structure.

Syntax 

#include "slapi-plugin.h"

Slapi_Mods* slapi_mods_new( void );

Parameters

This function takes no parameters.

Returns

This function returns a pointer to an allocated uninitialized Slapi_Mods.

Description

This function allocates a new initialized Slapi_Mods.

Memory Concerns

Use this function when you need a Slapi_Mods allocated from the heap rather than from the stack.

See Also 

slapi_mods_free()

slapi_mods_remove()

Removes the mod at the current Slapi_Mods iterator position.

Syntax 

#include "slapi-plugin.h"

void slapi_mods_remove(Slapi_Mods *smods);

Parameters

This function takes the following parameter: 

smods
Pointer to an initialized Slapi_Mods.

Description

This function removes the mod at the current iterator position.

See Also 

slapi_mods_get_first_mod()
 
slapi_mods_get_next_mod()
 
slapi_mods_get_first_smod()
 
slapi_mods_get_next_smod()

Functions for Monitoring Operations

This section contains reference information on operation routines.

Table 15-20 Operation Routines
Function
Description
slapi_op_abandoned()
Determines if the client has abandoned the current operation.
slapi_op_get_type()
Gets the type of a Slapi_Operation.

slapi_op_abandoned()

Determines whether the client has abandoned the current operation (the operation that passes in the parameter block).

Syntax 

#include "slapi-plugin.h"

int slapi_op_abandoned( Slapi_PBlock *pb );

Parameters

This function takes the following parameter: 

pb
Parameter block passed in from the current operation.

Description

This function allows you to verify if the operation associated to the pblock in the parameter has been abandoned. This function is useful to check periodically the operations status of long-running plug-ins.

Returns

This function returns one of the following values:

slapi_op_get_type()

Gets the type of a Slapi_Operation.

Syntax 

#include "slapi-plugin.h"

unsigned long slapi_op_get_type(Slapi_Operation * op);

Parameters

This function takes the following parameter: 

op
The operation of which you wish to get the type.

Description

This function returns the type of an operation. The Slapi_Operation structure can be extracted from a pblock structure using slapi_pblock_get() with the SLAPI_OPERATION parameter. For example: 

slapi_pblock_get (pb, SLAPI_OPERATION, &op);

Returns

This function returns one of the following operation types:

See Also 

slapi_pblock_get()

Functions for Managing Parameter Block

This section contains reference information on parameter block routines.

Table 15-21 Parameter Block Routines  
Function
Description
slapi_pblock_destroy()
Frees a pblock from memory.
slapi_pblock_get()
Gets the value from a pblock.
slapi_pblock_new()
Creates a new pblock.
slapi_pblock_set()
Sets the value of a pblock.

slapi_pblock_destroy()

Frees the specified parameter block from memory.

Syntax 

#include "slapi-plugin.h"

void slapi_pblock_destroy( Slapi_PBlock *pb );

Parameters

This function takes the following parameter: 

pb
Parameter block that you want to free.

Memory Concerns

The parameter block that you wish to free must have been created using slapi_pblock_new(). Use of this function with pblocks allocated on the stack (for example, Slapi_PBlock pb;) or using another memory allocator is not supported and may lead to memory errors and memory leaks. For example: 

Slapi_PBlock *pb = malloc(sizeof(Slapi_PBlock));

After calling this function, you should set the pblock pointer to NULL to avoid reusing freed memory in your function context, as in the following: 

slapi_pblock_destroy(pb);

pb =NULL;

If you reuse the pointer in this way, it makes it easier to identify a Segmentation Fault, rather than using some difficult method to detect memory leaks or other abnormal behavior.

It is safe to call this function with a NULL pointer. For example: 

Slapi_PBlock *pb = NULL;

slapi_pblock_destroy(pb);

This saves the trouble of checking for NULL before calling slapi_pblock_destroy().

See Also 

slapi_pblock_new()

slapi_pblock_get()

Gets the value of a name-value pair from a parameter block.

Syntax 

#include "slapi-plugin.h"

int slapi_pblock_get( Slapi_PBlock *pb, int arg, void *value );

Parameters

This function takes the following parameters: 

pb
Parameter block.
 
arg
ID of the name-value pair that you want to get. For a list of IDs that you can specify, see Chapter 16, "Parameter Block Reference."
 
value
Pointer to the value retrieved from the parameter block.

Returns

This function returns one of the following values:

Memory Concerns

The void *value argument should always be a pointer to the type of value you are retrieving: 

int connid = 0;

...

retval = slapi_pblock_get(pb, SLAPI_CONN_ID, &connid);

SLAPI_CONN_ID is an integer value, so you will pass in a pointer to/address of an integer to get the value. Similarly, for a char * value (a string), pass in a pointer to/address of the value. For example: 

char *binddn = NULL;

...

retval = slapi_pblock_get(pb, SLAPI_CONN_DN, &binddn);

With certain compilers on some platforms, you may have to cast the value to (void *).

We recommend that you set the value to 0 or NULL before calling slapi_pblock_get() to avoid reading from uninitialized memory, in case the call to slapi_pblock_get() fails.

In most instances, the caller should not free the returned value. The value will usually be freed internally or through the call to slapi_pblock_destroy(). The exception is if the value is explicitly set by the caller through slapi_pblock_set(). In this case, the caller is responsible for memory management. If the value is freed, it is strongly recommended that the free is followed by a call to slapi_pblock_set() with a value of NULL. For example: 

char *someparam = NULL;

...

someparam = slapi_ch_strdup(somestring);

slapi_pblock_set(pb, SOME_PARAM, someparam);

someparam = NULL; /* avoid dangling reference */

...

slapi_pblock_get(pb, SOME_PARAM, &someparam);

slapi_pblock_set(pb, SOME_PARAM, NULL); /* make sure no one else 
can reference this parameter */

slapi_ch_free_string(&someparam);

...

Some internal functions may change the value passed in, so it is recommended to use slapi_pblock_get() to retrieve the value again, rather than relying on a potential dangling pointer. This is shown in the example above, which sets someparam to NULL after setting it in the pblock.

See Also 

slapi_pblock_destroy()
 
slapi_pblock_set()

slapi_pblock_new()

Creates a new parameter block.

Syntax 

#include "slapi-plugin.h" 

Slapi_PBlock *slapi_pblock_new();

Returns

This function returns a pointer to the new parameter block.

Memory Concerns

The pblock pointer allocated with this function must always be freed by slapi_pblock_destroy(). The use of other memory deallocators (for example, free()) is not supported and may lead to crashes or memory leaks.

slapi_pblock_set()

Sets the value of a name-value pair in a parameter block.

Syntax 

#include "slapi-plugin.h"

int slapi_pblock_set( Slapi_PBlock *pb, int arg, void *value );

Parameters

This function takes the following parameters: 

pb
Parameter block.
 
arg
ID of the name-value pair that you want to set. For a list of IDs that you can specify, see Chapter 16, "Parameter Block Reference."
 
value
Pointer to the value that you want to set in the parameter block.

Returns

This function returns one of the following values:

Memory Concerns

The value to be passed in must always be a pointer, even for integer arguments. For example, if you wanted to do a search with the ManageDSAIT control: 

int managedsait = 1;

...

slapi_pblock_set(pb, SLAPI_MANAGEDSAIT, &managedsait);

A call similar to the following example will cause a crash: 

slapi_pblock_set(pb, SLAPI_MANAGEDSAIT, 1);

However, for values which are already pointers (char * strings, char **arrays, Slapi_Backend *, etc.), you can pass in the value directly. For example: 

char *target_dn = slapi_ch_strdup(some_dn);

slapi_pblock_set(pb, SLAPI_TARGET_DN, target_dn);

or 

slapi_pblock_set(pb, SLAPI_TARGET_DN, NULL);

With some compilers, you will have to cast the value argument to (void *). If the caller allocates the memory passed in, the caller is responsible for freeing that memory. Also, it is recommended to use slapi_pblock_get() to retrieve the value to free, rather than relying on a potentially dangling pointer. See the slapi_pblock_get() example for more details.

When setting parameters to register a plug-in, the plug-in type must always be set first, since many of the plug-in parameters depend on the type. For example, set the SLAPI_PLUGIN_TYPE to extended operation before setting the list of extended operation OIDs for the plug-in.

See Also 

slapi_pblock_get()

Functions for Handling Passwords

This section contains reference information on routines for handling passwords. The routines are listed in Table 15-22.

Table 15-22 Password Handling Routines  
Function
Description
slapi_pw_find_sv()
Determines whether a specified password matches one of the encrypted values of an attribute.
slapi_is_encoded()
Checks whether a value is encoded with any known algorithm.
slapi_encode()
Encodes a value with the specified algorithm.
slapi_add_pwd_control()
Sends back a password expired notification or password expiration warning.
slapi_pwpolicy_make_response_control()
Sends back information on the server password policy.

slapi_pw_find_sv()

Determines whether a specified password matches one of the encrypted values of an attribute. For example, you can call this function to determine if a given password matches a value in the userpassword attribute.

Syntax 

#include "slapi-plugin.h"

int slapi_pw_find_sv( Slapi_Value **vals, const Slapi_Value *v );

Parameters

This function takes the following parameters: 

vals
Pointer to the array of Slapi_Value structure pointers, containing the values of an attribute that stores passwords (for example, the userpassword attribute).
 
v
Pointer to the Slapi_Value structure containing the password that you wish to check; for example, you can get this value from the SLAPI_BIND_CREDENTIALS parameter in the parameter block and create the Slapi_Value using slapi_value_init_berval().

Returns

This function returns one of the following values:

Description

This function replaces the deprecated slapi_pw_find() function from previous Directory Server releases.

When the Directory Server stores the password for an entry in the userpassword attribute, it encodes the password using different schemes. Supported schemes are SSHA (default), SHA, CRYPT, and CLEAR.

Use this function to determine if a given password is one of the values of the userpassword attribute. This function determines which password scheme was used to store the password and uses the appropriate comparison function to compare a given value against the encoded values of the userpassword attribute.

See Also 

slapi_is_encoded()
 
slapi_encode()

slapi_is_encoded()

Checks whether the specified value is encoded with any known algorithm.

Syntax 

#include "slapi-plugin.h"

int slapi_is_encoded(char *value);

Parameters

This function takes the following parameter: 

value
The value, the encoding status of which needs to be determined.

Returns

This function returns one of the following values:

See Also 

slapi_pw_find_sv()
 
slapi_encode()

slapi_encode()

Encodes a value with the specified algorithm.

Syntax 

#include "slapi-plugin.h"

char* slapi_encode(char *value, char *alg);

Parameters

This function takes the following parameters: 

value
The value that needs to be encoded.
 
alg
The encoding algorithm. The following algorithms are supported in a a default Directory Server installation:
  • CRYPT
  • CLEAR
  • SSHA
  • SHA
If you pass NULL for the alg parameter, the scheme used is determined by the setting of the server's passwordStorageScheme value within the server configuration entry (cn=config). If no value is present, SSHA is the default.

Returns

This function returns one of the following values:

See Also 

slapi_pw_find_sv()
 
slapi_is_encoded()

slapi_add_pwd_control()

Sends back information about expired or expiring passwords.

Syntax 

#include "slapi-plugin.h"

int slapi_add_pwd_control ( Slapi_PBlock *pb, char *arg, long time )

Parameters

This function takes the following parameter: 

pb
Parameter block.
 
arg
Argument to the function.

Returns

This function returns one of the following values:

slapi_pwpolicy_make_response_control()

Sends back detailed information about password policies.

Syntax 

#include "slapi-plugin.h"

int slapi_pwpolicy_make_response_control (Slapi_PBlock *pb, int 
seconds, int logins, int error)

Parameters

This function takes the following parameter: 

pb
Parameter block.

Returns

This function returns any of the following values:

Description

stuff about this plug-in

Functions for Managing RDN

This section contains reference information on RDN routines.

Table 15-23 RDN Routines  
Function
Description
slapi_rdn_add()
Adds a new RDN to an existing RDN structure.
slapi_rdn_compare()
Compares two RDNs.
slapi_rdn_contains()
Checks if a Slapi_RDN structure holds any RDN matching a give type/value pair.
slapi_rdn_contains_attr()
Checks if a Slapi_RDN structure contains any RDN matching a given type.
slapi_rdn_done()
Clears a Slapi_RDN structure.
slapi_rdn_free()
Frees a Slapi_RDN structure.
slapi_rdn_get_first()
Gets the type/value pair of the first RDN.
slapi_rdn_get_index()
Gets the index of the RDN.
slapi_rdn_get_index_attr()
Gets the position and the attribute value of the first RDN.
slapi_rdn_get_next()
Gets the RDN type/value pair from the RDN.
slapi_rdn_get_num_components()
Gets the number of RDN type/value pairs.
slapi_rdn_get_rdn()
Gets the RDN from a Slapi_RDN structure.
slapi_rdn_get_nrdn()
Not implemented; do not use. Gets the normalized RDN from a Slapi_RDN structure.
slapi_rdn_init()
Gets the next RDN from a Slapi_RDN structure
slapi_rdn_init()
Initializes a Slapi_RDN structure.
slapi_rdn_init_dn()
Initializes a Slapi_RDN structure with an RDN value taken from a given DN.
slapi_rdn_init_rdn()
Initializes a Slapi_RDN structure with an RDN value.
slapi_rdn_init_sdn()
Initializes a Slapi_RDN structure with an RDN value taken from the DN contained in a given Slapi_RDN structure.
slapi_rdn_isempty()
Checks if an RDN value is stored in a Slapi_RDN structure.
slapi_rdn_new()
Allocates a new Slapi_RDN structure.
slapi_rdn_new_dn()
Creates a new Slapi_RDN structure.
slapi_rdn_new_rdn()
Creates a new Slapi_RDN structure and sets an RDN value.
slapi_rdn_new_sdn()
Creates a new Slapi_RDN structure and sets an RDN value taken from the DN contained in a given Slapi_RDN structure.
slapi_rdn_remove()
Removes an RDN type/value pair.
slapi_rdn_remove_attr()
Removes an RDN type/value pair from a Slapi_RDN structure.
slapi_rdn_remove_index()
Removes an RDN type/value pair from a Slapi_RDN structure.
slapi_rdn_set_dn()
Sets an RDN value in a Slapi_RDN structure.
slapi_rdn_set_rdn()
Sets an RDN in a Slapi_RDN structure.
slapi_rdn_set_sdn()
Sets an RDN value in a Slapi_RDN structure.
slapi_sdn_add_rdn()
Adds an RDN to a DN.

slapi_rdn_add()

Adds a new RDN to an existing Slapi_RDN structure.

Syntax 

#include "slapi-plugin.h"

int slapi_rdn_add(Slapi_RDN *rdn, const char *type,

  const char *value);

Parameters

This function takes the following parameters: 

rdn
The target Slapi_RDN structure.
 
type
The type (cn, o, ou, etc.) of the RDN to be added. This parameter cannot be NULL. 
value
The value of the RDN to be added. This parameter cannot be NULL.

Returns

This function always returns 1.

Description

This function adds a new type/value pair to an existing RDN or sets the type/value pair as the new RDN if rdn is empty. This function resets the FLAG_RDNS flags, which means that the RDN array within the Slapi_RDN structure is no longer current with the new RDN.

See Also 

slapi_rdn_get_num_components()

slapi_rdn_compare()

Compares two RDNs.

Syntax 

#include "slapi-plugin.h"

int slapi_rdn_compare(Slapi_RDN *rdn1, Slapi_RDN *rdn2);

Parameters

This function takes the following parameters: 

rdn1
The first RDN to compare.
 
rdn2
The second RDN to compare.

Returns

This function returns one of the following values:

Description

This function compares rdn1 and rdn2. For rdn1 and rdn2 to be considered equal RDNs, their components do not necessarily have to be in the same order.

slapi_rdn_contains()

Checks whether a Slapi_RDN structure holds any RDN matching a given type/value pair.

Syntax 

#include "slapi-plugin.h"

int slapi_rdn_contains(Slapi_RDN *rdn, const char *type,

  const char *value,size_t length);

Parameters

This function takes the following parameters: 

rdn
The Slapi_RDN structure containing the RDN value(s).
 
type
The type (cn, o, ou, etc.) of the RDN searched.
 
value
The value of the RDN searched.
 
length
Gives the length of value that should be taken into account for the string operation when searching for the RDN.

Returns

This function returns one of the following values:

Description

This function searches for an RDN inside of the Slapi_RDN structure rdn that matches both type and value as given in the parameters. This function makes a call to slapi_rdn_get_index() and verifies that the returned value is anything but -1.

See Also 

slapi_rdn_get_index()
 
slapi_rdn_contains_attr()

slapi_rdn_contains_attr()

Checks whether a Slapi_RDN structure contains any RDN matching a given type and, if true, gets the corresponding attribute value.

Syntax 

#include "slapi-plugin.h"

int slapi_rdn_contains_attr(Slapi_RDN *rdn, const char *type,

  char **value);

Parameters

This function takes the following parameters: 

rdn
The Slapi_RDN structure containing the RDN value(s).
 
type
Type (cn, o, ou, etc.) of the RDN searched.
 
value
Repository that will hold the value of the first RDN whose type matches the content of the parameter type. If this parameter is NULL at the return of the function, no RDN with the desired type exists within rdn.

Returns

This function returns one of the following values:

Description

This function looks for an RDN inside the Slapi_RDN structure rdn that matches the type given in the parameters. This function makes a call to slapi_rdn_get_index_attr() and verifies that the returned value is anything but -1. If successful, it also returns the corresponding attribute value.

See Also 

slapi_rdn_get_index_attr()
 
slapi_rdn_contains()

slapi_rdn_done()

Clears an instance of a Slapi_RDN structure.

Syntax 

#include "slapi-plugin.h"

void slapi_rdn_done(Slapi_RDN *rdn);

Parameters

This function takes the following parameter: 

rdn
Pointer to the structure to be cleared.

Description

This function clears the contents of a Slapi_RDN structure. It frees both the RDN value and the array of split RDNs. Those pointers are then set to NULL.

See Also 

slapi_rdn_free()
 
slapi_rdn_init()

slapi_rdn_free()

Frees a Slapi_RDN structure.

Syntax 

#include "slapi-plugin.h"

void slapi_rdn_free(Slapi_RDN **rdn);

Parameters

This function takes the following parameter: 

rdn
Pointer to the pointer of the Slapi_RDN structure to be freed.

Description

This function frees both the contents of the Slapi_RDN structure and the structure itself pointed to by the content of rdn.

See Also 

slapi_rdn_new()
 
slapi_rdn_done()

slapi_rdn_get_first()

Gets the type/value pair corresponding to the first RDN stored in a Slapi_RDN structure.

Syntax 

#include "slapi-plugin.h"

int slapi_rdn_get_first(Slapi_RDN *rdn, char **type, char **value);

Parameters

This function takes the following parameters: 

rdn
The Slapi_RDN structure containing the RDN value(s).
 
type
Repository that will hold the type of the first RDN. If this parameter is NULL at the return of the function, it means rdn is empty.
 
value
Repository that will hold the type of the first RDN. If this parameter is NULL at the return of the function, it means rdn is empty.

Returns

This function returns one of the following values:

Description

This function gets the type/value pair corresponding to the first RDN stored in rdn. For example, if the RDN is cn=Joey, the function will place cn in the type return parameter and Joey in value.

See Also 

slapi_rdn_get_next()
 
slapi_rdn_get_rdn()

slapi_rdn_get_index()

Gets the index of the RDN that follows the RDN with a given type and value.

Syntax 

#include "slapi-plugin.h"

int slapi_rdn_get_index(Slapi_RDN *rdn, const char *type,

  const char *value,size_t length);

Parameters

This function takes the following parameters: 

rdn
The Slapi_RDN structure containing the RDN value(s).
 
type
Type (cn, o, ou, etc.) of the RDN that is searched.
 
value
Value of the RDN searched.
 
length
Gives the length of value that should be taken into account for the string comparisons when searching for the RDN.

Returns

This function returns one of the following values:

Description

This function searches for an RDN inside the Slapi_RDN structure rdn that matches both type and value as given in the parameters. If it succeeds, the position of the matching RDN is returned.

See Also 

slapi_rdn_get_index_attr()
 
slapi_rdn_contains()

slapi_rdn_get_index_attr()

Gets the position and the attribute value of the first RDN in a Slapi_RDN structure that matches a given type.

Syntax 

#include "slapi-plugin.h"

int slapi_rdn_get_index_attr(Slapi_RDN *rdn,

  const char *type, char **value);

Parameters

This function takes the following parameters: 

rdn
The Slapi_RDN structure containing the RDN value(s).
 
type
Type (cn, o, ou, etc.) of the RDN searched.
 
value
Repository that will hold the value of the first RDN whose type matches the content of the parameter type. If this parameter is NULL at the return of the function, no RDN exists within rdn.

Returns

This function returns one of the following values:

Description

This function searches for an RDN inside of the Slapi_RDN structure rdn that matches the type given in the parameters. If successful, the position of the matching RDN, as well as the corresponding attribute value, is returned.

See Also 

slapi_rdn_get_index()

slapi_rdn_get_next()

Gets a certain RDN type/value pair from within the RDNs stored in a Slapi_RDN structure.

Syntax 

#include "slapi-plugin.h"

int slapi_rdn_get_next(Slapi_RDN *rdn, int index,

  char **type, char **value);

Parameters

This function takes the following parameters: 

rdn
The Slapi_RDN structure containing the RDN value(s).
 
index
Indicates the position of the RDN the precedes the currently desired RDN.
 
type
Repository that will hold the type (cn, o, ou, etc.) of the next (index+1) RDN. If this parameter is NULL at the return of the function, the RDN does not exist.
 
value
Repository that will hold the value of the next (index+1) RDN. If this parameter is NULL, the RDN does not exist.

Returns

This function returns one of the following values:

Description

This function gets the type/value pair corresponding to the RDN stored in the next (index+1) position inside rdn. The index of an element within an array of values is always one unit below its real position in the array.

See Also 

slapi_rdn_get_first()
 
slapi_rdn_get_rdn()

slapi_rdn_get_num_components()

Gets the number of RDN type/value pairs present in a Slapi_RDN structure.

Syntax 

#include "slapi-plugin.h"

int slapi_rdn_get_num_components(Slapi_RDN *rdn);

Parameters

This function takes the following parameter: 

rdn
The target Slapi_RDN structure.

Returns

This function returns the number of RDN type/value pairs present in rdn.

See Also 

slapi_rdn_add()

slapi_rdn_get_rdn()

Gets the RDN from a Slapi_RDN structure.

Syntax 

#include "slapi-plugin.h"

const char *slapi_rdn_get_rdn(const Slapi_RDN *rdn);

Parameters

This function takes the following parameter: 

rdn
The Slapi_RDN structure holding the RDN value.

Returns

This function returns the RDN value.

slapi_rdn_get_nrdn()

Not implemented; do not use.

Gets the new normalized RDN from a Slapi_RDN structure.

Syntax 

#include "slapi-plugin.h"

const char *slapi_rdn_get_nrdn(const Slapi_RDN *rdn);

Parameters

This function takes the following parameter: 

rdn
The Slapi_RDN structure holding the RDN value.

Returns

This function returns the new RDN value.

slapi_rdn_init()

Initializes a Slapi_RDN structure with NULL values.

Syntax 

#include "slapi-plugin.h"

void slapi_rdn_init(Slapi_RDN *rdn);

Parameters

This function takes the following parameters: 

rdn
The Slapi_RDN structure to be initialized.

Description

This function initializes a given Slapi_RDN structure with NULL values; both the RDN value and the array of split RDNs are set to NULL.

See Also 

slapi_rdn_new()
 
slapi_rdn_free()
 
slapi_rdn_done()

slapi_rdn_init_dn()

Initializes a Slapi_RDN structure with an RDN value taken from a given DN.

Syntax 

#include "slapi-plugin.h"

void slapi_rdn_init_dn(Slapi_RDN *rdn,const char *dn);

Parameters

This function takes the following parameters: 

rdn
The Slapi_RDN structure to be initialized.
 
dn
The DN value whose RDN will be used to initialize the new Slapi_RDN structure.

Description

This function initializes a given Slapi_RDN structure with the RDN value taken from the DN passed in the dn parameter.

See Also 

slapi_rdn_init_sdn()
 
slapi_rdn_init_rdn()

slapi_rdn_init_rdn()

Initializes a Slapi_RDN structure with an RDN value.

Syntax 

#include "slapi-plugin.h"

void slapi_rdn_init_rdn(Slapi_RDN *rdn,const Slapi_RDN *fromrdn);

Parameters

This function takes the following parameters: 

rdn
The Slapi_RDN structure to be initialized.
 
fromrdn
The RDN value to be set in the new Slapi_RDN structure.

Description

This function initializes a given Slapi_RDN structure with the RDN value in fromrdn.

See Also 

slapi_rdn_init_dn()
 
slapi_rdn_init_sdn()

slapi_rdn_init_sdn()

Initializes a Slapi_RDN structure with an RDN value taken from the DN contained in a given Slapi_RDN structure.

Syntax 

#include "slapi-plugin.h"

void slapi_rdn_init_sdn(Slapi_RDN *rdn,const Slapi_DN *sdn);

Parameters

This function takes the following parameters: 

rdn
The Slapi_RDN structure to be initialized.
 
sdn
The Slapi_DN structure containing the DN value whose RDN will be used to initialize the new Slapi_RDN structure.

Description

This function initializes a given Slapi_RDN structure with the RDN value taken from the DN passed within the Slapi_DN structure of the sdn parameter.

See Also 

slapi_rdn_init_dn()
 
slapi_rdn_init_rdn()

slapi_rdn_isempty()

Checks whether an RDN value is stored in a Slapi_RDN structure.

Syntax 

#include "slapi-plugin.h"

int slapi_rdn_isempty(const Slapi_RDN *rdn);

Parameters

This function takes the following parameter: 

rdn
The target Slapi_RDN structure.

Returns

This function returns one of the following values:

See Also 

slapi_rdn_init()
 
slapi_rdn_done()
 
slapi_rdn_free()

slapi_rdn_new()

Allocates a new Slapi_RDN structure and initializes the values to NULL.

Syntax 

#include "slapi-plugin.h"

Slapi_RDN * slapi_rdn_new();

Parameters

This function takes no parameters.

Returns

This function returns a pointer to the newly allocated, and still empty, Slapi_RDN structure.

Description

This function creates a new Slapi_RDN structure by allocating the necessary memory and initializing both the RDN value and the array of split RDNs to NULL.

See Also 

slapi_rdn_init()
 
slapi_rdn_done()
 
slapi_rdn_free()

slapi_rdn_new_dn()

Creates a new Slapi_RDN structure and sets an RDN value taken from a given DN.

Syntax 

#include "slapi-plugin.h"

Slapi_RDN *slapi_rdn_new_dn(const char *dn);

Parameters

This function takes the following parameter: 

dn
The DN value whose RDN will be used to initialize the new Slapi_RDN structure.

Returns

This function returns a pointer to the new Slapi_RDN structure initialized with the RDN taken from the DN value in dn.

Description

This function creates a new Slapi_RDN structure and initializes its RDN with the value taken from the DN passed in the dn parameter.

Memory Concerns

The memory is allocated by the function itself.

See Also 

slapi_rdn_new_sdn()
 
slapi_rdn_new_rdn()

slapi_rdn_new_rdn()

Creates a new Slapi_RDN structure and sets an RDN value.

Syntax 

#include "slapi-plugin.h"

Slapi_RDN * slapi_rdn_new_rdn(const Slapi_RDN *fromrdn);

Parameters

This function takes the following parameter: 

fromrdn
The RDN value to be set in the new Slapi_RDN structure.

Returns

This function returns a pointer to the new Slapi_RDN structure with an RDN set to the content of fromrdn.

Description

This function creates a new Slapi_RDN structure and initializes its RDN with the value of fromrdn.

Memory Concerns

The memory is allocated by the function itself.

See Also 

slapi_rdn_new_sdn()
 
slapi_rdn_new_dn()

slapi_rdn_new_sdn()

Creates a new Slapi_RDN structure and sets an RDN value taken from the DN contained in a given Slapi_RDN structure.

Syntax 

#include "slapi-plugin.h"

vSlapi_RDN *slapi_rdn_new_sdn(const Slapi_DN *sdn);

Parameters

This function takes the following parameter: 

sdn
Slapi_RDN structure containing the DN value whose RDN will be used to initialize the new Slapi_RDN structure.

Returns

This function returns a pointer to the new Slapi_RDN structure initialized with the RDN taken from the DN value in dn.

Description

This function creates a new Slapi_RDN structure and initializes its RDN with the value taken from the DN passed within the Slapi_RDN structure of the sdn parameter.

Memory Concerns

The memory is allocated by the function itself.

See Also 

slapi_rdn_new_dn()
 
slapi_rdn_new_rdn()

slapi_rdn_remove()

Removes an RDN type/value pair from a Slapi_RDN structure.

Syntax 

#include "slapi-plugin.h"

int slapi_rdn_remove(Slapi_RDN *rdn, const char *type,

  const char *value, size_t length);

Parameters

This function takes the following parameters: 

rdn
The target Slapi_RDN structure.
 
type
Type (cn, o, ou, etc.) of the RDN searched.
 
value
The value of the RDN searched.
 
length
Gives the length of value that should be taken into account for the string comparisons when searching for the RDN.

Returns

This function returns one of the following values:

Description

This function removes the RDN from rdn that matches the given criteria (type, value, and length).

See Also 

slapi_rdn_remove_attr()
 
slapi_rdn_remove_index()

slapi_rdn_remove_attr()

Removes an RDN type/value pair from a Slapi_RDN structure.

Syntax 

#include "slapi-plugin.h"

int slapi_rdn_remove_attr(Slapi_RDN *rdn, const char *type);

Parameters

This function takes the following parameters: 

rdn
The target Slapi_RDN structure.
 
type
Type (cn, o, ou, etc.) of the RDN searched.

Returns

This function returns one of the following values:

Description

This function removes the first RDN from rdn that matches the given type.

See Also 

slapi_rdn_remove()
 
slapi_rdn_remove_index()

slapi_rdn_remove_index()

Removes an RDN type/value pair from a Slapi_RDN structure.

Syntax 

#include "slapi-plugin.h"

int slapi_rdn_remove_index(Slapi_RDN *rdn, int atindex);

Parameters

This function takes the following parameters: 

rdn
The target Slapi_RDN structure.
 
atindex
The index of the RDN type/value pair to remove.

Returns

This function returns one of the following values:

Description

This function removes the RDN from rdn with atindex index (placed in the atindex+1 position).

See Also 

slapi_rdn_remove()
 
slapi_rdn_remove_attr()

slapi_rdn_set_dn()

Sets an RDN value in a Slapi_RDN structure.

Syntax 

#include "slapi-plugin.h"

void slapi_rdn_set_dn(Slapi_RDN *rdn,const char *dn);

Parameters

This function takes the following parameters: 

rdn
The target Slapi_RDN structure.
 
dn
The DN value whose RDN will be set in rdn.

Description

This function sets an RDN value in a Slapi_RDN structure. The structure is freed from memory and freed of any previous content before setting the new RDN. The new RDN is taken from the DN value present in the dn parameter.

See Also 

slapi_rdn_set_sdn()
 
slapi_rdn_set_rdn()

slapi_rdn_set_rdn()

Sets an RDN in a Slapi_RDN structure.

Syntax 

#include "slapi-plugin.h"

void slapi_rdn_set_rdn(Slapi_RDN *rdn,const Slapi_RDN *fromrdn);

Parameters

This function takes the following parameters: 

rdn
The target Slapi_RDN structure.
 
fromrdn
The RDN value to be set in rdn.

Description

This function sets an RDN value in a Slapi_RDN structure. The structure is freed from memory and freed of any previous content before setting the new RDN.

See Also 

slapi_rdn_set_dn()
 
slapi_rdn_set_sdn()

slapi_rdn_set_sdn()

Sets an RDN value in a Slapi_RDN structure.

Syntax 

#include "slapi-plugin.h"

void slapi_rdn_set_sdn(Slapi_RDN *rdn,const Slapi_DN *sdn);

Parameters

This function takes the following parameters: 

rdn
The target Slapi_RDN structure.
 
sdn
The Slapi_RDN structure containing the DN value whose RDN will be set in rdn.

Description

This function sets an RDN value in a Slapi_RDN structure. The structure is freed from memory and freed of any previous content before setting the new RDN. The new RDN is taken from the DN value present inside of a Slapi_DN structure.

See Also 

slapi_rdn_set_dn()
 
slapi_rdn_set_rdn()

Functions for Managing Roles

This section contains reference information on routines that help you deal with roles.

Table 15-24 Routines for Roles  
Function
Description
slapi_role_check()
Checks if the entry pointed to by entry_to_check contains the role indicated by role_dn.
slapi_register_role_check()
Allows registering of another function, other than the default, to use in slapi_role_check().

slapi_role_check()

Checks if the entry pointed to by entry_to_check contains the role indicated by role_dn.

Syntax 

#include "slapi-plugin.h"

int slapi_role_check(Slapi_Entry *entry_to_check,

  Slapi_DN *role_dn,int *present);

Parameters

This function takes the following parameters: 

entry_to_check
The entry in which the presence of a role is to be checked.
 
role_dn
The DN of the role for which to check.
 
present
Pointer to an integer where the result, present or not present, will be placed.

Returns

This function returns one of the following values:

slapi_register_role_check()

Allows registering of another function, other than the default, to use in slapi_role_check(). It is strongly recommended that the default should be used.

Syntax 

#include "slapi-plugin.h"

void slapi_register_role_check(roles_check_fn_type check_fn);

Parameters

This function takes the following parameter: 

check_fn
Function for registering.

Functions for Managing DNs

This section contains reference information on DN routines.

Table 15-25 DN Routines  
Function
Description
slapi_moddn_get_newdn()
Builds the new DN of an entry.
slapi_sdn_add_rdn()
Adds the RDN contained in a Slapi_RDN structure to the DN contained in a Slapi_DN structure.
slapi_sdn_compare()
Compares two DNs.
slapi_sdn_copy()
Copies a DN.
slapi_sdn_done()
Clears a Slapi_DN structure.
slapi_sdn_dup()
Duplicates a Slapi_DN structure.
slapi_sdn_free()
Frees a Slapi_DN structure.
slapi_sdn_get_backend_parent()
Gets the DN of the parent within a specific backend.
slapi_sdn_get_dn()
Gets the DN from a Slapi_DN structure.
slapi_sdn_get_ndn()
Gets the normalized DN of a Slapi_DN structure.
slapi_sdn_get_ndn_len()
Gets the length of the normalized DN of a Slapi_DN structure.
slapi_sdn_get_parent()
Get the parent DN of a given Slapi_DN structure.
slapi_sdn_get_rdn()
Gets the RDN from an NDN.
slapi_sdn_is_rdn_component()
Not implemented; do not use. Checks if there is a RDN value that is a component of the DN structure.
slapi_sdn_isempty()
Checks if there is a DN value stored in a Slapi_DN structure.
slapi_sdn_isgrandparent()
Checks if a DN is the parent of the parent of a DN.
slapi_sdn_isparent()
Checks if a DN is the parent of a DN.
slapi_sdn_issuffix()
Checks if a Slapi_DN structure contains a suffix of another.
slapi_sdn_new()
Allocates new Slapi_DN structure.
slapi_sdn_new_dn_byref()
Creates a new Slapi_DN structure.
slapi_sdn_new_dn_byval()
Creates a new Slapi_DN structure.
slapi_sdn_new_dn_passin()
Creates a new Slapi_DN structure.
slapi_sdn_new_ndn_byref()
Creates a new Slapi_DN structure.
slapi_sdn_new_ndn_byval()
Creates a new Slapi_DN structure.
slapi_sdn_scope_test()
Checks if an entry is in the scope of a certain base DN.
slapi_sdn_set_dn_byref()
Sets a DN value in a Slapi_DN structure.
slapi_sdn_set_dn_byval()
Sets a DN value in a Slapi_DN structure.
slapi_sdn_set_dn_passin()
Sets a DN value in a Slapi_DN structure.
slapi_sdn_set_ndn_byref()
Sets a a normalized DN in a Slapi_DN structure.
slapi_sdn_set_ndn_byval()
Sets a normalized DN in a Slapi_DN structure.
slapi_sdn_set_parent()
Sets a new parent in an entry.
slapi_sdn_set_rdn()
Sets a new RDN for an entry.

slapi_moddn_get_newdn()

Builds the new DN of an entry.

Syntax 

#include "slapi-plugin.h"

char * slapi_moddn_get_newdn(Slapi_DN *dn_olddn,

  char *newrdn, char *newsuperiordn);

Parameters

This function takes the following parameters: 

dn_olddn
The old DN value.
 
newrdn
The new RDN value.
 
newsuperordn
If not NULL, will be the DN of the future superior entry of the new DN, which will be worked out by adding the value in newrdn in front of the content of this parameter.

Returns

This function returns the new DN for the entry whose previous DN was dn_olddn.

Description

This function is used for moddn operations and builds a new DN out of a new RDN and the DN of the new parent.

The new DN is worked out by adding the new RDN in newrdn to a parent DN. The parent will be the value in newsuperiordn if different from NULL, and will otherwise be taken from dn_olddn by removing the old RDN (the parent of the entry will still be the same as the new DN).

slapi_sdn_add_rdn()

Adds the RDN contained in a Slapi_RDN structure to the DN contained in a Slapi_DN structure.

Syntax 

#include "slapi-plugin.h"

Slapi_DN *slapi_sdn_add_rdn(Slapi_DN *sdn, const Slapi_RDN *rdn);

Parameters

This function takes the following parameters: 

sdn
Slapi_DN structure containing the value to which a new RDN is to be added.
 
rdn
Slapi_RDN structure containing the RDN value that is to be added to the DN value.

Returns

This function returns the Slapi_DN structure with the new DN formed by adding the RDN value in rdn to the DN value in dn.

See Also 

slapi_sdn_set_rdn()

slapi_sdn_compare()

Compares two DNs.

Syntax 

#include "slapi-plugin.h" 

int slapi_sdn_compare( const Slapi_DN *sdn1, 

  const Slapi_DN *sdn2 );

Parameters

This function takes the following parameters: 

sdn1
DN to compare with the value in sdn2.
 
sdn2
DN to compare with the value in sdn1.

Returns

This function returns one of the following values:

Description

This function compares two DNs, sdn1 and sdn2. The comparison is case sensitive.

slapi_sdn_copy()

Makes a copy of a DN.

Syntax 

#include "slapi-plugin.h" 

void slapi_sdn_copy(const Slapi_DN *from, Slapi_DN *to);

Parameters

This function takes the following parameters: 

from
The original DN.
 
to
Destination of the copied DN, containing the copy of the DN in from.

Description

This function copies the DN in from to the structure pointed by to.

Memory Concerns

to must be allocated in advance of calling this function.

See Also 

slapi_sdn_dup()

slapi_sdn_done()

Clears an instance of a Slapi_DN structure.

Syntax 

#include "slapi-plugin.h" 

void slapi_sdn_done(Slapi_DN *sdn);

Parameters

This function takes the following parameter: 

sdn
Pointer to the structure to clear.

Description

This function clears the contents of a Slapi_DN structure. It frees both the DN and the normalized DN, if any, and sets those pointers to NULL.

See Also 

slapi_sdn_free()

slapi_sdn_dup()

Duplicates a Slapi_DN structure.

Syntax 

#include "slapi-plugin.h" 

Slapi_DN * slapi_sdn_dup(const Slapi_DN *sdn);

Parameters

This function takes the following parameter: 

sdn
Pointer to the Slapi_DN structure to duplicate.

Returns

This function returns a pointer to a duplicate of sdn.

See Also 

slapi_sdn_copy()
 
slapi_sdn_new()

slapi_sdn_free()

Frees a Slapi_DN structure.

Syntax 

#include "slapi-plugin.h" 

void slapi_sdn_free(Slapi_DN **sdn);

Parameters

This function takes the following parameter: 

sdn
Pointer tot he pointer of the Slapi_DN structure to be freed.

Description

This function frees the Slapi_DN structure and its contents pointed to by the contents of sdn.

See Also 

slapi_sdn_done()
 
slapi_sdn_new()

slapi_sdn_get_backend_parent()

Gets the DN of the parent of an entry within a specific backend.

Syntax 

#include "slapi-plugin.h" 

void slapi_sdn_get_backend_parent(const Slapi_DN *sdn,

  Slapi_DN *sdn_parent,const Slapi_Backend *backend);

Parameters

This function takes the following parameters: 

sdn
DN of the entry whose parent is searched.
 
sdn_parent
Parent DN of sdn.
 
backend
Backend of which the parent of sdn is to be searched.

Returns

This function gets the parent DN of an entry within a given backend. The parent DN is returned is sdn_parent, unless sdn is empty or is a suffix of the backend itself. In this case, sdn_parent is empty.

Memory Concerns

A Slapi_DN structure for sdn_parent must be allocated before calling this function.

See Also 

slapi_sdn_get_parent()

slapi_sdn_get_dn()

Gets the DN from a Slapi_DN structure.

Syntax 

#include "slapi-plugin.h" 

const char * slapi_sdn_get_dn(const Slapi_DN *sdn);

Parameters

This function takes the following parameter: 

sdn
The Slapi_DN structure containing the DN value.

Returns

This function returns the DN value.

Description

This function retrieves the DN value of a Slapi_DN structure. The returned value can be the normalized DN (in a canonical format and in lower case) if no other value is present.

See Also 

slapi_sdn_get_ndn()
 
slapi_sdn_get_parent()
 
slapi_sdn_get_rdn()

slapi_sdn_get_ndn()

Gets the normalized DN of a Slapi_DN structure.

Syntax 

#include "slapi-plugin.h" 

const char * slapi_sdn_get_ndn(const Slapi_DN *sdn);

Parameters

This function takes the following parameter: 

sdn
The Slapi_DN structure containing the DN value.

Returns

This function returns the normalized DN value.

Description

This function retrieves the normalized DN (in a canonical format and lower case) from a Slapi_DN structure and normalizes sdn if it has not already been normalized.

See Also 

slapi_sdn_get_dn()

slapi_sdn_get_ndn_len()

Gets the length of the normalized DN of a Slapi_DN structure.

Syntax 

#include "slapi-plugin.h" 

int slapi_sdn_get_ndn_len(const Slapi_DN *sdn);

Parameters

This function takes the following parameter: 

sdn
The Slapi_DN structure containing the DN value.

Returns

This function returns the length of the normalized DN.

Description

This function contains the length of the normalized DN and normalizes sdn if it has not already been normalized.

slapi_sdn_get_parent()

Gets the parent DN of a given Slapi_DN structure.

Syntax 

#include "slapi-plugin.h" 

void slapi_sdn_get_parent(const Slapi_DN *sdn,

  Slapi_DN *sdn_parent);

Parameters

This function takes the following parameters: 

sdn
Pointer to the Slapi_DN structure containing the DN whose parent is searched.
 
sdn_parent
Pointer to the Slapi_DN structure where the parent DN is returned.

Description

This function returns a Slapi_DN structure containing the parent DN of the DN kept in the structure pointed to by sdn.

See Also 

slapi_sdn_get_backend_parent()

slapi_sdn_get_rdn()

Gets the RDN from a DN.

Syntax 

#include "slapi-plugin.h" 

void slapi_sdn_get_rdn(const Slapi_DN *sdn,

  Slapi_RDN *rdn);

Parameters

This function takes the following parameters: 

sdn
Pointer to the Slapi_DN structure containing the DN.
 
rdn
Pointer to the Slapi_RDN structure where the RDN is returned.

Description

This function takes the DN stored in the Slapi_DN structure pointed to by sdn and retrieves its returned RDN within the Slapi_RDN structure pointed to by rdn.

See Also 

slapi_sdn_get_dn()
 
slapi_sdn_add_rdn()
 
slapi_sdn_is_rdn_component()

slapi_sdn_is_rdn_component()

Not implemented; do not use.

Checks if there is a RDN value that is a component of the DN structure.

Syntax 

#include "slapi-plugin.h" 

int slapi_sdn_is_rdn_component(const Slapi_DN *rdn, 

  const Slapi_Attr *a, const Slapi_Value *v);

Parameters

This function takes the following parameters: 

rdn

Pointer to the Slapi_DN structure that is going to be checked. 

a
A pointer to an attribute used to check the RDN value.
 
v
Holds the value of the attribute.

Returns

This function returns one of the following values:

Description

This function checks whether a Slapi_DN structure contains an RDN value that is a component of the DN structure.

See Also 

slapi_sdn_get_rdn()

slapi_sdn_isempty()

Checks whether there is a DN value stored in a Slapi_DN structure.

Syntax 

#include "slapi-plugin.h" 

int slapi_sdn_isempty( const Slapi_DN *sdn);

Parameters

This function takes the following parameter: 

sdn

Pointer to the Slapi_DN structure that is going to be checked.


Returns

This function returns one of the following values:

Description

This function checks whether a Slapi_DN structure contains a normalized or non-normalized value.

See Also 

slapi_sdn_done()

slapi_sdn_isgrandparent()

Checks whether a DN is the parent of the parent of a given DN.

Syntax 

#include "slapi-plugin.h" 

int slapi_sdn_isgrandparent( const Slapi_DN *parent, 

  const Slapi_DN *child );

Parameters

This function takes the following parameters: 

parent
Pointer to the Slapi_DN structure containing the DN which claims to be the grandparent DN of the DN in child.
 
child
Pointer to the Slapi_DN structure containing the DN of the supposed "grandchild" of the DN in the structure pointed to by parent.

Returns

This function returns one of the following values:

See Also 

slapi_sdn_isparent()
 
slapi_sdn_issuffix()
 
slapi_sdn_get_parent()

slapi_sdn_isparent()

Checks whether a DN is the parent of a given DN.

Syntax 

#include "slapi-plugin.h" 

int slapi_sdn_isparent( const Slapi_DN *parent, 

  const Slapi_DN *child );

Parameters

This function takes the following parameters: 

parent
Pointer to the Slapi_DN structure containing the DN which claims to be the parent of the DN in child.
 
child
Pointer to the Slapi_DN structure containing the DN of the supposed child of the DN in the structure pointed to by parent.

Returns

This function returns one of the following values:

See Also 

slapi_sdn_issuffix()
 
slapi_sdn_get_parent()

slapi_sdn_issuffix()

Checks whether a Slapi_DN structure contains a suffix of another Slapi_DN structure.

Syntax 

#include "slapi-plugin.h" 

int slapi_sdn_issuffix(const Slapi_DN *sdn, 

  const Slapi_DN *suffixsdn);

Parameters

This function takes the following parameters: 

sdn
Pointer to the Slapi_DN structure to be checked.
 
suffixsdn
Pointer to the Slapi_DN structure of the suffix.

Returns

This function returns one of the following values:

See Also 

slapi_sdn_isparent()

slapi_sdn_new()

Allocates a new Slapi_DN structure and initializes it to NULL.

Syntax 

#include "slapi-plugin.h" 

Slapi_DN *slapi_sdn_new();

Parameters

This function takes no parameters.

Returns

This function returns a pointer to the newly allocated, and still empty, Slapi_DN structure.

Description

This function creates a new Slapi_DN structure by allocating the necessary memory and initializing both DN and normalized DN values to NULL.

See Also 

slapi_sdn_free()
 
slapi_sdn_copy()
 
slapi_sdn_done()

slapi_sdn_new_dn_byref()

Creates a new Slapi_DN structure and sets a DN value.

Syntax 

#include "slapi-plugin.h" 

Slapi_DN *slapi_sdn_new_dn_byref(const char *dn);

Parameters

This function takes the following parameter: 

dn
The DN value to be set in the new Slapi_DN structure.

Returns

This function returns a pointer to the new Slapi_DN structure with a DN valueset to the content of dn.

Description

This function creates a new Slapi_DN structure and initializes its DN with the value of dn. The DN of the new structure will point to the same string pointed to by dn; the DN value is passed in to the parameter by reference. However, the FLAG_DN flag is not set, and no counter is incremented.

Memory Concerns

The memory is allocated by the function itself.

See Also 

slapi_sdn_new_dn_byval()
 
slapi_sdn_new_dn_passin()

slapi_sdn_new_dn_byval()

Creates a new Slapi_DN structure and sets a DN value.

Syntax 

#include "slapi-plugin.h" 

Slapi_DN *slapi_sdn_new_dn_byval(const char *dn);

Parameters

This function takes the following parameter: 

dn
The DN value to be set in the new Slapi_DN structure.

Returns

This function returns a pointer to the new Slapi_DN structure with a DN valueset to the content of dn.

Description

This function creates a new Slapi_DN structure and initializes its DN with the value of dn. The DN of the new structure will point to a copy of the string pointed to by dn; the DN value is passed in to the parameter by value. The FLAG_DN flag is set, and the internal counter is incremented.

Memory Concerns

The memory is allocated by the function itself.

See Also 

slapi_sdn_new_dn_byref()
 
slapi_sdn_new_dn_passin()

slapi_sdn_new_dn_passin()

Creates a new Slapi_DN structure and sets a DN value.

Syntax 

#include "slapi-plugin.h" 

Slapi_DN *slapi_sdn_new_dn_passin(const char *dn);

Parameters

This function takes the following parameter: 

dn
The DN value to be set the new Slapi_DN structure.

Returns

This function returns a pointer to the new Slapi_DN structure with DN valueset to the content of dn.

Description

This function creates a new Slapi_DN structure and initializes its DN with the value of dn. The DN of the new structure will point to the string pointed to by dn. The FLAG_DN flag is set, and the internal counter is incremented.

Memory Concerns

The memory is allocated by the function itself.

See Also 

slapi_sdn_new_dn_byval()
 
slapi_sdn_new_ndn_byref()

slapi_sdn_new_ndn_byref()

Creates a new Slapi_DN structure and sets a normalized DN value.

Syntax 

#include "slapi-plugin.h" 

Slapi_DN *slapi_sdn_new_ndn_byref(const char *ndn);

Parameters

This function takes the following parameter: 

ndn
The normalized DN value to be set in the new Slapi_DN structure.

Returns

This function returns a pointer to the new Slapi_DN structure with a normalized DN valueset to the content of ndn.

Descriptions

This function creates a new Slapi_DN structure and initializes its normalized DN with the value of ndn. The normalized DN of the new structure will point to the same string pointed to by ndn; the normalized DN value is passed into the parameter by reference. However, the FLAG_NDN flag is not set, and no counter is incremented.

Memory Concerns

The memory is allocated by the function itself.

See Also 

slapi_sdn_new_ndn_byval()

slapi_sdn_new_ndn_byval()

Creates a new Slapi_DN structure and sets a normalized DN value.

Syntax 

#include "slapi-plugin.h" 

Slapi_DN *slapi_sdn_new_ndn_byval(const char *ndn);

Parameters

This function takes the following parameter: 

ndn
The normalized DN value to be set in the new Slapi_DN structure.

Returns

This function returns a pointer to the new Slapi_DN structure with a normalized DN valueset to the content of ndn.

Description

This function creates a new Slapi_DN structure and initializes its normalized DN with the value of ndn. The normalized DN of the new structure will point to a copy of the string pointed to by ndn; the normalized DN value is passed into the parameter by value. The FLAG_DND flag is set, and the internal counter is incremented.

Memory Concerns

The memory is allocated by the function itself.

See Also 

slapi_sdn_new_ndn_byref()

slapi_sdn_scope_test()

Checks whether an entry, given its DN, is in the scope of a certain base DN.

Syntax 

#include "slapi-plugin.h" 

int slapi_sdn_scope_test( const Slapi_DN *dn, 

  const Slapi_DN *base, int scope );

Parameters

This function takes the following parameters: 

dn
The DN of the entry subject of scope test.
 
base
The base DN against which dn is going to be tested.
 
scope
The scope tested. This parameter can take one of the following levels:
  • LDAP_SCOPE_BASE - where the entry DN should be the same as the base DN.
  • LDAP_SCOPE_ONELEVEL - where the base DN should be the parent of the entry.
  • DN LDAP_SCOPE_SUBTREE - where the base DN should at least be the suffix of the entry DN.

Returns

This function returns non-zero if dn matches the scoping criteria given by base and scope.

Description

This function carries out a simple test to check whether the DN passed in the dn parameter is actually in the scope of the base DN according to the values passed into the scope and base parameters.

See Also 

slapi_sdn_compare()
 
slapi_sdn_isparent()
 
slapi_sdn_issuffix()

slapi_sdn_set_dn_byref()

Sets a DN value in a Slapi_DN structure.

Syntax 

#include "slapi-plugin.h" 

Slapi_DN *slapi_sdn_set_dn_byref(Slapi_DN *sdn, const char *dn);

Parameters

This function takes the following parameters: 

sdn
The target Slapi_DN structure.
 
dn
The DN value to be set in sdn.

Returns

This function returns a pointer to the Slapi_DN structure containing the new DN value.

Description

This function sets a DN value in a Slapi_DN structure. The DN of the new structure will point to the same string pointed to by dn; the DN value is passed into the parameter by value. However, the FLAG_DN flag is not set, and no internal counter is incremented.

See Also 

slapi_sdn_set_dn_byval()
 
slapi_sdn_set_dn_passin()

slapi_sdn_set_dn_byval()

Sets a DN value in a Slapi_DN structure.

Syntax 

#include "slapi-plugin.h" 

Slapi_DN *slapi_sdn_set_dn_byval(Slapi_DN *sdn, const char *dn);

Parameters

This function takes the following parameters: 

sdn
The target Slapi_DN structure.
 
dn
The DN value to be set in sdn.

Returns

This function returns a pointer to the Slapi_DN structure containing the new DN value.

Description

This function sets a DN value in a Slapi_DN structure. The DN of the new structure will point to a copy of the string pointed to by dn; the DN value is passed into the parameter by value. The FLAG_DN flag is set, and the internal counters are incremented.

See Also 

slapi_sdn_set_ndn_byref()
 
slapi_sdn_set_dn_passin()

slapi_sdn_set_dn_passin()

Sets a DN value in Slapi_DN structure.

Syntax 

#include "slapi-plugin.h" 

Slapi_DN *slapi_sdn_set_dn_passin(Slapi_DN *sdn, const char *dn);

Parameters

This function takes the following parameters: 

sdn
The target Slapi_DN structure.
 
dn
DN value to be set in sdn.

Returns

This function returns a pointer to the Slapi_DN structure containing the new DN value.

Description

This function sets a DN value in a Slapi_DN structure. The DN of the new structure will point to the same string pointed to by dn. The FLAG_DN flag is set, and the internal counters are incremented.

See Also 

slapi_sdn_set_dn_byval()
 
slapi_sdn_set_dn_byref()

slapi_sdn_set_ndn_byref()

Sets a normalized DN in a Slapi_DN structure.

Syntax 

#include "slapi-plugin.h" 

Slapi_DN *slapi_sdn_set_ndn_byref(Slapi_DN *sdn, const char *ndn);

Parameters

This function takes the following parameters: 

sdn
The target Slapi_DN structure.
 
ndn
Normalized DN value to be set in sdn.

Returns

This function returns a pointer to the Slapi_DN structure containing the new normalized DN value.

Description

This function sets a normalized DN value in a Slapi_DN structure. The normalized DN of the new structure will point to the same string pointed to by ndn; the normalized DN value is passed into the parameter by reference. However, the FLAG_DN flag is not set, and no internal counter is incremented.

See Also 

slapi_sdn_set_dn_byval()
 
slapi_sdn_set_dn_passin()

slapi_sdn_set_ndn_byval()

Sets a normalized DN value in Slapi_DN structure.

Syntax 

#include "slapi-plugin.h" 

Slapi_DN *slapi_sdn_set_ndn_byval(Slapi_DN *sdn, const char *ndn);

Parameters

This function takes the following parameters: 

sdn
The target Slapi_DN structure.
 
ndn
The normalized DN value to be set in sdn.

Returns

This function returns a pointer to the Slapi_DN structure containing the new normalized DN value.

Description

This function sets a normalized DN value in a Slapi_DN structure. The normalized DN of the new structure will point to a copy of the string pointed to by ndn; the normalized DN value is passed into the parameter by value. The FLAG_DN flag is set, and the internal counters are incremented.

See Also 

slapi_sdn_set_ndn_byref()
 
slapi_sdn_set_dn_passin()

slapi_sdn_set_parent()

Sets a new parent for a given entry.

Syntax 

#include "slapi-plugin.h" 

Slapi_DN *slapi_sdn_set_parent(Slapi_DN *sdn, 

  const Slapi_DN *parentdn);

Parameters

This function takes the following parameters: 

sdn
The Slapi_DN structure containing the DN of the entry.
 
parentdn
The new parent DN.

Returns

The function returns a pointer to the Slapi_DN structure that contains the DN of the entry after the new parent DN has been set.

Description

This function sets a new parent for an entry. This is done by keeping the RDN of the original DN of the entry and by adding the DN of its new parent (the value of parentdn) to it.

See Also 

slapi_sdn_isparent()
 
slapi_sdn_get_parent()

slapi_sdn_set_rdn()

Sets a new RDN for given entry.

Syntax 

#include "slapi-plugin.h" 

Slapi_DN *slapi_sdn_set_rdn(Slapi_DN *sdn, const Slapi_RDN *rdn);

Parameters

This function takes the following parameters: 

sdn
The Slapi_DN structure containing the DN of the entry.
 
rdn
The new RDN.

Returns

This function returns a pointer to the Slapi_DN structure that keeps the DN of the entry after the new RDN has been set.

Description

This function sets a new RDN for an entry. This is done by retrieving the DN of the entry's parent of the origin DN of the entry and then adding it to the RDN (the value of rdn) to it.

See Also 

slapi_sdn_get_rdn()

Functions for Sending Entries and Results to the Client

This section contains reference information on routines for sending entries and results to the client.

Table 15-26 Routines for Sending Entries and Results to Clients  
Function
Description
slapi_send_ldap_referral()
Processes an entry's LDAP v3 referrals.
slapi_send_ldap_result()
Sends an LDAP result code back to the client.
slapi_send_ldap_search_entry()
Sends an entry found by a search back to the client.

slapi_send_ldap_referral()

Processes an entry's LDAPv3 referrals, which are found in the entry's ref attribute. For LDAPv3 clients, this function sends the LDAP referrals back to the client. For LDAPv2 clients, this function copies the referrals to an array of berval structures that you can pass to slapi_send_ldap_result() function at a later time.

Syntax 

#include "slapi-plugin.h"

int slapi_send_ldap_referral( Slapi_PBlock *pb, 

  Slapi_Entry *e, struct berval **refs, 

  struct berval ***urls );

Parameters

This function takes the following parameters: 

pb
Parameter block.
 
e
Pointer to the Slapi_Entry structure representing the entry with which you are working. 
refs
Pointer to the NULL-terminated array of berval structures containing the LDAPv3 referrals (search result references) found in the entry. 
urls
Pointer to the array of berval structures used to collect LDAP referrals for LDAPv2 clients.

Returns

This function returns one of the following values:

Description

When you call this function, the server processes the LDAP referrals specified in the refs argument. The server processes referrals in different ways, depending on the version of the LDAP protocol supported by the client:

When you call the slapi_send_ldap_referral() function for LDAPv3 clients, the server sends the referrals specified in the refs argument back to the client as search result references. The urls argument is not used in this case.
When you call the slapi_send_ldap_referral() function for LDAPv2 clients, the server collects the referrals specified in refs in the urls argument. No data is sent to the LDAPv2 client.
To get the referrals to an LDAPv2 client, you need to pass the urls argument (along with an LDAP_PARTIAL_RESULTS result code) to the slapi_send_ldap_result() function. slapi_send_ldap_result() concatenates the referrals specified in the urls argument and sends the resulting string to the client as part of the error message.

If you want to define your own function for sending referrals, write a function that complies with the type definition send_ldap_referral_fn_ptr_t and set the SLAPI_PLUGIN_DB_REFERRAL_FN parameter in the parameter block to the name of your function.

See Also 

slapi_send_ldap_result()
 
slapi_send_ldap_search_entry()

slapi_send_ldap_result()

Sends an LDAP result code back to the client.

Syntax 

#include "slapi-plugin.h"

void slapi_send_ldap_result( Slapi_PBlock *pb, int err, 

  char *matched, char *text, int nentries, 

  struct berval **urls );

Parameters

This function takes the following parameters: 

pb
Parameter block.
 
err
LDAP result code that you want sent back to the client; for example, LDAP_SUCCESS. 
matched
When sending back an LDAP_NO_SUCH_OBJECT result code, use this argument to specify the portion of the target DN that could be matched. Pass NULL in other situations. 
text
Error message that you want sent back to the client. Pass NULL if you do not want an error message sent back. 
nentries
When sending back the result code for an LDAP search operation, use this argument to specify the number of matching entries found. 
urls
When sending back an LDAP_PARTIAL_RESULTS result code to an LDAPv2 client or an LDAP_REFERRAL result code to an LDAPv3 client, use this argument to specify the array of berval structures containing the referral URLs. Pass NULL in other situations.

Description

Call slapi_send_ldap_result() to send an LDAP result code (such as LDAP_SUCCESS) back to the client.

The following arguments are intended for use only in certain situations:

When sending an LDAP_NO_SUCH_OBJECT result code back to a client, use matched to specify how much of the target DN could be found in the database. For example, if the client was attempting to find the DN
  cn=Babs Jensen, ou=Product Division, l=US, dc=example,dc=com
and the database contains entries for c=US and dc=example,dc=com,c=US but no entry for ou=Product Division,l=US,dc=example,dc=com, you should set the matched parameter to
  l=US, dc=example,dc=com
When sending an LDAP_PARTIAL_RESULTS result code back to an LDAPv2 client or an LDAP_REFERRAL result code back to an LDAPv3 client, use urls to specify the referral URLs.
For LDAPv3 referrals, you can call the slapi_str2filter() to send referrals to LDAPv3 clients and collect them for LDAPv2 clients. You can pass the array of collected referrals to the urls argument of slapi_send_ldap_results(). For example: 
struct berval **urls;

...

slapi_send_ldap_referral( ld, e, &refs, &urls );

slapi_send_ldap_result( ld, LDAP_PARTIAL_RESULTS, NULL, NULL, 
0, \

    urls );
If you want to define your own function for sending result codes, write a function that complies with the type definition send_ldap_result_fn_ptr_t, and set the SLAPI_PLUGIN_DB_RESULT_FN parameter in the parameter block to the name of your function.

See Also 

slapi_str2filter()
 
slapi_send_ldap_search_entry()

slapi_send_ldap_search_entry()

Sends an entry found by a search back to the client.

Syntax 

#include "slapi-plugin.h"

int slapi_send_ldap_search_entry( Slapi_PBlock *pb, 

  Slapi_Entry *e, LDAPControl **ectrls, char **attrs, 

  int attrsonly );

Parameters

This function takes the following parameters: 

pb
Parameter block.
 
e
Pointer to the Slapi_Entry structure representing the entry that you want to send back to the client. 
ectrls
Pointer to the array of LDAPControl structures representing the controls associated with the search request. 
attrs
Attribute types specified in the LDAP search request 
attrsonly
Specifies whether the attribute values should be sent back with the result.
  • If 0, the values are included.
  • If 1, the values are not included.

Returns

This function returns one of the following values:

Description

Call slapi_send_ldap_search_entry() to send an entry found by a search back to the client.

attrs is the array of attribute types that you want to send from the entry. This value is equivalent to the SLAPI_SEARCH_ATTRS parameter in the parameter block.

attrsonly specifies whether you want to send only the attribute types or the attribute types and their values:

This value is equivalent to the SLAPI_SEARCH_ATTRSONLY parameter in the parameter block.

If you want to define your own function for sending entries, write a function that complies with the type definition send_ldap_search_entry_fn_ptr_t, and set the SLAPI_PLUGIN_DB_ENTRY_FN parameter in the parameter block to the name of your function.

See Also 

slapi_str2filter()
 
slapi_send_ldap_search_entry()

Functions Related to UTF-8

This section contains reference information on routines that are related to UTF-8.

Table 15-27 UTF-8 Related Routines  
Function
Description
slapi_has8thBit()
Checks if a string has an 8-bit character.
slapi_utf8casecmp()
Makes case-insensitive string comparison of two UTF-8 strings.
slapi_UTF8CASECMP()
Compares two UTF-8 strings.
slapi_utf8ncasecmp()
Makes case-insensitive string comparison of first n characters of two UTF-8 strings.
slapi_UTF8NCASECMP()
Compares a specified number of UTF-8 characters.
slapi_utf8isLower()
Verifies if a UTF-8 character is a lower-case letter.
slapi_UTF8ISLOWER()
Verifies if a UTF-8 character is a lower-case letter.
slapi_utf8isUpper()
Verifies if a UTF-8 character is an upper-case letter.
slapi_UTF8ISUPPER()
Verifies if a UTF-8 character is an upper-case letter.
slapi_utf8StrToLower()
Converts upper-case characters in a UTF-8 string to lower-case characters.
slapi_UTF8STRTOLOWER()
Converts upper-case characters in a UTF-8 string to lower-case characters.
slapi_utf8StrToUpper()
Converts lower-case characters in a UTF-8 string to upper-case characters.
slapi_UTF8STRTOUPPER()
Converts lower-case characters in a UTF-8 string to upper-case characters.
slapi_utf8ToLower()
Convert an upper-case UTF-8 character to lower-case character.
slapi_UTF8TOLOWER()
Converts an upper-case UTF-8 character to lower-case character.
slapi_utf8ToUpper()
Converts a lower-case UTF-8 character to an upper-case character.
slapi_UTF8TOUPPER()
Converts a lower-case UTF-8 character to an upper-case character.

slapi_has8thBit()

Checks if a string has an 8-bit character.

Syntax 

#include "slapi-plugin.h"

int slapi_has8thBit(unsigned char *s);

Parameters

This function takes the following parameter: 

s
Pointer to the null-terminated string to test.

Returns

This function returns one of the following values:

slapi_utf8casecmp()

Makes case-insensitive string comparison of two UTF-8 strings.

Syntax 

#include "slapi-plugin.h"

int slapi_utf8casecmp(unsigned char *s0, unsigned char *s1);

Parameters

This function takes the following parameters: 

s0
A null-terminated UTF-8 string.
 
s1
A null-terminated UTF-8 string.

Returns

This function returns one of the following values:

Description

The function takes two UTF-8 strings (s0, s1) of unsigned char to be compared. The comparison rules are as follows:

Evaluation occurs in this order:

Do not use this function for collation as there's no notion of locale in this function; it's UTF-8 code order, which is different from the locale-based collation.

slapi_UTF8CASECMP()

Compares two UTF-8 strings.

Syntax 

#include "slapi-plugin.h"

int slapi_UTF8CASECMP(char *s0, char *s1);

Parameters

This function takes the following parameters: 

s0
A null-terminated UTF-8 string.
 
s1
A null-terminated UTF-8 string.

Returns

This function returns one of the following values:

Description

The function takes two UTF-8 strings (s0, s1) of signed char to be compared. The comparison rules are as follows:

Evaluation occurs in this order:

slapi_utf8ncasecmp()

Makes case-insensitive string comparison of first n characters of two UTF-8 strings.

Syntax 

#include "slapi-plugin.h"

int slapi_utf8ncasecmp(unsigned char *s0, unsigned char *s1, int 
n);

Parameters

This function takes the following parameters: 

s0
A null-terminated UTF-8 string.
 
s1
A null-terminated UTF-8 string.
 
n
The number of UTF-8 characters (not bytes) from s0 and s1 to compare.

Returns

This function returns one of the following values:

Description

This function takes two UTF-8 strings (s0, s1) of unsigned char to be compared for a specified number of characters. The rules are the same as in slapi_utf8casecmp() except the n characters limit.

Do not use this function for collation as there is no notion of locale in this function; it's UTF-8 code order, which is different from the locale-based collation. Also, the comparison is for n characters, not n bytes.

slapi_UTF8NCASECMP()

Compares a specified number of UTF-8 characters.

Syntax 

#include "slapi-plugin.h"

int slapi_UTF8NCASECMP(char *s0, char *s1, int n);

Parameters

This function takes the following parameters: 

s0
A null-terminated UTF-8 string.
 
s1
A null-terminated UTF-8 string.
 
n
The number of UTF-8 characters (not bytes) from s0 and s1 to compare.

Returns

This function returns one of the following values:

Description

This function has the following rules:

Evaluation occurs in this order:

slapi_utf8isLower()

Verifies if a UTF-8 character is a lower-case letter.

Syntax 

#include "slapi-plugin.h"

int slapi_utf8isLower(unsigned char *s);

This function takes the following parameter: 

s
Pointer to a single UTF-8 character (could be multiple bytes).

Returns

This function returns one of the following values:

slapi_UTF8ISLOWER()

Verifies if a UTF-8 character is a lower-case letter.

Syntax 

#include "slapi-plugin.h"

int slapi_UTF8ISLOWER(char *s);

Parameters

This function takes the following parameter: 

s
Pointer to a single UTF-8 character (could be multiple bytes).

Returns

This function returns one of the following values:

slapi_utf8isUpper()

Verifies if a UTF-8 character is an upper-case letter.

Syntax 

#include "slapi-plugin.h"

int slapi_utf8isUpper(unsigned char *s);

Parameters

This function takes the following parameter: 

s
A single UTF-8 character (could be multiple bytes)

Returns

This function returns one of the following values:

slapi_UTF8ISUPPER()

Verifies if a UTF-8 character is an upper-case letter.

Syntax 

#include "slapi-plugin.h"

int slapi_UTF8ISUPPER(char *s);

Parameters

This function takes the following parameter: 

s
A single UTF-8 character (could be multiple bytes)

Returns

This function returns one of the following values:

slapi_utf8StrToLower()

Converts upper case characters in a UTF-8 string to lower-case characters.

Syntax 

#include "slapi-plugin.h"

unsigned char *slapi_utf8StrToLower(unsigned char *s);

Parameters

This function takes the following parameter: 

s
A null-terminated UTF-8 string to be converted to lower case.

Returns

This function returns one of the following values:

Description

This function converts a string of multiple UTF-8 characters, not a single character as in slapi_UTF8TOLOWER().

Memory Concerns

The output string is allocated and needs to be released when it is no longer needed.

See Also 

slapi_utf8ToLower()

slapi_UTF8STRTOLOWER()

Converts upper-case characters in a UTF-8 string to lower-case characters.

Syntax 

#include "slapi-plugin.h"

unsigned char *slapi_UTF8STRTOLOWER(char *s);;

Parameters

This function takes the following parameter: 

s
A null-terminated UTF-8 string to be converted to lower case.

Returns

This function returns one of the following values:

Description

This function converts a string of multiple UTF-8 characters, not a single character as in slapi_UTF8TOLOWER().

Memory Concerns

The output string is allocated and needs to be released when no longer needed.

See Also 

slapi_UTF8TOLOWER()

slapi_utf8StrToUpper()

Converts lower-case characters in a UTF-8 string to upper-case characters.

Syntax 

#include "slapi-plugin.h"

unsigned char *slapi_utf8StrToUpper(unsigned char *s);

Parameters

This function takes the following parameter: 

s
A null-terminated UTF-8 string.

Returns

This function returns one of the following values:

Description

This function converts a string of multiple UTF-8 characters, not a single character as in slapi_utf8ToUpper().

Memory Concerns

The output string is allocated in this function and needs to be released when it is no longer used.

slapi_UTF8STRTOUPPER()

Converts lower-case characters in a UTF-8 string to upper-case characters.

Syntax 

#include "slapi-plugin.h"

unsigned char *slapi_UTF8STRTOUPPER(char *s);

Parameters

This function takes the following parameter: 

s
A null-terminated UTF-8 string.

Returns

This function returns one of the following values:

Memory Concerns

The output string is allocated in this function and needs to be released when it is no longer used.

slapi_utf8ToLower()

Converts an upper-case UTF-8 character to a lower-case character.

Syntax 

#include "slapi-plugin.h"

void slapi_utf8ToLower(unsigned char *s, unsigned char *d, int *ssz, 

int *dsz);

Parameters

This function takes the following parameters: 

s
A single UTF-8 character (could be multiple bytes).
 
d
Pointer to the lower case form of s. The memory for this must be allocated by the caller before calling the function.
 
ssz
Length in bytes of the input character.
 
dsz
Length in bytes of the output character.

Memory Concerns

Memory for the output character is not allocated in this function; caller should have allocated it (d). memmove is used since s and d are overlapped.

slapi_UTF8TOLOWER()

Converts an upper-case UTF-8 character to a lower-case character.

Syntax 

#include "slapi-plugin.h"

void slapi_UTF8TOLOWER(char *s, char *d, int *ssz, int *dsz);

Parameters

This function takes the following parameters: 

s
A single UTF-8 character (could be multiple bytes).
 
d
Pointer to the lower case form of s. The memory for this must be allocated by the caller before calling the function.
 
ssz
Returns the length in bytes of the input character.
 
dsz
Returns the length in bytes of the output character.

slapi_utf8ToUpper()

Converts a lower-case UTF-8 character to an upper-case character.

Syntax 

#include "slapi-plugin.h"

void slapi_utf8ToUpper(unsigned char *s, unsigned char *d, int 
*ssz, 

int *dsz);

Parameters

This function takes the following parameters: 

s
Pointer to a single UTF-8 character (could be multiple bytes).
 
d
Pointer to the upper case version of s. The memory for this must be allocated by the caller before calling the function.
 
ssz
Length in bytes of the input character.
 
dsz
Length in bytes of the output character.

Memory Concerns

Memory for the output character is not allocated in this function; caller should have allocated it (d). memmove is used since s and d are overlapped.

slapi_UTF8TOUPPER()

Converts a lower-case UTF-8 character to an upper-case character.

Syntax 

#include "slapi-plugin.h"

void slapi_UTF8TOUPPER(char *s, char *d, int *ssz, int *dsz);

Parameters

This function takes the following parameters: 

s
Pointer to a single UTF-8 character (could be multiple bytes).
 
d
Pointer to the upper case version of s. The memory for this must be allocated by the caller before calling the function.
 
ssz
Returns the length in bytes of the input character.
 
dsz
Returns the length in bytes of the output character.

Functions for Handling Values

This section contains reference information on value routines.

Table 15-28 Value Routines  
Function
Description
slapi_value_compare()
Compares two values.
slapi_value_dup()
Duplicates a value.
slapi_value_free()
Frees a Slapi_Value structure from memory.
slapi_value_get_berval()
Gets the berval structure of the value.
slapi_value_get_int()
Converts the value of an integer.
slapi_value_get_length()
Gets the length of a value.
slapi_value_get_long()
Converts a value into a long integer.
slapi_value_get_string()
Returns the value as a string.
slapi_value_get_uint()
Converts the value into an unsigned integer.
slapi_value_get_ulong()
Converts the value into an unsigned long.
slapi_value_init()
Initializes a Slapi_Value structure with no values.
slapi_value_init_berval()
Initializes a Slapi_Value structure from the berval structure.
slapi_value_init_string()
Initializes a Slapi_Value structure from a string.
slapi_value_init_string_passin()
Initializes a Slapi_Value structure with a value contained in a string.
slapi_value_new()
Allocates a new Slapi_Value structure.
slapi_value_new_berval()
Allocates a new Slapi_Value structure from a berval structure.
slapi_value_new_string()
Allocates a new Slapi_Value structure from a string.
slapi_value_new_string_passin()
Allocates a new Slapi_Value structure and initializes it from a string.
slapi_value_new_value()
Allocates a new Slapi_Value from another Slapi_Value structure.
slapi_value_set()
Sets the value.
slapi_value_set_berval()
Copies the value from a berval structure into a Slapi_Value structure.
slapi_value_set_int()
Sets the integer value of a Slapi_Value structure.
slapi_value_set_string()
Copies a string into the value.
slapi_value_set_string_passin()
Sets the value.
slapi_value_set_value()
Copies the value of a Slapi_Value structure into another Slapi_Value structure.

slapi_value_compare()

Compares two values for a given attribute to determine if they are equals.

Syntax 

#include "slapi-plugin.h"

slapi_value_compare(const Slapi_Attr *a,

  const Slapi_Value *v1, const Slapi_Value *v2);

Parameters

This function takes the following parameters: 

a
A pointer to an attribute used to determine how the two values will be compared.
 
v1
Pointer to the Slapi_Value structure containing the first value to compare.
 
v2
Pointer to the Slapi_Value structure containing the second value to compare.

Returns

This function returns one of the following values:

Description

This function compares two Slapi_Values using the matching rule associated to the attribute a.

This function replaces the deprecated slapi_attr_value_cmp() function used in previous releases and uses the Slapi_Value attribute values instead of the berval attribute values.

slapi_value_dup()

Duplicates a value.

Syntax 

#include "slapi-plugin.h"

slapi_value_dup(const Slapi_Value *v);

Parameters

This function takes the following parameter: 

v
Pointer to the Slapi_Value structure you wish to duplicate.

Returns

This function returns a pointer to a newly allocated Slapi_Value.

Memory Concerns

The new Slapi_Value is allocated and needs to be freed by the caller, using slapi_value_free().

See Also 

slapi_value_free()

slapi_value_free()

Frees the specified Slapi_Value structure and its members from memory.

Syntax 

#include "slapi-plugin.h"

slapi_value_free(Slapi_Value **value);

Parameters

This function takes the following parameter: 

value
Address of the pointer to the Slapi_Value you wish to free.

Description

This function frees the Slapi_Value structure and its members (if it is not NULL), and sets the pointer to NULL.

Memory Concerns

Call this function when you are finished working with the structure.

slapi_value_get_berval()

Gets the berval structure of the value.

Syntax 

#include "slapi-plugin.h"

slapi_value_get_berval( const Slapi_Value *value );

Parameters

This function takes the following parameter: 

value
Pointer to the Slapi_Value of which you wish to get the berval.

Returns

This function returns a pointer to the berval structure contained in the Slapi_Value. This function returns a pointer to the actual berval structure, not a copy of it.

Memory Concerns

You should not free the berval structure unless you plan to replace it by calling slapi_value_set_berval().

See Also 

slapi_value_set_berval()

slapi_value_get_int()

Converts the value to an integer.

Syntax 

#include "slapi-plugin.h"

int slapi_value_get_int(const Slapi_Value *value);

Parameters

This function takes the following parameter: 

value
Pointer to the Slapi_Value that you want to get as an integer.

Returns

This function returns one of the following values:

Description

Converts the value in the Slapi_Value to an integer.

See Also 

slapi_value_get_long()
 
slapi_value_get_uint()

slapi_value_get_length()

Gets the actual length of the value.

Syntax 

#include "slapi-plugin.h"

size_t slapi_value_get_length(const Slapi_Value *value);

Parameters

This function takes the following parameter: 

value
Pointer to the Slapi_Value of which you wish to get the length.

Returns

This function returns one of the following values:

Description

This function returns the actual length of a value contained in the Slapi_Value structure.

slapi_value_get_long()

Converts the value into a long integer.

Syntax 

#include "slapi-plugin.h"

long slapi_value_get_long(const Slapi_Value *value);

Parameters

This function takes the following parameter: 

value
Pointer to the Slapi_Value that you wish to get as a long integer.

Returns

This function returns one of the following values:

Description

This function converts the value contained in the Slapi_Value structure into a long integer.

See Also 

slapi_value_get_int()
 
slapi_value_get_ulong()
 
slapi_value_get_uint()

slapi_value_get_string()

Returns the value as a string.

Syntax 

#include "slapi-plugin.h"

const char*slapi_value_get_string(const Slapi_Value *value);

Parameters

This function takes the following parameter: 

value
Pointer to the value you wish to get as a string.

Returns

This function returns one of the following values:

Memory Concerns

You should not free the string unless to plan to replace it by calling slapi_value_set_string().

See Also 

slapi_value_set_string()

slapi_value_get_uint()

Converts the value to an unsigned integer.

Syntax 

#include "slapi-plugin.h"

unsigned int slapi_value_get_uint(const Slapi_Value *value);

Parameters

This function takes the following parameter: 

value
Pointer to the value that you wish to get as an unsigned integer.

Returns

This function returns one of the following values:

Description

Converts the value contained in Slapi_Value into an unsigned integer.

See Also 

slapi_value_get_int()
 
slapi_value_get_long()
 
slapi_value_get_ulong()

slapi_value_get_ulong()

Converts the value into an unsigned long.

Syntax 

#include "slapi-plugin.h"

unsigned long slapi_value_get_ulong(const Slapi_Value *value);

Parameters

This function takes the following parameter: 

value
Pointer to the value that you wish to get as an unsigned integer.

Returns

This function returns one of the following values:

Description

Converts the value contained in the Slapi_Value structure into an unsigned long integer.

See Also 

slapi_value_get_int()
 
slapi_value_get_long()
 
slapi_value_get_uint()

slapi_value_init()

Initializes a Slapi_Value structure with no value.

Syntax 

#include "slapi-plugin.h"

slapi_value_init(Slapi_Value *v);

Parameters

This function takes the following parameter: 

v
Pointer to the value to be initialized. The pointer must not be NULL.

Returns

This function returns a pointer to the initialized Slapi_Value structure (itself).

Description

This function initializes the Slapi_Value structure, resetting all of its fields to zero. The value passed as the parameter must be a valid Slapi_Value.

slapi_value_init_berval()

Initializes a Slapi_Value structure from the berval structure.

Syntax 

#include "slapi-plugin.h"

slapi_value_init_berval(Slapi_Value *v, struct berval *bval);

Parameters

This function takes the following parameters: 

v
Pointer to the value to initialize. The pointer must not be NULL.
 
bval
Pointer to the berval structure to be used to initialize the value.

Returns

This function returns a pointer to the initialized Slapi_Value structure (itself).

Description

This function initializes the Slapi_Value structure with the value contained in the berval structure. The content of the berval structure is duplicated.

slapi_value_init_string()

Initializes a Slapi_Value structure from a string.

Syntax 

#include "slapi-plugin.h"

slapi_value_init_string(Slapi_Value *v,const char *s);

Parameters

This function takes the following parameters: 

v
Pointer to the value to be initialized. The pointer must not be NULL.
 
s
A null-terminated string used to initialize the value.

Returns

This function returns a pointer to the initialized Slapi_Value structure (itself).

Description

This function initializes the Slapi_Value structure with the value contained in the string. The string is duplicated.

slapi_value_init_string_passin()

Initializes a Slapi_Value structure with value contained in the string.

Syntax 

#include "slapi-plugin.h"

Slapi_Value * slapi_value_init_string_passin (Slapi_value *v,

  char *s);

Parameters

This function takes the following parameters: 

v
Pointer to the value to initialize. The pointer must not be NULL.
 
s
A null-terminated string used to initialize the value.

Returns

This function returns a pointer to the initialized Slapi_Value structure (itself).

Description

This function initializes a Slapi_Value structure with the value contained in the string. The string is not duplicated and must be freed.

Memory Concerns

The string will be freed when the Slapi_Value structure is freed from memory by calling slapi_value_free().

See Also 

slapi_value_free()
 
slapi_value_new_string_passin()
 
slapi_value_set_string_passin()

slapi_value_new()

Allocates a new Slapi_Value structure.

Syntax 

#include "slapi-plugin.h"

slapi_value_new();

Parameters

This function does not take any parameters.

Returns

This function returns a pointer to the newly allocated Slapi_Value structure. If space cannot be allocated (for example, if no more virtual memory exists), the slapd program terminates.

Description

This function returns an empty Slapi_Value structure. You can call other functions of the API to set the value.

Memory Concerns

When you are no longer using the value, free it from memory by calling slapi_value_free().

See Also 

slapi_value_dup()
 
slapi_value_free()
 
slapi_value_new_berval()

slapi_value_new_berval()

Allocates a new Slapi_Value structure and initializes it from a berval structure.

Syntax 

#include "slapi-plugin.h"

slapi_value_new_berval(const struct berval *bval);

Parameters

This function takes the following parameter: 

bval
Pointer to the berval structure used to initialize the newly allocated Slapi_Value.

Returns

This function returns a pointer to the newly allocated Slapi_Value. If space cannot be allocated (for example, if no more virtual memory exists), the slapd program will terminate.

Description

This function returns a Slapi_Value structure containing a value duplicated from the berval structure passed as the parameter.

Memory Concerns

When you are no longer using the value, you should free it from memory by calling slapi_value_free().

See Also 

slapi_value_new()
 
slapi_value_dup()
 
slapi_value_free()
 
slapi_value_new_string()

slapi_value_new_string()

Allocates a new Slapi_Value structure and initializes it from a string.

Syntax 

#include "slapi-plugin.h"

slapi_value_new_string(const char *s);

Parameters

This function takes the following parameter: 

s
A null-terminated string used to initialize the newly-allocated Slapi_Value.

Returns

This function returns a pointer to the newly allocated Slapi_Value. If space cannot be allocated (for example, if no more virtual memory exists), the slapd program will terminate.

Description

This function returns a Slapi_Value structure containing a value duplicated from the string passed as the parameter.

Memory Concerns

When you are no longer using the value, you should free it from memory by calling slapi_value_free().

See Also 

slapi_value_new()
 
slapi_value_new_berval()
 
slapi_value_free()
 
slapi_value_dup()

slapi_value_new_string_passin()

Allocates a new Slapi_Value structure and initializes it from a string.

Syntax 

#include "slapi-plugin.h"

Slapi_Value * slapi_value_new_string_passin ( char *s );

Parameters

This function takes the following parameter: 

s
A null-terminated string used to initialize the newly-allocated Slapi_Value structure.

Returns

This function returns a pointer to a newly allocated Slapi_Value structure. If space cannot be allocated (for example, if no virtual memory exists), the slapd program terminates.

Description

This function returns a Slapi_Value structure containing the string passed as the parameter. The string passed in must not be freed from memory.

Memory Concerns

The value should be freed by the caller, using slapi_value_free().

See Also 

slapi_value_free()
 
slapi_value_dup()
 
slapi_value_new()

slapi_value_new_value()

Allocates a new Slapi_Value structure and initializes it from another Slapi_Value structure.

Syntax 

#include "slapi-plugin.h"

slapi_value_new_value(const Slapi_Value *v);

Parameters

This function takes the following parameter: 

v
Pointer to the Slapi_Value structure used to initialize the newly allocated Slapi_Value.

Returns

This function returns a pointer to the newly allocated Slapi_Value. If space cannot be allocated (for example, if no more virtual memory exists), the slapd program will terminate.

Description

This function returns a Slapi_Value structure containing a value duplicated from the Slapi_Value structure passed as the parameter. This function is identical to slapi_value_dup().

Memory Concerns

When you are no longer using the value, you should free it from memory by calling the slapi_value_free() function.

See Also 

slapi_value_dup()
 
slapi_value_free()

slapi_value_set()

Sets the value in a Slapi_Value structure.

Syntax 

#include "slapi-plugin.h"

slapi_value_set( Slapi_Value *value, void *val, unsigned long len);

Parameters

This function takes the following parameters: 

value
Pointer to the Slapi_Value in which to set the value.
 
val
Pointer to the value.
 
len
Length of the value.

Returns

This function returns a pointer to the Slapi_Value with the valueset.

Description

This function sets the value in the Slapi_Value structure. The value is a duplicate of the data pointed to by val and of the length len.

Memory Concerns

If the pointer to the Slapi_Value structure is NULL, then nothing is done, and the function returns NULL. If the Slapi_Value structure already contains a value, it is freed from memory before the new one is set.

When you are no longer using the Slapi_Value structure, you should free it from memory by calling slapi_value_free().

See Also 

slapi_value_free()

slapi_value_set_berval()

Copies the value from a berval structure into a Slapi_Value structure.

Syntax 

#include "slapi-plugin.h"

slapi_value_set_berval( Slapi_Value *value,

  const struct berval *bval );

Parameters

This function takes the following parameters: 

value
Pointer to the Slapi_Value structure in which to set the value.
 
bval
Pointer to the berval value to be copied.

Returns

This function returns one of the following values:

Description

This function sets the value of Slapi_Value structure. The value is duplicated from the berval structure bval.

Memory Concerns

If the pointer to the Slapi_Value structure is NULL, nothing is done, and the function returns NULL. If the Slapi_Value already contains a value, it is freed from memory before the new one is set.

When you are no longer using the Slapi_Value structure, you should free it from memory by calling slapi_value_free().

See Also 

slapi_value_free()

slapi_value_set_int()

Sets the integer value of a Slapi_Value structure.

Syntax 

#include "slapi-plugin.h"

slapi_value_set_int(Slapi_Value *value, int intVal);

Parameters

This function takes the following parameters: 

value
Pointer to the Slapi_Value structure in which to set the integer value.
 
intVal
The integer containing the value to set.

Returns

This function returns one of the following values:

Description

This function sets the value of the Slapi_Value structure from the integer intVal.

Memory Concerns

If the pointer to the Slapi_Value structure is NULL, nothing is done, and the function returns -1. If the Slapi_Value already contains a value, it is freed from memory before the new one is set.

When you are no longer using the Slapi_Value structure, you should free it from memory by calling slapi_value_free().

See Also 

slapi_value_free()

slapi_value_set_string()

Copies a string in the value of a Slapi_Value structure.

Syntax 

#include "slapi-plugin.h"

slapi_value_set_string(Slapi_Value *value, const char *strVal);

Parameters

This function takes the following parameters: 

value
Pointer to the Slapi_Value structure in which to set the value.
 
strVal
The string containing the value to set.

Returns

This function returns one of the following:

Description

This function sets the value of the Slapi_Value structure by duplicating the string strVal.

Memory Concerns

If the pointer to the Slapi_Value is NULL, nothing is done, and the function returns -1. If the Slapi_Value already contains a value, it is freed from memory before the new one is set.

When you are no longer using the Slapi_Value structure, you should free it from memory by calling slapi_value_free().

See Also 

slapi_value_free()

slapi_value_set_string_passin()

Sets the value of a Slapi_Value structure from a string.

Syntax 

#include "slapi-plugin.h"

int slapi_value_set_string_passin ( Slapi_Value *value, char 
  *strVal);

Parameters

This function takes the following parameters: 

value
Pointer to the Slapi_Value structure into which the value will be set.
 
strVal
The string containing the value to set.

Returns

This function returns one of the following values:

Description

This function sets the value of Slapi_Value structure with the string strVal. If the Slapi_Value structure already contains a value, it is freed from memory before the new one is set. The string strVal must not be freed from memory.

Memory Concerns

Use slapi_value_free() when you are finished working with the structure to free it from memory.

slapi_value_set_value()

Copies the value of a Slapi_Value structure into a Slapi_Value structure.

Syntax 

#include "slapi-plugin.h"

slapi_value_set_value( Slapi_Value *value,

  const Slapi_Value *vfrom);

Parameters

This function takes the following parameters: 

value
Pointer to the Slapi_Value in which to set the value.
 
vfrom
Pointer to the Slapi_Value from which to get the value.

Returns

This function returns one of the following values:

Description

This function sets the value of the Slapi_Value structure. This value is duplicated from the Slapi_Value structure vfrom. vfrom must not be NULL.

Memory Concerns

If the pointer to the Slapi_Value is NULL, nothing is done, and the function returns NULL. If the Slapi_Value already contains a value, it is freed from before the new one is set.

When you are no longer using the Slapi_Value structure, you should free it from memory by calling slapi_value_free().

See Also 

slapi_value_free()

Functions for Handling Valueset

This section contains reference information on valueset routines.

Table 15-29 Valueset Routines  
Function
Description
slapi_valueset_add_value()
Adds a Slapi_Value in the Slapi_ValueSet structure.
slapi_valueset_add_value_ext()
Enables adding of a Slapi_Value in the Slapi_ValueSet structure without having to duplicate and free the target value.
slapi_valueset_count()
Returns the number of values contained in a Slapi_ValueSet structure.
slapi_valueset_done()
Frees the values contained in the Slapi_ValueSet structure.
slapi_valueset_find()
Finds the value in a valueset using the syntax of an attribute.
slapi_valueset_first_value()
Gets the first value of a Slapi_ValueSet structure.
slapi_valueset_free()
Frees the specified Slapi_ValueSet structure and its members from memory.
slapi_valueset_init()
Resets a Slapi_ValueSet structure to no values.
slapi_valueset_new()
Allocates a new Slapi_ValueSet structure.
slapi_valueset_next_value()
Gets the next value from a Slapi_ValueSet structure.
slapi_valueset_set_from_smod()
Copies the values of Slapi_Mod structure into a Slapi_ValueSet structure.
slapi_valueset_set_valueset()
Initializes a Slapi_ValueSet structure from another Slapi_ValueSet structure.

slapi_valueset_add_value()

Adds a Slapi_Value in the Slapi_ValueSet structure.

Syntax 

#include "slapi-plugin.h"

void slapi_valueset_add_value(Slapi_ValueSet *vs,

  const Slapi_Value *addval);

Parameters

This function takes the following parameters: 

vs
Pointer to the Slapi_ValueSet structure to which to add the value.
 
addval
Pointer to the Slapi_Value to add to the Slapi_ValueSet.

Description

This function adds a value in the form of a Slapi_Value structure in a Slapi_ValueSet structure.

Memory Concerns

The value is duplicated from the Slapi_Value structure, which can be freed from memory after using it without altering the Slapi_ValueSet structure.

This function does not verify if the value is already present in the Slapi_ValueSet structure. You can manually check this using slapi_valueset_first_value() and slapi_valueset_next_value().

See Also 

slapi_valueset_first_value()
 
slapi_valueset_next_value()

slapi_valueset_add_value_ext()

Enables adding of a Slapi_Value in the Slapi_ValueSet structure without having to duplicate and free the target value.

Syntax 

#include "slapi-plugin.h"

void slapi_valueset_add_value_ext(Slapi_ValueSet *vs, 

  Slapi_Value *addval, unsigned long flags);

Parameters

This function takes the following parameters: 

vs
Pointer to the Slapi_ValueSet structure to which to add the value.
 
addval
Pointer to the Slapi_Value to add to the Slapi_ValueSet.
 
flags
If SLAPI_VALUE_FLAG_PASSIN bit is set in the flags, the function would take over the ownership of the new value to be added without duplicating it.

Description

Sometimes, it is desirable to have a pass-in interface to add a Slapi_Value to a list without having to duplicate and free the target value. This function is similar to an existing function slapi_valueset_add_value() but has one more parameter, unsigned long flags, for setting flags. If SLAPI_VALUE_FLAG_PASSIN bit is set in the flags, the function would simply take over the ownership of the new value to be added without duplicating it.

See Also 

slapi_valueset_add_value()
 
slapi_valueset_first_value()
 
slapi_valueset_next_value()

slapi_valueset_count()

Returns the number of values contained in a Slapi_ValueSet structure.

Syntax 

#include "slapi-plugin.h"

int slapi_valueset_count( const Slapi_ValueSet *vs);

Parameters

This function takes the following parameter: 

vs
Pointer to the Slap_ValueSet structure of which you wish to get the count.

Returns

This function returns the number of values contained in the Slapi_ValueSet structure.

slapi_valueset_done()

Frees the values contained in the Slapi_ValueSet structure.

Syntax 

#include "slapi-plugin.h"

void slapi_valueset_done(Slapi_ValueSet *vs);

Parameters

This function takes the following parameter: 

vs
Pointer to the Slapi_ValueSet structure from which you wish to free its values.

Memory Concerns

Use this function when you are no longer using the values but you want to re-use the Slapi_ValueSet structure for a new set of values.

slapi_valueset_find()

Finds the value in a valueset using the syntax of an attribute.

Syntax 

#include "slapi-plugin.h"

Slapi_Value *slapi_valueset_find(const Slapi_Attr *a,

  const Slapi_ValueSet *vs, const Slapi_Value *v);

Parameters

This function takes the following parameters: 

a
Pointer to the attribute. This is used to determine the syntax of the values and how to match them.
 
vs
Pointer to the Slapi_ValueSet structure from which you wish to get the value.
 
v
Address of the pointer to the Slapi_Value structure for the returned value.

Returns

This function returns one of the following values:

Description

Use this function to check for duplicate values in an attribute.

slapi_valueset_first_value()

Gets the first value of a Slapi_ValueSet structure.

Syntax 

#include "slapi-plugin.h"

int slapi_valueset_first_value( Slapi_ValueSet *vs,

  Slapi_Value **v );

Parameters

This function takes the following parameters: 

vs
Pointer to the Slapi_ValueSet structure from which you wish to get the value.
 
v
Address of the pointer to the Slapi_Value structure for the returned value.

Returns

This function returns one of the following values:

Description

Call this function when you wish to get the first value of a Slapi_ValueSet or you wish to iterate through all of the values. The returned value is the index of the value in the Slapi_ValueSet structure and must be passed to call slapi_valueset_next_value() to get the next value.

Memory Concerns

This function gives a pointer to the actual value within the Slapi_ValueSet. You should not free it from memory.

See Also 

slapi_valueset_next_value()

slapi_valueset_free()

Frees the specified Slapi_ValueSet structure and its members from memory.

Syntax 

#include "slapi-plugin.h"

void slapi_valueset_free(Slapi_ValueSet *vs)

Parameters

This function takes the following parameter: 

vs
Pointer to the Slapi_ValueSet to free.

Description

This function frees the Slapi_ValueSet structure and its members if it is not NULL. Call this function when you are done working with the structure.

See Also 

slapi_valueset_done()

slapi_valueset_init()

Resets a Slapi_ValueSet structure to no values.

Syntax 

#include "slapi-plugin.h"

void slapi_valueset_init(Slapi_ValueSet *vs);

Parameters

This function takes the following parameter: 

vs
Pointer to the Slapi_ValueSet to replace.

Description

This function returns the values contained in the Slapi_ValueSet structure (sets them to 0). This does not free the values contained in the structure. To free the values, use slapi_valueset_done().

Memory Concerns

When you are no longer using the Slapi_ValueSet structure, you should free it from memory by using slapi_valueset_free().

See Also 

slapi_valueset_done()
 
slapi_valueset_free()

slapi_valueset_new()

Allocates a new Slapi_ValueSet structure.

Syntax 

#include "slapi-plugin.h"

Slapi_ValueSet *slapi_valueset_new( void );

Parameters

This function takes no parameters.

Returns

This function returns a a pointer to the newly allocated Slapi_ValueSet structure. If no space could be allocated (for example, if no more virtual memory exists), the slapd program terminates.

Description

This function returns an empty Slapi_ValueSet structure. You can call other slapi_valuset functions of the API to set the values in the Slapi_ValueSet structure.

Memory Concerns

When you are no longer using the value, you should free it from memory by calling slapi_valueset_free().

See Also 

slapi_valueset_free()

slapi_valueset_next_value()

Gets the next value from a Slapi_ValueSet structure.

Syntax 

#include "slapi-plugin.h"

int slapi_valueset_next_value( Slapi_ValueSet *vs,

  int index, Slapi_Value **v);

Parameters

This function takes the following parameters: 

vs
Pointer to the Slapi_ValueSet structure from which you wish to get the value.
 
index
Value returned by the previous call to slapi_valueset_next_value or slapi_value_first_value().
 
v
Address to the pointer to the Slapi_Value structure for the returned value.

Returns

This function returns one of the following values:

Description

Call this function when you wish to get the next value of a Slapi_ValueSet, after having first called slapi_valueset_first_value(). The returned value is the index of the value in the Slapi_ValueSet structure and must be passed to slapi_valueset_next_value().

Memory Concerns

This function gives a pointer to the actual value within the Slapi_ValueSet and you should not free it from memory.

See Also 

slapi_valueset_first_value()

slapi_valueset_set_from_smod()

Copies the values of Slapi_Mod structure into a Slapi_ValueSet structure.

Syntax 

#include "slapi-plugin.h"

void slapi_valueset_set_from_smod(Slapi_ValueSet *vs,

  Slapi_Mod *smod);

Parameters

This function takes the following parameters: 

vs
Pointer to the Slapi_ValueSet structure into which you wish to copy the values.
 
smod
Pointer to the Slapi_Mod structure from which you wish to copy the values.

Description

This function copies all of the values contained in a Slapi_Mod structure into a Slapi_ValueSet structure.

Memory Concerns

This function does not verify that the Slapi_ValueSet structure already contains values, so it is your responsibility to verify that there are no values prior to calling this function. If you do not verify this, the allocated memory space will leak. You can free existing values by calling slapi_valueset_done().

See Also 

slapi_valueset_done()

slapi_valueset_set_valueset()

Initializes a Slapi_ValueSet structure from another Slapi_ValueSet structure.

Syntax 

#include "slapi-plugin.h"

void slapi_valueset_set_valueset(Slapi_ValueSet *vs1,

  const Slapi_ValueSet *vs2);

Parameters

This function takes the following parameters: 

vs1
Pointer to the Slapi_ValueSet structure to which you wish to set the values.
 
vs2
Pointer to the Slapi_ValueSet structure from which you wish to copy the values.

Description

This function initializes a Slapi_ValueSet structure by copying the values contained in another Slapi_ValueSet structure.

Memory Concerns

The function does not verify that the Slapi_ValueSet structure contains values, so it is your responsibility to verify that there are no values prior to calling this function. If you do not verify this, the allocated memory space will leak. You can free existing values by calling slapi_valueset_done().

See Also 

slapi_valueset_done()

Functions Specific to Virtual Attribute Service

This section contains reference information on routines that are specific to virtual attribute services.

Table 15-30 Virtual Attribute Service Routines  
Function
Description
slapi_vattr_list_attrs()
Returns all the attribute types, both real and virtual, from an entry.
slapi_vattr_attrs_free()
Frees the attribute list returned by slapi_vattr_list_attrs().
slapi_vattr_schema_check_type()
Performs a schema check on the attribute types in the entry.
slapi_vattr_value_compare()
Compares the attribute and the name in a given entry.
slapi_vattr_values_free()
Frees the attribute value and name in a given entry.
slapi_vattr_values_get()
Returns the values of a virtual attribute for the given an entry and the attribute-type name.
slapi_vattr_values_get_ex()
Returns the values for an attribute type from an entry.
slapi_vattr_values_type_thang_get()
Gets values for an attribute type in the list only if the results field for that attribute type is NULL.

slapi_vattr_list_attrs()

Returns all the attribute types, both real and virtual, from an entry.

You can call slapi_vattr_values_type_thang_get() and take the values present in the vattr_type_thang list rather than calling slapi_vattr_values_get() to retrieve the value.

Syntax 

#include "slapi-plugin.h"

int slapi_vattr_list_attrs

   Slapi_Entry *e, vattr_type_thang **types, int flags, 

   int *buffer_flags);

Parameters

This function takes the following parameters: 

e
The entry of interest.
 
types
Pointer to receive the list.
 
flags
Bit mask of options. Valid values include:
SLAPI_VIRTUALATTRS_REQUEST_POINTERS
SLAPI_VIRTUALATTRS_ONLY
SLAPI_REALATTRS_ONLY
 
buffer_flags
Bit mask of options. Valid values include:
SLAPI_VIRTUALATTRS_RETURNED_COPIES
SLAPI_VIRTUALATTRS_RETURNED_POINTERS
SLAPI_VIRTUALATTRS_REALATTRS_ONLY

Memory Concerns

The list that is returned from this API should be freed by the user by calling slapi_vattr_attrs_free() for that list.

Description

This function should be used to return both the real and virtual attributes for an entry.

See Also 

slapi_vattr_values_type_thang_get()
 
slapi_vattr_values_free()

slapi_vattr_attrs_free()

Frees the attribute list returned by slapi_vattr_list_attrs().

Syntax 

#include "slapi-plugin.h"

void slapi_vattr_attrs_free(vattr_type_thang **types,

  int flags);

Parameters

This function takes the following parameters: 

types
Pointer to the list of attributes to be freed.
 
flags
Bit mask of options. Valid value is as follows:
SLAPI_VIRTUALATTRS_RETURNED_POINTERS

Description

This function should be used to free the list of attributes returned from slapi_vattrspi_add_type().

Memory Concerns

Free the pointer block using slapi_ch_free().

See Also 

slapi_vattr_list_attrs()

slapi_vattr_schema_check_type()

Performs a schema check on the attribute types in the entry.

Syntax 

#include "slapi-plugin.h"

int slapi_vattr_schema_check_type(Slapi_Entry *e, char *type);

Parameters

This function takes the following parameters: 

e
The entry to be checked.
 
type
The attribute type in the schema.

Returns

Return 0 if success, -1 if error.

slapi_vattr_value_compare()

Compares attribute type and name in a given entry.

Syntax 

#include "slapi-plugin.h"

int slapi_vattr_value_compare( Slapi_Entry *e, char *type,

  Slapi_Value *test_this, int *result, int flags);

Parameters

This function takes the following parameters: 

e
Entry to be compared.
 
type
Attribute type name.
 
test_this
Value to be tested.
 
result
0 if the compare is true, 1 if the compare is false.
 
flags
Not used. You should pass 0 for this parameter.

Returns

This function returns 0 for success, in which case result contains the result of the comparison. Otherwise, this function returns the following:

Description

There is no need to call slapi_vattr_values_free() after calling this function.

slapi_vattr_values_free()

Frees the valueset and type names.

Syntax 

#include "slapi-plugin.h"

void slapi_vattr_values_free ( Slapi_ValueSet **value, 

  char **actual_type_name, int flags);

Parameters

This function takes the following parameters: 

value
Valueset to be freed.
 
actual_type_name
List of type names.
 
flags
The buffer flags returned from slapi_vattr_values_get_ex(). This contains information that this function needs to determine which objects need to be freed.

Description

This function should be used to free the valueset and type names returned from slapi_vattr_values_get_ex().

See Also 

slapi_vattr_values_get_ex()

slapi_vattr_values_get()

Returns the values of a virtual attribute for the given an entry and the attribute-type name.

Syntax 

int slapi_vattr_values_get

   ( Slapi_Entry *e,    char *type,

   Slapi_ValueSet** results, 

   int *type_name_disposition, 

char **actual_type_name,

   int flags,int *buffer_flags);

Parameters

This function takes the following parameters: 

e
Entry to be compared.
 
type
Attribute type name.
 
results
Pointer to the result set: 0 if the compare is true, 1 if the compare is false.
 
type_name_disposition
Matching result. Valid value is as follows:
SLAPI_VIRTUALATTRS_TYPE_NAME_MATCHED_EXACTLY_OR_ALIAS
 
actual_type_name
Type name as found.
 
flags
Not used. You should pass 0 for this parameter.
 
buffer_flags
Bit mask of options. Valid value is as follows: SLAPI_VIRTUALATTRS_RETURNED_POINTERS

Returns

This function returns 0 for success. Otherwise, this function returns the following:

Memory Concerns

Gets values for an attribute type (vattr_type_thang) in the list.

See Also 

slapi_vattr_values_get_ex()

slapi_vattr_values_get_ex()

Returns the values for an attribute type from an entry.

Syntax 

#include "slapi-plugin.h"

int slapi_vattr_values_get_ex(Slapi_Entry *e, char *type,

  Slapi_ValueSet*** results, int **type_name_disposition, 

  char ***actual_type_name, int flags, int *buffer_flags, 

  int *subtype_count);

Parameters

This function takes the following parameters: 

e
Entry from which to get the values.
 
type
Attribute type name.
 
results
Pointer to result set.
 
type_name_disposition
Matching result.
 
actual_type_name
Type name as found.
 
flags
Bit mask of options. Valid values are as follows:
SLAPI_REALATTRS_ONLY
SLAPI_VIRTURALATTRS_ONLY
SLAPI_VIRTUALATTRS_REQUEST_POINTERS
SLAPI_VIRTUALATTRS_LIST_OPERATIONAL_AT TRS
 
buffer_flags
Bit mask to be used as input flags for slapi_values_free().
 
subtype_count
Number of subtypes matched.

Returns

This function returns 0 for success, in which case:

Otherwise, this function returns the following:

Description

This function returns the values for an attribute type from an entry, including the values for any subtypes of the specified attribute type. The routine will return the values of virtual attributes in that entry if requested to do so.

Memory Concerns

slapi_vattr_values_free() should be used to free the retrurned result set and type names, passing the buffer_flags value returned from this routine.

See Also 

slapi_vattr_values_free()

slapi_vattr_values_type_thang_get()

Gets values for an attribute type in the list only if the results field for that attribute type is NULL.

Syntax 

#include "slapi-plugin.h"

int slapi_vattr_values_type_thang_get

   Slapi_Entry *e,

   vattr_type_thang *type_thang,

   Slapi_ValueSet** results,

   int *type_name_disposition,

   char **actual_type_name,

   int flags,

   int *buffer_flags);

Parameters

This function takes the following parameters: 

e
Entry to be compared.
 
type
Attribute type name.
 
results
Pointer to the result set: 0 if the compare is true, 1 if the compare is false.
 
type_name_disposition
Matching result. Valid value is as follows:
SLAPI_VIRTUALATTRS_TYPE_NAME_MATCHED_EXACTLY_OR_ALIAS
 
actual_type_name
Type name as found.
 
flags
Not used. You should pass 0 for this parameter.
 
buffer_flags
Bit mask of options. Valid value is as follows: SLAPI_VIRTUALATTRS_RETURNED_POINTERS

Description

The slapi_vattr_values_type_thang_get() function is faster for getting the values of an attribute when a vattr_type_thang list is returned from a slapi_vattr_list_types() call. However, when the list for that call returns NULL, the computation becomes similar to slapi_vattr_values_get(). In functionality, slapi_vattr_values_type_thang_get() mimics slapi_vattr_values_get().

See Also 

slapi_vattr_values_get()

Functions for Managing Locks and Synchronization

This section contains reference information on locks and synchronization routines.

Table 15-31 Locks and Synchronization Routines  
Function
Description
slapi_destroy_condvar()
Frees a Slapi_CondVar structure from memory.
slapi_destroy_mutex()
Frees a Slapi_Mutex structure from memory.
slapi_lock_mutex()
Locks the specified mutex.
slapi_new_condvar()
Creates a new condition variable and returns a pointer to the corresponding Slapi_CondVar structure.
slapi_new_mutex()
Creates a new mutex and returns a pointer to the corresponding Slapi_Mutex structure.
slapi_notify_condvar()
Notifies a thread that is waiting on the specified condition variable.
slapi_unlock_mutex()
Unlocks the specified mutex.
slapi_wait_condvar()
Waits on a condition variable.

slapi_destroy_condvar()

Frees a Slapi_CondVar structure from memory.

Syntax 

#include "slapi-plugin.h"

void slapi_destroy_condvar( Slapi_CondVar *cvar );

Parameters

This function takes the following parameters: 

cvar
Pointer to the Slapi_CondVar structure that you want to free from memory.

Description

This function frees a Slapi_CondVer structure from memory. Before calling this function, you should make sure that this condition variable is no longer in use.

slapi_destroy_mutex()

Frees a Slapi_Mutex structure from memory.

Syntax 

#include "slapi-plugin.h"

void slapi_destroy_mutex( Slapi_Mutex *mutex );

Parameters

This function takes the following parameters: 

mutex
Pointer to the Slapi_Mutex structure that you want to free from memory.

Description

This function frees a Slapi_Mutex structure from memory. The calling function must ensure that no thread is currently in a lock-specific function. Locks do not provide self-referential protection against deletion.

slapi_lock_mutex()

Locks the specified mutex.

Syntax 

#include "slapi-plugin.h"

void slapi_lock_mutex( Slapi_Mutex *mutex );

Parameters

This function takes the following parameters: 

mutex
Pointer to a Slapi_Mutex structure representing the mutex that you want to lock.

Description

This function locks the mutex specified by the Slapi_Mutex structure. After this function returns, any other thread that attempts to acquire the same lock is blocked until the holder of the lock releases the lock. Acquiring the lock is not an interruptible operation, nor is there any time-out mechanism.

slapi_new_condvar()

Creates a new condition variable and returns a pointer to the corresponding Slapi_CondVar structure.

Syntax 

#include "slapi-plugin.h"

Slapi_CondVar *slapi_new_condvar( Slapi_Mutex *mutex );

Parameters

This function takes the following parameters: 

mutex
Pointer to an Slapi_Mutex structure representing the mutex that you want used to protect this condition variable.

Returns

This function returns one of the following values:

Description

This function creates a new condition variable and returns a pointer to the Slapi_CondVar structure. You can create the Slapi_Mutex structure by calling the slapi_new_mutex() function.

To wait on the condition variable, call the slapi_wait_condvar() function. To notify waiting threads, call the slapi_notify_condvar() function.

When you are done working with this Slapi_CondVar structure, call the slapi_destroy_condvar() function to free the structure from memory.

slapi_new_mutex()

Creates a new mutex and returns a pointer to the corresponding Slapi_Mutex structure.

Syntax 

#include "slapi-plugin.h"

Slapi_Mutex *slapi_new_mutex();

Returns

This function returns one of the following values:

Description

This function creates a new mutex and returns a pointer to the Slapi_Mutex structure. You can lock this mutex by calling the slapi_pblock_destroy() function and unlock the mutex by calling the slapi_unlock_mutex() function.

When you are done working with the mutex, you can free the Slapi_Mutex structure by calling the slapi_destroy_mutex() function.

slapi_notify_condvar()

Notifies a thread that is waiting on the specified condition variable.

Syntax 

#include "slapi-plugin.h"

int slapi_notify_condvar( Slapi_CondVar *cvar, int notify_all );

Parameters

This function takes the following parameters: 

cvar
Pointer to an Slapi_CondVar structure representing the condition variable. 
notify_all
If 1, notifies all threads that are waiting on the condition variable.

Returns

This function returns one of the following values:

Description

This function notifies one or all threads that are waiting on the condition variable (see the slapi_wait_condvar() function). Before calling this function, the calling thread must lock the mutex associated with this condition variable.

slapi_unlock_mutex()

Unlocks the specified mutex.

Syntax 

#include "slapi-plugin.h"

int slapi_unlock_mutex( Slapi_Mutex *mutex );

Parameters

This function takes the following parameters: 

mutex
Pointer to an Slapi_Mutex structure representing the mutex that you want to unlock.

Returns

This function returns one of the following values:

Description

This function unlocks the mutex specified by the Slapi_Mutex structure.

slapi_wait_condvar()

Waits on a condition variable.

Syntax 

#include "slapi-plugin.h"

int slapi_wait_condvar( Slapi_CondVar *cvar, 

  struct timeval *timeout );

Parameters

This function takes the following parameters: 

cvar
Pointer to an Slapi_CondVar structure representing the condition variable on which you want to wait. 
timeout
Time period to wait for notification on the condition variable. If NULL, the calling function blocks indefinitely.

Returns

This function returns one of the following values:

Description

This function waits on the condition variable until it receives notification; see the slapi_notify_condvar() function. Before calling this function, the calling thread must lock the mutex associated with this condition variable.

Functions for Managing Computed Attributes

This section contains reference information on computed-attribute routines.

Table 15-32 Routines for Computed Attributes  
Function
Description
slapi_compute_add_evaluator()
Registers a function as an evaluator that the server will call to generate a computed attribute.
slapi_compute_add_search_rewriter()
Registers callbacks for filter and search rewriting.
compute_rewrite_search_filter()
Call evaluator functions to see if there is a match with a search filter.

slapi_compute_add_evaluator()

Registers the specified function as an evaluator that the server will call to generate a computed attribute.

Syntax 

#include "slapi-plugin.h"

int slapi_compute_add_evaluator( slapi_compute_callback_t function);

Parameters

This function takes the following parameter: 

function
Function registered by the plug-in that will be used in evaluating the computed attributes.

Returns

This function returns one of the following values:

Description

The slapi_compute_add_evaluator() function registers a function of the slapi_compute_callback_t type as an evaluator of computed attributes.

Before the server sends an entry as a search result back to the client, the server determines if any of the requested attributes are computed attributes and generates the values for those attributes.

To do this, the server calls each registered evaluator function for each individually requested attribute. An evaluator function has the type slapi_compute_callback_t. If you want to set up the server to generate the value of a computed attribute and send the attribute back with each entry, you can define an evaluator function and register the function with the server by calling the slapi_compute_add_evaluator() function.

slapi_compute_add_search_rewriter()

Register callbacks for rewriting search filters.

Syntax 

#include "slapi-plugin.h"

int slapi_compute_add_search_rewriter

   (slapi_search_rewrite_callback_t function);

Parameters

This function takes the following parameter: 

function
Function registered by the plug-in to rewrite the search filters.

Returns

This function returns one of the following values:

Description

The slapi_compute_add_search_rewriter() function registers callback functions for filter searching and rewriting.

compute_rewrite_search_filter()

Calls evaluator functions to see if there is a match with a search filter.

Syntax 

#include "slapi-plugin.h"

int compute_rewrite_search_filter

   (Slapi_PBlock *pb);

Parameters

This function takes the following parameter: 

pb
Parameter block that matches the rewrite search filter.

Returns

This function returns one of the following values:

Description

This function calls evaluator functions to see if there is a match with a search filter. Before the server sends an entry as a search result back to the client, the server determines if any of the requested attributes are computed attributes and generates the values for those attributes.

See Also 

slapi_compute_add_evaluator()

Functions for Manipulating Bits

This section contains reference information on routines for manipulating bits.

Table 15-33 Bit Manipulator Routines  
Function
Description
slapi_isbitset_int()
Checks whether a particular bit is set in an integer.
slapi_isbitset_uchar()
Checks whether a particular bit is set in a character.
slapi_setbit_int()
Sets the specified bit in an integer.
slapi_setbit_uchar()
Sets the specified bit in a character.
slapi_unsetbit_int()
Unsets the specified bit in an integer.
slapi_unsetbit_uchar()
Unsets the specified bit in a character.

slapi_isbitset_int()

Checks whether a particular bit is set in the specified integer.

Syntax 

#include "slapi-plugin.h"

int slapi_isbitset_int(unsigned int f,unsigned int bitnum);

Parameters

This function takes the following parameters: 

f
The unsigned integer, a bit of which is to be checked.
 
bitnum
The bit number in the unsigned integer that needs to be checked.

Returns

This function returns one of the following values:

See Also 

slapi_setbit_int()
 
slapi_unsetbit_int()

slapi_isbitset_uchar()

Checks whether a particular bit is set in the specified character.

Syntax 

#include "slapi-plugin.h"

int slapi_isbitset_uchar(unsigned char f,unsigned char bitnum);

Parameters

This function takes the following parameters: 

f
The unsigned character, a bit of which is to be checked.
 
bitnum
The bit number in the unsigned character that needs to be checked.

Returns

This function returns one of the following values:

See Also 

slapi_setbit_uchar()
 
slapi_unsetbit_uchar()

slapi_setbit_int()

Sets the specified bit in an integer.

Syntax 

#include "slapi-plugin.h"

unsigned int slapi_setbit_int(unsigned int f,unsigned int bitnum);

Parameters

This function takes the following parameters: 

f
The integer in which a bit is to be set.
 
bitnum
The bit number that needs to be set in the integer.

Returns

This function returns the integer with the specified bit set.

See Also 

slapi_isbitset_int()
 
slapi_unsetbit_int()

slapi_setbit_uchar()

Sets the specified bit in a character.

Syntax 

#include "slapi-plugin.h"

unsigned char slapi_setbit_uchar(unsigned char f,

  unsigned char bitnum);

Parameters

This function takes the following parameters: 

f
The character in which a bit is to be set.
 
bitnum
The bit number that needs to be set in the character.

Returns

This function returns the character with the specified bit set.

See Also 

slapi_isbitset_uchar()
 
slapi_unsetbit_uchar()

slapi_unsetbit_int()

Unsets the specified bit in an integer.

Syntax 

#include "slapi-plugin.h"

unsigned int slapi_unsetbit_int(unsigned int f,unsigned int bitnum);

Parameters

This function takes the following parameters: 

f
The integer in which a bit is to be unset.
 
bitnum
The bit number that needs to be unset in the integer.

Returns

This function returns the integer with the specified bit unset.

See Also 

slapi_isbitset_int()
 
slapi_setbit_int()

slapi_unsetbit_uchar()

Unsets the specified bit in a character.

Syntax 

#include "slapi-plugin.h"

unsigned char slapi_unsetbit_uchar(unsigned char f,

  unsigned char bitnum);

Parameters

This function takes the following parameters: 

f
The character in which a bit is to be unset.
 
bitnum
The bit number that needs to be unset in the character.

Returns

This function returns the character with the specified bit unset.

See Also 

slapi_isbitset_uchar()
 
slapi_setbit_uchar()

Functions for Registering Object Extensions

This section contains reference information on routines for registering object extensions. This set of functions provides a means for extending core server objects; this functionality is provided so that you can efficiently pass state information between plug-in calls. Typically, a plug-in might register both a pre-operation and post-operation call. It is very convenient for the plug-in to associate its private data with the operation object that is passed through the parameter block.

Table 15-34 Routines for Registering Object Extensions  
Function
Description
slapi_get_object_extension()
Retrieves a pointer to the plug-in extension.
slapi_register_object_extension()
Registers a plug-in's object extension.
slapi_set_object_extension()
Changes a plug-in's object extension.

slapi_get_object_extension()

Retrieves a pointer to the plug-in extension.

Syntax 

#include "slapi-plugin.h"

void *slapi_get_object_extension(int objecttype, void *object,

  int extensionhandle);

Parameters

This function takes the following parameters: 

objecttype
The object type handle that was returned from the slapi_register_object_extension() call.
 
object
A pointer to the core server object from which the extension is to be retrieved.
 
extensionhandle
The extension handle that was returned from the slapi_register_object_extension() call.

Returns

This function returns a pointer to the plug-in's extension.

Description

A plug-in retrieves a pointer to its own extension by calling slapi_get_object_extension with the object from which the extension is to be retrieved. The factory uses objecttype to find the offset into the object where the extension block is stored. The extension handle is then used to find the appropriate extension within the block.

See Also 

slapi_register_object_extension()
 
slapi_set_object_extension()

slapi_register_object_extension()

Registers a plug-in's object extension.

Syntax 

#include "slapi-plugin.h"

int slapi_register_object_extension( const char *pluginname, 

  const char *objectname, 

  slapi_extension_constructor_fnptr constructor,

  slapi_extension_destructor_fnptr destructor, 

  int *objecttype, int *extensionhandle);

Parameters

This function takes the following parameters: 

pluginname
Plug-in name.
 
objectname
The name of the core server object to be extended. Objects that can be extended (possible values for the objectname parameter):
  • SLAPI_EXT_CONNECTION (Connection)
  • SLAPI_EXT_OPERATION (Operation)
  • SLAPI_EXT_ENTRY (Entry)
  • SLAPI_EXT_MTNODE (Mapping Tree Node)
Currently, only Operation and Connection are supported.
 
constructor
The function provided by the plug-in which is to be called when an instance of the core server object is created. This function must allocate some memory and return a pointer to be stored in the extension block on the object.
 
destructor
The function which is called when an instance of an object is destroyed. This function must release any resources acquired by the constructor function.
 
objecttype
Handle to find the offset into the object where the extension block is stored.
 
extensionhandle
Address, which is used to find the extension within the block.

Description

When a plug-in is initialized, it must register its object extensions. It must provide the name of the object to be extended, e.g., Operation, and constructor and destructor functions. These functions are called when the object is constructed and destroyed. The extension functions must allocate some memory and initialize it for its own use. The registration function will fail if any objects have already been created; this is why the registration must happen during plug-in initialization. In return, the plug-in will receive two handles, one for the object type and another one for the object extension; these only have meaning for the slapi_get_object_extension() function.

Returns

This function returns 0 if successful, error code otherwise.

See Also 

slapi_get_object_extension()
 
slapi_set_object_extension()

slapi_set_object_extension()

Changes a plug-in's object extension.

Syntax 

#include "slapi-plugin.h"

void slapi_set_object_extension(int objecttype, void *object,

  int extensionhandle, void *extension);

Parameters

This function takes the following parameters: 

objecttype
Handle to find the offset into the object where the extension block is stored.
 
object
A pointer to the core server object that needs to be changed.
 
extensionhandle
Address for finding the extension within the block.
 
extension
Pointer to the extension block.

Description

This function enables a plug-in to change its extensions.

See Also 

slapi_register_object_extension()
 
slapi_get_object_extension()

Functions Related to Data Interoperability

This section contains reference information on routines that support the data interoperability feature of Directory Server, which is explained in Chapter 13, "Using Data Interoperability Plug-ins." This set of functions allows a custom plug-in to preserve the default behavior of the Directory Server and bypass access control checking.

Table 15-35 Routines Related to Data Interoperability  
Function
Description
slapi_op_reserved()
Allows a plug-in to recognize reserved default operations of the Directory Server.
slapi_operation_set_flag()
Sets a flag for the operation.
slapi_operation_clear_flag()
Clears a flag for the operation.
slapi_is_flag_set()
Determines whether a flag is set in the operation.

slapi_op_reserved()

Allows a plug-in to recognize reserved default operations, such as the base-scope search on the rootdse and the operations on the reserved naming contexts, for handling by the core Directory Server and not by the DIOP plug-in.

Syntax 

#include "slapi-plugin.h"

int slapi_op_reserved(Slapi_PBlock *pb);

Parameter

This function takes the following parameter: 

pb
Parameter block.

Returns

This function returns 0 if the operation is not reserved and a non-zero value if the operation is reserved.

Description

This function allows you to implement a custom DIOP plug-in that does not affect the default behavior of the server. The code snippet below is a sample for a plug-in that handles the LDAP delete operation. The callback for the LDAP delete operation nullsuffix_delete will ignore all the LDAP delete operations on the reserved-naming contexts (such as cn=schema, cn=config, and cn=monitor). 

#define PLUGIN_OPERATION_HANDLED     0

#define PLUGIN_OPERATION_IGNORED        1

static int

nullsuffix_delete( Slapi_PBlock *pb )

{

    if( slapi_op_reserved(pb) ){

         return PLUGIN_OPERATION_IGNORED;

    }

    slapi_log_error( SLAPI_LOG_PLUGIN, PLUGIN_NAME, 
                        "nullsuffix_delete\n" );

    /* do the deletes */

    send_ldap_result( pb, LDAP_SUCCESS, NULL, NULL, 0, NULL );

    return PLUGIN_OPERATION_HANDLED;

}

slapi_operation_set_flag()

Sets the specified flag for the operation.

Syntax 

#include "slapi-plugin.h"

void slapi_operation_set_flag( Slapi_Operation *op, 

    unsigned long flag)

Parameter

This function takes the following parameters: 

op
Operation data structure.
 
flag
Flag to be set. By default, only one flag is supported, the SLAPI_OP_FLAG_NO_ACCESS_CHECK flag, which specifies that access control should not be checked.

Description

The code sample demonstrates how the flag for the operation is to be set: 

Slapi_Operation *op;

if ( slapi_pblock_get( pb, SLAPI_OPERATION, &op ) != 0 ) {

    slapi_operation_set_flag( op, SLAPI_OP_FLAG_NO_ACCESS_CHECK 
);

}

See Also 

slapi_operation_clear_flag()
 
slapi_is_flag_set()

slapi_operation_clear_flag()

Clears the specified flag for the operation.

Syntax 

#include "slapi-plugin.h"

void slapi_operation_clear_flag( Slapi_Operation *op, unsigned long 
flag)

Parameter

This function takes the following parameters: 

op
Operation data structure.
 
flag
Flag to be cleared. By default, only one flag is supported, the SLAPI_OP_FLAG_NO_ACCESS_CHECK flag, which specifies that access control should not be checked.

See Also 

slapi_operation_set_flag()
 
slapi_is_flag_set()

slapi_is_flag_set()

Determines whether the specified flag is set in the operation.

Syntax 

#include "slapi-plugin.h"

int slapi_is_flag_set(Slapi_Operation *op, unsigned long flag)

Parameter

This function takes the following parameters: 

op
Operation data structure.
 
flag
Flag to check. By default, only one flag can be checked, the SLAPI_OP_FLAG_NO_ACCESS_CHECK flag, which specifies that access control should not be checked.

Returns

This function returns 0 if the flag is not set and a non-zero value if the flag is set.

Description

The code sample below demonstrates how ACL checks for internal operations are skipped if the plug-in specifies to not check for access control. 

if (operation_is_flag_set(operation, 
SLAPI_OP_FLAG_NO_ACCESS_CHECK))

                    return LDAP_SUCCESS;

    }

    // Success indicates that access is allowed.

See Also 

slapi_operation_set_flag()
 
slapi_operation_clear_flag()

Functions for Registering Additional Plug-ins

This section contains reference information on interfaces that allow a plug-in to register additional plug-ins.

Table 15-36 Routines for Registering Additional Plug-ins  
Function
Description
slapi_register_plugin()
Allows a plug-in to register a plug-in.

slapi_register_plugin()

Allows plug-in to register a plug-in.

Syntax 

#include "slapi-plugin.h"

int slapi_register_plugin( const char *plugintype,

   int enabled,   const char *initsymbol,

   slapi_plugin_init_fnptr initfunc, 

   const char *name, char **argv,

   void *group_identity);

Parameters

This function takes the following parameters: 

plugintype
Handle to find the offset into the object where the extension block is stored.
 
enabled
A pointer to the core server object that needs to be changed.
 
initsymbol
Address for finding the extension within the block.
 
initfunc
Pointer to the extension block.
 
name
Pointer to the name of the plugin. 
argv
Pointer to an array of the plug-ins.
 
group_identity
Group identity of the plug-ins.

Description

This function allows a plug-in to register a plugin. This was added so that an object plug-in can register all the plug-in interfaces that it supports, including legacy plug-ins.




Previous
 Contents
 Index
 Next
© 2001 Sun Microsystems, Inc. Used by permission. © 2005 Red Hat, Inc. All rights reserved.
Read the Full Copyright and Third-Party Acknowledgments.

 last updated May 26, 2005