#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.
No IBM® i authority is required.
| 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);
|
The ldap_init() API will return NULL if not successful.
The following message may be sent from this function.
| Message ID | Error Message Text |
|---|---|
| CPF3CF2 E | Error(s) occurred during running of ldap_init API. |
[ Back to top | LDAP APIs | APIs by category ]