Sun Java System Directory Server Enterprise Edition 6.2 Developer's Guide

Chapter 17 Function Reference, Part II

This chapter contains the second part of the reference to the public functions for writing plug-ins. The previous chapter contains the first part of the reference.

Sections in the previous chapter cover plug-in API functions from slapi_access_allowed() to slapi_moddn_get_newdn().

The following sections cover plug-in API functions in alphabetical order from slapi_modify_internal_pb() to slapi_wait_condvar().

Functions Alphabetically, Part 1

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 -1 if the parameter passed is a NULL pointer. Otherwise, it returns 0.

After your code calls this function, the server sets SLAPI_PLUGIN_INTOP_RESULT in the parameter block to the appropriate LDAP result code. You can therefore check SLAPI_PLUGIN_INTOP_RESULT in the parameter block to determine whether an error has occurred.

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_modify_internal_set_pb()

Prepares a parameter block for an internal modify operation.

Syntax

#include "slapi-plugin.h"
int 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 for the internal modify operation

dn

Distinguished Name of the entry to modify

mods

Array of modifications to apply

controls

Array of controls to request for the modify operation

uniqueid

Unique identifier for the entry if using this rather than DN

plugin_identity

Plug-in identifier obtained from SLAPI_PLUGIN_IDENTITY during plug-in initialization

operation_flags

NULL or SLAPI_OP_FLAG_NEVER_CHAIN

Returns

This function returns 0 if successful. Otherwise, it returns an LDAP error code.

Description

This function prepares a parameter block for use with slapi_modify_internal_pb().

Memory Concerns

Allocate the parameter block using slapi_pblock_new() before calling this function.

Directory Server does not free the parameters you passed to this function.

Free the parameter block after calling slapi_modify_internal_pb() .

See Also

slapi_modify_internal_pb()

slapi_pblock_new()

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 -1 if the parameter passed is a NULL pointer. Otherwise, it returns 0.

After your code calls this function, the server sets SLAPI_PLUGIN_INTOP_RESULT in the parameter block to the appropriate LDAP result code. You can therefore check SLAPI_PLUGIN_INTOP_RESULT in the parameter block to determine whether an error has occurred.

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_rename_internal_set_pb() are altered or consumed by this function.

See Also

slapi_rename_internal_set_pb()

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 LDAP_SUCCESS if successful, or an LDAP return code if not successful.

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, 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_mod_values()

slapi_mods_add_modbvps()

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_ldapmod()

slapi_mods_add_mod_values()

slapi_mods_add_modbvps()

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, 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_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, 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_smod()

Appends a Slapi_Mod to a Slapi_Mods structure.

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 a the Slapi_Mod to be appended.

Description

Appends a Slapi_Mod to a Slapi_Mods.

Memory Concerns

Responsibility for the Slapi_Mod 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_mod_values()

slapi_mods_add_modbvps()

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, 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_mod_values()

slapi_mods_add_modbvps()

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:

smods

Pointer to a Slapi_Mods structure.

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 $INSTANCE_PATH/logs/errors for debugging.

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 a pointer to the first LDAPMod in the Slapi_Mods, or NULL if there are no mods.

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 an initialized Slapi_Mods.

smod

Pointer to a Slapi_Mod that used to hold the mod.

Returns

This function returns a pointer to the Slapi_Mod, wrapping the first mod, or NULL if no mod exists.

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_smod()

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:

smods

Pointer to an initialized Slapi_Mods.

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:

smods

Pointer to an initialized Slapi_Mods.

Returns

This function returns 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

A pointer to a an initialized Slapi_Mods.

smod

Pointer to a Slapi_Mod that 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

The number of mods in the 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

Number of modifications to allocate initially.

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. Notice that 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_first_smod()

slapi_mods_get_next_mod()

slapi_mods_get_next_smod()

slapi_mods_insert_at()

Inserts an LDAPMod anywhere in a Slapi_Mods.

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 in Slapi_Mods. Position 0 (zero) refers to the first mod. A position equal to the current number of 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.

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

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 a 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 a Slapi_Mod anywhere in a Slapi_Mods.

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 Slapi_Mod to be inserted.

pos

Position at which to insert the Slapi_Mod . Minimum value is 0. Maximum value is the current number of mods.

Description

This function inserts a Slapi_Mod at a given position in Slapi_Mods. Position 0 (zero) refers to the first mod. A position equal to the current number of 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.

Memory Concerns

Responsibility for the Slapi_Mod is transferred to the Slapi_Mods.

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

slapi_mods_insert_smod_before()

Inserts a Slapi_Mod into a Slapi_Mods structure before the current iterator position.

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 with a valid iterator position.

smod

Pointer to the Slapi_Mod to be inserted.

Description

Inserts a Slapi_Mod 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 Slapi_Mod 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_iterator_backone()

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_first_smod()

slapi_mods_get_next_mod()

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

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_first_smod()

slapi_mods_get_next_mod()

slapi_mods_get_next_smod()

slapi_mods_remove_at()

Removes the mod at the specified Slapi_Mods iterator position.

Syntax

