Table of Contents | Previous | Next | Index

Netscape Directory SDK 3.0 for C Programmer’s Guide

Chapter 8
Adding, Updating, and Deleting Entries

This chapter explains how to use the API functions to add, modify, delete, and rename entries in the directory. The chapter also provides examples of calling synchronous and asynchronous functions to perform these operations.

The chapter includes the following sections:

Specifying a New or Modified 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;
#define mod_values                        mod_vals.modv_strvals
#define mod_bvalues                        mod_vals.modv_bvals
} 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 in the mod_bvalues field, 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 for the mod_op 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 the values of (for example, "sn" or "telephoneNumber"). 

mod_values

A pointer to a NULL-terminated array of string values for the attribute. 

mod_bvalues

A pointer to a NULL-terminated array of berval structures for the attribute.

Note the following:

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.

For information on how to set up LDAPMod structures to add and modify entries in the directory, see the sections "Specifying the Attributes" and "Specifying the Changes."

Adding a New Entry

To add an entry to the directory:

  1. Create an array of LDAPMod structures to represent the attributes in the entry. Use the LDAPMod structure to specify the name and values of each attribute.

  2. Call the ldap_add_ext() or ldap_add_ext_s(), passing in the array of LDAPMod structures and a distinguished name for the entry.
After you are done, call the ldap_mods_free() function to free any LDAPMod structures you've allocated.

Specifying the Attributes

This section describes the process of specifying the attributes and values of the new entry.

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 a New or Modified 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 the documentation for your LDAP server. (For example, if you are using the Netscape Directory Server, see the chapters on object classes and attributes in the Netscape Directory Server Administrator's Guide.)
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 "Calling Synchronous and Asynchronous Functions.")

