ldap_modrdn

The ldap_modrdn function changes the relative distinguished name of an LDAP entry. This function is obsolete and is provided solely for backward compatibility with LDAP 1 implementations.

ULONG ldap_modrdn (
  LDAP* ExternalHandle,
  PCHAR DistinguishedName,
  PCHAR NewDistinguishedName
);

Parameters

ExternalHandle

[in] The session handle.

DistinguishedName

[in] The distinguished name of the entry to be changed.

NewDistinguishedName

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

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_modrdn function (or its synchronous equivalent, ldap_modrdn_s) to change the name of an LDAP entry. LDAP 2 supports additional functionality through ldap_modrdn2 and ldap_modrdn2_s.

As an asynchronous function, ldap_modrdn 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 only allows you to change the least significant component of the relative distinguished name. Effective with version 3, LDAP provides the Modify Distinguished Name protocol operation that 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 function to change the name of an entry.

Multithreading: Calls to ldap_modrdn 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.

ldap_modrdn is obsolete and provided solely for compatibility with LDAP 1 implementations.

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.

See Also

Functions, ldap_abandon, ldap_bind, ldap_modrdn_s, ldap_modrdn2, ldap_modrdn2_s, ldap_rename_ext, ldap_rename_ext_s, ldap_result, ldap_simple_bind