Plug-in Programmerís Guide
Red Hat Directory Server                                                            

Previous
Contents
Index
Next

Chapter 14

Data Type and Structure Reference


This chapter summarizes the data types and structures that you can use when writing Red Hat Directory Server (Directory Server) plug-in functions.

Summary of Data Types and Structures

The functions in the server plug-in API use the following data types and structures:

Data Types and Structures
Description
Represents binary data that is encoded using simplified Basic Encoding Rules (BER).
Represents information used for a computed attribute.
Represents a client or server control associated with an LDAP operation.
Represents an LDAP modification.
Specifies the prototype for a filter matching callback function.
Processes LDAP references generated by some internal searches.
Processes the results of LDAP entries that are located by an internal search.
Processes LDAP entries that are located by an internal search.
Specifies the prototype for a callback function that you can write to send LDAPv3 referrals (search result references) back to the client.
Specifies the prototype for a callback function that you can write to send LDAP result codes back to the client.
Specifies the prototype for a callback function that you can write to send search results (entries found by a search) back to the client.
Represents an attribute in an entry.
Represents a backend operation.
Specifies the prototype for a callback function, which allows a plug-in to register for callback, when a backend changes its state.
Represents the component ID in an entry.
Represents a callback for evaluating computed attributes.
Represents a prototype for an output function for computed attributes.
Represents an opaque type which represents a connection.
Represents a condition variable in the server plug-in.
Represents a distinguished name.
Represents an entry in the directory.
Represents a search filter.
Represents a matching rule.
Represents a single LDAP modification to a directory entry.
Represents two or more modifications performed on an a directory entry.
Represents a mutex in the server plug-in.
Represents an operation pending from an LDAP client.
Contains name-value pairs that you can get or set for each LDAP operation.
Represents information about a server plug-in.
Represents the relative distinguished name.
Represents the unique identifier of a directory entry.
Represents the value of the attribute in the directory entry.
Represents a set of Slapi_Value (or a list of Slapi_Value).

berval

Represents binary data that is encoded using simplified Basic Encoding Rules (BER).

Syntax

typedef struct berval { 

  unsigned long bv_len; 

  char *bv_val; 

}BerValue;
 

Parameters

This function has the following parameters:

bv_len
The length of the data.
bv_val
The binary data.

Description

The berval data structure represents binary data that is encoded using simplified Basic Encoding Rules (BER). The data and size of the data are included in a berval structure.

Use a berval structure when working with attributes that contain binary data (such as a JPEG or audio file).

computed_attr_context

Represents information used for a computed attribute.

Syntax

typedef struct _computed_attr_context computed_attr_context;
 

Description

computed_attr_context is the data type for an opaque structure that represents information about a computed attribute.

Before the Directory Server sends an entry back to a client, it determines if any of the attributes are computed, generates the attributes, and includes the generated attributes in the entry.

As part of this process, the server creates a computed_attr_context structure to pass relevant information to the functions generating the attribute values. Relevant information might include the attribute type, the BER-encoded request so far, and the parameter block.

LDAPControl

Represents a client or server control associated with an LDAP operation.

Syntax

typedef struct ldapcontrol {

  char *ldctl_oid;

  struct berval ldctl_value;

  char ldctl_iscritical;

} LDAPControl;
 

Parameters

This function has the following parameters:

ldctl_oid
Object ID (OID) of the control.
ldctl_value
berval structure containing the value used by the control for the operation.
ldctl_iscritical
Specifies whether the control is critical to the operation. This field can have one of the following values:
  • LDAP_OPT_ON specifies that the control is critical to the operation.
  • LDAP_OPT_OFF specifies that the control is not critical to the operation.

Description

The LDAPControl data type represents a client or server control associated with an LDAP operation. Controls are part of the LDAPv3 protocol. You can use a client or server control to extend the functionality of an LDAP control.

For example, you can use a server control to specify that you want the server to sort search results in an LDAP search operation.

The following table summarizes the front-end API functions that you can call to work with LDAP controls.

To ...
... Call this function
Create an LDAPControl structure based on a BerElement, an OID, and a criticality flag. It returns an LDAP error code.
Create an LDAPControl structure based on a struct berval, an OID, and a criticality flag. It returns an LDAP error code.
Check for the presence of a specific LDAPControl. It returns non-zero for presence and zero for absence.
Retrieve the LDAPMod contained in a Slapi_Mod structure
Register the specified control with the server. This function associates the control with an object identification (OID)
Retrieve an allocated array of object identifiers (OIDs) representing the controls supported by the Directory Server.

LDAPMod

Specifies changes to an attribute in an directory entry.

Syntax

typedef struct ldapmod {

  int mod_op;

  char *mod_type;

  union mod_vals_u{

    char **modv_strvals;

    struct berval **modv_bvals;

  } mod_vals;

#define mod_values mod_vals.modv_strvals

#define mod_bvalues mod_vals.modv_bvals

} LDAPMod;
 

Parameters

This function has the following parameters:

mod_op
The operation to be performed on the attribute and the type of data specified as the attribute values. This field can have one of the following values:
#define LDAP_MOD_ADD 0x00
#define LDAP_MOD_DELETE 0x01
#define LDAP_MOD_REPLACE 0x02
#define LDAP_MOD_BVALUES 0x80
  • LDAP_MOD_ADD specifies that you want to add the attribute values to the entry.
  • LDAP_MOD_DELETE specifies that you want to remove the attribute values from the entry.
  • LDAP_MOD_REPLACE specifies that you want to replace the existing value of the attribute with the value(s) in mod_values or mod_bvalues.