If you've allocated LDAPMod structures yourself, you should free the structures when you are done. Call the ldap_mods_free() function to free LDAPMod structures.

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 the documentation for your LDAP server. (For example, for the Netscape Directory Server, see the chapters on object classes and attributes in the Netscape Directory Server Administrator's Guide.)

Performing a Synchronous Add Operation

If you want to wait for the results of the add operation to complete before continuing, call the synchronous ldap_add_ext_s() function. This function sends an LDAP add request to the server and blocks until the server sends the results of the operation back to your client.

The ldap_add_ext_s() function returns LDAP_SUCCESS if the operation completed successfully or an error code if a problem occurred. See the documentation on the ldap_add_ext_s() function for a list of the possible result codes.

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

...
#include <stdio.h>
#include "ldap.h"
...
#define NEW_DN "uid=wbjensen,ou=People,o=Airius.com"
...
LDAP         *ld;
LDAPMod         **mods;
char         *matched_msg = NULL, *error_msg = NULL;
int         rc;
...
/* Perform the add operation. */
rc = ldap_add_ext_s( ld, NEW_DN, mods, NULL, NULL );
if ( rc != LDAP_SUCCESS ) {
   fprintf( stderr, "ldap_add_ext_s: %s\n", ldap_err2string( rc ) );
   ldap_get_lderrno( ld, &matched_msg, &error_msg );
   if ( error_msg != NULL && *error_msg != '\0' ) {
      fprintf( stderr, "%s\n", error_msg );
   }
   if ( matched_msg != NULL && *matched_msg != '\0' ) {
      fprintf( stderr, 
         "Part of the DN that matches an existing entry: %s\n", 
         matched_msg );
   }
} else {
   printf( "%s added successfully.\n", NEW_DN );
}
...

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_ext() function. This function sends an LDAP add request to the server and returns an LDAP_SUCCESS result code if the request was successfully sent (or an LDAP result code if an error occurred).

The ldap_add_ext() function passes back a message ID identifying the add operation. To determine whether the server sent a response for this operation to your client, call the ldap_result() function and pass in this message ID. The ldap_result() function uses the message ID to determine if the server sent the results of the add operation. The function passes back the results in an LDAPMessage structure.

You can call the ldap_parse_result() function to parse the LDAPMessage structure to determine if the operation was successful. (For a list of possible result codes for an LDAP add operation, see the result code documentation for the ldap_add_ext_s() function.)

The following section of code calls ldap_add_ext() to add the user William Jensen to the directory. 

...
#include <stdio.h>
#include "ldap.h"
...
#define NEW_DN "uid=wbjensen,ou=People,o=Airius.com"
...
LDAP         *ld;
LDAPMessage      *res;
LDAPControl      **serverctrls;
char         *matched_msg = NULL, *error_msg = NULL;
char         **referrals;
int            i, rc, parse_rc, msgid, finished = 0;
/* Timeout period for the ldap_result() function to wait for results. */
struct timeval   zerotime;
zerotime.tv_sec = zerotime.tv_usec = 0L;
...
/* Send the LDAP add request. */
rc = ldap_add_ext( ld, NEW_DN, mods, NULL, NULL, &msgid );
if ( rc != LDAP_SUCCESS ) {
   fprintf( stderr, "ldap_add_ext: %s\n", ldap_err2string( rc ) );
   ldap_unbind( ld );
   return( 1 );
}
...
/* Poll the server for the results of the add operation. */
while ( !finished ) {
   rc = ldap_result( ld, msgid, 0, &zerotime, &res );
   switch ( rc ) {
   case -1:
      /* An error occurred. */
      rc = ldap_get_lderrno( ld, NULL, NULL );
      fprintf( stderr, "ldap_result: %s\n", ldap_err2string( rc ) );
      ldap_unbind( ld );
      return( 1 );
   case 0:
      /* The timeout period specified by zerotime was exceeded, 
         so call ldap_result() again and continue polling. */
      break;
   default:
      /* The function has retrieved the results of the add operation. */
      finished = 1;
      /* Parse the result to determine the result of 
         the add operation. */
      parse_rc = ldap_parse_result( ld, res, &rc, &matched_msg, 
         &error_msg, &referrals, &serverctrls, 1 );
      if ( parse_rc != LDAP_SUCCESS ) {
         fprintf( stderr, "ldap_parse_result: %s\n", 
            ldap_err2string( parse_rc ) );
         ldap_unbind( ld );
         return( 1 );
      }
      /* Check the results of the LDAP add operation. */
      if ( rc != LDAP_SUCCESS ) {
         fprintf( stderr, "ldap_add_ext: %s\n", ldap_err2string( rc ) );
         if ( error_msg != NULL & *error_msg != '\0' ) {
            fprintf( stderr, "%s\n", error_msg );
         }
         if ( matched_msg != NULL && *matched_msg != '\0' ) {
            fprintf( stderr, 
               "Part of the DN that matches an existing entry: %s\n", 
               matched_msg );
         }
      } else {
         printf( "%s added successfully.\n", NEW_DN );
      }
   }
}
...

Example: Adding an Entry to the Directory (Synchronous)

The following sample program calls the synchronous ldap_add_ext_s() function to add a new user to the directory. 

#include <stdio.h>
#include "ldap.h"
/* Change these as needed. */
#define HOSTNAME "localhost"
#define PORTNUMBER LDAP_PORT
#define BIND_DN "cn=Directory Manager"
#define BIND_PW "23skidoo"
#define NEW_DN "uid=wbjensen,ou=People,o=Airius.com"
#define   NUM_MODS 5
int
main( int argc, char **argv )
{
    LDAP         *ld;
    LDAPMod         **mods;
   char         *matched_msg = NULL, *error_msg = NULL;
    int            i, rc;
    char *object_vals[] = { "top", "person", "organizationalPerson", "inetOrgPerson", NULL };
    char *cn_vals[] = { "William B Jensen", "William Jensen", "Bill Jensen", NULL };
    char *sn_vals[] = { "Jensen", NULL };
    char *givenname_vals[] = { "William", "Bill", NULL };
    char *telephonenumber_vals[] = { "+1 415 555 1212", NULL };
    /* Get a handle to an LDAP connection. */
    if ( (ld = ldap_init( HOSTNAME, PORTNUMBER )) == NULL ) {
      perror( "ldap_init" );
      return( 1 );
    }
    /* Bind to the server as the Directory Manager. */
    rc = ldap_simple_bind_s( ld, BIND_DN, BIND_PW );
   if ( rc != LDAP_SUCCESS ) {
      fprintf( stderr, "ldap_simple_bind_s: %s\n", ldap_err2string( rc ) );
      ldap_get_lderrno( ld, &matched_msg, &error_msg );
      if ( error_msg != NULL && *error_msg != '\0' ) {
         fprintf( stderr, "%s\n", error_msg );
      }
      if ( matched_msg != NULL && *matched_msg != '\0' ) {
         fprintf( stderr, 
            "Part of the DN that matches an existing entry: %s\n", 
            matched_msg );
      }
      ldap_unbind_s( ld );
      return( 1 );
    }
    /* Construct the array of LDAPMod structures representing the attributes 
      of the new entry. */
    mods = ( LDAPMod ** ) malloc(( NUM_MODS + 1 ) * sizeof( LDAPMod * ));
    if ( mods == NULL ) {
      fprintf( stderr, "Cannot allocate memory for mods array\n" );
      exit( 1 );
    }
    for ( i = 0; i < NUM_MODS; i++ ) {
      if (( mods[ i ] = ( LDAPMod * ) malloc( sizeof( LDAPMod ))) == NULL ) {
         fprintf( stderr, "Cannot allocate memory for mods element\n" );
         exit( 1 );
      }
    }
    mods[ 0 ]->mod_op = 0;
    mods[ 0 ]->mod_type = "objectclass";
    mods[ 0 ]->mod_values = object_vals;
    mods[ 1 ]->mod_op = 0;
    mods[ 1 ]->mod_type = "cn";
    mods[ 1 ]->mod_values = cn_vals;
    mods[ 2 ]->mod_op = 0;
    mods[ 2 ]->mod_type = "sn";
    mods[ 2 ]->mod_values = sn_vals;
    mods[ 3 ]->mod_op = 0;
    mods[ 3 ]->mod_type = "givenname";
    mods[ 3 ]->mod_values = givenname_vals;
    mods[ 4 ]->mod_op = 0;
    mods[ 4 ]->mod_type = "telephonenumber";
    mods[ 4 ]->mod_values = telephonenumber_vals;
    mods[ 5 ] = NULL;
    /* Perform the add operation. */
    rc = ldap_add_ext_s( ld, NEW_DN, mods, NULL, NULL );
   if ( rc != LDAP_SUCCESS ) {
      fprintf( stderr, "ldap_add_ext_s: %s\n", ldap_err2string( rc ) );
      ldap_get_lderrno( ld, &matched_msg, &error_msg );
      if ( error_msg != NULL & *error_msg != '\0' ) {
         fprintf( stderr, "%s\n", error_msg );
      }
      if ( matched_msg != NULL && *matched_msg != '\0' ) {
         fprintf( stderr, 
            "Part of the DN that matches an existing entry: %s\n", 
            matched_msg );
      }
    } else {
      printf( "%s added successfully.\n", NEW_DN );
   }
   ldap_unbind_s( ld );
   for ( i = 0; i < NUM_MODS; i++ ) {
      free( mods[ i ] );
   }
   free( mods );
   return 0;
}

Example: Adding an Entry to the Directory (Asynchronous)

The following sample program calls the asynchronous ldap_add_ext() function to add a new user to the directory. 

#include <stdio.h>
#include "ldap.h"
void do_other_work();
int global_counter = 0;
void free_mods( LDAPMod **mods );
/* Change these as needed. */
#define HOSTNAME "localhost"
#define PORTNUMBER LDAP_PORT
#define BIND_DN "cn=Directory Manager"
#define BIND_PW "23skidoo"
#define NEW_DN "uid=wbjensen,ou=People,o=Airius.com"
#define   NUM_MODS 5
int
main( int argc, char **argv )
{
    LDAP         *ld;
    LDAPMessage      *res;
    LDAPMod         **mods;
   LDAPControl      **serverctrls;
   char         *matched_msg = NULL, *error_msg = NULL;
   char         **referrals;
    int            i, rc, parse_rc, msgid, finished = 0;
    struct timeval   zerotime;
    char *object_vals[] = { "top", "person", "organizationalPerson", "inetOrgPerson", NULL };
    char *cn_vals[] = { "William B Jensen", "William Jensen", "Bill Jensen", NULL };
    char *sn_vals[] = { "Jensen", NULL };
    char *givenname_vals[] = { "William", "Bill", NULL };
    char *telephonenumber_vals[] = { "+1 415 555 1212", NULL };
    zerotime.tv_sec = zerotime.tv_usec = 0L;
    /* Get a handle to an LDAP connection. */
    if ( (ld = ldap_init( HOSTNAME, PORTNUMBER )) == NULL ) {
      perror( "ldap_init" );
      return( 1 );
    }
    /* Bind to the server as the Directory Manager. */
    rc = ldap_simple_bind_s( ld, BIND_DN, BIND_PW );
   if ( rc != LDAP_SUCCESS ) {
      fprintf( stderr, "ldap_simple_bind_s: %s\n", ldap_err2string( rc ) );
      ldap_get_lderrno( ld, &matched_msg, &error_msg );
      if ( error_msg != NULL && *error_msg != '\0' ) {
         fprintf( stderr, "%s\n", error_msg );
      }
      if ( matched_msg != NULL && *matched_msg != '\0' ) {
         fprintf( stderr, 
            "Part of the DN that matches an existing entry: %s\n",
            matched_msg );
      }
      ldap_unbind_s( ld );
      return( 1 );
    }
    /* Construct the array of LDAPMod structures representing the attributes 
      of the new entry. */
    mods = ( LDAPMod ** ) malloc(( NUM_MODS + 1 ) * sizeof( LDAPMod * ));
    if ( mods == NULL ) {
      fprintf( stderr, "Cannot allocate memory for mods array\n" );
      exit( 1 );
    }
    for ( i = 0; i < NUM_MODS; i++ ) {
      if (( mods[ i ] = ( LDAPMod * ) malloc( sizeof( LDAPMod ))) == NULL ) {
         fprintf( stderr, "Cannot allocate memory for mods element\n" );
         exit( 1 );
      }
    }
    mods[ 0 ]->mod_op = 0;
    mods[ 0 ]->mod_type = "objectclass";
    mods[ 0 ]->mod_values = object_vals;
    mods[ 1 ]->mod_op = 0;
    mods[ 1 ]->mod_type = "cn";
    mods[ 1 ]->mod_values = cn_vals;
    mods[ 2 ]->mod_op = 0;
    mods[ 2 ]->mod_type = "sn";
    mods[ 2 ]->mod_values = sn_vals;
    mods[ 3 ]->mod_op = 0;
    mods[ 3 ]->mod_type = "givenname";
    mods[ 3 ]->mod_values = givenname_vals;
    mods[ 4 ]->mod_op = 0;
    mods[ 4 ]->mod_type = "telephonenumber";
    mods[ 4 ]->mod_values = telephonenumber_vals;
    mods[ 5 ] = NULL;
    /* Send the LDAP add request. */
    rc = ldap_add_ext( ld, NEW_DN, mods, NULL, NULL, &msgid );
   if ( rc != LDAP_SUCCESS ) {
      fprintf( stderr, "ldap_add_ext: %s\n", ldap_err2string( rc ) );
      ldap_unbind( ld );
      free_mods( mods );
      return( 1 );
    }
    /* Poll the server for the results of the add operation. */
    while ( !finished ) {
      rc = ldap_result( ld, msgid, 0, &zerotime, &res );
      switch ( rc ) {
      case -1:
         /* An error occurred. */
         rc = ldap_get_lderrno( ld, NULL, NULL );
         fprintf( stderr, "ldap_result: %s\n", ldap_err2string( rc ) );
         ldap_unbind( ld );
         free_mods( mods );
         return( 1 );
      case 0:
         /* The timeout period specified by zerotime was exceeded.
            This means that the server has still not yet sent the 
            results of the add operation back to your client.
            Break out of this switch statement, and continue calling  
            ldap_result() to poll for results. */
         break;
      default:
         /* The function has retrieved the results of the add operation
            from the server. */
         finished = 1;
         /* Parse the results received from the server. Note the last
            argument is a non-zero value, which indicates that the 
            LDAPMessage structure will be freed when done.  (No need
            to call ldap_msgfree().) */
         parse_rc = ldap_parse_result( ld, res, &rc, &matched_msg, &error_msg, &referrals, &serverctrls, 1 );
         if ( parse_rc != LDAP_SUCCESS ) {
            fprintf( stderr, "ldap_parse_result: %s\n", ldap_err2string( parse_rc ) );
            ldap_unbind( ld );
            free_mods( mods );
            return( 1 );
         }
         /* Check the results of the LDAP add operation. */
         if ( rc != LDAP_SUCCESS ) {
            fprintf( stderr, "ldap_add_ext: %s\n", ldap_err2string( rc ) );
            if ( error_msg != NULL & *error_msg != '\0' ) {
               fprintf( stderr, "%s\n", error_msg );
            }
            if ( matched_msg != NULL && *matched_msg != '\0' ) {
               fprintf( stderr, 
                  "Part of the DN that matches an existing entry: %s\n", 
                  matched_msg );
            }
         } else {
            printf( "%s added successfully.\n"
               "Counted to %d while waiting for the add operation.\n",
               NEW_DN, global_counter );
         }
      }
      /* Do other work while waiting for the results of the add operation. */
      if ( !finished ) {
         do_other_work();
      }
   }
   ldap_unbind( ld );
   free_mods( mods );
   return 0;
}
/*
 * Free a mods array.
 */
void
free_mods( LDAPMod **mods )
{
    int i;
    for ( i = 0; i < NUM_MODS; i++ ) {
   free( mods[ i ] );
    }
    free( mods );
}
   
/*
 * Perform other work while polling for results.  This doesn't do anything
 * useful, but it could.
 */
void
do_other_work()
{
    global_counter++;
}

Modifying an Entry

To modify an entry:

  1. Create an array of LDAPMod structures representing the changes that need to be made. Use the LDAPMod structure to specify a change to an attribute.

  2. Call the ldap_modify_ext() or ldap_modify_ext_s(), passing in the array of LDAPMod structures and a distinguished name of the entry that you want modified.
After you are done, call the ldap_mods_free() function to free any LDAPMod structures you've allocated.

Specifying the Changes

This section describes the process of specifying changes to an entry.

Replacing the Values of an Attribute

To replace all existing values of an attribute, create an LDAPMod structure with the following:

If you want to specify binary data as berval structures (as opposed to string values), you need to do the following:

Note the following:

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

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

Removing Values from an Attribute

To remove values from an attribute, create an LDAPMod structure with the following:

If you want to specify binary data as berval structures (as opposed to string values), you need to do the following:

Note the following:

The following example specifies the removal of one of the values of the facsimileTelephoneNumber attribute in the entry:

#include "ldap.h"
LDAPMod attribute2;
char *fax_values[] = { "+1 650 555 1967", NULL };
attribute2.mod_type = "facsimileTelephoneNumber";
attribute2.mod_op = LDAP_MOD_DELETE;
attribute2.mod_values = fax_values;
...

Adding Values to an Attribute

To add values to an attribute to an entry, create an LDAPMod structure with the following:

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

Note that if the attribute does not already exist in the entry, the attribute will be added to the entry.

The following example adds values to 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;
...

Removing an Attribute

You can remove an attribute from an entry in one of the following ways:

Adding an Attribute

If you add or replace values in an attribute that does not yet exist in the entry, the attribute will be added to the entry.

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 "Calling Synchronous and Asynchronous Functions.")

