ldap_open

The ldap_open function creates and initializes a connection block, then opens the connection to an LDAP server. This function is currently deprecated. Use ldap_init instead. For more information, see Remarks.

LDAP* ldap_open(
  PCHAR HostName,
  ULONG PortNumber
);

Parameters

HostName

[in] A pointer to a null-terminated string. A domain name, a list of host names, or dotted strings that represent the IP address of LDAP server hosts. Use a single space to separate the host names in the list. Each host name in the list may be followed by a port number. The optional port number is separated from the host itself with a colon (:). The LDAP run time attempts connection with the hosts in the order listed, stopping when a successful connection is made. Be aware that only ldap_open attempts to make the connection before returning to the caller. The function ldap_init does not connect to the LDAP server.

PortNumber

[in] Contains the TCP port number to which to connect. The default LDAP port, 389, can be obtained by supplying the constant LDAP_PORT. If a host name includes a port number then this parameter is ignored.

Return Values

If the function succeeds, it returns a session handle, in the form of a pointer to an LDAP data structure. Free the session handle, when no longer required, with a call to ldap_unbind.

If the function fails, it returns NULL. Use the LdapGetLastError function to retrieve the error code.

Remarks

Call ldap_open to create a connection block to an LDAP server. The can be NULL in which case the run time attempts to find the default LDAP server. The host names are tried in the order listed, stopping with the first successful connection. For Active Directory servers, the DsGetDcName function can be used to obtain name of the server, which can then be passed as the HostName parameter instead of using NULL.

The default LDAP server is a Microsoft specific option when you use LDAP_OPT_HOST_NAME. This option specifies the host name of the default LDAP server and returns the host name of the server in Unicode or ANSI, contingent on the use of ldap_get_optionW or ldap_get_optionA, respectively.

If a Global Catalog port number is passed to ldap_open as one of the arguments, then the HostName passed for that port number must be the name of the forest for the underlying call to DsGetDcName() to correctly find the GC in the enterprise.

The ldap_open function allocates an LDAP data structure to maintain state data for the session and returns a handle to this structure. Pass this handle to subsequent LDAP function calls during the course of the session.

Multithreading: Calls to ldap_open are thread-safe.

Note  The use of ldap_open is heavily deprecated by the current LDAP RFC, since it precludes the use of setting any session options. Users are encouraged to use ldap_init as the preferred method of initializing an LDAP session.

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

cldap_open, Functions, ldap_init, LdapGetLastError, ldap_unbind