#include "slapi-plugin.h"
void slapi_mods_remove_at(Slapi_Mods *smods, int pos);

Parameters

This function takes the following parameters:

smods

Pointer to an initialized Slapi_Mods.

pos

Position of the mod to remove.

Description

This function removes the mod at the pos iterator position, obtained by counting as you iterate through the modifications in a Slapi_Mods.

See Also

slapi_mods_get_first_mod()

slapi_mods_get_first_smod()

slapi_mods_get_next_mod()

slapi_mods_get_next_smod()

slapi_mr_filter_index()

Call a matching rule filter index function.

Syntax

#include "slapi-plugin.h"
int slapi_mr_filter_index(Slapi_Filter* f, Slapi_PBlock* pb);

Parameters

This function takes the following parameters:

f

Filter containing the matching rule OID

pb

Parameter block to pass to the filter index function

Description

This function enables plug-ins to call matching rule filter index functions.

Returns

This function returns 0 if successful. It returns LDAP_UNAVAILABLE_CRITICAL_EXTENSION if no filter index function is available for the rule in the filter. It returns -1 if something goes horribly wrong setting the parameter block arguments.

slapi_mr_indexer_create()

Set a pointer in the parameter block to the indexer factory function for a matching rule.

Syntax

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

Parameters

This function takes the following parameters:

pb

Parameter block containing the matching rule object identifier affected to SLAPI_PLUGIN_MR_OID

Description

This function enables plug-ins to call matching rule indexer factory functions. If successful, the function sets SLAPI_PLUGIN_MR_INDEXER_CREATE_FN in pb to point to the indexer factory function.

Returns

This function returns 0 if successful. It returns LDAP_UNAVAILABLE_CRITICAL_EXTENSION if no indexer factory function is available for the matching rule. It returns -1 if something goes horribly wrong getting or setting the parameter block arguments.

slapi_new_condvar()

Allocate a condition variable.

Syntax

#include "slapi-plugin.h"
Slapi_CondVar *slapi_new_condvar( Slapi_Mutex *mutex );

Parameters

This function takes the following parameter:

mutex

Mutex used for the lock

Description

This function enables thread synchronization using a wait/notify mechanism.

Returns

This function returns a pointer to the new condition variable if successful. Otherwise, it returns NULL.

Memory Considerations

Call this function to create the condition variable and slapi_destroy_condvar() to free the condition variable.

See Also

slapi_destroy_condvar()

slapi_notify_condvar()

slapi_wait_condvar()

slapi_new_mutex()

Allocate a mutex.

Syntax

#include "slapi-plugin.h"
Slapi_Mutex *slapi_new_mutex( void );

Returns

This function returns a pointer to the new mutex if successful. Otherwise, it returns NULL.

Description

This function enables thread synchronization. Once a thread has locked the mutex using slapi_lock_mutex(), other threads attempting to acquire the lock are blocked until the thread holding the mutex calls slapi_UTF-8STRTOLOWER().

Memory Considerations

Call slapi_destroy_mutex() to free the mutex.

See Also

slapi_destroy_mutex()

slapi_lock_mutex()

slapi_notify_condvar()

Notify a change in a condition variable.

Syntax

#include "slapi-plugin.h"
int slapi_notify_condvar( Slapi_CondVar *cvar, int notify_all );

Parameters

This function takes the following parameter:

cvar

Condition variable changed

notify_all

NULL means notify only the next thread waiting for notification. Otherwise, all threads are notified.

Description

This function enables thread synchronization using a wait/notify mechanism.

Returns

This function returns 1 if successful. Otherwise, it returns NULL.

Memory Considerations

Call slapi_wait_condvar() to wait on a change to the condition variable.

See Also

slapi_destroy_condvar()

slapi_new_condvar()

slapi_wait_condvar()

slapi_op_abandoned()

Determines whether or not 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 periodically check the operations status from 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 will return one of the following operation types:

See Also

slapi_pblock_get()

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

pb

Parameter block that you wish 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 parameter blocks allocated on the stack, with 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 parameter block 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 15, Data Type and Structure 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
                                              references this. */
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 previous example, which sets someparam to NULL after setting it in the parameter block.

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

Pointer to the new parameter block.

Memory Concerns

The parameter block pointer allocated with slapi_pblock_new() must always be freed by slapi_pblock_destroy(). The use of other memory liberators such as 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 15, Data Type and Structure Reference

value

Pointer to the value that you want to set in the parameter block.

Returns

This function returns 0 if successful, or -1 if an error occurs (for example, if an invalid ID is specified).

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 such as char * strings , char **arrays,Slapi_Backend *, and so forth, 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()

slapi_pw_find_sv()

Determines whether a specified password matches one of the hashed 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 to hold the values of an attribute that stores passwords such as userpassword.

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 0 if the password specified by v was found in vals, or a non-zero value if the password v was not found in vals.

Memory Concerns

You must allocate and release an array of Slapi_Value structures for vals sized to hold the exact number of password values for the userpassword attribute on the entry to check. The resulting array is not NULL terminated. For a simpler memory allocation model, use slapi_pw_find_valueset() instead.

Description

