722 lines
21 KiB
HTML
722 lines
21 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_set_option() -- Set 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 April 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_set_option() -- Set LDAP Options</h2>
|
|
|
|
<div class="box" style="width: 70%;">
|
|
<br>
|
|
Syntax<br>
|
|
<pre>
|
|
#include <ldap.h>
|
|
|
|
int ldap_set_option(
|
|
LDAP *<em>ld</em>,
|
|
int <em>optionToSet</em>,
|
|
const void *<em>optionValue</em> )
|
|
</pre>
|
|
|
|
<br>
|
|
Library Name/Service Program: QSYS/QGLDCLNT<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
Default Public Authority: *USE<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
Threadsafe: Yes<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
</div>
|
|
|
|
<p>The <strong>ldap_set_option()</strong> function is used to set options for
|
|
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><strong><em>ld</em></strong></dt>
|
|
|
|
<dd>(Input) An 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 <em>ld</em> is passed in, the default option value is set. Later calls 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>
|
|
will use the set value as the default for the option.<br>
|
|
<br>
|
|
</dd>
|
|
|
|
<dt><strong><em>optionToSet</em></strong></dt>
|
|
|
|
<dd>(Input) The option value to be set. See below for the list of supported
|
|
options.<br>
|
|
<br>
|
|
</dd>
|
|
|
|
<dt><strong><em>optionValue</em></strong></dt>
|
|
|
|
<dd>(Input) The address of the value. For LDAP V3 client options, <em>
|
|
optionValue</em> is the actual value to be set.</dd>
|
|
</dl>
|
|
|
|
<p>The following session settings can be set using the <strong>
|
|
ldap_set_option()</strong> API:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="35 65" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>LDAP_OPT_SIZELIMIT</em></td>
|
|
<td align="left" valign="top">Mmaximum number of entries that can be returned
|
|
on a search operation</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>LDAP_OPT_TIMELIMIT</em></td>
|
|
<td align="left" valign="top">Maximum number of seconds to wait for search
|
|
results</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>LDAP_OPT_REFHOPLIMIT</em></td>
|
|
<td align="left" valign="top">Maximum number of referrals in a sequence that
|
|
the client can follow</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>LDAP_OPT_DEREF</em></td>
|
|
<td align="left" valign="top">Rules for following aliases at the server</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>LDAP_OPT_REFERRALS</em></td>
|
|
<td align="left" valign="top">Whether referrals should be followed by the
|
|
client</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>LDAP_OPT_DEBUG</em></td>
|
|
<td align="left" valign="top">Client debug options</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>LDAP_OPT_SSL_CIPHER</em></td>
|
|
<td align="left" valign="top">SSL ciphers to use</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>LDAP_OPT_SSL_TIMEOUT</em></td>
|
|
<td align="left" valign="top">SSL timeout for refreshing session keys</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>LDAP_OPT_REBIND_FN</em></td>
|
|
<td align="left" valign="top">Address of application's setrebindproc
|
|
procedure</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>LDAP_OPT_PROTOCOL_VERSION</em></td>
|
|
<td align="left" valign="top">LDAP protocol version to use (V2 or V3)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>LDAP_OPT_SERVER_CONTROLS</em></td>
|
|
<td align="left" valign="top">Default server controls.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>LDAP_OPT_CLIENT_CONTROLS</em></td>
|
|
<td align="left" valign="top">Default client library controls</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>LDAP_OPT_UTF8_IO</em></td>
|
|
<td align="left" valign="top">String Data type UTF-8 option</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>The value returned by <a href="ldap_get_option.htm">ldap_get_option()</a>
|
|
when <strong>LDAP_OPT_PROTOCOL_VERSION</strong> is specified can be used to
|
|
determine how parameters should be passed to the <strong>
|
|
ldap_set_option()</strong> call. The easiest way to work with this
|
|
compatibility feature is to guarantee that calls to <strong>
|
|
ldap_set_option()</strong> are all performed while the <strong>
|
|
LDAP_OPT_PROTOCOL_VERSION</strong> 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 <strong>ldap_set_option()</strong>:</p>
|
|
|
|
<pre>
|
|
int sizeLimit=100;
|
|
|
|
int protocolVersion;
|
|
|
|
ldap_get_option( ld, LDAP_OPT_PROTOCOL_VERSION, &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, &sizeLimit );
|
|
}
|
|
</pre>
|
|
|
|
<p>Additional details on specific options for <strong>
|
|
ldap_set_option()</strong> are provided in the following sections.</p>
|
|
|
|
<br>
|
|
|
|
|
|
<h3><a name="sizelimit"></a>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, &sizevalue);
|
|
ldap_get_option( ld, LDAP_OPT_SIZELIMIT, &sizevalue);
|
|
</pre>
|
|
|
|
<br>
|
|
|
|
|
|
<h3><a name="timelimit"></a>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, &timevalue);
|
|
ldap_get_option( ld, LDAP_OPT_TIMELIMIT, &timevalue);
|
|
</pre>
|
|
|
|
<br>
|
|
|
|
|
|
<h3><a name="refhoplimit"></a>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, &hoplimit);
|
|
ldap_get_option( ld, LDAP_OPT_REFHOPLIMIT, &hoplimit);
|
|
</pre>
|
|
|
|
<br>
|
|
|
|
|
|
<h3><a name="deref"></a>LDAP_OPT_DEREF</h3>
|
|
|
|
<p>Specifies alternative rules for following aliases at the server. The default
|
|
is LDAP_DEREF_NEVER.</p>
|
|
|
|
<p>Supported values:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="5 95" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>0</em></td>
|
|
<td align="left" valign="top">LDAP_DEREF_NEVER</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>1</em></td>
|
|
<td align="left" valign="top">LDAP_DEREF_SEARCHING</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>2</em></td>
|
|
<td align="left" valign="top">LDAP_DEREF_FINDING</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>3</em></td>
|
|
<td align="left" valign="top">LDAP_DEREF_ALWAYS</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><strong>Examples:</strong></p>
|
|
|
|
<pre>
|
|
int deref = LDAP_DEREF_NEVER;
|
|
ldap_set_option( ld, LDAP_OPT_DEREF,&deref);
|
|
ldap_get_option( ld, LDAP_OPT_DEREF, &deref);
|
|
</pre>
|
|
|
|
<br>
|
|
|
|
|
|
<h3><a name="referrals"></a>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, &value);
|
|
</pre>
|
|
|
|
<br>
|
|
|
|
|
|
<h3><a name="debug"></a>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 cellpadding="5">
|
|
<!-- cols="30 70" -->
|
|
<tr>
|
|
<th align="left" valign="top" colspan="2">/* Debug levels */</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>LDAP_DEBUG_OFF</em></td>
|
|
<td align="left" valign="top">0x000</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>LDAP_DEBUG_TRACE</em></td>
|
|
<td align="left" valign="top">0x001</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>LDAP_DEBUG_PACKETS</em></td>
|
|
<td align="left" valign="top">0x002</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>LDAP_DEBUG_ARGS</em></td>
|
|
<td align="left" valign="top">0x004</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>LDAP_DEBUG_CONNS</em></td>
|
|
<td align="left" valign="top">0x008</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>LDAP_DEBUG_BER</em></td>
|
|
<td align="left" valign="top">0x010</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>LDAP_DEBUG_FILTER</em></td>
|
|
<td align="left" valign="top">0x020</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>LDAP_DEBUG_CONFIG</em></td>
|
|
<td align="left" valign="top">0x040</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>LDAP_DEBUG_ACL</em></td>
|
|
<td align="left" valign="top">0x080</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>LDAP_DEBUG_STATS</em></td>
|
|
<td align="left" valign="top">0x100</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>LDAP_DEBUG_STATS2</em></td>
|
|
<td align="left" valign="top">0x200</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>LDAP_DEBUG_SHELL</em></td>
|
|
<td align="left" valign="top">0x400</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>LDAP_DEBUG_PARSE</em></td>
|
|
<td align="left" valign="top">0x800</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>LDAP_DEBUG_ANY</em></td>
|
|
<td align="left" valign="top">0xffff</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><strong>Examples:</strong></p>
|
|
|
|
<pre>
|
|
int value;
|
|
int debugvalue= LDAP_DEBUG_TRACE | LDAP_DEBUG_PACKETS;
|
|
ldap_set_option( ld, LDAP_OPT_DEBUG, &debugvalue);
|
|
ldap_get_option( ld, LDAP_OPT_DEBUG, &value );
|
|
</pre>
|
|
|
|
<p>An alternative way to set the debug level is to set the LDAP_DEBUG
|
|
environment variable in the job that the client application will run in. The
|
|
environment variable is set to the same numerical value that the value variable
|
|
would be set to if <strong>ldap_set_option()</strong> was used. An example of
|
|
enabling client trace for an application using the LDAP_DEBUG environment
|
|
variable:</p>
|
|
|
|
<pre>
|
|
ADDENVVAR ENVVAR(LDAP_DEBUG) VALUE(0X0003)
|
|
</pre>
|
|
|
|
<p>After the client application has run, use</p>
|
|
|
|
<pre>
|
|
DMPUSRTRC jobnumber-of-the-client-job
|
|
</pre>
|
|
|
|
<p>Then, to display the trace information interactively, use</p>
|
|
|
|
<pre>
|
|
DSPPFM QAP0ZDMP QP0Znnnnnn -- where nnnnnn is the job number.
|
|
</pre>
|
|
|
|
<br>
|
|
|
|
|
|
<h3><a name="cipher"></a>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 cellpadding="5">
|
|
<!-- cols="30 70" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>LDAP_SSL_RC4_MD5_EX</em></td>
|
|
<td align="left" valign="top">03</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>LDAP_SSL_RC2_MD5_EX</em></td>
|
|
<td align="left" valign="top">05 (Non-export only)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>LDAP_SSL_RC4_SHA_US</em></td>
|
|
<td align="left" valign="top">04 (Non-export only)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>LDAP_SSL_RC4_MD5_US</em></td>
|
|
<td align="left" valign="top">06</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>LDAP_SSL_DES_SHA_US</em></td>
|
|
<td align="left" valign="top">09 (Non-export only)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>LDAP_SSL_3DES_SHA_US</em></td>
|
|
<td align="left" valign="top">0A (Non-export only)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">
|
|
<em>LDAP_SSL_AES_SHA_US</em></td>
|
|
<td align="left" valign="top">2F (Non-export only)</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<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, &getcipher );
|
|
</pre>
|
|
|
|
<br>
|
|
|
|
|
|
<h3><a name="timeout"></a>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, &value );
|
|
ldap_get_option( ld, LDAP_OPT_SSL_TIMEOUT, &value );
|
|
</pre>
|
|
|
|
<br>
|
|
|
|
|
|
<h3><a name="rebind_fn"></a>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, &proc_address);
|
|
ldap_get_option( ld, LDAP_OPT_REBIND_FN, &value);
|
|
</pre>
|
|
|
|
<br>
|
|
|
|
|
|
<h3><a name="version"></a>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 LDAP_VERSION3 for communicating with the LDAP server.
|
|
The default value of this option will be LDAP_VERSION2 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 <strong>
|
|
ldap_set_option()</strong> 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, &version2);
|
|
/* Example of Version 2 application setting version to version 3 */
|
|
ldap_set_option( ld, LDAP_OPT_PROTOCOL_VERSION, &version3);
|
|
ldap_get_option( ld, LDAP_OPT_PROTOCOL_VERSION, &value);
|
|
</pre>
|
|
|
|
<br>
|
|
|
|
|
|
<h3><a name="server_controls"></a>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, no server controls will be
|
|
sent.</p>
|
|
|
|
<p><strong>Example:</strong></p>
|
|
|
|
<pre>
|
|
ldap_set_option( ld, LDAP_OPT_SERVER_CONTROLS, &ctrlp);
|
|
</pre>
|
|
|
|
<br>
|
|
|
|
|
|
<h3><a name="client_controls"></a>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 <strong>ldap_set_option()</strong> 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>
|
|
|
|
<br>
|
|
|
|
|
|
<h3><a name="utf8_io"></a>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>It is important to note</strong> that 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). For example, string values passed in
|
|
to <a href="ldap_search.htm">ldap_search()</a> will be converted, but string
|
|
values passed in to <a href="ldap_init.htm">ldap_init</a> will not.</p>
|
|
|
|
<p><strong>It is also important to note</strong> that 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.</p>
|
|
|
|
<p>For more information on explicitly setting the locale for conversions, see
|
|
<a href="ldap_set_locale.htm">ldap_set_locale()</a>.</p>
|
|
|
|
<p><strong>Examples:</strong></p>
|
|
|
|
<pre>
|
|
int value;
|
|
ldap_set_option( ld, LDAP_OPT_UTF8_IO, (void *)LDAP_UTF8_XLATE_ON);
|
|
ldap_get_option( ld, LDAP_OPT_UTF8_IO, &value);
|
|
</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_set_option()</strong> function will return an LDAP error
|
|
code if not successful. See <a href="ldap_error_condt.htm">LDAP Client API
|
|
Error Conditions</a> for possible LDAP error codes values.</p>
|
|
|
|
<br>
|
|
|
|
|
|
<h3>Error Messages</h3>
|
|
|
|
<p>The following message may be sent from this function.</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="15 85" -->
|
|
<tr>
|
|
<th align="left" valign="top" nowrap>Message ID</th>
|
|
<th align="left" valign="top">Error Message Text</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF3CF2 E</td>
|
|
<td align="left" valign="top">Error(s) occurred during running of
|
|
ldap_set_option API.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
<br>
|
|
|
|
|
|
<h3>Related Information</h3>
|
|
|
|
<ul>
|
|
<li><a href="ldap_get_option.htm">ldap_get_option()</a> -- Retrieve an option
|
|
associated with an LDAP descriptor.</li>
|
|
|
|
<li><a href="ldap_init.htm">ldap_init()</a> -- Initializes a session with an
|
|
LDAP server.</li>
|
|
|
|
<li><a href="ldap_open.htm">ldap_open()</a> -- Open a connection to an LDAP
|
|
server (deprecated).</li>
|
|
|
|
<li><a href="ldap_set_rebind_proc.htm">ldap_set_rebind_proc()</a> -- Set rebind
|
|
procedure</li>
|
|
|
|
<li><a href="ldap_version.htm">ldap_version()</a> -- Obtain LDAP version and
|
|
SSL cipher information.</li>
|
|
</ul>
|
|
|
|
<br>
|
|
<hr>
|
|
API introduced: V4R5
|
|
|
|
<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>
|
|
|