#include <ldap.h>
int ldap_rename_s( LDAP *ld, const char *dn, const char *newrdn,
const char *newparent, int deleteoldrdn,
LDAPControl **serverctrls, LDAPControl **clientctrls );
ld |
Connection handle, which is a pointer to an |
dn | |
newrdn | New relative distinguished name (RDN) to assign to the entry. |
newparent | |
deleteoldrdn | |
serverctrls |
Pointer to an array of |
clientctrls |
Pointer to an array of |
LDAP_SUCCESS if successful. LDAP_PARAM_ERROR if any of the arguments are invalid. LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request. LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost. LDAP_NO_MEMORY if memory cannot be allocated. LDAP_LOCAL_ERROR if an error occurred when receiving the results from the server. LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded results from the server. LDAP_NOT_SUPPORTED if your LDAP client does not specify that it is using the LDAP v3 protocol. Make sure that you set the version of your LDAP client to version 3 before calling this function. (For details, see "Specifying the LDAP Version of Your Client" on page 54.) LDAP_OPERATIONS_ERROR may be sent by the Netscape Directory Server for general errors encountered by the server when processing the request.LDAP_PROTOCOL_ERROR if the modify RDN request did not comply with the LDAP protocol. The Netscape Directory Server may set this error code in the results for a variety of reasons. Some of these reasons include: newrdn argument is not a valid RDN. newparent argument is not a valid DN. LDAP_UNWILLING_TO_PERFORM may be sent by the Netscape Directory Server in the following situations: newparent argument and the server does not support the ability to move an entry under another parent entry in the directory tree. LDAP_NO_SUCH_OBJECT may be sent by the Netscape Directory Server if the entry that you want modified does not exist and if no referral URLs are available. LDAP_REFERRAL may be sent by the Netscape Directory Server if the DN specified by the dn argument identifies an entry not handled by the current server and if referral URLs identify a different server to handle the entry. (For example, if the DN is uid=bjensen, ou=European Sales, o=Airius.com, all entries under ou=European Sales might be handled by a different Directory Server.) LDAP_NOT_ALLOWED_ON_NONLEAF may be sent by the Netscape Directory Server if the entry that you want renamed has entries beneath it in the directory tree (in other words, if this entry is a parent entry to other entries). LDAP_INSUFFICIENT_ACCESS may be sent by the Netscape Directory Server if the DN that your client is authenticated as does not have the access rights to write to the entry. LDAP_ALREADY_EXISTS may be sent by the Netscape Directory Server if the new DN identifies an entry that already exists in the directory (for example, if you want to change the DN of an entry to uid=bjensen, ou=People, o=Airius.com but an entry with that DN already exists). ldap_rename_s() changes the DN of an entry in the directory synchronously and allows you to move the entry under a different parent entry in the directory tree.
This function is a new version of the ldap_modrdn2_s() function. If you are writing a new LDAP client, you should call this function instead of ldap_modrdn2_s().
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 JensenIf 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 JensenIf 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_s() is a synchronous function, which directly returns the results of the operation. If you want to perform other operations while waiting for the results of this operation, call the asynchronous function ldap_rename() instead. (For more information on asynchronous and synchronous functions, see "Calling Synchronous and Asynchronous Functions" on page 80.)
For more information on changing the DN of an entry, see "Changing the DN of an Entry" on page 217.
ldap_rename().
Last Updated: 10/01/98 17:06:23