When the server stores the password for an entry in the userpassword attribute, it hashes the password using different schemes.

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 hashed values of the userpassword attribute.

See Also

slapi_pw_find_valueset()

slapi_pw_find_valueset()

Determines whether or not a specified password matches one of the hashed 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_valueset(Slapi_Valueset *valset,
    const Slapi_Value *v);

Parameters

This function takes the following parameters:

valset

Pointer to the Slapi_ValueSet structure containing the values of an attribute that stores passwords such as userpassword .

v

Pointer to the Slapi_Value structure containing the password 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 0 if the password specified by v was found in valset, or a non-zero value if the password v was not found in valset.

Description

When the server stores the password for an entry in the userpassword attribute, it hashes the password using different schemes.

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 hashed values of the userpassword attribute.

See Also

slapi_pw_find_sv()

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 0 if rdn1 and rdn2 have the same RDN components, or -1 if they do not.

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 1 if rdn contains an RDN that matches the type, value and length, or 0 if no RDN matches the desired type/value.

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_contains_attr()

slapi_rdn_get_index()

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 1 if rdn contains a RDN that matches the given type, or 0 if there is no match.

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_contains()

slapi_rdn_get_index_attr()

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_done()

slapi_rdn_new()

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 -1 if rdn is empty, or 1 if the operation is successful.

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. A matching RDN value must not exceed the length specified.

Returns

This function returns the index of the RDN that follows the RDN matching the contents of the parameters type and value. If no RDN stored in rdn matches the given type/value pair, -1 is returned.

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_contains()

slapi_rdn_get_index_attr()

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 -1 if there is no RDN that matches the content type, or the real position of the first RDN within RDN that matches the content of type.

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 that 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 -1 if there is no RDN in the index position, or the real position of the retrieved RDN if the operation was successful.

Description

This function gets the type/value pair corresponding to the RDN stored in the next (index+1) position inside rdn. Notice that 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_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 parameter:

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_done()

slapi_rdn_free()

slapi_rdn_new()

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_rdn()

slapi_rdn_init_sdn()

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_DN 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 1 if there is no RDN value present, or 0 if rdn contains a value.

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 TDN 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_rdn()

slapi_rdn_new_sdn()

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

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_dn()

slapi_rdn_new_sdn()

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 1 if the RND is removed from rdn, or 0 if no RDN is removed.

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 1 of the RDN is removed from rdn, or 0 if no RDN is removed.

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 1 if the RDN is removed from rdn, or 0 if no RDN is removed because either rdn is empty, or the index goes beyond the number of RDNs present.

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_rdn()

slapi_rdn_set_sdn()

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 Slapi_RDN structure from which to take the 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_DN structure from which to take the 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()

slapi_rdn_syntax_check()

This function determines whether the value of the RDN complies with attribute syntax rules.

Syntax

#include "slapi-plugin.h"
int slapi_rdn_syntax_check( Slapi_PBlock *pb, const char *rdn );

Parameters

This function takes the following parameters:

pb

Parameter block.

rdn

Value whose compliance is to be checked.

Returns

Returns one of the following values:

Memory Concerns

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

slapi_register_object_extension()

Register an 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

String identifying the plug-in

objectname

Name of the object to extend such as SLAPI_EXT_CONNECTION to add private data to a connection or SLAPI_EXT_OPERATION to add private data to an operation

constructor

Constructor to allocate memory for the object extension and create the extension

destructor

Destructor to free memory used for the object extension

objecttype

Set by the server and used to retrieve the extension

extensionhandle

Set by the server and used to retrieve the extension

Description

This function registers an extension to an object such as a connection or an operation. This mechanism enables a plug-in to store private data with an operation that is passed from a preoperation to a postoperation plug-in for example, something not possible using parameter blocks.

Register object extensions as part of the plug-in initialization function.

Returns

This function returns 0 if successful. Otherwise, it returns -1.

See Also

slapi_extension_constructor_fnptr

slapi_extension_destructor_fnptr

slapi_get_object_extension()

slapi_set_object_extension()

slapi_register_plugin()

Register another 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

String identifying the plug-in type as described under Plug-In Registration

enabled

1 to enable the plug-in on registration, 0 otherwise

initsymbol

String representation of the plug-in initialization function initfunc such as "my_init_fcn"

initfunc

Pointer to the plug-in initialization function

name

Common Name for the plug-in

argv

Arguments passed to the plug-in

group_identity

Plug-in group identifier, typically obtained from SLAPI_PLUGIN_IDENTITY for the plug-in calling this function

Description

This function registers another plug-in. Register plug-ins as part of the plug-in initialization function.

Returns

This function returns 0 if successful. Otherwise, it returns -1.

See Also

slapi_plugin_init_fnptr

slapi_register_role_get_scope()

Register a callback to determine the scope of a role.

Syntax

#include "slapi-plugin.h"
void slapi_register_role_get_scope(
    roles_get_scope_fn_type get_scope_fn);

Parameters

This function takes the following parameters:

get_scope_fn

Callback to determine the scope of a role

Description

This function registers the callback that evaluates the scope of a role. Register the callback as part of the plug-in initialization function.

