Table of Contents | Previous | Next | Index

Netscape Directory SDK 3.0 for C Programmer’s Guide
Chapter 18 Functions

ldap_rename()

Changes the DN of an entry in the directory asynchronously.

Syntax

#include <ldap.h>
int ldap_rename( LDAP *ld, const char *dn, const char *newrdn, 
   const char *newparent, int deleteoldrdn, 
   LDAPControl **serverctrls, LDAPControl **clientctrls, 
   int *msgidp );

This function is a new version of the ldap_modrdn2() function. If you are writing a new LDAP client, you should call this function instead of ldap_modrdn2().

You can specify whether or not the old RDN is retained as an attribute of the entry. Use the deleteoldrdn argument to do this. Suppose an entry has the following values for the cn attribute:

   cn: Barbara Jensen

   cn: Babs Jensen

If you change the RDN to cn=Barbie Jensen and pass 1 as deleteoldrdn, the resulting entry has the following values:

   cn: Barbie Jensen

   cn: Babs Jensen

If instead you pass 0 as deleteoldrdn, the "Barbara Jensen" value is not removed from the entry:

   cn: Barbie Jensen

   cn: Babs Jensen

   cn: Barbara Jensen

ldap_rename() is an asynchronous function; it does not directly return results. If you want the results to be returned directly by the function, call the synchronous function ldap_rename_s() instead. (For more information on asynchronous and synchronous functions, see "Calling Synchronous and Asynchronous Functions" on page 80.)

In order to get the results of the LDAP rename operation, you need to call the ldap_result() function and the ldap_parse_result() function. (See "Calling Asynchronous Functions" on page 82 for details.) For a list of possible result codes for an LDAP rename operation, see the result code documentation for the ldap_rename_s() function.

For more information on changing the DN of an entry, see "Changing the DN of an Entry" on page 217.

Example

See the example under "Example: Renaming an Entry in the Directory (Asynchronous)" on page 225.

ld	Connection handle, which is a pointer to an `LDAP` structure containing information about the connection to the LDAP server.
dn	Distinguished name (DN) of the entry to rename.
newrdn	New relative distinguished name (RDN) to assign to the entry.
newparent	DN of the new parent entry you want to move the entry under. Pass NULL if you do not want to move the entry to a different location in the directory tree.
deleteoldrdn	If this is a non-zero value, the old RDN is not retained as a value in the entry. If 0, the old RDN is retained as an attribute in the entry.
serverctrls	Pointer to an array of `LDAPControl` structures representing LDAP server controls that apply to this LDAP operation. If you do not want to pass any server controls, specify NULL for this argument.
clientctrls	Pointer to an array of `LDAPControl` structures representing LDAP client controls that apply to this LDAP operation. If you do not want to pass any client controls, specify NULL for this argument.
msgidp	Pointer to an integer that will be set to the message ID of the LDAP operation.Pointer to an integer that will be set to the message ID of the LDAP operation. To check the result of this operation, call `ldap_result()` and `ldap_parse_result()` functions.

ldap_rename()

Syntax

Parameters

Returns

Description

Example

See Also