[Previous] [Next] [TOC] [Index]

Chapter 6
Adding and Updating Entries

he LDAP API includes functions that you can call to manipulate entries in the directory. For example, you can add a new entry to the directory or modify the attributes of an existing entry.

This chapter explains how to use the API functions to add, modify, delete, and manipulate entries in the directory. The chapter includes the following sections:

Specifying Changes to an Attribute

 In order to add or modify an entry in the directory, you need to specify information about the entry's attributes:

In most of the cases above, you need to specify the following attribute information:

To specify this information, you use an LDAPMod structure. 

typedef struct ldapmod {
   int mod_op;
   char *mod_type;
   union {
      char **modv_strvals;
      struct berval **modv_bvals;
   } mod_vals;
} LDAPMod;
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: In addition, if you are specifying binary values (as opposed to strings), you should use the bitwise OR operator ( | ) to combine LDAP_MOD_BVALUES with the operation type. For example:

mod->mod_op = LDAP_MOD_ADD | LDAP_MOD_BVALUES

NOTE: If you are using the structure to add a new entry, you can specify 0 as the value for this field (unless you are adding binary values and need to specify LDAP_MOD_BVALUES). See "Adding a New Entry" for details.

mod_type The attribute type that you want to add, delete, or replace (for example, "sn" or "telephoneNumber").
mod_values A pointer to a NULL-terminated array of string values for the attribute. Although this does not appear in the structure definition, it is defined in the ldap.h header file as mod_vals.modv_strvals.
mod_bvalues A pointer to a NULL-terminated array of berval structures for the attribute. Although this does not appear in the structure definition, it is defined in the ldap.h header file as mod_vals.modv_bvals.

If you've allocated memory for the structures yourself, you should free the structures when you're finished by calling the ldap_mods_free() function.

The following sections show how to set up LDAPMod structures to add and modify entries in the directory.

Adding a New Entry

Suppose you want to add an entry with the following attributes: 

cn: Barbara Jensen
cn: Babs Jensen
sn: Jensen
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
jpegPhoto: (JPEG data for photograph of Babs)
To add this entry, you need to follow this general procedure:

  1. Specify the values of each attribute. To do this, you need to create an LDAPMod structure for each attribute.

  2. Assemble a list of the attributes to be included in the new entry. To do this, you need to construct an array of the LDAPMod structures that you created in the previous step.

  3. Specify a distinguished name for the entry, and add the entry with its attributes to the directory.

Specifying the Values of an Attribute

 An attribute can have a single value or multiple values and can contain string values or binary data. This section describes the process of specifying the values of an attribute.

Specifying a Single Value in an Attribute

 To specify a value in an attribute, set the mod_op, mod_type, and mod_values fields in an LDAPMod structure. (See the section "Specifying Changes to an Attribute" for a brief overview of this structure.)

The following section of code sets up the structure for the sn attribute: 

#include <ldap.h>
...
LDAPMod attribute1;
char *sn_values[] = { "Jensen", NULL };
...
attribute1.mod_op = 0;
attribute1.mod_type = "sn";
attribute1.mod_values = sn_values;
...
Note that because you are specifying an attribute for a new entry (rather than for an existing entry), you can set the mod_op field to 0. (For an existing entry, the mod_op field identifies the type of change you are making to the entry.)

Specifying Multiple Values in an Attribute

If an attribute has more than one value, specify the values in the mod_values array. This example specifies two values for the cn attribute:

#include <ldap.h>
...
LDAPMod attribute2, attribute3;
char *cn_values[] = { "Barbara Jensen", "Babs Jensen", NULL };
char *objectClass_values[] = { "top", "person", "organizationalPerson", "inetOrgPerson", NULL };
...
attribute2.mod_op = 0;
attribute2.mod_type = "cn";
attribute2.mod_values = cn_values;
attribute3.mod_op = 0;
attribute3.mod_type = "objectClass";
attribute3.mod_values = objectClass_values;
...

Specifying Binary Data as the Values of an Attribute

 If the attribute contains binary data (rather than string values), specify the data in a berval structure:

struct berval {
   unsigned long bv_len;
   char *bv_val;
}
bv_len The length of the data.
bv_val A pointer to the binary data.
After creating the berval structures for the binary data, you need to do the following:

For example, suppose the file my_photo.jpg contains a JPEG photograph of Barbara Jensen. The following example sets the jpegPhoto attribute to the JPEG data of the photograph. 