See Also

roles_get_scope_fn_type

slapi_role_get_scope()

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 const *controloid,
    unsigned long controlops );

Parameters

This function takes the following parameters:

controloid

OID of the control you want to register.

controlops

Operation that the control is applicable to.

The controlops argument can have one or more of the following values:

ID 

Description 

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 LDAP v3 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 ORing the values together (for example, SLAPI_OPERATION_ADD | SLAPI_OPERATION_DELETE).

See Also

slapi_control_present()

slapi_entry_get_uniqueid()

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

String identifying the SASL mechanism to both the server and to clients requesting the mechanism during a SASL bind

Description

Use this function in the plug-in initialization function to register the name of a SASL mechanism supported by the plug-in. The preoperation function handling the SASL bind can then check the SASL bind mechanism name provided by the client to determine whether to attempt to handle the bind.

See Also

The sample $INSTALL_DIR/plugins/slapd/slapi/examples/testsaslbind.c plug-in demonstrates the use of this function.

slapi_rename_internal_set_pb()

Prepares a parameter block for an internal modify RDN operation.

Syntax

#include "slapi-plugin.h"
int 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 for the internal modify RDN operation

olddn

Distinguished Name of the entry to rename

newrdn

New Relative Distinguished name to apply

newsuperior

DN of parent after renaming

deloldrdn

1 to delete the old RDN, 0 to retain the old RDN

controls

Array of controls to request for the modify RDN operation

uniqueid

Unique identifier for the entry if using this rather than DN

plugin_identity

Plug-in identifier obtained from SLAPI_PLUGIN_IDENTITY during plug-in initialization

operation_flags

NULL or SLAPI_OP_FLAG_NEVER_CHAIN

Returns

This function returns 0 if successful. Otherwise, it returns an LDAP error code.

Description

This function prepares a parameter block for use with slapi_modrdn_internal_pb().

Memory Concerns

Allocate the parameter block using slapi_pblock_new() before calling this function.

Directory Server does not free the parameters you passed to this function.

Free the parameter block after calling slapi_modrdn_internal_pb() .

See Also

slapi_modrdn_internal_pb()

slapi_pblock_new()

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 is placed. For results:

  • non 0 means present

  • 0 means not present

Returns

This function returns one of the following values:

slapi_role_get_scope()

Determine the scope of a role.

Syntax

#include "slapi-plugin.h"
int slapi_role_get_scope(Slapi_Entry *role_entry,
    Slapi_DN ***scope_dn, int *nb_scope);

Parameters

This function takes the following parameters:

role_entry

Entry defining the role

scope_dn

Set by the callback to the Distinguished Name of the entry at the base of the scope

nb_scope

Set by the callback to a value such as LDAP_SCOPE_BASE, LDAP_SCOPE_ONELEVEL, or LDAP_SCOPE_SUBTREE

Description

This function triggers a callback to evaluate the scope of a role.

Memory Concerns

Directory Server does not free or copy the parameters passed to this function.

See Also

roles_get_scope_fn_type

slapi_register_role_get_scope()

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 to the Slapi_DN structure to free.

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.

Description

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 initialized 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_add_rdn()

slapi_sdn_get_dn()

slapi_sdn_get_suffix()

Returns a pointer to the DN of the suffix containing the target.

Syntax

#include "slapi-plugin.h"
Slapi_DN* slapi_sdn_get_suffix(const Slapi_DN *target_sdn);

Parameters

This function takes the following parameter:

target_sdn

DN of the target entry whose suffix you want.

Returns

This function returns a pointer to a Slapi_DN structure containing the base DN of the suffix for the entry with target_sdn, or NULL if that suffix is not available.

Memory Concerns

Free the structure returned using slapi_sdn_free().

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 that 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_get_parent()

slapi_sdn_isparent()

slapi_sdn_issuffix()

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 that 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_get_parent()

slapi_sdn_issuffix()

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_copy()

slapi_sdn_done()

slapi_sdn_free()

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 value set 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 value set 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 in the new Slapi_DN structure.

Returns

This function returns a pointer to the new Slapi_DN structure with DN value set 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_byref()

slapi_sdn_new_dn_byval()

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 value set 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 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 value set 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 to which dn is going to be tested against.

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 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_log_info_ex()

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

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 FLAG_DN flag is set, and the internal counters are incremented.

See Also

slapi_log_info_ex()

slapi_sdn_set_dn_byval()

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.

dn

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

dn

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_log_info_ex()

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

See Also

slapi_sdn_get_parent()

slapi_sdn_isparent()

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

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

callback_data

A pointer to arbitrary plug-in or operation-specific data that you would like to pass to your callback functions.

prc

Callback function that the server calls to send result codes. The function must have the prototype specified by plugin_result_callback .

psec

Callback function that the server calls when finding a matching entry in the directory. The function must have the prototype specified by plugin_search_entry_callback.

prec

Callback function that the server calls when finding an entry that contains LDAP v3 referrals. The function must have the prototype specified by plugin_referral_entry_callback.

Returns

This function returns -1 if the parameter passed is a NULL pointer. Otherwise, it returns 0.