Performing a Synchronous Modify Operation

If you want to wait for the results of the modify operation to complete before continuing, call the synchronous ldap_modify_ext_s() function. This function sends an LDAP modify request to the server and blocks until the server sends the results of the operation back to your client.

The ldap_modify_ext_s() function returns LDAP_SUCCESS if the operation completed successfully or an error code if a problem occurred. See the documentation on the ldap_modify_ext_s() function for a list of the possible result codes.

The following section of code uses the synchronous ldap_add_ext_s() function to modify the entry for the user William Jensen in the directory. 

...
#include <stdio.h>
#include "ldap.h"
#define MODIFY_DN "uid=wbjensen,ou=People,o=Airius.com"
...
LDAP         *ld;
LDAPMod         *mods[ 3 ];
char         *matched_msg = NULL, *error_msg = NULL;
int            rc;
...
/* Perform the modify operation. */
rc = ldap_modify_ext_s( ld, MODIFY_DN, mods, NULL, NULL );
if ( rc != LDAP_SUCCESS ) {
   fprintf( stderr, "ldap_modify_ext_s: %s\n", ldap_err2string( rc ) );
   ldap_get_lderrno( ld, &matched_msg, &error_msg );
   if ( error_msg != NULL && *error_msg != '\0' ) {
      fprintf( stderr, "%s\n", error_msg );
   }
   if ( matched_msg != NULL && *matched_msg != '\0' ) {
      fprintf( stderr, 
         "Part of the DN that matches an existing entry: %s\n", 
         matched_msg );
   }
} else {
   printf( "%s modified successfully.\n", MODIFY_DN );
}
ldap_unbind_s( ld );
...

Performing an Asynchronous Modify Operation

If you want to perform other work (in parallel) while waiting for the entry to be modified, call the asynchronous ldap_modify_ext() function. This function sends an LDAP modify request to the server and returns an LDAP_SUCCESS result code if the request was successfully sent (or an LDAP result code if an error occurred).

The ldap_modify_ext() function passes back a message ID identifying the modify operation. To determine whether the server sent a response for this operation to your client, call the ldap_result() function and pass in this message ID. The ldap_result() function uses the message ID to determine if the server sent the results of the modify operation. The function passes back the results in an LDAPMessage structure.

You can call the ldap_parse_result() function to parse the LDAPMessage structure to determine if the operation was successful. (For a list of possible result codes for an LDAP modify operation, see the result code documentation for the ldap_modify_ext_s() function.)

The following section of code calls ldap_modify_ext() to modify the entry for the user William Jensen in the directory. 