#include <stdio.h>
#include <sys/stat.h>
#include <ldap.h>
...
char *photo_data;
FILE *fp;
struct stat st;
LDAPMod attribute4;
struct berval photo_berval;
struct berval *jpegPhoto_values[2];
/* Get information about the JPEG file, including its size. */
if ( stat( "my_photo.jpg", &st ) != 0 ) {
   perror( "stat" );
   return( 1 );
}

/* Open the JPEG file and read it into memory. */
if ( ( fp = fopen( "my_photo.jpg", "rb" ) ) == NULL ) {
   perror( "fopen" );
   return( 1 );
}
if ( ( ( photo_data = ( char * )malloc( st.st_size ) ) == NULL ) || 
         ( fread ( photo_data, st.st_size, 1, fp ) != 1 ) ) {
   perror( photo_data ? "fread" : "malloc" );
   return( 1 );
}

fclose( fp );

attribute4.mod_op = LDAP_MOD_BVALUES;
attribute4.mod_type = "jpegPhoto";
photo_berval.bv_len = st.st_size;
photo_berval.bv_val = photo_data;
jpegPhoto_values[0] = &photo_berval;
jpegPhoto_values[1] = NULL;
attribute4.mod_values = jpegPhoto_values;

Specifying the Attributes in the Entry

 After specifying the values of attributes in LDAPMod structures, you need to construct an array of these structures. (You will pass a pointer to this array as a parameter to the LDAP API function for creating a new entry.)

NOTE: Make sure that you created LDAPMod structures for all required attributes in the new entry. For information on which attributes are required, see Appendix B, "Entries and Attributes."
The following section of code creates an array of LDAPMod structures: 

#include <ldap.h>
LDAPMod *list_of_mods[5];
LDAPMod attribute1, attribute2, attribute3, attribute4;
...
/* Code for filling the LDAPMod structures with values */
...
list_of_mods[0] = &attribute1;
list_of_mods[1] = &attribute2;
list_of_mods[2] = &attribute3;
list_of_mods[3] = &attribute4;
list_of_mods[4] = NULL;
...

Adding the Entry to the Directory

 To add the entry to the directory, call one of the following functions:

(For more information about the difference between synchronous and asynchronous functions, see "Synchronous and Asynchronous Functions".)

If you've allocated LDAPMod structures yourself, you should free the structures when you're finished using them. To free these LDAPMod structures, call the ldap_mods_free() function.

NOTE: Before you add an entry, you should make sure that you've defined all required attributes for the entry type. For a listing of the required attributes for the different types of entries, see Appendix B, "Entries and Attributes."

Performing a Synchronous Add Operation

 If you want the add operation to complete before continuing, call the synchronous ldap_add_s() function. The ldap_add_s() function returns LDAP_SUCCESS if the operation completed successfully or an error code if a problem occurred. (See "Status Codes" for a complete listing.)

The following section of code uses the synchronous ldap_add_s() function to add the user Barbara Jensen to the directory. 


#include <ldap.h>
...
LDAP *ld;
LDAPMod *list_of_attrs[4];
LDAPMod attribute1, attribute2, attribute3;

/* Distinguished name of the new entry. Note that "Ace Industry" and "US" must already exist in the directory. */
char *dn = "cn=Barbara Jensen, o=Ace Industry, c=US";

/* To add a "person" entry, you must specify values for the sn, cn, and objectClass attributes. (These are required attributes for the inetOrgPerson object class.) */
char *sn_values[] = { "Jensen", NULL };

/* To specify multiple values for an attribute, add the different values to the array. */ 
char *cn_values[] = { "Barbara Jensen", "Babs Jensen", NULL };

/* The object class for a "person" entry is "inetOrgPerson", which is a subclass of "top", "person", and "organizationalPerson". You should add all of these classes as values of the objectClass attribute. */
char *objectClass_values[] = { "top", "person", "organizationalPerson", "inetOrgPerson", NULL };
...
/* Specify the value and type of each attribute in separate LDAPMod structures. */
attribute1.mod_type = "sn";
attribute1.mod_values = sn_values;
attribute2.mod_type = "cn";
attribute2.mod_values = cn_values;
attribute3.mod_type = "objectClass";
attribute3.mod_values = objectClass_values;