After your code calls this function, the server sets SLAPI_PLUGIN_INTOP_RESULT in the parameter block to the appropriate LDAP result code. You can therefore check SLAPI_PLUGIN_INTOP_RESULT in the parameter block to determine whether an error has occurred.

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:

Memory Concerns

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

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

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

slapi_search_internal_get_entry()

Performs an internal search operation to read one entry (that is, it performs a base object search).

Syntax

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

Parameters

This function takes the following parameters:

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_entry_free()

slapi_search_internal_pb()

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 -1 if the parameter passed is a NULL pointer. Otherwise, it returns 0.

After your code calls this function, the server sets SLAPI_PLUGIN_INTOP_RESULT in the parameter block to the appropriate LDAP result code. You can therefore check SLAPI_PLUGIN_INTOP_RESULT in the parameter block to determine whether an error has occurred.

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

slapi_search_internal_set_pb()

Sets a parameter block for an internal search.

Syntax

#include slapi-plugin.h
int 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.

base

The base of the search.

scope

LDAP_SCOPE_SUBTREE, LDAP_SCOPE_ONELEVEL , or LDAP_SCOPE_BASE

filter

The search filter.

attrs

Request attribute list.

This parameter is currently ignored.

attrsonly

Specifying 1 retrieves only the attribute types. Specifying 0 retrieves the attribute types and the attribute values.

controls

LDAP control that you wish to attach.

uniqueid

Unique ID must be set to NULL.

plugin_identity

Plug-in identifier obtained from SLAPI_PLUGIN_IDENTITY during plug-in initialization.

operation_flags

The only flag that is exposed in this release is SLAPI_OP_FLAG_NEVER_CHAIN . If this flag is set, then the search will not be conducted if the entry is a chained backend.

Returns

This function returns 0 if successful. Otherwise, it returns an LDAP error code.

Description

Use this function to set the parameter block to perform an internal search. This function is needed in order to use the internal search operation function, slapi_search_internal_pb().

You would typically create a Slapi_PBlock structure using slapi_pblock_new(), pass that parameter block to slapi_search_internal_pb(), and then pass the same parameter block to actually do the search.

Memory Concerns

Allocate the parameter block using slapi_pblock_new() before calling this function.

Directory Server does not free the parameters you passed to this function.

Free the parameter block after calling slapi_search_internal_pb() .

See Also

slapi_pblock_new()

slapi_search_internal_pb()

slapi_send_ldap_referral()

Processes an entry’s LDAP v3 referrals (which are found in the entry’s ref attribute). For LDAP v3 clients, this function sends the LDAP referrals back to the client. For LDAP v2 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 that you are working with.

refs

Pointer to the NULL terminated array of berval structures containing the LDAP v3 referrals (search result references) found in the entry.

urls

Pointer to the array of berval structures used to collect LDAP referrals for LDAP v2 clients.

Returns

This function returns 0 if successful, or -1 if an error occurs.

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:

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 LDAP v2 client or an LDAP_REFERRAL result code to an LDAP v3 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:

See Also

slapi_send_ldap_referral()

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 or not 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 0 if successful, 1 if the entry is not sent (for example, if access control did not allow it to be sent), or -1 if an error occurs.

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:

See Also

slapi_send_ldap_referral()

slapi_send_ldap_result()

slapi_set_object_extension()

Modify an 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

Set by the server and used to retrieve the extension

object

Extended object

extensionhandle

Set by the server and used to retrieve the extension

extension

New extension to attach to the object

Description

This function modifies an extension to an object.

See Also

slapi_register_object_extension()

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

Pointer to the Slapi_Entry structure representing the entry, or NULL if the string cannot be converted (for example, if no DN is specified in the string).

Description

A directory entry can be described by a string in LDIF format.

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 must use the string value again, 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 finished working with the entry, you should call the slapi_entry_free() function.

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

Memory Concerns

Do not use free() or slapi_ch_free() to free the entry. Always use slapi_entry_free() instead.

See Also

slapi_entry2str()

slapi_entry_free()

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.

Memory Concerns

Do not pass a static string to this function. Instead, create a duplicate using slapi_ch_strdup(). When you are finished working with this filter, you should free the Slapi_Filter structure by calling slapi_filter_free().

Returns

Pointer to the Slapi_Filter structure representing the search filter, or NULL if the string cannot be converted (for example, if an empty string is specified or if the filter syntax is incorrect).

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

One of the following values:

Description

This function unlocks the mutex specified by the Slapi_Mutex structure.

See Also

slapi_destroy_mutex()

slapi_lock_mutex()

slapi_new_mutex()

slapi_UTF-8CASECMP()

Compares two UTF-8 strings.

Syntax