In addition, if you are specifying binary values (as opposed to strings), you should OR (|) LDAP_MOD_BVALUES with the operation type. For example:
  mod->mod_op = LDAP_MOD_ADD |
    LDAP_MOD_BVALUES
mod_type
Pointer to the attribute type that you want to add, delete, or replace.
mod_values_u
A NULL-terminated array of string values for the attribute.
modv_strvals
Pointer to a NULL terminated array of string values for the attribute.
mod_bvalues
Pointer to a NULL-terminated array of berval structures for the attribute.
mod_vals
Values that you want to add, delete, or replace.

Description

LDAPMod is a type of structure that you use to specify changes to an attribute in an directory entry. Before you call the slapi_add_internal_pb() and slapi_modify_internal_pb() routines to add or modify an entry in the directory, you need to fill LDAPMod structures with the attribute values that you intend to add or change.

The following section of code sets up an LDAPMod structure to change the email address of a user's entry to [email protected]:

Code Example 14-1 Sample Code for Changing the Email Address of a User's Entry  
 
Slapi_PBlock *rcpb;
LDAPMod attribute1;
LDAPMod *list_of_attrs[2];
char *mail_values[] = { "[email protected]", NULL };
char *dn;
...
/* Identify the entry that you want changed */
dn = "cn=Barbara Jensen, ou=Product Development, l=US, dc=example,dc=com";
/* Specify that you want to replace the value of an attribute */
attribute1.mod_op = LDAP_MOD_REPLACE;
 
/* Specify that you want to change the value of the mail attribute */
attribute1.mod_type = "mail";
 
/* Specify the new value of the mail attribute */
attribute1.mod_values = mail_values;
 
/* Add the change to the list of attributes that you want changed */
list_of_attrs[0] = &attribute_change;
list_of_attrs[1] = NULL;
 
/* Update the entry with the change */
rcpb = slapi_modify_internal( dn, list_of_attrs, NULL, 1 );
...
 

The following table summarizes the front-end API functions that you can call to specify changes to an attribute in an directory entry.

To ...
... Call this function
Translate from entry to LDAPMod.
Dump the contents of an LDAPMod to the server log.
Get a reference to the LDAPMod in a Slapi_Mod structure.
Retrieve the reference to the LDAPMod contained in a Slapi_Mod structure.

See Also

Slapi_Mod and Slapi_Mods.

mrFilterMatchFn

Specifies the prototype for a filter matching callback function.

Syntax

#include "slapi-plugin.h"

typedef int (*mrFilterMatchFn) (void* filter, 

  Slapi_Entry* entry, Slapi_Attr* attrs);
 

Parameters

This function has the following parameters:

filter
Pointer to the filter structure created by your filter factory function. (For details, see "Writing a Filter Factory Function," on page 145.)
entry
Pointer to the Slapi_Entry structure representing the candidate entry being checked by the server.
attrs
Pointer to the Slapi_Attr structure representing the first attribute in the entry. To iterate through the rest of the attributes in the entry, call slapi_entry_next_attr().

Returns

This function returns an integer value of 0 if the filter is matched or -1 if the filter did not match. If an LDAP error occurs, it returns a value >0.

Description

mrFilterMatchFn specifies the prototype for a filter matching function that is called by the server when processing an extensible match filter.

An extensible match filter specifies either the OID of a matching rule or an attribute type (or both) that indicates how matching entries are found. For example, a sound-alike matching rule might find all entries that sound like a given value.

To handle an extensible match filter for a matching rule, you can write a matching rule plug-in.

You need to define the filter matching function, which is the function that has prototype specified by mrFilterMatchFn. The server calls this function for each potential matching candidate entry. The server passes pointers to a filter structure that you create in your filter factory function (see "Writing a Filter Factory Function"), the candidate entry, and the entry's attributes.

In your filter matching function, you can retrieve information about the filter, such as the attribute type and value specified in the filter, from the filter structure. You can then use this information to compare the value in the filter against the attribute values in the candidate entry.

For more information on writing a filter matching function, see "Writing a Filter Factory Function."

plugin_referral_entry_callback

This typedef is used for LDAP referral entry callback functions, which are plugin-defined functions that process LDAP references generated by some internal searches.

Syntax

#include "slapi-plugin.h" 

typedef int (*plugin_referral_entry_callback) 

  (char *referral, void *callback_data);
 

Parameters

The function takes the following parameters:

referral
The URL of a reference that is returned in response to an internal search call.
callback_data
This value matches the callback_data pointer that was passed to the original internal operation function.

Returns

0 if successful or -1 if an error occurred.

Description

A function that matches this typedef can be passed as the prec parameter of slapi_search_internal_callback_pb(), or as the ref_callback parameter of the slapi_seq_internal_callback_pb() function.

The LDAP referral entry callback function will be called once for each referral entry found by a search operation, which means it could be called zero or any number of times.

The callback_data parameter can be used to pass arbitrary plug-in or operation-specific information to a referral entry callback function.

plugin_result_callback

This typedef is used for LDAP result callback functions, which are plugin-defined functions that process result messages that are generated by some internal search functions.