/* Add the pointers to these LDAPMod structures to an array. */
list_of_attrs[0] = &attribute1;
list_of_attrs[1] = &attribute2;
list_of_attrs[2] = &attribute3;
list_of_attrs[3] = NULL;
...
/* Add the user "Barbara Jensen". */
if ( ldap_add_s( ld, dn, list_of_attrs ) != LDAP_SUCCESS ) {
   ldap_perror( ld, "ldap_add_s" );
   return( 1 );
}
...

Performing an Asynchronous Add Operation

 If you want to perform other work (in parallel) while waiting for the entry to be added, call the asynchronous ldap_add() function. The ldap_add() function returns a message ID identifying the add operation. To determine whether the operation has completed or is still in progress, call the ldap_result() function.

After the operation is completed, call the ldap_result2error() function to determine if the operation was successful. The ldap_result2error() function returns LDAP_SUCCESS if the operation completed successfully or an error code if a problem occurred. (See "Status Codes" for a complete listing.)

The following section of code calls ldap_add() to add the user Barbara Jensen to the directory. 


#include <ldap.h>
...
LDAP *ld;
LDAPMod *list_of_attrs[4];
LDAPMod attribute1, attribute2, attribute3;
LDAPMessage *result;
int msgid, rc;
struct timeval tv;

/* Distinguished name of the new entry. Note that "Ace Industry" and "US" must already exist in the directory. */
char *dn = "cn=Barbara Jensen, o=Ace Industry, c=US";

/* To add a "person" entry, you must specify values for the sn, cn, and objectClass attributes. (These are required attributes for the inetOrgPerson object class.) */
char *sn_values[] = { "Jensen", NULL };

/* To specify multiple values for an attribute, add the different values to the array. */ 
char *cn_values[] = { "Barbara Jensen", "Babs Jensen", NULL };

/* The object class for a "person" entry is "inetOrgPerson", which is a subclass of "top", "person", and "organizationalPerson". You should add all of these classes as values of the objectClass attribute. */
char *objectClass_values[] = { "top", "person", "organizationalPerson", "inetOrgPerson", NULL };
...
/*Specify the value and type of each attribute in a LDAPMod structure.*/
attribute1.mod_type = "sn";
attribute1.mod_values = sn_values;
attribute2.mod_type = "cn";
attribute2.mod_values = cn_values;
attribute3.mod_type = "objectClass";
attribute3.mod_values = objectClass_values;

/* Add the pointers to these LDAPMod structures to an array. */
list_of_attrs[0] = &attribute1;
list_of_attrs[1] = &attribute2;
list_of_attrs[2] = &attribute3;
list_of_attrs[3] = NULL;
...
/* Set up the timeout period for adding the new entry. */
tv.tv_sec = tv.tv_usec = 0;

/* Add the user "Barbara Jensen". */
if ( ( msgid = ldap_modify( ld, dn, list_of_attrs ) ) == -1 ) {
   ldap_perror( ld, "ldap_add" );
   return( 1 );
}

/* Check whether the operation has completed. */
while ( ( rc = ldap_result( ld, msgid, 0, &tv, &result ) ) == 0 ) {
   /* Do other work while waiting for the operation to complete. */
}

/* Check whether any errors occurred. */
ldap_result2error( ld, result, 1 );
ldap_perror( ld, "ldap_add" );
...

Modifying an Existing Entry

 Suppose you want to modify the following entry: 

cn: Barbara Jensen 
cn: Babs Jensen 
sn: Jensen 
objectClass: top 
objectClass: person 
objectClass: organizationalPerson 
objectClass: inetOrgPerson 
jpegPhoto: (JPEG data for photograph of Babs)
telephoneNumber: 555-1212
facsimileTelephoneNumber: 555-2000
Suppose you want to make the following changes to the entry:

To modify this entry, you need to follow this general procedure:

  1. Specify each change to an attribute that needs to be made. To do this, you need to create an LDAPMod structure for each attribute that needs to be added, modified, or deleted.

  2. Assemble the list of the changes that need to be made to the entry. To do this, you need to construct an array of the LDAPMod structures that you created in the previous step.

  3. Use the distinguished name of the entry to find and update the entry in the directory.
After you are done modifying entries to the directory, you should free the LDAPMod structures you've allocated by calling the ldap_mods_free() function.

Specifying the Changes to an Attribute

You can change an entry by adding a new attribute, removing an existing attribute, or by changing the values of an existing attribute. This section describes the process of specifying changes to an entry.

Changing the Values of an Attribute

 To change the values of an attribute, specify the change in an LDAPMod structure. In this structure, you need to do the following:

If the attribute contains binary data (as opposed to string values), you need to do the following:

The following section of code specifies a change to the values of the telephoneNumber attribute. 


#include <ldap.h>
LDAPMod attribute1;
char *telephoneNumber_values[] = { "555-1967", NULL };
attribute1.mod_type = "telephoneNumber";
attribute1.mod_op = LDAP_MOD_REPLACE;
attribute1.mod_values = telephoneNumber_values;

Removing an Attribute

 To remove an attribute from an entry, specify the removal in an LDAPMod structure. In this structure, you need to do the following:

You do not need to assign values to the mod_values or mod_bvalues fields.

The following example specifies the removal of the facsimileTelephoneNumber attribute from the entry:


#include <ldap.h>
LDAPMod attribute2;
attribute2.mod_type = "facsimileTelephoneNumber";
attribute2.mod_op = LDAP_MOD_DELETE;
...

Adding an Attribute

 To add an attribute to an entry, specify the addition in an LDAPMod structure. In this structure, you need to do the following:

If the attribute contains binary data (as opposed to string values), you need to do the following:

The following example adds the audio attribute to an entry: 


#include <stdio.h>
#include <sys/stat.h>
#include <ldap.h>
...
char *audio_data;
FILE *fp;
struct stat st;
LDAPMod attribute3;
struct berval audio_berval;
struct berval *audio_values[2];
...
/* Get information about the audio file, including its size. */
if ( stat( "my_sounds.au", &st ) != 0 ) {
   perror( "stat" );
   return( 1 );
}

/* Open the audio file and read it into memory. */
if ( ( fp = fopen( "my_sounds.au", "rb" ) ) == NULL ) {
   perror( "fopen" );
   return( 1 );
}

if ( ( ( audio_data = ( char * )malloc( st.st_size ) ) == NULL ) || 
         ( fread ( audio_data, st.st_size, 1, fp ) != 1 ) ) {
   perror( audio_data ? "fread" : "malloc" );
   return( 1 );
}

fclose( fp );
attribute3.mod_op = LDAP_MOD_ADD | LDAP_MOD_BVALUES;
attribute3.mod_type = "audio";
audio_berval.bv_len = st.st_size;
audio_berval.bv_val = audio_data;
audio_values[0] = &audio_berval;
audio_values[1] = NULL;
attribute3.mod_values = audio_values;
...

Assembling the List of Changes

 After specifying the changes to attribute values in LDAPMod structures, you need to construct an array of these structures. (You will pass a pointer to this array as a parameter to the LDAP API function for modifying the entry.)

The following section of code creates an array of LDAPMod structures: 


#include <ldap.h>
...
LDAPMod *list_of_mods[4]
LDAPMod attribute1, attribute2, attribute3;
...
/* Code for filling the LDAPMod structures with values */
...
list_of_mods[0] = &attribute1;
list_of_mods[1] = &attribute2;
list_of_mods[2] = &attribute3;
list_of_mods[3] = NULL;
...

Modifying the Entry in the Directory

 To modify the entry in the directory, call one of the following functions:

(For more information about the difference between synchronous and asynchronous functions, see "Synchronous and Asynchronous Functions".)

Performing a Synchronous Modify Operation

If you want the modify operation to complete before continuing, call the synchronous ldap_modify_s() function. The ldap_modify_s() function returns LDAP_SUCCESS if the operation completed successfully or an error code if a problem occurred. (See "Status Codes" for a complete listing.)

The following section of code uses the synchronous ldap_modify_s() function to modify the Barbara Jensen entry in the directory. The example makes these changes to the entry:


#include <ldap.h>
...
LDAP *ld;
LDAPMod *list_of_attrs[4];
LDAPMod attribute1, attribute2, attribute3;

/* Distinguished name of the entry that you want to modify */
char *dn = "cn=Barbara Jensen, o=Ace Industry, c=US";
/* Values to add or change */
char *homePhone_values[] = { "555-1212", NULL };
char *telephoneNumber_values[] = { "555-1967", NULL };

...
/* Specify each change in separate LDAPMod structures. */
attribute1.mod_type = "homePhone";
attribute1.mod_op = LDAP_MOD_ADD;
attribute1.mod_values = homePhone_values;
attribute2.mod_type = "telephoneNumber";
attribute2.mod_op = LDAP_MOD_REPLACE;
attribute2.mod_values = telephoneNumber_values;
attribute3.mod_type = "facsimileTelephoneNumber";
attribute3.mod_op = LDAP_MOD_DELETE;
attribute3.mod_values = NULL;
/* NOTE: When removing attributes, you need to specify a value of NULL for the mod_values field. */

