ldap_sslinit

The ldap_sslinit function initializes a Secure Sockets Layer (SSL) session with an LDAP server.

LDAP* ldap_sslinit(
  PCHAR HostName,
  ULONG PortNumber,
  int secure
);

Parameters

HostName

[in] A pointer to a null-terminated string that contains a space-separated list of host names or dotted strings representing the IP address of hosts running an LDAP server to which to connect. Each host name in the list can include an optional port number which is separated from the host itself with a colon (:) character.

PortNumber

[in] Contains the TCP port number to which to connect. Set to LDAP_SSL_PORT to obtain the default port, 636. This parameter is ignored if a host name includes a port number.

secure

[in] If non-zero, the function uses SSL encryption. If the value is 0, the function establishes a plain TCP connection and uses clear text (no encryption).

Return Values

If the function succeeds, it returns a session handle, in the form of a pointer to an LDAP structure. The session handle must be freed with a call to ldap_unbind when it is no longer needed.

If the function fails, the return value is NULL.Use LdapGetLastError to retrieve the error code.

Remarks

Call ldap_sslinit to create a connection block to a secured LDAP server. The HostName parameter can be NULL in which case the run time attempts to find the "default" LDAP server. The hosts are tried in the order listed, stopping with the first one to which a successful connection is made.

If a Global Catalog port number is passed to ldap_sslinit 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 function allocates an LDAP structure to maintain state information for the session, and returns a handle to this structure. You pass this handle to subsequent LDAP function calls during the course of the session.

Multithreading: Calls to ldap_sslinit are thread-safe.

Microsoft implements security features, like SSL, through its SSPI capabilities.

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

Functions, LDAP, LdapGetLastError, ldap_unbind, SSPI Options for Distributed Applications, Initializing a Session