Syntax

#include "slapi-plugin.h"

typedef void (*plugin_result_callback)(int rc, 

  void *callback_data);
 

Parameters

The function takes the following parameters:

rc
The LDAP result code of the internal operation; for example, LDAP_SUCCESS.
callback_data
This value matches the callback_data pointer that was passed to the original internal operation function.

Returns

0 if successful or -1 if an error occurred.

Description

A function that matches this typedef can be passed as the prc parameter of slapi_search_internal_callback_pb() or as the res_callback parameter of slapi_seq_internal_callback_pb().

The LDAP result callback function should be called once for each search operation, unless the search is abandoned, in which case it will not be called.

The callback_data parameter can be used to pass arbitrary plug-in or operation-specific information to a result callback function.

plugin_search_entry_callback

This typedef is used for LDAP search entry callback functions, which are plug-in defined functions that process LDAP entries that are located by an internal search.

Syntax

#include "slapi-plugin.h"

typedef int (*plugin_search_entry_callback)(Slapi_Entry *e, 

  void *callback_data);
 

Parameters

The function has the following parameters:

e
Pointer to the Slapi_Entry structure representing an entry found by the search.
callback_data
This value matches the callback_data pointer that was passed to the original internal operation function.

Returns

0 if successful or -1 if an error occurred.

Description

A function that matches this typedef can be passed as the psec parameter of slapi_search_internal_callback_pb() or as the srch_callback parameter of slapi_seq_internal_callback_pb().

The LDAP referral entry callback function will be called once for each referral entry found by a search operation, which means it could be called zero or any number of times.

The callback_data parameter can be used to pass arbitrary plug-in or operation-specific information to a referral entry callback function.

send_ldap_referral_fn_ptr_t

send_ldap_referral_fn_ptr_t specifies the prototype for a callback function that you can write to send LDAPv3 referrals (search result references) back to the client. You can register your function so that it is called whenever the slapi_send_ldap_result() function is called.

Syntax

#include "slapi-plugin.h"

typedef int (*send_ldap_referral_fn_ptr_t)( Slapi_PBlock *pb, 

  Slapi_Entry *e, struct berval **refs, struct berval ***urls);
 

Parameters

The function has the following parameters:

pb
Parameter block.
e
Pointer to the Slapi_Entry structure representing the entry with which you are working.
refs
Pointer to the NULL-terminated array of berval structures containing the LDAPv3 referrals (search result references) found in the entry.
urls
Pointer to the array of berval structures used to collect LDAP referrals for LDAPv2 clients.

Returns

0 if successful, or -1 if an error occurs.

Description

The slapi_send_ldap_result()function is responsible for sending LDAPv3 referrals (search result references) back to the client. You can replace the function that sends LDAPv3 referrals to the client with your own function. To do this:

  1. Write a function with the prototype specified by send_ldap_result_fn_ptr_t.
  2. In your plug-in initialization function, register your function by setting the SLAPI_PLUGIN_PRE_REFERRAL_FN parameter in the parameter block to the name of your function if you are using the pre-operation plug-in. If you are using the post-operation plug-in, register your function by setting the SLAPI_PLUGIN_POST_REFERRAL_FN parameter in the parameter block to the name of your function.

See slapi_send_ldap_result() for information on the default function that sends LDAPv3 referrals to clients.

See Also

send_result()

send_ldap_result_fn_ptr_t

send_ldap_result_fn_ptr_t specifies the prototype for a callback function that you can write to send LDAP result codes back to the client. You can register your function so that it is called whenever the slapi_send_ldap_result() function is called.

Syntax

#include "slapi-plugin.h"

typedef void (*send_ldap_result_fn_ptr_t)( Slapi_PBlock *pb, 

  int err, char *matched, char *text, int nentries, 

  struct berval **urls );
 

Parameters

The function has 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.
text
Error message that you want sent back to the client. Use NULL if you do not want an error message sent back.
nentries
When sending back the result code for an LDAP search operation, use this argument to specify the number of matching entries found.
urls
When sending back an LDAP_PARTIAL_RESULTS result code to an LDAPv2 client or an LDAP_REFERRAL result code to an LDAPv3 client, use this argument to specify the array of berval structures containing the referral URLs.

Description

The slapi_send_ldap_result() function is responsible for sending LDAP result codes back to the client. You can replace the function that sends LDAP result codes to the client with your own function. To do this:

  1. Write a function with the prototype specified by send_ldap_result_fn_ptr_t.
  2. In your plug-in initialization function, register your function for sending results to the client by setting the SLAPI_PLUGIN_PRE_RESULT_FN or SLAPI_PLUGIN_POST_RESULT_FN parameter, depending on the type of plug-in and if it is a pre-operation or post-operation, respectively, in the parameter block to the name of your function.

See slapi_send_ldap_result() for information on the default function that sends LDAP result codes to clients.

See Also

slapi_send_ldap_result()

send_ldap_search_entry_fn_ptr_t

send_ldap_result_fn_ptr_t specifies the prototype for a callback function that you can write to send search results (entries found by a search) back to the client. You can register your function so that it is called whenever the slapi_send_ldap_search_entry() function is called.

Syntax

#include "slapi-plugin.h"