...
#include <stdio.h>
#include "ldap.h"
...
#define MODIFY_DN "uid=wbjensen,ou=People,o=Airius.com"
...
LDAP         *ld;
LDAPMessage      *res;
LDAPMod         *mods[ 3 ];
LDAPControl      **serverctrls;
char         *matched_msg = NULL, *error_msg = NULL;
char         **referrals;
int            rc, parse_rc, msgid, finished = 0;
/* Timeout period for the ldap_result() function to wait for results. */
struct timeval   zerotime;
zerotime.tv_sec = zerotime.tv_usec = 0L;
...
/* Send the LDAP modify request. */
rc = ldap_modify_ext( ld, MODIFY_DN, mods, NULL, NULL, &msgid );
if ( rc != LDAP_SUCCESS ) {
   fprintf( stderr, "ldap_modify_ext: %s\n", ldap_err2string( rc ) );
   ldap_unbind( ld );
   return( 1 );
}
/* Poll the server for the results of the modify operation. */
while ( !finished ) {
   rc = ldap_result( ld, msgid, 0, &zerotime, &res );
   switch ( rc ) {
   case -1:
      /* An error occurred. */
         rc = ldap_get_lderrno( ld, NULL, NULL );
         fprintf( stderr, "ldap_result: %s\n", ldap_err2string( rc ) );
         ldap_unbind( ld );
         return( 1 );
   case 0:
      /* The timeout period specified by zerotime was exceeded, 
         so call ldap_result() again and continue polling. */
      break;
   default:
      /* The function has retrieved the results of the 
         modify operation. */
      finished = 1;
      /* Parse the results received from the server. */
      parse_rc = ldap_parse_result( ld, res, &rc, &matched_msg, 
         &error_msg, &referrals, &serverctrls, 1 );
      if ( parse_rc != LDAP_SUCCESS ) {
         fprintf( stderr, "ldap_parse_result: %s\n", 
            ldap_err2string( parse_rc ) );
         ldap_unbind( ld );
         return( 1 );
      }
      /* Check the results of the LDAP modify operation. */
      if ( rc != LDAP_SUCCESS ) {
         fprintf( stderr, "ldap_modify_ext: %s\n", 
            ldap_err2string( rc ) );
         if ( error_msg != NULL & *error_msg != '\0' ) {
            fprintf( stderr, "%s\n", error_msg );
         }
         if ( matched_msg != NULL && *matched_msg != '\0' ) {
            fprintf( stderr, 
            "Part of the DN that matches an existing entry: %s\n", 
            matched_msg );
         }
      } else {
         printf( "%s modified successfully.\n", MODIFY_DN );
      }
   }
}
ldap_unbind( ld );
...

Example: Modifying an Entry in the Directory (Synchronous)

The following sample program calls the synchronous ldap_modify_ext_s() function to modify a user's entry in the directory. The program replaces the values of the mail attribute of the entry and adds a description attribute to the entry. 

#include <stdio.h>
#include <time.h>
#include "ldap.h"
/* Change these as needed. */
#define HOSTNAME "localhost"
#define PORTNUMBER LDAP_PORT
#define BIND_DN "cn=Directory Manager"
#define BIND_PW "23skidoo"
#define MODIFY_DN "uid=wbjensen,ou=People,o=Airius.com"
int
main( int argc, char **argv )
{
    LDAP         *ld;
   LDAPMod         mod0, mod1;
    LDAPMod         *mods[ 3 ];
   char         *matched_msg = NULL, *error_msg = NULL;
   char         *vals0[ 2 ], *vals1[ 2 ];
   time_t         now;
   char         buf[ 128 ];
    int            rc;
    /* Get a handle to an LDAP connection. */
    if ( (ld = ldap_init( HOSTNAME, PORTNUMBER )) == NULL ) {
      perror( "ldap_init" );
      return( 1 );
    }
    /* Bind to the server as the Directory Manager. */
    rc = ldap_simple_bind_s( ld, BIND_DN, BIND_PW );
   if ( rc != LDAP_SUCCESS ) {
      fprintf( stderr, "ldap_simple_bind_s: %s\n", ldap_err2string( rc ) );
      ldap_get_lderrno( ld, &matched_msg, &error_msg );
      if ( error_msg != NULL && *error_msg != '\0' ) {
         fprintf( stderr, "%s\n", error_msg );
      }
      if ( matched_msg != NULL && *matched_msg != '\0' ) {
         fprintf( stderr, 
            "Part of the DN that matches an existing entry: %s\n", 
            matched_msg );
      }
      ldap_unbind_s( ld );
      return( 1 );
    }
    /* Construct the array of LDAPMod structures representing the changes 
      that you want to make to attributes in the entry. */
   /* Specify the first modification, which replaces all values of the
      mail attribute with the value "wbj@airius.com". */
    mod0.mod_op = LDAP_MOD_REPLACE;
    mod0.mod_type = "mail";
    vals0[0] = "wbj@airius.com";
    vals0[1] = NULL;
    mod0.mod_values = vals0;
   /* Specify the second modification, which adds a value to the description
      attribute.  If this attribute does not yet exist, the attribute ia added
      to the entry. */
    mod1.mod_op = LDAP_MOD_ADD;
    mod1.mod_type = "description";
    time( &now );
    sprintf( buf, "This entry was modified with the modattrs program on %s",
       ctime( &now ));
    /* Get rid of \n which ctime put on the end of the time string */
    if ( buf[ strlen( buf ) - 1 ] == '\n' ) {
      buf[ strlen( buf ) - 1 ] = '\0';
    }
    vals1[ 0 ] = buf;
    vals1[ 1 ] = NULL;
    mod1.mod_values = vals1;
    mods[ 0 ] = &mod0;
    mods[ 1 ] = &mod1;
    mods[ 2 ] = NULL;
    /* Perform the modify operation. */
    rc = ldap_modify_ext_s( ld, MODIFY_DN, mods, NULL, NULL );
   if ( rc != LDAP_SUCCESS ) {
      fprintf( stderr, "ldap_modify_ext_s: %s\n", ldap_err2string( rc ) );
      ldap_get_lderrno( ld, &matched_msg, &error_msg );
      if ( error_msg != NULL && *error_msg != '\0' ) {
         fprintf( stderr, "%s\n", error_msg );
      }
      if ( matched_msg != NULL && *matched_msg != '\0' ) {
         fprintf( stderr, 
            "Part of the DN that matches an existing entry: %s\n", 
            matched_msg );
      }
    } else {
      printf( "%s modified successfully.\n", MODIFY_DN );
   }
   ldap_unbind_s( ld );
   return 0;
}

Example: Modifying an Entry in the Directory (Asynchronous)

The following sample program calls the asynchronous ldap_modify_ext() function to modify a user's entry in the directory. The program replaces the values of the mail attribute of the entry and adds a description attribute to the entry. 

