Plug-In Programmer's Guide Netscape Directory Server

Previous      Contents      Index      DocHome      Next

Chapter 14   Data Type and Structure Reference

This chapter summarizes the data types and structures that you can use when writing Netscape 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
berval	Represents binary data that is encoded using simplified Basic Encoding Rules (BER).
computed_attr_context	Represents information used for a computed attribute.
LDAPControl	Represents a client or server control associated with an LDAP operation.
LDAPMod	Represents an LDAP modification.
mrFilterMatchFn	Specifies the prototype for a filter matching callback function.
plugin_referral_entry_callback	Processes LDAP references generated by some internal searches.
plugin_result_callback	Processes the results of LDAP entries that are located by an internal search.
plugin_search_entry_callback	Processes LDAP entries that are located by an internal search.
send_ldap_referral_fn_ptr_t	Specifies the prototype for a callback function that you can write to send LDAP v3 referrals (search result references) back to the client.
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.
send_ldap_search_entry_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.
Slapi_Attr	Represents an attribute in an entry.
Slapi_Backend	Represents a backend operation.
slapi_backend_state_change_fnptr	Specifies the prototype for a callback function, which allows a plug-in to register for callback, when a backend changes its state.
Slapi_ComponentID	Represents the component ID in an entry.
slapi_compute_callback_t	Represents a callback for evaluating computed attributes.
slapi_compute_output_t	Represents a prototype for an output function for computed attributes.
Slapi_Connection	Represents a opaque type which represents a connection.
Slapi_CondVar	Represents a condition variable in the server plug-in.
Slapi_DN	Represents a distinguished name.
Slapi_Entry	Represents an entry in the directory.
Slapi_Filter	Represents a search filter.
Slapi_MatchingRuleEntry	Represents a matching rule.
Slapi_Mod	Represents a single LDAP modification to a directory entry.
Slapi_Mods	Represents two or more modifications performed on an a directory entry.
Slapi_Mutex	Represents a mutex in the server plug-in.
Slapi_Operation	Represents an operation pending from an LDAP client.
Slapi_PBlock	Contains name-value pairs that you can get or set for each LDAP operation.
Slapi_PluginDesc	Represents information about a server plug-in.
Slapi_RDN	Represents the relative distinguished name.
Slapi_UniqueID	Represents the unique identifier of a directory entry.
Slapi_Value	Represents the value of the attribute in the directory entry.
Slapi_ValueSet	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 or not 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 LDAP v3 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 do this...	Call this function
Creates an LDAPControl structure based on a BerElement, an OID, and a criticality flag. Returns an LDAP error code.	slapi_build_control()
Creates an LDAPControl structure based on a struct berval, an OID, and a criticality flag. Returns an LDAP error code.	slapi_build_control_from_berval()
Checks for the presence of a specific LDAPControl. Returns non-zero for presence and zero for absence.	slapi_control_present()
Retrieves the LDAPMod contained in a Slapi_Mod structure	slapi_mod_get_ldapmod_passout()
Registers the specified control with the server. This function associates the control with an object identification (OID)	slapi_register_supported_control())
Retrieves an allocated array of object identifiers (OIDs) representing the controls supported by the Directory Server.	slapi_get_supported_controls_copy()

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 "bab@example.com":

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[] = { "bab@example.com", NULL };

char *dn;

...

/* Identify the entry that you want changed */

dn = "cn=Barbara Jensen, ou=Product Development, o=Ace Industry, c=US";

