ldap_add_ext

The ldap_add_ext function initiates an asynchronous add operation to a tree. The parent of the entry added must exist, or the parent must be empty (equal to the distinguished name of the root) for an add operation to succeed.

ULONG ldap_add_ext(
  LDAP* ld,
  PCHAR dn,
  LDAPMod* attrs[],
  PLDAPControl* ServerControls,
  PLDAPControl* ClientControls,
  ULONG* MessageNumber
);

Parameters

ld

[in] The session handle.

dn

[in] A pointer to a null-terminated string that contains the distinguished name of the entry to add.

attrs

[in] An array of pointers to LDAPMod structures. Each structure specifies a single attribute. For more information, see the Remarks section.

ServerControls

[in] List of LDAP server controls.

ClientControls

[in] List of client controls.

MessageNumber

[out] The message ID for the request.

Return Values

If the function succeeds, LDAP_SUCCESS is returned.

If the function fails, an error code is returned. For more information, see Error Handling.

Remarks

The parameters and effects of ldap_add_ext includes those of ldap_add. The extended routine includes additional parameters to support client and server controls and thread safety.

Before calling ldap_add_ext, create an entry by specifying its attributes in LDAPMod structures. Set the mod_op field of each structure to LDAP_MOD_ADD, and set the mod_type and mod_vals fields as appropriate for your entry.

If the operation succeeds, ldap_add_ext passes the message ID to the caller as a parameter. Call ldap_result with the message ID to get the result of the operation.

To have the results returned directly, use the synchronous function ldap_add_ext_s.

Multi-thread: Calls to ldap_add_ext are 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 other operations.

ServerControls and ClientControls are optional and should be set to NULL if not used.

Requirements

Client: Included in Windows XP and Windows 2000 Professional.
Server: Included in Windows Server 2003 and Windows 2000 Server.
Redistributable: Requires Active Directory Client Extension on Windows NT 4.0 SP6a and Windows 95/98/Me.
Unicode: Implemented as Unicode and ANSI versions on all platforms.
Header: Declared in Winldap.h.
Library: Use Wldap32.lib.

See Also

Extended Controls, Using Controls, Error Handling, Functions, ldap_add, ldap_add_ext_s, ldap_bind, ldap_result, ldap_simple_bind, LDAPMod, Modifying a Directory Entry