#include <stdio.h>
#include <time.h>
#include "ldap.h"
void do_other_work();
int global_counter = 0;
/* Change these as needed. */
#define HOSTNAME "localhost"
#define PORTNUMBER LDAP_PORT
#define BIND_DN "cn=Directory Manager"
#define BIND_PW "23skidoo"
#define MODIFY_DN "uid=wbjensen,ou=People,o=Airius.com"
int
main( int argc, char **argv )
{
    LDAP         *ld;
    LDAPMessage      *res;
   LDAPMod         mod0, mod1;
    LDAPMod         *mods[ 3 ];
   LDAPControl      **serverctrls;
   char         *matched_msg = NULL, *error_msg = NULL;
   char         **referrals;
   char         *vals0[ 2 ], *vals1[ 2 ];
   time_t         now;
   char         buf[ 128 ];
    int            rc, parse_rc, msgid, finished = 0;
    struct timeval   zerotime;
    zerotime.tv_sec = zerotime.tv_usec = 0L;
    /* Get a handle to an LDAP connection. */
    if ( (ld = ldap_init( HOSTNAME, PORTNUMBER )) == NULL ) {
      perror( "ldap_init" );
      return( 1 );
    }
    /* Bind to the server as the Directory Manager. */
    rc = ldap_simple_bind_s( ld, BIND_DN, BIND_PW );
   if ( rc != LDAP_SUCCESS ) {
      fprintf( stderr, "ldap_simple_bind_s: %s\n", ldap_err2string( rc ) );
      ldap_get_lderrno( ld, &matched_msg, &error_msg );
      if ( error_msg != NULL && *error_msg != '\0' ) {
         fprintf( stderr, "%s\n", error_msg );
      }
      if ( matched_msg != NULL && *matched_msg != '\0' ) {
         fprintf( stderr, 
            "Part of the DN that matches an existing entry: %s\n", 
            matched_msg );
      }
      ldap_unbind_s( ld );
      return( 1 );
    }
    /* Construct the array of LDAPMod structures representing the changes 
      that you want to make to attributes in the entry. */
   /* Specify the first modification, which replaces all values of the
      mail attribute with the value "wbj@airius.com". */
    mod0.mod_op = LDAP_MOD_REPLACE;
    mod0.mod_type = "mail";
    vals0[0] = "wbj@airius.com";
    vals0[1] = NULL;
    mod0.mod_values = vals0;
   /* Specify the second modification, which adds a value to the description
      attribute.  If this attribute does not yet exist, the attribute ia added
      to the entry. */
    mod1.mod_op = LDAP_MOD_ADD;
    mod1.mod_type = "description";
    time( &now );
    sprintf( buf, "This entry was modified with the modattrs program on %s",
       ctime( &now ));
    /* Get rid of \n which ctime put on the end of the time string */
    if ( buf[ strlen( buf ) - 1 ] == '\n' ) {
      buf[ strlen( buf ) - 1 ] = '\0';
    }
    vals1[ 0 ] = buf;
    vals1[ 1 ] = NULL;
    mod1.mod_values = vals1;
    mods[ 0 ] = &mod0;
    mods[ 1 ] = &mod1;
    mods[ 2 ] = NULL;
    /* Send the LDAP modify request. */
    rc = ldap_modify_ext( ld, MODIFY_DN, mods, NULL, NULL, &msgid );
   if ( rc != LDAP_SUCCESS ) {
      fprintf( stderr, "ldap_modify_ext: %s\n", ldap_err2string( rc ) );
      ldap_unbind( ld );
      return( 1 );
    }
    /* Poll the server for the results of the modify operation. */
    while ( !finished ) {
      rc = ldap_result( ld, msgid, 0, &zerotime, &res );
      switch ( rc ) {
      case -1:
         /* An error occurred. */
         rc = ldap_get_lderrno( ld, NULL, NULL );
         fprintf( stderr, "ldap_result: %s\n", ldap_err2string( rc ) );
         ldap_unbind( ld );
         return( 1 );
      case 0:
         /* The timeout period specified by zerotime was exceeded.
            This means that the server has still not yet sent the 
            results of the modify operation back to your client.
            Break out of this switch statement, and continue calling  
            ldap_result() to poll for results. */
         break;
      default:
         /* The function has retrieved the results of the modify operation
            from the server. */
         finished = 1;
         /* Parse the results received from the server. Note the last
            argument is a non-zero value, which indicates that the 
            LDAPMessage structure will be freed when done.  (No need
            to call ldap_msgfree().) */
         parse_rc = ldap_parse_result( ld, res, &rc, &matched_msg, &error_msg, &referrals, &serverctrls, 1 );
         if ( parse_rc != LDAP_SUCCESS ) {
            fprintf( stderr, "ldap_parse_result: %s\n", ldap_err2string( parse_rc ) );
            ldap_unbind( ld );
            return( 1 );
         }
         /* Check the results of the LDAP add operation. */
         if ( rc != LDAP_SUCCESS ) {
            fprintf( stderr, "ldap_modify_ext: %s\n", ldap_err2string( rc ) );
            if ( error_msg != NULL & *error_msg != '\0' ) {
               fprintf( stderr, "%s\n", error_msg );
            }
            if ( matched_msg != NULL && *matched_msg != '\0' ) {
               fprintf( stderr, 
                  "Part of the DN that matches an existing entry: %s\n", 
                  matched_msg );
            }
         } else {
            printf( "%s modified successfully.\n"
               "Counted to %d while waiting for the modify operation.\n",
               MODIFY_DN, global_counter );
         }
      }
      /* Do other work while waiting for the results of the modify operation. */
      if ( !finished ) {
         do_other_work();
      }
   }
   ldap_unbind( ld );
   return 0;
}
   
/*
 * Perform other work while polling for results.  This doesn't do anything
 * useful, but it could.
 */
void
do_other_work()
{
    global_counter++;
}

Deleting an Entry

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

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

Performing a Synchronous Delete Operation

If you want to wait for the results of the delete operation to complete before continuing, call the synchronous ldap_delete_ext_s() function. This function sends an LDAP delete request to the server and blocks until the server sends the results of the operation back to your client.

The ldap_delete_ext_s() function returns LDAP_SUCCESS if the operation completed successfully or an error code if a problem occurred. See the documentation on the ldap_delete_ext_s() function for a list of the possible result codes.

The following section of code uses the synchronous ldap_delete_ext_s() function to remove the entry for the user William Jensen from the directory. 

...
#include <stdio.h>
#include "ldap.h"
...
#define DELETE_DN "uid=wjensen,ou=People,o=Airius.com"
...
LDAP         *ld;
char         *matched_msg = NULL, *error_msg = NULL;
int         rc;
...
/* Perform the delete operation. */
rc = ldap_delete_ext_s( ld, DELETE_DN, NULL, NULL );
if ( rc != LDAP_SUCCESS ) {
   fprintf( stderr, "ldap_delete_ext_s: %s\n", ldap_err2string( rc ) );
   ldap_get_lderrno( ld, &matched_msg, &error_msg );
   if ( error_msg != NULL && *error_msg != '\0' ) {
      fprintf( stderr, "%s\n", error_msg );
   }
   if ( matched_msg != NULL && *matched_msg != '\0' ) {
      fprintf( stderr, 
         "Part of the DN that matches an existing entry: %s\n", 
         matched_msg );
   }
} else {
   printf( "%s deleted successfully.\n", DELETE_DN );
}
ldap_unbind_s( ld );
...

Performing an Asynchronous Delete Operation

If you want to perform other work (in parallel) while waiting for the entry to be deleted, call the asynchronous ldap_delete_ext() function. This function sends an LDAP delete request to the server and returns an LDAP_SUCCESS result code if the request was successfully sent (or an LDAP result code if an error occurred).

The ldap_delete_ext() function passes back a message ID identifying the delete operation. To determine whether the server sent a response for this operation to your client, call the ldap_result() function and pass in this message ID. The ldap_result() function uses the message ID to determine if the server sent the results of the delete operation. The function passes back the results in an LDAPMessage structure.

You can call the ldap_parse_result() function to parse the LDAPMessage structure to determine if the operation was successful. (For a list of possible result codes for an LDAP delete operation, see the result code documentation for the ldap_delete_ext_s() function.)

The following section of code calls ldap_delete_ext() to remove the user William Jensen from the directory. 

