friedkiwi/ibm-information-center
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
8826eae394
ibm-information-center/dist/eclipse/plugins/i5OS.ic.apis_5.4.0.1/ldap_get_option.htm

806 lines
20 KiB
HTML
Raw Normal View History

Add readme and dist folders
2024-04-02 14:02:31 +00:00
<!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_get_option()--Retrieve LDAP Options</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_get_option()--Retrieve LDAP Options</h2>
<div class="box" style="width: 70%;">
<br>
&nbsp;&nbsp;Syntax<br>
<pre>
#include &lt;ldap.h&gt;
int ldap_get_option(
LDAP <em>*ld</em>,
int <em>optionToGet</em>,
void <em>*optionValue</em>)
</pre>
<br>
&nbsp;&nbsp;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Library Name/Service Program: QSYS/QGLDCLNT<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: Yes<br>
<!-- iddvc RMBR -->
<br>
</div>
<br>
<p>The <strong>ldap_get_option()</strong> function is used to query settings
associated with the specified LDAP connection.</p>
<br>
<h3>Authorities and Locks</h3>
<p>No i5/OS authority is required.</p>
<br>
<h3>Parameters</h3>
<dl>
<dt><em>ld</em></dt>
<dd>(Input) The LDAP pointer returned by a previous call to <a href=
"ldap_init.htm">ldap_init()</a>, <a href="ldap_ssl_init.htm">
ldap_ssl_init()</a>, or <a href="ldap_open.htm">ldap_open()</a>. If a NULL ld
is passed in, the default value for the option is retrieved.<br><br></dd>
<dt><em>optionToGet</em></dt>
<dd>(Input) The option value that is to be queried on the <strong>
ldap_get_option()</strong> call. See below for the list of supported
options.<br><br></dd>
<dt><em>optionValue</em></dt>
<dd>(Input) The address of the storage in which to return the queried
value using <strong>ldap_get_option()</strong>.</dd>
</dl>
<p>The following session settings can be get using the <strong>
ldap_get_option()</strong> API:</p>
<table width="100%" cellpadding="5">
<!-- cols="40 60" -->
<tr>
<td valign="top">LDAP_OPT_SIZELIMIT</td>
<td valign="top">maximum number of entries that can be returned on
a search operation</td>
</tr>
<tr>
<td valign="top">LDAP_OPT_TIMELIMIT</td>
<td valign="top">maximum number of seconds to wait for search results.</td>
</tr>
<tr>
<td valign="top">LDAP_OPT_REFHOPLIMIT</td>
<td valign="top">maximum number of referrals in a sequence that the client can
follow</td>
</tr>
<tr>
<td valign="top">LDAP_OPT_DEREF</td>
<td valign="top">rules for following aliases at the server.</td>
</tr>
<tr>
<td valign="top">LDAP_OPT_REFERRALS</td>
<td valign="top">whether or not referrals should be followed by the
client.</td>
</tr>
<tr>
<td valign="top">LDAP_OPT_DEBUG</td>
<td valign="top">debug options.</td>
</tr>
<tr>
<td valign="top">LDAP_OPT_SSL_CIPHER</td>
<td valign="top">SSL ciphers to use.</td>
</tr>
<tr>
<td valign="top">LDAP_OPT_SSL_TIMEOUT</td>
<td valign="top">SSL timeout for refreshing session keys</td>
</tr>
<tr>
<td valign="top">LDAP_OPT_REBIND_FN</td>
<td valign="top">address of application's setrebindproc procedure.</td>
</tr>
<tr>
<td valign="top">LDAP_OPT_PROTOCOL_VERSION</td>
<td valign="top">LDAP protocol version to use (V2 or V3).</td>
</tr>
<tr>
<td valign="top">LDAP_OPT_SERVER_CONTROLS</td>
<td valign="top">default server controls.</td>
</tr>
<tr>
<td valign="top">LDAP_OPT_CLIENT_CONTROLS</td>
<td valign="top">default client library controls.</td>
</tr>
<tr>
<td valign="top">LDAP_OPT_UTF8_IO</td>
<td valign="top">mode for converting string data between the local code page
and UTF-8</td>
</tr>
<tr>
<td valign="top">LDAP_OPT_HOST_NAME</td>
<td valign="top">current host name</td>
</tr>
<tr>
<td valign="top">LDAP_OPT_ERROR_NUMBER</td>
<td valign="top">error number</td>
</tr>
<tr>
<td valign="top">LDAP_OPT_ERROR_STRING</td>
<td valign="top">error string</td>
</tr>
<tr>
<td valign="top">LDAP_OPT_EXT_ERROR</td>
<td valign="top">extended error code</td>
</tr>
<tr>
<td valign="top">LDAP_OPT_EXT_GSS_ERR</td>
<td valign="top">GSSAPI extended error code</td>
</tr>
</table>
<br>
<p>Additional details on specific options for <strong>
ldap_get_option()</strong> are provided in the following sections.</p>
<br>
<h3>LDAP_OPT_SIZELIMIT</h3>
<p>Specifies the maximum number of entries that can be returned on a search
operation. Note: the actual size limit for operations is also bounded by the
maximum number of entries that the server is configured to return. Thus, the
actual size limit will be the lesser of the value specified on this option and
the value configured in the LDAP server. The default sizelimit is unlimited,
specified with a value of zero (thus deferring to the sizelimit setting of the
LDAP server).</p>
<p><strong>Examples:</strong></p>
<pre>
sizevalue=50;
ldap_set_option( ld, LDAP_OPT_SIZELIMIT, &amp;sizevalue);
ldap_get_option( ld, LDAP_OPT_SIZELIMIT, &amp;sizevalue );
</pre>
<br>
<h3>LDAP_OPT_TIMELIMIT</h3>
<p>Specifies the number of seconds to wait for search results. Note: the actual
time limit for operations is also bounded by the maximum time that the server
is configured to allow. Thus, the actual time limit will be the lesser of the
value specified on this option and the value configured in the LDAP server. The
default is unlimited (specified with a value of zero).</p>
<p><strong>Examples:</strong></p>
<pre>
timevalue=50;
ldap_set_option( ld, LDAP_OPT_TIMELIMIT, &amp;timevalue);
ldap_get_option( ld, LDAP_OPT_TIMELIMIT, &amp;timevalue );
</pre>
<p><br>
<br>
</p>
<h3>LDAP_OPT_REFHOPLIMIT</h3>
<p>Specifies the maximum number of hops that the client library will take when
chasing referrals. The default is 5.</p>
<p><strong>Examples:</strong></p>
<pre>
hoplimit=7;
ldap_set_option( ld, LDAP_OPT_REFHOPLIMIT, &amp;hoplimit);
ldap_get_option( ld, LDAP_OPT_REFHOPLIMIT, &amp;hoplimit);
</pre>
<br>
<h3>LDAP_OPT_DEREF</h3>
<p>Specifies alternative rules for following aliases at the server. The default
is <strong>LDAP_DEREF_NEVER</strong>.</p>
<p>Supported values:</p>
<table width="100%" cellpadding="5">
<tr>
<td width="30%" valign="top">LDAP_DEREF_NEVER</td>
<td width="70%" valign="top">0</td>
</tr>
<tr>
<td valign="top">LDAP_DEREF_SEARCHING</td>
<td valign="top">1</td>
</tr>
<tr>
<td valign="top">LDAP_DEREF_FINDING</td>
<td valign="top">2</td>
</tr>
<tr>
<td valign="top">LDAP_DEREF_ALWAYS</td>
<td valign="top">3</td>
</tr>
</table>
<br>
<p><strong>Examples:</strong></p>
<pre>
int deref = LDAP_DEREF_NEVER;
ldap_set_option( ld, LDAP_OPT_DEREF, &amp;deref);
ldap_get_option( ld, LDAP_OPT_DEREF, &amp;deref);
</pre>
<br>
<h3>LDAP_OPT_REFERRALS</h3>
<p>Specifies whether the LDAP library will automatically follow referrals
returned by LDAP servers or not. It can be set to one of the constants <strong>
LDAP_OPT_ON</strong> or <strong>LDAP_OPT_OFF</strong>. By default, the LDAP
client will follow referrals.</p>
<p><strong>Examples:</strong></p>
<pre>
int value;
ldap_set_option( ld, LDAP_OPT_REFFERALS, (void *)LDAP_OPT_ON);
ldap_get_option( ld, LDAP_OPT_REFFERALS, &amp;value);
</pre>
<br>
<h3>LDAP_OPT_DEBUG</h3>
<p>Specifies a bit-map that indicates the level of debug trace for the LDAP
library.</p>
<p>Supported values:</p>
<table width="100%" cellpadding="5">
<tr>
<td width="30%" valign="top">LDAP_DEBUG_OFF</td>
<td width="70%" valign="top">0x000</td>
</tr>
<tr>
<td valign="top">LDAP_DEBUG_TRACE</td>
<td valign="top">0x001</td>
</tr>
<tr>
<td valign="top">LDAP_DEBUG_PACKETS</td>
<td valign="top">0x002</td>
</tr>
<tr>
<td valign="top">LDAP_DEBUG_ARGS</td>
<td valign="top">0x004</td>
</tr>
<tr>
<td valign="top">LDAP_DEBUG_CONNS</td>
<td valign="top">0x008</td>
</tr>
<tr>
<td valign="top">LDAP_DEBUG_BER</td>
<td valign="top">0x010</td>
</tr>
<tr>
<td valign="top">LDAP_DEBUG_FILTER</td>
<td valign="top">0x020</td>
</tr>
<tr>
<td valign="top">LDAP_DEBUG_CONFIG</td>
<td valign="top">0x040</td>
</tr>
<tr>
<td valign="top">LDAP_DEBUG_ACL</td>
<td valign="top">0x080</td>
</tr>
<tr>
<td valign="top">LDAP_DEBUG_STATS</td>
<td valign="top">0x100</td>
</tr>
<tr>
<td valign="top">LDAP_DEBUG_STATS2</td>
<td valign="top">0x200</td>
</tr>
<tr>
<td valign="top">LDAP_DEBUG_SHELL</td>
<td valign="top">0x400</td>
</tr>
<tr>
<td valign="top">LDAP_DEBUG_PARSE</td>
<td valign="top">0x800</td>
</tr>
<tr>
<td valign="top">LDAP_DEBUG_ANY</td>
<td valign="top">0xffff<br>
</td>
</tr>
</table>
<br>
<br>
<p><strong>Examples:</strong></p>
<pre>
int value;
int debugvalue= LDAP_DEBUG_TRACE | LDAP_DEBUG_PACKETS;
ldap_set_option( ld, LDAP_OPT_DEBUG, &amp;debugvalue);
ldap_get_option( ld, LDAP_OPT_DEBUG, &amp;value );
</pre>
<br>
<h3>LDAP_OPT_SSL_CIPHER</h3>
<p>Specifies a set of one or more ciphers to be used when negotiating the
cipher algorithm with the LDAP server. The first cipher in the list that is
common with the list of ciphers supported by the server is chosen. For the
export version of the library, the value used is "0306". For the domestic
version of the library, the default value is "05040A090306". Note that the
cipher string supported by the export version of the LDAP client library is
fixed and cannot be modified.</p>
<p>Supported ciphers:</p>
<table width="100%" cellpadding="5">
<tr>
<td width="30%" valign="top">LDAP_SSL_RC4_MD5_EX</td>
<td width="70%" valign="top">03</td>
</tr>
<tr>
<td valign="top">LDAP_SSL_RC2_MD5_EX</td>
<td valign="top">06</td>
</tr>
<tr>
<td valign="top">LDAP_SSL_RC4_SHA_US</td>
<td valign="top">05 (Non-export only)</td>
</tr>
<tr>
<td valign="top">LDAP_SSL_RC4_MD5_US</td>
<td valign="top">04 (Non-export only)</td>
</tr>
<tr>
<td valign="top">LDAP_SSL_DES_SHA_US</td>
<td valign="top">09 (Non-export only)</td>
</tr>
<tr>
<td valign="top">LDAP_SSL_3DES_SHA_US</td>
<td valign="top">0A (Non-export only)</td>
</tr>
<tr>
<td valign="top">
LDAP_SSL_AES_SHA_US</td>
<td valign="top">2F (Non-export only)</td>
</tr>
</table>
<br>
<p><strong>Examples:</strong></p>
<pre>
char *setcipher = "2F090A";
char *getcipher;
ldap_set_option( ld, LDAP_OPT_SSL_CIPHER, setcipher);
ldap_get_option( ld, LDAP_OPT_SSL_CIPHER, &amp;getcipher );
</pre>
<br>
<p>Use <a href="ldap_memfree.htm">ldap_memfree()</a> to free the memory
returned by the call to <strong>ldap_get_option()</strong>.</p>
<br>
<h3>LDAP_OPT_SSL_TIMEOUT</h3>
<p>Specifies in seconds the SSL inactivity timer. After the specified seconds,
in which no SSL activity has occurred, the SSL connection will be refreshed
with new session keys. A smaller value may help increase security, but will
have a small impact on performance. The default SSL timeout value is 43200
seconds.</p>
<p><strong>Examples:</strong></p>
<pre>
value = 100;
ldap_set_option( ld, LDAP_OPT_SSL_TIMEOUT, &amp;value );
ldap_get_option( ld, LDAP_OPT_SSL_TIMEOUT, &amp;value)
</pre>
<br>
<h3>LDAP_OPT_REBIND_FN</h3>
<p>Specifies the address of a routine to be called by the LDAP library when the
need arises to authenticate a connection with another LDAP server. This can
occur, for example, when the LDAP library is chasing a referral. If a routine
is not defined, referrals will always be chased using the anonymous identity. A
default routine is not defined.</p>
<p><strong>Examples:</strong></p>
<pre>
extern LDAPRebindProc proc_address;
LDAPRebindProc value;
ldap_set_option( ld, LDAP_OPT_REBIND_FN, &amp;proc_address);
ldap_get_option( ld, LDAP_OPT_REBIND_FN, &amp;value);
</pre>
<h3>LDAP_OPT_PROTOCOL_VERSION</h3>
<p>Specifies the LDAP protocol to be used by the LDAP client library when
connecting to an LDAP server. Also used to determine which LDAP protocol is
being used for the connection. For an application that uses <a href=
"ldap_init.htm">ldap_init()</a> to create the LDAP connection the default value
of this option will be <strong>LDAP_VERSION3</strong> for communicating with
the LDAP server. The default value of this option will be <strong>
LDAP_VERSION2</strong> if the application uses the deprecated <a href=
"ldap_open.htm">ldap_open()</a> API. In either case, the <strong>
LDAP_OPT_PROTOCOL_VERSION</strong> option can be used with <a href=
"ldap_set_option.htm">ldap_set_option()</a> to change the default. The LDAP
protocol version should be reset prior to issuing the bind (or any operation
that causes an implicit bind).</p>
<p><strong>Examples:</strong></p>
<pre>
version2 = LDAP_VERSION2;
version3 = LDAP_VERSION3;
/* Example for Version 3 application setting version to version 2 */
ldap_set_option( ld, LDAP_OPT_PROTOCOL_VERSION, &amp;version2);
/* Example of Version 2 application setting version to version 3 */
ldap_set_option( ld, LDAP_OPT_PROTOCOL_VERSION, &amp;version3);
ldap_get_option( ld, LDAP_OPT_PROTOCOL_VERSION, &amp;value);
</pre>
<p>The value returned by <strong>ldap_get_option()</strong> when <strong>
LDAP_OPT_PROTOCOL_VERSION</strong> is specified can be used to determine how
parameters should be passed to the <a href="ldap_set_option.htm">
ldap_set_option()</a> call. The easiest way to work with this compatibility
feature is to guarantee that calls to <a href="ldap_set_option.htm">
ldap_set_option()</a> are all performed while LDAP_OPT_PROTOCOL_VERSION is set
to the same value. If this cannot be guaranteed by the application, then follow
the format of the example below when coding the call to <a href=
"ldap_set_option.htm">ldap_set_option()</a>:</p>
<p><strong>Examples:</strong></p>
<pre>
int sizeLimit=100;
int protocolVersion;
ldap_get_option( ld, LDAP_OPT_PROTOCOL_VERSION, &amp;protocolVersion );
if ( protocolVersion == LDAP_VERSION2 ) {
ldap_set_option( ld, LDAP_OPT_SIZELIMIT, (void *)sizeLimit );
} else { /* the protocol version is LDAP_VERSION3 */
ldap_set_option( ld, LDAP_OPT_SIZELIMIT, &amp;sizeLimit );
}
</pre>
<br>
<h3>LDAP_OPT_SERVER_CONTROLS</h3>
<p>Specifies a default list of server controls to be sent with each request.
The default list can be overridden by specifying a server control, or list of
server controls, on specific APIs. By default, there are no settings for Server
Controls.</p>
<p><strong>Example:</strong></p>
<pre>
ldap_set_option( ld, LDAP_OPT_SERVER_CONTROLS, &amp;ctrlp);
</pre>
<br>
<h3>LDAP_OPT_CLIENT_CONTROLS</h3>
<p>Specifies a default list of client controls to be processed by the client
library with each request. Since client controls are not defined for this
version of the library, the ldap_set_option() API can be used to define a set
of default, non-critical client controls. If one or more client controls in the
set is critical, the entire list is rejected with a return code of <strong>
LDAP_UNAVAILABLE_CRITICAL_EXTENSION</strong>.</p>
<h3>LDAP_OPT_UTF8_IO</h3>
<p>Specifies whether the LDAP library will automatically convert string data to
and from the local code page. It can be set to one of the constants <strong>
LDAP_UTF8_XLATE_ON</strong> or <strong>LDAP_UTF8_XLATE_OFF</strong>. By
default, the LDAP library will convert string data.</p>
<p>When conversion is disabled, the LDAP library assumes that data received
from the application by LDAP APIs is already represented in UTF-8. Similarly,
the LDAP library assumes that the application is prepared to receive string
data from the LDAP library represented in UTF-8 (or as binary).</p>
<p>When <strong>LDAP_UTF8_XLATE_ON</strong> is set (the default), the LDAP library
assumes that string data received from the application by LDAP APIs is in the
default (or explicitly designated) code page. Similarly, all string data
returned from the LDAP library (back to the application) is converted to the
designated local code page.</p>
<p><strong>Notes:</strong></p>
<ol>
<li>Only string data supplied on connection-based APIs will be translated (that is,
only those APIs that include an <strong>ld</strong> will be subject to
translation).</li>
<li>Translation of strings from a UTF-8 encoding to local code page may result
in loss of data when one or more characters in the UTF-8 encoding cannot be
represented in the local code page. When this occurs, a substitution character
replaces any UTF-8 characters that cannot be converted to the local code
page.</li>
</ol>
<p><strong>Example:</strong></p>
<pre>
int value;
ldap_get_option( ld, LDAP_OPT_UTF8_IO, &amp;value);
</pre>
<br>
<h3>LDAP_OPT_HOST_NAME</h3>
<p>This is a read-only option that returns a pointer to the hostname for the
original connection (as specified on <a href="ldap_init.htm">ldap_init()</a>,
<a href="ldap_open.htm">ldap_open()</a>, or <a href="ldap_ssl_init.htm">
ldap_ssl_init()</a>).</p>
<p><strong>Example:</strong></p>
<pre>
char *hostname;
ldap_get_option( ld, LDAP_OPT_HOST_NAME, &amp;hostname);
</pre>
<p>Use <a href="ldap_memfree.htm">ldap_memfree()</a> to free the memory
returned by the call to <strong>ldap_get_option()</strong>.</p>
<br>
<h3>LDAP_OPT_ERROR_NUMBER</h3>
<p>This is a read-only option that returns the error code associated with the
most recent LDAP error that occurred for the specified LDAP connection.</p>
<p><strong>Example:</strong></p>
<pre>
int error;
ldap_get_option( ld, LDAP_OPT_ERROR_NUMBER, &amp;error);
</pre>
<br>
<h3>LDAP_OPT_ERROR_STRING</h3>
<p>This is a read-only option that returns the text message associated with the
most recent LDAP error that occurred for the specified LDAP connection.</p>
<p><strong>Example:</strong></p>
<pre>
char *error_string;
ldap_get_option( ld, LDAP_OPT_ERROR_STRING, &amp;error_string);
</pre>
<p>Use <a href="ldap_memfree.htm">ldap_memfree()</a> to free memory returned by
the call to <strong>ldap_get_option()</strong>.</p>
<br>
<h3>LDAP_OPT_EXT_ERROR</h3>
<p>This is a read-only option that returns the extended error code. For
example, if an SSL error occurred when attempting to call an <a href=
"ldap_search_s.htm">ldap_search_s()</a> API, the actual SSL error can be
obtained by using <strong>LDAP_OPT_EXT_ERROR</strong>.</p>
<p><strong>Example:</strong></p>
<pre>
int exterror;
ldap_get_option( ld, LDAP_OPT_EXT_ERROR, &amp;exterror);
</pre>
<p>Returns errors reported by the SSL library.</p>
<br>
<h3>LDAP_OPT_EXT_GSS_ERR</h3>
<p>This is a read-only option that returns the extended error code from SASL
binds using the GSSAPI mechanism.</p>
<p><strong>Example:</strong></p>
<pre>
int gsserror;
ldap_get_option( ld, LDAP_OPT_EXT_GSS_ERR, &amp;gsserror);
</pre>
<br>
<h3>Return Value</h3>
<dl>
<dt><strong>LDAP_SUCCESS</strong></dt>
<dd>if the request was successful.<br>
<br>
</dd>
<dt><strong>another LDAP error code</strong></dt>
<dd>if the request was not successful.</dd>
</dl>
<br>
<h3>Error Conditions</h3>
<p>The <strong>ldap_get_option()</strong> API will return an LDAP error code if
not successful. See <a href="ldap_error_condt.htm">LDAP Client API Error
Conditions</a> for possible values for LDAP error codes.</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_get_option API.</td>
</tr>
</table>
<br>
<br>
<h3>Related Information</h3>
<ul>
<li><a href="ldap_init.htm">ldap_init()</a> -- Initializes a session with an
LDAP server.</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_version.htm">ldap_version()</a> -- Obtain LDAP version and
SSL cipher information.</li>
</ul>
<br>
<hr>
API introduced: V4R3
<hr>
<table align="center" 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>
</body>
</html>
Reference in New Issue Copy Permalink