/* 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 do this...	Call this function
Translate from entry to LDAPMod	slapi_entry2mods()
Dumps the contents of an LDAPMod to the server log	slapi_mod_dump()
Gets a reference to the LDAPMod in a Slapi_Mod structure	slapi_mod_get_ldapmod_byref()
Retrieves the reference to the LDAPMod contained in a Slapi_Mod structure	slapi_mod_get_ldapmod_passout()

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.")
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 Matching 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 0 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 0 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 LDAP v3 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 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

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

Description

The slapi_send_ldap_result()function is responsible for sending LDAP v3 referrals (search result references) back to the client. You can replace the function that sends LDAP v3 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 your 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 LDAP v3 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 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.

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 do this...	Call this function
Add an attribute value	slapi_attr_add_value()
Return the base type of an attribute	slapi_attr_basetype()
Duplicate an attribute	slapi_attr_dup()
Get the first value of an attribute	slapi_attr_first_value()
Determine if certain flags are set	slapi_attr_flag_is_set()
Free an attribute	slapi_attr_free()
Puts the values contained in an attribute into an array of berval structures	slapi_attr_get_bervals_copy()
Get the flags associated with an attribute	slapi_attr_get_flags()
Put the count of values of an attribute into an integer	slapi_attr_get_numvalues()
Search for an attribute type and gives its OID string	slapi_attr_get_oid_copy()
Get the type of an attribute	slapi_attr_get_type()
Get the next value of an attribute	slapi_attr_get_valueset()
Determine the next value of an attribute	slapi_attr_next_value()
Initialize a valueset in a Slapi_Attr structure from a specified Slapi_ValueSet structure	slapi_attr_set_valueset()
Get information about the plug-in responsible for handling an attribute type	slapi_attr_type2plugin()
Compare two attribute names to determine if they represent the same attribute	slapi_attr_types_equivalent()
Find the first attribute in an entry	slapi_entry_first_attr()
Iterate through the attributes in an entry	slapi_entry_next_attr()
Determine if an attribute contains a given value	slapi_entry_attr_find()
Determine if an attribute has the specified value	slapi_attr_value_find()
Compare two attribute values	slapi_attr_value_cmp()
Add the changes in a modification to a valueset	slapi_valueset_set_from_smod()
Initialize a Slapi_ValueSet structure from another Slapi_ValueSet structure	slapi_valueset_set_valueset()

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 do this...	Call this function
Add the specified suffix to the given backend and increments the backend's suffix count	slapi_be_addsuffix()
Set the flag to denote that the backend will be deleted on exiting	slapi_be_delete_onexit()
Check if the backend that contains the specified DN exists	slapi_be_exist()
Free memory and linked resources from the backend structure	slapi_be_free()
Get the instance information of the specified backend	slapi_be_get_instance_info()
Return the name of the specified backend	slapi_be_get_name()
Indicate if the database associated with the backend is in read-only mode	slapi_be_get_readonly()
Get pointer to a callback function that corresponds to the specified entry point into a given backend	slapi_be_getentrypoint()
Return the n+1 suffix associated with the specified backend	slapi_be_getsuffix()
Return the type of the backend	slapi_be_gettype()
Check if a flag is set in the backend configuration	slapi_be_is_flag_set()
Verify that the specified suffix matches a registered backend suffix	slapi_be_issuffix()
Indicate if the changes applied to the backend should be logged in the change log	slapi_be_logchanges()
Create a new backend structure, allocates memory for it, and initializes values for relevant parameters	slapi_be_new()
Verify if the backend is private	slapi_be_private()
Find the backend that should be used to service the entry with the specified DN	slapi_be_select()
Find the backend that matches by the name of the backend. Backend's can be identified by name and type.	slapi_be_select_by_instance_name()
Set the specified flag in the backend	slapi_be_set_flag()
Set the instance information of the specified backend with given data	slapi_be_set_instance_info()
Set a flag to denote that the backend is meant to be read-only	slapi_be_set_readonly()
Set the entry point in the backend to the specified function	slapi_be_setentrypoint()
Return a pointer to the backend structure of the first backend	slapi_get_first_backend()
Return a pointer to the next backend, selected by index	slapi_get_next_backend()
Return the first root suffix of the DIT	slapi_get_first_suffix()
Return the DN of the next root suffix of the DIT	slapi_get_next_suffix()
Check if a suffix is a root suffix of the DIT	slapi_is_root_suffix()

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:

• -1 if the function is not responsible for generating the computed attribute.
• 0 if the function successfully generates the computed attribute.
• An LDAP error code if an error occurred.

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:

• 0 if the function successfully BER-encodes the computed attribute and adds it to the BER element to be sent to the client.
• An LDAP error code if an error occurred.

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.

Note that 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 do this...	Call this function
Destroy a condition variable	slapi_destroy_condvar()
Create a new condition variable	slapi_new_condvar()
Send notification about a condition variable	slapi_notify_condvar()
Wait for a condition variable	slapi_wait_condvar()

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 do this...	Call this function
Converts all characters in a DN to a lowercase distinguished name to make it case insensitive	slapi_dn_ignore_case()
Determine if a DN is equal to a specified suffix	slapi_dn_issuffix()
Determine if a DN is the parent of a specific DN	slapi_dn_isparent()
Specify a distinguished name is a root	slapi_dn_isroot()
Determine if the a DN is the suffix of the local database	slapi_dn_isbesuffix()
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 compatible with older versions of Directory Server, all of the syntaxes in the above RFC's may not be supported.	slapi_dn_normalize()
Convert a DN to canonical format and all characters to lower case	slapi_dn_normalize_case()
Normalize part of a DN value	slapi_dn_normalize_to_end()
Get a copy of the DN of the parent of an entry	slapi_dn_beparent()
Get the DN of the parent of an entry	slapi_dn_parent()
Add an RDN to a DN	slapi_dn_plus_rdn()

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 do this...	Call this function
Generate an LDIF string description	slapi_entry2str()
Generate an LDIF string descriptions with options	slapi_entry2str_with_options()
Add components in an entry's RDN	slapi_entry_add_rdn_values()
Add a string value to an attribute in an entry	slapi_entry_add_string()
Add a data value to an attribute in an entry.	slapi_entry_add_value()
Add an array of data values to an attribute in an entry	slapi_entry_add_values_sv()
Add a data value to an attribute in an entry	slapi_entry_add_valueset()
Allocate memory for a entry structure	slapi_entry_alloc()
Delete an attribute from an entry	slapi_entry_attr_delete()
Check if an entry contains a specific attribute	slapi_entry_attr_find()
Get the first value as a string	slapi_entry_attr_get_charptr()
Get the values of a multi-valued attribute of an entry	slapi_entry_attr_get_charray()
Get the first value as an integer	slapi_entry_attr_get_int()
Get the first value as a long.	slapi_entry_attr_get_long()
Get the first value as an unsigned integer	slapi_entry_attr_get_uint()
Get the first value as an unsigned long	slapi_entry_attr_get_ulong()
Check if an attribute in an entry contains a value	slapi_entry_attr_has_syntax_value()
Adds an array to the attribute values in an entry	slapi_entry_attr_merge_sv()
Replaces the values of an attribute with a string	slapi_entry_attr_replace_sv()
Set the first value as a string	slapi_entry_attr_set_charptr())
Set the first value as an integer	slapi_entry_attr_set_int()
Set the first value as a long.	slapi_entry_attr_set_long()
Set the first value as an unsigned integer	slapi_entry_attr_set_uint()
Set the first value as an unsigned long	slapi_entry_attr_set_ulong()
Delete a string from an attribute.	slapi_entry_delete_string()
Removes a Slapi_Value array from an attribute	slapi_entry_delete_values_sv()
Copy an entry, its DN, and its attributes	slapi_entry_dup()
Find the first attribute in an entry	slapi_entry_first_attr()
Free an entry from memory	slapi_entry_free()
Get the DN from an entry	slapi_entry_get_dn()
Return the DN of an entry as a constant	slapi_entry_get_dn_const()
Return the normalized distinguished name (NDN) of an entry	slapi_entry_get_ndn()
Return the Slapi_DN from an entry	slapi_entry_get_sdn()
Return a Slapi_DN from an entry as a constant	slapi_entry_get_sdn_const()
Get the unique ID from an entry	slapi_entry_get_uniqueid()
Determine if the specified entry has child entries	slapi_entry_has_children()
Initializes the values of an entry	slapi_entry_init()
Adds an array of data values to an attribute in an entry	slapi_entry_merge_values_sv()
Find the next attribute in an entry	slapi_entry_next_attr()
Check if values present in an entry's RDN are also present as attribute values	slapi_entry_rdn_values_present()
Determine if an entry complies with the schema for its object class	slapi_entry_schema_check()
Set the DN of an entry	slapi_entry_set_dn()
Set the Slapi_DN value in an entry	slapi_entry_set_sdn()
Set the unique ID in an entry	slapi_entry_set_uniqueid()
Return the size of an entry	slapi_entry_size()
Determine if an entry is the root DSE	slapi_is_rootdse()
Convert an LDIF description into an entry	slapi_str2entry()

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

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

To do this...	Call this function
Determine if an entry matches a filter's criteria	slapi_filter_test_ext()
Get the filter type	slapi_filter_get_choice()
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)	slapi_filter_get_ava()
Get the type of attribute that the filter is searching for (only applicable to LDAP_FILTER_PRESENT searches)	slapi_filter_get_type()
Get the substring pattern used for the filter (applicable only to LDAP_FILTER_SUBSTRING searches)	slapi_filter_get_subfilt()
Convert a string representation of a filter to a filter of the data type Slapi_Filter	slapi_str2filter())
Construct a new LDAP_FILTER_AND, LDAP_FILTER_OR, or LDAP_FILTER_NOT filter from other filters	slapi_filter_join()
Get the components of a filter (only applicable to LDAP_FILTER_AND, LDAP_FILTER_OR, and LDAP_FILTER_NOT searches)	slapi_filter_list_first() slapi_filter_list_next()
Free a filter from memory	slapi_filter_free()

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 do this...	Call this function
Compare two berval structures to determine if they are equal	slapi_berval_cmp()
Call the indexer function associated with an extensible match filter	slapi_mr_filter_index()
Free the specified matching rule structure (and optionally, its members) from memory	slapi_matchingrule_free()
Get information about a matching rule	slapi_matchingrule_get()
Call the indexer factory function for the plug-in responsible for a specified matching rule	slapi_mr_indexer_create()
Allocate memory for a new Slapi_MatchingRuleEntry structure	slapi_matchingrule_new()
Register the specified matching rule with the server	slapi_matchingrule_register()
Set information about the matching rule	slapi_matchingrule_set()
Placeholder for future function (currently, this function does nothing.)	slapi_matchingrule_unregister()

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 do this...	Call this function
Add a value to a Slapi_Mod structure	slapi_mod_add_value()
Free internals of Slapi_Mod structure	slapi_mod_done()
Dump the contents of an LDAPMod to the server log	slapi_mod_dump()
Free a Slapi_Mod structure	slapi_mod_free()
Initialize a Slapi_Mod iterator and returns the first attribute value	slapi_mod_get_first_value()
Get a reference to the LDAPMod in a Slapi_Mod structure	slapi_mod_get_ldapmod_byref()
Retrieves the LDAPMod contained in a Slapi_Mod structure	slapi_mod_get_ldapmod_passout()
Increment the Slapi_Mod iterator and return the next attribute value	slapi_mod_get_next_value()
Get the number of values in a Slapi_Mod structure	slapi_mod_get_num_values()
Get the operation type of Slapi_Mod structure	slapi_mod_get_operation()
Get the attribute type of a Slapi_Mod structure	slapi_mod_get_type()
Initialize a Slapi_Mod structure	slapi_mod_init()
Initialize a Slapi_Mod structure that is a wrapper for an existing LDAPMod	slapi_mod_init_byref()
Initialize a modification by value	slapi_mod_init_byval()
Initialize a Slapi_Mod from an LDAPMod	slapi_mod_init_passin()
Determine whether a Slapi_Mod structure is valid	slapi_mod_isvalid()
Allocate a new Slapi_Mod structure	slapi_mod_new()
Removes the value at the current Slapi_Mod iterator position	slapi_mod_remove_value()
Set the operation type of a Slapi_Mod structure	slapi_mod_set_operation()
Set the attribute type of a Slapi_Mod	slapi_mod_set_type()

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 do this...	Call this function
Create a Slapi_Entry from an array of LDAPMod	slapi_mods2entry()
Append a new mod with a single attribute value to Slapi_Mods structure	slapi_mods_add()
Append an LDAPMod to a Slapi_Mods structure	slapi_mods_add_ldapmod()
Appends a new mod to a Slapi_Mods structure, with attribute values provided as an array of berval	slapi_mods_add_modbvps()
Append a new mod to a Slapi_Mods structure, with attribute values provided as an array of Slapi_Value	slapi_mods_add_mod_values()
Append a new mod to Slapi_Mods structure with a single attribute value provided as a string	slapi_mods_add_string()
Complete a modification	slapi_mods_done()
Dump the contents of a Slapi_Mods structure to the server log	slapi_mods_dump()
Frees a Slapi_Mods structure.	slapi_mods_free()
Initialize a Slapi_Mods iterator and return the first LDAPMod.	slapi_mods_get_first_mod()
Get a reference to the array of LDAPMod in a Slapi_Mods structure	slapi_mods_get_ldapmods_byref()
Retrieve the array of LDAPMod contained in a Slapi_Mods structure	slapi_mods_get_ldapmods_passout()
Increment the Slapi_Mods iterator and return the next LDAPMod	slapi_mods_get_next_mod()
Increment the Slapi_Mods iterator and return the next mod wrapped in a Slapi_Mods	slapi_mods_get_next_smod()
Get the number of mods in a Slapi_Mods structure	slapi_mods_get_num_mods()
Initialize a Slapi_Mods	slapi_mods_init()
Initialize a Slapi_Mods that is a wrapper for an existing array of LDAPMod	slapi_mods_init_byref()
Initialize a Slapi_Mods structure from an array of LDAPMod	slapi_mods_init_passin()
Insert an LDAPMod into a Slapi_Mods structure after the current iterator position