#include "slapi-plugin.h"
 int slapi_UTF-8CASECMP(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

This function has the following rules:

slapi_UTF-8NCASECMP()

Compares a specified number of UTF-8 characters.

Syntax

#include "slapi-plugin.h"
 int slapi_UTF-8NCASECMP(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:

slapi_UTF-8ISLOWER()

Verifies if a UTF-8 character is lower case.

Syntax

#include "slapi-plugin.h"
 int slapi_UTF-8ISLOWER(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 1 if the character is a lower case letter, or 0 if it is not.

slapi_UTF-8ISUPPER()

Verifies if a single UTF-8 character is upper case.

Syntax

#include "slapi-plugin.h"
 int slapi_UTF-8ISUPPER(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 1 if the character is an upper case letter, or 0 if it is not.

slapi_UTF-8STRTOLOWER()

Converts a UTF-8 string to lower case.

Syntax

#include "slapi-plugin.h"
 unsigned char *slapi_UTF-8STRTOLOWER(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 a pointer to a NULL terminated UTF-8 string whose characters are converted to lower case. Characters which are not upper case are copied as is. If the string is not found to be a UTF-8 string, this function returns NULL.

Description

This function converts a string of multiple UTF-8 characters, and not a single character, as in slapi_UTF-8TOLOWER().

Memory Concerns

The output string is allocated, and needs to be released when it is no longer needed.

See Also

slapi_UTF-8TOLOWER()

slapi_UTF-8STRTOUPPER()

Converts a string made up of UTF-8 characters and converts it to upper case.

Syntax

#include "slapi-plugin.h"
 unsigned char *slapi_UTF-8STRTOUPPER(char *s);

Parameters

This function takes the following parameter:

s

A NULL terminated UTF-8 string to be converted to upper case.

Returns

This function returns a NULL terminated UTF-8 string whose characters are converted to upper case. Character which are not lower case are copied as is. If the string is not considered to be a UTF-8 string, this function returns NULL.

Memory Concerns

The output string is allocated in this function, and needs to be released when it is no longer used.

slapi_UTF-8TOLOWER()

Converts a UTF-8 character to lower case.

Syntax

#include "slapi-plugin.h"
 void slapi_UTF-8TOLOWER(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_UTF-8TOUPPER()

Converts a lower case UTF-8 character to an upper case character.

Syntax

#include "slapi-plugin.h"
 void slapi_UTF-8TOUPPER(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.

slapi_value_compare()

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

Syntax

#include "slapi-plugin.h"
 int 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_ValueSet 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_done()

Frees internals of a Slapi_Value structure.

Syntax

#include "slapi-plugin.h"
void slapi_value_done(Slapi_Value *v);

Parameters

This function takes the following parameter:

v

Pointer to the Slapi_Value structure whose internals you want to free.

See Also

slapi_value_init(), slapi_value_init_berval(), slapi_value_init_string()

slapi_value_dup()

Duplicates a value.

Syntax

#include "slapi-plugin.h"
 Slapi_Value * 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"
 void 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_valuearray_free()

Frees the specified array of Slapi_Value structures and their members from memory.

Syntax

#include "slapi-plugin.h"
void slapi_valuearray_free(Slapi_Value ***value);

Parameters

This function takes the following parameter:

value

Array of Slapi_Value structures to free.

Description

This function frees each Slapi_Value structure and its members, and sets the pointer to NULL.

Memory Concerns

Call this function when you are finished working with the array of values.

slapi_value_get_berval()

Gets the berval structure of the value.

Syntax

#include "slapi-plugin.h"
 const struct berval * 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

Returns a pointer to the berval structure contained in the Slapi_Value. This function returns a pointer to the actual berval structure, and 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 of which you wish to get as an integer.

Returns

This function returns an integer that corresponds to the value stored in the Slapi_Value structure, or 0 if there is no value.

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 the length of the value contained in Slapi_Value, or 0 if there is no value.

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 of which you wish to get as a long integer.

Returns

This function returns a long integer that corresponds to the value stored in the Slapi_Value structure, or 0 if there is no value.

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_uint()

slapi_value_get_ulong()

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 Slapi_Value of which you wish to get as a string.

Returns

This function returns a string containing the value, or NULL if there is no value.

This function returns a pointer to the actual string value in Slapi_Value, not a copy of it.

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 Slapi_Value of which you wish to get as an unsigned integer.

Returns

This function returns an unsigned integer that corresponds to the value stored in the Slapi_Value structure, or 0 if there is no value.

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 Slapi_Value of which you wish to get as an unsigned long integer.

Returns

This function returns an unsigned long integer that corresponds to the value stored in the Slapi_Value structure, or 0 if there is no value.

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

Memory Concerns

When finished using the Slapi_Value structure, free its internal structures by using slapi_value_done().

slapi_value_init_berval()

Initializes a Slapi_Value structure from the berval structure.

Syntax

#include "slapi-plugin.h"
 Slapi_Value * 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.

Memory Concerns

When finished using the Slapi_Value structure, free its internal structures by using slapi_value_done().

slapi_value_init_string()

Initializes a Slapi_Value structure from a string.

Syntax

#include "slapi-plugin.h"
 Slapi_Value * 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

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.

Memory Concerns

When finished using the Slapi_Value structure, free its internal structures by using slapi_value_done().

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 be initialized. The pointer must not be NULL.

s

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 * 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 * 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_dup()

slapi_value_free()

slapi_value_new()

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 * slapi_value_new_string(const char *s);

Parameters

This function takes the following parameter:

s

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_dup()

slapi_value_free()

slapi_value_new()

slapi_value_new_berval()

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

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_dup()

slapi_value_free()

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 * 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 terminated.

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 * 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 value set.

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 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 * 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 the pointer to the Slapi_Value structure passed as the parameter, or NULL if it was NULL.

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"
 int 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"
 int 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 in which to set the value.

strVal

The string containing the value to set.

Returns

This function returns 0 if the value is set, or -1 if the pointer to the Slapi_Value structure is NULL.

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 * 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 the pointer to the Slapi_Value structure passed as the parameter, or NULL if it was NULL.

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

slapi_valueset_add_value_optimised()

Adds a Slapi_Value in the Slapi_ValueSet structure.

Syntax

#include "slapi-plugin.h"
 void slapi_valueset_add_value_optimised(Slapi_ValueSet *vs,
    const Slapi_Value *addval, void *syntax_plugin);

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.

syntax_plugin

Pointer to the plug-in for this attribute type, obtained using slapi_attr_get_plugin().

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_const() and slapi_valueset_next_value_const() .

See Also

slapi_valueset_first_value_const()

slapi_valueset_next_value_const()

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 Slapi_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 reuse the Slapi_ValueSet structure for a new set of values.

slapi_valueset_find_const()

Finds the value in a value set using the syntax of an attribute.

#include "slapi-plugin.h"
const 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 a pointer to the value in the value set if the value was found. Otherwise, it returns NULL.

Description

Use this function to check for duplicate values in an attribute.

slapi_valueset_first_value_const()

Gets the first value of a Slapi_ValueSet structure.

Syntax

#include "slapi-plugin.h"
int slapi_valueset_first_value_const(const Slapi_ValueSet *vs,
    const 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 the index of the value in the Slapi_ValueSet, or -1 if there was no value.

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_const() 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_const()

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 finished 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 reset.

Description

This function initializes 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_valueset 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_const()

Gets the next value from a Slapi_ValueSet structure.

Syntax

#include "slapi-plugin.h"
int slapi_valueset_next_value_const(const Slapi_ValueSet *vs, int index,
    const 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_const() or slapi_valueset_first_value_const().

v

Address to the pointer to the Slapi_Value structure for the returned value.

Returns

This function returns the index of the value in the Slapi_ValueSet, or -1 if there was no more value or the input index is incorrect.

Description

Call this function when you wish to get the next value of a Slapi_ValueSet, after having first called slapi_valueset_first_value_const(). The returned value is the index of the value in the Slapi_ValueSet structure and must be passed to slapi_valueset_next_value_const().

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_const()

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_optimised()

Initializes a Slapi_ValueSet structure from another Slapi_ValueSet structure.

Syntax

#include "slapi-plugin.h"
 void slapi_valueset_set_valueset_optimised(Slapi_ValueSet *vs1,
    const Slapi_ValueSet *vs2, void *syntax_plugin);

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.

syntax_plugin

Pointer to the plug-in for this attribute type, obtained using slapi_attr_type2plugin().

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

slapi_vattr_attr_free()

Free a virtual attribute.

Syntax

#include "slapi-plugin.h"
void slapi_vattr_attr_free(Slapi_Attr **a, int buffer_flags);

Parameters

This function takes the following parameters:

a

Attribute to free

buffer_flags

Bitmask of SLAPI_VIRTUALATTRS_RETURNED_POINTERS, SLAPI_VIRTUALATTRS_RETURNED_COPIES, SLAPI_VIRTUALATTRS_REALATTRS_ONLY , SLAPI_VIRTUALATTRS_RETURNED_TYPENAME_ONLY

Description

Use this function to frees a virtual attribute when finished with it.

See Also

slapi_vattr_attrs_free()

slapi_vattr_attrs_free()

Free a list of virtual attributes.

Syntax

#include "slapi-plugin.h"
void slapi_vattr_attrs_free(vattr_type_thang **types, int flags);

Parameters

This function takes the following parameters:

types

List of attributes to free

flags

Bitmask of SLAPI_REALATTRS_ONLY, SLAPI_VIRTUALATTRS_ONLY , SLAPI_VIRTUALATTRS_REQUEST_POINTERS, SLAPI_VIRTUALATTRS_LIST_OPERATIONAL_ATTRS passed as flags to slapi_vattr_list_attrs()

Description

Use this function to frees a list of virtual attributes obtained using slapi_vattr_list_attrs().

See Also

slapi_vattr_attr_free()

slapi_vattr_list_attrs()

slapi_vattr_filter_test()

Test a filter against an entry that may contain virtual attributes.

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 the search request

e

Candidate entry

f

Filter to check

verify_access

1 to verify access to the entry before checking, 0 otherwise

Description

This function checks whether the candidate entry e matches the filter f. It does not support LDAP v3 extensible match filters.

Returns

This functions returns 0 if the filter matches, or if the filter is NULL. Otherwise, it returns -1.

slapi_vattr_is_registered()

Check whether an attribute may be virtual.

Syntax

#include "slapi-plugin.h"
int slapi_vattr_is_registered(const char *attrtype,
    const char *scopendn);

Parameters

This function takes the following parameters:

attrtype

Attribute type to check

scopendn

Base of the scope to check

Description

This function checks whether a virtual attribute service is registered for the attribute type in the scope specified.

The fact that a virtual attribute service is registered for an attribute type does not guarantee that the service can currently provide a value.

Returns

This functions returns 1 if the attribute may be virtual in the scope specified. Otherwise, it returns 0.

slapi_vattr_is_virtual()

Check whether an attribute is virtually generated.

Syntax

#include "slapi-plugin.h"
int slapi_vattr_is_virtual( Slapi_Entry *e, const char *attrtype,
    Slapi_Value *v);

Parameters

This function takes the following parameters:

e

Entry to check.

attrtype

Attribute type to check.

v

Not currently used.

Returns

This functions returns 1 if the attribute value is virtually generated. Otherwise, it returns 0.

slapi_vattr_list_attrs()

Get a list of the real and virtual attributes for an entry.

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

Get attributes for this entry

types

List of attributes set by the server

flags

Bitmask of SLAPI_REALATTRS_ONLY, SLAPI_VIRTUALATTRS_ONLY , SLAPI_VIRTUALATTRS_REQUEST_POINTERS, SLAPI_VIRTUALATTRS_LIST_OPERATIONAL_ATTRS determining what to set in the list

buffer_flags

Bitmask of SLAPI_VIRTUALATTRS_RETURNED_POINTERS, SLAPI_VIRTUALATTRS_RETURNED_COPIES, SLAPI_VIRTUALATTRS_REALATTRS_ONLY , SLAPI_VIRTUALATTRS_RETURNED_TYPENAME_ONLY determining how the virtual attributes should be handled

Description

This function sets types to point to a full list of attributes for the entry e depending on the flags parameter. Use the buffer_flags parameter when freeing the list.

Use slapi_vattr_values_type_thang_get() to access the attributes.

Returns

This functions returns 1 if the attribute may be virtual in the scope specified. Otherwise, it returns 0.

Memory Considerations

When finished with the types list, free it using slapi_vattr_attrs_free().

See Also

vattr_type_thang

slapi_vattr_attrs_free()

slapi_vattr_values_type_thang_get()

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 value set 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

Value set 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 value set and type names returned from slapi_vattr_values_get_ex().

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_VIRTUALATTRS_ONLY

  • SLAPI_VIRTUALATTRS_REQUEST_POINTERS

  • SLAPI_VIRTUALATTRS_LIST_OPERATIONAL_ATTRS

buffer_flags

Bit mask to be used as input flags for slapi_vattr_values_free() .

subtype_count

Number of subtypes matched.

Returns

This function returns 0 for success, in which case:

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 returned 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()

Get values from a list of the real and virtual attributes for an entry.

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 the attributes belong to

type_thang

Real or virtual attribute type

results

Values for the attribute, set by the server

type_name_disposition

Set by the server to reflect how type name matched; one of SLAPI_VIRTUALATTRS_TYPE_NAME_MATCHED_EXACTLY_OR_ALIAS, SLAPI_VIRTUALATTRS_TYPE_NAME_MATCHED_SUBTYPE , SLAPI_VIRTUALATTRS_NOT_FOUND (type matched no real or virtual attribute on the entry), or SLAPI_VIRTUALATTRS_LOOP_DETECTED (could not evaluate the virtual attribute)

actual_type_name

Set by the server to the actual type name found

flags

Bitmask of SLAPI_REALATTRS_ONLY, SLAPI_VIRTUALATTRS_ONLY , SLAPI_VIRTUALATTRS_REQUEST_POINTERS, SLAPI_VIRTUALATTRS_LIST_OPERATIONAL_ATTRS applied when obtaining the list using slapi_vattr_list_attrs()

buffer_flags

Set by the server to a bitmask of SLAPI_VIRTUALATTRS_RETURNED_POINTERS , SLAPI_VIRTUALATTRS_RETURNED_COPIES, SLAPI_VIRTUALATTRS_REALATTRS_ONLY , SLAPI_VIRTUALATTRS_RETURNED_TYPENAME_ONLY, useful for freeing the list

Description

This function offers optimized access to values of attributes in a list set by slapi_vattr_list_attrs().

Returns

This function returns 0 for success, in which case:

See Also

vattr_type_thang

slapi_vattr_list_attrs()

slapi_wait_condvar()

Wait for a change in a condition variable.

Syntax

#include "slapi-plugin.h"
int slapi_wait_condvar(Slapi_CondVar *cvar,struct timeval *timeout);

Parameters

This function takes the following parameter:

cvar

Condition variable on which to wait

timeout

NULL means block until notified. Otherwise, block until the time is up, then try again to acquire the lock.

Description

This function enables thread synchronization using a wait/notify mechanism.

Returns

This function returns 1 if successful. Otherwise, it returns NULL.

Memory Considerations

Call slapi_notify_condvar() to notify other threads of a change to the condition variable.

See Also

slapi_destroy_condvar()

slapi_new_condvar()

slapi_notify_condvar()