ldap_init()--Perform an LDAP Initialization Operation

#include <ldap.h>

LDAP *ldap_init(
                char  *host,
                int    port)

The ldap_init() API is used to allocate an LDAP structure, which is used to identify the connection and to maintain per-connection information.

The ldap_init() API returns a pointer to an LDAP structure, which should be passed to subsequent calls to other LDAP functions such as ldap_bind() and ldap_search().

ldap_init() initializes a session with an LDAP server. The server is not actually contacted until an operation is performed that requires it, allowing various options to be set after initialization, but before actually contacting the host. It allocates an LDAP structure which is used to identify the connection and maintain per-connection information. Although still supported, the use of ldap_open() is deprecated. Use of ldap_init() instead of ldap_open() is recommended.

Authorities and Locks

No IBM^® i authority is required.

Parameters

host

(Input) Several methods are supported for specifying one or more target LDAP servers, including the following:

Explicit Host List	Specifies the name of the host on which the LDAP server is running. The host parameter may contain a blank-separated list of hosts to try to connect to, and each host may optionally be of the form host:port. If present, the :port overrides the port parameter. The following are typical examples: ld=ldap_init ("server1", ldap_port); ld=ldap_init ("server2:1200", ldap_port); ld=ldap_init ("server1:800 server2:2000 server3", ldap_port);
Localhost	If the host parameter is NULL, the LDAP server will be assumed to be running on the local host.
Default Hosts	If the host parameter is set to LDAP_URL_PREFIX ("ldap://") the LDAP library will attempt to locate one or more default LDAP servers, with non-SSL ports, using the SecureWay® ldap_server_locate() function. The port specified on the call is ignored, since ldap_server_locate() returns the port. For example, the following two are equivalent: ld=ldap_init ("ldap://", ldap_port); ld=ldap_init (LDAP_URL_PREFIX, LDAP_PORT); If more than one default server is located, the list is processed in sequence, until an active server is found. The LDAP URL can include a Distinguished Name (DN), used as a filter for selecting candidate LDAP servers based on the server's suffix (or suffixes). If the most significant portion of the DN is an exact match with a server's suffix (after normalizing for case), the server is added to the list of candidate servers. For example, the following will only return default LDAP servers that have a suffix that supports the specified DN: ld=ldap_init ("ldap:///cn=fred, dc=austin, dc=ibm, dc=com", LDAP_PORT); In this case, a server that has a suffix of "dc=austin, dc=ibm, dc=com" would match. If more than one default server is located, the list is processed in sequence, until an active server is found. If the LDAP URL contains a host name and optional port, the host is used to create the connection. No attempt is made to locate the default server(s), and the DN, if present, is ignored. For example, the following two are equivalent: ld=ldap_init ("ldap://myserver", LDAP_PORT); ld=ldap_init ("myserver", LDAP_PORT);
Local Socket	If the host parameter is prefixed with "/", the host parameter is assumed to be the name of a UNIX® socket (that is, socket family is AF_UNIX) and port is ignored. Use of a UNIX socket requires the LDAP server to be running on the local host. In addition, the LDAP server must be listening on the specified UNIX socket. The IBM i Secureway Directory Services server listens on the /tmp/s.slapd local socket, in addition to any configured TCP/IP ports. For example: ld=ldap_init ("/tmp/s.slapd", ldap_port);

port

Specifies the port number to which to connect. If the default IANA-assigned port of 389 is desired, LDAP_PORT should be specified.

Return Value

Pointer to an LDAP structure

if the request was successful.

NULL

if the request was not successful.

Error Conditions

The ldap_init() API will return NULL if not successful.

Error Messages

The following message may be sent from this function.

Related Information

• ldap_open() -- Open a connection to an LDAP server (deprecated).
• ldap_ssl_init() -- Initializes an SSL Connection
• ldap_set_option() -- Set an option associated with an LDAP descriptor.
• ldap_get_option() -- Get an option associated with an LDAP descriptor.
• ldap_version() -- Obtain LDAP version and SSL cipher information.

[ Back to top | LDAP APIs | APIs by category ]