typedef int (*send_ldap_search_entry_fn_ptr_t)

  ( Slapi_PBlock *pb, Slapi_Entry *e, LDAPControl **ectrls, 

  char **attrs, int attrsonly );
 

Description

The slapi_send_ldap_search_entry() function is responsible for sending entries found by a search back to the client. You can replace the function that sends entries to the client with your own function. To do this:

  1. Write a function with the prototype specified by send_ldap_search_entry_fn_ptr_t.
  2. In your plug-in initialization function, register your function by setting the SLAPI_PLUGIN_PRE_ENTRY_FN parameter in the parameter block to the name of your function if you are using the pre-operation plug-in. If you are using the post-operation plug-in, register your function by setting the SLAPI_PLUGIN_POST_ENTRY_FN parameter in the parameter block to the name of your function.

See slapi_send_ldap_search_entry() for information on the default function that sends entries to clients.

See Also

slapi_send_ldap_search_entry()

Slapi_Attr

Represents an attribute in an entry.

Syntax

#include "slapi-plugin.h" 

typedef struct slapi_attr Slapi_Attr;
 

Description

Slapi_Attr is the data type for an opaque structure that represents an attribute in a directory entry. In certain cases, your server plug-in may need to work with an entry's attributes.

The following table summarizes the front-end API functions that you can call to work with attributes.

To ...
... Call this function
Add an attribute value.
Return the base type of an attribute.
Duplicate an attribute.
Get the first value of an attribute.
Determine if certain flags are set.
Free an attribute.
Put the values contained in an attribute into an array of berval structures.
Get the flags associated with an attribute.
Put the count of values of an attribute into an integer.
Search for an attribute type and gives its OID string.
Get the type of an attribute.
Get the next value of an attribute.
Determine the next value of an attribute.
Initialize a valueset in a Slapi_Attr structure from a specified Slapi_ValueSet structure.
Get information about the plug-in responsible for handling an attribute type.
Compare two attribute names to determine if they represent the same attribute.
Find the first attribute in an entry.
Iterate through the attributes in an entry.
Determine if an attribute contains a given value.
Determine if an attribute has the specified value.
Compare two attribute values.
Add the changes in a modification to a valueset.
Initialize a Slapi_ValueSet structure from another Slapi_ValueSet structure.

See Also

Slapi_Entry

Slapi_Backend

Represents a backend operation in the server plug-in-in.

Syntax

#include "slapi-plugin.h" 

typedef struct backend Slapi_Backend;
 

Description

Slapi_Backend is the data type for an opaque structure that represents a backend operation.

The following table summarizes the front-end API functions that you can call to work with the backend operations.

To ...
... Call this function
Add the specified suffix to the given backend and increment the backend's suffix count.
Set the flag to denote that the backend will be deleted on exiting.
Check if the backend that contains the specified DN exists.
Free memory and linked resources from the backend structure.
Get the instance information of the specified backend.
Return the name of the specified backend.
Indicate if the database associated with the backend is in read-only mode.
Get pointer to a callback function that corresponds to the specified entry point into a given backend.
Return the n+1 suffix associated with the specified backend.
Return the type of the backend.
Check if a flag is set in the backend configuration.
Verify that the specified suffix matches a registered backend suffix.
Indicate if the changes applied to the backend should be logged in the changelog.
Create a new backend structure, allocates memory for it, and initializes values for relevant parameters.
Verify if the backend is private.
Find the backend that should be used to service the entry with the specified DN.
Find the backend that matches by the name of the backend. Backends can be identified by name and type.
Set the specified flag in the backend.
Set the instance information of the specified backend with given data.
Set a flag to denote that the backend is meant to be read-only.
Set the entry point in the backend to the specified function.
Return a pointer to the backend structure of the first backend.
Return a pointer to the next backend, selected by index.
Return the first root suffix of the DIT.
Return the DN of the next root suffix of the DIT.
Check if a suffix is a root suffix of the DIT.

slapi_backend_state_change_fnptr

slapi_backend_state_change_fnptr specifies the prototype for a callback function, which allows a plug-in to register for callback when a backend state changes.

Syntax

#include "slapi-plugin.h"

typedef void (*slapi_backend_state_change_fnptr)(void *handle, 

  char *be_name, int old_be_state, int new_be_state);
 

Parameters

The function has the following parameters:

handle
Pointer or reference to the address of the specified function.
be_name
Name of the backend.
old_be_state
Old backend state.
new_be_state
New backend state.

Description

The slapi_register_backend_state_change() function enables a plug-in to register for callback when the state of a backend changes. You may need to keep track of backend state changes when writing custom plug-ins.

See Also

slapi_register_backend_state_change()
 
slapi_unregister_backend_state_change()
 

Slapi_ComponentID

Represents a the component ID in a directory entry.

Syntax

#include "slapi-plugin.h" 

typedef struct slapi_componentid Slapi_ComponentId;
 

Description

Slapi_ComponentId is the data type for an opaque structure that represents a the component ID in a directory entry.

slapi_compute_callback_t

Represents a callback for evaluating computed attributes.

Syntax

#include "slapi-plugin.h"

typedef int (*slapi_compute_callback_t)

  (computed_attr_context *c, char* type, 

  Slapi_Entry *e, slapi_compute_output_t outputfn);
 

Parameters

The function has the following parameters:

c
Pointer to the computed_attr_context structure containing information relevant to the computed attribute.
type
Attribute type of the attribute to be generated.
e
Pointer to the Slapi_Entry structure representing the entry to be sent back to the client.
outputfn
Pointer to the slapi_compute_output_t function responsible for BER-encoding the computed attribute and for adding it to the BER element to be sent to the client.

Returns

One of the following values:

Description

slapi_compute_callback_t specifies the prototype for a callback function that is called by the server when generating a computed attribute. If you want to use computed attributes, you should write a function of this type.

See Also

slapi_compute_output_t

slapi_compute_output_t

Represents a prototype for an output function for contributed attributes.

Syntax

#include "slapi-plugin.h"

typedef int (*slapi_compute_output_t)

  (computed_attr_context *c, Slapi_Attr *a, Slapi_Entry *e);
 

Parameters

The function has the following parameters:

Returns

One of the following values:

Description

slapi_compute_output_t specifies the prototype for a callback function that BER-encodes a computed attribute and appends it to the BER element to be sent to the client.

You do not need to define a function of this type. The server will pass a function of this type your slapi_compute_callback_t function. In your slapi_compute_callback_t function, you need to call this slapi_compute_output_t function.

For example:

static int
 
my_compute_callback(computed_attr_context *c, char* type, 

  Slapi_Entry *e, slapi_compute_output_t outputfn)

{

  ...

  int rc; 

  Slapi_Attr my_computed_attr;

  ...

  /* Call the output function after created the computed 

    attribute and setting its values. */

  rc = (*outputfn) (c, &my_computed_attr, e);

  ...

}
 

In the example above, the slapi_compute_output_t function outputfn is passed in as an argument to my_compute_callback function. After generating the computed attribute, you need to call outputfn, passing it the context, the newly created attribute, and the entry. outputfn BER-encodes the attribute and appends it to the BER element to be sent to the client.

You do not need to define outputfn yourself. You just need to call the function passed in as the last statement from the callback.

See Also

slapi_compute_callback_t

Slapi_Connection

Represents a connection.

Syntax

#include "slapi-plugin.h" 

typedef struct conn Slapi_Connection;
 

Description

Slapi_Connection is the data type for an opaque structure that represents a connection.

Slapi_CondVar

Represents a condition variable in a directory entry.

Syntax

#include "slapi-plugin.h" 

typedef struct slapi_condvar Slapi_CondVar;
 

Description

Slapi_CondVar is the data type for an opaque structure that represents a synchronization lock in the server plug-in.

The following table summarizes the front-end API functions that you can call to modify synchronization locks in the server plug-in.

To ...
... Call this function
Destroy a condition variable.
Create a new condition variable.
Send notification about a condition variable.
Wait for a condition variable.

Slapi_DN

Represents a distinguished name in a directory entry.

Syntax

#include "slapi-plugin.h" 

typedef struct slapi_dn Slapi_DN;
 

Description

Slapi_DN is the data type for an opaque structure that represents a distinguished name in the server plug-in.

The following table summarizes the front-end API functions that you can call to work with distinguished names.

To ...
... Call this function
Convert all characters in a DN to a lowercase distinguished name to make it case insensitive.
Determine if a DN is equal to a specified suffix.
Determine if a DN is the parent of a specific DN.
Specify a distinguished name is a root.
Determine if the a DN is the suffix of the local database.
Convert a DN to canonical format by normalizing the case and the format. Handle a DN in the syntax defined by RFC 22 and RFC 1779. To handle some syntaxes compatible with older versions of Directory Server, all of the syntaxes in the above RFC's may not be supported.
Convert a DN to canonical format and all characters to lower case
Normalize part of a DN value
Get a copy of the DN of the parent of an entry
Get the DN of the parent of an entry
Add an RDN to a DN

See Also

Slapi_PBlock

Slapi_Entry

Represents an entry in the directory.

Syntax

#include "slapi-plugin.h" 

typedef struct slapi_entry Slapi_Entry;
 

Description

Slapi_Entry is the data type for an opaque structure that represents an entry in the directory. In certain cases, your server plug-in may need to work with an entry in the directory.

The following table summarizes the front-end API functions that you can call to work with entries.

To ...
... Call this function
Generate an LDIF string description.
Generate an LDIF string descriptions with options.
Add components in an entry's RDN.
Add a string value to an attribute in an entry.
Add a data value to an attribute in an entry.
Add an array of data values to an attribute in an entry.
Add a data value to an attribute in an entry.
Allocate memory for an entry structure.
Delete an attribute from an entry.
Check if an entry contains a specific attribute.
Get the first value as a string.
Get the values of a multi-valued attribute of an entry.
Get the first value as an integer.
Get the first value as a long.
Get the first value as an unsigned integer.
Get the first value as an unsigned long.
Check if an attribute in an entry contains a value.
Add an array to the attribute values in an entry.
Replace the values of an attribute with a string.
Set the first value as a string.
Set the first value as an integer.
Set the first value as a long.
Set the first value as an unsigned integer.
Set the first value as an unsigned long.
Delete a string from an attribute.
Remove a Slapi_Value array from an attribute.
Copy an entry, its DN, and its attributes.
Find the first attribute in an entry.
Free an entry from memory.
Get the DN from an entry.
Return the DN of an entry as a constant.
Return the normalized distinguished name (NDN) of an entry.
Return the Slapi_DN from an entry.
Return a Slapi_DN from an entry as a constant.
Get the unique ID from an entry.
Determine if the specified entry has child entries.
Initialize the values of an entry.
Add an array of data values to an attribute in an entry.
Find the next attribute in an entry.
Check if values present in an entry's RDN are also present as attribute values.
Determine if an entry complies with the schema for its object class.
Set the DN of an entry.
Set the Slapi_DN value in an entry.
Set the unique ID in an entry.
Return the size of an entry.
Determine if an entry is the root DSE.
Convert an LDIF description into an entry.