...
#include <stdio.h>
#include "ldap.h"
...
#define DELETE_DN "uid=wjensen,ou=People,o=Airius.com"
...
LDAP         *ld;
LDAPMessage      *res;
LDAPControl      **serverctrls;
char         *matched_msg = NULL, *error_msg = NULL;
char         **referrals;
int            rc, parse_rc, msgid, finished = 0;
/* Timeout period for the ldap_result() function to wait for results. */
struct timeval   zerotime;
zerotime.tv_sec = zerotime.tv_usec = 0L;
...
/* Send the LDAP delete request. */
rc = ldap_delete_ext( ld, DELETE_DN, NULL, NULL, &msgid );
if ( rc != LDAP_SUCCESS ) {
   fprintf( stderr, "ldap_delete_ext: %s\n", ldap_err2string( rc ) );
   ldap_unbind( ld );
   return( 1 );
}
/* Poll the server for the results of the delete operation. */
while ( !finished ) {
   rc = ldap_result( ld, msgid, 0, &zerotime, &res );
   switch ( rc ) {
   case -1:
      /* An error occurred. */
      rc = ldap_get_lderrno( ld, NULL, NULL );
      fprintf( stderr, "ldap_result: %s\n", ldap_err2string( rc ) );
      ldap_unbind( ld );
      return( 1 );
   case 0:
      /* The timeout period specified by zerotime was exceeded, 
         so call ldap_result() again and continue polling. */
         break;
   default:
      /* The function has retrieved the results of the 
         delete operation. */
         finished = 1;
      /* Parse the results received from the server. */
      parse_rc = ldap_parse_result( ld, res, &rc, &matched_msg, 
         &error_msg, &referrals, &serverctrls, 1 );
      if ( parse_rc != LDAP_SUCCESS ) {
         fprintf( stderr, "ldap_parse_result: %s\n", 
            ldap_err2string( parse_rc ) );
         ldap_unbind( ld );
         return( 1 );
      }
      /* Check the results of the LDAP delete operation. */
      if ( rc != LDAP_SUCCESS ) {
         fprintf( stderr, "ldap_delete_ext: %s\n", 
            ldap_err2string( rc ) );
         if ( error_msg != NULL & *error_msg != '\0' ) {
            fprintf( stderr, "%s\n", error_msg );
         }
         if ( matched_msg != NULL && *matched_msg != '\0' ) {
            fprintf( stderr, 
               "Part of the DN that matches an existing entry: %s\n", 
               matched_msg );
         }
      } else {
         printf( "%s deleted successfully.\n", DELETE_DN );
      }
   }
}
ldap_unbind( ld );
...

Example: Deleting an Entry from the Directory (Synchronous)

The following sample program calls the synchronous ldap_delete_ext_s() function to delete a user's entry from the directory. 

#include <stdio.h>
#include "ldap.h"
/* Change these as needed. */
#define HOSTNAME "localhost"
#define PORTNUMBER LDAP_PORT
#define BIND_DN "cn=Directory Manager"
#define BIND_PW "23skidoo"
#define DELETE_DN "uid=wjensen,ou=People,o=Airius.com"
int
main( int argc, char **argv )
{
    LDAP         *ld;
   char         *matched_msg = NULL, *error_msg = NULL;
    int            rc;
    /* Get a handle to an LDAP connection. */
    if ( (ld = ldap_init( HOSTNAME, PORTNUMBER )) == NULL ) {
      perror( "ldap_init" );
      return( 1 );
    }
    /* Bind to the server as the Directory Manager. */
    rc = ldap_simple_bind_s( ld, BIND_DN, BIND_PW );
   if ( rc != LDAP_SUCCESS ) {
      fprintf( stderr, "ldap_simple_bind_s: %s\n", ldap_err2string( rc ) );
      ldap_get_lderrno( ld, &matched_msg, &error_msg );
      if ( error_msg != NULL && *error_msg != '\0' ) {
         fprintf( stderr, "%s\n", error_msg );
      }
      if ( matched_msg != NULL && *matched_msg != '\0' ) {
         fprintf( stderr, 
            "Part of the DN that matches an existing entry: %s\n", 
            matched_msg );
      }
      ldap_unbind_s( ld );
      return( 1 );
    }
    /* Perform the delete operation. */
    rc = ldap_delete_ext_s( ld, DELETE_DN, NULL, NULL );
   if ( rc != LDAP_SUCCESS ) {
      fprintf( stderr, "ldap_delete_ext_s: %s\n", ldap_err2string( rc ) );
      ldap_get_lderrno( ld, &matched_msg, &error_msg );
      if ( error_msg != NULL && *error_msg != '\0' ) {
         fprintf( stderr, "%s\n", error_msg );
      }
      if ( matched_msg != NULL && *matched_msg != '\0' ) {
         fprintf( stderr, 
            "Part of the DN that matches an existing entry: %s\n", 
            matched_msg );
      }
    } else {
      printf( "%s deleted successfully.\n", DELETE_DN );
   }
   ldap_unbind_s( ld );
   return 0;
}   

Example: Deleting an Entry from the Directory (Asynchronous)

The following sample program calls the asynchronous ldap_delete_ext() function to delete a user's entry from the directory. 

#include <stdio.h>
#include "ldap.h"
void do_other_work();
int global_counter = 0;
/* Change these as needed. */
#define HOSTNAME "localhost"
#define PORTNUMBER LDAP_PORT
#define BIND_DN "cn=Directory Manager"
#define BIND_PW "23skidoo"
#define DELETE_DN "uid=wjensen,ou=People,o=Airius.com"
int
main( int argc, char **argv )
{
    LDAP         *ld;
    LDAPMessage      *res;
   LDAPControl      **serverctrls;
   char         *matched_msg = NULL, *error_msg = NULL;
   char         **referrals;
    int            rc, parse_rc, msgid, finished = 0;
    struct timeval   zerotime;
    zerotime.tv_sec = zerotime.tv_usec = 0L;
    /* Get a handle to an LDAP connection. */
    if ( (ld = ldap_init( HOSTNAME, PORTNUMBER )) == NULL ) {
      perror( "ldap_init" );
      return( 1 );
    }
    /* Bind to the server as the Directory Manager. */
    rc = ldap_simple_bind_s( ld, BIND_DN, BIND_PW );
   if ( rc != LDAP_SUCCESS ) {
      fprintf( stderr, "ldap_simple_bind_s: %s\n", ldap_err2string( rc ) );
      ldap_get_lderrno( ld, &matched_msg, &error_msg );
      if ( error_msg != NULL && *error_msg != '\0' ) {
         fprintf( stderr, "%s\n", error_msg );
      }
      if ( matched_msg != NULL && *matched_msg != '\0' ) {
         fprintf( stderr, 
            "Part of the DN that matches an existing entry: %s\n", 
            matched_msg );
      }
      ldap_unbind_s( ld );
      return( 1 );
    }
    /* Send the LDAP delete request. */
    rc = ldap_delete_ext( ld, DELETE_DN, NULL, NULL, &msgid );
   if ( rc != LDAP_SUCCESS ) {
      fprintf( stderr, "ldap_delete_ext: %s\n", ldap_err2string( rc ) );
      ldap_unbind( ld );
      return( 1 );
    }
    /* Poll the server for the results of the delete operation. */
    while ( !finished ) {
      rc = ldap_result( ld, msgid, 0, &zerotime, &res );
      switch ( rc ) {
      case -1:
         /* An error occurred. */
         rc = ldap_get_lderrno( ld, NULL, NULL );
         fprintf( stderr, "ldap_result: %s\n", ldap_err2string( rc ) );
         ldap_unbind( ld );
         return( 1 );
      case 0:
         /* The timeout period specified by zerotime was exceeded.
            This means that the server has still not yet sent the 
            results of the delete operation back to your client.
            Break out of this switch statement, and continue calling  
            ldap_result() to poll for results. */
         break;
      default:
         /* The function has retrieved the results of the delete operation
            from the server. */
         finished = 1;
         /* Parse the results received from the server. Note the last
            argument is a non-zero value, which indicates that the 
            LDAPMessage structure will be freed when done.  (No need
            to call ldap_msgfree().) */
         parse_rc = ldap_parse_result( ld, res, &rc, &matched_msg, &error_msg, &referrals, &serverctrls, 1 );
         if ( parse_rc != LDAP_SUCCESS ) {
            fprintf( stderr, "ldap_parse_result: %s\n", ldap_err2string( parse_rc ) );
            ldap_unbind( ld );
            return( 1 );
         }
         /* Check the results of the LDAP delete operation. */
         if ( rc != LDAP_SUCCESS ) {
            fprintf( stderr, "ldap_delete_ext: %s\n", ldap_err2string( rc ) );
            if ( error_msg != NULL & *error_msg != '\0' ) {
               fprintf( stderr, "%s\n", error_msg );
            }
            if ( matched_msg != NULL && *matched_msg != '\0' ) {
            fprintf( stderr, 
               "Part of the DN that matches an existing entry: %s\n", 
               matched_msg );
            }
         } else {
            printf( "%s deleted successfully.\n"
               "Counted to %d while waiting for the delete operation.\n",
               DELETE_DN, global_counter );
         }
      }
      /* Do other work while waiting for the results of the delete operation. */
      if ( !finished ) {
         do_other_work();
      }
   }
   ldap_unbind( ld );
   return 0;
}   
/*
 * Perform other work while polling for results.  This doesn't do anything
 * useful, but it could.
 */