/* Add the pointers to these LDAPMod structures to an array. */
list_of_attrs[0] = &attribute1;
list_of_attrs[1] = &attribute2;
list_of_attrs[2] = &attribute3;
list_of_attrs[3] = NULL;
...
/* Change the entry. */
if ( ldap_modify_s( ld, dn, list_of_attrs ) != LDAP_SUCCESS ) {
   ldap_perror( ld, "ldap_modify_s" );
   return( 1 );
}
...

Performing an Asynchronous Modify Operation

 If you want to perform other work (in parallel) while waiting for the entry to be updated in the directory, call the asynchronous ldap_modify() function. The ldap_modify() function returns a message ID identifying the modify operation. To determine whether the operation has completed or is still in progress, call the ldap_result() function.

After the operation is completed, call the ldap_result2error() function to determine if the operation was successful. The ldap_result2error() function returns LDAP_SUCCESS if the operation completed successfully or an error code if a problem occurred. (See "Status Codes" for a complete listing.)

The following section of code uses the asynchronous ldap_modify() function to modify the Barbara Jensen entry in the directory. The example makes the following changes to the entry:


#include <ldap.h>
LDAP *ld;
LDAPMod *list_of_attrs[4];
LDAPMod attribute1, attribute2, attribute3;
LDAPMessage *result;
int msgid, rc;
struct timeval tv;

/* Distinguished name of the entry that you want to modify */
char *dn = "cn=Barbara Jensen, o=Ace Industry, c=US";

/* Values to add or change */
char *homePhone_values[] = { "555-1212", NULL };
char *telephoneNumber_values[] = { "869-5309", NULL };
/* Specify each change in separate LDAPMod structures. */
attribute1.mod_type = "homePhone";
attribute1.mod_op = LDAP_MOD_ADD;
attribute1.mod_values = homePhone_values;
attribute2.mod_type = "telephoneNumber";
attribute2.mod_op = LDAP_MOD_REPLACE;
attribute2.mod_values = telephoneNumber_values;
attribute3.mod_type = "facsimileTelephoneNumber";
attribute3.mod_op = LDAP_MOD_DELETE;
attribute3.mod_values = NULL;
/* NOTE: When removing attributes, you need to specify a NULL value for the mod_values field. */

/* Add the pointers to these LDAPMod structures to an array. */
list_of_attrs[0] = &attribute1;
list_of_attrs[1] = &attribute2;
list_of_attrs[2] = &attribute3;
list_of_attrs[3] = NULL;
/* Set up the timeout period to wait for the modify operation. In this example, the client continuously polls for results. */
tv.tv_sec = tv.tv_usec = 0;

/* Change the entry. */
if ( ( msgid = ldap_modify( ld, dn, list_of_attrs ) ) == -1 ) {
   ldap_perror( ld, "ldap_modify" );
   return( 1 );
}

/* Check whether the operation has completed. */
while ( ( rc = ldap_result( ld, msgid, 0, &tv, &result ) ) == 0 ) {
   /* Do other work while waiting for the operation to complete. */
}
/* Check whether any errors occurred. */
ldap_result2error( ld, result, 1 );
ldap_perror( ld, "ldap_modify" );
...

Deleting an Entry

 To remove an entry from the directory, call one of the following functions:

the ldap_delete() or ldap_delete_s() function.

(For more information about the difference between synchronous and asynchronous functions, see "Synchronous and Asynchronous Functions".)

Performing a Synchronous Delete Operation

If you want the delete operation to complete before continuing, call the synchronous ldap_delete_s() function. The ldap_delete_s() function returns LDAP_SUCCESS if the operation completed successfully or an error code if a problem occurred. (See "Status Codes" for a complete listing.)

The following section of code uses the synchronous ldap_delete_s() function to delete the Barbara Jensen entry from the directory. 


#include <ldap.h>
...
LDAP *ld;

/* Distinguished name of the entry that you want to delete */
char *dn = "cn=Barbara Jensen, o=Ace Industry, c=US";
/* Delete the entry. */
if ( ldap_delete_s( ld, dn ) != LDAP_SUCCESS ) {
   ldap_perror( ld, "ldap_delete_s" );
   return( 1 );
}
...

