299 lines
8.0 KiB
HTML
299 lines
8.0 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
|
<meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation">
|
|
<title>ldap_init()--Perform an LDAP Initialization Operation</title>
|
|
<!-- Begin Header Records ========================================== -->
|
|
<!-- All rights reserved. Licensed Materials Property of IBM -->
|
|
<!-- US Government Users Restricted Rights -->
|
|
<!-- Use, duplication or disclosure restricted by -->
|
|
<!-- GSA ADP Schedule Contract with IBM Corp. -->
|
|
<!-- Change History: -->
|
|
<!-- YYMMDD USERID Change description -->
|
|
<!-- Direct1 SCRIPT J converted by B2H R4.1 (346) (CMS) by V2KEA304 -->
|
|
<!-- at RCHVMW2 on 17 Feb 1999 at 11:05:09 -->
|
|
<!-- File Edited March 2001 -->
|
|
<!-- This file has undergone html cleanup on 2/19/02 by JET -->
|
|
<!-- End Header Records -->
|
|
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
|
|
</head>
|
|
<body>
|
|
<!-- Java sync-link -->
|
|
<script language="Javascript" src="../rzahg/synch.js" type="text/javascript">
|
|
</script>
|
|
|
|
<a name="Top_Of_Page"></a>
|
|
|
|
<h2>ldap_init()--Perform an LDAP Initialization Operation</h2>
|
|
|
|
<div class="box" style="width: 70%;">
|
|
<br>
|
|
Syntax<br>
|
|
<pre>
|
|
#include <ldap.h>
|
|
|
|
LDAP *ldap_init(
|
|
char *<em>host</em>,
|
|
int <em>port</em>)
|
|
</pre>
|
|
|
|
<br>
|
|
Default Public Authority: *USE<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
Library Name/Service Program: QSYS/QGLDCLNT<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
Threadsafe: Yes<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
</div>
|
|
|
|
<p>The <strong>ldap_init()</strong> API is used to allocate an LDAP structure,
|
|
which is used to identify the connection and to maintain per-connection
|
|
information.</p>
|
|
|
|
<p>The <strong>ldap_init()</strong> 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().</p>
|
|
|
|
<p><strong>ldap_init()</strong> 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 <a href="ldap_open.htm">ldap_open()</a> is deprecated.
|
|
Use of <strong>ldap_init()</strong> instead of <a href="ldap_open.htm">
|
|
ldap_open()</a> is recommended.</p>
|
|
|
|
<br>
|
|
|
|
|
|
<h3>Authorities and Locks</h3>
|
|
|
|
<p>No i5/OS authority is required.</p>
|
|
|
|
<br>
|
|
|
|
|
|
<h3>Parameters</h3>
|
|
|
|
<dl>
|
|
<dt><strong>host</strong></dt>
|
|
|
|
<dd>(Input) Several methods are supported for specifying one or more target
|
|
LDAP servers, including the following:<br>
|
|
<br>
|
|
|
|
|
|
<table>
|
|
<tr>
|
|
<td width="15%" valign="top"><em>Explicit Host List</em></td>
|
|
<td width="85%" valign="top">Specifies the name of the host on which the LDAP
|
|
server is running. The <em>host</em> parameter may contain a blank-separated
|
|
list of hosts to try to connect to, and each host may optionally be of the form
|
|
<em>host:port</em>. If present, the <em>:port</em> overrides the <em>port</em>
|
|
parameter.<br>
|
|
<br>
|
|
The following are typical examples:<br>
|
|
<br>
|
|
|
|
|
|
<pre>
|
|
ld=ldap_init ("server1", ldap_port);
|
|
ld=ldap_init ("server2:1200", ldap_port);
|
|
ld=ldap_init ("server1:800 server2:2000 server3", ldap_port);
|
|
</pre>
|
|
|
|
<br>
|
|
<br>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top"><em>Localhost</em></td>
|
|
<td valign="top">If the <em>host</em> parameter is <strong>NULL</strong>, the
|
|
LDAP server will be assumed to be running on the local host.<br>
|
|
<br>
|
|
<br>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top"><em>Default Hosts</em></td>
|
|
<td valign="top">If the <em>host</em> parameter is set to <strong>
|
|
LDAP_URL_PREFIX</strong> ("ldap://") the LDAP library will attempt to locate
|
|
one or more default LDAP servers, with non-SSL ports, using the SecureWay <a
|
|
href="ldap_server_locate.htm">ldap_server_locate()</a> function. The port
|
|
specified on the call is ignored, since <strong>ldap_server_locate()</strong>
|
|
returns the port.<br>
|
|
<br>
|
|
|
|
|
|
<p>For example, the following two are equivalent:</p>
|
|
|
|
<pre>
|
|
ld=ldap_init ("ldap://", ldap_port);
|
|
ld=ldap_init (LDAP_URL_PREFIX, LDAP_PORT);
|
|
</pre>
|
|
|
|
<br>
|
|
|
|
|
|
<p>If more than one default server is located, the list is processed in
|
|
sequence, until an active server is found.</p>
|
|
|
|
<p>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:</p>
|
|
|
|
<pre>
|
|
ld=ldap_init ("ldap:///cn=fred, dc=austin, dc=ibm, dc=com", LDAP_PORT);
|
|
</pre>
|
|
|
|
<br>
|
|
|
|
|
|
<p>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.</p>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>For example, the following two are equivalent:</p>
|
|
|
|
<pre>
|
|
ld=ldap_init ("ldap://myserver", LDAP_PORT);
|
|
ld=ldap_init ("myserver", LDAP_PORT);
|
|
</pre>
|
|
|
|
<br>
|
|
<br>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top"><em>Local Socket</em></td>
|
|
<td valign="top">If the <em>host</em> parameter is prefixed with "/", the <em>
|
|
host</em> parameter is assumed to be the name of a UNIX socket (that is, socket
|
|
family is AF_UNIX) and <em>port</em> 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 i5/OS Secureway Directory
|
|
Services server listens on the <strong>/tmp/s.slapd</strong> local socket, in
|
|
addition to any configured TCP/IP ports.<br>
|
|
<br>
|
|
|
|
|
|
<p>For example:</p>
|
|
|
|
<pre>
|
|
ld=ldap_init ("/tmp/s.slapd", ldap_port);
|
|
</pre>
|
|
|
|
<br>
|
|
<br>
|
|
</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<br>
|
|
</dd>
|
|
|
|
<dt><strong>port</strong></dt>
|
|
|
|
<dd>Specifies the port number to which to connect. If the default IANA-assigned
|
|
port of 389 is desired, <strong>LDAP_PORT</strong> should be specified.</dd>
|
|
</dl>
|
|
|
|
<br>
|
|
<br>
|
|
|
|
|
|
<h3>Return Value</h3>
|
|
|
|
<dl>
|
|
<dt><strong>Pointer to an LDAP structure</strong></dt>
|
|
|
|
<dd>if the request was successful.<br>
|
|
<br>
|
|
</dd>
|
|
|
|
<dt><strong>NULL</strong></dt>
|
|
|
|
<dd>if the request was not successful.</dd>
|
|
</dl>
|
|
|
|
<br>
|
|
|
|
|
|
<h3>Error Conditions</h3>
|
|
|
|
<p>The <strong>ldap_init()</strong> API will return NULL if not successful.</p>
|
|
|
|
<br>
|
|
|
|
|
|
<h3>Error Messages</h3>
|
|
|
|
<p>The following message may be sent from this function.</p>
|
|
|
|
<table width="100%" cellpadding="3">
|
|
<tr>
|
|
<th align="left" valign="top">Message ID</th>
|
|
<th align="left" valign="top">Error Message Text</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td width="15%" valign="top">CPF3CF2 E</td>
|
|
<td width="85%" valign="top">Error(s) occurred during running of ldap_init
|
|
API.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
<br>
|
|
|
|
|
|
<h3>Related Information</h3>
|
|
|
|
<ul>
|
|
<li><a href="ldap_open.htm">ldap_open()</a> -- Open a connection to an LDAP
|
|
server (deprecated).</li>
|
|
|
|
<li><a href="ldap_ssl_init.htm">ldap_ssl_init()</a> -- Initializes an SSL
|
|
Connection</li>
|
|
|
|
<li><a href="ldap_set_option.htm">ldap_set_option()</a> -- Set an option
|
|
associated with an LDAP descriptor.</li>
|
|
|
|
<li><a href="ldap_get_option.htm">ldap_get_option()</a> -- Get an option
|
|
associated with an LDAP descriptor.</li>
|
|
|
|
<li><a href="ldap_version.htm">ldap_version()</a> -- Obtain LDAP version and
|
|
SSL cipher information.</li>
|
|
</ul>
|
|
|
|
<hr>
|
|
API introduced: V4R3
|
|
|
|
<hr>
|
|
<center>
|
|
<table cellpadding="2" cellspacing="2">
|
|
<tr align="center">
|
|
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href=
|
|
"dirserv1.htm">LDAP APIs</a> | <a href="aplist.htm">APIs by
|
|
category</a></td>
|
|
</tr>
|
|
</table>
|
|
</center>
|
|
</body>
|
|
</html>
|
|
|