See Also

Slapi_Attr

Slapi_Filter

Represents a search filter.

Syntax

#include "slapi-plugin.h" 

typedef struct slapi_filter Slapi_Filter;
 

Description

Slapi_Filter is the data type for an opaque structure that represents an search filter. (For more information on search filters, see "Working with Search Filters," on page 74.)

The following table summarizes the front-end API functions that you can call to work with filters.

To ...
... Call this function
Determine if an entry matches a filter's criteria.
Get the filter type.
Get the attribute type and value used for comparison in a filter (only applicable to LDAP_FILTER_EQUALITY, LDAP_FILTER_GE, LDAP_FILTER_LE, and LDAP_FILTER_APPROX searches).
Get the type of attribute that the filter is searching for (only applicable to LDAP_FILTER_PRESENT searches).
Get the substring pattern used for the filter (applicable only to LDAP_FILTER_SUBSTRING searches).
Convert a string representation of a filter to a filter of the data type Slapi_Filter.
Construct a new LDAP_FILTER_AND, LDAP_FILTER_OR, or LDAP_FILTER_NOT filter from other filters.
Get the components of a filter (only applicable to LDAP_FILTER_AND, LDAP_FILTER_OR, and LDAP_FILTER_NOT searches).
Free a filter from memory.

Slapi_MatchingRuleEntry

Represents a matching rule.

Syntax

#include "slapi-plugin.h" 

typedef struct slapi_matchingRuleEntry Slapi_MatchingRuleEntry;
 

Description

Slapi_MatchingRuleEntry is the data type for an opaque structure that represents a matching rule.

The following table summarizes the front-end API functions that you can call to work with matching rules.

To ...
... Call this function
Compare two berval structures to determine if they are equal.
Call the indexer function associated with an extensible match filter.
Free the specified matching rule structure (and optionally, its members) from memory.
Get information about a matching rule.
Call the indexer factory function for the plug-in responsible for a specified matching rule.
Allocate memory for a new Slapi_MatchingRuleEntry structure.
Register the specified matching rule with the server.
Set information about the matching rule.
Placeholder for future function (currently, this function does nothing).

Slapi_Mod

Represents a single LDAP modification to a directory entry.

Syntax

#include "slapi-plugin.h" 

typedef struct slapi_mod Slapi_Mod;
 

Description

Slapi_Mod is the data type for an opaque structure that represents LDAPMod modifications to an attribute in a directory entry.

The following table summarizes the front-end API functions that you can call to manipulate directory entries.

To ...
... Call this function
Add a value to a Slapi_Mod structure.
Free internals of Slapi_Mod structure.
Dump the contents of an LDAPMod to the server log.
Free a Slapi_Mod structure.
Initialize a Slapi_Mod iterator and return the first attribute value.
Get a reference to the LDAPMod in a Slapi_Mod structure.
Retrieve the LDAPMod contained in a Slapi_Mod structure.
Increment the Slapi_Mod iterator and return the next attribute value.
Get the number of values in a Slapi_Mod structure.
Get the operation type of Slapi_Mod structure.
Get the attribute type of a Slapi_Mod structure.
Initialize a Slapi_Mod structure.
Initialize a Slapi_Mod structure that is a wrapper for an existing LDAPMod.
Initialize a modification by value.
Initialize a Slapi_Mod from an LDAPMod.
Determine whether a Slapi_Mod structure is valid.
Allocate a new Slapi_Mod structure.
Remove the value at the current Slapi_Mod iterator position.
Set the operation type of a Slapi_Mod structure.
Set the attribute type of a Slapi_Mod.

See Also

LDAPMod and Slapi_Mods

Slapi_Mods

Represents two or more LDAP modifications to a directory entry

Syntax

#include "slapi-plugin.h" 

typedef struct slapi_mods Slapi_Mods;
 

Description

Slapi_Mods is the data type for an opaque structure that represents LDAPMod manipulations that can be made to a directory entry.

The following table summarizes the front-end API functions that you can call to manipulate directory entries.

To ...
... Call this function
Create a Slapi_Entry from an array of LDAPMod.
Append a new mod with a single attribute value to Slapi_Mods structure.
Append an LDAPMod to a Slapi_Mods structure.
Append a new mod to a Slapi_Mods structure, with attribute values provided as an array of berval.
Append a new mod to a Slapi_Mods structure, with attribute values provided as an array of Slapi_Value.
Append a new mod to Slapi_Mods structure with a single attribute value provided as a string.
Complete a modification.
Dump the contents of a Slapi_Mods structure to the server log.
Free a Slapi_Mods structure.
Initialize a Slapi_Mods iterator and return the first LDAPMod.
Get a reference to the array of LDAPMod in a Slapi_Mods structure.
Retrieve the array of LDAPMod contained in a Slapi_Mods structure.
Increment the Slapi_Mods iterator and return the next LDAPMod.
Increment the Slapi_Mods iterator and return the next mod wrapped in a Slapi_Mods.
Get the number of mods in a Slapi_Mods structure.
Initialize a Slapi_Mods.
Initialize a Slapi_Mods that is a wrapper for an existing array of LDAPMod.
Initialize a Slapi_Mods structure from an array of LDAPMod.
Insert an LDAPMod into a Slapi_Mods structure after the current iterator position.
Insert an LDAPMod anywhere in a Slapi_Mods.
Insert an LDAPMod into a Slapi_Mods structure before the current iterator position.
Decrement the Slapi_Mods current iterator position.
Allocate a new uninitialized Slapi_Mods structure.
Remove the mod at the current Slapi_Mods iterator position.