void
do_other_work()
{
    global_counter++;
}

Changing the DN of an Entry

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

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

For both functions, you can choose to delete the attribute that represents the old relative distinguished name (RDN). (See"Deleting the Attribute for the Old RDN" for details.) You can also change the location of the entry in the directory tree. (See "Changing the Location of the Entry" for details.)

Performing a Synchronous Renaming Operation

If you want to wait for the results of the modify DN operation to complete before continuing, call the synchronous ldap_rename_s() function. This function sends an LDAP modify DN request to the server and blocks until the server sends the results of the operation back to your client.

The ldap_rename_s() function returns LDAP_SUCCESS if the operation completed successfully or an error code if a problem occurred. See the documentation on the ldap_rename_s() function for a list of the possible result codes.

The following section of code uses the synchronous ldap_rename_s() function to change the RDN of the entry for the user William Jensen in the directory. 

...
#include <stdio.h>
#include "ldap.h"
...
#define OLD_DN "uid=wbjensen,ou=People,o=Airius.com"
#define NEW_RDN "uid=wjensen"
...
LDAP         *ld;
char         *matched_msg = NULL, *error_msg = NULL;
int            rc;
...
/* Perform the modify DN operation. */
rc = ldap_rename_s( ld, OLD_DN, NEW_RDN, NULL, 1, NULL, NULL );
if ( rc != LDAP_SUCCESS ) {
   fprintf( stderr, "ldap_rename_s: %s\n", ldap_err2string( rc ) );
   ldap_get_lderrno( ld, &matched_msg, &error_msg );
   if ( error_msg != NULL && *error_msg != '\0' ) {
      fprintf( stderr, "%s\n", error_msg );
   }
   if ( matched_msg != NULL && *matched_msg != '\0' ) {
      fprintf( stderr, 
         "Part of the DN that matches an existing entry: %s\n", 
         matched_msg );
   }
} else {
   printf( "%s renamed successfully.\n", OLD_DN );
}
ldap_unbind_s( ld );
...

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_rename() function. This function sends an LDAP modify DN request to the server and returns an LDAP_SUCCESS result code if the request was successfully sent (or an LDAP result code if an error occurred).

The ldap_rename() function passes back a message ID identifying the modify DN operation. To determine whether the server sent a response for this operation to your client, call the ldap_result() function and pass in this message ID. The ldap_result() function uses the message ID to determine if the server sent the results of the modify DN operation. The function passes back the results in an LDAPMessage structure.

You can call the ldap_parse_result() function to parse the LDAPMessage structure to determine if the operation was successful. (For a list of possible result codes for an LDAP rename operation, see the result code documentation for the ldap_rename_s() function.)

The following section of code calls ldap_rename() to change the RDN of the user William Jensen in the directory. 

...
#include <stdio.h>
#include "ldap.h"
...
#define OLD_DN "uid=wbjensen,ou=People,o=Airius.com"
#define NEW_RDN "uid=wjensen"
...
LDAP         *ld;
LDAPMessage      *res;
LDAPControl      **serverctrls;
char         *matched_msg = NULL, *error_msg = NULL;
char         **referrals;
int            rc, parse_rc, msgid, finished = 0;
/* Timeout period for the ldap_result() function to wait for results. */
struct timeval   zerotime;
zerotime.tv_sec = zerotime.tv_usec = 0L;
...
/* Send the LDAP modify DN request. */
rc = ldap_rename( ld, OLD_DN, NEW_RDN, NULL, 1, NULL, NULL, &msgid );
if ( rc != LDAP_SUCCESS ) {
   fprintf( stderr, "ldap_rename: %s\n", ldap_err2string( rc ) );
   ldap_unbind( ld );
   return( 1 );
}
 
/* Poll the server for the results of the modify DN operation. */
while ( !finished ) {
   rc = ldap_result( ld, msgid, 0, &zerotime, &res );
   switch ( rc ) {
   case -1:
      /* An error occurred. */
      rc = ldap_get_lderrno( ld, NULL, NULL );
      fprintf( stderr, "ldap_result: %s\n", ldap_err2string( rc ) );
      ldap_unbind( ld );
      return( 1 );
   case 0:
      /* The timeout period specified by zerotime was exceeded, 
         so call ldap_result() again and continue polling. */
      break;
   default:
      /* The function has retrieved the results of the 
         modify DN operation. */
      finished = 1;
      /* Parse the results received from the server. */
      parse_rc = ldap_parse_result( ld, res, &rc, &matched_msg, 
         &error_msg, &referrals, &serverctrls, 1 );
      if ( parse_rc != LDAP_SUCCESS ) {
         fprintf( stderr, "ldap_parse_result: %s\n", 
            ldap_err2string( parse_rc ) );
         ldap_unbind( ld );
         return( 1 );
      }
      /* Check the results of the LDAP modify DN operation. */
      if ( rc != LDAP_SUCCESS ) {
         fprintf( stderr, "ldap_rename: %s\n", ldap_err2string( rc ) );
         if ( error_msg != NULL & *error_msg != '\0' ) {
            fprintf( stderr, "%s\n", error_msg );
         }
         if ( matched_msg != NULL && *matched_msg != '\0' ) {
            fprintf( stderr, 
               "Part of the DN that matches an existing entry: %s\n", 
               matched_msg );
         }
      } else {
         printf( "%s renamed successfully.\n", OLD_DN );
      }
   }
}
ldap_unbind( ld );
...

Deleting the Attribute for the Old RDN

Both ldap_rename() and ldap_rename_s() 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

Changing the Location of the Entry

Both ldap_rename() and ldap_rename_s() have a newparent parameter that allows you to specify a new location for the entry in the directory tree.

For example, if you pass "ou=Contractors, o=Airius.com" as the newparent parameter when renaming the entry "uid=bjensen,ou=People,o=Airius.com", the entry is moved under "ou=Contractors, o=Airius.com" and the new DN for the entry is "uid=bjensen,ou=Contractors, o=Airius.com".

