806 lines
20 KiB
HTML
806 lines
20 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_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>
|
|
Syntax<br>
|
|
<pre>
|
|
#include <ldap.h>
|
|
|
|
int ldap_get_option(
|
|
LDAP <em>*ld</em>,
|
|
int <em>optionToGet</em>,
|
|
void <em>*optionValue</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>
|
|
|
|
<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, &sizevalue);
|
|
ldap_get_option( ld, LDAP_OPT_SIZELIMIT, &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, &timevalue);
|
|
ldap_get_option( ld, LDAP_OPT_TIMELIMIT, &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, &hoplimit);
|
|
ldap_get_option( ld, LDAP_OPT_REFHOPLIMIT, &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, &deref);
|
|
ldap_get_option( ld, LDAP_OPT_DEREF, &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, &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, &debugvalue);
|
|
ldap_get_option( ld, LDAP_OPT_DEBUG, &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, &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, &value );
|
|
ldap_get_option( ld, LDAP_OPT_SSL_TIMEOUT, &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, &proc_address);
|
|
ldap_get_option( ld, LDAP_OPT_REBIND_FN, &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, &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>
|
|
|
|
<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, &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>
|
|
|
|
<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, &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, &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, &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, &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, &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, &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, &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>
|
|
|