See Also

LDAPMod and Slapi_Mod

Slapi_Mutex

Represents a mutually exclusive lock in the server plug-in.

Syntax

#include "slapi-plugin.h" 

typedef struct slapi_mutex Slapi_Mutex;
 

Description

Slapi_Mutex is the data type for an opaque structure that represents a mutual exclusive lock (mutex) in the server plug-in.

The following table summarizes the front-end API functions that you can call to work with mutually exclusive locks.

To ...
... Call this function
Destroy a mutex.
Lock a mutex.
Create a new mutex.
Unlock a mutes.

Slapi_Operation

Represents an operation pending from an LDAP client.

Syntax

#include "slapi-plugin.h" 

typedef struct op Slapi_Operation;
 

Description

Slapi_Operation is the data type for an opaque structure that represents an operation pending from an LDAP client.

The following table summarizes the front-end API functions that you can call to work with mutually exclusive locks.

To ...
... Call this function
Determine if the client has abandoned the current operation.
Get the type of a Slapi_Operation.

Slapi_PBlock

Contains name-value pairs, known as parameter blocks, that you can get or set for each LDAP operation.

Syntax

#include "slapi-plugin.h" 

typedef struct slapi_pblock Slapi_PBlock;
 

Description

Slapi_PBlock contains name-value pairs that you can use to retrieve information from the server and set information to be used by the server.

For most types of plug-in functions, the server passes in a Slapi_PBlock structure that typically includes data relevant to the operation being processed. You can get the value of a parameter by calling the slapi_pblock_get() function.

For example, when the plug-in function for an LDAP bind operation is called, the server puts the DN and credentials in the SLAPI_BIND_TARGET and SLAPI_BIND_CREDENTIALS parameters of the Slapi_PBlock structure. You can call slapi_pblock_get() to get the DN and credentials of the client requesting authentication.

For plug-in initialization functions, you can use the Slapi_PBlock structure to pass information to the server, such as the description of your plug-in and the names of your plug-in functions. You can set the value of a parameter by calling the slapi_pblock_set() function.

For example, in order to register a pre-operation bind plug-in function, you need to call slapi_pblock_set() to set the version number, description, and name of the plug-in function as the SLAPI_PLUGIN_VERSION, SLAPI_PLUGIN_DESCRIPTION, and SLAPI_PLUGIN_PRE_BIND_FN parameters.

The available parameters that you can use depends on the type of plug-in function you are writing.

The following table summarizes the front-end API functions that you can call to work with block parameters.

To ...
... Call this function
Set up a parameter block so that it can be used by slapi_add_internal_pb() for an internal add operation.
Add an LDAP add operation based on a parameter block to add a new directory entry.
Set up a parameter block so that it can be used by slapi_add_internal_pb() for an internal add operation; the entry is constructed from a DN and a set of attributes.
Perform an LDAP delete operation based on a parameter block to remove a directory entry.
Delete an internal parameter block set.
Perform an LDAP modify operation based on a parameter block to modify a directory entry.
Set up a parameter block so that it can be used by slapi_modify_internal_pb() for an internal modify operation.
Perform an LDAP modify RDN operation based on a parameter block to rename a directory entry.
Free a pblock from memory.
Get the value from a pblock.
Create a new pblock.
Set the value of a pblock.
Set up a parameter block so that it can be used by slapi_modrdn_internal_pb() for an internal rename operation.
Perform an LDAP search operation based on a parameter block to search the directory.
Search for an internal parameter block.
Set up a parameter block so that it can be used by slapi_search_internal_pb() for an internal search operation.
Perform an internal sequential access operation.
Set up a parameter block for use by slapi_seq_internal_callback_pb() for an internal, sequential-access operation.

Slapi_PluginDesc

Represents information about a server plug-in.

Syntax

typedef struct slapi_plugindesc {

  char *spd_id;

  char *spd_vendor;

  char *spd_version;

  char *spd_description;

} Slapi_PluginDesc;
 

Parameters

The function has the following parameters:

spd_id
Unique identifier for the server plug-in.
spd_vendor
Name of the vendor supplying the server plug-in; for example, example.com.
spd_version
Version of the server plug-in used for your own tracking purposes; for example, 0.5. This is different from the value of the SLAPI_PLUGIN_VERSION, which specifies the general version of plug-in technology; the Directory Server uses that version to determine if it supports a plug-in.
spd_description
Description of the server plug-in.

Description

Slapi_PluginDesc represents information about a server plug-in. In your initialization function, you specify information about your plug-in in this structure and call slapi_pblock_set() to put the structure in the SLAPI_PLUGIN_DESCRIPTION parameter.