Note that not all LDAP servers support this feature. At this point in time, the Netscape Directory Server 3.0 does not support this feature. If you specify this argument, the Netscape Directory Server will send back the LDAP result code LDAP_UNWILLING_TO_PERFORM with the error message "server does not support moving of entries".

Example: Renaming an Entry in the Directory (Synchronous)

The following sample program calls the synchronous ldap_rename_s() function to change the RDN of a user's entry in the directory. 

#include <stdio.h>
#include "ldap.h"
/* Change these as needed. */
#define HOSTNAME "localhost"
#define PORTNUMBER LDAP_PORT
#define BIND_DN "cn=Directory Manager"
#define BIND_PW "23skidoo"
#define OLD_DN "uid=wbjensen,ou=People,o=Airius.com"
#define NEW_RDN "uid=wjensen"
int
main( int argc, char **argv )
{
    LDAP         *ld;
   char         *matched_msg = NULL, *error_msg = NULL;
    int            rc;
    /* Get a handle to an LDAP connection. */
    if ( (ld = ldap_init( HOSTNAME, PORTNUMBER )) == NULL ) {
      perror( "ldap_init" );
      return( 1 );
    }
    /* Bind to the server as the Directory Manager. */
    rc = ldap_simple_bind_s( ld, BIND_DN, BIND_PW );
   if ( rc != LDAP_SUCCESS ) {
      fprintf( stderr, "ldap_simple_bind_s: %s\n", ldap_err2string( rc ) );
      ldap_get_lderrno( ld, &matched_msg, &error_msg );
      if ( error_msg != NULL && *error_msg != '\0' ) {
         fprintf( stderr, "%s\n", error_msg );
      }
      if ( matched_msg != NULL && *matched_msg != '\0' ) {
         fprintf( stderr, 
            "Part of the DN that matches an existing entry: %s\n", 
            matched_msg );
      }
      ldap_unbind_s( ld );
      return( 1 );
    }
    /* Perform the modify DN operation. */
    rc = ldap_rename_s( ld, OLD_DN, NEW_RDN, NULL, 1, NULL, NULL );
   if ( rc != LDAP_SUCCESS ) {
      fprintf( stderr, "ldap_rename_s: %s\n", ldap_err2string( rc ) );
      ldap_get_lderrno( ld, &matched_msg, &error_msg );
      if ( error_msg != NULL && *error_msg != '\0' ) {
         fprintf( stderr, "%s\n", error_msg );
      }
      if ( matched_msg != NULL && *matched_msg != '\0' ) {
         fprintf( stderr, 
            "Part of the DN that matches an existing entry: %s\n", 
            matched_msg );
      }
    } else {
      printf( "%s renamed successfully.\n", OLD_DN );
   }
   ldap_unbind_s( ld );
   return 0;
}   

Example: Renaming an Entry in the Directory (Asynchronous)

The following sample program calls the asynchronous ldap_rename() function to change the RDN of a user's entry in the directory. 

#include <stdio.h>
#include "ldap.h"
void do_other_work();
int global_counter = 0;
/* Change these as needed. */
#define HOSTNAME "localhost"
#define PORTNUMBER LDAP_PORT
#define BIND_DN "cn=Directory Manager"
#define BIND_PW "dougy4444"
#define OLD_DN "uid=wbjensen,ou=People,o=Airius.com"
#define NEW_RDN "uid=wjensen"
int
main( int argc, char **argv )
{
    LDAP         *ld;
    LDAPMessage      *res;
   LDAPControl      **serverctrls;
   char         *matched_msg = NULL, *error_msg = NULL;
   char         **referrals;
    int            rc, parse_rc, msgid, finished = 0;
    struct timeval   zerotime;
    zerotime.tv_sec = zerotime.tv_usec = 0L;
    /* Get a handle to an LDAP connection. */
    if ( (ld = ldap_init( HOSTNAME, PORTNUMBER )) == NULL ) {
      perror( "ldap_init" );
      return( 1 );
    }
    /* Bind to the server as the Directory Manager. */
    rc = ldap_simple_bind_s( ld, BIND_DN, BIND_PW );
   if ( rc != LDAP_SUCCESS ) {
      fprintf( stderr, "ldap_simple_bind_s: %s\n", ldap_err2string( rc ) );
      ldap_get_lderrno( ld, &matched_msg, &error_msg );
      if ( error_msg != NULL && *error_msg != '\0' ) {
         fprintf( stderr, "%s\n", error_msg );
      }
      if ( matched_msg != NULL && *matched_msg != '\0' ) {
         fprintf( stderr, 
            "Part of the DN that matches an existing entry: %s\n", 
            matched_msg );
      }
      ldap_unbind_s( ld );
      return( 1 );
    }
    /* Send the LDAP modify DN request. */
    rc = ldap_rename( ld, OLD_DN, NEW_RDN, NULL, 1, NULL, NULL, &msgid );
   if ( rc != LDAP_SUCCESS ) {
      fprintf( stderr, "ldap_rename: %s\n", ldap_err2string( rc ) );
      ldap_unbind( ld );
      return( 1 );
    }
    /* Poll the server for the results of the modify DN operation. */
    while ( !finished ) {
      rc = ldap_result( ld, msgid, 0, &zerotime, &res );
      switch ( rc ) {
      case -1:
         /* An error occurred. */
         rc = ldap_get_lderrno( ld, NULL, NULL );
         fprintf( stderr, "ldap_result: %s\n", ldap_err2string( rc ) );
         ldap_unbind( ld );
         return( 1 );
      case 0:
         /* The timeout period specified by zerotime was exceeded.
            This means that the server has still not yet sent the 
            results of the modify DN operation back to your client.
            Break out of this switch statement, and continue calling  
            ldap_result() to poll for results. */
         break;
      default:
         /* The function has retrieved the results of the modify DN operation
            from the server. */
         finished = 1;
         /* Parse the results received from the server. Note the last
            argument is a non-zero value, which indicates that the 
            LDAPMessage structure will be freed when done.  (No need
            to call ldap_msgfree().) */
         parse_rc = ldap_parse_result( ld, res, &rc, &matched_msg, &error_msg, &referrals, &serverctrls, 1 );
         if ( parse_rc != LDAP_SUCCESS ) {
            fprintf( stderr, "ldap_parse_result: %s\n", ldap_err2string( parse_rc ) );
            ldap_unbind( ld );
            return( 1 );
         }
         /* Check the results of the LDAP modify DN operation. */
         if ( rc != LDAP_SUCCESS ) {
            fprintf( stderr, "ldap_rename: %s\n", ldap_err2string( rc ) );
            if ( error_msg != NULL & *error_msg != '\0' ) {
               fprintf( stderr, "%s\n", error_msg );
            }
            if ( matched_msg != NULL && *matched_msg != '\0' ) {
               fprintf( stderr, 
                  "Part of the DN that matches an existing entry: %s\n", 
                  matched_msg );
            }
         } else {
            printf( "%s renamed successfully.\n"
               "Counted to %d while waiting for the modify DN operation.\n",
               OLD_DN, global_counter );
         }
      }
      /* Do other work while waiting for the results of the modify DN operation. */
      if ( !finished ) {
         do_other_work();
      }
   }
   ldap_unbind( ld );
   return 0;
}   
/*
 * Perform other work while polling for results.  This doesn't do anything
 * useful, but it could.
 */
void
do_other_work()
{
    global_counter++;
}

Table of Contents | Previous | Next | Index

Last Updated: 10/01/98 17:04:13