Performing an Asynchronous Delete Operation

 If you want to perform other work (in parallel) while waiting for the entry to be removed, call the asynchronous ldap_delete() function. The ldap_delete() function returns a message ID identifying the delete operation. To determine whether the operation has completed or is still in progress, call the ldap_result() function.

After the operation is completed, call the ldap_result2error() function to determine if the operation was successful. The ldap_result2error() function returns LDAP_SUCCESS if the operation completed successfully or an error code if a problem occurred. (See "Status Codes" for a complete listing.)

The following section of code uses the asynchronous ldap_delete() function to remove the Barbara Jensen entry from the directory. 


#include <ldap.h>
...
LDAP *ld;
LDAPMessage *result;
int msgid, rc;
struct timeval tv;

/* Distinguished name of the entry that you want to delete */
char *dn = "cn=Barbara Jensen, o=Ace Industry, c=US";
...
/* Set up the timeout period to wait for the delete operation */
tv.tv_sec = tv.tv_usec = 0;

/* Delete the entry. */
if ( ( msgid = ldap_delete( ld, dn ) ) == -1 ) {
   ldap_perror( ld, "ldap_delete" );
   return( 1 );
}

/* Check whether the operation has completed */
while ( ( rc = ldap_result( ld, msgid, 0, &tv, &result ) ) == 0 ) {
   ...
   /* Do other work while waiting for the operation to complete. */
   ...
}

/* Check whether any errors occurred. */
ldap_result2error( ld, result, 1 );
ldap_perror( ld, "ldap_delete" );
...

Changing the Name of an Entry

To change the relative distinguished name (RDN) of an entry, call one of the following functions:

(For more information about the difference between synchronous and asynchronous functions, see "Synchronous and Asynchronous Functions".)

Both functions have a deleteoldrdn parameter that allows you to remove the old RDN from the entry. The deleteoldrdn parameter is best explained through this example. Suppose an entry has the following values for the cn attribute: 


   cn: Barbara Jensen
   cn: Babs Jensen
The following function call adds "Barbie Jensen" to this list of values and removes the "Barbara Jensen" value:


   ldap_modrdn2( "cn=Barbara Jensen", "cn=Barbie Jensen", 1 );
The resulting entry has the following values:


   cn: Barbie Jensen
   cn: Babs Jensen
If instead a 0 is passed for the deleteoldrdn parameter:


   ldap_modrdn2( "cn=Barbara Jensen", "cn=Barbie Jensen", 0 );
the "Barbara Jensen" value is not removed from the entry:


   cn: Barbie Jensen
   cn: Babs Jensen
   cn: Barbara Jensen

Performing a Synchronous Renaming Operation

 If you want the renaming operation to complete before continuing, call the synchronous ldap_modrdn2_s() function. The ldap_modrdn2_s() function returns LDAP_SUCCESS if the operation completed successfully or an error code if a problem occurred. (See "Status Codes" for a complete listing.)

The following section of code uses the synchronous ldap_modrdn2_s() function to change the RDN of an entry from "cn=Barbara Jensen" to "cn=Barbie Jensen". The code removes the existing RDN "cn=Barbara Jensen" from the entry. 


#include <ldap.h>
...
LDAP *ld;
/* Distinguished name of the entry that you want to rename */
char *dn = "cn=Barbara Jensen, o=Ace Industry, c=US";

/* New relative distinguished name (RDN) of the entry */
char *rdn = "cn=Barbie Jensen";
...
/* Rename the entry */
if ( ldap_modrdn2_s( ld, dn, rdn, 1 ) != LDAP_SUCCESS ) {
   ldap_perror( ld, "ldap_modrdn2_s" );
   return( 1 );
}
...

Performing an Asynchronous Renaming Operation

 If you want to perform other work (in parallel) while waiting for the entry to be renamed, call the asynchronous ldap_modrdn2() function. The ldap_modrdn2() function returns a message ID identifying the renaming operation. To determine whether the operation has completed or is still in progress, call the ldap_result() function.

After the operation is completed, call the ldap_result2error() function to determine if the operation was successful. The ldap_result2error() function returns LDAP_SUCCESS if the operation completed successfully or an error code if a problem occurred. (See "Status Codes" for a complete listing.)

The following section of code uses the asynchronous ldap_modrdn2() function to change the RDN of an entry from "cn=Barbara Jensen" to "cn=Barbie Jensen". The code removes the existing RDN "cn=Barbara Jensen" from the entry.