See Also

For more information on using Slapi_PluginDesc to specify plug-in information, see "Specifying Information about the Plug-in," on page 43.

Slapi_RDN

Represents a relative distinguished name in a directory entry.

Syntax

#include "slapi-plugin.h" 

typedef struct slapi_rdn Slapi_RDN;
 

Description

Slapi_RDN is the data type for an opaque structure that represents a relative distinguished name in the server plug-in.

The following table summarizes the front-end API functions that you can call to work with relative distinguished names.

To ...
... Call this function
Add a new RDN to an existing RDN structure.
Compare two RDNs.
Check if a Slapi_RDN structure holds any RDN matching a give type/value pair.
Check if a Slapi_RDN structure contains any RDN matching a given type.
Clear a Slapi_RDN structure.
Free a Slapi_RDN structure.
Get the type/value pair of the first RDN.
Get the index of the RDN.
Get the position and the attribute value of the first RDN.
Get the RDN type/value pair from the RDN.
Get the number of RDN type/value pairs.
Get the RDN from a Slapi_RDN structure.
Initialize a Slapi_RDN structure.
Initialize a Slapi_RDN structure with an RDN value taken from a given DN.
Initializes Slapi_RDN structure with an RDN value.
Initialize a Slapi_RDN structure with an RDN value taken from the DN contained in a given Slapi_RDN.
Check if an RDN value is stored in a Slapi_RDN structure.
Allocate a new Slapi_RDN structure.
Create a new Slapi_RDN structure.
Create a new Slapi_RDN structure and set an RDN value.
Create a new Slapi_RDN structure and set an RDN value taken from the DN contained in a given Slapi_RDN structure.
Remove an RDN type/value pair.
Remove an RDN type/value pair from a Slapi_RDN.
Remove an RDN type/value pair from a Slapi_RDN structure.
Set an RDN value in a Slapi_RDN structure.
Set an RDN in a Slapi_RDN structure.
Set an RDN value in a Slapi_RDN structure.
Add an RDN to a DN.

Slapi_UniqueID

Represents the unique identifier of a directory entry.

Syntax

#include "slapi-plugin.h" 

typedef struct _guid_t Slapi_UniqueID;
 

Description

Slapi_UniqueID is the data type for an opaque structure that represents the unique identifier of a directory entry. All directory entries contain a unique identifier. Unlike the distinguished name (DN), the unique identifier of an entry never changes, providing a good way to refer unambiguously to an entry in a distributed/replicated environment.

Slapi_Value

Represents the value of the attribute in a directory entry.

Syntax

#include "slapi-plugin.h" 

typedef struct slapi_value Slapi_Value;
 

Description

Slapi_Value is the data type for an opaque structure that represents the value of an attribute in a directory entry.

The following table summarizes the front-end API functions that you can call to work with directory entry values.

To ...
... Call this function
Compare a value.
Duplicate a value.
Free a Slapi_Value structure from memory.
Get the berval structure of the value.
Convert the value of an integer.
Get the length of a value.
Get the actual length of the value.
Convert a value into a long integer.
Return the value as a string. The value returned may not be null-terminated.
Convert the value into an unsigned integer.
Convert the value into an unsigned long.
Initialize a Slapi_Value structure with no values.
Initialize a Slapi_Value structure from the berval structure.
Initialize a Slapi_Value structure from a string.
Initialize a Slapi_Value structure with a value contained in a string.
Allocate a new Slapi_Value structure.
Allocate a new Slapi_Value structure from a berval structure.
Allocate a new Slapi_Value structure from a string.
Allocate a new Slapi_Value structure and initializes it from a string.
Allocate anew Slapi_Value from another Slapi_Value structure.
Set the value.
Copy the value from a berval structure into a Slapi_Value structure.
Set the integer value of a Slapi_Value structure.
Copy a string into the value.
Set the value.
Copy the value of a Slapi_Value structure into another Slapi_Value structure.

See Also

Slapi_ValueSet

Slapi_ValueSet

Represents a set of Slapi_Value (or a list of Slapi_Value).

Syntax

#include "slapi-plugin.h" 

typedef struct slapi_value_set Slapi_ValueSet;
 

Description

Slapi_ValueSet is the data type for an opaque structure that represents set of Slapi_Value (or a list of Slapi_Value).

The following table summarizes the front-end API functions that you can call to work with sets of Slapi_Value.

To ...
... Call this function
Add a Slapi_Value in the Slapi_ValueSet structure.
Count the values in a valueset.
Free the values contained in the Slapi_ValueSet structure.
Find the value in a valueset using the syntax of an attribute.
Get the first value of a Slapi_ValueSet structure.
Free the specified Slapi_ValueSet structure and its members from memory.
Reset a Slapi_ValueSet structure to no values.
Allocate a new Slapi_ValueSet structure.
Get the next value from a Slapi_ValueSet structure.
Add the changes in a modification to a valueset.
Initialize a Slapi_ValueSet structure from another Slapi_ValueSet structure.

See Also

Slapi_Value




Previous
Contents
Index
Next

© 2001 Sun Microsystems, Inc. Used by permission. © 2005 Red Hat, Inc. All rights reserved.
Read the Full Copyright and Third-Party Acknowledgments.

last updated May 26, 2005