ldap_modrdn2

The ldap_modrdn2 function is used to modify the distinguished name of an LDAP entry. This function is effective with LDAP 3.

ULONG ldap_modrdn2 (
  LDAP* ExternalHandle,
  PCHAR DistinguishedName,
  PCHAR NewDistinguishedName,
  INT DeleteOldRdn
);

Parameters

ExternalHandle

[in] The session handle.

DistinguishedName

[in] The distinguished name to be changed.

NewDistinguishedName

[in] The new relative distinguished name to give the entry.

DeleteOldRdn

[in] TRUE if the old relative distinguished name should be deleted; FALSE if the old relative distinguished name should be retained.

Return Values

If the function succeeds, it returns the message ID of the modify operation.

If the function fails, it returns –1 and sets the session error parameters in the LDAP data structure.

Remarks

Use the ldap_modrdn2 function (or its synchronous equivalent, ldap_modrdn2_s) to change the name of an LDAP entry.

As an asynchronous function, ldap_modrdn2 returns a message ID for the operation. Call ldap_result with the message ID to get the result of the operation. To cancel an asynchronous add operation before it has completed, call ldap_abandon.

Note that the ldap_modrdn function allows you to change only the least significant component of the relative distinguished name. Effective with version 3, LDAP provides the Modify Distinguished Name protocol operation, which allows more general name-change access. This functionality is available by calling ldap_rename_ext or ldap_rename_ext_s. We recommend using these functions instead of the ldap_modrdn* functions, to change the name of an entry.

Multithreading: Calls to ldap_modrdn2 are not thread-safe because the function returns a message ID, rather than the return code. In order to determine whether the call returned an error value, you have to retrieve the return code from the connection block. It's possible for another thread to overwrite the return code before you retrieve it. Use ldap_rename_ext, which is thread safe.

Note  When connecting to an LDAP 2 server, the application must perform a bind operation (by calling one of the ldap_bind or ldap_simple_bind routines) before attempting any other operations.

Requirements

  Windows NT/2000: Requires Windows NT 4.0 SP4 or later.
  Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
  Header: Declared in Winldap.h.
  Library: Use Wldap32.lib.
  Unicode: Declared as Unicode and ANSI prototypes.

See Also

Functions, ldap_abandon, ldap_modrdn2_s, ldap_rename_ext, ldap_rename_ext_s, ldap_result, Modifying a Directory Entry