#include <ldap.h>
LDAP *ld;
LDAPMessage *result;
int msgid, rc;
struct timeval tv;
/* Distinguished name of the entry that you want to rename */
char *dn = "cn=Barbara Jensen, o=Ace Industry, c=US";

/* New relative distinguished name (RDN) of the entry */
char *rdn = "cn=Barbie Jensen";
...
/* Set up the timeout period to wait for the renaming operation. */
tv.tv_sec = tv.tv_usec = 0;

/* Rename the entry. */
if ( ( msgid = ldap_modrdn2( ld, dn, rdn, 1 ) ) == -1 ) {
   ldap_perror( ld, "ldap_modrdn2" );
   return( 1 );
}

/* Check whether the operation has completed. */
while ( ( rc = ldap_result( ld, msgid, 0, &tv, &result ) ) == 0 ) {
   ...
   /* Do other work while waiting for the operation to complete. */
   ...
}

/* Check whether any errors occurred. */
ldap_result2error( ld, result, 1 );
ldap_perror( ld, "ldap_modrdn2" );
...

Comparing the Value of an Attribute

 To determine if an attribute contains a certain value, call one of the following functions:

(For more information about the difference between synchronous and asynchronous functions, see "Synchronous and Asynchronous Functions".)

Performing a Synchronous Comparison Operation

If you want the comparison operation to complete before continuing, call the synchronous ldap_compare_s() function. The ldap_compare_s() function returns one of the following values after the operation has completed:

The following section of code uses the synchronous ldap_compare_s() function to determine whether Barbara Jensen's entry has the email address babs@ace.com (in other words, whether the mail attribute is babs@ace.com). 


#include <ldap.h>
LDAP *ld;
int rc; 

/* Distinguished name of the entry that you want to check */
char *dn = "cn=Barbara Jensen, o=Ace Industry, c=US";
/* Check for the value "babs@ace.com" in the "mail" attribute. */
rc = ldap_compare_s( ld, dn, "mail", "babs@ace.com ) 
switch( rc ) {
   case LDAP_COMPARE_TRUE:
      printf( "The value \"babs@ace.com\" is in the mail attribute." );
      break;
   case LDAP_COMPARE_FALSE:
      printf("The value \"babs@ace.com\" is not in the mail attribute");
      break;
   default:
      ldap_perror( ld, "ldap_compare_s" );
}
...

Performing an Asynchronous Comparison Operation

 If you want to perform other work (in parallel) while waiting for the results of the comparison, call the asynchronous ldap_compare() function. The ldap_compare() function returns a message ID identifying the comparison operation. To determine whether the operation has completed or is still in progress, call the ldap_result() function.

After the operation is completed, call the ldap_result2error() function to determine if the operation was successful. The ldap_result2error() function returns one of the following values after the operation is completed:

The following section of code uses the asynchronous ldap_compare() function to determine whether Barbara Jensen's entry has the email address babs@ace.com. 


#include <ldap.h>
...
LDAP *ld;
LDAPMessage *result;
int msgid, rc;
struct timeval tv;
/* Distinguished name of the entry that you want to check */
char *dn = "cn=Barbara Jensen, o=Ace Industry, c=US";
...
/* Set up the timeout period to wait for the comparison operation */
tv.tv_sec = tv.tv_usec = 0;

/* Check for the value "babs@ace.com" in the "mail" attribute. */
if ( ( msgid = ldap_compare( ld, dn, "mail", "babs@ace.com") ) == -1 ) {
   ldap_perror( ld, "ldap_compare" );
   return( 1 );
}

/* Check whether the operation has completed. */
while ( ( rc = ldap_result( ld, msgid, 0, &tv, &result ) ) == 0 ) {
   ...
   /* Do other work while waiting for the operation to complete. */
   ...
}

/* Check whether any errors occurred. */
switch ( ldap_result2error( ld, result, 1 ) ) {
   case LDAP_COMPARE_TRUE:
      printf( "The value \"babs@ace.com\" is in the mail attribute." );
      break;
   case LDAP_COMPARE_FALSE:
      printf( "The value \"babs@ace.com\" is not in the mail attribute." );
      break;
   default:
      ldap_perror( ld, "ldap_compare" );
}

[Previous] [Next] [TOC] [Index]

Last modified: March 31, 1997
Copyright © 1997 Netscape Communications Corporation