20728 lines
773 KiB
Plaintext
20728 lines
773 KiB
Plaintext
<!--
|
|
|
|
Copyright 2000-2007 Sun Microsystems, Inc. All Rights Reserved.
|
|
Portions copyright 1999 Netscape Communications Corporation. All
|
|
Rights Reserved.
|
|
|
|
The contents of this document are subject to the terms of the
|
|
Creative Commons Attribution-ShareAlike 2.5 license or any later
|
|
version (the "License"). You may not use this document except in
|
|
compliance with the License.
|
|
|
|
See the License for the specific language governing
|
|
permissions and limitations under the License. You can obtain
|
|
a copy of the License at
|
|
http://creativecommons.org/licenses/by-sa/2.5/legalcode.
|
|
|
|
-->
|
|
<chapter id="bdane"><title>&DirectorySDKForC; Function Reference</title>
|
|
<indexterm>
|
|
<primary>functions</primary>
|
|
<see>C SDK functions</see></indexterm><indexterm>
|
|
<primary>C SDK functions</primary>
|
|
</indexterm><highlights>
|
|
<para>This chapter contains detailed reference material for each public function
|
|
of &DirectorySDKForC;. Each reference gives a description of the function,
|
|
and its usage syntax, parameters and return values. In many cases, an example
|
|
program is also included. The chapter contains the following sections:</para>
|
|
<itemizedlist>
|
|
<listitem><para><olink targetptr="bdanf">Typographic Conventions</olink></para>
|
|
</listitem>
|
|
<listitem><para><olink targetptr="bdang">Function Summary by Task</olink></para>
|
|
</listitem>
|
|
<listitem><para><olink targetptr="bdanx">Functions Alphabetically</olink></para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</highlights>
|
|
<sect1 id="bdanf"><title>Typographic Conventions</title>
|
|
<para>The general purpose of a function is usually given by its name. <olink targetptr="function-naming-conventions">Table 21–1</olink> lists the
|
|
naming conventions used when adding suffixes to function names.</para>
|
|
<table frame="topbot" id="function-naming-conventions"><title>Function Naming
|
|
Conventions</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Suffix</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>_ext</literal></para></entry>
|
|
<entry>
|
|
<para>Identifies extended functions introduced for LDAP v3. These functions
|
|
are augmented through additional parameters, as compared to the functions
|
|
they replace. As LDAP v3 has become widely adopted, it is recommended you
|
|
use extended functions whenever possible in your new applications.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>_s</literal></para></entry>
|
|
<entry>
|
|
<para>Identifies the synchronous form of functions. A synchronous function
|
|
will not return until it receives a response from the server, thereby blocking
|
|
the caller. Similar function names without this suffix are asynchronous, allowing
|
|
the caller to perform other operations while waiting for a result.</para>
|
|
<para>The synchronous and asynchronous forms exist only for functions which
|
|
involve possible delays due to communication with the LDAP server. Functions
|
|
which do not involve communication do not use this suffix.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect1>
|
|
<sect1 id="bdang"><title>Function Summary by Task</title>
|
|
<indexterm>
|
|
<primary>C SDK</primary>
|
|
<secondary>functions</secondary>
|
|
<tertiary>summary of</tertiary>
|
|
</indexterm><indexterm>
|
|
<primary>functions</primary>
|
|
<secondary>C SDK</secondary>
|
|
</indexterm>
|
|
<para>In the following sections the functions of &DirectorySDKForC; are
|
|
grouped into task categories.</para>
|
|
<sect2 id="bdanh"><title>Working with Basic Encoding Rules</title>
|
|
<indexterm>
|
|
<primary>C SDK</primary>
|
|
<secondary>functions</secondary>
|
|
<tertiary>for BER</tertiary>
|
|
</indexterm>
|
|
<para>The functions listed in <olink targetptr="ber-encoding-functions">Table
|
|
21–2</olink> may be used to encode and decode with Basic Encoding Rules
|
|
(BER). They are often used inside of control and extension values.</para>
|
|
<table frame="topbot" id="ber-encoding-functions"><title>Functions to Encode
|
|
and Decode BER</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Function</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><olink targetptr="bdany">ber_alloc</olink>, <olink targetptr="bdanz">ber_alloc_t
|
|
</olink>, <olink targetptr="bdapl">ber_sockbuf_alloc</olink>, <olink targetptr="bdapq">ber_special_alloc</olink></para></entry>
|
|
<entry>
|
|
<para>Allocate new BER elements.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdaoa">ber_bvecfree</olink>, <olink targetptr="bdaoc">ber_bvfree
|
|
</olink>, <olink targetptr="bdaog">ber_free</olink>, <olink targetptr="bdapm">ber_sockbuf_free
|
|
</olink>, <olink targetptr="bdapn">ber_sockbuf_free_data</olink></para></entry>
|
|
<entry>
|
|
<para>Free allocated memory.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdaob">ber_bvdup</olink>, <olink targetptr="bdaod">ber_dup
|
|
</olink></para></entry>
|
|
<entry>
|
|
<para>Duplicate BER structures.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdaor">ber_init</olink>, <olink targetptr="bdaos">ber_init_w_nullchar
|
|
</olink></para></entry>
|
|
<entry>
|
|
<para>Construct new structures.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdaoh">ber_get_boolean</olink>, <olink targetptr="bdaoi">
|
|
ber_get_int</olink>, <olink targetptr="bdaoj">ber_get_next</olink>, <olink targetptr="bdaok">ber_get_next_buffer</olink>, <olink targetptr="bdaol">ber_get_next_buffer_ext
|
|
</olink>, <olink targetptr="bdaom">ber_get_null</olink>, <olink targetptr="bdaon">
|
|
ber_get_option</olink>, <olink targetptr="bdaoo">ber_get_stringa</olink>, <olink targetptr="bdaop">ber_get_stringal</olink>, <olink targetptr="bdaoq">ber_get_stringb
|
|
</olink></para></entry>
|
|
<entry>
|
|
<para>Retrieve miscellaneous information.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdaow">ber_put_bitstring</olink>, <olink targetptr="bdaox">ber_put_boolean</olink>, <olink targetptr="bdaoy">ber_put_enum</olink>, <olink targetptr="bdaoz">ber_put_int</olink>, <olink targetptr="bdapa">ber_put_null</olink>, <olink targetptr="bdapb">ber_put_ostring</olink>, <olink targetptr="bdapc">ber_put_seq</olink>, <olink targetptr="bdapd">ber_put_set</olink>, <olink targetptr="bdape">ber_put_string</olink></para>
|
|
</entry>
|
|
<entry>
|
|
<para>Write miscellaneous information.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdaoe">ber_first_element</olink>, <olink targetptr="bdaot">ber_next_element</olink>, <olink targetptr="bdaou">ber_peek_tag
|
|
</olink>, <olink targetptr="bdapk">ber_skip_tag</olink></para></entry>
|
|
<entry>
|
|
<para>Target specific elements and tags.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdapi">ber_set_option</olink>, <olink targetptr="bdapj">ber_set_string_translators
|
|
</olink></para></entry>
|
|
<entry>
|
|
<para>Set session parameters.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdaof">ber_flatten</olink>, <olink targetptr="bdaov">ber_printf
|
|
</olink>, <olink targetptr="bdapf">ber_read</olink>, <olink targetptr="bdapg">ber_reset
|
|
</olink>, <olink targetptr="bdaph">ber_scanf</olink>, <olink targetptr="bdapo">ber_sockbuf_get_option
|
|
</olink>, <olink targetptr="bdapp">ber_sockbuf_set_option</olink>, <olink targetptr="bdapt">ber_start_seq</olink>, <olink targetptr="bdapt">ber_start_seq</olink>, <olink targetptr="bdapu">ber_start_set</olink>, <olink targetptr="bdapv">ber_svecfree</olink>, <olink targetptr="bdapw">ber_write</olink></para></entry>
|
|
<entry>
|
|
<para>Miscellaneous functions.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect2>
|
|
<sect2 id="bdani"><title>Managing LDAP Sessions</title>
|
|
<indexterm>
|
|
<primary>C SDK</primary>
|
|
<secondary>functions</secondary>
|
|
<tertiary>for LDAP sessions</tertiary>
|
|
</indexterm>
|
|
<para>The functions listed in <olink targetptr="manage-session-functions">Table
|
|
21–3</olink> manage the different phases of an LDAP session: initialization,
|
|
configuration, authentication (binding) and termination (unbinding).</para>
|
|
<table frame="topbot" id="manage-session-functions"><title>Functions to Manage
|
|
an LDAP Session</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Function</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><olink targetptr="bdasv">ldap_init</olink>, <olink targetptr="bdaxr">prldap_init
|
|
</olink> (IPv6)</para></entry>
|
|
<entry>
|
|
<para>Initializes an LDAP session.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdavs">ldapssl_init</olink></para></entry>
|
|
<entry>
|
|
<para>Initializes an LDAP session over SSL.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdavu">ldapssl_pkcs_init</olink></para></entry>
|
|
<entry>
|
|
<para>Initializes a thread-safe session over SSL.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdass">ldap_get_option</olink>, <olink targetptr="bdavg">
|
|
ldap_set_option</olink></para></entry>
|
|
<entry>
|
|
<para>Read and writes the current preference settings for a session.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdati">ldap_memcache_init</olink>, <olink targetptr="bdatj">ldap_memcache_set</olink>, <olink targetptr="bdath">ldap_memcache_get
|
|
</olink>, <olink targetptr="bdatk">ldap_memcache_update</olink>, <olink targetptr="bdatg">ldap_memcache_flush</olink>, <olink targetptr="bdatf">ldap_memcache_destroy
|
|
</olink></para></entry>
|
|
<entry>
|
|
<para>Creates a memory cache and uses it for search results from this session.
|
|
Manages the data in the cache and frees the memory when the cache is no longer
|
|
needed. The in-memory cache for search results is an extension to the API.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdawj">ldap_unbind_ext</olink></para></entry>
|
|
<entry>
|
|
<para>Ends an LDAP session and frees the associated data structures.</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect2>
|
|
<sect2 id="bdanj"><title>Performing LDAP Operations</title>
|
|
<indexterm>
|
|
<primary>C SDK</primary>
|
|
<secondary>functions</secondary>
|
|
<tertiary>for LDAP operations</tertiary>
|
|
</indexterm>
|
|
<para>The functions listed in <olink targetptr="ldapops-functions">Table 21–4
|
|
</olink> perform LDAP operations on a server and retrieve the results.</para>
|
|
<table frame="topbot" id="ldapops-functions"><title>Functions to Perform Operations
|
|
on LDAP Server</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Function</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><olink targetptr="bdaqa">ldap_add_ext</olink> or <olink targetptr="bdaqb">ldap_add_ext_s
|
|
</olink></para></entry>
|
|
<entry>
|
|
<para>Adds a new entry to the directory.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdatn">ldap_modify_ext</olink> or <olink targetptr="bdato">ldap_modify_ext_s</olink></para></entry>
|
|
<entry>
|
|
<para>Modifies an entry in the directory</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdari">ldap_delete_ext</olink> or <olink targetptr="bdarj">ldap_delete_ext_s</olink></para></entry>
|
|
<entry>
|
|
<para>Deletes an entry from the directory.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdaus">ldap_rename</olink> or<olink targetptr="bdaut">ldap_rename_s
|
|
</olink></para></entry>
|
|
<entry>
|
|
<para>Renames or moves one or more entries.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdauz">ldap_search_ext</olink> or <olink targetptr="bdava">ldap_search_ext_s</olink></para></entry>
|
|
<entry>
|
|
<para>Searches the directory.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdaqp">ldap_compare_ext</olink> or <olink targetptr="bdaqq">ldap_compare_ext_s</olink></para></entry>
|
|
<entry>
|
|
<para>Compares a value with the values of an entry's attribute.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdauu">ldap_result</olink></para></entry>
|
|
<entry>
|
|
<para>Checks the results of an asynchronous operation.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdapy">ldap_abandon_ext</olink></para></entry>
|
|
<entry>
|
|
<para>Cancels an asynchronous operation.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdaru">ldap_extended_operation</olink> or <olink targetptr="bdarv">ldap_extended_operation_s</olink></para></entry>
|
|
<entry>
|
|
<para>Performs an LDAP v3 extended operation.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdaul">ldap_parse_extended_result</olink></para></entry>
|
|
<entry>
|
|
<para>Parses the results of an LDAP v3 extended operation.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdatv">ldap_msgfree</olink></para></entry>
|
|
<entry>
|
|
<para>Frees the memory used by the data structure for the results.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdavi">ldap_simple_bind</olink> or <olink targetptr="bdavj">ldap_simple_bind_s</olink></para></entry>
|
|
<entry>
|
|
<para>Authenticates to an LDAP server using a password.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdauw">ldap_sasl_bind</olink> and <olink targetptr="bdauo">ldap_parse_sasl_bind_result</olink> or <olink targetptr="bdaux">
|
|
ldap_sasl_bind_s</olink></para></entry>
|
|
<entry>
|
|
<para>Authenticates to an LDAP server using a SASL mechanism.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdavh">ldap_set_rebind_proc</olink></para></entry>
|
|
<entry>
|
|
<para>Specifies the function used to get authentication information when following
|
|
referrals.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect2>
|
|
<sect2 id="bdank"><title>Processing Search Results</title>
|
|
<indexterm>
|
|
<primary>C SDK</primary>
|
|
<secondary>functions</secondary>
|
|
<tertiary>for search results processing</tertiary>
|
|
</indexterm>
|
|
<para>Search results are given as a chain of <olink targetptr="bdaly">LDAPMessage
|
|
</olink> structures which can contain both entry messages and search reference
|
|
messages. The functions listed in <olink targetptr="search-functions">Table
|
|
21–5</olink> retrieve the results of a search operation and process
|
|
the data structures which are returned.</para>
|
|
<table frame="topbot" id="search-functions"><title>Functions to Process Search
|
|
Results</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Function</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><olink targetptr="bdarz">ldap_first_message</olink></para></entry>
|
|
<entry>
|
|
<para>Gets the first message (an entry or search reference) in a chain of
|
|
search results.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdaud">ldap_next_message</olink></para></entry>
|
|
<entry>
|
|
<para>Gets the next message (an entry or search reference) in a chain of search
|
|
results.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdaqv">ldap_count_messages</olink></para></entry>
|
|
<entry>
|
|
<para>Counts the number of messages (entries and search references) in a chain
|
|
of search results.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdatw">ldap_msgid</olink></para></entry>
|
|
<entry>
|
|
<para>Gets the ID number of a message structure containing part of a result.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdatx">ldap_msgtype</olink></para></entry>
|
|
<entry>
|
|
<para>Determines whether a message structure contains an entry or a search
|
|
reference.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdatv">ldap_msgfree</olink></para></entry>
|
|
<entry>
|
|
<para>Frees the memory allocated for search results or other LDAP operation
|
|
results.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdary">ldap_first_entry</olink></para></entry>
|
|
<entry>
|
|
<para>Gets the first entry in a chain of search results.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdauc">ldap_next_entry</olink></para></entry>
|
|
<entry>
|
|
<para>Gets the next entry in a chain of search results.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdaqu">ldap_count_entries</olink></para></entry>
|
|
<entry>
|
|
<para>Counts the number of entries in a chain of search results.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdasa">ldap_first_reference</olink></para></entry>
|
|
<entry>
|
|
<para>Gets the first search reference in a chain of search results.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdaue">ldap_next_reference</olink></para></entry>
|
|
<entry>
|
|
<para>Gets the next search reference in a chain of search results.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdaqw">ldap_count_references</olink></para></entry>
|
|
<entry>
|
|
<para>Counts the number of search references in a chain of search results.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdaum">ldap_parse_reference</olink></para></entry>
|
|
<entry>
|
|
<para>Extracts the referral strings from a search reference.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect2>
|
|
<sect2 id="bdanl"><title>Reading the Contents of an Entry</title>
|
|
<indexterm>
|
|
<primary>C SDK</primary>
|
|
<secondary>functions</secondary>
|
|
<tertiary>for reading entry contents</tertiary>
|
|
</indexterm>
|
|
<para>The functions listed in <olink targetptr="entry-functions">Table 21–6
|
|
</olink> are used to access the contents of an entry returned as a search
|
|
result.</para>
|
|
<table frame="topbot" id="entry-functions"><title>Functions to Access Contents
|
|
of an Entry</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Function</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><olink targetptr="bdask">ldap_get_dn</olink></para></entry>
|
|
<entry>
|
|
<para>Get the DN for an entry.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdarr">ldap_explode_dn</olink> <olink targetptr="bdart">ldap_explode_rdn
|
|
</olink></para></entry>
|
|
<entry>
|
|
<para>Split a DN or relative DN into its components.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdars">ldap_explode_dns</olink></para></entry>
|
|
<entry>
|
|
<para>Takes a DNS-style DN and breaks it up into its components.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdatc">ldap_is_dns_dn</olink></para></entry>
|
|
<entry>
|
|
<para>Determines the style of the DN.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdarl">ldap_dn2ufn</olink></para></entry>
|
|
<entry>
|
|
<para>Removes cryptic type names to make a DN easier to read.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdarw">ldap_first_attribute</olink></para></entry>
|
|
<entry>
|
|
<para>Get the name of the first attribute in an entry.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdaua">ldap_next_attribute</olink></para></entry>
|
|
<entry>
|
|
<para>Get the name of the next attribute in an entry.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdast">ldap_get_values</olink></para></entry>
|
|
<entry>
|
|
<para>Get the string values of an attribute.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdasu">ldap_get_values_len</olink></para></entry>
|
|
<entry>
|
|
<para>Get the binary values of an attribute.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdaqx">ldap_count_values</olink></para></entry>
|
|
<entry>
|
|
<para>Count the string values of an attribute.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdaqy">ldap_count_values_len</olink></para></entry>
|
|
<entry>
|
|
<para>Count the binary values of an attribute.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdaxc">ldap_value_free</olink></para></entry>
|
|
<entry>
|
|
<para>Free the memory allocated for the string values of an attribute.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdaxd">ldap_value_free_len</olink></para></entry>
|
|
<entry>
|
|
<para>Free the memory allocated for the binary values of an attribute.</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect2>
|
|
<sect2 id="bdanm"><title>Sorting Search Results</title>
|
|
<indexterm>
|
|
<primary>C SDK</primary>
|
|
<secondary>functions</secondary>
|
|
<tertiary>for sorting search results</tertiary>
|
|
</indexterm>
|
|
<para>With the functions listed in <olink targetptr="client-sort-functions">Table
|
|
21–7</olink>, your LDAP client can sort the data structures returned
|
|
as search results.</para>
|
|
<table frame="topbot" id="client-sort-functions"><title>Client-side Sorting
|
|
Functions</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Function</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><olink targetptr="bdavk">ldap_sort_entries</olink></para></entry>
|
|
<entry>
|
|
<para>Sorts search results by DN or by a single attribute.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdaty">ldap_multisort_entries</olink></para></entry>
|
|
<entry>
|
|
<para>Sorts search results by multiple attributes</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdate">ldap_keysort_entries</olink></para></entry>
|
|
<entry>
|
|
<para>Sorts search results using key(s).</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdavm">ldap_sort_values</olink></para></entry>
|
|
<entry>
|
|
<para>Sorts the values of an attribute.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdavl">ldap_sort_strcasecmp</olink></para></entry>
|
|
<entry>
|
|
<para>A case-insensitive comparison function that you can pass to <olink targetptr="bdavm">ldap_sort_values</olink>.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
<para>&cnDirectoryServer; and others also provide server-side sorting through
|
|
LDAP v3 controls.</para>
|
|
<table frame="topbot" id="server-sort-functions"><title>Server-Side Sorting
|
|
Functions</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Function</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><olink targetptr="bdarf">ldap_create_sort_keylist</olink></para></entry>
|
|
<entry>
|
|
<para>Define the criteria for sorting entries by attribute values.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdasg">ldap_free_sort_keylist</olink></para></entry>
|
|
<entry>
|
|
<para>Free the memory for the sort criteria data structure.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdare">ldap_create_sort_control</olink></para></entry>
|
|
<entry>
|
|
<para>Create the sort control structure needed for server-side sorting.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdaqs">ldap_control_free</olink></para></entry>
|
|
<entry>
|
|
<para>Free the memory for the sort control data structure.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdaup">ldap_parse_sort_control</olink></para></entry>
|
|
<entry>
|
|
<para>Analyze the server’s response to the sort control.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdaqt">ldap_controls_free</olink></para></entry>
|
|
<entry>
|
|
<para>Free the memory for the sort control response data structure.</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect2>
|
|
<sect2 id="bdann"><title>Working with Search Filters</title>
|
|
<indexterm>
|
|
<primary>C SDK</primary>
|
|
<secondary>functions</secondary>
|
|
<tertiary>for search filters</tertiary>
|
|
</indexterm>
|
|
<para>The functions listed in <olink targetptr="filter-functions">Table 21–9
|
|
</olink> retrieve and build filters using a filter configuration file. Use
|
|
this mechanism to create complex filters to pass to the search functions.</para>
|
|
<table frame="topbot" id="filter-functions"><title>Functions to Initialize,
|
|
Retrieve, and Build Filters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Function</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><olink targetptr="bdasw">ldap_init_getfilter</olink></para></entry>
|
|
<entry>
|
|
<para>Read a filter configuration file into memory.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdasx">ldap_init_getfilter_buf</olink></para></entry>
|
|
<entry>
|
|
<para>Read a filter configuration string from a buffer.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdasm">ldap_getfilter_free</olink></para></entry>
|
|
<entry>
|
|
<para>Free the filter configuration data structure from memory.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdavd">ldap_set_filter_additions</olink></para></entry>
|
|
<entry>
|
|
<para>Specify the prefix and suffix to be added to all filters retrieved from
|
|
the filter configuration.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdasn">ldap_getfirstfilter</olink></para></entry>
|
|
<entry>
|
|
<para>Retrieve the first matching filter from the filter configuration.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdasr">ldap_getnextfilter</olink></para></entry>
|
|
<entry>
|
|
<para>Retrieve the next matching filter from the filter configuration.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdaqz">ldap_create_filter</olink></para></entry>
|
|
<entry>
|
|
<para>Build a filter without using the filter configuration file mechanism.</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect2>
|
|
<sect2 id="bdano"><title>Using LDAP v3 Controls</title>
|
|
<indexterm>
|
|
<primary>C SDK</primary>
|
|
<secondary>functions</secondary>
|
|
<tertiary>for LDAP v3 controls</tertiary>
|
|
</indexterm>
|
|
<para>&cnDirectoryServer; and others also provide additional functionality
|
|
through LDAP v3 controls. The functions listed in <olink targetptr="controls-functions">Table 21–10</olink> configure LDAP v3
|
|
control structures which ask the server to perform advanced operations.</para>
|
|
<table frame="topbot" id="controls-functions"><title>Functions to Manage LDAP
|
|
v3 Controls</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Function</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><olink targetptr="ldap-create-authzid-control">ldap_create_authzid_control</olink>, <olink targetptr="ldap-parse-authzid-control">ldap_parse_authzid_control</olink></para>
|
|
</entry>
|
|
<entry>
|
|
<para>Examine the authorization ID used for the operation.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdara">ldap_create_persistentsearch_control</olink>, <olink targetptr="bdasl">ldap_get_entry_controls</olink>, <olink targetptr="bdauk">ldap_parse_entrychange_control
|
|
</olink></para></entry>
|
|
<entry>
|
|
<para>Track changes to an entry or a set of entries by setting the persistent
|
|
search control and analyzing the entry change control sent by the server.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdarc">ldap_create_proxiedauth_control</olink></para>
|
|
</entry>
|
|
<entry>
|
|
<para>Define a proxy authorization control to perform an operation under a
|
|
different bind DN</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="ldap-create-pwdpolicy-control">ldap_create_pwdpolicy_control
|
|
</olink>, <olink targetptr="ldap-parse-pwdpolicy-control">ldap_parse_pwdpolicy_control
|
|
</olink></para></entry>
|
|
<entry>
|
|
<para>Examine password policy information for an entry.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdarf">ldap_create_sort_keylist</olink>, <olink targetptr="bdasg">ldap_free_sort_keylist</olink>, <olink targetptr="bdare">ldap_create_sort_control
|
|
</olink>, <olink targetptr="bdaup">ldap_parse_sort_control</olink></para>
|
|
</entry>
|
|
<entry>
|
|
<para>Define and send criteria for server-side sorting of search results and
|
|
check the server’s response</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="ldap-create-userstatus-control">ldap_create_userstatus_control
|
|
</olink>, <olink targetptr="ldap-parse-userstatus-control">ldap_parse_userstatus_control
|
|
</olink></para></entry>
|
|
<entry>
|
|
<para>Examine account availability information for an entry.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdarg">ldap_create_virtuallist_control</olink>, <olink targetptr="bdauq">ldap_parse_virtuallist_control</olink></para></entry>
|
|
<entry>
|
|
<para>Use in conjunction with server-side sorting to limit and handle the
|
|
number of results returned to the client.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdaun">ldap_parse_result</olink></para></entry>
|
|
<entry>
|
|
<para>Parse an LDAP response from the server to extract the result and the
|
|
response to the control.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect2>
|
|
<sect2 id="bdanp"><title>Using Extensions</title>
|
|
<indexterm>
|
|
<primary>C SDK</primary>
|
|
<secondary>functions</secondary>
|
|
<tertiary>for parsing host lists</tertiary>
|
|
</indexterm>
|
|
<para>The functions listed in <olink targetptr="proprietary-extensions">Table
|
|
21–11</olink> are utility functions for parsing space-separated host
|
|
lists. This is useful for implementing an extended I/O CONNECT callback function.
|
|
</para>
|
|
<table frame="topbot" id="proprietary-extensions"><title>Extensions Provided</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Function</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><olink targetptr="bdaxh">ldap_x_hostlist_first</olink>, <olink targetptr="bdaxi">ldap_x_hostlist_next</olink>, <olink targetptr="bdaxj">ldap_x_hostlist_status
|
|
</olink></para></entry>
|
|
<entry>
|
|
<para>Utility functions for parsing space-separated host lists.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect2>
|
|
<sect2 id="bdanq"><title>Working with LDAP URLs</title>
|
|
<indexterm>
|
|
<primary>C SDK</primary>
|
|
<secondary>functions</secondary>
|
|
<tertiary>for LDAP URLs</tertiary>
|
|
</indexterm>
|
|
<para>The functions listed in <olink targetptr="ldapurl-functions">Table 21–12
|
|
</olink> interpret LDAP URLs, universal resource locators of the form <literal>ldap://...
|
|
</literal>.</para>
|
|
<table frame="topbot" id="ldapurl-functions"><title>Functions to Interpret
|
|
LDAP URLs</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Function</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><olink targetptr="bdatd">ldap_is_ldap_url</olink></para></entry>
|
|
<entry>
|
|
<para>Determine if a URL is an LDAP URL.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdawk">ldap_url_parse</olink></para></entry>
|
|
<entry>
|
|
<para>Split up an LDAP URL into its components.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdawm">ldap_url_search</olink>, <olink targetptr="bdawn">
|
|
ldap_url_search_s</olink>, <olink targetptr="bdawo">ldap_url_search_st</olink></para>
|
|
</entry>
|
|
<entry>
|
|
<para>Perform the search specified by an LDAP URL.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdasi">ldap_free_urldesc</olink></para></entry>
|
|
<entry>
|
|
<para>Free the memory allocated for a parsed URL.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect2>
|
|
<sect2 id="bdanr"><title>Working with UTF-8 Encoding</title>
|
|
<indexterm>
|
|
<primary>C SDK</primary>
|
|
<secondary>functions</secondary>
|
|
<tertiary>for UTF-8 encoding</tertiary>
|
|
</indexterm>
|
|
<para>The functions listed in <olink targetptr="utf8-functions">Table 21–13
|
|
</olink> work with strings and characters that use UTF-8 encoding.</para>
|
|
<table frame="topbot" id="utf8-functions"><title>Functions to Handle UTF-8
|
|
Encoding</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Function</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><olink targetptr="bdaww">ldap_utf8len</olink></para></entry>
|
|
<entry>
|
|
<para>Function to determine byte length.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdawx">ldap_utf8next</olink></para></entry>
|
|
<entry>
|
|
<para>Function to get next character.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdawy">ldap_utf8prev</olink></para></entry>
|
|
<entry>
|
|
<para>Function to get previous character.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdawq">ldap_utf8copy</olink></para></entry>
|
|
<entry>
|
|
<para>Function to copy a character to a destination.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdawp">ldap_utf8characters</olink></para></entry>
|
|
<entry>
|
|
<para>Function to return the number of characters.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdawr">ldap_utf8getcc</olink></para></entry>
|
|
<entry>
|
|
<para>Function moves the pointer to the next character following a UCS-4 character.
|
|
</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdawz">ldap_utf8strtok_r</olink></para></entry>
|
|
<entry>
|
|
<para>Function moves the pointer to the next character following a UCS-4 character.
|
|
</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdaws">ldap_utf8isalnum</olink>, <olink targetptr="bdawt">
|
|
ldap_utf8isalpha</olink>, <olink targetptr="bdawu">ldap_utf8isdigit</olink>, <olink targetptr="bdaww">ldap_utf8len</olink>, <olink targetptr="bdawv">ldap_utf8isspace
|
|
</olink></para></entry>
|
|
<entry>
|
|
<para>Functions to determine characteristics of the character.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect2>
|
|
<sect2 id="bdans"><title>Handling Errors</title>
|
|
<indexterm>
|
|
<primary>C SDK</primary>
|
|
<secondary>functions</secondary>
|
|
<tertiary>for error handling</tertiary>
|
|
</indexterm>
|
|
<para>The functions listed in <olink targetptr="error-functions">Table 21–14
|
|
</olink> handle errors returned by the functions. <olink targetptr="bdaxx">Chapter 22,
|
|
Directory SDK for C Result Codes</olink> lists all of the error and status
|
|
codes used in the &DirectorySDKForC;. You can also find details about possible
|
|
errors in the reference section for each function.</para>
|
|
<table frame="topbot" id="error-functions"><title>Functions for Error Handling</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Function</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><olink targetptr="bdaun">ldap_parse_result</olink></para></entry>
|
|
<entry>
|
|
<para>Get the error code resulting from an asynchronous LDAP operation.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdasq">ldap_get_lderrno</olink></para></entry>
|
|
<entry>
|
|
<para>Get information about the last error that occurred.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdavf">ldap_set_lderrno</olink></para></entry>
|
|
<entry>
|
|
<para>Set information about an error.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdarq">ldap_err2string</olink></para></entry>
|
|
<entry>
|
|
<para>Get the error message for a specific error code.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdavr">ldapssl_err2string</olink></para></entry>
|
|
<entry>
|
|
<para>Get the error message for a specific SSL error code.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect2>
|
|
<sect2 id="bdant"><title>Managing Memory</title>
|
|
<indexterm>
|
|
<primary>C SDK</primary>
|
|
<secondary>functions</secondary>
|
|
<tertiary>for memory management</tertiary>
|
|
</indexterm>
|
|
<para>The functions listed in <olink targetptr="free-functions">Table 21–15
|
|
</olink> free memory allocated by the &DirectorySDKForC; functions.</para>
|
|
<table frame="topbot" id="free-functions"><title>Functions to Free Memory</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Function</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><olink targetptr="bdaoc">ber_bvfree</olink></para></entry>
|
|
<entry>
|
|
<para>Free the memory allocated for a <olink targetptr="bdakg">berval</olink> structure.
|
|
</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdaog">ber_free</olink></para></entry>
|
|
<entry>
|
|
<para>Free the memory of a <olink targetptr="bdakh">BerElement</olink> structure.
|
|
</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdaqs">ldap_control_free</olink></para></entry>
|
|
<entry>
|
|
<para>Free the memory of an <olink targetptr="bdala">LDAPControl</olink> structure.
|
|
</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdaqt">ldap_controls_free</olink></para></entry>
|
|
<entry>
|
|
<para>Free an array of <olink targetptr="bdala">LDAPControl</olink> structures.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdase">ldap_free_friendlymap</olink></para></entry>
|
|
<entry>
|
|
<para>Free the memory of a <olink targetptr="bdaki">FriendlyMap</olink> structure
|
|
</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdasg">ldap_free_sort_keylist</olink></para></entry>
|
|
<entry>
|
|
<para>Free an array of <olink targetptr="bdamc">LDAPsortkey</olink> structures</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdasi">ldap_free_urldesc</olink></para></entry>
|
|
<entry>
|
|
<para>Free the memory of an <olink targetptr="bdams">LDAPURLDesc</olink> structure
|
|
</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdasm">ldap_getfilter_free</olink></para></entry>
|
|
<entry>
|
|
<para>Free the memory of an <olink targetptr="bdalf">LDAPFiltDesc</olink> structure.
|
|
</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdatl">ldap_memfree</olink></para></entry>
|
|
<entry>
|
|
<para>General function for freeing memory of any other data structure</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdatu">ldap_mods_free</olink></para></entry>
|
|
<entry>
|
|
<para>Free an array of <olink targetptr="bdalz">LDAPMod</olink> structure.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdatv">ldap_msgfree</olink></para></entry>
|
|
<entry>
|
|
<para>Free the memory of an <olink targetptr="bdaly">LDAPMessage</olink> structure.
|
|
</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdaxc">ldap_value_free</olink></para></entry>
|
|
<entry>
|
|
<para>Free the memory allocated for the string values of an attribute.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdaxd">ldap_value_free_len</olink></para></entry>
|
|
<entry>
|
|
<para>Free the memory allocated for the binary values of an attribute (an
|
|
array of <olink targetptr="bdakg">berval</olink> structures)</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
<para>You may also manage memory directly with the functions in <olink targetptr="mem-mngt-functions">Table 21–16</olink>.</para>
|
|
<table frame="topbot" id="mem-mngt-functions"><title>Functions to Directly
|
|
Manage Memory</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Function</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><olink targetptr="bdaxl">ldap_x_malloc</olink></para></entry>
|
|
<entry>
|
|
<para>Allocates memory.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdaxf">ldap_x_calloc</olink></para></entry>
|
|
<entry>
|
|
<para>Allocates memory for an array of elements.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdaxm">ldap_x_realloc</olink></para></entry>
|
|
<entry>
|
|
<para>Changes the size of a memory block.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdaxg">ldap_x_free</olink></para></entry>
|
|
<entry>
|
|
<para>Frees a block of memory.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect2>
|
|
<sect2 id="bdanu"><title>Working with <acronym>NSPR</acronym></title>
|
|
<indexterm>
|
|
<primary>C SDK</primary>
|
|
<secondary>functions</secondary>
|
|
<tertiary>for NSPR</tertiary>
|
|
</indexterm>
|
|
<para>The functions listed in <olink targetptr="nspr-functions">Table 21–17
|
|
</olink> tie <literal>libldap</literal> into Netscape Portable Runtime, <acronym>
|
|
NSPR</acronym>.</para>
|
|
<table frame="topbot" id="nspr-functions"><title>Functions to Work with <acronym>
|
|
NSPR</acronym></title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Function</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><olink targetptr="bdaxn">prldap_get_default_socket_info</olink></para>
|
|
</entry>
|
|
<entry>
|
|
<para>Gets default socket information.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdaxo">prldap_get_session_info</olink></para></entry>
|
|
<entry>
|
|
<para>Gets application-specific data.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdaxp">prldap_get_session_option</olink></para></entry>
|
|
<entry>
|
|
<para>Gets a session option specific to the <literal>prldap</literal> layer.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdaxq">prldap_get_socket_info</olink></para></entry>
|
|
<entry>
|
|
<para>Gets socket information.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdaxr">prldap_init</olink></para></entry>
|
|
<entry>
|
|
<para>Creates a new <acronym>NSPR</acronym> session handle.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdaxs">prldap_install_routines</olink></para></entry>
|
|
<entry>
|
|
<para>Installs <acronym>NSPR</acronym> functions for use with LDAP handle.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdaxt">prldap_set_default_socket_info</olink></para>
|
|
</entry>
|
|
<entry>
|
|
<para>Sets default socket information.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdaxu">prldap_set_session_info</olink></para></entry>
|
|
<entry>
|
|
<para>Sets application-specific data.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdaxv">prldap_set_session_option</olink></para></entry>
|
|
<entry>
|
|
<para>Sets a session option specific to the <literal>prldap</literal> layer.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdaxw">prldap_set_socket_info</olink></para></entry>
|
|
<entry>
|
|
<para>Sets socket information.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect2>
|
|
<sect2 id="bdanv"><title>Deprecated and Outdated Functions</title>
|
|
<indexterm>
|
|
<primary>C SDK</primary>
|
|
<secondary>functions</secondary>
|
|
<tertiary>deprecated</tertiary>
|
|
</indexterm>
|
|
<para>The functions listed in first column of <olink targetptr="deprecated-functions">Table 21–18</olink> should no longer
|
|
be used; they have been superseded by the newer functions listed in the second
|
|
column. Deprecated functions are those being dropped from the standard or
|
|
from extensions to &DirectorySDKForC;. Outdated functions are those which
|
|
are not officially deprecated but which have newer, extended functions for
|
|
performing the same operation.</para>
|
|
<note><para>Deprecated functions are not guaranteed to be implemented in future
|
|
versions of the API. However, all of these functions are still implemented
|
|
in this version for backwards compatibility. For maintenance reasons, they
|
|
have often been implemented to call the newer function which performs the
|
|
same task.</para></note>
|
|
<table frame="topbot" id="deprecated-functions"><title>Deprecated Functions
|
|
and Their Replacements</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Deprecated Function</para></entry>
|
|
<entry>
|
|
<para>Replacement</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><olink targetptr="bdaqd">ldap_ber_free</olink></para></entry>
|
|
<entry>
|
|
<para>Replaced by <olink targetptr="bdaog">ber_free</olink>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdaqe">ldap_bind</olink>, <olink targetptr="bdaqf">ldap_bind_s
|
|
</olink></para></entry>
|
|
<entry>
|
|
<para>Replaced by <olink targetptr="bdavi">ldap_simple_bind</olink> and <olink targetptr="bdavj">ldap_simple_bind_s</olink> respectively.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdaqg">ldap_build_filter</olink></para></entry>
|
|
<entry>
|
|
<para>Replaced by <olink targetptr="bdaqz">ldap_create_filter</olink>.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdaqh">ldap_cache_flush</olink></para></entry>
|
|
<entry>
|
|
<para>Replaced by <function>ldap_memcache_*</function> functions.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdaqi">ldap_charray_add</olink>, <olink targetptr="bdaqj">
|
|
ldap_charray_dup</olink>, <olink targetptr="bdaqk">ldap_charray_free</olink>, <olink targetptr="bdaql">ldap_charray_inlist</olink>, <olink targetptr="bdaqm">ldap_charray_merge
|
|
</olink>, <olink targetptr="bdaqn">ldap_charray_position</olink>, <olink targetptr="bdavy">ldap_str2charray</olink></para></entry>
|
|
<entry>
|
|
<para>None documented to replace these character array functions.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdard">ldap_create_proxyauth_control</olink></para>
|
|
</entry>
|
|
<entry>
|
|
<para>Replaced by <olink targetptr="bdarb">ldap_create_geteffectiveRights_control
|
|
</olink>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdaso">ldap_get_lang_values</olink>, <olink targetptr="bdasp">ldap_get_lang_values_len</olink></para></entry>
|
|
<entry>
|
|
<para>Rarely used, no replacement.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdatq">ldap_modrdn</olink></para></entry>
|
|
<entry>
|
|
<para>Replaced by <olink targetptr="bdats">ldap_modrdn2</olink>, itself outdated
|
|
by <olink targetptr="bdaus">ldap_rename</olink>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdatr">ldap_modrdn_s</olink></para></entry>
|
|
<entry>
|
|
<para>Replaced by <olink targetptr="bdatt">ldap_modrdn2_s</olink>, itself
|
|
outdated by <olink targetptr="bdaut">ldap_rename_s</olink>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdauj">ldap_open</olink></para></entry>
|
|
<entry>
|
|
<para>Replaced by <olink targetptr="bdasv">ldap_init</olink> and one of the
|
|
bind functions.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdauv">ldap_result2error</olink></para></entry>
|
|
<entry>
|
|
<para>Replaced by <olink targetptr="bdaun">ldap_parse_result</olink>.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdave">ldap_setfilteraffixes</olink></para></entry>
|
|
<entry>
|
|
<para>Replaced by <olink targetptr="bdavd">ldap_set_filter_additions</olink>.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdawb">ldap_ufn_search_c</olink>, <olink targetptr="bdawc">ldap_ufn_search_ct</olink>, <olink targetptr="bdawd">ldap_ufn_search_s
|
|
</olink>, <olink targetptr="bdawe">ldap_ufn_setfilter</olink>, <olink targetptr="bdawf">ldap_ufn_setprefix</olink>, <olink targetptr="bdawg">ldap_ufn_timeout
|
|
</olink></para></entry>
|
|
<entry>
|
|
<para>None documented to replace these user-friendly search functions.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdaxe">ldap_version</olink></para></entry>
|
|
<entry>
|
|
<para>Replaced by <olink targetptr="bdass">ldap_get_option</olink>.</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect2>
|
|
<sect2 id="bdanw"><title>Outdated Standard Functions and Equivalents</title>
|
|
<indexterm>
|
|
<primary>C SDK</primary>
|
|
<secondary>functions</secondary>
|
|
<tertiary>outdated</tertiary>
|
|
</indexterm>
|
|
<para>Many LDAP v2 functions are outdated now that LDAP v3 has been widely
|
|
adopted. <olink targetptr="outdated-functions">Table 21–19</olink> lists
|
|
both the outdated function and its new equivalent. Although LDAP v2 functions
|
|
remain in the standard specification, you should use the LDAP v3 functions
|
|
in any new client applications. Again, for maintenance reasons, the outdated
|
|
functions have often been implemented to call the newer function.</para>
|
|
<table frame="topbot" id="outdated-functions"><title>Outdated LDAP v2 Functions
|
|
and New Equivalents</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>LDAP v2 Functions</para></entry>
|
|
<entry>
|
|
<para>LDAP v3 Equivalent</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><olink targetptr="bdapx">ldap_abandon</olink></para></entry>
|
|
<entry>
|
|
<para><olink targetptr="bdapy">ldap_abandon_ext</olink></para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdapz">ldap_add</olink>, <olink targetptr="bdaqc">ldap_add_s
|
|
</olink></para></entry>
|
|
<entry>
|
|
<para><olink targetptr="bdaqa">ldap_add_ext</olink>, <olink targetptr="bdaqb">ldap_add_ext_s
|
|
</olink></para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdaqo">ldap_compare</olink>, <olink targetptr="bdaqr">ldap_compare_s
|
|
</olink></para></entry>
|
|
<entry>
|
|
<para><olink targetptr="bdaqp">ldap_compare_ext</olink>, <olink targetptr="bdaqq">
|
|
ldap_compare_ext_s</olink></para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdarh">ldap_delete</olink>, <olink targetptr="bdark">ldap_delete_s
|
|
</olink></para></entry>
|
|
<entry>
|
|
<para><olink targetptr="bdari">ldap_delete_ext</olink>, <olink targetptr="bdarj">
|
|
ldap_delete_ext_s</olink></para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdatm">ldap_modify</olink>, <olink targetptr="bdatp">ldap_modify_s
|
|
</olink></para></entry>
|
|
<entry>
|
|
<para><olink targetptr="bdatn">ldap_modify_ext</olink>, <olink targetptr="bdato">
|
|
ldap_modify_ext_s</olink></para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdats">ldap_modrdn2</olink>, <olink targetptr="bdatt">ldap_modrdn2_s
|
|
</olink></para></entry>
|
|
<entry>
|
|
<para><olink targetptr="bdaus">ldap_rename</olink>, <olink targetptr="bdaut">ldap_rename_s
|
|
</olink></para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdauy">ldap_search</olink>, <olink targetptr="bdavb">ldap_search_s
|
|
</olink>, <olink targetptr="bdavc">ldap_search_st</olink></para></entry>
|
|
<entry>
|
|
<para><olink targetptr="bdauz">ldap_search_ext</olink>, <olink targetptr="bdava">
|
|
ldap_search_ext_s</olink>, <olink targetptr="bdava">ldap_search_ext_s</olink> -
|
|
use <parameter>timeout</parameter> argument</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><olink targetptr="bdawh">ldap_unbind</olink>, <olink targetptr="bdawi">ldap_unbind_s
|
|
</olink></para></entry>
|
|
<entry>
|
|
<para><olink targetptr="bdawj">ldap_unbind_ext</olink> replaces both forms
|
|
which are identical besides the suffix.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect2>
|
|
</sect1>
|
|
<sect1 id="bdanx"><title>Functions Alphabetically</title>
|
|
<indexterm>
|
|
<primary>C SDK</primary>
|
|
<secondary>functions</secondary>
|
|
<tertiary>alphabetically</tertiary>
|
|
</indexterm><indexterm>
|
|
<primary>functions</primary>
|
|
<secondary>C SDK</secondary>
|
|
<seealso>C SDK, functions</seealso></indexterm>
|
|
<sect2 id="bdany"><title><function>ber_alloc</function></title>
|
|
<para>The <function>ber_alloc</function> function is used to allocate a new
|
|
Basic Encoding Rules (BER) <olink targetptr="bdakh">BerElement</olink> structure.
|
|
</para>
|
|
<sect3 id="gaqrr"><title>Syntax</title>
|
|
<programlisting>#include <lber.h>
|
|
BerElement* ber_alloc( void );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gaqqn"><title>Parameters</title>
|
|
<para>This function has no parameters.</para></sect3>
|
|
<sect3 id="gaqri"><title>Returns</title>
|
|
<itemizedlist>
|
|
<listitem><para>If successful, a pointer to the newly allocated <olink targetptr="bdakh">BerElement</olink> structure.</para></listitem>
|
|
<listitem><para>If unsuccessful, a <literal>NULL</literal> pointer.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="gaqrc"><title>Description</title>
|
|
<para><function>ber_alloc</function> is used to allocate a new <olink targetptr="bdakh">BerElement</olink> structure for encoding data with the
|
|
BER.</para></sect3>
|
|
<sect3 id="gaqrf"><title>See Also</title>
|
|
<para><olink targetptr="bdaov">ber_printf</olink>, <olink targetptr="bdakh">BerElement
|
|
</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdanz"><title><function>ber_alloc_t</function></title>
|
|
<para>The <function>ber_alloc_t</function> function constructs and returns
|
|
a <olink targetptr="bdakh">BerElement</olink> structure.</para>
|
|
<sect3 id="gaqqz"><title>Syntax</title>
|
|
<programlisting>#include <lber.h>
|
|
BerElement* ber_alloc_t( int options );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gaqrx"><title>Parameters</title>
|
|
<table frame="topbot" id="gaqqy"><title><function>ber_alloc_t</function> Function
|
|
Parameter</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>options</literal></para></entry>
|
|
<entry>
|
|
<para>Contains bitwise OR of options to be used when generating the encoding
|
|
of the <olink targetptr="bdakh">BerElement</olink>. One option is defined
|
|
and must always be supplied:</para>
|
|
<para><literal>#define LBER_USE_DER 0x01</literal></para>
|
|
<para>When this option is present, lengths will always be encoded in the minimum
|
|
number of octets. This option does not cause values of sets and sequences
|
|
to be rearranged in tag and byte order, so these functions are not suitable
|
|
for generating DER output as defined in X.509 and X.680.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gaqry"><title>Returns</title>
|
|
<itemizedlist>
|
|
<listitem><para>If successful, a pointer to the newly allocated <olink targetptr="bdakh">BerElement</olink> structure.</para></listitem>
|
|
<listitem><para>If unsuccessful, a <literal>NULL</literal> pointer.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="gaqru"><title>Description</title>
|
|
<para>This function is the same as <olink targetptr="bdany">ber_alloc</olink> except
|
|
it has an option.</para></sect3>
|
|
<sect3 id="gaqrd"><title>See Also</title>
|
|
<para><olink targetptr="bdaov">ber_printf</olink>, <olink targetptr="bdakh">BerElement
|
|
</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaoa"><title><function>ber_bvecfree</function></title>
|
|
<para>The <function>ber_bvecfree</function> function frees an array of <olink targetptr="bdakg">berval</olink> structures.</para>
|
|
<sect3 id="gaqrk"><title>Syntax</title>
|
|
<programlisting>#include <lber.h>
|
|
void ber_bvecfree( struct berval **bv );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gaqqd"><title>Parameters</title>
|
|
<table frame="topbot" id="gaqrt"><title><function>ber_bvecfree</function> Function
|
|
Parameter</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>bv</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to the array that you want to free from memory.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gaqqs"><title>Description</title>
|
|
<para>Each <olink targetptr="bdakg">berval</olink> in the array is freed using <olink targetptr="bdaoc">ber_bvfree</olink>, and then the array itself is freed.</para>
|
|
</sect3>
|
|
<sect3 id="gaqrw"><title>See Also</title>
|
|
<para><olink targetptr="bdaoc">ber_bvfree</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaob"><title><function>ber_bvdup</function></title>
|
|
<para>The <function>ber_bvdup</function> function returns a copy of a <olink targetptr="bdakg">berval</olink> structure.</para>
|
|
<sect3 id="gaqqr"><title>Syntax</title>
|
|
<programlisting>#include <lber.h>
|
|
berval* ber_bvdup( const struct berval *bv );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gaqqa"><title>Parameters</title>
|
|
<table frame="topbot" id="gaqqu"><title><function>ber_bvdup</function> Function
|
|
Parameter</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>bv</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to the <olink targetptr="bdakg">berval</olink> structure to
|
|
be duplicated.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gaqrm"><title>Returns</title>
|
|
<itemizedlist>
|
|
<listitem><para>If successful, a pointer to the newly allocated <olink targetptr="bdakg">berval</olink> structure.</para></listitem>
|
|
<listitem><para>If unsuccessful, a <literal>NULL</literal> pointer.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="gaqrv"><title>Description</title>
|
|
<para>The <function>ber_bvdup</function> function returns a copy of a <olink targetptr="bdakg">berval</olink> structure. The data referenced in the structure
|
|
is also duplicated. The <literal>bv_val</literal> field in the returned <olink targetptr="bdakg">berval</olink> points to a different area of memory than
|
|
the <literal>bv_val</literal> field in the argument <olink targetptr="bdakg">berval
|
|
</olink>.</para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaoc"><title><function>ber_bvfree</function></title>
|
|
<para>The <function>ber_bvfree</function> function frees a <olink targetptr="bdakg">berval</olink> structure.</para>
|
|
<sect3 id="gaqqt"><title>Syntax</title>
|
|
<programlisting>#include <lber.h>
|
|
void ber_bvfree( struct berval *bv );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gaqql"><title>Parameters</title>
|
|
<table frame="topbot" id="gaqrn"><title><function>ber_bvfree</function> Function
|
|
Parameter</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>bv</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to the <olink targetptr="bdakg">berval</olink> structure that
|
|
you want to free from memory.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gaqqo"><title>Description</title>
|
|
<para>The <function>ber_bvfree</function> function frees a <olink targetptr="bdakg">berval</olink> structure from memory. Call this function
|
|
to free a <olink targetptr="bdakg">berval</olink> passed back from the <olink targetptr="bdarv">ldap_extended_operation_s</olink> , <olink targetptr="bdaul">ldap_parse_extended_result
|
|
</olink>, <olink targetptr="bdaux">ldap_sasl_bind_s</olink>, or <olink targetptr="bdauo">ldap_parse_sasl_bind_result</olink> functions.</para></sect3>
|
|
<sect3 id="gaqrg"><title>See Also</title>
|
|
<para><olink targetptr="bdarv">ldap_extended_operation_s</olink>, <olink targetptr="bdaul">ldap_parse_extended_result</olink>, <olink targetptr="bdaux">ldap_sasl_bind_s
|
|
</olink> , <olink targetptr="bdauo">ldap_parse_sasl_bind_result</olink></para>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="bdaod"><title><function>ber_dup</function></title>
|
|
<para>The <function>ber_dup</function> function returns a copy of a <olink targetptr="bdakh">BerElement</olink> structure.</para>
|
|
<sect3 id="gaqqc"><title>Syntax</title>
|
|
<programlisting>#include <lber.h>
|
|
BerElement* ber_dup( BerElement *ber );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gaqrs"><title>Parameters</title>
|
|
<table frame="topbot" id="gaqqw"><title><function>ber_dup</function> Function
|
|
Parameter</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ber</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to the <olink targetptr="bdakh">BerElement</olink> to be duplicated.
|
|
</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gaqqk"><title>Returns</title>
|
|
<itemizedlist>
|
|
<listitem><para>If successful, a pointer to the newly allocated <olink targetptr="bdakh">BerElement</olink> structure.</para></listitem>
|
|
<listitem><para>If unsuccessful, a <literal>NULL</literal> pointer.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="gaqre"><title>Description</title>
|
|
<para>The <function>ber_dup</function> function returns a copy of a <olink targetptr="bdakh">BerElement</olink> structure.</para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaoe"><title><function>ber_first_element</function></title>
|
|
<para>The <function>ber_first_element</function> function is used to return
|
|
the tag and length of the first element in a set or sequence.</para>
|
|
<sect3 id="gaqqv"><title>Syntax</title>
|
|
<programlisting>#include <lber.h>
|
|
unsigned long ber_first_element( BerElement *ber, unsigned long *len,
|
|
char **last );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gaqrh"><title>Parameters</title>
|
|
<table frame="topbot" id="gaqsl"><title><function>ber_first_element</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ber</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to a <olink targetptr="bdakh">BerElement</olink>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>len</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to the address of the unsigned long which returns the length
|
|
of the first element.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>last</literal></para></entry>
|
|
<entry>
|
|
<para>Address of the pointer to return the address of the last byte of the
|
|
element.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gaqtn"><title>Returns</title>
|
|
<para><literal>NULL</literal> pointer is returned on error.</para></sect3>
|
|
<sect3 id="gaqsu"><title>Description</title>
|
|
<para>The <function>ber_first_element</function> function is used to return
|
|
the tag and length of the first element in a set or sequence. It also returns
|
|
a magic cookie parameter that should be passed to subsequent calls to <olink targetptr="bdaot">ber_next_element</olink> .</para></sect3>
|
|
<sect3 id="gaqtm"><title>See Also</title>
|
|
<para><olink targetptr="bdaot">ber_next_element</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaof"><title><function>ber_flatten</function></title>
|
|
<para>The <function>ber_flatten</function> function allocates a <olink targetptr="bdakg">berval</olink> structure whose contents are taken from a
|
|
source <olink targetptr="bdakh">BerElement</olink> structure.</para>
|
|
<sect3 id="gaqtg"><title>Syntax</title>
|
|
<programlisting>#include <lber.h>
|
|
int ber_flatten( BerElement *ber, struct berval **bvPtr );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gaqsi"><title>Parameters</title>
|
|
<table frame="topbot" id="gaqst"><title><function>ber_flatten</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ber</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to the source <olink targetptr="bdakh">BerElement</olink>.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>bvPtr</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to the newly allocated <olink targetptr="bdakg">berval</olink> structure
|
|
which must be freed using <olink targetptr="bdaoc">ber_bvfree</olink>.</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gaqsa"><title>Returns</title>
|
|
<para>Returns <literal>0</literal> on success and <literal>-1</literal> on
|
|
error.</para></sect3>
|
|
<sect3 id="gaqtc"><title>Description</title>
|
|
<para>This function is usually used when encoding LDAP v3 controls or extended
|
|
operations values.</para></sect3>
|
|
<sect3 id="gaqsd"><title>See Also</title>
|
|
<para><olink targetptr="bdaoc">ber_bvfree</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaog"><title><function>ber_free</function></title>
|
|
<para>The <function>ber_free</function> function frees a <olink targetptr="bdakh">BerElement</olink> structure previously allocated with <olink targetptr="bdany">ber_alloc</olink> , <olink targetptr="bdanz">ber_alloc_t</olink>,
|
|
<olink targetptr="bdaor">ber_init</olink>, or the <olink targetptr="bdarw">ldap_first_attribute
|
|
</olink> and <olink targetptr="bdaua">ldap_next_attribute</olink> search
|
|
functions.</para>
|
|
<sect3 id="gaqsq"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
void ber_free( BerElement *ber, int freebuf );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gaqsp"><title>Parameters</title>
|
|
<table frame="topbot" id="gaqtj"><title><function>ber_free</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ber</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to the <olink targetptr="bdakh">BerElement</olink> structure
|
|
that you want to free.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>freebuf</literal></para></entry>
|
|
<entry>
|
|
<para>Specifies whether or not to free the buffer in the <olink targetptr="bdakh">BerElement</olink> structure.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gaqtb"><title>Description</title>
|
|
<para>This function frees a <olink targetptr="bdakh">BerElement</olink> structure,
|
|
which is used to keep track of the current attribute. When you are done working
|
|
with the attributes, you should free this structure from memory, if it still
|
|
exists.</para>
|
|
<note><para>To retrieve attributes from a search result entry, you need to
|
|
call either the <olink targetptr="bdarw">ldap_first_attribute</olink> or <olink targetptr="bdaua">ldap_next_attribute</olink> function. When freeing structures
|
|
allocated by these functions, you should specify <literal>0</literal> for
|
|
the <literal>freebuf</literal> argument. Otherwise, it should always be set
|
|
to <literal>1</literal>.</para></note>
|
|
</sect3>
|
|
<sect3 id="gaqsx"><title>Example</title>
|
|
<para><olink targetptr="ber-free-example">Example 21–1</olink> frees
|
|
the <olink targetptr="bdakh">BerElement</olink> structure allocated by the <olink targetptr="bdarw">ldap_first_attribute</olink> function.</para>
|
|
<example id="ber-free-example"><title>Using <function>ber_free</function></title>
|
|
<programlisting>LDAP *ld;
|
|
LDAPMessage *a, *e;
|
|
BerElement *ber;
|
|
...
|
|
for ( a = ldap_first_attribute( ld, e, &ber ); a != NULL;
|
|
a =ldap_next_attribute( ld, e, ber ) {
|
|
...
|
|
/* Retrieve the value of each attribute */
|
|
...
|
|
}
|
|
|
|
/* Free the BerElement when done */
|
|
if ( ber != NULL ) {
|
|
ber_free( ber, 0 );
|
|
}
|
|
...</programlisting>
|
|
</example>
|
|
</sect3>
|
|
<sect3 id="gaqse"><title>See Also</title>
|
|
<para><olink targetptr="bdany">ber_alloc</olink>, <olink targetptr="bdanz">ber_alloc_t
|
|
</olink> , <olink targetptr="bdaor">ber_init</olink>, <olink targetptr="bdarw">ldap_first_attribute
|
|
</olink>, <olink targetptr="bdaua">ldap_next_attribute</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaoh"><title><function>ber_get_boolean</function></title>
|
|
<para>The <function>ber_get_boolean</function> function is used to read a
|
|
boolean value.</para>
|
|
<sect3 id="gaqsw"><title>Syntax</title>
|
|
<programlisting>#include <lber.h>
|
|
unsigned long ber_get_boolean( BerElement *ber,
|
|
int *boolval );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gaqsy"><title>Parameters</title>
|
|
<table frame="topbot" id="gaqta"><title><function>ber_get_boolean</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ber</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to the <olink targetptr="bdakh">BerElement</olink> structure
|
|
that contains the boolean.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>boolval</literal></para></entry>
|
|
<entry>
|
|
<para>Specifies the boolean to read.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gaqth"><title>Returns</title>
|
|
<para>The value is returned on success and <literal>LBER_ERROR</literal> (<literal>
|
|
-1</literal>) on failure.</para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaoi"><title><function>ber_get_int</function></title>
|
|
<para>The <function>ber_get_int</function> function tries to interpret the
|
|
next element as an integer, returning the result in <literal>num</literal>.</para>
|
|
<sect3 id="gaqtp"><title>Syntax</title>
|
|
<programlisting>#include <lber.h>
|
|
unsigned long ber_get_int( BerElement *ber, int *num );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gaqsr"><title>Parameters</title>
|
|
<table frame="topbot" id="gaqrz"><title><function>ber_get_int</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ber</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to the <olink targetptr="bdakh">BerElement</olink> structure
|
|
that contains the boolean.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>num</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to the result.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gaqsc"><title>Returns</title>
|
|
<para>The tag of whatever it finds is returned on success and <literal>LBER_ERROR
|
|
</literal> (<literal>-1</literal>) on failure.</para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaoj"><title><function>ber_get_next</function></title>
|
|
<para>The <function>ber_get_next</function> function reads the next BER element.</para>
|
|
<sect3 id="gaqso"><title>Syntax</title>
|
|
<programlisting>#include <lber.h>
|
|
unsigned long ber_get_next( Sockbuf *sb, unsigned long *len,
|
|
BerElement *ber );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gaqsg"><title>Parameters</title>
|
|
<table frame="topbot" id="gaqsf"><title><function>ber_get_next</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>sb</literal></para></entry>
|
|
<entry>
|
|
<para>Descriptor (socket or file descriptor) from which to read.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>len</literal></para></entry>
|
|
<entry>
|
|
<para>The length of the entire element.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>ber</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to the <olink targetptr="bdakh">BerElement</olink> structure.</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gaqsk"><title>Description</title>
|
|
<para><function>ber_get_next</function> strips off and returns the leading
|
|
tag, strips off and returns the length of the entire element, and sets up
|
|
a pointer to <literal>ber</literal> for subsequent calls to decode the element.</para>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="bdaok"><title><function>ber_get_next_buffer</function></title>
|
|
<para>The <function>ber_get_next_buffer</function> function reads the next
|
|
BER element from a byte buffer.</para>
|
|
<note><para>This is an older function included in the SDK for backward-compatibility.
|
|
If you are writing a new LDAP client, use <olink targetptr="bdaol">ber_get_next_buffer_ext
|
|
</olink> instead.</para></note>
|
|
<sect3 id="bdaol"><title><function>ber_get_next_buffer_ext</function></title>
|
|
<para>The <function>ber_get_next_buffer_ext</function> function reads the
|
|
next BER element from a byte buffer.</para>
|
|
<note><para><olink targetptr="bdaol">ber_get_next_buffer_ext</olink> is a
|
|
new version of the <olink targetptr="bdaok">ber_get_next_buffer</olink> function.
|
|
If you are writing a new LDAP client, use <olink targetptr="bdaol">ber_get_next_buffer_ext
|
|
</olink> .</para></note>
|
|
</sect3>
|
|
<sect3 id="gaqtf"><title>Syntax</title>
|
|
<programlisting>#include <lber.h>
|
|
unsigned long ber_get_next_buffer_ext( void *buffer,
|
|
size_t buffer_size, unsigned long *len, BerElement *ber,
|
|
unsigned long *Bytes_Scanned, Sockbuf *sb );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gaqto"><title>Parameters</title>
|
|
<table frame="topbot" id="gaqtd"><title><function>ber_get_next_buffer_ext</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>buffer</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to the buffer.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>buffer_size</literal></para></entry>
|
|
<entry>
|
|
<para>The size of the buffer.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>len</literal></para></entry>
|
|
<entry>
|
|
<para>The length of the entire element.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>ber</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to a <olink targetptr="bdakh">BerElement</olink>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>Bytes_Scanned</literal></para></entry>
|
|
<entry>
|
|
<para>Returns the number of bytes actually searched through.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>sb</literal></para></entry>
|
|
<entry>
|
|
<para>Descriptor (socket or file descriptor) from which to read.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="bdaom"><title><function>ber_get_null</function></title>
|
|
<para>The <function>ber_get_null</function> function is used to read a <literal>NULL
|
|
</literal> element.</para>
|
|
<sect3 id="gaqss"><title>Syntax</title>
|
|
<programlisting>#include <lber.h>
|
|
unsigned long ber_get_null( BerElement *ber );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gaqsz"><title>Parameters</title>
|
|
<table frame="topbot" id="gaqti"><title><function>ber_get_null</function> Function
|
|
Parameter</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ber</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to a <olink targetptr="bdakh">BerElement</olink>.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gaqsh"><title>Returns</title>
|
|
<para>Returns the tag of the element it skips over.</para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaon"><title><function>ber_get_option</function></title>
|
|
<para>The <function>ber_get_option</function> function is used to retrieve
|
|
information about the API and about the specific implementation being used.</para>
|
|
<sect3 id="gaqsn"><title>Syntax</title>
|
|
<programlisting>#include <lber.h>
|
|
int ber_get_option( BerElement *ber, int option, void *value );</programlisting>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="bdaoo"><title><function>ber_get_stringa</function></title>
|
|
<para>The <function>ber_get_stringa</function> function is used to allocate
|
|
memory space into which an octet string is read.</para>
|
|
<sect3 id="gaqsj"><title>Syntax</title>
|
|
<programlisting>#include <lber.h>
|
|
unsigned long ber_get_stringa( BerElement *ber, char **buf );</programlisting>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="bdaop"><title><function>ber_get_stringal</function></title>
|
|
<para>The <function>ber_get_stringal</function> function is used to allocate
|
|
memory space into which an octet string and its length are read.</para>
|
|
<sect3 id="gaqtl"><title>Syntax</title>
|
|
<programlisting>#include <lber.h>
|
|
unsigned long ber_get_stringal( BerElement *ber, struct berval **bv );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gaqtk"><title>Description</title>
|
|
<para>It takes a <olink targetptr="bdakg">berval</olink> structure, and returns
|
|
the result in this parameter.</para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaoq"><title><function>ber_get_stringb</function></title>
|
|
<para>The <function>ber_get_stringb</function> function is used to read an
|
|
octet string into a preallocated buffer.</para>
|
|
<sect3 id="gaqsm"><title>Syntax</title>
|
|
<programlisting>#include <lber.h>
|
|
unsigned long ber_get_stringb( BerElement *ber, char *buf,
|
|
unsigned long *len );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gaqtq"><title>Description</title>
|
|
<para>The <literal>len</literal> parameter should be initialized to the size
|
|
of the buffer, and will contain the length of the octet string read upon return.
|
|
The buffer should be big enough to take the octet string value plus a terminating <literal>
|
|
NULL</literal> byte.</para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaor"><title><function>ber_init</function></title>
|
|
<para>The <function>ber_init</function> function constructs a new <olink targetptr="bdakh">BerElement</olink>.</para>
|
|
<sect3 id="gaqsv"><title>Syntax</title>
|
|
<programlisting>#include <lber.h>
|
|
BerElement * ber_init( const struct berval *bv );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gaqte"><title>Parameters</title>
|
|
<table frame="topbot" id="gaqsb"><title><function>ber_init</function> Function
|
|
Parameter</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>bv</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to a <olink targetptr="bdakg">berval</olink>.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gaqve"><title>Returns</title>
|
|
<itemizedlist>
|
|
<listitem><para>If successful, returns a new <olink targetptr="bdakh">BerElement</olink> containing
|
|
a copy of the data in the <literal>bv</literal> argument.</para></listitem>
|
|
<listitem><para>If not, returns a <literal>NULL</literal> pointer.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="bdaos"><title><function>ber_init_w_nullchar</function></title>
|
|
<para>The <function>ber_init_w_nullchar</function> function constructs a new <olink targetptr="bdakh">BerElement</olink> with a <literal>NULL</literal> character.</para>
|
|
<sect3 id="gaqtu"><title>Syntax</title>
|
|
<programlisting>#include <lber.h>
|
|
void ber_init_w_nullchar( BerElement *ber, int options );</programlisting>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="bdaot"><title><function>ber_next_element</function></title>
|
|
<para>The <function>ber_next_element</function> function is used to return
|
|
the tag and length of the next element in a set or sequence.</para>
|
|
<sect3 id="gaquc"><title>Syntax</title>
|
|
<programlisting>#include <lber.h>
|
|
unsigned long ber_next_element( BerElement *ber, unsigned long *len,
|
|
char *last );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gaqun"><title>Parameters</title>
|
|
<table frame="topbot" id="gaquk"><title><function>ber_next_element</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ber</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to a <olink targetptr="bdakh">BerElement</olink>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>len</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to the address of the unsigned long which returns the length
|
|
of the next element.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>last</literal></para></entry>
|
|
<entry>
|
|
<para>Address of the pointer to return the address of the last byte of the
|
|
element.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gaqvc"><title>Returns</title>
|
|
<para><literal>NULL</literal> pointer is returned on error.</para></sect3>
|
|
<sect3 id="gaquz"><title>Description</title>
|
|
<para>The <function>ber_next_element</function> function is used to return
|
|
the tag and length of the first element in a set or sequence.</para></sect3>
|
|
<sect3 id="gaquq"><title>See Also</title>
|
|
<para><olink targetptr="bdaoe">ber_first_element</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaou"><title><function>ber_peek_tag</function></title>
|
|
<para>The <function>ber_peek_tag</function> function returns the tag of the
|
|
next element to be parsed in the supplied <olink targetptr="bdakh">BerElement</olink> structure.
|
|
</para>
|
|
<sect3 id="gaqtt"><title>Syntax</title>
|
|
<programlisting>#include <lber.h>
|
|
unsigned long ber_peek_tag( BerElement *ber, unsigned long *len );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gaqug"><title>Parameters</title>
|
|
<table frame="topbot" id="gaqui"><title><function>ber_peek_tag</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ber</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to a <olink targetptr="bdakh">BerElement</olink>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>len</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to the address of the unsigned long which returns the length
|
|
of the next element.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gaqtr"><title>Returns</title>
|
|
<para>Returns the tag of the next element to be read in the <olink targetptr="bdakh">BerElement</olink> structure. <literal>LBER_DEFAULT</literal> is
|
|
returned if there is no further data to be read.</para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaov"><title><function>ber_printf</function></title>
|
|
<para>The <function>ber_printf</function> function encodes a BER element.</para>
|
|
<sect3 id="gaquv"><title>Syntax</title>
|
|
<programlisting>#include <lber.h>
|
|
ber_printf( BerElement *ber, const char *fmt, ... );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gaqut"><title>Parameters</title>
|
|
<table frame="topbot" id="gaqty"><title><function>ber_printf</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ber</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to a <olink targetptr="bdakh">BerElement</olink> returned by <olink targetptr="bdany">ber_alloc</olink> or <olink targetptr="bdanz">ber_alloc_t</olink>.
|
|
</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>fmt</literal></para></entry>
|
|
<entry>
|
|
<para>Defines the encoding format string. The format string can contain the
|
|
following characters:</para>
|
|
<itemizedlist>
|
|
<listitem><para><literal>-b</literal> Boolean. An integer parameter should
|
|
be supplied. A boolean element is output.</para></listitem>
|
|
<listitem><para><literal>-i</literal> Integer. An integer parameter should
|
|
be supplied. An integer element is output.</para></listitem>
|
|
<listitem><para><literal>-B</literal> Bitstring. A <literal>char *</literal> pointer
|
|
to the start of the bitstring is supplied, followed by the number of bits
|
|
in the bitstring. A bitstring element is output.</para></listitem>
|
|
<listitem><para><literal>-n</literal> Null. No parameter is required. A <literal>
|
|
NULL</literal> element is output.</para></listitem>
|
|
<listitem><para><literal>-o</literal> Octet string. A <literal>char *</literal> is
|
|
supplied, followed by the length of the string pointed to. An octet string
|
|
element is output.</para></listitem>
|
|
<listitem><para><literal>-s</literal> Octet string. A <literal>NULL</literal> terminated
|
|
string is supplied. An octet string element is output, not including the trailing
|
|
<literal>NULL</literal> octet.</para></listitem>
|
|
<listitem><para><literal>-t</literal> Tag. An <literal>int</literal> specifying
|
|
the tag to give the next element is provided. This works across calls.</para>
|
|
</listitem>
|
|
<listitem><para><literal>-v</literal> Several octet strings. A <literal>NULL</literal> terminated
|
|
array of char *s is supplied. Note that a construct like '{v}' is required
|
|
to get an actual sequence of octet strings.</para></listitem>
|
|
<listitem><para><literal>-{</literal> Begin sequence. No parameter is required.</para>
|
|
</listitem>
|
|
<listitem><para><literal>-}</literal> End sequence. No parameter is required.</para>
|
|
</listitem>
|
|
<listitem><para><literal>-[</literal> Begin set. No parameter is required.</para>
|
|
</listitem>
|
|
<listitem><para><literal>-]</literal> End set. No parameter is required.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>...</literal></para></entry>
|
|
<entry>
|
|
<para>Values to be encoded.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gaqtv"><title>Description</title>
|
|
<para>State information is kept with the <literal>ber</literal> parameter
|
|
so multiple calls can be made to <function>ber_printf</function> to append
|
|
things to the end of the <olink targetptr="bdakh">BerElement</olink>. <function>ber_printf
|
|
</function> interprets and formats its arguments according to the format string <literal>
|
|
fmt</literal>. Each character in <literal>fmt</literal> refers to an argument
|
|
to <function>ber_printf</function> .</para></sect3>
|
|
<sect3 id="gaqup"><title>Returns</title>
|
|
<para><literal>-1</literal> if there is an error during encoding.</para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaow"><title><function>ber_put_bitstring</function></title>
|
|
<para>The <function>ber_put_bitstring</function> function writes a bitstring
|
|
value to the given <olink targetptr="bdakh">BerElement</olink>.</para>
|
|
<sect3 id="gaquo"><title>Syntax</title>
|
|
<programlisting>#include <lber.h>
|
|
int ber_put_bitstring( BerElement *ber, char *str,
|
|
unsigned long bitlen, unsigned long tag );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gaqus"><title>Description</title>
|
|
<para>The <function>ber_put_bitstring</function> function writes <literal>bitlen</literal> bits
|
|
starting at <literal>str</literal> as a bitstring value to the given <olink targetptr="bdakh">BerElement</olink>.</para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaox"><title><function>ber_put_boolean</function></title>
|
|
<para>The <function>ber_put_boolean</function> function writes a boolean value
|
|
to a <olink targetptr="bdakh">BerElement</olink>.</para>
|
|
<sect3 id="gaqvb"><title>Syntax</title>
|
|
<programlisting>#include <lber.h>
|
|
int ber_put_boolean( BerElement *ber, int boolval, unsigned long tag );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gaqud"><title>Description</title>
|
|
<para>The boolean value is given by <literal>boolval</literal> to the <olink targetptr="bdakh">BerElement</olink>.</para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaoy"><title><function>ber_put_enum</function></title>
|
|
<para>The <function>ber_put_enum</function> function writes an enumerated
|
|
value to a <olink targetptr="bdakh">BerElement</olink>.</para>
|
|
<sect3 id="gaque"><title>Syntax</title>
|
|
<programlisting>#include <lber.h>
|
|
int ber_put_enum( BerElement *ber, long num, unsigned long tag );</programlisting>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="bdaoz"><title><function>ber_put_int</function></title>
|
|
<para>The <function>ber_put_int</function> function writes an integer to a <olink targetptr="bdakh">BerElement</olink>.</para>
|
|
<sect3 id="gaquy"><title>Syntax</title>
|
|
<programlisting>#include <lber.h>
|
|
int ber_put_int( BerElement *ber, long num, unsigned long tag );</programlisting>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="bdapa"><title><function>ber_put_null</function></title>
|
|
<para>The <function>ber_put_null</function> function writes a writes a <literal>NULL
|
|
</literal> element to a <olink targetptr="bdakh">BerElement</olink>.</para>
|
|
<sect3 id="gaquw"><title>Syntax</title>
|
|
<programlisting>#include <lber.h>
|
|
int ber_put_null( BerElement *ber, unsigned long tag );</programlisting>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="bdapb"><title><function>ber_put_ostring</function></title>
|
|
<para>The <function>ber_put_ostring</function> function writes bytes to a
|
|
<olink targetptr="bdakh">BerElement</olink> as an octet string.</para>
|
|
<sect3 id="gaqum"><title>Syntax</title>
|
|
<programlisting>#include <lber.h>
|
|
int ber_put_ostring( BerElement *ber, char *str,
|
|
unsigned long len, unsigned long tag );</programlisting>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="bdapc"><title><function>ber_put_seq</function></title>
|
|
<para>The <function>ber_put_seq</function> function puts a sequence to a <olink targetptr="bdakh">BerElement</olink>.</para>
|
|
<sect3 id="gaqtz"><title>Syntax</title>
|
|
<programlisting>#include <lber.h>
|
|
int ber_put_seq( BerElement *ber );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gaqts"><title>Parameters</title>
|
|
<table frame="topbot" id="gaqua"><title><function>ber_put_seq</function> Function
|
|
Parameter</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ber</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to a <olink targetptr="bdakh">BerElement</olink>.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gaqvd"><title>Description</title>
|
|
<para>The <olink targetptr="bdapt">ber_start_seq</olink> function is used
|
|
to start a sequence in the <olink targetptr="bdakh">BerElement</olink>. The
|
|
end of the sequence is marked by the nearest matching call to <function>ber_put_seq
|
|
</function>.</para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdapd"><title><function>ber_put_set</function></title>
|
|
<para>The <function>ber_put_set</function> function puts a set to a <olink targetptr="bdakh">BerElement</olink>.</para>
|
|
<sect3 id="gaqtw"><title>Syntax</title>
|
|
<programlisting>#include <lber.h>
|
|
int ber_put_set( BerElement *ber );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gaqub"><title>Parameters</title>
|
|
<table frame="topbot" id="gaquh"><title><function>ber_put_set</function> Function
|
|
Parameter</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ber</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to a <olink targetptr="bdakh">BerElement</olink>.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gaqtx"><title>Description</title>
|
|
<para>The <olink targetptr="bdapu">ber_start_set</olink> function is used
|
|
to start a set in the <olink targetptr="bdakh">BerElement</olink>. The end
|
|
of the set is marked by the nearest matching call to <function>ber_put_set</function>.
|
|
</para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdape"><title><function>ber_put_string</function></title>
|
|
<para>The <function>ber_put_string</function> function writes a <literal>NULL</literal> terminated
|
|
string (minus the terminating <literal>0</literal>) to a <olink targetptr="bdakh">BerElement</olink> as an octet string.</para>
|
|
<sect3 id="gaqur"><title>Syntax</title>
|
|
<programlisting>#include <lber.h>
|
|
int ber_put_string( BerElement *ber, char *str, unsigned long tag );</programlisting>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="bdapf"><title><function>ber_read</function></title>
|
|
<sect3 id="gaqul"><title>Syntax</title>
|
|
<programlisting>#include <lber.h>
|
|
long ber_read( BerElement *ber, char *buf, unsigned long len );</programlisting>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="bdapg"><title><function>ber_reset</function></title>
|
|
<sect3 id="gaquj"><title>Syntax</title>
|
|
<programlisting>#include <lber.h>
|
|
void ber_reset( BerElement *ber, int was_writing );</programlisting>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="bdaph"><title><function>ber_scanf</function></title>
|
|
<para>The <function>ber_scanf</function> function decodes a <olink targetptr="bdakh">BerElement</olink>.</para>
|
|
<sect3 id="gaqux"><title>Syntax</title>
|
|
<programlisting>#include <lber.h>
|
|
unsigned long ber_scanf( BerElement *ber, const char *fmt, ... );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gaquu"><title>Parameters</title>
|
|
<table frame="topbot" id="gaqva" remap="*Standard"><title><function>ber_scanf</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ber</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to a <olink targetptr="bdakh">BerElement</olink> as returned
|
|
by <olink targetptr="bdaoj">ber_get_next</olink>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>fmt</literal></para></entry>
|
|
<entry>
|
|
<para>Defines the encoding format string. The format string can contain the
|
|
following characters:</para>
|
|
<itemizedlist>
|
|
<listitem><para><literal>-a</literal> Octet string. A <literal>char **</literal> should
|
|
be supplied. Memory is allocated, filled with the contents of the octet string,
|
|
<literal>NULL</literal> terminated, and returned in the parameter.</para>
|
|
</listitem>
|
|
<listitem><para><literal>-s</literal> Octet string. A <literal>char *</literal>
|
|
buffer should be supplied, followed by a pointer to an integer initialized
|
|
to the size of the buffer. Upon return, the <literal>NULL</literal> terminated
|
|
octet string is put into the buffer, and the integer is set to the actual
|
|
size of the octet string.</para></listitem>
|
|
<listitem><para><literal>-O</literal> Octet string. A <literal>struct ber_val
|
|
**</literal> should be supplied, which upon return points to a memory allocated <literal>
|
|
struct berval</literal> containing the octet string and its length. Call
|
|
<olink targetptr="bdaoc">ber_bvfree</olink> to free allocated memory.</para>
|
|
</listitem>
|
|
<listitem><para><literal>-b</literal> Boolean. A pointer to an integer should
|
|
be supplied.</para></listitem>
|
|
<listitem><para><literal>-i</literal> Integer. A pointer to an integer should
|
|
be supplied.</para></listitem>
|
|
<listitem><para><literal>-B</literal> Bitstring. A <literal>char **</literal> should
|
|
be supplied which will point to the memory allocated bits, followed by an
|
|
<literal>unsigned long *</literal>, which will point to the length (in bits)
|
|
of the bitstring returned.</para></listitem>
|
|
<listitem><para><literal>-n</literal> Null. No parameter is required. The
|
|
element is simply skipped if it is recognized.</para></listitem>
|
|
<listitem><para><literal>-v</literal> Sequence of octet strings. A <literal>char
|
|
***</literal> should be supplied, which upon return points to a memory allocated
|
|
<literal>NULL</literal> terminated array of <literal>char *</literal>s containing
|
|
the octet strings. <literal>NULL</literal> is returned if the sequence is
|
|
empty.</para></listitem>
|
|
</itemizedlist>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>fmt</literal> (continued)</para></entry>
|
|
<entry>
|
|
<itemizedlist>
|
|
<listitem><para><literal>-V</literal> Sequence of octet strings with lengths.
|
|
A <literal>struct berval ***</literal> should be supplied, which upon
|
|
return points to a memory allocated, <literal>NULL</literal> terminated array
|
|
of <literal>struct berval *</literal>s containing the octet strings and their
|
|
lengths. <literal>NULL</literal> is returned if the sequence is empty. <olink targetptr="bdaoa">ber_bvecfree</olink> can be called to free the allocated
|
|
memory.</para></listitem>
|
|
<listitem><para><literal>-x</literal> Skip element. The next element is skipped.</para>
|
|
</listitem>
|
|
<listitem><para><literal>-{</literal> Begin sequence. No parameter is required.
|
|
The initial sequence tag and length are skipped.</para></listitem>
|
|
<listitem><para><literal>-}</literal> End sequence. No parameter is required
|
|
and no action is taken.</para></listitem>
|
|
<listitem><para><literal>-[</literal> Begin set. No parameter is required.
|
|
The initial set tag and length are skipped.</para></listitem>
|
|
<listitem><para><literal>-]</literal> End set. No parameter is required and
|
|
no action is taken.</para></listitem>
|
|
</itemizedlist>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>...</literal></para></entry>
|
|
<entry>
|
|
<para>Values to be encoded.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gaquf"><title>Description</title>
|
|
<para><function>ber_scanf</function> reads from <literal>ber</literal>, interprets
|
|
the bytes according to the format string <literal>fmt</literal>, and stores
|
|
the results in its additional arguments. The format string contains conversion
|
|
specifications which are used to direct the interpretation of the BER element.</para>
|
|
</sect3>
|
|
<sect3 id="gaqvt"><title>See Also</title>
|
|
<para><olink targetptr="bdaov">ber_printf</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdapi"><title><function>ber_set_option</function></title>
|
|
<sect3 id="gaqvq"><title>Syntax</title>
|
|
<programlisting>#include <lber.h>
|
|
int ber_set_option( BerElement *ber, int option, void *value );</programlisting>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="bdapj"><title><function>ber_set_string_translators</function></title>
|
|
<sect3 id="gaqvl"><title>Syntax</title>
|
|
<programlisting>#include <lber.h>
|
|
unsigned long ber_skip_tag( BerElement *ber, unsigned long *len );</programlisting>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="bdapk"><title><function>ber_skip_tag</function></title>
|
|
<para>The <function>ber_skip_tag</function> function advances the pointer
|
|
to a <olink targetptr="bdakh">BerElement</olink> past the first tag and length
|
|
to the next tag.</para>
|
|
<sect3 id="gaqvx"><title>Syntax</title>
|
|
<programlisting>#include <lber.h>
|
|
unsigned long ber_skip_tag( BerElement *ber, unsigned long *len );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gaqwn"><title>Parameters</title>
|
|
<table frame="topbot" id="gaqws"><title><function>ber_skip_tag</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ber</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to a <olink targetptr="bdakh">BerElement</olink>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>len</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to the length of the value to be skipped.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gaqvy"><title>Description</title>
|
|
<para><function>ber_skip_tag</function> should only be used with constructed
|
|
types and situations when a BER encoding is used as the value of an octet
|
|
string.</para></sect3>
|
|
<sect3 id="gaqwi"><title>See Also</title>
|
|
<para><olink targetptr="bdaou">ber_peek_tag</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdapl"><title><function>ber_sockbuf_alloc</function></title>
|
|
<sect3 id="gaqwg"><title>Syntax</title>
|
|
<programlisting>#include <lber.h>
|
|
Sockbuf* ber_sockbuf_alloc( void );</programlisting>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="bdapm"><title><function>ber_sockbuf_free</function></title>
|
|
<sect3 id="gaqvh"><title>Syntax</title>
|
|
<programlisting>#include <lber.h>
|
|
void ber_sockbuf_free( Sockbuf* p );</programlisting>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="bdapn"><title><function>ber_sockbuf_free_data</function></title>
|
|
<sect3 id="gaqwa"><title>Syntax</title>
|
|
<programlisting>#include <lber.h>
|
|
void ber_sockbuf_free_data(Sockbuf *p);</programlisting>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="bdapo"><title><function>ber_sockbuf_get_option</function></title>
|
|
<sect3 id="gaqwp"><title>Syntax</title>
|
|
<programlisting>#include <lber.h>
|
|
int ber_sockbuf_get_option( Sockbuf *sb, int option, void *value );</programlisting>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="bdapp"><title><function>ber_sockbuf_set_option</function></title>
|
|
<sect3 id="gaqwo"><title>Syntax</title>
|
|
<programlisting>#include <lber.h>
|
|
int ber_sockbuf_set_option( Sockbuf *sb, int option, void *value );</programlisting>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="bdapq"><title><function>ber_special_alloc</function></title>
|
|
<para>The <function>ber_special_alloc</function> function allocates a <olink targetptr="bdakh">BerElement</olink> structure plus some extra memory.</para>
|
|
<sect3 id="gaqvi"><title>Syntax</title>
|
|
<programlisting>#include <lber.h>
|
|
void* ber_special_alloc( size_t size, BerElement **ppBer );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gaqwf"><title>Returns</title>
|
|
<para>Returns a pointer to the <olink targetptr="bdakh">BerElement</olink> and
|
|
a pointer to the extra memory.</para></sect3>
|
|
<sect3 id="gaqvu"><title>Description</title>
|
|
<para><function>ber_special_alloc</function> allocates a ber data buffer within
|
|
the same block, thus saving a call to calloc later when we read data.</para>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="bdapr"><title><function>ber_special_free</function></title>
|
|
<para>The <function>ber_special_free</function> function frees an allocated <olink targetptr="bdakh">BerElement</olink> structure.</para>
|
|
<sect3 id="gaqwv"><title>Syntax</title>
|
|
<programlisting>#include <lber.h>
|
|
void ber_special_free( void* buf, BerElement *ber );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gaqwm"><title>See Also</title>
|
|
<para><olink targetptr="bdapq">ber_special_alloc</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaps"><title><function>ber_stack_init</function></title>
|
|
<sect3 id="gaqvv"><title>Syntax</title>
|
|
<programlisting>#include <lber.h>
|
|
int) LDAP_CALL ber_stack_init(BerElement *ber, int options,
|
|
char * buf, size_t size);</programlisting>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="bdapt"><title><function>ber_start_seq</function></title>
|
|
<para>The <function>ber_start_seq</function> function is used to start a sequence
|
|
in a <olink targetptr="bdakh">BerElement</olink>.</para>
|
|
<sect3 id="gaqwl"><title>Syntax</title>
|
|
<programlisting>#include <lber.h>
|
|
int ber_start_seq( BerElement *ber, unsigned long tag );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gaqvw"><title>See Also</title>
|
|
<para><olink targetptr="bdapc">ber_put_seq</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdapu"><title><function>ber_start_set</function></title>
|
|
<para>The <function>ber_start_seq</function> function is used to start a set
|
|
in a <olink targetptr="bdakh">BerElement</olink>.</para>
|
|
<sect3 id="gaqvj"><title>Syntax</title>
|
|
<programlisting>#include <lber.h>
|
|
int ber_start_set( BerElement *ber, unsigned long tag );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gaqww"><title>See Also</title>
|
|
<para><olink targetptr="bdapd">ber_put_set</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdapv"><title><function>ber_svecfree</function></title>
|
|
<sect3 id="gaqwc"><title>Syntax</title>
|
|
<programlisting>#include <lber.h>
|
|
void ber_svecfree( char **vals );</programlisting>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="bdapw"><title><function>ber_write</function></title>
|
|
<sect3 id="gaqvg"><title>Syntax</title>
|
|
<programlisting>#include <lber.h>
|
|
long ber_write( BerElement *ber, char *buf,
|
|
unsigned long len, int nosos );</programlisting>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="bdapx"><title><function>ldap_abandon</function></title>
|
|
<para>The <function>ldap_abandon</function> function cancels an asynchronous
|
|
LDAP operation that is in progress.</para>
|
|
<note><para>This is an older function included in the SDK for backward-compatibility.
|
|
If you are writing a new LDAP client, use <olink targetptr="bdapy">ldap_abandon_ext
|
|
</olink> instead.</para></note>
|
|
<sect3 id="gaqvm"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_abandon( LDAP *ld, int msgid );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gaqwh"><title>Parameters</title>
|
|
<table frame="topbot" id="gaqvn"><title><function>ldap_abandon</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>msgid</literal></para></entry>
|
|
<entry>
|
|
<para>Message ID of an LDAP operation.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gaqwe"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para><literal>-1</literal> if unsuccessful.</para></listitem>
|
|
</itemizedlist>
|
|
<note><para>The appropriate LDAP error code is also set in the <olink targetptr="bdakj">LDAP</olink> structure. You can retrieve the error code
|
|
by calling <olink targetptr="bdasq">ldap_get_lderrno</olink>. Some possible
|
|
codes are:</para>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if any of the arguments
|
|
are invalid.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_ENCODING_ERROR</errorcode> if an error occurred
|
|
when BER-encoding the request.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_SERVER_DOWN</errorcode> if the LDAP server
|
|
did not receive the request or if the connection to the server was lost.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
|
|
allocated.</para></listitem>
|
|
</itemizedlist>
|
|
</note>
|
|
</sect3>
|
|
<sect3 id="gaqvo"><title>Description</title>
|
|
<para>Please use the newer version of this function, <olink targetptr="bdapy">ldap_abandon_ext
|
|
</olink>.</para></sect3>
|
|
<sect3 id="gaqwr"><title>Example</title>
|
|
<para><olink targetptr="cancel-url-search">Example 21–2</olink> cancels
|
|
an <olink targetptr="bdawm">ldap_url_search</olink> operation, abandoning
|
|
the results of the operation.</para>
|
|
<example id="cancel-url-search"><title>Cancelling an <function>ldap_url_search</function> Operation
|
|
</title>
|
|
<programlisting>LDAP *ld;
|
|
char *url = "ldap://ldap.example.com/c=US?o,description?one?o=sales";
|
|
int msgid;
|
|
...
|
|
/* Initiate a search operation */
|
|
msgid = ldap_url_search( ld, url, 0 );
|
|
...
|
|
/* Abandon the search operation */
|
|
if ( ldap_abandon( ld, msgid ) != LDAP_SUCCESS ) {
|
|
ldap_perror( ld, "ldap_abandon" );
|
|
return( 1 );
|
|
}
|
|
...</programlisting>
|
|
</example>
|
|
</sect3>
|
|
<sect3 id="gaqwu"><title>See Also</title>
|
|
<para><olink targetptr="bdapy">ldap_abandon_ext</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdapy"><title><function>ldap_abandon_ext</function></title>
|
|
<para>The <function>ldap_abandon_ext</function> function cancels an asynchronous
|
|
LDAP operation that is in progress.</para>
|
|
<note><para><olink targetptr="bdapy">ldap_abandon_ext</olink> is a new version
|
|
of the <olink targetptr="bdapx">ldap_abandon</olink> function. If you are
|
|
writing a new LDAP client, use <olink targetptr="bdapy">ldap_abandon_ext</olink>.
|
|
</para></note>
|
|
<sect3 id="gaqwt"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_abandon_ext( LDAP *ld, int msgid,
|
|
LDAPControl **serverctrls, LDAPControl **clientctrls );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gaqvp"><title>Parameters</title>
|
|
<table frame="topbot" id="gaqwb"><title><function>ldap_abandon_ext</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>msgid</literal></para></entry>
|
|
<entry>
|
|
<para>Message ID of an LDAP operation to identify the operation to be cancelled.
|
|
When you call an asynchronous function such as <olink targetptr="bdauz">ldap_search_ext
|
|
</olink>, the <literal>msgidp</literal> argument returns a pointer to a message
|
|
ID that uniquely identifies the operation. Thus, when you call <olink targetptr="bdapy">ldap_abandon_ext</olink>, your LDAP client is able to send
|
|
a request specifying the message ID of the operation to be cancelled.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>serverctrls</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
|
|
representing LDAP server controls that apply to this operation. If you do
|
|
not want to pass any server controls, specify <literal>NULL</literal> for
|
|
this argument.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>clientctrls</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
|
|
representing LDAP client controls that apply to this operation. If you do
|
|
not want to pass any client controls, specify <literal>NULL</literal> for
|
|
this argument.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gaqwq"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if any of the arguments
|
|
are invalid.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_ENCODING_ERROR</errorcode> if an error occurred
|
|
when BER-encoding the request.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_SERVER_DOWN</errorcode> if the LDAP server
|
|
did not receive the request or if the connection to the server was lost.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
|
|
allocated.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="gaqwd"><title>Description</title>
|
|
<para>The <function>ldap_abandon_ext</function> function cancels an asynchronous
|
|
LDAP operation that is in progress. For example, if you called <olink targetptr="bdauz">ldap_search_ext</olink> to initiate an LDAP search operation
|
|
on the server, you can call <function>ldap_abandon_ext</function> to cancel
|
|
it. When you call <function>ldap_abandon_ext</function>, the function checks
|
|
to see if the results of the operation have already been returned. If so, <function>
|
|
ldap_abandon_ext</function> deletes the message ID from the queue of pending
|
|
messages. If the results have not been returned, <function>ldap_abandon_ext</function> sends
|
|
a request to abandon the operation. Once cancelled, the results of the operation
|
|
will not be returned, even if you subsequently call <olink targetptr="bdauu">ldap_result
|
|
</olink> to retrieve them. To identify the operation to be cancelled, specify
|
|
the message ID of the operation in the <literal>msgid</literal> argument of
|
|
the <function>ldap_abandon_ext</function> function.</para></sect3>
|
|
<sect3 id="gaqwk"><title>Example</title>
|
|
<para><olink targetptr="abandon-example">Example 21–3</olink> cancels
|
|
an <olink targetptr="bdawm">ldap_url_search</olink> operation, abandoning
|
|
the results of the operation.</para>
|
|
<example id="abandon-example"><title>Using <function>ldap_abandon_ext</function></title>
|
|
<programlisting>LDAP *ld;
|
|
char *url = "ldap://ldap.example.com/c=US?o,description?one?o=sales";
|
|
int msgid;
|
|
LDAPControl **srvrctrls, **clntctrls;
|
|
...
|
|
/* Initiate a search operation */
|
|
msgid = ldap_url_search( ld, url, 0 );
|
|
...
|
|
/* Abandon the search operation */
|
|
if ( ldap_abandon_ext( ld, msgid, srvrctrls, clntctrls )
|
|
!= LDAP_SUCCESS ) {
|
|
ldap_perror( ld, "ldap_abandon" );
|
|
return( 1 );
|
|
}
|
|
...</programlisting>
|
|
</example>
|
|
</sect3>
|
|
<sect3 id="gaqvf"><title>See Also</title>
|
|
<para><olink targetptr="bdaqa">ldap_add_ext</olink>, <olink targetptr="bdaqp">ldap_compare_ext
|
|
</olink> , <olink targetptr="bdari">ldap_delete_ext</olink>, <olink targetptr="bdaru">ldap_extended_operation</olink>, <olink targetptr="bdatn">ldap_modify_ext
|
|
</olink>, <olink targetptr="bdaus">ldap_rename</olink>, <olink targetptr="bdauw">
|
|
ldap_sasl_bind</olink> , <olink targetptr="bdauz">ldap_search_ext</olink>,
|
|
<olink targetptr="bdavi">ldap_simple_bind</olink>, <olink targetptr="bdawm">ldap_url_search
|
|
</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdapz"><title><function>ldap_add</function></title>
|
|
<para>The <function>ldap_add</function> function adds a new entry to the directory
|
|
asynchronously.</para>
|
|
<note><para>This is an older function that is included in the SDK for backward-compatibility.
|
|
If you are writing a new LDAP client, use <olink targetptr="bdaqa">ldap_add_ext</olink>
|
|
instead.</para></note>
|
|
<sect3 id="gaqwj"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_add( LDAP *ld, const char *dn, LDAPMod **attrs );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gaqvs"><title>Parameters</title>
|
|
<table frame="topbot" id="gaqvk"><title><function>ldap_add</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>dn</literal></para></entry>
|
|
<entry>
|
|
<para>DN of the entry to add. With the exception of the leftmost component,
|
|
all components of the DN (for example, <literal>o=organization</literal> or <literal>
|
|
c=country</literal>) must already exist.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>attrs</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to a <literal>NULL</literal> terminated array of pointers to <olink targetptr="bdalz">LDAPMod</olink> structures representing the attributes of
|
|
the new entry.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gaqvr"><title>Returns</title>
|
|
<para>The message ID of the <function>ldap_add</function> operation.</para>
|
|
<note><para>To check the result of this operation, call <olink targetptr="bdauu">
|
|
ldap_result</olink> and <olink targetptr="bdauv">ldap_result2error</olink>.
|
|
See <olink targetptr="bdaqb">ldap_add_ext_s</olink> for a list of possible
|
|
result codes for the LDAP add operation.</para></note>
|
|
</sect3>
|
|
<sect3 id="gaqvz"><title>Description</title>
|
|
<para>Please use the newer version of this function, <olink targetptr="bdaqa">ldap_add_ext
|
|
</olink> .</para></sect3>
|
|
<sect3 id="gaqxo"><title>Example</title>
|
|
<para><olink targetptr="adding-entry-example">Example 21–4</olink> adds
|
|
a new entry to the directory.</para>
|
|
<example id="adding-entry-example"><title>Using <function>ldap_add</function></title>
|
|
<programlisting>#include <ldap.h>
|
|
...
|
|
LDAP *ld;
|
|
LDAPMod *list_of_attrs[4];
|
|
LDAPMod attribute1, attribute2, attribute3;
|
|
LDAPMessage *result;
|
|
int msgid, rc;
|
|
struct timeval tv;
|
|
|
|
/* Distinguished name of the new entry. Note that "dc=example,dc=com" and
|
|
"ou=People,dc=example,dc=com" must already exist in the directory. */
|
|
char *dn = "uid=bjensen,ou=People,dc=example,dc=com";
|
|
|
|
/* To add a "person" entry, you must specify values for the sn, cn,
|
|
and objectClass attributes. (These are required attributes.) */
|
|
char *sn_values[] = { "Jensen", NULL };
|
|
|
|
/* To specify multiple values for an attribute, add the different values
|
|
to the array. */
|
|
char *cn_values[] = { "Barbara Jensen", "Babs Jensen", NULL };
|
|
|
|
/* The object class for a "person" entry is "inetOrgPerson", which is a
|
|
subclass of "top", "person", and "organizationalPerson". You should add
|
|
all of these classes as values of the objectClass attribute. */
|
|
char *objectClass_values[] = { "top", "person", "organizationalPerson",
|
|
"inetOrgPerson", NULL };
|
|
...
|
|
/* Specify the value and type of each attribute in separate LDAPMod
|
|
structures */
|
|
attribute1.mod_type = "sn";
|
|
attribute1.mod_values = sn_values;
|
|
attribute2.mod_type = "cn";
|
|
attribute2.mod_values = cn_values;
|
|
attribute3.mod_type = "objectClass";
|
|
attribute3.mod_values = objectClass_values;
|
|
|
|
/* Add the pointers to these LDAPMod structures to an array */
|
|
list_of_attrs[0] = &attribute1;
|
|
list_of_attrs[1] = &attribute2;
|
|
list_of_attrs[2] = &attribute3;
|
|
list_of_attrs[3] = NULL;
|
|
...
|
|
/* Set up the timeout period for adding the new entry */
|
|
tv.tv_sec = tv.tv_usec = 0;
|
|
|
|
/* Add the user "Barbara Jensen" */
|
|
if ( ( msgid = ldap_add( ld, dn, list_of_attrs ) ) == -1 ) {
|
|
ldap_perror( ld, "ldap_add" );
|
|
return( 1 );
|
|
}
|
|
|
|
/* Check to see if the operation has completed */
|
|
while ( ( rc = ldap_result( ld, msgid, 0, &tv, &result ) ) == 0 ) {
|
|
...
|
|
/* do other work while waiting for the operation to complete */
|
|
...
|
|
}
|
|
|
|
/* Check the result to see if any errors occurred */
|
|
if (( rc = ldap_result2error( ld, result, 1 )) != LDAP_SUCCESS ) {
|
|
printf( "Error while adding entry: %s\n", ldap_err2string( rc ));
|
|
}
|
|
...</programlisting>
|
|
</example>
|
|
</sect3>
|
|
<sect3 id="gaqyi"><title>See Also</title>
|
|
<para><olink targetptr="bdaqa">ldap_add_ext</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaqa"><title><function>ldap_add_ext</function></title>
|
|
<para>The <function>ldap_add_ext</function> function adds a new entry to the
|
|
directory asynchronously.</para>
|
|
<note><para><olink targetptr="bdaqa">ldap_add_ext</olink> is a new version
|
|
of the <olink targetptr="bdapz">ldap_add</olink> function. If you are writing
|
|
a new LDAP client, use <olink targetptr="bdaqa">ldap_add_ext</olink>.</para>
|
|
</note>
|
|
<sect3 id="gaqxp"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_add_ext( LDAP *ld, const char *dn, LDAPMod **attrs,
|
|
LDAPControl **serverctrls, LDAPControl **clientctrls,
|
|
int *msgidp );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gaqxc"><title>Parameters</title>
|
|
<table frame="topbot" id="gaqyd"><title><function>ldap_add_ext</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>dn</literal></para></entry>
|
|
<entry>
|
|
<para>DN of the entry to add. With the exception of the leftmost component,
|
|
all components of the DN (for example, <literal>o=organization</literal> or <literal>
|
|
c=country</literal>) must already exist.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>attrs</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to a <literal>NULL</literal> terminated array of pointers to <olink targetptr="bdalz">LDAPMod</olink> structures representing the attributes of
|
|
the new entry.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>serverctrls</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
|
|
representing LDAP server controls that apply to this operation. If you do
|
|
not want to pass any server controls, specify <literal>NULL</literal> for
|
|
this argument.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>clientctrls</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
|
|
representing LDAP client controls that apply to this operation. If you do
|
|
not want to pass any client controls, specify <literal>NULL</literal> for
|
|
this argument.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>msgidp</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an integer that will be set to the message ID of the LDAP
|
|
operation.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gaqxs"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if any of the arguments
|
|
are invalid.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_ENCODING_ERROR</errorcode> if an error occurred
|
|
when BER-encoding the request.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_SERVER_DOWN</errorcode> if the LDAP server
|
|
did not receive the request or if the connection to the server was lost.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
|
|
allocated.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_NOT_SUPPORTED</errorcode> if controls are
|
|
included in your request (for example, as a session preference) and your LDAP
|
|
client does not specify that it is using the LDAP v3. Make sure that you set
|
|
the version of your LDAP client to version 3 before calling this function.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="gaqxw"><title>Description</title>
|
|
<para>The <function>ldap_add_ext</function> adds a new entry to the directory.
|
|
To add a new entry to the directory, you need to specify:</para>
|
|
<itemizedlist>
|
|
<listitem><para>A unique DN identifying the new entry.</para><para>Use the
|
|
<literal>dn</literal> argument to specify the DN of the new entry. The parents
|
|
of the entry should already exist. For example, if you are adding the entry <literal>
|
|
uid=bjensen,ou=People,dc=example,dc=com</literal> , the entries <literal>ou=People
|
|
</literal> and <literal>dc=example,dc=com</literal> must already exist in
|
|
the directory.</para></listitem>
|
|
<listitem><para>A set of attributes for the new entry.</para><para>Create
|
|
an <olink targetptr="bdalz">LDAPMod</olink> structure for each attribute.
|
|
Set the <literal>mod_op</literal> field to <literal>0</literal> if the attribute
|
|
values are string values. To specify values that consist of binary data (such
|
|
as a sound file or a JPEG file), set the <literal>mod_op</literal> field to <literal>
|
|
LDAP_MOD_BVALUES</literal>. Create an array of these <olink targetptr="bdalz">LDAPMod
|
|
</olink> structures and pass the array as the <literal>attrs</literal> argument.</para>
|
|
<para><function>ldap_add_ext</function> is an asynchronous function; it does
|
|
not directly return results. In order to get the results of the asynchronous
|
|
operation, you need to call the <olink targetptr="bdauu">ldap_result</olink> and <olink targetptr="bdaun">ldap_parse_result</olink> functions. If you want the results
|
|
to be returned directly by the function, call the synchronous function <olink targetptr="bdaqb">ldap_add_ext_s</olink>. For a list of possible result codes
|
|
for an LDAP add operation, see the <olink targetptr="bdaqb">ldap_add_ext_s</olink>
|
|
function.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="gaqxd"><title>See Also</title>
|
|
<para><olink targetptr="bdaqb">ldap_add_ext_s</olink>, <olink targetptr="bdauu">
|
|
ldap_result</olink>, <olink targetptr="bdaun">ldap_parse_result</olink>, <olink targetptr="bdalz">LDAPMod</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaqb"><title><function>ldap_add_ext_s</function></title>
|
|
<para>The <function>ldap_add_ext_s</function> function adds a new entry to
|
|
the directory synchronously.</para>
|
|
<note><para><olink targetptr="bdaqb">ldap_add_ext_s</olink> is a new version
|
|
of the <olink targetptr="bdaqc">ldap_add_s</olink> function. If you are writing
|
|
a new LDAP client, use <olink targetptr="bdaqb">ldap_add_ext_s</olink>.</para>
|
|
</note>
|
|
<sect3 id="gaqyl"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_add_ext_s( LDAP *ld, const char *dn, LDAPMod **attrs,
|
|
LDAPControl **serverctrls, LDAPControl **clientctrls );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gaqxe"><title>Parameters</title>
|
|
<table frame="topbot" id="gaqyk"><title><function>ldap_add_ext_s</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>dn</literal></para></entry>
|
|
<entry>
|
|
<para>DN of the entry to add. With the exception of the leftmost component,
|
|
all components of the DN (for example, <literal>o=organization</literal> or <literal>
|
|
c=country</literal>) must already exist.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>attrs</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to a <literal>NULL</literal> terminated array of pointers to <olink targetptr="bdalz">LDAPMod</olink> structures representing the attributes of
|
|
the new entry.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>serverctrls</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
|
|
representing LDAP server controls that apply to this operation. If you do
|
|
not want to pass any server controls, specify <literal>NULL</literal> for
|
|
this argument.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>clientctrls</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
|
|
representing LDAP client controls that apply to this operation. If you do
|
|
not want to pass any client controls, specify <literal>NULL</literal> for
|
|
this argument.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gaqyn"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if any of the arguments
|
|
are invalid.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_ENCODING_ERROR</errorcode> if an error occurred
|
|
when BER-encoding the request.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_SERVER_DOWN</errorcode> if the LDAP server
|
|
did not receive the request or if the connection to the server was lost.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
|
|
allocated.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_LOCAL_ERROR</errorcode> if an error occurred
|
|
when receiving the results from the server.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_DECODING_ERROR</errorcode> if an error occurred
|
|
when decoding the BER-encoded results from the server.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_NOT_SUPPORTED</errorcode> if controls are
|
|
included in your request (for example, as a session preference) and your LDAP
|
|
client does not specify that it is using the LDAP v3. Make sure that you set
|
|
the version of your LDAP client to version 3 before calling this function.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<note><para>&cnDirectoryServer; and other LDAP server products may send result
|
|
codes in addition to those described. For example, the server may have loaded
|
|
a plug-in that returns custom result codes. Check your LDAP server documentation
|
|
for other result codes.</para></note>
|
|
</sect3>
|
|
<sect3 id="gaqxx"><title>Description</title>
|
|
<para>The <function>ldap_add_ext_s</function> function adds a new entry to
|
|
the directory. To add a new entry to the directory, you need to specify:</para>
|
|
<itemizedlist>
|
|
<listitem><para>A unique DN identifying the new entry.</para><para>Use the
|
|
<literal>dn</literal> argument to specify the DN of the new entry. The parents
|
|
of the entry should already exist. For example, if you are adding the entry <literal>
|
|
uid=bjensen,ou=People,dc=example,dc=com</literal> , the entries <literal>ou=People
|
|
</literal> and <literal>dc=example,dc=com</literal> must already exist in
|
|
the directory.</para></listitem>
|
|
<listitem><para>A set of attributes for the new entry.</para><para>Create
|
|
an <olink targetptr="bdalz">LDAPMod</olink> structure for each attribute.
|
|
Set the <literal>mod_op</literal> field to <literal>0</literal> if the attribute
|
|
values are string values. To specify values that consist of binary data (such
|
|
as a sound file or a JPEG file), set the <literal>mod_op</literal> field to <literal>
|
|
LDAP_MOD_BVALUES</literal>. Create an array of these <olink targetptr="bdalz">LDAPMod
|
|
</olink> structures and pass the array as the <literal>attrs</literal> argument.</para>
|
|
<para><function>ldap_add_ext_s</function> is a synchronous function; it directly
|
|
returns the results of the operation. If you want to perform other operations
|
|
while waiting for the results of this operation, call the asynchronous function <olink targetptr="bdaqa">ldap_add_ext</olink>.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="gaqxz"><title>See Also</title>
|
|
<para><olink targetptr="bdaqa">ldap_add_ext</olink>, <olink targetptr="bdalz">LDAPMod
|
|
</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaqc"><title><function>ldap_add_s</function></title>
|
|
<para>The <function>ldap_add_s</function> function adds a new entry to the
|
|
directory synchronously.</para>
|
|
<note><para>This is an older function that is included in the SDK for backward-compatibility.
|
|
If you are writing a new LDAP client, use <olink targetptr="bdaqb">ldap_add_ext_s
|
|
</olink> instead.</para></note>
|
|
<sect3 id="gaqyq"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_add_s( LDAP *ld, const char *dn, LDAPMod **attrs );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gaqyr"><title>Parameters</title>
|
|
<table frame="topbot" id="gaqym"><title><function>ldap_add_s</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>dn</literal></para></entry>
|
|
<entry>
|
|
<para>DN of the entry to add. With the exception of the leftmost component,
|
|
all components of the DN (for example, <literal>o=organization</literal> or <literal>
|
|
c=country</literal>) must already exist.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>attrs</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to a <literal>NULL</literal> terminated array of pointers to <olink targetptr="bdalz">LDAPMod</olink> structures representing the attributes of
|
|
the new entry.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gaqxi"><title>Returns</title>
|
|
<para>See <olink targetptr="bdaqb">ldap_add_ext_s</olink> for a list of possible
|
|
return codes.</para></sect3>
|
|
<sect3 id="gaqxg"><title>Description</title>
|
|
<para>Please use the newer version of this function, <olink targetptr="bdaqb">ldap_add_ext_s
|
|
</olink> .</para></sect3>
|
|
<sect3 id="gaqxa"><title>Example</title>
|
|
<para><olink targetptr="ldap-add-s-example">Example 21–5</olink> adds
|
|
a new entry to the directory.</para>
|
|
<example id="ldap-add-s-example"><title>Using <function>ldap_add_s</function></title>
|
|
<programlisting>#include <ldap.h>
|
|
...
|
|
LDAP *ld;
|
|
LDAPMod *list_of_attrs[4];
|
|
LDAPMod attribute1, attribute2, attribute3;
|
|
|
|
/* Distinguished name of the new entry. Note that "dc=example,dc=com" and
|
|
"ou=People,dc=example,dc=com" must already exist in the directory. */
|
|
char *dn = "uid=bjensen,ou=People,dc=example, dc=com";
|
|
|
|
/* To add a "person" entry, you must specify values for the sn, cn,
|
|
and objectClass attributes. (These are required attributes.) */
|
|
char *sn_values[] = { "Jensen", NULL };
|
|
|
|
/* To specify multiple values for an attribute, add the different values
|
|
to the array. */
|
|
char *cn_values[] = { "Barbara Jensen", "Babs Jensen", NULL };
|
|
|
|
/* The object class for a "person" entry is "inetOrgPerson", which is a
|
|
* subclass of "top", "person", and "organizationalPerson". You should add
|
|
* all of these classes as values of the objectClass attribute. */
|
|
char *objectClass_values[] = { "top", "person", "organizationalPerson",
|
|
"inetOrgPerson", NULL };
|
|
...
|
|
/* Specify the value and type of each attribute in separate LDAPMod
|
|
structures */
|
|
attribute1.mod_type = "sn";
|
|
attribute1.mod_values = sn_values;
|
|
attribute2.mod_type = "cn";
|
|
attribute2.mod_values = cn_values;
|
|
attribute3.mod_type = "objectClass";
|
|
attribute3.mod_values = objectClass_values;
|
|
|
|
/* Add the pointers to these LDAPMod structures to an array */
|
|
list_of_attrs[0] = &attribute1;
|
|
list_of_attrs[1] = &attribute2;
|
|
list_of_attrs[2] = &attribute3;
|
|
list_of_attrs[3] = NULL;
|
|
...
|
|
/* Add the user "Barbara Jensen" */
|
|
if ( ldap_add_s( ld, dn, list_of_attrs ) != LDAP_SUCCESS ) {
|
|
ldap_perror( ld, "ldap_add_s" );
|
|
return( 1 );
|
|
}
|
|
...</programlisting>
|
|
</example>
|
|
</sect3>
|
|
<sect3 id="gaqxt"><title>See Also</title>
|
|
<para><olink targetptr="bdaqb">ldap_add_ext_s</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaqd"><title><function>ldap_ber_free</function></title>
|
|
<para>The <function>ldap_ber_free</function> function frees a <olink targetptr="bdakh">BerElement</olink> structure from memory.</para>
|
|
<note><para>This is an older function that is included in the SDK for backward-compatibility.
|
|
If you are writing a new LDAP client, use <olink targetptr="bdaog">ber_free</olink> instead.
|
|
Except in name, the two functions are identical.</para></note>
|
|
<sect3 id="gaqwy"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
void ldap_ber_free( BerElement *ber, int freebuf );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gaqwx"><title>Parameters</title>
|
|
<table frame="topbot" id="gaqxy"><title><function>ldap_ber_free</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ber</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to the <olink targetptr="bdakh">BerElement</olink> structure
|
|
that you want to free.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>freebuf</literal></para></entry>
|
|
<entry>
|
|
<para>Specifies whether or not to free the buffer in the <olink targetptr="bdakh">BerElement</olink> structure.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gaqxj"><title>Description</title>
|
|
<para>Please use the newer version of this function, <olink targetptr="bdaog">ber_free
|
|
</olink> .</para></sect3>
|
|
<sect3 id="gaqxn"><title>See Also</title>
|
|
<para><olink targetptr="bdaog">ber_free</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaqe"><title><function>ldap_bind</function></title>
|
|
<note><para>This function is deprecated and should not be used. It is included
|
|
in <literal>ldap-deprecated.h</literal> for backward-compatibility. Use <olink targetptr="bdavi">ldap_simple_bind</olink> instead.</para></note>
|
|
<para><function>ldap_bind</function> can be used when the authentication method
|
|
being used needs to be selected at runtime.</para>
|
|
<sect3 id="gaqxm"><title>Syntax</title>
|
|
<programlisting>#include <ldap-deprecated.h>
|
|
ldap_bind( LDAP *ld, const char *who, const char *passwd, int method );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gaqyo"><title>Parameters</title>
|
|
<table frame="topbot" id="gaqxk"><title><function>ldap_bind</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>who</literal></para></entry>
|
|
<entry>
|
|
<para>DN of the user who wants to authenticate. For anonymous authentication,
|
|
set this or the <parameter>passwd</parameter> argument to <literal>NULL</literal>.
|
|
</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>passwd</literal></para></entry>
|
|
<entry>
|
|
<para>Password of the user who wants to authenticate. For anonymous authentication,
|
|
set this or the who argument to <literal>NULL</literal>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>method</literal></para></entry>
|
|
<entry>
|
|
<para>Defines the authentication method to be used. It should be set to <literal>
|
|
LDAP_AUTH_SIMPLE</literal> to select simple authentication.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gaqye"><title>Returns</title>
|
|
<para><function>ldap_bind</function> returns the message ID of the request
|
|
it initiates.</para></sect3>
|
|
<sect3 id="gaqxu"><title>Description</title>
|
|
<para>This is an asynchronous function that authenticates a specified entry
|
|
to the directory. After a connection is made to an LDAP server using <olink targetptr="bdauj">ldap_open</olink>, a bind operation must be performed before
|
|
other operations can be attempted over the connection.</para></sect3>
|
|
<sect3 id="gaqyg"><title>See Also</title>
|
|
<para><olink targetptr="bdauj">ldap_open</olink>, <olink targetptr="bdasv">ldap_init
|
|
</olink>, <olink targetptr="bdaxr">prldap_init</olink> (IPv6), <olink targetptr="bdaqf">ldap_bind_s</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaqf"><title><function>ldap_bind_s</function></title>
|
|
<note><para>This function is deprecated and should not be used. It is included
|
|
in <literal>ldap-deprecated.h</literal> for backward-compatibility. Use <olink targetptr="bdavj">ldap_simple_bind_s</olink> instead.</para></note>
|
|
<para><function>ldap_bind_s</function> can be used when the authentication
|
|
method needs to be selected at runtime.</para>
|
|
<sect3 id="gaqxl"><title>Syntax</title>
|
|
<programlisting>#include <ldap-deprecated.h>
|
|
ldap_bind_s( LDAP *ld, const char *who, const char *cred, int method );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gaqyc"><title>Parameters</title>
|
|
<table frame="topbot" id="gaqyj"><title><function>ldap_bind_s</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>who</literal></para></entry>
|
|
<entry>
|
|
<para>DN of the user who wants to authenticate. For anonymous authentication,
|
|
set this or the <parameter>passwd</parameter> argument to <literal>NULL</literal>.
|
|
</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>cred</literal></para></entry>
|
|
<entry>
|
|
<para>Password of the user who wants to authenticate. For anonymous authentication,
|
|
set this or the who argument to <literal>NULL</literal>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>method</literal></para></entry>
|
|
<entry>
|
|
<para>Defines the authentication method to be used. It should be set to <literal>
|
|
LDAP_AUTH_SIMPLE</literal> to select simple authentication.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gaqya"><title>Returns</title>
|
|
<para><function>ldap_bind_s</function> returns an LDAP error indication.</para>
|
|
</sect3>
|
|
<sect3 id="gaqxr"><title>Description</title>
|
|
<para>This is a synchronous function that authenticates a specified entry
|
|
to the directory. After a connection is made to an LDAP server using <olink targetptr="bdauj">ldap_open</olink> , a bind operation must be performed
|
|
before other operations can be attempted over the connection.</para></sect3>
|
|
<sect3 id="gaqyh"><title>See Also</title>
|
|
<para><olink targetptr="bdauj">ldap_open</olink>, <olink targetptr="bdasv">ldap_init
|
|
</olink>, <olink targetptr="bdaxr">prldap_init</olink> (IPv6), <olink targetptr="bdaqe">ldap_bind</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaqg"><title><function>ldap_build_filter</function></title>
|
|
<note><para>This function is deprecated and should not be used. It is included
|
|
in <literal>ldap-deprecated.h</literal> for backward-compatibility. Use <olink targetptr="bdaqz">ldap_create_filter</olink> instead.</para></note>
|
|
<sect3 id="gaqxq"><title>See Also</title>
|
|
<para><olink targetptr="bdaqz">ldap_create_filter</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaqh"><title><function>ldap_cache_flush</function></title>
|
|
<note><para>This function is deprecated and should not be used. It is included
|
|
in <literal>ldap-deprecated.h</literal> for backward-compatibility. Use the
|
|
<literal>ldap_memcache_*</literal> functions instead.</para></note>
|
|
<para>For more specific information, see the header file <literal>ldap-deprecated.h
|
|
</literal> .</para>
|
|
<sect3 id="gaqxv"><title>See Also</title>
|
|
<para><olink targetptr="bdati">ldap_memcache_init</olink>, <olink targetptr="bdatj">ldap_memcache_set</olink>, <olink targetptr="bdath">ldap_memcache_get
|
|
</olink>, <olink targetptr="bdatk">ldap_memcache_update</olink>, <olink targetptr="bdatg">ldap_memcache_flush</olink> , <olink targetptr="bdatf">ldap_memcache_destroy
|
|
</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaqi"><title><function>ldap_charray_add</function></title>
|
|
<note><para>This function is deprecated and should not be used. It is included
|
|
in <literal>ldap-to-be-deprecated.h</literal> for backward-compatibility.</para>
|
|
</note>
|
|
<para>For more specific information, see the header file <literal>ldap-to-be-deprecated.h
|
|
</literal> .</para>
|
|
<sect3 id="bdaqj"><title><function>ldap_charray_dup</function></title>
|
|
<note><para>This function is deprecated and should not be used. It is included
|
|
in <literal>ldap-to-be-deprecated.h</literal> for backward-compatibility.</para>
|
|
</note>
|
|
<para>For more specific information, see the header file <literal>ldap-to-be-deprecated.h
|
|
</literal> .</para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaqk"><title><function>ldap_charray_free</function></title>
|
|
<note><para>This function is deprecated and should not be used. It is included
|
|
in <literal>ldap-to-be-deprecated.h</literal> for backward-compatibility.</para>
|
|
</note>
|
|
<para>For more specific information, see the header file <literal>ldap-to-be-deprecated.h
|
|
</literal> .</para>
|
|
<sect3 id="bdaql"><title><function>ldap_charray_inlist</function></title>
|
|
<note><para>This function is deprecated and should not be used. It is included
|
|
in <literal>ldap-to-be-deprecated.h</literal> for backward-compatibility.</para>
|
|
</note>
|
|
<para>For more specific information, see the header file <literal>ldap-to-be-deprecated.h
|
|
</literal> .</para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaqm"><title><function>ldap_charray_merge</function></title>
|
|
<note><para>This function is deprecated and should not be used. It is included
|
|
in <literal>ldap-to-be-deprecated.h</literal> for backward-compatibility.</para>
|
|
</note>
|
|
<para>For more specific information, see the header file <literal>ldap-to-be-deprecated.h
|
|
</literal> .</para>
|
|
<sect3 id="bdaqn"><title><function>ldap_charray_position</function></title>
|
|
<note><para>This function is deprecated and should not be used. It is included
|
|
in <literal>ldap-to-be-deprecated.h</literal> for backward-compatibility.</para>
|
|
</note>
|
|
<para>For more specific information, see the header file <literal>ldap-to-be-deprecated.h
|
|
</literal> .</para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaqo"><title><function>ldap_compare</function></title>
|
|
<para>The <function>ldap_compare</function> function asynchronously determines
|
|
if an attribute of an entry contains a specified value.</para>
|
|
<note><para>This is an older function that is included in the SDK for backward-compatibility.
|
|
If you are writing a new LDAP client, use <olink targetptr="bdaqp">ldap_compare_ext
|
|
</olink> instead.</para></note>
|
|
<sect3 id="gaqxf"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_compare( LDAP *ld, const char *dn, const char *attr,
|
|
const char *value );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gaqyf"><title>Parameters</title>
|
|
<table frame="topbot" id="gaqwz"><title><function>ldap_compare</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>dn</literal></para></entry>
|
|
<entry>
|
|
<para>DN of the entry used in the comparison.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>attr</literal></para></entry>
|
|
<entry>
|
|
<para>Attribute type that you want to check the value against.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>value</literal></para></entry>
|
|
<entry>
|
|
<para>Value that you want to compare against the attribute values.</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gaqxh"><title>Returns</title>
|
|
<para>Returns the message ID of the <function>ldap_compare</function> operation.</para>
|
|
<note><para>To check the result of this operation, call <olink targetptr="bdauu">
|
|
ldap_result</olink> and <olink targetptr="bdauv">ldap_result2error</olink>.
|
|
See <olink targetptr="bdaqq">ldap_compare_ext_s</olink> function for a list
|
|
of possible result codes for the LDAP compare operation.</para></note>
|
|
</sect3>
|
|
<sect3 id="gaqyb"><title>Description</title>
|
|
<para>Please use the newer version of this function, <olink targetptr="bdaqp">ldap_compare_ext
|
|
</olink> .</para></sect3>
|
|
<sect3 id="gaqyp"><title>Example</title>
|
|
<para><olink targetptr="ldap-compare-example">Example 21–6</olink> checks
|
|
to see if Barbara Jensen has the email address <literal>bjensen@example.com</literal>.
|
|
</para>
|
|
<example id="ldap-compare-example"><title>Using <function>ldap_compare</function></title>
|
|
<programlisting>#include <stdio.h>
|
|
#include <ldap.h>
|
|
...
|
|
LDAP *ld;
|
|
char *dn = "uid=bjensen,ou=People,dc=example, dc=com";
|
|
int msgid;
|
|
...
|
|
msg_id = ldap_compare( ld, dn, "mail", "bjensen@example.com" );
|
|
...</programlisting>
|
|
</example>
|
|
</sect3>
|
|
<sect3 id="gaqxb"><title>See Also</title>
|
|
<para><olink targetptr="bdaqp">ldap_compare_ext</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaqp"><title><function>ldap_compare_ext</function></title>
|
|
<para>The <function>ldap_compare_ext</function> function asynchronously determines
|
|
if an attribute of an entry contains a specified value.</para>
|
|
<note><para><olink targetptr="bdaqp">ldap_compare_ext</olink> is a new version
|
|
of the <olink targetptr="bdaqo">ldap_compare</olink> function. If you are
|
|
writing a new LDAP client, use <olink targetptr="bdaqp">ldap_compare_ext</olink>.
|
|
</para></note>
|
|
<sect3 id="gaqzh"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_compare_ext( LDAP *ld, const char *dn, const char *attr,
|
|
struct berval *bvalue, LDAPControl **serverctrls,
|
|
LDAPControl **clientctrls, int *msgidp );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gaqzs"><title>Parameters</title>
|
|
<table frame="topbot" id="gaqzv"><title><function>ldap_compare_ext</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>dn</literal></para></entry>
|
|
<entry>
|
|
<para>DN of the entry used in the comparison.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>attr</literal></para></entry>
|
|
<entry>
|
|
<para>Attribute type that you want to check the value against.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>value</literal></para></entry>
|
|
<entry>
|
|
<para>Value that you want to compare against the attribute values.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>serverctrls</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
|
|
representing LDAP server controls that apply to this operation. If you do
|
|
not want to pass any server controls, specify <literal>NULL</literal> for
|
|
this argument.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>clientctrls</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
|
|
representing LDAP client controls that apply to this operation. If you do
|
|
not want to pass any client controls, specify <literal>NULL</literal> for
|
|
this argument.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>msgidp</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an integer that will be set to the message ID of the LDAP
|
|
operation.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gaqzj"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if any of the arguments
|
|
are invalid.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_ENCODING_ERROR</errorcode> if an error occurred
|
|
when BER-encoding the request.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_SERVER_DOWN</errorcode> if the LDAP server
|
|
did not receive the request or if the connection to the server was lost.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
|
|
allocated.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_NOT_SUPPORTED</errorcode> if controls are
|
|
included in your request (for example, as a session preference) and your LDAP
|
|
client does not specify that it is using the LDAP v3. Make sure that you set
|
|
the version of your LDAP client to version 3 before calling this function.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<note><para>To check the result of this operation, call <olink targetptr="bdauu">
|
|
ldap_result</olink> and <olink targetptr="bdaun">ldap_parse_result</olink>.</para>
|
|
</note>
|
|
</sect3>
|
|
<sect3 id="gaqzf"><title>Returns</title>
|
|
<para>For a list of the possible result codes for an LDAP compare operation,
|
|
see <olink targetptr="bdaqq">ldap_compare_ext_s</olink>.</para></sect3>
|
|
<sect3 id="gaqyx"><title>Description</title>
|
|
<para>The <function>ldap_compare_ext</function> function compares the value
|
|
of an attribute in an entry against a specified value. Because <function>ldap_compare_ext
|
|
</function> is an asynchronous function, it does not directly return results.
|
|
If you want the results to be returned directly by the function, call the
|
|
synchronous function <olink targetptr="bdaqq">ldap_compare_ext_s</olink>.</para>
|
|
</sect3>
|
|
<sect3 id="gaqzc"><title>See Also</title>
|
|
<para><olink targetptr="bdaqq">ldap_compare_ext_s</olink>, <olink targetptr="bdauu">ldap_result</olink>, <olink targetptr="bdaun">ldap_parse_result
|
|
</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaqq"><title><function>ldap_compare_ext_s</function></title>
|
|
<para>The <function>ldap_compare_ext_s</function> function synchronously determines
|
|
if an attribute of an entry contains a specified value.</para>
|
|
<sect3 id="gaqyt"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_compare_ext_s( LDAP *ld, const char *dn,
|
|
const char *attr, struct berval *bvalue,
|
|
LDAPControl **serverctrls, LDAPControl **clientctrls );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gaqzu"><title>Parameters</title>
|
|
<table frame="topbot" id="gaqze"><title><function>ldap_compare_ext_s</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>dn</literal></para></entry>
|
|
<entry>
|
|
<para>DN of the entry used in the comparison.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>attr</literal></para></entry>
|
|
<entry>
|
|
<para>Attribute type that you want to check the value against.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>value</literal></para></entry>
|
|
<entry>
|
|
<para>Value that you want to compare against the attribute values.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>serverctrls</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
|
|
representing LDAP server controls that apply to this operation. If you do
|
|
not want to pass any server controls, specify <literal>NULL</literal> for
|
|
this argument.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>clientctrls</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
|
|
representing LDAP client controls that apply to this operation. If you do
|
|
not want to pass any client controls, specify <literal>NULL</literal> for
|
|
this argument.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gaqyw"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_COMPARE_TRUE</errorcode> if the entry contains
|
|
the attribute value.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_COMPARE_FALSE</errorcode> if the entry does
|
|
not contain the attribute value.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if any of the arguments
|
|
are invalid.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_ENCODING_ERROR</errorcode> if an error occurred
|
|
when BER-encoding the request.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_SERVER_DOWN</errorcode> if the LDAP server
|
|
did not receive the request or if the connection to the server was lost.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
|
|
allocated.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_LOCAL_ERROR</errorcode> if an error occurred
|
|
when receiving the results from the server.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_DECODING_ERROR</errorcode> if an error occurred
|
|
when decoding the BER-encoded results from the server.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_NOT_SUPPORTED</errorcode> if controls are
|
|
included in your request (for example, as a session preference) and your LDAP
|
|
client does not specify that it is using the LDAP v3. Make sure that you set
|
|
the version of your LDAP client to version 3 before calling this function.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<note><para>&cnDirectoryServer; and other LDAP server products may send result
|
|
codes in addition to those described. For example, the server may have loaded
|
|
a plug-in that returns custom result codes. Check your LDAP server documentation
|
|
for other result codes.</para></note>
|
|
</sect3>
|
|
<sect3 id="gaqyy"><title>Description</title>
|
|
<para>The <function>ldap_compare_ext_s</function> function compares the value
|
|
of an attribute in an entry against a specified value. <function>ldap_compare_ext_s
|
|
</function> is a synchronous function, which directly returns the results
|
|
of the operation. If you want to perform other operations while waiting for
|
|
the results of this operation, call the asynchronous function <olink targetptr="bdaqp">ldap_compare_ext</olink>.</para></sect3>
|
|
<sect3 id="gaqzt"><title>See Also</title>
|
|
<para><olink targetptr="bdaqp">ldap_compare_ext</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaqr"><title><function>ldap_compare_s</function></title>
|
|
<para>The <function>ldap_compare_s</function> function synchronously determines
|
|
if an attribute of an entry contains a specified value.</para>
|
|
<note><para>This is an older function that is included in the SDK for backward-compatibility.
|
|
If you are writing a new LDAP client, use <olink targetptr="bdaqq">ldap_compare_ext_s
|
|
</olink> instead.</para></note>
|
|
<sect3 id="gaqzl"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_compare_s( LDAP *ld, const char *dn,
|
|
const char *attr, const char *value );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gaqzk"><title>Parameters</title>
|
|
<table frame="topbot" id="gaqzp"><title><function>ldap_compare_s</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>dn</literal></para></entry>
|
|
<entry>
|
|
<para>DN of the entry used in the comparison.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>attr</literal></para></entry>
|
|
<entry>
|
|
<para>Attribute type that you want to check the value against.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>value</literal></para></entry>
|
|
<entry>
|
|
<para>Value that you want to compare against the attribute values.</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gaqzg"><title>Returns</title>
|
|
<para>For a list of the possible result codes for an LDAP compare operation,
|
|
see <olink targetptr="bdaqq">ldap_compare_ext_s</olink>.</para></sect3>
|
|
<sect3 id="gaqzz"><title>Description</title>
|
|
<para>Please use the newer version of this function, <olink targetptr="bdaqq">ldap_compare_ext_s
|
|
</olink> .</para></sect3>
|
|
<sect3 id="gaqzy"><title>Example</title>
|
|
<para><olink targetptr="ldap-compare-s-example">Example 21–7</olink> checks
|
|
to see if Barbara Jensen has the email address <literal>bjensen@example.com</literal>.
|
|
</para>
|
|
<example id="ldap-compare-s-example"><title>Using <function>ldap_compare_s</function></title>
|
|
<programlisting>#include <stdio.h>
|
|
#include <ldap.h>
|
|
LDAP *ld;
|
|
char *dn = "uid=bjensen,ou=People,dc=example, dc=com";
|
|
int has_value;
|
|
...
|
|
has_value = ldap_compare_s( ld, dn, "mail", "bjensen@example.com" );
|
|
switch ( has_value ) {
|
|
case LDAP_COMPARE_TRUE:
|
|
printf( "The mail attribute contains bjensen@example.com.\n");
|
|
break;
|
|
case LDAP_COMPARE_FALSE:
|
|
printf( "The mail attribute does not contain bjensen@example.com.\n");
|
|
break;
|
|
default:
|
|
ldap_perror( ld, "ldap_compare_s" );
|
|
return( 1 );
|
|
}
|
|
...</programlisting>
|
|
</example>
|
|
</sect3>
|
|
<sect3 id="gaqzo"><title>See Also</title>
|
|
<para><olink targetptr="bdaqq">ldap_compare_ext_s</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaqs"><title><function>ldap_control_free</function></title>
|
|
<para>The <function>ldap_control_free</function> function frees an <olink targetptr="bdala">LDAPControl</olink> structure from memory.</para>
|
|
<sect3 id="gaqzx"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
void ldap_control_free( LDAPControl *ctrl );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gaqyv"><title>Parameters</title>
|
|
<table frame="topbot" id="gaqzn"><title><function>ldap_control_free</function> Function
|
|
Parameter</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ctrl</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdala">LDAPControl</olink> structure
|
|
that you want to free from memory.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gaqzi"><title>Description</title>
|
|
<para>The <function>ldap_control_free</function> function frees an <olink targetptr="bdala">LDAPControl</olink> structure from memory. You should call
|
|
this function to free controls that you create; for example, if you call the <olink targetptr="bdare">ldap_create_sort_control</olink> function.</para></sect3>
|
|
<sect3 id="gaqzr"><title>See Also</title>
|
|
<para><olink targetptr="bdaqt">ldap_controls_free</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaqt"><title><function>ldap_controls_free</function></title>
|
|
<para>The <function>ldap_controls_free</function> function frees an array
|
|
of <olink targetptr="bdala">LDAPControl</olink> structures from memory.</para>
|
|
<sect3 id="gaqzq"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
void ldap_controls_free( LDAPControl **ctrls );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gaqzd"><title>Parameters</title>
|
|
<table frame="topbot" id="gaqzm"><title><function>ldap_controls_free</function> Function
|
|
Parameter</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ctrls</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
|
|
that you want to free from memory.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gaqyu"><title>Description</title>
|
|
<para>The <function>ldap_controls_free</function> function frees an array
|
|
of <olink targetptr="bdala">LDAPControl</olink> structures from memory. You
|
|
should call this function to free arrays of controls that you create or any
|
|
arrays returned by <olink targetptr="bdaun">ldap_parse_result</olink>.</para>
|
|
</sect3>
|
|
<sect3 id="gaqyz"><title>See Also</title>
|
|
<para><olink targetptr="bdaqs">ldap_control_free</olink>, <olink targetptr="bdaun">ldap_parse_result</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaqu"><title><function>ldap_count_entries</function></title>
|
|
<para>The <function>ldap_count_entries</function> function returns the number
|
|
of <olink targetptr="bdaly">LDAPMessage</olink> structures representing directory
|
|
entries in a chain of search results.</para>
|
|
<sect3 id="gaqys"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_count_entries( LDAP *ld, LDAPMessage *result );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gaqza"><title>Parameters</title>
|
|
<table frame="topbot" id="gaqzb"><title><function>ldap_count_entries</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>result</literal></para></entry>
|
|
<entry>
|
|
<para>Chain of search results, represented by pointer to an <olink targetptr="bdaly">LDAPMessage</olink> structure.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gaqzw"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para>If successful, the number of <olink targetptr="bdaly">LDAPMessage
|
|
</olink> structures of the type <literal>LDAP_RES_SEARCH_ENTRY</literal> in
|
|
a chain of search results. If there are no structures of this type, returns <literal>
|
|
0</literal>.</para></listitem>
|
|
<listitem><para><literal>-1</literal> if <literal>ld</literal> is not a valid
|
|
connection handle.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garag"><title>Description</title>
|
|
<para>The <function>ldap_count_entries</function> function returns the number
|
|
of <olink targetptr="bdaly">LDAPMessage</olink> structures representing directory
|
|
entries in a chain of search results. These messages have the type <literal>LDAP_RES_SEARCH_ENTRY
|
|
</literal> .</para>
|
|
<note><para>If you pass in a pointer to an <olink targetptr="bdaly">LDAPMessage</olink> structure
|
|
in the middle of the chain of results, the function counts only the entries
|
|
between that structure and the last structure in the chain. In this type of
|
|
situation, the function does not return the count of all entries in the chain.</para>
|
|
</note>
|
|
</sect3>
|
|
<sect3 id="garaf"><title>Example</title>
|
|
<para>See the examples under <olink targetptr="bdauz">ldap_search_ext</olink> and <olink targetptr="bdava">ldap_search_ext_s</olink>.</para></sect3>
|
|
<sect3 id="garbe"><title>See Also</title>
|
|
<para><olink targetptr="bdauu">ldap_result</olink>, <olink targetptr="bdauz">ldap_search_ext
|
|
</olink> , <olink targetptr="bdava">ldap_search_ext_s</olink>, <olink targetptr="bdary">ldap_first_entry</olink>, <olink targetptr="bdauc">ldap_next_entry
|
|
</olink>, <olink targetptr="bdary">ldap_first_entry</olink>, <olink targetptr="bdaud">ldap_next_message</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaqv"><title><function>ldap_count_messages</function></title>
|
|
<para>The <function>ldap_count_messages</function> function returns the number
|
|
of <olink targetptr="bdaly">LDAPMessage</olink> structures in a chain of search
|
|
results.</para>
|
|
<sect3 id="garbo"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_count_messages( LDAP *ld, LDAPMessage *res );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garbl"><title>Parameters</title>
|
|
<table frame="topbot" id="garbn"><title><function>ldap_count_messages</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>result</literal></para></entry>
|
|
<entry>
|
|
<para>Chain of search results, represented by pointer to an <olink targetptr="bdaly">LDAPMessage</olink> structure.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garbf"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para>The number of <olink targetptr="bdaly">LDAPMessage</olink> structures
|
|
in a chain of search results, if successful. If there are no structures, returns
|
|
<literal>0</literal>.</para></listitem>
|
|
<listitem><para><literal>-1</literal> if <literal>ld</literal> is not a valid
|
|
connection handle.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garav"><title>Description</title>
|
|
<para>The <function>ldap_count_messages</function> function returns the number
|
|
of <olink targetptr="bdaly">LDAPMessage</olink> structures in a chain of search
|
|
results. The count is the number of search entries plus the number of search
|
|
references.</para>
|
|
<note><para>If you pass in a pointer to an <olink targetptr="bdaly">LDAPMessage</olink> structure
|
|
in the middle of the chain of results, the function counts only between that
|
|
structure and the last structure in the chain. In this type of situation,
|
|
the function does not return the count of all structures in the chain.</para>
|
|
</note>
|
|
</sect3>
|
|
<sect3 id="garas"><title>Example</title>
|
|
<para>See the examples under <olink targetptr="bdauz">ldap_search_ext</olink> and <olink targetptr="bdava">ldap_search_ext_s</olink>.</para></sect3>
|
|
<sect3 id="garat"><title>See Also</title>
|
|
<para><olink targetptr="bdauu">ldap_result</olink>, <olink targetptr="bdauz">ldap_search_ext
|
|
</olink> , <olink targetptr="bdava">ldap_search_ext_s</olink>, <olink targetptr="bdarz">ldap_first_message</olink>, <olink targetptr="bdaud">ldap_next_message
|
|
</olink>, <olink targetptr="bdary">ldap_first_entry</olink>, <olink targetptr="bdauc">ldap_next_entry</olink> , <olink targetptr="bdasa">ldap_first_reference
|
|
</olink>, <olink targetptr="bdaue">ldap_next_reference</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaqw"><title><function>ldap_count_references</function></title>
|
|
<para>The <function>ldap_count_references</function> function returns the
|
|
number of <olink targetptr="bdaly">LDAPMessage</olink> structures representing
|
|
search references in a chain of search results.</para>
|
|
<sect3 id="garaz"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_count_references( LDAP *ld, LDAPMessage *res );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garam"><title>Parameters</title>
|
|
<table frame="topbot" id="garbm"><title><function>ldap_count_references</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>result</literal></para></entry>
|
|
<entry>
|
|
<para>Chain of search results, represented by pointer to an <olink targetptr="bdaly">LDAPMessage</olink> structure.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garab"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para>The number of <olink targetptr="bdaly">LDAPMessage</olink> structures
|
|
of the type <literal>LDAP_RES_SEARCH_REFERENCE</literal> in a chain of search
|
|
results, if successful. (If there are no structures of this type, returns <literal>
|
|
0</literal>.)</para></listitem>
|
|
<listitem><para><literal>-1</literal> if <literal>ld</literal> is not a valid
|
|
connection handle.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garay"><title>Description</title>
|
|
<para>The <function>ldap_count_references</function> function returns the
|
|
number of <olink targetptr="bdaly">LDAPMessage</olink> structures representing
|
|
search references in a chain of search results. These messages have the type <literal>
|
|
LDAP_RES_SEARCH_REFERENCE</literal>, continuation references as specified
|
|
in LDAPv3 that are stored as referral entries. Like a referral, each continuation
|
|
reference itself may contain a number of URLs assumed to be equivalent, and
|
|
the client should use one of those URLs.</para>
|
|
<note><para>If you pass in a pointer to an <olink targetptr="bdaly">LDAPMessage</olink> structure
|
|
in the middle of the chain of results, the function counts only the references
|
|
between that structure and the last structure in the chain. In this type of
|
|
situation, the function does not return the count of all references in the
|
|
chain.</para></note>
|
|
</sect3>
|
|
<sect3 id="garan"><title>Example</title>
|
|
<para>See the examples under <olink targetptr="bdauz">ldap_search_ext</olink> and <olink targetptr="bdava">ldap_search_ext_s</olink>.</para></sect3>
|
|
<sect3 id="garax"><title>See Also</title>
|
|
<para><olink targetptr="bdauu">ldap_result</olink>, <olink targetptr="bdauz">ldap_search_ext
|
|
</olink> , <olink targetptr="bdava">ldap_search_ext_s</olink>, <olink targetptr="bdasa">ldap_first_reference</olink>, <olink targetptr="bdaue">ldap_next_reference
|
|
</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaqx"><title><function>ldap_count_values</function></title>
|
|
<para>The <function>ldap_count_values</function> function returns the number
|
|
of values in an array of strings.</para>
|
|
<note><para>Use the <olink targetptr="bdaqy">ldap_count_values_len</olink> function
|
|
if the array contains <olink targetptr="bdakg">berval</olink> structures.</para>
|
|
</note>
|
|
<sect3 id="garbd"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_count_values( char **values );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garbp"><title>Parameters</title>
|
|
<table frame="topbot" id="garbb"><title><function>ldap_count_values</function> Function
|
|
Parameter</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><parameter>values</parameter></para></entry>
|
|
<entry>
|
|
<para>Array of values.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garbc"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para>The number of values in the array, if successful.</para>
|
|
</listitem>
|
|
<listitem><para><literal>-1</literal> if unsuccessful.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garbk"><title>Example</title>
|
|
<para><olink targetptr="ldap-count-values-example">Example 21–8</olink> counts
|
|
the number of values assigned to an attribute.</para>
|
|
<example id="ldap-count-values-example"><title>Using <function>ldap_count_values</function></title>
|
|
<programlisting>#include <ldap.h>
|
|
...
|
|
LDAP *ld;
|
|
LDAPMessage *e;
|
|
char *a="cn";
|
|
char **vals;
|
|
int count;
|
|
...
|
|
|
|
/* Get the values of the cn attribute */
|
|
vals = ldap_get_values( ld, e, a );
|
|
|
|
/* Count the values of the attribute */
|
|
count = ldap_count_values( vals );
|
|
...</programlisting>
|
|
</example>
|
|
</sect3>
|
|
<sect3 id="garak"><title>See Also</title>
|
|
<para><olink targetptr="bdaqy">ldap_count_values_len</olink>, <olink targetptr="bdast">ldap_get_values</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaqy"><title><function>ldap_count_values_len</function></title>
|
|
<para>The <function>ldap_count_values_len</function> function returns the
|
|
number of values in an array of <olink targetptr="bdakg">berval</olink> structures.
|
|
</para>
|
|
<note><para>Use the <olink targetptr="bdaqx">ldap_count_values</olink> function
|
|
if the array contains strings.</para></note>
|
|
<sect3 id="garaw"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_count_values_len( struct berval **vals );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garah"><title>Parameters</title>
|
|
<table frame="topbot" id="garbr"><title><function>ldap_count_values_len</function> Function
|
|
Parameter</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>values</literal></para></entry>
|
|
<entry>
|
|
<para>Array of <olink targetptr="bdakg">berval</olink> structures.</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garal"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para>The number of values in the array, if successful.</para>
|
|
</listitem>
|
|
<listitem><para><literal>-1</literal> if unsuccessful.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garaj"><title>Example</title>
|
|
<para><olink targetptr="ldap-count-values-len-example">Example 21–9</olink>
|
|
counts the number of values assigned to an attribute.</para>
|
|
<example id="ldap-count-values-len-example"><title>Using <function>ldap_count_values_len
|
|
</function></title>
|
|
<programlisting>#include <ldap.h>
|
|
LDAP *ld;
|
|
LDAPMessage *e;
|
|
char *a="jpegPhoto";
|
|
struct berval **bvals;
|
|
int count;
|
|
...
|
|
/* Get the values of the jpegPhoto attribute */
|
|
bvals = ldap_get_values_len( ld, e, a );
|
|
|
|
/* Count the values of the attribute */
|
|
count = ldap_count_values_len( vals );
|
|
...</programlisting>
|
|
</example>
|
|
</sect3>
|
|
<sect3 id="garac"><title>See Also</title>
|
|
<para><olink targetptr="bdaqx">ldap_count_values</olink>, <olink targetptr="bdasu">ldap_get_values_len</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="ldap-create-authzid-control"><title><function>ldap_create_authzid_control
|
|
</function></title>
|
|
<para>The <function>ldap_create_authzid_control</function> function creates
|
|
a control that requests the authorization ID for a bind operation. This is
|
|
defined in RFC 3829.</para>
|
|
<note><para>In order for the control to work, the LDAP server that you are
|
|
connecting to must support the server controls for authorization bind identity
|
|
(OID <literal>2.16.840.1.113730.3.4.16</literal> or <literal>LDAP_CONTROL_AUTHZID_REQ
|
|
</literal>, and OID <literal>2.16.840.1.113730.3.4.15</literal> or <literal>LDAP_CONTROL_AUTHZID_RES
|
|
</literal>).</para></note>
|
|
<para>Calling <function>ldap_create_authzid_control</function> creates an
|
|
LDAP control that you can pass to the <olink targetptr="bdavi">ldap_simple_bind</olink> function
|
|
to retrieve the authorization ID in the response. You call <olink targetptr="ldap-parse-authzid-control">ldap_parse_authzid_control</olink> function
|
|
on the controls returned with an entry to retrieve a <literal>char *</literal> containing
|
|
the authorization ID.</para>
|
|
<para>When you are done with the search, you should free the control by calling
|
|
the <olink targetptr="bdaqs">ldap_control_free</olink> function.</para>
|
|
<sect3><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
LDAP_API(int) LDAP_CALL ldap_create_authzid_control( LDAP *ld,
|
|
const char ctl_iscritical, LDAPControl **ctrlp );</programlisting>
|
|
</sect3>
|
|
<sect3><title>Parameters</title>
|
|
<table frame="topbot" id="gbgbu"><title><function>ldap_create_authzid_control</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2" colsep="0" rowsep="0"><colspec colwidth="50*"><colspec
|
|
colwidth="50*">
|
|
<thead>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>
|
|
<para><parameter>ld</parameter></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><parameter>ctl_iscritical</parameter></para></entry>
|
|
<entry>
|
|
<para>Specifies whether the control is critical to the operation.</para>
|
|
<itemizedlist>
|
|
<listitem><para>If non-zero, the control is critical to the operation. If
|
|
the server does not support it, the server returns an <errorcode>LDAP_UNAVAILABLE_CRITICAL_EXTENSION
|
|
</errorcode> error.</para></listitem>
|
|
<listitem><para>If <literal>0</literal>, the control is not critical to the
|
|
operation. Even if the server does not support the control, the operation
|
|
is still attempted and the control is ignored.</para></listitem>
|
|
</itemizedlist>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><parameter>ctrlp</parameter></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdala">LDAPControl</olink> structure
|
|
created by this function. When you are done using this control, you should
|
|
free it by calling <olink targetptr="bdaqs">ldap_control_free</olink>.</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if an invalid parameter
|
|
was passed to the function.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
|
|
allocated.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_ENCODING_ERROR</errorcode> if an error occurred
|
|
when BER-encoding the control.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3><title>See Also</title>
|
|
<para><olink targetptr="ldap-parse-authzid-control">ldap_parse_authzid_control</olink></para>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="bdaqz"><title><function>ldap_create_filter</function></title>
|
|
<para>The <function>ldap_create_filter</function> routine constructs an LDAP
|
|
search filter.</para>
|
|
<sect3 id="garau"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_create_filter( char *buf, unsigned long buflen,
|
|
char *pattern, char *prefix, char *suffix, char *attr,
|
|
char *value, char **valwords );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garae"><title>Parameters</title>
|
|
<table frame="topbot" id="garao"><title><function>ldap_create_filter</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>buf</literal></para></entry>
|
|
<entry>
|
|
<para>Buffer to contain the constructed filter.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>buflen</literal></para></entry>
|
|
<entry>
|
|
<para>Size of the buffer.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>pattern</literal></para></entry>
|
|
<entry>
|
|
<para>Pattern for the filter.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>prefix</literal></para></entry>
|
|
<entry>
|
|
<para>Prefix to prepend to the filter. (<literal>NULL</literal> if not used.)</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>suffix</literal></para></entry>
|
|
<entry>
|
|
<para>Suffix to append to the filter. (<literal>NULL</literal> if not used.)</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>attr</literal></para></entry>
|
|
<entry>
|
|
<para>Replaces <literal>%a</literal> in the pattern.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>value</literal></para></entry>
|
|
<entry>
|
|
<para>Replaces <literal>%v</literal> in the pattern.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>valwords</literal></para></entry>
|
|
<entry>
|
|
<para>Replaces <literal>%vM</literal> through <literal>%vN</literal> in the
|
|
pattern.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garbj"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_SIZELIMIT_EXCEEDED</errorcode> if the created
|
|
filter exceeds the size of the buffer.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if an invalid parameter
|
|
was passed to the function.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garaa"><title>Example</title>
|
|
<para><olink targetptr="ldap-create-filter-example">Example 21–10</olink> builds
|
|
the filter <literal>(mail=bjensen@example.com)</literal>.</para>
|
|
<example id="ldap-create-filter-example"><title>Creating a Filter with <function>
|
|
ldap_create_filter</function></title>
|
|
<programlisting>char buf[LDAP_FILT_MAXSIZ];
|
|
char *pattern = "(%a=%v)";
|
|
char *attr = "mail";
|
|
char *value = "bjensen@example.com";
|
|
...
|
|
ldap_create_filter( buf, LDAP_FILT_MAXSIZ, pattern, NULL,
|
|
NULL, attr, value, NULL );
|
|
...</programlisting>
|
|
</example>
|
|
</sect3>
|
|
<sect3 id="garbq"><title>See Also</title>
|
|
<para><olink targetptr="bdasw">ldap_init_getfilter</olink>, <olink targetptr="bdasx">ldap_init_getfilter_buf</olink>, <olink targetptr="bdasn">ldap_getfirstfilter
|
|
</olink> , <olink targetptr="bdasr">ldap_getnextfilter</olink>, <olink targetptr="bdavd">ldap_set_filter_additions</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdarb"><title><function>ldap_create_geteffectiveRights_control</function></title>
|
|
<para>The <function>ldap_create_geteffectiveRights_control</function> function
|
|
allows a user having correct privileges to query about the access rights another
|
|
identity has on one or more entries in the directory.</para>
|
|
<sect3 id="garap"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
LDAP_API(int) LDAP_CALL ldap_create_geteffectiveRights_control( LDAP *ld,
|
|
const char *authzid, const char **attrlist, const char ctl_iscritical,
|
|
LDAPControl **ctrlp );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garbg"><title>Parameters</title>
|
|
<table frame="topbot" id="garar"><title><function>ldap_create_geteffectiveRights_control
|
|
</function> Function Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="25*"><colspec colnum="2"
|
|
colwidth="75*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>authzid</literal></para></entry>
|
|
<entry>
|
|
<para>The DN of the identity for which you are checking access rights.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>attrlist</literal></para></entry>
|
|
<entry>
|
|
<para>List of attributes to return, such as <literal>aclRights</literal> and <literal>
|
|
aclRightsInfo</literal>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>ctl_iscritical</literal></para></entry>
|
|
<entry>
|
|
<para>Specifies whether the control is critical to the operation.</para>
|
|
<itemizedlist>
|
|
<listitem><para>If non-zero, the control is critical to the operation. If
|
|
the server does not support it, the server will return an <errorcode>LDAP_UNAVAILABLE_CRITICAL_EXTENSION
|
|
</errorcode> error.</para></listitem>
|
|
<listitem><para>If <literal>0</literal>, the control is not critical to the
|
|
operation. Even if the server does not support the control, the operation
|
|
is still attempted and the control is ignored.</para></listitem>
|
|
</itemizedlist>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>ctrlp</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdala">LDAPControl</olink> structure
|
|
created by this function. When you are done using this control, you should
|
|
free it by calling <olink targetptr="bdaqs">ldap_control_free</olink>.</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="bdara"><title><function>ldap_create_persistentsearch_control</function></title>
|
|
<para>The <function>ldap_create_persistentsearch_control</function> function
|
|
creates a control that allows your client to perform a search of an LDAP v3
|
|
server that continues without termination until your client abandons it.</para>
|
|
<note><para>Persistent search is an optional feature; it may not be supported
|
|
on all LDAP servers. In order for the control to work, the server that you
|
|
are connecting to must support the server control for persistent searches
|
|
(OID 2.16.840.1.113730.3.4.3, or <literal>LDAP_CONTROL_PERSISTENTSEARCH</literal>,
|
|
as defined in the <literal>ldap.h</literal> header file).</para></note>
|
|
<sect3 id="garai"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_create_persistentsearch_control( LDAP *ld,
|
|
int changetypes, int changesonly, int return_echg_ctls,
|
|
char ctl_iscritical, LDAPControl **ctrlp );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garaq"><title>Parameters</title>
|
|
<table frame="topbot" id="garad"><title><function>ldap_create_persistentsearch_control
|
|
</function> Function Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="30*"><colspec colnum="2"
|
|
colwidth="70*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>changetypes</literal></para></entry>
|
|
<entry>
|
|
<para>Specifies the types of changes that you want to keep track of. This
|
|
field can have one or more of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><literal>LDAP_CHANGETYPE_ADD</literal> specifies that you
|
|
want to keep track of entries added to the directory.</para></listitem>
|
|
<listitem><para><literal>LDAP_CHANGETYPE_DELETE</literal> specifies that you
|
|
want to keep track of entries deleted from the directory.</para></listitem>
|
|
<listitem><para><literal>LDAP_CHANGETYPE_MODIFY</literal> specifies that you
|
|
want to keep track of entries that are modified.</para></listitem>
|
|
<listitem><para><literal>LDAP_CHANGETYPE_MODDN</literal> specifies that you
|
|
want to keep track of entries that are renamed.</para></listitem>
|
|
<listitem><para><literal>LDAP_CHANGETYPE_ANY</literal> specifies that you
|
|
want to keep track of all of the above changes to the directory.</para><para>You
|
|
can <literal>OR</literal> the values together to specify multiple types.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>changesonly</literal></para></entry>
|
|
<entry>
|
|
<para>Specifies whether or not you want skip the initial search and only get
|
|
the latest changes as they occur:</para>
|
|
<itemizedlist>
|
|
<listitem><para>If non-zero, the initial search is skipped and only entries
|
|
that have changed after the initial search are returned.</para></listitem>
|
|
<listitem><para>If <literal>0</literal>, the results of the initial search
|
|
are returned first.</para></listitem>
|
|
</itemizedlist>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>return_echg_ctls</literal></para></entry>
|
|
<entry>
|
|
<para>Specifies whether or not entry controls are included with each entry
|
|
returned to your client:</para>
|
|
<itemizedlist>
|
|
<listitem><para>If non-zero, a control is included with each entry.</para>
|
|
</listitem>
|
|
<listitem><para>If <literal>0</literal>, controls are not included with the
|
|
entries returned from the server.</para></listitem>
|
|
</itemizedlist>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>ctl_iscritical</literal></para></entry>
|
|
<entry>
|
|
<para>Specifies whether the control is critical to the operation.</para>
|
|
<itemizedlist>
|
|
<listitem><para>If non-zero, the control is critical to the operation. If
|
|
the server does not support it, the server will return an <literal>LDAP_UNAVAILABLE_CRITICAL_EXTENSION
|
|
</literal> error.</para></listitem>
|
|
<listitem><para>If <literal>0</literal>, the control is not critical to the
|
|
operation. Even if the server does not support the control, the operation
|
|
is still attempted and the control is ignored.</para></listitem>
|
|
</itemizedlist>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>ctrlp</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdala">LDAPControl</olink> structure
|
|
created by this function. When you are done using this control, you should
|
|
free it by calling <olink targetptr="bdaqs">ldap_control_free</olink>.</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garbi"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if an invalid parameter
|
|
was passed to the function.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
|
|
allocated.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_ENCODING_ERROR</errorcode> if an error occurred
|
|
when BER-encoding the control.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garbh"><title>Description</title>
|
|
<para>The <function>ldap_create_persistentsearch_control</function> function
|
|
allows you to perform persistent searches. A <emphasis>persistent search</emphasis> provides
|
|
the means to track changes to a set of entries that match the search criteria.
|
|
After the initial search is performed, the server keeps track of the search
|
|
criteria and sends back information when any entry that matches the criteria
|
|
is added, deleted, modified, or renamed. Calling <function>ldap_create_persistentsearch_control
|
|
</function> creates an LDAP server control that you can pass to the <olink targetptr="bdauz">ldap_search_ext</olink> function.</para>
|
|
<para>As stated, after you create the control, you can pass it to the LDAP
|
|
server during a search operation. If you specify that you want “entry
|
|
change notification” controls sent back (that is, if you specify a non-zero
|
|
value for the <literal>return_echg_ctls</literal> parameter), the server
|
|
includes controls with each changed entry it sends back. To retrieve the controls
|
|
from each entry, call the <olink targetptr="bdasl">ldap_get_entry_controls</olink> function.
|
|
To get data about the changes made to the entry from the control, call the <olink targetptr="bdauk">ldap_parse_entrychange_control</olink> function.</para>
|
|
<para>When you are done with the search, you can cancel the persistent search
|
|
by calling the <olink targetptr="bdapy">ldap_abandon_ext</olink> function.
|
|
You should also free the control from memory by calling the <olink targetptr="bdaqs">ldap_control_free</olink> function.</para></sect3>
|
|
<sect3 id="garba"><title>See Also</title>
|
|
<para><olink targetptr="bdauz">ldap_search_ext</olink>, <olink targetptr="bdapy">
|
|
ldap_abandon_ext</olink>, <olink targetptr="bdasl">ldap_get_entry_controls</olink>, <olink targetptr="bdauk">ldap_parse_entrychange_control</olink>, <olink targetptr="bdaqs">ldap_control_free</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="ldap-create-pwdpolicy-control"><title><function>ldap_create_pwdpolicy_control
|
|
</function></title>
|
|
<para>The <function>ldap_create_pwdpolicy_control</function> function creates
|
|
a control that requests information about the status of a user account.</para>
|
|
<note><para><function>ldap_create_pwdpolicy_control</function> implements
|
|
an extension to the LDAP v3 supported by &cnDirectoryServer;.</para><para>In
|
|
order for the control to work, the LDAP server that you are connecting to
|
|
must support the server control for password policy (OID <literal>1.3.6.1.4.1.42.2.27.8.5.1
|
|
</literal>, or <literal>LDAP_CONTROL_ACCOUNT_USABLE</literal>).</para></note>
|
|
<para>Calling <function>ldap_create_pwdpolicy_control</function> creates an
|
|
LDAP control that you can pass to the <olink targetptr="bdavi">ldap_simple_bind</olink> functions
|
|
to retrieve password policy information from bind, modify, add, compare, and
|
|
potentially extended operation responses including password policy response
|
|
controls. You call <olink targetptr="ldap-parse-pwdpolicy-control">ldap_parse_pwdpolicy_control
|
|
</olink> function on the controls returned with an entry to retrieve a <olink targetptr="ldappwdpolicy">LDAPpwdpolicy</olink> structure containing information
|
|
about the status of the account.</para>
|
|
<para>When you are done with the search, you should free the control by calling
|
|
the <olink targetptr="bdaqs">ldap_control_free</olink> function.</para>
|
|
<sect3><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
LDAP_API(int) LDAP_CALL ldap_create_pwdpolicy_control( LDAP *ld,
|
|
const char ctl_iscritical, LDAPControl **ctrlp );</programlisting>
|
|
</sect3>
|
|
<sect3><title>Parameters</title>
|
|
<table frame="topbot" id="gbgby"><title><function>ldap_create_pwdpolicy_control</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2" colsep="0" rowsep="0"><colspec colwidth="50*"><colspec
|
|
colwidth="50*">
|
|
<thead>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>
|
|
<para><parameter>ld</parameter></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><parameter>ctl_iscritical</parameter></para></entry>
|
|
<entry>
|
|
<para>Specifies whether the control is critical to the operation.</para>
|
|
<itemizedlist>
|
|
<listitem><para>If non-zero, the control is critical to the operation. If
|
|
the server does not support it, the server returns an <errorcode>LDAP_UNAVAILABLE_CRITICAL_EXTENSION
|
|
</errorcode> error.</para></listitem>
|
|
<listitem><para>If <literal>0</literal>, the control is not critical to the
|
|
operation. Even if the server does not support the control, the operation
|
|
is still attempted and the control is ignored.</para></listitem>
|
|
</itemizedlist>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><parameter>ctrlp</parameter></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdala">LDAPControl</olink> structure
|
|
created by this function. When you are done using this control, you should
|
|
free it by calling <olink targetptr="bdaqs">ldap_control_free</olink>.</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if an invalid parameter
|
|
was passed to the function.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
|
|
allocated.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_ENCODING_ERROR</errorcode> if an error occurred
|
|
when BER-encoding the control.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3><title>See Also</title>
|
|
<para><olink targetptr="ldap-parse-pwdpolicy-control">ldap_parse_pwdpolicy_control
|
|
</olink>, <olink targetptr="ldappwdpolicy">LDAPpwdpolicy</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdarc"><title><function>ldap_create_proxiedauth_control</function></title>
|
|
<para>The <function>ldap_create_proxiedauth_control</function> function creates
|
|
an LDAP v3 control that allows a bound entity to assume the identity of another
|
|
directory entry.</para>
|
|
<note><para><olink targetptr="bdarc">ldap_create_proxiedauth_control</olink> is
|
|
a new version of the <olink targetptr="bdard">ldap_create_proxyauth_control</olink> function.
|
|
If you are writing a new LDAP client, use <olink targetptr="bdarc">ldap_create_proxiedauth_control
|
|
</olink> .</para></note>
|
|
<sect3 id="gardl"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_create_proxiedauth_control( LDAP *ld, char *authzid,
|
|
LDAPControl **ctrlp);</programlisting>
|
|
</sect3>
|
|
<sect3 id="gardm"><title>Parameters</title>
|
|
<table frame="topbot" id="garcl"><title><function>ldap_create_proxiedauth_control
|
|
</function> Function Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="25*"><colspec colnum="2"
|
|
colwidth="75*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>authzid</literal></para></entry>
|
|
<entry>
|
|
<para>The string representing the identity to assume for the access rights,
|
|
defined in the format specified by the following Augmented Backus-Naur Form
|
|
(ABNF) from RFC 4513:</para>
|
|
<programlisting>; Specific predefined authorization (authz)
|
|
; id schemes are defined below --
|
|
; new schemes may be defined in the future.
|
|
|
|
authzId = dnAuthzId / uAuthzId
|
|
|
|
; distinguished-name-based authz id.
|
|
dnAuthzId = "dn:" dn
|
|
dn = utf8string ; syntax from RFC 4514
|
|
|
|
; unspecified userid, UTF-8 encoded.
|
|
uAuthzId = "u:" userid
|
|
userid = utf8string ; syntax unspecified</programlisting>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>ctrlp</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdala">LDAPControl</olink> structure
|
|
created by this function. When you are done using this control, you should
|
|
free it by calling <olink targetptr="bdaqs">ldap_control_free</olink>.</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garcz"><title>Description</title>
|
|
<para>More information on proxy authorization can be found in the <citetitle> LDAP
|
|
Proxied Authorization Control Internet Draft</citetitle> (<ulink
|
|
url="http://ietfreport.isoc.org/ids/draft-weltman-ldapv3-proxy-12.txt"
|
|
type="text_url"></ulink>).</para>
|
|
<note><para>Proxy authorization is an optional feature; it may not be supported
|
|
on all LDAP servers. In order for the control to work, the server that you
|
|
are connecting to must support the server control for proxy authorization
|
|
(OID 2.16.840.1.113730.3.4.18, or <literal>LDAP_CONTROL_PROXIEDAUTH</literal>,
|
|
as defined in the <literal>ldap-extension.h</literal> header file).</para>
|
|
</note>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="bdard"><title><function>ldap_create_proxyauth_control</function></title>
|
|
<para>The <function>ldap_create_proxyauth_control</function> function creates
|
|
an LDAP v3 control that allows a bound entity to assume the identity of another
|
|
directory entry.</para>
|
|
<note><para>This is an older function that is included in the SDK for backward-compatibility.
|
|
If you are writing a new LDAP client, use <olink targetptr="bdarc">ldap_create_proxiedauth_control
|
|
</olink> .</para></note>
|
|
<sect3 id="garcp"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_create_proxyauth_control( LDAP *ld, char *DN,
|
|
char ctl_iscritical, LDAPControl **ctrlp);</programlisting>
|
|
</sect3>
|
|
<sect3 id="garcw"><title>Parameters</title>
|
|
<table frame="topbot" id="garby"><title><function>ldap_create_proxyauth_control</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="30*"><colspec colnum="2"
|
|
colwidth="70*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>DN</literal></para></entry>
|
|
<entry>
|
|
<para>String representing the DN of the entry who's identity the client will
|
|
be assuming.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>ctl_iscritical</literal></para></entry>
|
|
<entry>
|
|
<para>Specifies whether the control is critical to the operation.</para>
|
|
<itemizedlist>
|
|
<listitem><para>If non-zero, the control is critical to the operation. If
|
|
the server does not support it, the server will return an <errorcode>LDAP_UNAVAILABLE_CRITICAL_EXTENSION
|
|
</errorcode> error.</para></listitem>
|
|
<listitem><para>If <literal>0</literal>, the control is not critical to the
|
|
operation. Even if the server does not support the control, the operation
|
|
is still attempted and the control is ignored.</para></listitem>
|
|
</itemizedlist>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>ctrlp</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdala">LDAPControl</olink> structure
|
|
created by this function. When you are done using this control, you should
|
|
free it by calling <olink targetptr="bdaqs">ldap_control_free</olink>.</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gardo"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if an invalid parameter
|
|
was passed to the function.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
|
|
allocated.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_ENCODING_ERROR</errorcode> if an error occurred
|
|
when BER-encoding the control.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_UNAVAILABLE_CRITICAL_EXTENSION</errorcode> if
|
|
the server does not support proxy authorization and <literal>ctl_iscritical</literal> is
|
|
set to a non-zero value.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="gardd"><title>See Also</title>
|
|
<para><olink targetptr="bdaqs">ldap_control_free</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdare"><title><function>ldap_create_sort_control</function></title>
|
|
<para>The <function>ldap_create_sort_control</function> function creates a
|
|
control that specifies the order in which you want search results returned.</para>
|
|
<note><para>This function implements an extension to the LDAP v3. Server-side
|
|
sorting is an optional feature; it may not be supported on all LDAP servers.
|
|
Call this function when interacting with LDAP servers that support this LDAP
|
|
v3 extension.</para></note>
|
|
<sect3 id="garcu"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_create_sort_control( LDAP *ld,
|
|
LDAPsortkey **sortKeyList, const char ctl_iscritical,
|
|
LDAPControl **ctrlp );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gardg"><title>Parameters</title>
|
|
<table frame="topbot" id="gardi"><title><function>ldap_create_sort_control</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="30*"><colspec colnum="2"
|
|
colwidth="70*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>sortKeyList</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an array of <olink targetptr="bdamc">LDAPsortkey</olink> structures
|
|
that specify the attribute types or matching rules used for sorting and the
|
|
order (ascending or descending) in which to sort the results.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>ctl_iscritical</literal></para></entry>
|
|
<entry>
|
|
<para>Specifies whether the control is critical to the operation.</para>
|
|
<itemizedlist>
|
|
<listitem><para>If non-zero, the control is critical to the operation. If
|
|
the server does not support it, the server will return an <errorcode>LDAP_UNAVAILABLE_CRITICAL_EXTENSION
|
|
</errorcode> error.</para></listitem>
|
|
<listitem><para>If <literal>0</literal>, the control is not critical to the
|
|
operation. Even if the server does not support the control, the operation
|
|
is still attempted and the control is ignored.</para></listitem>
|
|
</itemizedlist>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>ctrlp</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdala">LDAPControl</olink> structure
|
|
created by this function. When you are done using this control, you should
|
|
free it by calling <olink targetptr="bdaqs">ldap_control_free</olink>.</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gardf"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if an invalid parameter
|
|
was passed to the function.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
|
|
allocated.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_ENCODING_ERROR</errorcode> if an error occurred
|
|
when BER-encoding the control.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garce"><title>Description</title>
|
|
<para>The <function>ldap_create_sort_control</function> function allows you
|
|
to specify the order in which you want to receive data from the server. Calling
|
|
this function creates an LDAP control that you can pass to the <olink targetptr="bdauz">ldap_search_ext</olink> and <olink targetptr="bdava">ldap_search_ext_s
|
|
</olink> functions.</para>
|
|
<note><para>In order for the control to work, the LDAP server that you are
|
|
connecting to must support the server control for sorting search results (OID
|
|
1.2.840.113556.1.4.473, or <literal>LDAP_CONTROL_SORTREQUEST</literal>, as
|
|
defined in the <literal>ldap.h</literal> header file).</para></note>
|
|
<para>To specify the attributes to use for sorting the results, you can call <olink targetptr="bdarf">ldap_create_sort_keylist</olink> to create an array of <olink targetptr="bdamc">LDAPsortkey</olink> structures and pass the array as the
|
|
<literal>sortKeyList</literal> argument. When you are done with the search,
|
|
you should free the control and the array of <olink targetptr="bdamc">LDAPsortkey
|
|
</olink> structures by calling the <olink targetptr="bdaqs">ldap_control_free</olink> and
|
|
<olink targetptr="bdasg">ldap_free_sort_keylist</olink> functions.</para>
|
|
</sect3>
|
|
<sect3 id="gardp"><title>See Also</title>
|
|
<para><olink targetptr="bdarf">ldap_create_sort_keylist</olink>, <olink targetptr="bdauz">ldap_search_ext</olink>, <olink targetptr="bdava">ldap_search_ext_s
|
|
</olink>, <olink targetptr="bdaqs">ldap_control_free</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdarf"><title><function>ldap_create_sort_keylist</function></title>
|
|
<para>The <function>ldap_create_sort_keylist</function> function creates an
|
|
array of <olink targetptr="bdamc">LDAPsortkey</olink> structures from a string
|
|
representation of a set of sort keys.</para>
|
|
<sect3 id="garbs"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_create_sort_keylist(LDAPsortkey ***sortKeyList,
|
|
const char *string_rep);</programlisting>
|
|
</sect3>
|
|
<sect3 id="gardn"><title>Parameters</title>
|
|
<table frame="topbot" id="garcv"><title><function>ldap_create_sort_keylist</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>sortKeyList</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an array of <olink targetptr="bdamc">LDAPsortkey</olink> structures
|
|
that specify the attribute types or matching rules used for sorting and the
|
|
order (ascending or descending) in which to sort the results.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>string_rep</literal></para></entry>
|
|
<entry>
|
|
<para>String representation of a set of sort keys. The value should specify
|
|
the name of the attribute that you want to sort by. To sort in reverse order,
|
|
precede the attribute name with a hyphen, <literal>-</literal>. To use a matching
|
|
rule for sorting, append a colon to the attribute name and specify the object
|
|
identifier (OID) of a matching rule after the colon. For example:</para>
|
|
<orderedlist>
|
|
<listitem><para><literal>cn</literal> (sorts by the <literal>cn</literal> attribute)
|
|
</para></listitem>
|
|
<listitem><para><literal>-cn</literal> (sorts by the <literal>cn</literal> attribute
|
|
in reverse order)</para></listitem>
|
|
<listitem><para><literal>-cn:1.2.3.4</literal> (sorts by the <literal>cn</literal> attribute
|
|
in reverse order using the matching rule identified by the OID <literal>1.2.3.4</literal>)
|
|
</para></listitem>
|
|
</orderedlist>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garbu"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if an invalid parameter
|
|
was passed to the function.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
|
|
allocated.</para></listitem>
|
|
<listitem><para><literal>-1</literal> if an error occurred.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garda"><title>Description</title>
|
|
<para>Calling the <function>ldap_create_sort_keylist</function> function allows
|
|
you to create an array of <olink targetptr="bdamc">LDAPsortkey</olink> structures
|
|
from a string representation of a set of sort keys. You can then pass the
|
|
array to the <olink targetptr="bdare">ldap_create_sort_control</olink> function.
|
|
The string representation specified by the <literal>string_rep</literal> argument
|
|
should specify the name of the attribute that you want to sort by and how
|
|
the sort will work. When you are done sorting the results, you should free
|
|
the array of <olink targetptr="bdamc">LDAPsortkey</olink> structures by calling
|
|
the <olink targetptr="bdasg">ldap_free_sort_keylist</olink> function.</para>
|
|
</sect3>
|
|
<sect3 id="garbw"><title>See Also</title>
|
|
<para><olink targetptr="bdare">ldap_create_sort_control</olink>, <olink targetptr="bdasg">ldap_free_sort_keylist</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="ldap-create-userstatus-control"><title><function>ldap_create_userstatus_control
|
|
</function></title>
|
|
<para>The <function>ldap_create_userstatus_control</function> function creates
|
|
a control that requests information about the status of a user account.</para>
|
|
<note><para><function>ldap_create_userstatus_control</function> implements
|
|
an extension to the LDAP v3 supported by &cnDirectoryServer;.</para><para>In
|
|
order for the control to work, the LDAP server that you are connecting to
|
|
must support the server control for account availability (OID <literal>1.3.6.1.4.1.42.2.27.9.5.8
|
|
</literal>, or <literal>LDAP_CONTROL_ACCOUNT_USABLE</literal>).</para></note>
|
|
<para>Calling <function>ldap_create_userstatus_control</function> creates
|
|
an LDAP control that you can pass to the <olink targetptr="bdauz">ldap_search_ext
|
|
</olink> and <olink targetptr="bdava">ldap_search_ext_s</olink> functions.
|
|
You call <olink targetptr="ldap-parse-userstatus-control">ldap_parse_userstatus_control
|
|
</olink> function on the controls returned with an entry to retrieve a <olink targetptr="ldapuserstatus">LDAPuserstatus</olink> structure containing information
|
|
about the status of the account.</para>
|
|
<para>When you are done with the search, you should free the control by calling
|
|
the <olink targetptr="bdaqs">ldap_control_free</olink> function.</para>
|
|
<sect3><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
LDAP_API(int) LDAP_CALL ldap_create_userstatus_control( LDAP *ld,
|
|
const char ctl_iscritical, LDAPControl **ctrlp );</programlisting>
|
|
</sect3>
|
|
<sect3><title>Parameters</title>
|
|
<table frame="topbot" id="gbgbt"><title><function>ldap_create_userstatus_control</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2" colsep="0" rowsep="0"><colspec colwidth="50*"><colspec
|
|
colwidth="50*">
|
|
<thead>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>
|
|
<para><parameter>ld</parameter></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><parameter>ctl_iscritical</parameter></para></entry>
|
|
<entry>
|
|
<para>Specifies whether the control is critical to the operation.</para>
|
|
<itemizedlist>
|
|
<listitem><para>If non-zero, the control is critical to the operation. If
|
|
the server does not support it, the server returns an <errorcode>LDAP_UNAVAILABLE_CRITICAL_EXTENSION
|
|
</errorcode> error.</para></listitem>
|
|
<listitem><para>If <literal>0</literal>, the control is not critical to the
|
|
operation. Even if the server does not support the control, the operation
|
|
is still attempted and the control is ignored.</para></listitem>
|
|
</itemizedlist>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><parameter>ctrlp</parameter></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdala">LDAPControl</olink> structure
|
|
created by this function. When you are done using this control, you should
|
|
free it by calling <olink targetptr="bdaqs">ldap_control_free</olink>.</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if an invalid parameter
|
|
was passed to the function.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
|
|
allocated.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_ENCODING_ERROR</errorcode> if an error occurred
|
|
when BER-encoding the control.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3><title>See Also</title>
|
|
<para><olink targetptr="ldap-parse-userstatus-control">ldap_parse_userstatus_control
|
|
</olink>, <olink targetptr="ldapuserstatus">LDAPuserstatus</olink></para>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="bdarg"><title><function>ldap_create_virtuallist_control</function></title>
|
|
<para>The <function>ldap_create_virtuallist_control</function> function creates
|
|
a control that requests a subset of search results for use in a virtual list
|
|
box.</para>
|
|
<note><para><function>ldap_create_virtuallist_control</function> implements
|
|
an extension to the LDAP v3 supported by &cnDirectoryServer;.</para></note>
|
|
<sect3 id="garbx"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_create_virtuallist_control( LDAP *ld,
|
|
LDAPVirtualList *ldvlistp, LDAPControl **ctrlp );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garde"><title>Parameters</title>
|
|
<table frame="topbot" id="garci"><title><function>ldap_create_virtuallist_control
|
|
</function> Function Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>ldvlistp</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdamv">LDAPVirtualList</olink> structure
|
|
that specifies the subset of entries that you want retrieved from the server
|
|
and the selected entry.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>ctrlp</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdala">LDAPControl</olink> structure
|
|
created by this function. When you are done using this control, you should
|
|
free it by calling <olink targetptr="bdaqs">ldap_control_free</olink>.</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garbz"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if an invalid parameter
|
|
was passed to the function.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
|
|
allocated.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_ENCODING_ERROR</errorcode> if an error occurred
|
|
when BER-encoding the control.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garco"><title>Description</title>
|
|
<para>The <function>ldap_create_virtuallist_control</function> function allows
|
|
you to retrieve a subset of entries from the server for use in a virtual list
|
|
box. To specify the subset of entries that you want to retrieve, create an
|
|
<olink targetptr="bdamv">LDAPVirtualList</olink> structure and pass in a
|
|
pointer to this structure as the <literal>ldvlistp</literal> argument.</para>
|
|
<note><para>In order for the control to work, the LDAP server that you are
|
|
connecting to must support the server control for sorting search results (OID
|
|
2.16.840.1.113730.3.4.9, or <literal>LDAP_CONTROL_VLVREQUEST</literal>, as
|
|
defined in the <literal>ldap.h</literal> header file).</para></note>
|
|
<para>Calling <function>ldap_create_virtuallist_control</function> creates
|
|
an LDAP control that you can pass to the <olink targetptr="bdauz">ldap_search_ext
|
|
</olink> and <olink targetptr="bdava">ldap_search_ext_s</olink> functions.
|
|
You also need to pass a server-side sorting control to the search functions.
|
|
You can call <olink targetptr="bdarf">ldap_create_sort_keylist</olink> and <olink targetptr="bdare">ldap_create_sort_control</olink> to create a server-side
|
|
sorting control. When you are done with the search, you should free the control
|
|
by calling the <olink targetptr="bdaqs">ldap_control_free</olink> function.</para>
|
|
</sect3>
|
|
<sect3 id="garcd"><title>See Also</title>
|
|
<para><olink targetptr="bdamv">LDAPVirtualList</olink>, <olink targetptr="bdauq">
|
|
ldap_parse_virtuallist_control</olink>, <olink targetptr="bdauz">ldap_search_ext</olink> , <olink targetptr="bdava">ldap_search_ext_s</olink>, <olink targetptr="bdaqs">ldap_control_free
|
|
</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdarh"><title><function>ldap_delete</function></title>
|
|
<para>The <function>ldap_delete</function> function removes an entry from
|
|
the directory asynchronously.</para>
|
|
<note><para>This is an older function that is included in the SDK for backward-compatibility.
|
|
If you are writing a new LDAP client, use <olink targetptr="bdari">ldap_delete_ext
|
|
</olink> instead.</para></note>
|
|
<sect3 id="garbv"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_delete( LDAP *ld, const char *dn );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garcf"><title>Parameters</title>
|
|
<table frame="topbot" id="garcb"><title><function>ldap_delete</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>dn</literal></para></entry>
|
|
<entry>
|
|
<para>DN of the entry to remove.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garcq"><title>Returns</title>
|
|
<para>Returns the message ID of the <function>ldap_delete</function> operation.</para>
|
|
<note><para>To check the result of this operation, call <olink targetptr="bdauu">
|
|
ldap_result</olink> and <olink targetptr="bdauv">ldap_result2error</olink>.
|
|
See <olink targetptr="bdarj">ldap_delete_ext_s</olink> for a list of possible
|
|
result codes for the LDAP delete operation.</para></note>
|
|
</sect3>
|
|
<sect3 id="gardc"><title>Description</title>
|
|
<para>Please use the newer version of this function, <olink targetptr="bdari">ldap_delete_ext
|
|
</olink> .</para></sect3>
|
|
<sect3 id="garch"><title>Example</title>
|
|
<para><olink targetptr="ldap-delete-example">Example 21–11</olink> uses
|
|
the asynchronous <function>ldap_delete</function> function to remove the entry
|
|
for <literal>Barbara Jensen</literal> from the directory.</para>
|
|
<example id="ldap-delete-example"><title>Using <function>ldap_delete</function></title>
|
|
<programlisting>#include <ldap.h>
|
|
...
|
|
LDAP *ld;
|
|
LDAPMessage *result;
|
|
int msgid, rc;
|
|
struct timeval tv;
|
|
|
|
/* Distinguished name of the entry that you want to delete. */
|
|
char *dn = "uid=bjensen,ou=People,dc=example, dc=com";
|
|
...
|
|
/* Set up the timeout period to wait for the "modify" operation */
|
|
tv.tv_sec = tv.tv_usec = 0;
|
|
|
|
/* Delete the entry */
|
|
if ( ( msgid = ldap_delete( ld, dn ) ) == -1 ) {
|
|
ldap_perror( ld, "ldap_delete" );
|
|
return( 1 );
|
|
}
|
|
/* Check to see if the operation has completed */
|
|
while ( ( rc = ldap_result( ld, msgid, 0, &tv, &result ) ) == 0 ) {
|
|
...
|
|
/* do other work while waiting for the operation to complete */
|
|
...
|
|
}
|
|
/* Check the result to see if any errors occurred */
|
|
ldap_result2error( ld, result, 1 );
|
|
ldap_perror( ld, "ldap_delete" );
|
|
...</programlisting>
|
|
</example>
|
|
</sect3>
|
|
<sect3 id="garcg"><title>See Also</title>
|
|
<para><olink targetptr="bdari">ldap_delete_ext</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdari"><title><function>ldap_delete_ext</function></title>
|
|
<para>The <function>ldap_delete_ext</function> function deletes an entry from
|
|
the directory asynchronously.</para>
|
|
<note><para><function>ldap_delete_ext</function> is a new version of the <olink targetptr="bdarh">ldap_delete</olink> function. If you are writing a new LDAP
|
|
client, you should call <olink targetptr="bdari">ldap_delete_ext</olink>.</para>
|
|
</note>
|
|
<sect3 id="garcs"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_delete_ext( LDAP *ld, const char *dn,
|
|
LDAPControl **serverctrls, LDAPControl **clientctrls, int *msgidp );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garck"><title>Parameters</title>
|
|
<table frame="topbot" id="gardb"><title><function>ldap_delete_ext</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>dn</literal></para></entry>
|
|
<entry>
|
|
<para>DN of the entry to remove.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>serverctrls</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
|
|
representing LDAP server controls that apply to this operation. If you do
|
|
not want to pass any server controls, specify <literal>NULL</literal> for
|
|
this argument.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>clientctrls</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
|
|
representing LDAP client controls that apply to this operation. If you do
|
|
not want to pass any client controls, specify <literal>NULL</literal> for
|
|
this argument.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>msgidp</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an integer that will be set to the message ID of the LDAP
|
|
operation.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garcx"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if an invalid parameter
|
|
was passed to the function.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
|
|
allocated.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_ENCODING_ERROR</errorcode> if an error occurred
|
|
when BER-encoding the control.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_SERVER_DOWN</errorcode> if the LDAP server
|
|
did not receive the request or if the connection to the server was lost.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_NOT_SUPPORTED</errorcode> if controls are
|
|
included in your request (for example, as a session preference) and your LDAP
|
|
client does not specify that it is using the LDAP v3. Make sure that you set
|
|
the version of your LDAP client to version 3 before calling this function.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<note><para>To check the result of this operation, call <olink targetptr="bdauu">
|
|
ldap_result</olink> and <olink targetptr="bdauv">ldap_result2error</olink>.
|
|
See <olink targetptr="bdarj">ldap_delete_ext_s</olink> for a list of possible
|
|
result codes for the LDAP delete operation.</para></note>
|
|
</sect3>
|
|
<sect3 id="garcn"><title>Description</title>
|
|
<para>The <function>ldap_delete_ext</function> function deletes an entry from
|
|
the directory, using the <literal>dn</literal> argument to specify the entry
|
|
that you want to delete. <function>ldap_delete_ext</function> is an asynchronous
|
|
function; it does not directly return results. If you want the results to
|
|
be returned directly by the function, call the synchronous function <olink targetptr="bdarj">ldap_delete_ext_s</olink> .</para></sect3>
|
|
<sect3 id="garbt"><title>See Also</title>
|
|
<para><olink targetptr="bdarj">ldap_delete_ext_s</olink>, <olink targetptr="bdauu">ldap_result</olink>, <olink targetptr="bdaun">ldap_parse_result
|
|
</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdarj"><title><function>ldap_delete_ext_s</function></title>
|
|
<para>The <function>ldap_delete_ext_s</function> function deletes an entry
|
|
from the directory synchronously.</para>
|
|
<note><para><function>ldap_delete_ext_s</function> is a new version of the <olink targetptr="bdark">ldap_delete_s</olink> function. If you are writing a new
|
|
LDAP client, you should call <function>ldap_delete_ext_s</function>.</para>
|
|
</note>
|
|
<sect3 id="gardj"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_delete_ext_s( LDAP *ld, const char *dn,
|
|
LDAPControl **serverctrls, LDAPControl **clientctrls );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gardk"><title>Parameters</title>
|
|
<table frame="topbot" id="garct"><title><function>ldap_delete_ext_s</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>dn</literal></para></entry>
|
|
<entry>
|
|
<para>DN of the entry to remove.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>serverctrls</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
|
|
representing LDAP server controls that apply to this operation. If you do
|
|
not want to pass any server controls, specify <literal>NULL</literal> for
|
|
this argument.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>clientctrls</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
|
|
representing LDAP client controls that apply to this operation. If you do
|
|
not want to pass any client controls, specify <literal>NULL</literal> for
|
|
this argument.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garca"><title>Returns</title>
|
|
<para>One of the following values:</para></sect3>
|
|
<sect3 id="garcr"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if an invalid parameter
|
|
was passed to the function.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
|
|
allocated.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_ENCODING_ERROR</errorcode> if an error occurred
|
|
when BER-encoding the control.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_SERVER_DOWN</errorcode> if the LDAP server
|
|
did not receive the request or if the connection to the server was lost.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_NOT_SUPPORTED</errorcode> if controls are
|
|
included in your request (for example, as a session preference) and your LDAP
|
|
client does not specify that it is using the LDAP v3. Make sure that you set
|
|
the version of your LDAP client to version 3 before calling this function.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_LOCAL_ERROR</errorcode> if an error occurred
|
|
when receiving the results from the server.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_DECODING_ERROR</errorcode> if an error occurred
|
|
when decoding the BER-encoded results from the server.</para></listitem>
|
|
</itemizedlist>
|
|
<note><para>&cnDirectoryServer; and other LDAP server products may send result
|
|
codes in addition to those described. For example, the server may have loaded
|
|
a plug-in that returns custom result codes. Check your LDAP server documentation
|
|
for other result codes.</para></note>
|
|
</sect3>
|
|
<sect3 id="garcc"><title>Description</title>
|
|
<para>The <function>ldap_delete_ext_s</function> function deletes an entry
|
|
from the directory, using the <literal>dn</literal> argument to specify the
|
|
entry that you want to delete. <function>ldap_delete_ext_s</function> is a
|
|
synchronous function, which directly returns the results of the operation.
|
|
If you want to perform other operations while waiting for the results of this
|
|
operation, call the asynchronous function <olink targetptr="bdari">ldap_delete_ext
|
|
</olink> instead.</para></sect3>
|
|
<sect3 id="garcy"><title>See Also</title>
|
|
<para><olink targetptr="bdari">ldap_delete_ext</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdark"><title><function>ldap_delete_s</function></title>
|
|
<para>The <function>ldap_delete_s</function> deletes an entry from the directory
|
|
synchronously.</para>
|
|
<note><para>This is an older function that is included in the SDK for backward-compatibility.
|
|
If you are writing a new LDAP client, use <olink targetptr="bdarj">ldap_delete_ext_s
|
|
</olink> instead.</para></note>
|
|
<sect3 id="garcj"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_delete_s(LDAP *ld, const char *dn);</programlisting>
|
|
</sect3>
|
|
<sect3 id="garcm"><title>Parameters</title>
|
|
<table frame="topbot" id="gareg"><title><function>ldap_delete_s</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameters</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>dn</literal></para></entry>
|
|
<entry>
|
|
<para>DN of the entry to remove.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garfc"><title>Returns</title>
|
|
<para>For a list of possible result codes for an LDAP delete operation, see
|
|
the <olink targetptr="bdarj">ldap_delete_ext_s</olink> function.</para></sect3>
|
|
<sect3 id="garfj"><title>Description</title>
|
|
<para>Please use the newer version of this function, <olink targetptr="bdarj">ldap_delete_ext_s
|
|
</olink> .</para></sect3>
|
|
<sect3 id="garex"><title>Example</title>
|
|
<para><olink targetptr="ldap-delete-s-example">Example 21–12</olink> uses
|
|
the synchronous <function>ldap_delete_s</function> function to delete the
|
|
entry for <literal>Barbara Jensen</literal> from the directory.</para>
|
|
<example id="ldap-delete-s-example"><title>Using <function>ldap_delete_s</function></title>
|
|
<programlisting>#include <ldap.h>
|
|
LDAP *ld;
|
|
|
|
/* Distinguished name of the entry that you want to delete. */
|
|
char *dn = "uid=bjensen,ou=People,dc=example, dc=com";
|
|
...
|
|
/* Delete the entry */
|
|
if ( ldap_delete_s( ld, dn ) != LDAP_SUCCESS ) {
|
|
ldap_perror( ld, "ldap_delete_s" );
|
|
return( 1 );
|
|
}
|
|
...</programlisting>
|
|
</example>
|
|
</sect3>
|
|
<sect3 id="garfg"><title>See Also</title>
|
|
<para><olink targetptr="bdarj">ldap_delete_ext_s</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdarl"><title><function>ldap_dn2ufn</function></title>
|
|
<para>The <function>ldap_dn2ufn</function> function converts a DN into a more
|
|
user-friendly form by stripping off the cryptic type names.</para>
|
|
<sect3 id="garet"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
char * ldap_dn2ufn( const char *dn );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garfd"><title>Parameters</title>
|
|
<table frame="topbot" id="garei"><title><function>ldap_dn2ufn</function> Function
|
|
Parameter</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>dn</literal></para></entry>
|
|
<entry>
|
|
<para>The DN that you want converted.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garer"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para>If successful, returns the DN in its friendlier form.</para>
|
|
</listitem>
|
|
<listitem><para>If unsuccessful, returns <literal>NULL</literal>.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garew"><title>Description</title>
|
|
<para>For more information on user friendly naming (UFN), see RFC 1781,<citetitle>
|
|
Using the OSI Directory to Achieve User Friendly Naming </citetitle> (<ulink
|
|
url="http://www.faqs.org/rfcs/rfc1781.html" type="text_url"></ulink>).</para>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="bdarm"><title><function>ldap_entry2html</function></title>
|
|
<para>The <function>ldap_entry2html</function> function writes the HTML representation
|
|
of an LDAP entry.</para>
|
|
<sect3 id="garek"><title>Syntax</title>
|
|
<programlisting>#include <disptmpl.h>
|
|
int ldap_entry2html( LDAP *ld, char *buf, LDAPMessage *entry,
|
|
struct ldap_disptmpl *tmpl, char **defattrs, char ***defvals,
|
|
writeptype writeproc, void *writeparm, char *eol, int rdncount,
|
|
unsigned long opts, char *urlprefix, char *base );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garef"><title>Parameters</title>
|
|
<table frame="topbot" id="garfi"><title><function>ldap_entry2html</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>buf</literal></para></entry>
|
|
<entry>
|
|
<para>A pointer to a buffer of size <literal>LDAP_DTMPL_BUFSIZ</literal> or
|
|
larger. If <literal>NULL</literal>, a buffer is allocated and freed internally.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>entry</literal></para></entry>
|
|
<entry>
|
|
<para>Specifies the attribute values to be represented.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>tmpl</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to the display template to be used, usually obtained by calling <olink targetptr="bdaui">ldap_oc2template</olink>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>defattrs</literal></para></entry>
|
|
<entry>
|
|
<para>A <literal>NULL</literal> terminated array of LDAP attribute names for
|
|
which you wish to provide default values. It is only used if the entry contains
|
|
no values for the attribute.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>defvals</literal></para></entry>
|
|
<entry>
|
|
<para>An array of <literal>NULL</literal> terminated arrays of default values
|
|
corresponding to the attributes.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>writeproc</literal></para></entry>
|
|
<entry>
|
|
<para>Your <function>writeproc</function> function should be declared as:</para>
|
|
<para><literal>int writeproc( writeparm, p, len )</literal></para>
|
|
<para><literal>void *writeparm;</literal></para>
|
|
<para><literal>char *p;</literal></para>
|
|
<para><literal>int len;</literal></para>
|
|
<para>where <literal>p</literal> is a pointer to text to be written and <literal>
|
|
len</literal> is the length of the text. <parameter>p</parameter> is guaranteed
|
|
to be zero terminated.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>writeparm</literal></para></entry>
|
|
<entry>
|
|
<para>A pointer to a structure that will be passed as the first parameter
|
|
of the <function>writeproc</function> procedure. Typically, this is used to
|
|
pass the file descriptor of the file to write to.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>eol</literal></para></entry>
|
|
<entry>
|
|
<para>Lines of text are terminated with this string.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>rdncount</literal></para></entry>
|
|
<entry>
|
|
<para>Limits the number of components that are displayed for DN attributes.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>opts</literal></para></entry>
|
|
<entry>
|
|
<para>Specifies output options. The allowed values are:</para>
|
|
<itemizedlist>
|
|
<listitem><para>zero (default output)</para></listitem>
|
|
<listitem><para><literal>LDAP_DISP_OPT_AUTOLABELWIDTH</literal> which causes
|
|
the width for labels to be determined based on the longest label in <literal>tmpl
|
|
</literal>.</para></listitem>
|
|
<listitem><para><literal>LDAP_DISP_OPT_HTMLBODYONLY</literal> which instructs
|
|
the library not to include <literal><HTML></literal>, <literal><HEAD></literal>,
|
|
<literal><TITLE></literal>, and <literal><BODY></literal> tags. In
|
|
other words, an HTML fragment is generated, and the caller is responsible
|
|
for prepending and appending the appropriate HTML tags to construct a correct
|
|
HTML document.</para></listitem>
|
|
</itemizedlist>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>urlprefix</literal></para></entry>
|
|
<entry>
|
|
<para>Starting text to use when constructing an LDAP URL. The default is
|
|
the string <literal>ldap://</literal>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>base</literal></para></entry>
|
|
<entry>
|
|
<para>The base with which to begin when executing search actions. If <literal>NULL
|
|
</literal> , search action template items are ignored.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gards"><title>Returns</title>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para>An LDAP error code on error.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="gardt"><title>Description</title>
|
|
<para><function>ldap_entry2html</function> produces an HTML representation
|
|
of an entry. It behaves exactly like <olink targetptr="bdaro">ldap_entry2text</olink> except
|
|
for the output and the addition of two parameters.</para></sect3>
|
|
<sect3 id="garfa"><title>See Also</title>
|
|
<para><olink targetptr="bdaro">ldap_entry2text</olink>, <olink targetptr="bdaui">
|
|
ldap_oc2template</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdarn"><title><function>ldap_entry2html_search</function></title>
|
|
<para>The <function>ldap_entry2html_search</function> function determines
|
|
the appropriate display template to use by calling <olink targetptr="bdaui">ldap_oc2template
|
|
</olink>.</para>
|
|
<sect3 id="gareb"><title>Syntax</title>
|
|
<programlisting>#include <disptmpl.h>
|
|
int ldap_entry2html_search( LDAP *ld, char *dn, char *base,
|
|
LDAPMessage *entry, struct ldap_disptmpl *tmpllist, char **defattrs,
|
|
char ***defvals, writeptype writeproc, void *writeparm, char *eol,
|
|
int rdncount, unsigned long opts, char *urlprefix );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garez"><title>Parameters</title>
|
|
<table frame="topbot" id="garem"><title><function>ldap_entry2html_search</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>dn</literal></para></entry>
|
|
<entry>
|
|
<para>DN of the entry to write as HTML.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>base</literal></para></entry>
|
|
<entry>
|
|
<para>The base with which to begin when executing search actions. If <literal>NULL
|
|
</literal> , search action template items are ignored.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>entry</literal></para></entry>
|
|
<entry>
|
|
<para>Specifies the attribute values to be represented.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>tmpllist</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to the entire list of templates available, usually obtained
|
|
by calling <olink targetptr="bdata">ldap_init_templates</olink> or <olink targetptr="bdatb">ldap_init_templates_buf</olink>. If <literal>NULL</literal>,
|
|
will attempt to read a load templates from the default template configuration
|
|
file.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>defattrs</literal></para></entry>
|
|
<entry>
|
|
<para>A <literal>NULL</literal> terminated array of LDAP attribute names for
|
|
which you wish to provide default values. It is only used if the entry contains
|
|
no values for the attribute.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>defvals</literal></para></entry>
|
|
<entry>
|
|
<para>An array of <literal>NULL</literal> terminated arrays of default values
|
|
corresponding to the attributes.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>writeproc</literal></para></entry>
|
|
<entry>
|
|
<para><function>writeproc</function> function should be declared as:</para>
|
|
<para><literal>int writeproc( writeparm, p, len )</literal></para>
|
|
<para><literal>void *writeparm;</literal></para>
|
|
<para><literal>char *p;</literal></para>
|
|
<para><literal>int len;</literal></para>
|
|
<para>where <literal>p</literal> is a pointer to text to be written and <literal>
|
|
len</literal> is the length of the text. <parameter>p</parameter> is guaranteed
|
|
to be zero terminated.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>writeparm</literal></para></entry>
|
|
<entry>
|
|
<para>A pointer to a structure that will be passed as the first parameter
|
|
of the <function>writeproc</function> procedure. Typically, this is used to
|
|
pass the file descriptor of the file to write to.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>eol</literal></para></entry>
|
|
<entry>
|
|
<para>Lines of text are terminated with this string.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>rdncount</literal></para></entry>
|
|
<entry>
|
|
<para>Limits the number of components that are displayed for DN attributes.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>opts</literal></para></entry>
|
|
<entry>
|
|
<para>Specifies output options. The allowed values are:</para>
|
|
<itemizedlist>
|
|
<listitem><para>zero (default output)</para></listitem>
|
|
<listitem><para><literal>LDAP_DISP_OPT_AUTOLABELWIDTH</literal> which causes
|
|
the width for labels to be determined based on the longest label in <literal>tmpl
|
|
</literal>.</para></listitem>
|
|
<listitem><para><literal>LDAP_DISP_OPT_HTMLBODYONLY</literal> which instructs
|
|
the library not to include <literal><HTML></literal>, <literal><HEAD></literal>,
|
|
<literal><TITLE></literal>, and <literal><BODY></literal> tags. In
|
|
other words, an HTML fragment is generated, and the caller is responsible
|
|
for prepending and appending the appropriate HTML tags to construct a correct
|
|
HTML document.</para></listitem>
|
|
</itemizedlist>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>urlprefix</literal></para></entry>
|
|
<entry>
|
|
<para>Starting text to use when constructing an LDAP URL. The default
|
|
is the string <literal>ldap://</literal></para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gares"><title>Returns</title>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para>An LDAP error code on error.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garfn"><title>Description</title>
|
|
<para><function>ldap_entry2html_search</function> will call <olink targetptr="bdavb">ldap_search_s</olink> to retrieve any attribute values to
|
|
be displayed. It behaves exactly like <olink targetptr="bdarp">ldap_entry2text_search
|
|
</olink>, except the <literal>urlprefix</literal> parameter is required and
|
|
HTML is the output.</para></sect3>
|
|
<sect3 id="gardu"><title>See Also</title>
|
|
<para><olink targetptr="bdavb">ldap_search_s</olink>, <olink targetptr="bdarp">ldap_entry2text_search
|
|
</olink>, <olink targetptr="bdata">ldap_init_templates</olink>, <olink targetptr="bdatb">ldap_init_templates_buf</olink>, <olink targetptr="bdaro">ldap_entry2text
|
|
</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaro"><title><function>ldap_entry2text</function></title>
|
|
<para>The <function>ldap_entry2text</function> function writes the text representation
|
|
of an LDAP entry.</para>
|
|
<sect3 id="gardz"><title>Syntax</title>
|
|
<programlisting>#include <disptmpl.h>
|
|
int ldap_entry2text( LDAP *ld, char *buf, LDAPMessage *entry,
|
|
struct ldap_disptmpl *tmpl, char **defattrs, char ***defvals,
|
|
writeptype writeproc, void *writeparm, char *eol, int rdncount,
|
|
unsigned long opts );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garfb"><title>Parameters</title>
|
|
<table frame="topbot" id="gardw"><title><function>ldap_entry2text</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>buf</literal></para></entry>
|
|
<entry>
|
|
<para>A pointer to a buffer of size <literal>LDAP_DTMPL_BUFSIZ</literal> or
|
|
larger. If <literal>NULL</literal>, a buffer is allocated and freed internally.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>entry</literal></para></entry>
|
|
<entry>
|
|
<para>Specifies the attribute values to be represented.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>tmpl</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to the display template to be used, usually obtained by calling <olink targetptr="bdaui">ldap_oc2template</olink>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>defattrs</literal></para></entry>
|
|
<entry>
|
|
<para>A <literal>NULL</literal> terminated array of LDAP attribute names for
|
|
which you wish to provide default values. It is only used if the entry contains
|
|
no values for the attribute.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>defvals</literal></para></entry>
|
|
<entry>
|
|
<para>An array of <literal>NULL</literal> terminated arrays of default values
|
|
corresponding to the attributes.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>writeproc</literal></para></entry>
|
|
<entry>
|
|
<para><function>writeproc</function> function should be declared as:</para>
|
|
<para><literal>int writeproc( writeparm, p, len )</literal></para>
|
|
<para><literal>void *writeparm;</literal></para>
|
|
<para><literal>char *p;</literal></para>
|
|
<para><literal>int len;</literal></para>
|
|
<para>where <literal>p</literal> is a pointer to text to be written and <literal>
|
|
len</literal> is the length of the text. <parameter>p</parameter> is guaranteed
|
|
to be zero terminated.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>writeparm</literal></para></entry>
|
|
<entry>
|
|
<para>A pointer to a structure that will be passed as the first parameter
|
|
of the <function>writeproc</function> procedure. Typically, this is used to
|
|
pass the file descriptor of the file to write to.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>eol</literal></para></entry>
|
|
<entry>
|
|
<para>Lines of text are terminated with this string.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>rdncount</literal></para></entry>
|
|
<entry>
|
|
<para>Limits the number of components that are displayed for DN attributes.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>opts</literal></para></entry>
|
|
<entry>
|
|
<para>Specifies output options. The allowed values are:</para>
|
|
<itemizedlist>
|
|
<listitem><para>zero (default output)</para></listitem>
|
|
<listitem><para><literal>LDAP_DISP_OPT_AUTOLABELWIDTH</literal> which causes
|
|
the width for labels to be determined based on the longest label in <literal>tmpl
|
|
</literal>.</para></listitem>
|
|
<listitem><para><literal>LDAP_DISP_OPT_HTMLBODYONLY</literal> which instructs
|
|
the library not to include <literal><HTML></literal>, <literal><HEAD></literal>,
|
|
<literal><TITLE></literal>, and <literal><BODY></literal> tags. In
|
|
other words, an HTML fragment is generated, and the caller is responsible
|
|
for prepending and appending the appropriate HTML tags to construct a correct
|
|
HTML document.</para></listitem>
|
|
</itemizedlist>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garfh"><title>Returns</title>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para>An LDAP error code on error.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="gared"><title>Description</title>
|
|
<para><function>ldap_entry2text</function> produces a text representation
|
|
of an entry and writes the text by calling the <literal>writeproc</literal> function.
|
|
All of the attribute values to be displayed must be present in entry as no
|
|
interaction with the LDAP server will be performed.</para></sect3>
|
|
<sect3 id="garfl"><title>See Also</title>
|
|
<para><olink targetptr="bdarm">ldap_entry2html</olink>, <olink targetptr="bdaui">
|
|
ldap_oc2template</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdarp"><title><function>ldap_entry2text_search</function></title>
|
|
<para>The <function>ldap_entry2text_search</function> function determines
|
|
the appropriate display template to use by calling <olink targetptr="bdaui">ldap_oc2template
|
|
</olink>.</para>
|
|
<sect3 id="garec"><title>Syntax</title>
|
|
<programlisting>#include <disptmpl.h>
|
|
int ldap_entry2text_search( LDAP *ld, char *dn, char *base,
|
|
LDAPMessage *entry, struct ldap_disptmpl *tmpllist, char **defattrs,
|
|
char ***defvals, writeptype writeproc, void *writeparm,
|
|
char *eol, int rdncount, unsigned long opts );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gardy"><title>Parameters</title>
|
|
<table frame="topbot" id="gareu"><title><function>ldap_entry2text_search</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>dn</literal></para></entry>
|
|
<entry>
|
|
<para>DN of the entry to write.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>base</literal></para></entry>
|
|
<entry>
|
|
<para>If <literal>NULL</literal>, the search action template items are ignored.
|
|
If not <literal>NULL</literal>, it is the search base to use when executing
|
|
search actions.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>entry</literal></para></entry>
|
|
<entry>
|
|
<para>If entry is not <literal>NULL</literal>, it should contain the <literal>objectClass
|
|
</literal> attribute values for the entry to be displayed. If <literal>NULL</literal>, <parameter>
|
|
dn</parameter> can not be <literal>NULL</literal>, and <olink targetptr="bdarp">ldap_entry2text_search
|
|
</olink> will retrieve the <literal>objectClass</literal> values itself by
|
|
calling <olink targetptr="bdavb">ldap_search_s</olink>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>tmpllist</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to the entire list of templates available, usually obtained
|
|
by calling <olink targetptr="bdata">ldap_init_templates</olink> or <olink targetptr="bdatb">ldap_init_templates_buf</olink>. If <literal>NULL</literal>,
|
|
will attempt to read a load templates from the default template configuration
|
|
file.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>defattrs</literal></para></entry>
|
|
<entry>
|
|
<para>A <literal>NULL</literal> terminated array of LDAP attribute names for
|
|
which you wish to provide default values. It is only used if the entry contains
|
|
no values for the attribute.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>defvals</literal></para></entry>
|
|
<entry>
|
|
<para>An array of <literal>NULL</literal> terminated arrays of default values
|
|
corresponding to the attributes.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>writeproc</literal></para></entry>
|
|
<entry>
|
|
<para><function>writeproc</function> function should be declared as:</para>
|
|
<para><literal>int writeproc( writeparm, p, len )</literal></para>
|
|
<para><literal>void *writeparm;</literal></para>
|
|
<para><literal>char *p;</literal></para>
|
|
<para><literal>int len;</literal></para>
|
|
<para>where <literal>p</literal> is a pointer to text to be written and <literal>
|
|
len</literal> is the length of the text. <parameter>p</parameter> is guaranteed
|
|
to be zero terminated.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>writeparm</literal></para></entry>
|
|
<entry>
|
|
<para>A pointer to a structure that will be passed as the first parameter
|
|
of the <function>writeproc</function> procedure. Typically, this is used to
|
|
pass the file descriptor of the file to write to.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>eol</literal></para></entry>
|
|
<entry>
|
|
<para>Lines of text are terminated with this string.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>rdncount</literal></para></entry>
|
|
<entry>
|
|
<para>Limits the number of components that are displayed for DN attributes.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>opts</literal></para></entry>
|
|
<entry>
|
|
<para>Specifies output options. The allowed values are:</para>
|
|
<itemizedlist>
|
|
<listitem><para>zero (default output)</para></listitem>
|
|
<listitem><para><literal>LDAP_DISP_OPT_AUTOLABELWIDTH</literal> which causes
|
|
the width for labels to be determined based on the longest label in <literal>tmpl
|
|
</literal>.</para></listitem>
|
|
<listitem><para><literal>LDAP_DISP_OPT_HTMLBODYONLY</literal> which instructs
|
|
the library not to include <literal><HTML></literal>, <literal><HEAD></literal>,
|
|
<literal><TITLE></literal>, and <literal><BODY></literal> tags. In
|
|
other words, an HTML fragment is generated, and the caller is responsible
|
|
for prepending and appending the appropriate HTML tags to construct a correct
|
|
HTML document.</para></listitem>
|
|
</itemizedlist>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garen"><title>Returns</title>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para>An LDAP error code on error.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garey"><title>Description</title>
|
|
<para><function>ldap_entry2text_search</function> will call <olink targetptr="bdavb">ldap_search_s</olink> to retrieve any attribute values to
|
|
be displayed.</para></sect3>
|
|
<sect3 id="gareh"><title>See Also</title>
|
|
<para><olink targetptr="bdarn">ldap_entry2html_search</olink>, <olink targetptr="bdaui">ldap_oc2template</olink>, <olink targetptr="bdavb">ldap_search_s
|
|
</olink>, <olink targetptr="bdata">ldap_init_templates</olink>, <olink targetptr="bdatb">ldap_init_templates_buf</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdarq"><title><function>ldap_err2string</function></title>
|
|
<para>The <function>ldap_err2string</function> function returns the corresponding
|
|
error message for an error code.</para>
|
|
<sect3 id="garep"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
char * ldap_err2string( int err );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gardq"><title>Parameters</title>
|
|
<table frame="topbot" id="garff"><title><function>ldap_err2string</function> Function
|
|
Parameter</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>err</literal></para></entry>
|
|
<entry>
|
|
<para>Error code that you want interpreted into an error message.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garee"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para>If successful, returns the corresponding error message for
|
|
the error code.</para></listitem>
|
|
<listitem><para>If unsuccessful (for example, if the error code is not a valid
|
|
LDAP API error code), returns <literal>Unknown error</literal>.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garea"><title>Example</title>
|
|
<para><olink targetptr="ldap-err2string-example">Example 21–13</olink> sets
|
|
the variable <replaceable>err_msg</replaceable> to the error message corresponding
|
|
to the error code returned by the <function>ldap_simple_bind_s</function> function.
|
|
</para>
|
|
<example id="ldap-err2string-example"><title>Using <function>ldap_err2string</function></title>
|
|
<programlisting>#include <ldap.h>
|
|
...
|
|
LDAP *ld;
|
|
char *dn = "uid=bjensen,ou=People,dc=example, dc=com";
|
|
char *pw = "hifalutin";
|
|
char *err_msg;
|
|
...
|
|
err_msg = ldap_err2string( ldap_simple_bind_s( ld, dn, pw ) );
|
|
...</programlisting>
|
|
</example>
|
|
</sect3>
|
|
<sect3 id="gardv"><title>See Also</title>
|
|
<para><olink targetptr="bdasq">ldap_get_lderrno</olink>, <olink targetptr="bdaur">ldap_perror</olink>, <olink targetptr="bdauv">ldap_result2error
|
|
</olink>, <olink targetptr="bdavf">ldap_set_lderrno</olink>, <olink targetptr="bdavr">ldapssl_err2string</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdarr"><title><function>ldap_explode_dn</function></title>
|
|
<para>The <function>ldap_explode_dn</function> function converts a DN into
|
|
its component parts.</para>
|
|
<sect3 id="garej"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
char ** ldap_explode_dn( const char *dn, int notypes );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gareo"><title>Parameters</title>
|
|
<table frame="topbot" id="garfe"><title><function>ldap_explode_dn</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>dn</literal></para></entry>
|
|
<entry>
|
|
<para>DN that you want separated into components.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>notypes</literal></para></entry>
|
|
<entry>
|
|
<para>Specifies whether or not type names in the DN are returned. This parameter
|
|
can have the following possible values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><literal>0</literal> specifies that type names are returned.</para>
|
|
</listitem>
|
|
<listitem><para>A non-zero value specifies that type names are not returned.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garfk"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para>If successful, returns a <literal>NULL</literal> terminated
|
|
array containing the components of the DN.</para></listitem>
|
|
<listitem><para>If unsuccessful, returns <literal>NULL</literal>.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garev"><title>Example</title>
|
|
<para>The following function call:</para>
|
|
<programlisting>ldap_explode_dn( "uid=bjensen,ou=People,dc=example,dc=com", 0 );</programlisting>
|
|
<para>returns this array:</para>
|
|
<programlisting>{ "uid=bjensen", "ou=People", "dc=example,dc=com", NULL }</programlisting>
|
|
<para>If you change the <literal>notypes</literal> parameter from <literal>0</literal> to
|
|
<literal>1</literal>:</para>
|
|
<programlisting>ldap_explode_dn( "uid=bjensen,ou=People,dc=example,dc=com", 1 );</programlisting>
|
|
<para>The component names are not returned in the array:</para>
|
|
<programlisting>{ "bjensen", "People", "example.com", NULL }</programlisting>
|
|
</sect3>
|
|
<sect3 id="gardr"><title>See Also</title>
|
|
<para><olink targetptr="bdart">ldap_explode_rdn</olink>, <olink targetptr="bdask">ldap_get_dn</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdars"><title><function>ldap_explode_dns</function></title>
|
|
<note><para>This function is to be deprecated and should not be used. It is
|
|
included in <literal>ldap-to-be-deprecated.h</literal> for backward-compatibility.
|
|
</para></note>
|
|
<para>The <function>ldap_explode_dns</function> function takes a DNS-style
|
|
DN, breaks it up into its component parts, and returns a <literal>NULL</literal> terminated
|
|
array. For example, the DN <literal>ldap.example.com</literal> will return <literal>
|
|
{ "ldap", "example", "com", NULL }</literal>. The result can be freed by calling
|
|
<olink targetptr="bdaxc">ldap_value_free</olink>.</para>
|
|
<sect3 id="garfm"><title>Syntax</title>
|
|
<programlisting>#include <ldap-to-be-deprecated.h>
|
|
char ** ldap_explode_dns( const char *dn );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gareq"><title>Parameters</title>
|
|
<table frame="topbot" id="garel"><title><function>ldap_explode_dns</function> Function
|
|
Parameter</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>dn</literal></para></entry>
|
|
<entry>
|
|
<para>DN that you want separated into components.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gardx"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para>If successful, returns a <literal>NULL</literal> terminated
|
|
array containing the components of the DN.</para></listitem>
|
|
<listitem><para>If unsuccessful, returns <literal>NULL</literal>.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="bdart"><title><function>ldap_explode_rdn</function></title>
|
|
<para>The <function>ldap_explode_rdn</function> function converts a relative
|
|
distinguished name (RDN) into its component parts.</para>
|
|
<sect3 id="gargn"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
char ** ldap_explode_rdn( const char *dn, int notypes );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garhi"><title>Parameters</title>
|
|
<table frame="topbot" id="gargd"><title><function>ldap_explode_rdn</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>dn</literal></para></entry>
|
|
<entry>
|
|
<para>RDN that you want separated into components.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>notypes</literal></para></entry>
|
|
<entry>
|
|
<para>Specifies whether or not type names in the RDN are returned. This parameter
|
|
can have the following possible values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><literal>0</literal> specifies that type names are returned.</para>
|
|
</listitem>
|
|
<listitem><para>A non-zero value specifies that type names are not returned.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garhg"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para>If successful, returns a <literal>NULL</literal> terminated
|
|
array containing the components of the RDN.</para></listitem>
|
|
<listitem><para>If unsuccessful, returns <literal>NULL</literal>.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="gargu"><title>Example</title>
|
|
<para>The following function call:</para>
|
|
<programlisting>ldap_explode_rdn( "ou=Sales + cn=Barbara Jensen", 0 );</programlisting>
|
|
<para>returns this array:</para>
|
|
<programlisting>{ "ou=Sales", "cn=Barbara Jensen", NULL }</programlisting>
|
|
</sect3>
|
|
<sect3 id="gargt"><title>See Also</title>
|
|
<para><olink targetptr="bdarr">ldap_explode_dn</olink>, <olink targetptr="bdask">
|
|
ldap_get_dn</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaru"><title><function>ldap_extended_operation</function></title>
|
|
<para>The <function>ldap_extended_operation</function> function sends a request
|
|
to the server to perform an extended operation asynchronously.</para>
|
|
<sect3 id="gargk"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_extended_operation( LDAP *ld, const char *requestoid,
|
|
struct berval *requestdata, LDAPControl **serverctrls,
|
|
LDAPControl **clientctrls, int *msgidp );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garhn"><title>Parameters</title>
|
|
<table frame="topbot" id="garfr"><title><function>ldap_extended_operation</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>requestoid</literal></para></entry>
|
|
<entry>
|
|
<para>Object identifier (OID) of the extended operation that you want the
|
|
server to perform. After processing an LDAP v3 extended operation, an LDAP
|
|
server can return an OID and data in the result. To parse the OID and data
|
|
from the result, call the <olink targetptr="bdaul">ldap_parse_extended_result</olink> function.
|
|
</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>requestdata</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to a <olink targetptr="bdakg">berval</olink> structure containing
|
|
the data that you want passed to the server to perform the extended operation.
|
|
The data in the <olink targetptr="bdakg">berval</olink> is a buffer of the
|
|
BER encoded data type, usually obtained using the <olink targetptr="bdaof">ber_flatten
|
|
</olink> function.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>serverctrls</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
|
|
representing LDAP server controls that apply to this operation. If you do
|
|
not want to pass any server controls, specify <literal>NULL</literal> for
|
|
this argument.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>clientctrls</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
|
|
representing LDAP client controls that apply to this operation. If you do
|
|
not want to pass any client controls, specify <literal>NULL</literal> for
|
|
this argument.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>msgidp</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an integer that will be set to the message ID of the LDAP
|
|
operation.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gargy"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if an invalid parameter
|
|
was passed to the function.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
|
|
allocated.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_ENCODING_ERROR</errorcode> if an error occurred
|
|
when BER-encoding the control.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_SERVER_DOWN</errorcode> if the LDAP server
|
|
did not receive the request or if the connection to the server was lost.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_NOT_SUPPORTED</errorcode> if controls are
|
|
included in your request (for example, as a session preference) and your LDAP
|
|
client does not specify that it is using the LDAP v3. Make sure that you set
|
|
the version of your LDAP client to version 3 before calling this function.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<note><para>To check the result of this operation, call <olink targetptr="bdauu">
|
|
ldap_result</olink>, <olink targetptr="bdaul">ldap_parse_extended_result</olink>,
|
|
and <olink targetptr="bdasq">ldap_get_lderrno</olink>.</para></note>
|
|
</sect3>
|
|
<sect3 id="garge"><title>Description</title>
|
|
<para>The <function>ldap_extended_operation</function> function sends a request
|
|
to the server to perform an LDAP v3 extended operation. <function>ldap_extended_operation
|
|
</function> is an asynchronous function; it does not directly return results.
|
|
If you want the results to be returned directly by the function, call the
|
|
synchronous function <olink targetptr="bdarv">ldap_extended_operation_s</olink>.</para>
|
|
</sect3>
|
|
<sect3 id="gargi"><title>See Also</title>
|
|
<para><olink targetptr="bdarv">ldap_extended_operation_s</olink>, <olink targetptr="bdauu">ldap_result</olink>, <olink targetptr="bdaul">ldap_parse_extended_result
|
|
</olink>, <olink targetptr="bdasq">ldap_get_lderrno</olink>, <olink targetptr="bdaof">ber_flatten</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdarv"><title><function>ldap_extended_operation_s</function></title>
|
|
<para>The <function>ldap_extended_operation_s</function> function sends a
|
|
request to the server to perform an extended operation synchronously.</para>
|
|
<sect3 id="gargg"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_extended_operation_s( LDAP *ld, const char *requestoid,
|
|
struct berval *requestdata, LDAPControl **serverctrls,
|
|
LDAPControl **clientctrls, char **retoidp, struct berval **retdatap );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garfx"><title>Parameters</title>
|
|
<table frame="topbot" id="gargo"><title><function>ldap_extended_operation_s</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>requestoid</literal></para></entry>
|
|
<entry>
|
|
<para>Object identifier (OID) of the extended operation that you want the
|
|
server to perform.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>requestdata</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to a <olink targetptr="bdakg">berval</olink> structure containing
|
|
the data that you want passed to the server to perform the extended operation.
|
|
The data in the <olink targetptr="bdakg">berval</olink> is a buffer of the
|
|
BER encoded data type, usually obtained using the <olink targetptr="bdaof">ber_flatten
|
|
</olink> function.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>serverctrls</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
|
|
representing LDAP server controls that apply to this operation. If you do
|
|
not want to pass any server controls, specify <literal>NULL</literal> for
|
|
this argument.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>clientctrls</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
|
|
representing LDAP client controls that apply to this operation. If you do
|
|
not want to pass any client controls, specify <literal>NULL</literal> for
|
|
this argument.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>retoidp</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to the OID returned by the server after performing the extended
|
|
operation. When done, you can free this by calling the <olink targetptr="bdatl">ldap_memfree
|
|
</olink> function.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>retdatap</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to the pointer for a <olink targetptr="bdakg">berval</olink> structure
|
|
containing the data returned by the server after performing the extended operation.
|
|
When done, you can free this by calling the <olink targetptr="bdaoc">ber_bvfree</olink>
|
|
function.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gargc"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if an invalid parameter
|
|
was passed to the function.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
|
|
allocated.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_ENCODING_ERROR</errorcode> if an error occurred
|
|
when BER-encoding the control.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_SERVER_DOWN</errorcode> if the LDAP server
|
|
did not receive the request or if the connection to the server was lost.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_LOCAL_ERROR</errorcode> if an error occurred
|
|
when receiving the results from the server.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_DECODING_ERROR</errorcode> if an error occurred
|
|
when decoding the BER-encoded results from the server.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_NOT_SUPPORTED</errorcode> if controls are
|
|
included in your request (for example, as a session preference) and your LDAP
|
|
client does not specify that it is using the LDAP v3. Make sure that you set
|
|
the version of your LDAP client to version 3 before calling this function.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<note><para>&cnDirectoryServer; and other LDAP server products may send result
|
|
codes in addition to those described. For example, the server may have loaded
|
|
a plug-in that returns custom result codes. Check your LDAP server documentation
|
|
for other result codes.</para></note>
|
|
</sect3>
|
|
<sect3 id="garga"><title>Description</title>
|
|
<para>The <function>ldap_extended_operation_s</function> function sends a
|
|
request to the server to perform an LDAP v3 extended operation.</para>
|
|
<note><para>The LDAP server must support the extended operation. &cnDirectoryServer; supports
|
|
a server plug-in interface that you can use to add support for extended operations.
|
|
</para></note>
|
|
<para><function>ldap_extended_operation_s</function> is a synchronous function,
|
|
which directly returns the results of the operation. If you want to perform
|
|
other operations while waiting for the results of this operation, call the
|
|
asynchronous function <olink targetptr="bdaru">ldap_extended_operation</olink>.
|
|
After processing an LDAP v3 extended operation, an LDAP server can return
|
|
an object identifier and data in the results. The <literal>retoidp</literal> and <literal>
|
|
retdatap</literal> arguments point to these values.</para></sect3>
|
|
<sect3 id="gargv"><title>See Also</title>
|
|
<para><olink targetptr="bdaru">ldap_extended_operation</olink>, <olink targetptr="bdaof">ber_flatten</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdarw"><title><function>ldap_first_attribute</function></title>
|
|
<para>The <function>ldap_first_attribute</function> function returns the name
|
|
of the first attribute in an entry returned by the <olink targetptr="bdary">ldap_first_entry
|
|
</olink> , the <olink targetptr="bdauc">ldap_next_entry</olink>, or the <olink targetptr="bdauu">ldap_result</olink> functions.</para>
|
|
<sect3 id="garhe"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
char * ldap_first_attribute( LDAP *ld, LDAPMessage *entry,
|
|
BerElement **ber );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gargx"><title>Parameters</title>
|
|
<table frame="topbot" id="gargp"><title><function>ldap_first_attribute</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>entry</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to the <olink targetptr="bdaly">LDAPMessage</olink> structure
|
|
representing the entry returned by the <olink targetptr="bdary">ldap_first_entry</olink> or <olink targetptr="bdauc">ldap_next_entry</olink> function.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>ber</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to a <olink targetptr="bdakh">BerElement</olink> allocated to
|
|
keep track of its current position. Pass this pointer to subsequent calls
|
|
to <olink targetptr="bdaua">ldap_next_attribute</olink> to step through the
|
|
entry's attributes.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garhm"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para>If successful, returns the pointer to the name of the first
|
|
attribute in an entry. When you are done using this data, you should free
|
|
the memory by calling the <olink targetptr="bdatl">ldap_memfree</olink> function.
|
|
</para></listitem>
|
|
<listitem><para>If unsuccessful, returns a <literal>NULL</literal> and sets
|
|
the appropriate error code in the <olink targetptr="bdakj">LDAP</olink> structure.
|
|
To get the error code, call the <olink targetptr="bdasq">ldap_get_lderrno</olink> function.
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garfq"><title>Example</title>
|
|
<para><olink targetptr="ldap-first-attribute-example">Example 21–14</olink>
|
|
retrieves each attribute for an entry.</para>
|
|
<example id="ldap-first-attribute-example"><title>Using <function>ldap_first_attribute
|
|
</function></title>
|
|
<programlisting>#include <stdio.h>
|
|
#include <ldap.h>
|
|
...
|
|
LDAP *ld;
|
|
LDAPMessage *result, *e;
|
|
BerElement *ber;
|
|
char *a;
|
|
char *my_searchbase = "dc=example,dc=com";
|
|
char *my_filter = "(sn=Jensen)"
|
|
...
|
|
/* Search the directory */
|
|
if ( ldap_search_s( ld, my_searchbase, LDAP_SCOPE_SUBTREE,
|
|
my_filter, NULL, 0, &result ) !=
|
|
LDAP_SUCCESS ) {
|
|
ldap_perror( ld, "ldap_search_s" );
|
|
return( 1 );
|
|
}
|
|
|
|
/* Get the first matching entry.*/
|
|
e = ldap_first_entry( ld, result );
|
|
|
|
/* Retrieve the attributes the entry */
|
|
for ( a = ldap_first_attribute( ld, e, &ber ); a != NULL;
|
|
a = ldap_next_attribute( ld, e, ber ) ) {
|
|
...
|
|
/* Code to get and manipulate attribute values */
|
|
...
|
|
}
|
|
ldap_memfree( a );
|
|
}
|
|
/* Free the BerElement from memory when done */
|
|
if ( ber != NULL ) {
|
|
ldap_ber_free( ber, 0 );
|
|
}
|
|
...</programlisting>
|
|
</example>
|
|
</sect3>
|
|
<sect3 id="garfo"><title>See Also</title>
|
|
<para><olink targetptr="bdary">ldap_first_entry</olink>, <olink targetptr="bdauc">ldap_next_entry</olink>, <olink targetptr="bdaua">ldap_next_attribute
|
|
</olink>, <olink targetptr="bdakh">BerElement</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdarx"><title><function>ldap_first_disptmpl</function></title>
|
|
<para>The <function>ldap_first_disptmpl</function> function returns the first
|
|
template in a list.</para>
|
|
<sect3 id="garhd"><title>Syntax</title>
|
|
<programlisting>#include <disptmpl.h>
|
|
ldap_first_disptmpl( struct ldap_disptmpl *tmpllist );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gargh"><title>Parameters</title>
|
|
<table frame="topbot" id="garft"><title><function>ldap_first_disptmpl</function> Function
|
|
Parameter</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>tmpllistp</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to a list of template data structures.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garfy"><title>Description</title>
|
|
<para><function>ldap_first_disptmpl</function> returns the first template
|
|
in the list of templates pointed to by the parameter <literal>tmpllistp</literal>. <literal>
|
|
tmpllistp</literal> is typically obtained by calling <olink targetptr="bdata">ldap_init_templates
|
|
</olink> .</para></sect3>
|
|
<sect3 id="gargw"><title>See Also</title>
|
|
<para><olink targetptr="bdaub">ldap_next_disptmpl</olink>, <olink targetptr="bdata">ldap_init_templates</olink>, <olink targetptr="bdatb">ldap_init_templates_buf
|
|
</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdary"><title><function>ldap_first_entry</function></title>
|
|
<para>The <function>ldap_first_entry</function> function returns a pointer
|
|
to the <olink targetptr="bdaly">LDAPMessage</olink> structure representing
|
|
the first directory entry in a chain of search results.</para>
|
|
<sect3 id="garfp"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
LDAPMessage * ldap_first_entry( LDAP *ld, LDAPMessage *result );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gargz"><title>Parameters</title>
|
|
<table frame="topbot" id="gargj"><title><function>ldap_first_entry</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>result</literal></para></entry>
|
|
<entry>
|
|
<para>Chain of search results, which are represented by a pointer to the <olink targetptr="bdaly">LDAPMessage</olink> structure.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garhj"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para>If successful, returns the pointer to the first <olink targetptr="bdaly">LDAPMessage</olink> structure of the type <literal>LDAP_RES_SEARCH_ENTRY
|
|
</literal> in the chain of search results.</para></listitem>
|
|
<listitem><para>If no <olink targetptr="bdaly">LDAPMessage</olink> structures
|
|
of the type <literal>LDAP_RES_SEARCH_ENTRY</literal> are in the chain of the
|
|
search results or if the function is unsuccessful, returns a <literal>NULLMSG</literal>.
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garhc"><title>Description</title>
|
|
<para>The <function>ldap_first_entry</function> function returns a pointer
|
|
to the <olink targetptr="bdaly">LDAPMessage</olink> structure representing
|
|
the first directory entry in a chain of search results. Search result entries
|
|
are in messages of the type <literal>LDAP_RES_SEARCH_ENTRY</literal>. You
|
|
can use this function in conjunction with the <olink targetptr="bdauc">ldap_next_entry
|
|
</olink> function to iterate through the directory entries in a chain of search
|
|
results. These functions skip over any messages in the chain that do not have
|
|
the type <literal>LDAP_RES_SEARCH_ENTRY</literal>.</para>
|
|
<para>Do not free the <olink targetptr="bdaly">LDAPMessage</olink> structure
|
|
returned by this function. Because this is a structure within a chain of search
|
|
results, freeing this structure will free part of the chain of search results.
|
|
When you are done working with the search results, you can free the chain
|
|
itself, rather than individual structures within the chain.</para></sect3>
|
|
<sect3 id="garfv"><title>See Also</title>
|
|
<para><olink targetptr="bdauu">ldap_result</olink>, <olink targetptr="bdauz">ldap_search_ext
|
|
</olink> , <olink targetptr="bdava">ldap_search_ext_s</olink>, <olink targetptr="bdauc">ldap_next_entry</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdarz"><title><function>ldap_first_message</function></title>
|
|
<para>The <function>ldap_first_message</function> function returns a pointer
|
|
to the first <olink targetptr="bdaly">LDAPMessage</olink> structure in a chain
|
|
of search results.</para>
|
|
<sect3 id="garfw"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
LDAPMessage * ldap_first_message( LDAP *ld, LDAPMessage *res );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garfs"><title>Parameters</title>
|
|
<table frame="topbot" id="garfz"><title><function>ldap_first_message</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>res</literal></para></entry>
|
|
<entry>
|
|
<para>Chain of search results, represented by a pointer to the <olink targetptr="bdaly">LDAPMessage</olink> structure.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garhf"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para>If successful, returns the pointer to the first <olink targetptr="bdaly">LDAPMessage</olink> structure in the chain of search results.</para>
|
|
</listitem>
|
|
<listitem><para>If no <olink targetptr="bdaly">LDAPMessage</olink> structures
|
|
are in the chain or if the function is unsuccessful, returns a <literal>NULLMSG</literal>.
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garha"><title>Description</title>
|
|
<para>The <function>ldap_first_message</function> function returns a pointer
|
|
to the first <olink targetptr="bdaly">LDAPMessage</olink> structure in a chain
|
|
of search results. You can use this function in conjunction with the <olink targetptr="bdaud">ldap_next_message</olink> function to iterate through the
|
|
chain of search results. You can also call the <olink targetptr="bdatx">ldap_msgtype
|
|
</olink> function to determine if each message contains a matching entry,
|
|
a message of the type <literal>LDAP_RES_SEARCH_ENTRY</literal>, or a search
|
|
reference, a message of the type <literal>LDAP_RES_SEARCH_REFERENCE</literal>.</para>
|
|
<para>Do not free the <olink targetptr="bdaly">LDAPMessage</olink> structure
|
|
returned by this function. Because this is a structure within a chain of search
|
|
results, freeing this structure will free part of the chain of search results.
|
|
When you are done working with the search results, you can free the chain
|
|
itself, rather than individual structures within the chain.</para></sect3>
|
|
<sect3 id="gargb"><title>See Also</title>
|
|
<para><olink targetptr="bdauu">ldap_result</olink>, <olink targetptr="bdauz">ldap_search_ext
|
|
</olink> , <olink targetptr="bdava">ldap_search_ext_s</olink>, <olink targetptr="bdaud">ldap_next_message</olink>, <olink targetptr="bdary">ldap_first_entry
|
|
</olink>, <olink targetptr="bdasa">ldap_first_reference</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdasa"><title><function>ldap_first_reference</function></title>
|
|
<para>The <function>ldap_first_reference</function> function returns a pointer
|
|
to the <olink targetptr="bdaly">LDAPMessage</olink> structure representing
|
|
the first search reference in a chain of search results.</para>
|
|
<sect3 id="gargq"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
LDAPMessage * ldap_first_reference(LDAP *ld, LDAPMessage *res );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garhl"><title>Parameters</title>
|
|
<table frame="topbot" id="gargm"><title><function>ldap_first_reference</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>res</literal></para></entry>
|
|
<entry>
|
|
<para>Chain of search results, which are represented by a pointer to the <olink targetptr="bdaly">LDAPMessage</olink> structure.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garhk"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para>If successful, returns the pointer to the first <olink targetptr="bdaly">LDAPMessage</olink> structure of the type <literal>LDAP_RES_SEARCH_REFERENCE
|
|
</literal> in the chain of search results.</para></listitem>
|
|
<listitem><para>If no <olink targetptr="bdaly">LDAPMessage</olink> structures
|
|
of the type <literal>LDAP_RES_SEARCH_REFERENCE</literal> are in the chain
|
|
of the search results or if the function is unsuccessful, returns a <literal>NULLMSG
|
|
</literal>.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garfu"><title>Description</title>
|
|
<para>The <function>ldap_first_reference</function> function returns a pointer
|
|
to the <olink targetptr="bdaly">LDAPMessage</olink> structure representing
|
|
the first search reference in a chain of search results. Search references
|
|
are in messages of the type <literal>LDAP_RES_SEARCH_REFERENCE</literal>,
|
|
continuation references as specified in LDAPv3 that are stored as referral
|
|
entries. Like a referral, each continuation reference itself may contain a
|
|
number of URLs assumed to be equivalent, and the client should use one of
|
|
those URLs.</para>
|
|
<para>You can use this function in conjunction with the <olink targetptr="bdaue">
|
|
ldap_next_reference</olink> function to iterate through the search references
|
|
in a chain of search results. These functions skip over any messages in the
|
|
chain that do not have the type <literal>LDAP_RES_SEARCH_REFERENCE</literal>.</para>
|
|
<para>Do not free the <olink targetptr="bdaly">LDAPMessage</olink> structure
|
|
returned by this function. Because this is a structure within a chain of search
|
|
results, freeing this structure will free part of the chain of search results.
|
|
When you are done working with the search results, you can free the chain
|
|
itself, rather than individual structures within the chain.</para></sect3>
|
|
<sect3 id="gargl"><title>See Also</title>
|
|
<para><olink targetptr="bdauu">ldap_result</olink>, <olink targetptr="bdauz">ldap_search_ext
|
|
</olink> , <olink targetptr="bdava">ldap_search_ext_s</olink>, <olink targetptr="bdaue">ldap_next_reference</olink>, <olink targetptr="bdarz">ldap_first_message
|
|
</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdasb"><title><function>ldap_first_searchobj</function></title>
|
|
<para>The <function>ldap_first_searchobj</function> function returns the first
|
|
search preference configuration from a data structure defined in the list <literal>
|
|
solist</literal> .</para>
|
|
<sect3 id="garhh"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
ldap_searchobj * ldap_first_searchobj( struct ldap_searchobj *solist );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garhb"><title>Parameters</title>
|
|
<table frame="topbot" id="gargr"><title><function>ldap_first_searchobj</function> Function
|
|
Parameter</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><parameter>solist</parameter></para></entry>
|
|
<entry>
|
|
<para>Pointer to the search preference data structures, typically obtained
|
|
by calling <olink targetptr="bdasy">ldap_init_searchprefs</olink>.</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gargf"><title>Description</title>
|
|
<para><literal>ldap_first_searchobj</literal> provides access to LDAP search
|
|
preference configuration data. LDAP search preference configurations are typically
|
|
used by LDAP client programs to specify which attributes a user may search
|
|
by, the labels for the attributes, and the LDAP filters and scopes associated
|
|
with those searches.</para></sect3>
|
|
<sect3 id="gargs"><title>See Also</title>
|
|
<para><olink targetptr="bdasy">ldap_init_searchprefs</olink>, <olink targetptr="bdasz">ldap_init_searchprefs_buf</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdasc"><title><function>ldap_first_tmplcol</function></title>
|
|
<para>The <function>ldap_first_tmplcol</function> function returns a pointer
|
|
to the first item within a template.</para>
|
|
<sect3 id="garhr"><title>Syntax</title>
|
|
<programlisting>#include <disptmpl.h>
|
|
struct ldap_tmplitem * ldap_first_tmplcol( struct ldap_disptmpl *tmpl,
|
|
struct ldap_tmplitem *row );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garjf"><title>Parameters</title>
|
|
<table frame="topbot" id="garij"><title><function>ldap_first_tmplcol</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>tmpl</literal></para></entry>
|
|
<entry>
|
|
<para>The name of the template to be retrieved.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>row</literal></para></entry>
|
|
<entry>
|
|
<para>The row in which the item is to be retrieved from.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garih"><title>Returns</title>
|
|
<itemizedlist>
|
|
<listitem><para>If successful, a pointer to an <literal>ldap_tmplitem</literal> structure.
|
|
</para></listitem>
|
|
<listitem><para>A <literal>NULL</literal> pointer on error.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="gario"><title>Description</title>
|
|
<para><function>ldap_first_tmplcol</function> returns a pointer to the first
|
|
item (in the first column) of the row, defined by <literal>row</literal>,
|
|
within the template defined by <literal>tmpl</literal>.</para></sect3>
|
|
<sect3 id="garji"><title>See Also</title>
|
|
<para><olink targetptr="bdasd">ldap_first_tmplrow</olink>, <olink targetptr="bdaug">ldap_next_tmplcol</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdasd"><title><function>ldap_first_tmplrow</function></title>
|
|
<para>The <function>ldap_first_tmplrow</function> function returns a pointer
|
|
to the first row of items in a template.</para>
|
|
<sect3 id="garic"><title>Syntax</title>
|
|
<programlisting>#include <disptmpl.h>
|
|
struct ldap_tmplitem * ldap_first_tmplrow( struct ldap_disptmpl *tmpl );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gariq"><title>Parameters</title>
|
|
<table frame="topbot" id="garjb"><title><function>ldap_first_tmplrow</function> Function
|
|
Parameter</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>tmpl</literal></para></entry>
|
|
<entry>
|
|
<para>The name of the template to be retrieved.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garho"><title>Returns</title>
|
|
<itemizedlist>
|
|
<listitem><para>If successful, a pointer to an <literal>ldap_tmplitem</literal> structure.
|
|
</para></listitem>
|
|
<listitem><para>A <literal>NULL</literal> pointer on error.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="gariy"><title>See Also</title>
|
|
<para><olink targetptr="bdauh">ldap_next_tmplrow</olink>, <olink targetptr="bdasc">ldap_first_tmplcol</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdase"><title><function>ldap_free_friendlymap</function></title>
|
|
<para>The <function>ldap_free_friendlymap</function> function frees the <olink targetptr="bdaki">FriendlyMap</olink> structures allocated by the <olink targetptr="bdasj">ldap_friendly_name</olink> function when no more calls
|
|
to it are to be made.</para>
|
|
<sect3 id="garhy"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
void ldap_free_friendlymap( FriendlyMap *map );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garjj"><title>Parameters</title>
|
|
<table frame="topbot" id="garin"><title><function>ldap_free_friendlymap</function> Function
|
|
Parameter</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>map</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to the <olink targetptr="bdaki">FriendlyMap</olink> mapping
|
|
structure in memory.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garhq"><title>Example</title>
|
|
<para><olink targetptr="ldap-free-friendlymap-example">Example 21–15</olink>
|
|
frees memory allocated by the <olink targetptr="bdasj">ldap_friendly_name</olink>
|
|
function.</para>
|
|
<example id="ldap-free-friendlymap-example"><title>Using <function>ldap_free_friendlymap
|
|
</function></title>
|
|
<programlisting>#include <ldap.h>
|
|
#include <stdio.h>
|
|
...
|
|
FriendlyMap map = NULL;
|
|
char *map_file = "/u/mozilla/ldapsdk/examples/ldapfriendly";
|
|
char *unfriendly_name = "IS";
|
|
char *friendly_name;
|
|
...
|
|
/* Read the ldapfriendly file into the map in memory */
|
|
friendly_name = ldap_friendly_name( map_file, unfriendly_name, &map );
|
|
printf( "Friendly Name for %s: %s\n", unfriendly_name, friendly_name );
|
|
|
|
/* Since file is in memory, no need to reference it in subsequent calls */
|
|
friendly_name = ldap_friendly_name( NULL, "VI", &map );
|
|
printf( "Friendly Name for VI: %s\n", friendly_name );
|
|
...
|
|
ldap_free_friendlymap( map );
|
|
...</programlisting>
|
|
</example>
|
|
</sect3>
|
|
<sect3 id="garie"><title>See Also</title>
|
|
<para><olink targetptr="bdasj">ldap_friendly_name</olink>, <olink targetptr="bdaki">FriendlyMap</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdasf"><title><function>ldap_free_searchprefs</function></title>
|
|
<para>The <function>ldap_free_searchprefs</function> function disposes of
|
|
the data structures allocated by <olink targetptr="bdasy">ldap_init_searchprefs</olink>.
|
|
</para>
|
|
<sect3 id="garit"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
void ldap_free_searchprefs( struct ldap_searchobj *solist );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garhs"><title>Parameters</title>
|
|
<table frame="topbot" id="garir"><title><function>ldap_free_searchprefs</function> Function
|
|
Parameter</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>solist</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to the data structures, typically obtained by calling <olink targetptr="bdasy">ldap_init_searchprefs</olink>.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garja"><title>See Also</title>
|
|
<para><olink targetptr="bdasy">ldap_init_searchprefs</olink>, <olink targetptr="bdasz">ldap_init_searchprefs_buf</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdasg"><title><function>ldap_free_sort_keylist</function></title>
|
|
<para>The <function>ldap_free_sort_keylist</function> function frees the structures
|
|
allocated by the <olink targetptr="bdarf">ldap_create_sort_keylist</olink> function.
|
|
</para>
|
|
<sect3 id="garhx"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
void ldap_free_sort_keylist (LDAPsortkey **sortKeyList);</programlisting>
|
|
</sect3>
|
|
<sect3 id="garht"><title>Parameters</title>
|
|
<table frame="topbot" id="gariv"><title><function>ldap_free_sort_keylist</function> Function
|
|
Parameter</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>sortKeyList</literal></para></entry>
|
|
<entry>
|
|
<para>Array of <olink targetptr="bdamc">LDAPsortkey</olink> structures that
|
|
you want to free from memory.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garim"><title>Description</title>
|
|
<para>The <function>ldap_free_sort_keylist</function> function frees the array
|
|
of <olink targetptr="bdamc">LDAPsortkey</olink> structures allocated by the
|
|
<olink targetptr="bdarf">ldap_create_sort_keylist</olink> function. When
|
|
done sorting results, call this function to free the memory that you have
|
|
allocated. This function must be called after the <olink targetptr="bdare">ldap_create_sort_control
|
|
</olink> function has completed.</para></sect3>
|
|
<sect3 id="garif"><title>See Also</title>
|
|
<para><olink targetptr="bdarf">ldap_create_sort_keylist</olink>, <olink targetptr="bdare">ldap_create_sort_control</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdash"><title><function>ldap_free_templates</function></title>
|
|
<para>The <function>ldap_free_templates</function> function disposes of the
|
|
templates allocated by <olink targetptr="bdata">ldap_init_templates</olink>.</para>
|
|
<sect3 id="garjc"><title>Syntax</title>
|
|
<programlisting>#include <disptmpl.h>
|
|
void ldap_free_templates( struct ldap_disptmpl *tmpllist );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garjd"><title>Parameters</title>
|
|
<table frame="topbot" id="garjg"><title><function>ldap_free_templates</function> Function
|
|
Parameter</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>tmpllistp</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to a list of template data structures.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garhz"><title>Description</title>
|
|
<para><function>ldap_free_templates</function> releases the templates allocated
|
|
by <olink targetptr="bdata">ldap_init_templates</olink>. Each template defined
|
|
in the file is an <literal>ldap_disptmpl</literal> structure.</para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdasi"><title><function>ldap_free_urldesc</function></title>
|
|
<para>The <function>ldap_free_urldesc</function> function frees memory allocated
|
|
by the <olink targetptr="bdawk">ldap_url_parse</olink> function.</para>
|
|
<sect3 id="garib"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
void ldap_free_urldesc( LDAPURLDesc *ludp );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garig"><title>Parameters</title>
|
|
<table frame="topbot" id="garis"><title><function>ldap_free_urldesc</function> Function
|
|
Parameter</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ludp</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to a <olink targetptr="bdams">LDAPURLDesc</olink> structure.</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gariz"><title>Example</title>
|
|
<para><olink targetptr="ldap-free-urldesc-example">Example 21–16</olink> parses
|
|
an LDAP URL and then frees the <olink targetptr="bdams">LDAPURLDesc</olink> structure
|
|
from memory after verifying that the LDAP URL is valid.</para>
|
|
<example id="ldap-free-urldesc-example"><title>Using <function>ldap_free_urldesc</function></title>
|
|
<programlisting>#include <stdio.h>
|
|
#include <ldap.h>
|
|
...
|
|
char *my_url =
|
|
"ldap://ldap.example.com:1389/dc=example,dc=com?cn,mail,telephoneNumber?
|
|
sub?(sn=Jensen)";
|
|
LDAPURLDesc *ludpp;
|
|
int res, i;
|
|
...
|
|
if ( ( res = ldap_url_parse( my_url, &ludpp ) ) != 0 ) {
|
|
switch( res ){
|
|
case LDAP_URL_ERR_NOTLDAP:
|
|
printf( "URL does not begin with \"ldap://\"\n" );
|
|
break;
|
|
case LDAP_URL_ERR_NODN:
|
|
printf( "URL does not contain a distinguished name\n" );
|
|
break;
|
|
case LDAP_URL_ERR_BADSCOPE:
|
|
printf( "URL contains an invalid scope\n" );
|
|
break;
|
|
case LDAP_URL_ERR_MEM:
|
|
printf( "Not enough memory\n" );
|
|
break;
|
|
default:
|
|
printf( "Unknown error\n" );
|
|
}
|
|
return( 1 );
|
|
}
|
|
printf( "URL is a valid LDAP URL\n" );
|
|
ldap_free_urldesc( ludpp );
|
|
...</programlisting>
|
|
</example>
|
|
</sect3>
|
|
<sect3 id="garia"><title>See Also</title>
|
|
<para><olink targetptr="bdawk">ldap_url_parse</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdasj"><title><function>ldap_friendly_name</function></title>
|
|
<para>The <function>ldap_friendly_name</function> function maps a set of standard
|
|
identifiers to their user-friendly counterparts. For example, you can represent
|
|
the list of two-letter state codes (CA, IA) with their corresponding state
|
|
names (California, Iowa), or map country ISO codes to the full country names.</para>
|
|
<note><para><literal>ldapfriendly</literal>, located in <literal>lib/ldapcsdk/etc
|
|
</literal>, is a sample file that maps two letter country codes to their full
|
|
names. It can be used in context with <olink targetptr="bdasj">ldap_friendly_name
|
|
</olink>.</para></note>
|
|
<sect3 id="garhp"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
char * ldap_friendly_name( char *filename, char *uname,
|
|
FriendlyMap *map );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garid"><title>Parameters</title>
|
|
<table frame="topbot" id="garik"><title><function>ldap_friendly_name</function> function
|
|
parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>filename</literal></para></entry>
|
|
<entry>
|
|
<para>Name of the file mapping the standard identifiers to the user-friendly
|
|
names.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>uname</literal></para></entry>
|
|
<entry>
|
|
<para>Standard identifier name for which you want to find the user-friendly
|
|
name.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>map</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to the <olink targetptr="bdaki">FriendlyMap</olink> mapping
|
|
in memory. Initialize this pointer to <literal>NULL</literal> on the first
|
|
call, then use it during subsequent calls so that the mapping file does not
|
|
need to be read again.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garje"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para>If successful, returns the user-friendly name for the specified
|
|
identifier.</para></listitem>
|
|
<listitem><para>If unsuccessful—for example, if the file cannot be read,
|
|
if the file is in a bad format, or if the map parameter is set to <literal>NULL</literal>—returns
|
|
the original identifier (the value passed as the <literal>uname</literal> parameter).
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garil"><title>Description</title>
|
|
<para>This function relies on the existence of a text file mapping standard
|
|
identifiers to user-friendly names. The names in the file are tab-delimited.</para>
|
|
<example id="garii"><title>Unfriendly to Friendly Name Mapping File</title>
|
|
<programlisting><unfriendly_name> <friendly_name>
|
|
AD Andorra
|
|
AE United Arab Emirates
|
|
AF Afghanistan
|
|
AG Antigua and Barbuda
|
|
AI Anguilla</programlisting>
|
|
</example>
|
|
</sect3>
|
|
<sect3 id="garix"><title>Example</title>
|
|
<para><olink targetptr="ldap-friendly-name-example">Example 21–18</olink>
|
|
reads in a map of user-friendly names and prints the name corresponding to
|
|
the standard identifier <literal>IS</literal>.</para>
|
|
<example id="ldap-friendly-name-example"><title>Using <function>ldap_friendly_name
|
|
</function></title>
|
|
<programlisting>#include <ldap.h>
|
|
#include <stdio.h>
|
|
...
|
|
FriendlyMap map = NULL;
|
|
char *map_file = "/u/mozilla/ldapsdk/examples/ldapfriendly";
|
|
char *unfriendly_name = "IS";
|
|
char *friendly_name;
|
|
...
|
|
/* Read the ldapfriendly file into the map in memory */
|
|
friendly_name = ldap_friendly_name( map_file, unfriendly_name, &map );
|
|
printf( "Friendly Name for %s: %s\n", unfriendly_name, friendly_name );
|
|
|
|
/* Since file is in memory, no need to reference it in subsequent calls */
|
|
friendly_name = ldap_friendly_name( NULL, "VI", &map );
|
|
printf( "Friendly Name for VI: %s\n", friendly_name );
|
|
...</programlisting>
|
|
</example>
|
|
</sect3>
|
|
<sect3 id="gariw"><title>See Also</title>
|
|
<para><olink targetptr="bdase">ldap_free_friendlymap</olink>, <olink targetptr="bdaki">FriendlyMap</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdask"><title><function>ldap_get_dn</function></title>
|
|
<para>The <function>ldap_get_dn</function> routine returns the DN for an entry
|
|
in a chain of search results.</para>
|
|
<sect3 id="garhu"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
char * ldap_get_dn( LDAP *ld, LDAPMessage *entry );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garhw"><title>Parameters</title>
|
|
<table frame="topbot" id="garjh"><title><function>ldap_get_dn</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>entry</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an entry in a chain of search results, as returned by the <olink targetptr="bdary">ldap_first_entry</olink> and <olink targetptr="bdauc">ldap_next_entry
|
|
</olink> functions.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garhv"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para>If successful, returns the DN for the specified entry.</para>
|
|
</listitem>
|
|
<listitem><para>If unsuccessful, returns a <literal>NULL</literal> and sets
|
|
the appropriate error code in the LDAP structure. To get the error code, call
|
|
the <olink targetptr="bdasq">ldap_get_lderrno</olink> function.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garip"><title>Description</title>
|
|
<para>You can get an entry from a chain of search results by calling the <olink targetptr="bdary">ldap_first_entry</olink> and <olink targetptr="bdauc">ldap_next_entry
|
|
</olink> functions.</para></sect3>
|
|
<sect3 id="gariu"><title>Example</title>
|
|
<para><olink targetptr="ldap-get-dn-example">Example 21–19</olink> prints
|
|
the DN for each entry found in a search.</para>
|
|
<example id="ldap-get-dn-example"><title>Using <function>ldap_get_dn</function></title>
|
|
<programlisting>#include <stdio.h>
|
|
#include <ldap.h>
|
|
...
|
|
LDAP *ld;
|
|
LDAPMessage *result, *e;
|
|
char *dn;
|
|
char *my_searchbase = "dc=example,dc=com";
|
|
char *my_filter = "(sn=Jensen)";
|
|
...
|
|
/* Search the directory */
|
|
if ( ldap_search_s( ld, my_searchbase, LDAP_SCOPE_SUBTREE, my_filter,
|
|
NULL, 0, &result ) != LDAP_SUCCESS ) {
|
|
ldap_perror( ld, "ldap_search_s" );
|
|
return( 1 );
|
|
}
|
|
|
|
/* For each matching entry found, print out the name of the entry.*/
|
|
for ( e = ldap_first_entry( ld, result ); e != NULL;
|
|
e = ldap_next_entry( ld, e ) ) {
|
|
if ( ( dn = ldap_get_dn( ld, e ) ) != NULL ) {
|
|
printf( "dn: %s\n", dn );
|
|
/* Free the memory used for the DN when done */
|
|
ldap_memfree( dn );
|
|
}
|
|
}
|
|
/* Free the result from memory when done. */
|
|
ldap_msgfree( result );
|
|
...</programlisting>
|
|
</example>
|
|
</sect3>
|
|
<sect3 id="garkp"><title>See Also</title>
|
|
<para><olink targetptr="bdary">ldap_first_entry</olink>, <olink targetptr="bdauc">ldap_next_entry</olink>, <olink targetptr="bdasq">ldap_get_lderrno
|
|
</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdasl"><title><function>ldap_get_entry_controls</function></title>
|
|
<para>The <function>ldap_get_entry_controls</function> function gets the LDAP
|
|
controls included with a directory entry in a set of search results.</para>
|
|
<sect3 id="garkd"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_get_entry_controls( LDAP *ld, LDAPMessage *entry,
|
|
LDAPControl ***serverctrlsp );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garlb"><title>Parameters</title>
|
|
<table frame="topbot" id="garkz"><title><function>ldap_get_entry_controls</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>entry</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdaly">LDAPMessage</olink> structure
|
|
representing an entry in a chain of search results.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>serverctrlsp</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures,
|
|
which represent the LDAP v3 server controls returned by the server.</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garjz"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_DECODING_ERROR</errorcode> if an error occurred
|
|
when decoding the BER-encoded results from the server.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if an invalid parameter
|
|
was passed to the function.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
|
|
allocated.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garkr"><title>Description</title>
|
|
<para>The <function>ldap_get_entry_controls</function> function retrieves
|
|
the LDAP v3 controls included in a directory entry in a chain of search results.
|
|
The LDAP controls are specified in an array of <olink targetptr="bdala">LDAPControl
|
|
</olink> structures with each structure representing one LDAP control. Other
|
|
controls are returned with results sent from the server. You can call <olink targetptr="bdaun">ldap_parse_result</olink> to retrieve those controls.</para>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="bdasm"><title><function>ldap_getfilter_free</function></title>
|
|
<para>The <function>ldap_getfilter_free</function> function frees the memory
|
|
used by a filter set.</para>
|
|
<sect3 id="garjy"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
void ldap_getfilter_free( LDAPFiltDesc *lfdp );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garkm"><title>Parameters</title>
|
|
<table frame="topbot" id="garjo"><title><function>ldap_getfilter_free</function> Function
|
|
Parameter</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>lfdp</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to a <olink targetptr="bdalf">LDAPFiltDesc</olink> structure.</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garku"><title>Description</title>
|
|
<para>Once you call <function>ldap_getfilter_free</function>, the <olink targetptr="bdalf">LDAPFiltDesc</olink> structure is no longer valid and cannot
|
|
be used again.</para></sect3>
|
|
<sect3 id="garjw"><title>Example</title>
|
|
<para><olink targetptr="ldap-getfilter-free-example">Example 21–20</olink> frees
|
|
the <olink targetptr="bdalf">LDAPFiltDesc</olink> structure from memory after
|
|
all searches are completed.</para>
|
|
<example id="ldap-getfilter-free-example"><title>Using <function>ldap_getfilter_free
|
|
</function></title>
|
|
<programlisting>#include <ldap.h>
|
|
...
|
|
LDAPFiltDesc *lfdp;
|
|
char *filter_file = "myfilters.conf";
|
|
...
|
|
/* Read the filter configuration file into an LDAPFiltDesc structure */
|
|
lfdp = ldap_init_getfilter( filter_file );
|
|
...
|
|
/* Retrieve filters and perform searches */
|
|
...
|
|
/* Free the configuration file (the LDAPFiltDesc structure) */
|
|
ldap_getfilter_free( lfdp );
|
|
...</programlisting>
|
|
</example>
|
|
</sect3>
|
|
<sect3 id="garju"><title>See Also</title>
|
|
<para><olink targetptr="bdasw">ldap_init_getfilter</olink>, <olink targetptr="bdasx">ldap_init_getfilter_buf</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdasn"><title><function>ldap_getfirstfilter</function></title>
|
|
<para>The <function>ldap_getfirstfilter</function> function retrieves the
|
|
first filter that is appropriate for a given value.</para>
|
|
<sect3 id="garkb"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
LDAPFiltInfo * ldap_getfirstfilter( LDAPFiltDesc *lfdp,
|
|
char *tagpat, char *value );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garla"><title>Parameters</title>
|
|
<table frame="topbot" id="garkw"><title><function>ldap_getfirstfilter</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>lfdp</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdalf">LDAPFiltDesc</olink> structure.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>tagpat</literal></para></entry>
|
|
<entry>
|
|
<para>Regular expression for a tag in the filter configuration.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>value</literal></para></entry>
|
|
<entry>
|
|
<para>Value for which to find the first appropriate filter.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garjx"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para>If successful, returns a pointer to an <olink targetptr="bdalg">LDAPFiltInfo
|
|
</olink> structure.</para></listitem>
|
|
<listitem><para>If no more filters can be returned, returns a <literal>NULL</literal>.
|
|
</para></listitem>
|
|
<listitem><para>If unsuccessful, returns a <literal>NULL</literal>.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garkc"><title>Example</title>
|
|
<para><olink targetptr="ldap-getfirstfilter-example">Example 21–21</olink>
|
|
is based on the <literal>getfilt</literal> command-line program example provided
|
|
with the &DirectorySDKForC;. The program prompts the user to enter search
|
|
criteria and, based on the criteria entered, it retrieves filters that match
|
|
the criteria.</para>
|
|
<example id="ldap-getfirstfilter-example"><title>Using <function>ldap_getfirstfilter
|
|
</function></title>
|
|
<programlisting>#include <stdio.h>
|
|
#include <ldap.h>
|
|
...
|
|
LDAP *ld;
|
|
LDAPMessage *result, *e;
|
|
BerElement *ber;
|
|
char *a, *dn;
|
|
char **vals;
|
|
int i;
|
|
LDAPFiltDesc *ldfp;
|
|
LDAPFiltInfo *ldfi;
|
|
char buf[ 80 ]; /* Contains the search criteria */
|
|
int found;
|
|
...
|
|
/* Load the filter configuration file into an LDAPFiltDesc structure */
|
|
if ( ( ldfp = ldap_init_getfilter( "myfilters.conf" ) ) == NULL ) {
|
|
perror( "Cannot open filter configuration file" );
|
|
return( 1 );
|
|
}
|
|
|
|
/* Read a string to search for */
|
|
printf( "Enter a string to search for: " );
|
|
gets( buf );
|
|
if ( strlen( buf ) == 0 ) {
|
|
fprintf( stderr, "usage: %s search-string\n", argv[ 0 ]);
|
|
return( 1 );
|
|
}
|
|
|
|
/* Select a filter to use when searching for the value in buf */
|
|
found = 0;
|
|
for ( ldfi = ldap_getfirstfilter( ldfp, "people", buf );
|
|
ldfi != NULL;
|
|
ldfi = ldap_getnextfilter( ldfp ) ) {
|
|
|
|
/* Use the selected filter to search the directory */
|
|
if ( ldap_search_s( ld, "dc=example,dc=com, ldfi->lfi_scope,
|
|
ldfi->lfi_filter, NULL, 0, &result ) != LDAP_SUCCESS ) {
|
|
ldap_perror( ld, "ldap_search_s" );
|
|
return( 1 );
|
|
} else {
|
|
|
|
/* Once a filter gets results back, stop iterating through
|
|
the different filters */
|
|
if ( ( found = ldap_count_entries( ld, result ) > 0 ) ) {
|
|
break;
|
|
} else {
|
|
ldap_msgfree( result );
|
|
}
|
|
}
|
|
}
|
|
|
|
if ( found == 0 ) {
|
|
printf( "No matching entries found.\n" );
|
|
} else {
|
|
printf( "Found %d %s match%s for \"%s\"\n\n", found,
|
|
ldfi->lfi_desc, found == 1 ? "" : "es", buf );
|
|
}
|
|
|
|
ldap_msgfree( result );
|
|
ldap_getfilter_free( ldfp );
|
|
...</programlisting>
|
|
</example>
|
|
</sect3>
|
|
<sect3 id="garjv"><title>See Also</title>
|
|
<para><olink targetptr="bdasw">ldap_init_getfilter</olink>, <olink targetptr="bdasx">ldap_init_getfilter_buf</olink>, <olink targetptr="bdasr">ldap_getnextfilter
|
|
</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaso"><title><function>ldap_get_lang_values</function></title>
|
|
<note><para>This function is deprecated and should not be used. It is included
|
|
in <literal>ldap-deprecated.h</literal> for backward-compatibility. Please
|
|
use <olink targetptr="bdast">ldap_get_values</olink>.</para></note>
|
|
<para>The <function>ldap_get_lang_values</function> function returns a <literal>NULL
|
|
</literal> terminated array of an attribute’s string values that match
|
|
a specified language subtype.</para>
|
|
<sect3 id="garkh"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
char ** ldap_get_lang_values( LDAP *ld, LDAPMessage *entry,
|
|
const char *target, char **type );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garjr"><title>Parameters</title>
|
|
<table frame="topbot" id="garjs"><title><function>ldap_get_lang_values</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameters</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>entry</literal></para></entry>
|
|
<entry>
|
|
<para>Entry retrieved from the directory.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>target</literal></para></entry>
|
|
<entry>
|
|
<para>Attribute type (including an optional language subtype) that you want
|
|
to retrieve the values of.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>type</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to a buffer that returns the attribute type retrieved by this
|
|
function.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garkk"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para>If successful, returns a <literal>NULL</literal> terminated
|
|
array of the attribute’s values.</para></listitem>
|
|
<listitem><para>If unsuccessful or if no such attribute exists in the entry,
|
|
returns a <literal>NULL</literal> and sets the appropriate error code in the
|
|
<olink targetptr="bdakj">LDAP</olink> structure. To get the error code, call
|
|
the <olink targetptr="bdasq">ldap_get_lderrno</olink> function.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garjl"><title>Description</title>
|
|
<para>Unlike the <olink targetptr="bdast">ldap_get_values</olink> function,
|
|
if a language subtype is specified, this function first attempts to find and
|
|
return values that match that subtype—for example, <literal>cn;lang-en</literal>.
|
|
If you want to retrieve binary data from an attribute, call the <olink targetptr="bdasp">ldap_get_lang_values_len</olink> function.</para></sect3>
|
|
<sect3 id="garkv"><title>See Also</title>
|
|
<para><olink targetptr="bdary">ldap_first_entry</olink>, <olink targetptr="bdarw">ldap_first_attribute</olink>, <olink targetptr="bdasp">ldap_get_lang_values_len
|
|
</olink> , <olink targetptr="bdast">ldap_get_values</olink>, <olink targetptr="bdauc">ldap_next_entry</olink>, <olink targetptr="bdaua">ldap_next_attribute
|
|
</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdasp"><title><function>ldap_get_lang_values_len</function></title>
|
|
<note><para>This function is deprecated and should not be used. It is included
|
|
in <literal>ldap-deprecated.h</literal> for backward-compatibility. Please
|
|
use <olink targetptr="bdasu">ldap_get_values_len</olink>.</para></note>
|
|
<para>The <function>ldap_get_lang_values_len</function> function returns a
|
|
<literal>NULL</literal> terminated array of pointers to <olink targetptr="bdakg">
|
|
berval</olink> structures, each containing the length and pointer to a binary
|
|
value of an attribute for a given entry.</para>
|
|
<sect3 id="garks"><title>Syntax</title>
|
|
<programlisting>#include <ldap-deprecated.h>
|
|
struct berval ** ldap_get_lang_values_len( LDAP *ld,
|
|
LDAPMessage *entry, const char *target, char **type );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garkl"><title>Parameters</title>
|
|
<table frame="topbot" id="garjq"><title><function>ldap_get_lang_values_len</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>entry</literal></para></entry>
|
|
<entry>
|
|
<para>Result returned by the <olink targetptr="bdauu">ldap_result</olink> or <olink targetptr="bdavb">ldap_search_s</olink> function.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>target</literal></para></entry>
|
|
<entry>
|
|
<para>Attribute returned by <olink targetptr="bdarw">ldap_first_attribute</olink> or <olink targetptr="bdaua">ldap_next_attribute</olink>, or the attribute as a literal
|
|
string, such as <literal>jpegPhoto</literal> or <literal>audio</literal>.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>type</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to a buffer that returns the attribute type retrieved by this
|
|
function.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garjm"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para>If successful, returns a <literal>NULL</literal> terminated
|
|
array of pointers to <olink targetptr="bdakg">berval</olink> structures, which,
|
|
in turn, contain pointers to the attribute’s binary values.</para>
|
|
</listitem>
|
|
<listitem><para>If unsuccessful or if no such attribute exists in the entry,
|
|
returns a <literal>NULL</literal> and sets the appropriate error code in the
|
|
<olink targetptr="bdakj">LDAP</olink> structure. To get the error code, call
|
|
the <olink targetptr="bdasq">ldap_get_lderrno</olink> function.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garjk"><title>Description</title>
|
|
<para>Use the <olink targetptr="bdaso">ldap_get_lang_values</olink> routine
|
|
if the attribute values are string values.</para></sect3>
|
|
<sect3 id="garko"><title>See Also</title>
|
|
<para><olink targetptr="bdarw">ldap_first_attribute</olink>, <olink targetptr="bdary">ldap_first_entry</olink>, <olink targetptr="bdaso">ldap_get_lang_values
|
|
</olink>, <olink targetptr="bdauc">ldap_next_entry</olink>, <olink targetptr="bdaua">ldap_next_attribute</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdasq"><title><function>ldap_get_lderrno</function></title>
|
|
<para>The <function>ldap_get_lderrno</function> function gets information
|
|
about the last error that occurred for an LDAP operation.</para>
|
|
<sect3 id="garkn"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_get_lderrno( LDAP *ld, char **m, char **s );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garkj"><title>Parameters</title>
|
|
<table frame="topbot" id="garky"><title><function>ldap_get_lderrno</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>m</literal></para></entry>
|
|
<entry>
|
|
<para>In the event of an <errorcode>LDAP_NO_SUCH_OBJECT</errorcode> error
|
|
return, this parameter contains the portion of the DN that identifies an existing
|
|
entry.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>s</literal></para></entry>
|
|
<entry>
|
|
<para>The text of the error message.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garjt"><title>Returns</title>
|
|
<para>The LDAP error code for the last operation.</para></sect3>
|
|
<sect3 id="garka"><title>Description</title>
|
|
<para><function>ldap_get_lderrno</function> gets information about the last
|
|
error that occurred for an LDAP operation. You can also call this function
|
|
to get error codes for functions that do not return errors, such as <olink targetptr="bdaua">ldap_next_attribute</olink>.</para></sect3>
|
|
<sect3 id="garkq"><title>Example</title>
|
|
<para><olink targetptr="ldap-get-lderrno-example">Example 21–22</olink> attempts
|
|
to add a new user to the directory. If the entry identified by a DN does not
|
|
exist, the server returns the portion of the DN that matches an existing entry;
|
|
this is the variable matched.</para>
|
|
<example id="ldap-get-lderrno-example"><title>Using <function>ldap_get_lderrno</function></title>
|
|
<programlisting>#include <ldap.h>
|
|
LDAP *ld;
|
|
char *dn = "uid=bjensen,ou=People,dc=example,dc=com";
|
|
LDAPMod **list_of_attrs;
|
|
char *matched;
|
|
int rc;
|
|
...
|
|
if ( ldap_add_s( ld, dn, list_of_attrs ) != LDAP_SUCCESS ) {
|
|
rc = ldap_get_lderrno( ld, &matched, NULL );
|
|
return( rc );
|
|
}
|
|
...</programlisting>
|
|
</example>
|
|
<para>In <olink targetptr="ldap-get-lderrno-example">Example 21–22</olink>,
|
|
if no organizational unit named <literal>People</literal> exists, the matched
|
|
variable is set to <literal>dc=example,dc=com</literal> .</para></sect3>
|
|
<sect3 id="garke"><title>See Also</title>
|
|
<para><olink targetptr="bdarq">ldap_err2string</olink>, <olink targetptr="bdaur">
|
|
ldap_perror</olink>, <olink targetptr="bdauv">ldap_result2error</olink>, <olink targetptr="bdavf">ldap_set_lderrno</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdasr"><title><function>ldap_getnextfilter</function></title>
|
|
<para>The <function>ldap_getnextfilter</function> function retrieves the next
|
|
filter that is appropriate for a given value.</para>
|
|
<sect3 id="garkx"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
LDAPFiltInfo * ldap_getnextfilter( LDAPFiltDesc *lfdp );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garjp"><title>Parameters</title>
|
|
<table frame="topbot" id="garki"><title><function>ldap_getnextfilter</function> Function
|
|
Parameter</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>lfdp</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdalf">LDAPFiltDesc</olink> structure.</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garjn"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para>If successful, returns a pointer to an <olink targetptr="bdalg">LDAPFiltInfo
|
|
</olink> structure.</para></listitem>
|
|
<listitem><para>If no more filters can be returned, returns a <literal>NULL</literal>.
|
|
</para></listitem>
|
|
<listitem><para>If unsuccessful, returns a <literal>NULL</literal>.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garkg"><title>Description</title>
|
|
<para>Call this function to get subsequent filters after calling <olink targetptr="bdasn">ldap_getfirstfilter</olink>.</para></sect3>
|
|
<sect3 id="garkt"><title>Example</title>
|
|
<para>See <olink targetptr="ldap-getfirstfilter-example">Example 21–21</olink>.
|
|
</para></sect3>
|
|
<sect3 id="garmi"><title>See Also</title>
|
|
<para><olink targetptr="bdasn">ldap_getfirstfilter</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdass"><title><function>ldap_get_option</function></title>
|
|
<para>The function <function>ldap_get_option</function> retrieves session
|
|
preferences from an <olink targetptr="bdakj">LDAP</olink> structure.</para>
|
|
<sect3 id="garle"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_get_option( LDAP *ld, int option, void *optdata );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garlx"><title>Parameters</title>
|
|
<table frame="topbot" id="garlg"><title><function>ldap_get_option</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>option</literal></para></entry>
|
|
<entry>
|
|
<para>Option that you want to retrieve. This parameter must be set to one
|
|
of the option values.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>optdata</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to the buffer in which the value of the option will be put.</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
<para><olink targetptr="ldap-get-options-options">Table 21–110</olink> describes
|
|
the options that you can retrieve with <function>ldap_get_option</function>.</para>
|
|
<table frame="topbot" id="ldap-get-options-options"><title>Options for the <function>
|
|
ldap_get_options</function> Function</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Option</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>LDAP_OPT_API_FEATURE_INFO</literal></para></entry>
|
|
<entry>
|
|
<para>Retrieves information about the revision of a supported LDAP feature.
|
|
This option is READ-ONLY and cannot be set.</para>
|
|
<para>The data type for the <literal>optdata</literal> parameter is <literal>(LDAPAPIFeatureInfo
|
|
*)</literal>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>LDAP_OPT_API_INFO</literal></para></entry>
|
|
<entry>
|
|
<para>Retrieves information about the API implementation at execution time
|
|
(API version, protocol version, the names of supported API extensions with
|
|
their vendor name version, etc.). For details on the structure returned, refer
|
|
to the <literal>ldap.h</literal> header file. This option is READ-ONLY and
|
|
cannot be set.</para>
|
|
<para>The data type for the <literal>optdata</literal> parameter is <literal>(LDAPAPIInfo
|
|
*)</literal>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>LDAP_OPT_CLIENT_CONTROLS</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
|
|
representing the LDAP v3 client controls you want sent with every request
|
|
by default.</para>
|
|
<para>The data type for the <literal>optdata</literal> parameter is <literal>(LDAPControl
|
|
***)</literal>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>LDAP_OPT_DESC</literal></para></entry>
|
|
<entry>
|
|
<para>Socket descriptor underlying the main LDAP connection. The <literal>LBER_SOCKET
|
|
</literal> data type depends on the platform that you are using:</para>
|
|
<itemizedlist>
|
|
<listitem><para><literal>int</literal> in UNIX.</para></listitem>
|
|
<listitem><para><literal>SOCKET</literal> in Windows.</para><para>The data
|
|
type for the <literal>optdata</literal> parameter is <literal>(LBER_SOCKET
|
|
*)</literal>.</para></listitem>
|
|
</itemizedlist>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>LDAP_OPT_DEREF</literal></para></entry>
|
|
<entry>
|
|
<para>Determines how aliases work during a search. <literal>optdata</literal> can
|
|
be one of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><literal>LDAP_DEREF_NEVER</literal> specifies that aliases
|
|
are never dereferenced.</para></listitem>
|
|
<listitem><para><literal>LDAP_DEREF_SEARCHING</literal> specifies that aliases
|
|
are dereferenced when searching under the base object (but not when finding
|
|
the base object).</para></listitem>
|
|
<listitem><para><literal>LDAP_DEREF_FINDING</literal> specifies that aliases
|
|
are dereferenced when finding the base object (but not when searching under
|
|
the base object).</para></listitem>
|
|
<listitem><para><literal>LDAP_DEREF_ALWAYS</literal> specifies that aliases
|
|
are always dereferenced when finding and searching under the base object.</para>
|
|
<para>The data type for the <literal>optdata</literal> parameter is <literal>(int
|
|
*)</literal>.</para></listitem>
|
|
</itemizedlist>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>LDAP_OPT_DNS_FN_PTRS</literal></para></entry>
|
|
<entry>
|
|
<para><emphasis role="strong">DEPRECATED OPTION:</emphasis> Lets you use alternate
|
|
DNS functions for getting the host entry of the LDAP server.</para>
|
|
<para>The data type for the <literal>optdata</literal> parameter is <literal>(struct
|
|
ldap_dns_fns *)</literal>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>LDAP_OPT_ERROR_NUMBER</literal></para></entry>
|
|
<entry>
|
|
<para>Retrieves the result code for the most recent LDAP error that occurred
|
|
in this session.</para>
|
|
<para>The data type for the <literal>optdata</literal> parameter is <literal>(int
|
|
*)</literal>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>LDAP_OPT_ERROR_STRING</literal></para></entry>
|
|
<entry>
|
|
<para>Retrieves the error message returned with the result code for the most
|
|
recent LDAP error that occurred in this session.</para>
|
|
<para>The data type for the <literal>optdata</literal> parameter is <literal>(char
|
|
**)</literal>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>LDAP_OPT_EXTRA_THREAD_FN_PTRS</literal></para></entry>
|
|
<entry>
|
|
<para>Lets you specify the locking and semaphore functions that you want called
|
|
when getting results from the server. </para>
|
|
<para>The data type for the <literal>optdata</literal> parameter is <literal>(struct
|
|
ldap_extra_thread_fns *)</literal>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>LDAP_OPT_HOST_NAME</literal></para></entry>
|
|
<entry>
|
|
<para>Sets the host name (or list of hosts) for the primary LDAP server.</para>
|
|
<para>The data type for the <literal>optdata</literal> parameter is <literal>(char
|
|
**)</literal>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>LDAP_OPT_IO_FN_PTRS</literal></para></entry>
|
|
<entry>
|
|
<para><emphasis role="strong">DEPRECATED OPTION:</emphasis> Lets you use alternate
|
|
communication stacks.</para>
|
|
<para>The data type for the <literal>optdata</literal> parameter is <literal>(struct
|
|
ldap_io_fns *)</literal>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>LDAP_OPT_MATCHED_DN</literal></para></entry>
|
|
<entry>
|
|
<para>Gets the matched DN value returned with the most recent LDAP error that
|
|
occurred for this session.</para>
|
|
<para>The data type for the <literal>optdata</literal> parameter is <literal>(char
|
|
**)</literal></para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>LDAP_OPT_MEMALLOC_FN_PTRS</literal></para></entry>
|
|
<entry>
|
|
<para>Gets a pointer to the callback structure which you previously set.</para>
|
|
<para>The data type for the <literal>optdata</literal> parameter is <literal>(struct
|
|
ldap_memalloc_fnsldap_io_fns *)</literal>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>LDAP_OPT_PROTOCOL_VERSION</literal></para></entry>
|
|
<entry>
|
|
<para>Version of the protocol supported by your client. You can specify either <literal>
|
|
LDAP_VERSION2</literal> or <literal>LDAP_VERSION3.</literal> If no version
|
|
is set, the default is <literal>LDAP_VERSION2</literal>. In order to use LDAP
|
|
v3 features, you need to set the protocol version to <literal>LDAP_VERSION3</literal>.
|
|
</para>
|
|
<para>The data type for the <literal>optdata</literal> parameter is <literal>(int
|
|
*)</literal>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>LDAP_OPT_REBIND_ARG</literal></para></entry>
|
|
<entry>
|
|
<para>Lets you set the last argument passed to the routine specified by <literal>
|
|
LDAP_OPT_REBIND_FN</literal>. You can also set this option by calling the <olink targetptr="bdavh">ldap_set_rebind_proc</olink> function.</para>
|
|
<para>The data type for the <literal>optdata</literal> parameter is <literal>(void
|
|
*)</literal>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>LDAP_OPT_REBIND_FN</literal></para></entry>
|
|
<entry>
|
|
<para>Lets you set the routine to be called when you need to authenticate
|
|
a connection with another LDAP server (for example, during the course of following
|
|
a referral). You can also set this option by calling the <olink targetptr="bdavh">
|
|
ldap_set_rebind_proc</olink> function.</para>
|
|
<para>The data type for the <literal>optdata</literal> parameter is <literal>(LDAP_REBINDPROC_CALLBACK
|
|
*)</literal>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>LDAP_OPT_RECONNECT</literal></para></entry>
|
|
<entry>
|
|
<para>If the connection to the server is lost, determines whether or not the
|
|
same connection handle should be used to reconnect to the server. By default,
|
|
this option is off. You handle failover with the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><literal>LDAP_OPT_ON</literal> specifies that the same connection
|
|
handle can be used to reconnect to the server.</para></listitem>
|
|
<listitem><para><literal>LDAP_OPT_OFF</literal> specifies that you want to
|
|
create a new connection handle to connect to the server.</para><para>The data
|
|
type for the <literal>optdata</literal> parameter is <literal>(int *)</literal>.
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>LDAP_OPT_REFERRALS</literal></para></entry>
|
|
<entry>
|
|
<para>Determines whether or not the client should follow referrals. By default,
|
|
the client follows referrals. <literal>optdata</literal> can be one of the
|
|
following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><literal>LDAP_OPT_ON</literal> specifies that the server should
|
|
follow referrals.</para></listitem>
|
|
<listitem><para><literal>LDAP_OPT_OFF</literal> specifies that the server
|
|
should not follow referrals.</para><para>The data type for the <literal>optdata</literal> parameter
|
|
is <literal>(int *)</literal>.</para></listitem>
|
|
</itemizedlist>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>LDAP_OPT_REFERRAL_HOP_LIMIT</literal></para></entry>
|
|
<entry>
|
|
<para>Maximum number of referrals the client should follow in a sequence.
|
|
In other words, the client can only be referred this number of times before
|
|
it gives up. By default, the maximum number of referrals that the client can
|
|
follow in a sequence is 5 for the initial connection. This limit does not
|
|
apply to individual requests that generate multiple referrals in parallel.</para>
|
|
<para>The data type for the <literal>optdata</literal> parameter is <literal>(int
|
|
*)</literal>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>LDAP_OPT_RESTART</literal></para></entry>
|
|
<entry>
|
|
<para>Determines whether or not LDAP I/O operations should be restarted automatically
|
|
if they are prematurely aborted. <literal>optdata</literal> can be one of
|
|
the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><literal>LDAP_OPT_ON</literal> specifies that I/O operations
|
|
should be restarted automatically.</para></listitem>
|
|
<listitem><para><literal>LDAP_OPT_OFF</literal> specifies that I/O operations
|
|
should not be restarted automatically.</para><para>The data type for the <literal>
|
|
optdata</literal> parameter is <literal>(int *)</literal>.</para></listitem>
|
|
</itemizedlist>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>LDAP_OPT_SERVER_CONTROLS</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
|
|
representing the LDAP v3 server controls you want sent with every request
|
|
by default. Typically, since controls are specific to the type of request,
|
|
you may want to pass the controls using operation-specific functions, such
|
|
as <olink targetptr="bdaqa">ldap_add_ext</olink>, instead.</para>
|
|
<para>The data type for the <literal>optdata</literal> parameter is <literal>(LDAPControl
|
|
***)</literal>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>LDAP_OPT_SIZELIMIT</literal></para></entry>
|
|
<entry>
|
|
<para>Maximum number of entries that should be returned by the server in search
|
|
results. The LDAP server may impose a smaller size limit than the limit you
|
|
specify as the server administrator also has the ability to set this limit.</para>
|
|
<para>The data type for the <literal>optdata</literal> parameter is <literal>(int
|
|
*)</literal>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>LDAP_OPT_SSL</literal></para></entry>
|
|
<entry>
|
|
<para>Determines whether or not SSL is enabled. <literal>optdata</literal> can
|
|
be one of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><literal>LDAP_OPT_ON</literal> specifies that SSL is enabled.</para>
|
|
</listitem>
|
|
<listitem><para><literal>LDAP_OPT_OFF</literal> specifies that SSL is disabled.</para>
|
|
<para>The data type for the <literal>optdata</literal> parameter is <literal>(int
|
|
*)</literal>.</para></listitem>
|
|
</itemizedlist>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>LDAP_OPT_THREAD_FN_PTRS</literal></para></entry>
|
|
<entry>
|
|
<para>Lets you specify the thread function pointers. </para>
|
|
<para>The data type for the <literal>optdata</literal> parameter is <literal>(struct
|
|
ldap_thread_fns *)</literal>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>LDAP_OPT_TIMELIMIT</literal></para></entry>
|
|
<entry>
|
|
<para>Maximum number of seconds that should be spent by the server when answering
|
|
a search request. The LDAP server may impose a shorter time limit than the
|
|
limit you specify as the server administrator also has the ability to set
|
|
this limit.</para>
|
|
<para>The data type for the <literal>optdata</literal> parameter is <literal>(int
|
|
*)</literal>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>LDAP_X_OPT_EXTIO_FN_PTRS</literal></para></entry>
|
|
<entry>
|
|
<para>Extended I/O function callback option.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>LDAP_X_OPT_CONNECT_TIMEOUT</literal></para></entry>
|
|
<entry>
|
|
<para>Value of a time out (expressed in milliseconds) for non-blocking connect
|
|
call.</para>
|
|
<para>The data type for the <literal>optdata</literal> parameter is <literal>(int
|
|
*)</literal>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>LDAP_X_OPT_SOCKBUF</literal></para></entry>
|
|
<entry>
|
|
<para>Socket buffer structure associated to the LDAP connection.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
<para>See also <citerefentry><refentrytitle>ldap_get_option</refentrytitle>
|
|
<manvolnum>3LDAP</manvolnum></citerefentry> for details on <literal>LDAP_OPT_X_SASL*
|
|
</literal> parameters.</para></sect3>
|
|
<sect3 id="garmm"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para><literal>-1</literal> if unsuccessful.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garli"><title>Examples</title>
|
|
<para><olink targetptr="ldap-get-options-example">Example 21–23</olink> gets
|
|
the session preference for the maximum number of entries to be returned from
|
|
search operations.</para>
|
|
<example id="ldap-get-options-example"><title>Using <function>ldap_get_option</function></title>
|
|
<programlisting>#include <ldap.h>
|
|
...
|
|
LDAP *ld;
|
|
int max_ret;
|
|
...
|
|
/* Get the maximum number of entries returned */
|
|
if (ldap_get_option, LDAP_OPT_SIZELIMIT, &max_ret) != LDAP_SUCCESS) {
|
|
ldap_perror( ld, "ldap_get_option" );
|
|
return( 1 );
|
|
}</programlisting>
|
|
</example>
|
|
<para><olink targetptr="ldap-get-options-example">Example 21–23</olink> could
|
|
also include the following two small sections of code that show how to use
|
|
the <literal>LDAP_OPT_API_FEATURE_INFO</literal> and the <literal>LDAP_OPT_API_INFO
|
|
</literal> options, respectively.</para>
|
|
<example id="garlu"><title>Using <structname>LDAP_OPT_API_FEATURE_INFO</structname> and <structname>
|
|
LDAP_OPT_API_INFO</structname></title>
|
|
<programlisting>LDAPIIFeatureInfo ldfi;
|
|
ldfi.ldapaif_info_version = LDAP_FEATURE_INFO_VERSION;
|
|
ldfi.ldapaif_name = "VIRTUAL_LIST_VIEW";
|
|
if (ldap_get_option(NULL, LDAP_OPT_API_FEATURE_INFO, &ldfi)==0) {
|
|
/* use the info here */ }
|
|
|
|
LDAPIInfo ldai;
|
|
ldai.ldapiai_info_version = LDAP_API_INFO_VERSION;
|
|
if (ldap_get_option( NULL, LDAP_OPT_API_INFO, &ldia ) == 0) {
|
|
/* use the ldai info here */
|
|
}</programlisting>
|
|
</example>
|
|
</sect3>
|
|
<sect3 id="garmf"><title>See Also</title>
|
|
<para><olink targetptr="bdasv">ldap_init</olink>, <olink targetptr="bdaxr">prldap_init
|
|
</olink> (IPv6), <olink targetptr="bdavg">ldap_set_option</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdast"><title><function>ldap_get_values</function></title>
|
|
<para>The <function>ldap_get_values</function> function returns a <literal>NULL</literal> terminated
|
|
array of an attribute’s string values for a given entry.</para>
|
|
<sect3 id="garmv"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
char ** ldap_get_values( LDAP *ld, LDAPMessage *entry,
|
|
const char *target );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garlt"><title>Parameters</title>
|
|
<table frame="topbot" id="garmt"><title><function>ldap_get_values</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameters</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>entry</literal></para></entry>
|
|
<entry>
|
|
<para>Result returned by the <olink targetptr="bdauu">ldap_result</olink> or <olink targetptr="bdavb">ldap_search_s</olink> function.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>target</literal></para></entry>
|
|
<entry>
|
|
<para>Attribute returned by <olink targetptr="bdarw">ldap_first_attribute</olink> or <olink targetptr="bdaua">ldap_next_attribute</olink>, or the attribute as a literal
|
|
string, such as <literal>jpegPhoto</literal> or <literal>audio</literal>.</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garms"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para>If successful, returns a <literal>NULL</literal> terminated
|
|
array of the attribute’s values.</para></listitem>
|
|
<listitem><para>If unsuccessful or if no such attribute exists in the entry,
|
|
returns a <literal>NULL</literal> and sets the appropriate error code in the
|
|
<olink targetptr="bdakj">LDAP</olink> structure. To get the error code, call
|
|
the <olink targetptr="bdasq">ldap_get_lderrno</olink> function.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garmk"><title>Description</title>
|
|
<para>Use the <olink targetptr="bdasu">ldap_get_values_len</olink> function
|
|
if the attribute values are binary.</para></sect3>
|
|
<sect3 id="garmq"><title>Example</title>
|
|
<para><olink targetptr="ldap-get-values-example">Example 21–25</olink> gets
|
|
and prints the values of an attribute in an entry. This example assumes that
|
|
all attributes have string values.</para>
|
|
<example id="ldap-get-values-example"><title>Using <function>ldap_get_values</function></title>
|
|
<programlisting>#include <stdio.h>
|
|
#include <ldap.h>
|
|
...
|
|
LDAP *ld;
|
|
LDAPMessage *result, *e;
|
|
BerElement *ber;
|
|
char *a;
|
|
char **vals;
|
|
char *my_searchbase = "dc=example,dc=com";
|
|
char *my_filter = "(sn=Jensen)";
|
|
int i;
|
|
...
|
|
/* Search the directory */
|
|
if ( ldap_search_s( ld, my_searchbase, LDAP_SCOPE_SUBTREE, my_filter,
|
|
NULL, 0, &result ) != LDAP_SUCCESS ) {
|
|
ldap_perror( ld, "ldap_search_s" );
|
|
return( 1 );
|
|
}
|
|
|
|
/* Get the first matching entry.*/
|
|
e = ldap_first_entry( ld, result );
|
|
|
|
/* Get the first matching attribute */
|
|
a = ldap_first_attribute( ld, e, &ber );
|
|
|
|
/* Get the values of the attribute */
|
|
if ( ( vals = ldap_get_values( ld, e, a ) ) != NULL ) {
|
|
for ( i = 0; vals[i] != NULL; i++ ) {
|
|
/* Print the name of the attribute and each value */
|
|
printf( "%s: %s\n", a, vals[i] );
|
|
}
|
|
/* Free the attribute values from memory when done. */
|
|
ldap_value_free( vals );
|
|
}
|
|
...</programlisting>
|
|
</example>
|
|
</sect3>
|
|
<sect3 id="garlm"><title>See Also</title>
|
|
<para><olink targetptr="bdary">ldap_first_entry</olink>, <olink targetptr="bdarw">ldap_first_attribute</olink>, <olink targetptr="bdasu">ldap_get_values_len
|
|
</olink>, <olink targetptr="bdauc">ldap_next_entry</olink>, <olink targetptr="bdaua">ldap_next_attribute</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdasu"><title><function>ldap_get_values_len</function></title>
|
|
<para>The <function>ldap_get_values_len</function> function returns a <literal>NULL
|
|
</literal> terminated array of pointers to <olink targetptr="bdakg">berval</olink> structures,
|
|
each containing the length and pointer to a binary value of an attribute for
|
|
a given entry.</para>
|
|
<sect3 id="garmg"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
struct berval ** ldap_get_values_len( LDAP *ld,
|
|
LDAPMessage *entry, const char *target );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garlo"><title>Parameters</title>
|
|
<table frame="topbot" id="garlj"><title><function>ldap_get_values_len</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>entry</literal></para></entry>
|
|
<entry>
|
|
<para>Result returned by the <olink targetptr="bdauu">ldap_result</olink> or <olink targetptr="bdavb">ldap_search_s</olink> function.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>target</literal></para></entry>
|
|
<entry>
|
|
<para>Attribute returned by <olink targetptr="bdarw">ldap_first_attribute</olink> or <olink targetptr="bdaua">ldap_next_attribute</olink>, or the attribute as a literal
|
|
string, such as <literal>jpegPhoto</literal> or <literal>audio</literal>.</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garmd"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para>If successful, returns a <literal>NULL</literal> terminated
|
|
array of pointers to <structname>berval</structname> structures, which in
|
|
turn contains pointers to the attribute’s binary values.</para></listitem>
|
|
<listitem><para>If unsuccessful or if no such attribute exists in the entry,
|
|
returns <literal>NULL</literal> and sets the appropriate error code in the
|
|
<olink targetptr="bdakj">LDAP</olink> structure. To get the error code, call
|
|
the <olink targetptr="bdasq">ldap_get_lderrno</olink> function.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garld"><title>Description</title>
|
|
<para>Use the <olink targetptr="bdast">ldap_get_values</olink> routine if
|
|
the attribute values are string values.</para></sect3>
|
|
<sect3 id="garlz"><title>Example</title>
|
|
<para><olink targetptr="ldap-get-values-len-example">Example 21–26</olink>
|
|
gets the first value of the <literal>jpegPhoto</literal> attribute and saves
|
|
the JPEG data to a file.</para>
|
|
<example id="ldap-get-values-len-example"><title><function>ldap_get_values_len</function></title>
|
|
<programlisting>#include <stdio.h>
|
|
#include <ldap.h>
|
|
...
|
|
LDAP *ld;
|
|
LDAPMessage *result, *e;
|
|
BerElement *ber;
|
|
struct berval photo_data;
|
|
struct berval **list_of_photos;
|
|
FILE *out;
|
|
char *my_searchbase = "dc=example,dc=com";
|
|
char *my_filter = "(sn=Jensen)";
|
|
...
|
|
/* Search the directory */
|
|
if ( ldap_search_s( ld, my_searchbase, LDAP_SCOPE_SUBTREE, my_filter, NULL,
|
|
0, &result ) != LDAP_SUCCESS ) {
|
|
ldap_perror( ld, "ldap_search_s" );
|
|
return( 1 );
|
|
}
|
|
|
|
/* Get the first matching entry.*/
|
|
e = ldap_first_entry( ld, result );
|
|
|
|
/* Get the value of the jpegPhoto attribute */
|
|
if ( ( list_of_photos = ldap_get_values_len( ld, e, "jpegPhoto" ) ) !=
|
|
NULL ) {
|
|
/* Prepare to write the JPEG data to a file */
|
|
if ( ( out = fopen( "photo.jpg", "wb" ) ) == NULL ) {
|
|
perror( "fopen" );
|
|
return( 1 );
|
|
}
|
|
/* Get the first JPEG */
|
|
photo_data = *list_of_photos[0];
|
|
/* Write the JPEG data to a file */
|
|
fwrite( photo_data.bv_val, photo_data.bv_len, 1, out );
|
|
fclose( out );
|
|
/* Free the attribute values from memory when done. */
|
|
ldap_value_free_len( list_of_photos );
|
|
}
|
|
...</programlisting>
|
|
</example>
|
|
</sect3>
|
|
<sect3 id="garll"><title>See Also</title>
|
|
<para><olink targetptr="bdary">ldap_first_entry</olink>, <olink targetptr="bdarw">ldap_first_attribute</olink>, <olink targetptr="bdast">ldap_get_values
|
|
</olink>, <olink targetptr="bdauc">ldap_next_entry</olink>, <olink targetptr="bdaua">ldap_next_attribute</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdasv"><title><function>ldap_init</function></title>
|
|
<para>The <function>ldap_init</function> function initializes a session with
|
|
an LDAP server and returns an <olink targetptr="bdakj">LDAP</olink> structure
|
|
that represents the context of the connection to that server.</para>
|
|
<sect3 id="garlk"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
LDAP * ldap_init( const char *defhost, int defport );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garmh"><title>Parameters</title>
|
|
<table frame="topbot" id="garmo"><title><function>ldap_init</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>defhost</literal></para></entry>
|
|
<entry>
|
|
<para>Space-delimited list of one or more host names (or IP address in dotted
|
|
notation, such as "141.211.83.36") of the LDAP servers that you want the LDAP
|
|
client to connect to. The names can be in <replaceable>hostname</replaceable>:<replaceable>
|
|
portnumber</replaceable> format (in which case, <replaceable>portnumber</replaceable> overrides
|
|
the port number specified by the <literal>defport</literal> argument.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>defport</literal></para></entry>
|
|
<entry>
|
|
<para>Default port number of the LDAP server. To specify the standard LDAP
|
|
port (port 389), use <literal>LDAP_PORT</literal> as the value for this parameter.
|
|
</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garmj"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para>If successful, returns a pointer to an <olink targetptr="bdakj">LDAP
|
|
</olink> structure.</para></listitem>
|
|
<listitem><para>If unsuccessful, returns a <literal>NULL</literal>.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garlf"><title>Description</title>
|
|
<para>The <function>ldap_init</function> function initializes a session with
|
|
an LDAP server by allocating an <olink targetptr="bdakj">LDAP</olink> structure
|
|
containing information about the session including the host name and port
|
|
of the LDAP server, preferences for the session (such as the maximum number
|
|
of entries to return in a search), and the error code of the last LDAP operation
|
|
performed. The <olink targetptr="bdakj">LDAP</olink> structure defaults to
|
|
LDAP v2. It is highly recommended to set it to LDAP v3 using the <olink targetptr="bdavg">ldap_set_option</olink>.</para>
|
|
<note><para><olink targetptr="bdasv">ldap_init</olink> does not open a connection
|
|
to the LDAP server. The actual connection opening will occur when the first
|
|
operation is attempted. Certain fields in the <olink targetptr="bdakj">LDAP</olink> structure
|
|
can be set using <olink targetptr="bdavg">ldap_set_option</olink>.</para></note>
|
|
<para>You can specify a list of LDAP servers to which you want to attempt
|
|
to connect by passing a space-delimited list of the host names as the <literal>defhost
|
|
</literal> argument. Your client will attempt to connect to the first LDAP
|
|
server in the list. If the attempt fails, your client will attempt to connect
|
|
to the next LDAP server in the list. In <olink targetptr="ldap-init-example">Example
|
|
21–27</olink> <literal>ld1.example.com</literal>, port <literal>389</literal>.
|
|
If that server does not respond, the client will attempt to connect to the
|
|
LDAP server on <literal>ld2.example.com</literal>, port <literal>389</literal>.
|
|
If that server does not respond, the client will use the server on <literal>ld3.example.com
|
|
</literal> , port <literal>389</literal>.</para>
|
|
<example id="ldap-init-example"><title>Space-Delimited List for <function>ldap_init
|
|
</function></title>
|
|
<programlisting>...
|
|
LDAP *ld
|
|
...
|
|
ld = ldap_init( "ld1.example.com ld2.example.com ld3.example.com",
|
|
LDAP_PORT );</programlisting>
|
|
</example>
|
|
<para>If any of the servers do not use the default port specified by the <literal>
|
|
defport</literal> argument, use the <replaceable>hostname</replaceable>: <replaceable>
|
|
portnumber</replaceable> format to specify the server name. In <olink targetptr="ldap-init-example">Example 21–27</olink> <literal>ld1.example.com
|
|
</literal>, port <literal>389</literal>. If that server does not respond,
|
|
the client will attempt to connect to the LDAP server on <literal>ld2.example.com
|
|
</literal>, port <literal>1389</literal>.</para>
|
|
<example id="ldap-init-example2"><title><function>ldap_init</function> Example
|
|
Using Variable Argument</title>
|
|
<programlisting>...
|
|
LDAP *ld
|
|
...
|
|
ld = ldap_init( "ld1.example.com ld2.example.com:1389", LDAP_PORT );</programlisting>
|
|
</example>
|
|
<note><para>If you are connecting to a secure LDAP server over SSL, you should
|
|
be calling the <olink targetptr="bdavs">ldapssl_init</olink> function.</para>
|
|
</note>
|
|
</sect3>
|
|
<sect3 id="garmr"><title>Example</title>
|
|
<para><olink targetptr="ldap-init-example3">Example 21–29</olink> initializes
|
|
a session with the LDAP server at <literal>ldap.example.com:389</literal>,
|
|
and sets a session preference that identifies the client as an LDAP v3 client.</para>
|
|
<example id="ldap-init-example3"><title>Using <function>ldap_init</function></title>
|
|
<programlisting>#include <ldap.h>
|
|
...
|
|
LDAP *ld;
|
|
|
|
/* Specify the host name of the LDAP server. */
|
|
char *ldap_host = "ldap.example.com";
|
|
|
|
/* Because the LDAP server is running on the standard LDAP port (port 389),
|
|
* you can use LDAP_PORT to identify the port number. */
|
|
int ldap_port = LDAP_PORT;
|
|
...
|
|
/* Initialize the session with ldap.example.com:389 */
|
|
/* Use prldap_init() for IPv6 support. */
|
|
if ( ( ld = ldap_init( ldap_host, ldap_port ) ) == NULL ) {
|
|
perror( "ldap_init" );
|
|
return( 1 );
|
|
}
|
|
|
|
/* Specify the LDAP version supported by the client. */
|
|
version = LDAP_VERSION3;
|
|
ldap_set_option( ld, LDAP_OPT_PROTOCOL_VERSION, &version );
|
|
|
|
...
|
|
/* Subsequent calls that authenticate to the LDAP server. */
|
|
...</programlisting>
|
|
</example>
|
|
</sect3>
|
|
<sect3 id="garly"><title>See Also</title>
|
|
<para><olink targetptr="bdaxr">prldap_init</olink> (IPv6), <olink targetptr="bdawh">ldap_unbind</olink>, <olink targetptr="bdawi">ldap_unbind_s</olink> , <olink targetptr="bdavi">ldap_simple_bind</olink>, <olink targetptr="bdavj">ldap_simple_bind_s
|
|
</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdasw"><title><function>ldap_init_getfilter</function></title>
|
|
<para>The <function>ldap_init_getfilter</function> function reads a valid
|
|
LDAP filter configuration file (such as <literal>ldapfilter.conf</literal>)
|
|
and returns a pointer to an <olink targetptr="bdalf">LDAPFiltDesc</olink> structure.
|
|
</para>
|
|
<note><para><literal>ldapfilter.conf</literal>, the sample LDAP filter configuration
|
|
file located in <literal>lib/ldapcsdk/etc</literal> directory, can be used
|
|
in context with <olink targetptr="bdasw">ldap_init_getfilter</olink> .</para>
|
|
</note>
|
|
<sect3 id="garmu"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
LDAPFiltDesc * ldap_init_getfilter( char *fname );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garln"><title>Parameters</title>
|
|
<table frame="topbot" id="garlp"><title><function>ldap_init_getfilter</function> Function
|
|
Parameter</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>fname</literal></para></entry>
|
|
<entry>
|
|
<para>Name of the LDAP filter configuration file to use.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garlq"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para>If successful, returns a pointer to an <olink targetptr="bdalf">LDAPFiltDesc
|
|
</olink> structure.</para></listitem>
|
|
<listitem><para>If unsuccessful (for example, if there is an error reading
|
|
the file), returns a <literal>NULL</literal>.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garls"><title>Example</title>
|
|
<para><olink targetptr="load-config-example">Example 21–30</olink>
|
|
loads a filter configuration file named <literal>myfilters.conf</literal> into
|
|
memory.</para>
|
|
<example id="load-config-example"><title>Loading a Filter Configuration File</title>
|
|
<programlisting>#include <ldap.h>
|
|
...
|
|
LDAPFiltDesc *lfdp;
|
|
char *filter_file = "myfilters.conf";
|
|
...
|
|
lfdp = ldap_init_getfilter( filter_file );
|
|
...</programlisting>
|
|
</example>
|
|
</sect3>
|
|
<sect3 id="garmn"><title>See Also</title>
|
|
<para><olink targetptr="bdasx">ldap_init_getfilter_buf</olink>, <olink targetptr="bdasm">ldap_getfilter_free</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdasx"><title><function>ldap_init_getfilter_buf</function></title>
|
|
<para>The <function>ldap_init_getfilter_buf</function> function reads LDAP
|
|
filter configuration information from a buffer and returns a pointer to an
|
|
<olink targetptr="bdalf">LDAPFiltDesc</olink> structure.</para>
|
|
<sect3 id="garma"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
LDAPFiltDesc * ldap_init_getfilter_buf(char *buf, long buflen );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garml"><title>Parameters</title>
|
|
<table frame="topbot" id="garlh"><title><function>ldap_init_getfilter_buf</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>buf</literal></para></entry>
|
|
<entry>
|
|
<para>Buffer containing LDAP filter configuration information.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>buflen</literal></para></entry>
|
|
<entry>
|
|
<para>Size of the buffer</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garmp"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para>If successful, returns a pointer to an <olink targetptr="bdalf">LDAPFiltDesc
|
|
</olink> structure.</para></listitem>
|
|
<listitem><para>If unsuccessful—for example, if there is an error reading
|
|
the file—returns a <literal>NULL</literal>.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garlc"><title>Example</title>
|
|
<para><olink targetptr="ldap-init-getfilter-example">Example 21–31</olink>
|
|
copies the following filter configuration to a buffer in memory and uses this
|
|
buffer to fill an <olink targetptr="bdalf">LDAPFiltDesc</olink> structure.</para>
|
|
<programlisting>"ldap-example"
|
|
"@" " " "(mail=%v)" "email address"
|
|
"(mail=%v*)" "start of email address"</programlisting>
|
|
<example id="ldap-init-getfilter-example"><title>Using <function>ldap_init_getfilter
|
|
</function></title>
|
|
<programlisting>#include <string.h>
|
|
#include <ldap.h>
|
|
...
|
|
LDAPFiltDesc *lfdp;
|
|
char filtbuf[ 1024 ];
|
|
...
|
|
/* Create the filter config buffer */
|
|
strcpy( filtbuf, "\"ldap-example\"\n" );
|
|
strcat( filtbuf, " \"@\"\t\" \"\t\"(mail=%v)\"\t\"email address\"\n" );
|
|
strcat( filtbuf, " \t\t\"(mail=%v*)\"\t\"start of email address\"\n" );
|
|
lfdp = ldap_init_getfilter( filtbuf, strlen( filtbuf ) );
|
|
...</programlisting>
|
|
</example>
|
|
</sect3>
|
|
<sect3 id="garlr"><title>See Also</title>
|
|
<para><olink targetptr="bdasw">ldap_init_getfilter</olink>, <olink targetptr="bdasm">ldap_getfilter_free</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdasy"><title><function>ldap_init_searchprefs</function></title>
|
|
<para>The <function>ldap_init_searchprefs</function> function reads a sequence
|
|
of search preference configurations from a valid LDAP <literal>searchpref</literal> configuration
|
|
file.</para>
|
|
<sect3 id="garlv"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_init_searchprefs( char *file, struct ldap_searchobj **solistp );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garmb"><title>Parameters</title>
|
|
<table frame="topbot" id="garmc"><title><function>ldap_init_searchprefs</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>file</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to a valid LDAP <literal>searchpref</literal> configuration
|
|
file.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>solistp</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to a list of search preference data structures.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garlw"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><literal>LDAP_SEARCHPREF_ERR_VERSION</literal>.</para>
|
|
</listitem>
|
|
<listitem><para><literal>LDAP_SEARCHPREF_ERR_MEM</literal> if there is a memory
|
|
allocation problem.</para></listitem>
|
|
<listitem><para>Upon success, <literal>0</literal> is returned and <literal>solistp
|
|
</literal> is set to point to a list of search preference data structures.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garme"><title>Description</title>
|
|
<para><function>ldap_init_searchprefs</function> provides a standard way to
|
|
access LDAP search preference configuration data.</para>
|
|
<note><para>LDAP search preference configurations are typically used by LDAP
|
|
client programs to specify which attributes a user may search by, labels for
|
|
the attributes, and LDAP filters and scopes associated with those searches.
|
|
Client software presents these choices to a user, who can then specify the
|
|
type of search to be performed.</para></note>
|
|
</sect3>
|
|
<sect3 id="garog"><title>See Also</title>
|
|
<para><olink targetptr="bdasf">ldap_free_searchprefs</olink>, <olink targetptr="bdasz">ldap_init_searchprefs_buf</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdasz"><title><function>ldap_init_searchprefs_buf</function></title>
|
|
<para>The <function>ldap_init_searchprefs_buf</function> function reads a
|
|
sequence of search preference configurations from the parameter, <literal>buf</literal>.
|
|
</para>
|
|
<sect3 id="garnx"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_init_searchprefs_buf( char *buf, long buflen,
|
|
struct ldap_searchobj **solistp );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garoa"><title>Parameters</title>
|
|
<table frame="topbot" id="garnr"><title><function>ldap_init_searchprefs_buf</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>buf</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to data in the format defined for an LDAP search preference
|
|
configuration file.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>buflen</literal></para></entry>
|
|
<entry>
|
|
<para>The size of <literal>buf</literal>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>solistp</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to a list of search preference data structures.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garok"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><literal>LDAP_SEARCHPREF_ERR_VERSION</literal> if <literal>buf</literal> points
|
|
to data that is newer than can be handled.</para></listitem>
|
|
<listitem><para><literal>LDAP_SEARCHPREF_ERR_MEM</literal> if there is a memory
|
|
allocation problem.</para></listitem>
|
|
<listitem><para>Upon success, <literal>0</literal> is returned and <literal>solistp
|
|
</literal> is set to point to a list of search preference data structures.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garnq"><title>Description</title>
|
|
<para><function>ldap_init_searchprefs_buf</function> reads a sequence of search
|
|
preference configurations from <literal>buf</literal>.</para>
|
|
<note><para>LDAP search preference configurations are typically used by LDAP
|
|
client programs to specify which attributes a user may search by, labels for
|
|
the attributes, and LDAP filters and scopes associated with those searches.
|
|
Client software presents these choices to a user, who can then specify the
|
|
type of search to be performed.</para></note>
|
|
</sect3>
|
|
<sect3 id="garna"><title>See Also</title>
|
|
<para><olink targetptr="bdasy">ldap_init_searchprefs</olink>, <olink targetptr="bdasf">ldap_free_searchprefs</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdata"><title><function>ldap_init_templates</function></title>
|
|
<para>The <function>ldap_init_templates</function> function reads a sequence
|
|
of templates from a valid LDAP template configuration file.</para>
|
|
<sect3 id="garny"><title>Syntax</title>
|
|
<programlisting>#include <disptmpl.h>
|
|
int ldap_init_templates( char *file, struct ldap_disptmpl **tmpllistp );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garng"><title>Parameters</title>
|
|
<table frame="topbot" id="garoi"><title><function>ldap_init_templates</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>file</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to a valid LDAP template configuration file.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>tmpllistp</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to a list of template data structures.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garoh"><title>Returns</title>
|
|
<itemizedlist>
|
|
<listitem><para>If successful, <literal>0</literal> is returned and <literal>tmpllistp
|
|
</literal> is configured.</para></listitem>
|
|
<listitem><para>Upon error:</para>
|
|
<itemizedlist>
|
|
<listitem><para><literal>LDAP_TMPL_ERR_VERSION</literal> if <literal>buf</literal> points
|
|
to data that is newer than can be handled.</para></listitem>
|
|
<listitem><para><literal>LDAP_TMPL_ERR_MEM</literal> if there is a memory
|
|
allocation problem.</para></listitem>
|
|
<listitem><para><literal>LDAP_TMPL_ERR_SYNTAX</literal> if there is a problem
|
|
with the format of the templates buffer or file.</para></listitem>
|
|
<listitem><para><literal>LDAP_TMPL_ERR_FILE</literal> if the file cannot be
|
|
read.</para></listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garnp"><title>Description</title>
|
|
<para><function>ldap_init_templates</function> reads a sequence of templates
|
|
from a valid LDAP template configuration file. Each template defined in the
|
|
file is an <literal>ldap_disptmpl</literal> structure.</para></sect3>
|
|
<sect3 id="garob"><title>See Also</title>
|
|
<para><olink targetptr="bdatb">ldap_init_templates_buf</olink>, <olink targetptr="bdash">ldap_free_templates</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdatb"><title><function>ldap_init_templates_buf</function></title>
|
|
<para>The <function>ldap_init_templates_buf</function> function reads a sequence
|
|
of templates from a buffer.</para>
|
|
<sect3 id="garnb"><title>Syntax</title>
|
|
<programlisting>#include <disptmpl.h>
|
|
int ldap_init_templates_buf( char *buf, long buflen,
|
|
struct ldap_disptmpl **tmpllistp );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garnw"><title>Parameters</title>
|
|
<table frame="topbot" id="garoq"><title><function>ldap_init_templates_buf</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>buf</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to data in the format defined for a valid LDAP template configuration
|
|
file.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>buflen</literal></para></entry>
|
|
<entry>
|
|
<para>The size of <literal>buf</literal>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>tmpllistp</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to a list of template data structures.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garnm"><title>Returns</title>
|
|
<itemizedlist>
|
|
<listitem><para>If successful, <literal>0</literal> is returned and <literal>tmpllistp
|
|
</literal> is configured.</para></listitem>
|
|
<listitem><para>Upon error:</para>
|
|
<itemizedlist>
|
|
<listitem><para><literal>LDAP_TMPL_ERR_VERSION</literal> if <literal>buf</literal> points
|
|
to data that is newer than can be handled.</para></listitem>
|
|
<listitem><para><literal>LDAP_TMPL_ERR_MEM</literal> if there is a memory
|
|
allocation problem.</para></listitem>
|
|
<listitem><para><literal>LDAP_TMPL_ERR_SYNTAX</literal> if there is a problem
|
|
with the format of the templates buffer or file.</para></listitem>
|
|
<listitem><para><literal>LDAP_TMPL_ERR_FILE</literal> if the file cannot be
|
|
read.</para></listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garnt"><title>Description</title>
|
|
<para>The <function>ldap_init_templates_buf</function> function reads a sequence
|
|
of templates from a buffer.</para></sect3>
|
|
<sect3 id="garor"><title>See Also</title>
|
|
<para><olink targetptr="bdata">ldap_init_templates</olink>, <olink targetptr="bdash">ldap_free_templates</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdatc"><title><function>ldap_is_dns_dn</function></title>
|
|
<note><para>This function is deprecated and should not be used. It is included
|
|
in <literal>ldap-to-be-deprecated.h</literal> for backward-compatibility.</para>
|
|
</note>
|
|
<para>The <function>ldap_is_dns_dn</function> function determines whether
|
|
a DN string is of the experimental DNS-style DN (generally in the form of
|
|
an RFC 822 email address) or the RFC 1779 formatted DN.</para>
|
|
<sect3 id="garnl"><title>Description</title>
|
|
<para>This function is specific to LDAP v2 and should not be used when dealing
|
|
with LDAP v3 servers or data.</para>
|
|
<note><para>More information can be found in <citetitle>RFC 1779 - A String
|
|
Representation of Distinguished Names</citetitle> (<ulink
|
|
url="http://www.faqs.org/rfcs/rfc1779.html" type="text_url"></ulink>) and <citetitle>
|
|
RFC 822 - Standard for the Format of ARPA Internet Text Messages</citetitle> (<ulink
|
|
url="http://www.faqs.org/rfcs/rfc822.html" type="text_url"></ulink>).</para>
|
|
</note>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="bdatd"><title><function>ldap_is_ldap_url</function></title>
|
|
<para>The <function>ldap_is_ldap_url</function> function determines whether
|
|
or not a URL is an LDAP URL.</para>
|
|
<sect3 id="garnd"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_is_ldap_url( const char *url );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garol"><title>Parameters</title>
|
|
<table frame="topbot" id="garmy"><title><function>ldap_is_ldap_url</function> Function
|
|
Parameter</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>url</literal></para></entry>
|
|
<entry>
|
|
<para>The URL that you want to check.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garop"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><literal>1</literal> if the URL is an LDAP URL.</para>
|
|
</listitem>
|
|
<listitem><para><literal>0</literal> if the URL is not an LDAP URL.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garmw"><title>Description</title>
|
|
<para>The <function>ldap_is_ldap_url</function> function determines whether
|
|
or not a URL is an LDAP URL. An LDAP URL is a URL with the protocol set to <literal>
|
|
ldap://</literal> (or <literal>ldaps://</literal>, if the server is communicating
|
|
over a SSL connection).</para></sect3>
|
|
<sect3 id="garnc"><title>Example</title>
|
|
<para><olink targetptr="ldap-is-ldap-url-example">Example 21–32</olink> determines
|
|
if a URL is a LDAP URL.</para>
|
|
<example id="ldap-is-ldap-url-example"><title>Using <function>ldap_is_ldap_url</function></title>
|
|
<programlisting>#include <stdio.h>
|
|
#include <ldap.h>
|
|
...
|
|
char *my_url = "ldap://ldap.sun.com/dc=example,dc=com";
|
|
...
|
|
if ( ldap_is_ldap_url( my_url ) != 0 ) {
|
|
printf( "%s is an LDAP URL.\n", my_url );
|
|
} else {
|
|
printf( "%s is not an LDAP URL.\n", my_url );
|
|
}
|
|
...</programlisting>
|
|
</example>
|
|
</sect3>
|
|
<sect3 id="garnj"><title>See Also</title>
|
|
<para><olink targetptr="bdawk">ldap_url_parse</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdate"><title><function>ldap_keysort_entries</function></title>
|
|
<para>The <function>ldap_keysort_entries</function> function is used for sorting
|
|
entries.</para>
|
|
<sect3 id="garod"><title>Syntax</title>
|
|
<programlisting>#include <ldap-extension.h>
|
|
int ldap_keysort_entries( LDAP *ld, LDAPMessage **chain,
|
|
void *arg, LDAP_KEYGEN_CALLBACK *gen, LDAP_KEYCMP_CALLBACK *cmp,
|
|
LDAP_KEYFREE_CALLBACK *fre );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garoe"><title>Parameters</title>
|
|
<table frame="topbot" id="garns"><title><function>ldap_keysort_entries</function> Function
|
|
Parameter</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>chain</literal></para></entry>
|
|
<entry>
|
|
<para>Chain of entries returned by the <olink targetptr="bdauu">ldap_result</olink> or <olink targetptr="bdavb">ldap_search_s</olink> function.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>arg</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an additional argument that you want to pass.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>gen</literal></para></entry>
|
|
<entry>
|
|
<para>Callback used to generate the key(s) for sorting once the compare function
|
|
has been applied.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>cmp</literal></para></entry>
|
|
<entry>
|
|
<para>Comparison function used when sorting the values.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>fre</literal></para></entry>
|
|
<entry>
|
|
<para>Callback used to free the key once the compare function has been applied.</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garnk"><title>See Also</title>
|
|
<para><olink targetptr="bdalu">LDAP_KEYGEN_CALLBACK</olink>, <olink targetptr="bdals">LDAP_KEYCMP_CALLBACK</olink>, <olink targetptr="bdalt">LDAP_KEYFREE_CALLBACK
|
|
</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdatf"><title><function>ldap_memcache_destroy</function></title>
|
|
<para>The <function>ldap_memcache_destroy</function> function frees an <olink targetptr="bdalx">LDAPMemCache</olink> structure from memory.</para>
|
|
<sect3 id="garnv"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
void ldap_memcache_destroy( LDAPMemCache *cache );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garon"><title>Parameters</title>
|
|
<table frame="topbot" id="garmx"><title><function>ldap_memcache_destroy</function> Function
|
|
Parameter</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>cache</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to the <olink targetptr="bdalx">LDAPMemCache</olink> structure
|
|
that you want freed from memory.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garoc"><title>Description</title>
|
|
<para>The <function>ldap_memcache_destroy</function> function frees the specified <olink targetptr="bdalx">LDAPMemCache</olink> structure from memory. Call this function
|
|
after you are done working with a cache.</para></sect3>
|
|
<sect3 id="garoj"><title>See Also</title>
|
|
<para><olink targetptr="bdati">ldap_memcache_init</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdatg"><title><function>ldap_memcache_flush</function></title>
|
|
<para>The <function>ldap_memcache_flush</function> function flushes items
|
|
from the specified cache.</para>
|
|
<sect3 id="garne"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
void ldap_memcache_flush( LDAPMemCache *cache, char *dn,
|
|
int scope );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garoo"><title>Parameters</title>
|
|
<table frame="topbot" id="garnu"><title><function>ldap_memcache_flush</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>cache</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to the <olink targetptr="bdalx">LDAPMemCache</olink> structure
|
|
that you want to flush entries from.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>dn</literal></para></entry>
|
|
<entry>
|
|
<para>Base DN identifying the search requests that you want flushed from the
|
|
cache. If the base DN of a search request is within the scope specified by
|
|
this DN and the scope argument, the search request is flushed from the cache.
|
|
If this argument is NULL, the entire cache is flushed.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>scope</literal></para></entry>
|
|
<entry>
|
|
<para>Scope that (together with the <literal>dn</literal> argument) identifies
|
|
the search requests that you want flushed from the cache. If the base DN of
|
|
the request is within the scope specified by this argument and the <literal>dn</literal> argument,
|
|
the request is flushed from the cache. This argument can have one of the following
|
|
values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><literal>LDAP_SCOPE_BASE</literal></para></listitem>
|
|
<listitem><para><literal>LDAP_SCOPE_ONELEVEL</literal></para></listitem>
|
|
<listitem><para><literal>LDAP_SCOPE_SUBTREE</literal></para></listitem>
|
|
</itemizedlist>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garom"><title>Description</title>
|
|
<para>The <function>ldap_memcache_flush</function> function flushes search
|
|
requests from the cache. If the base DN of a search request is within the
|
|
scope specified by the <literal>dn</literal> and scope arguments, the search
|
|
request is flushed from the cache. If no DN is specified, the entire cache
|
|
is flushed.</para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdath"><title><function>ldap_memcache_get</function></title>
|
|
<para>The <function>ldap_memcache_get</function> function gets the in-memory
|
|
cache associated with an LDAP connection handle.</para>
|
|
<sect3 id="garnf"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_memcache_get( LDAP *ld, LDAPMemCache **cachep );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garof"><title>Parameters</title>
|
|
<table frame="topbot" id="garnn"><title><function>ldap_memcache_get</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>cachep</literal></para></entry>
|
|
<entry>
|
|
<para>When you call <function>ldap_memcache_get</function>, it sets this parameter
|
|
to the pointer to the <olink targetptr="bdalx">LDAPMemCache</olink> structure
|
|
associated with the connection handle.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garno"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if the cache for the specified
|
|
connection handle was retrieved successfully.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if an invalid parameter
|
|
was passed to the function.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garni"><title>Description</title>
|
|
<para>The <function>ldap_memcache_get</function> function gets the cache associated
|
|
with the specified connection handle (<olink targetptr="bdakj">LDAP</olink> structure).
|
|
This cache is used by all search requests made through that connection. You
|
|
can call this function if you want to associate a cache with multiple LDAP
|
|
connection handles. For example, you can call this function to get the cache
|
|
associated with one connection, then you can call the <olink targetptr="bdatj">ldap_memcache_set
|
|
</olink> function to associate the cache with another connection.</para></sect3>
|
|
<sect3 id="garmz"><title>See Also</title>
|
|
<para><olink targetptr="bdatj">ldap_memcache_set</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdati"><title><function>ldap_memcache_init</function></title>
|
|
<para>The <function>ldap_memcache_init</function> function creates an in-memory
|
|
cache for your LDAP client that you can associate with an LDAP connection.</para>
|
|
<sect3 id="garnz"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_memcache_init( unsigned long ttl, unsigned long size,
|
|
char **baseDNs, struct ldap_thread_fns *thread_fns,
|
|
LDAPMemCache **cachep );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garnh"><title>Parameters</title>
|
|
<table frame="topbot" id="garqm"><title><function>ldap_memcache_init</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ttl</literal></para></entry>
|
|
<entry>
|
|
<para>The maximum amount of time (in seconds) that an item can be cached.
|
|
If <literal>0</literal>, there is no limit to the amount of time that an
|
|
item can be cached.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>size</literal></para></entry>
|
|
<entry>
|
|
<para>Maximum amount of memory (in bytes) that the cache will consume. If
|
|
<literal>0</literal>, the cache has no size limit.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>baseDNs</literal></para></entry>
|
|
<entry>
|
|
<para>An array of the base DN strings representing the base DNs of the search
|
|
requests you want cached. If not <literal>NULL</literal>, only the search
|
|
requests with the specified base DNs will be cached. If <literal>NULL</literal>,
|
|
all search requests are cached.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>thread_fns</literal></para></entry>
|
|
<entry>
|
|
<para>An <olink targetptr="bdamr">ldap_thread_fns</olink> structure specifying
|
|
the functions that you want used to ensure that the cache is thread-safe.
|
|
You should specify this if you have multiple threads that are using the same
|
|
connection handle and cache. If you are not using multiple threads, pass <literal>
|
|
NULL</literal> for this parameter.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>cachep</literal></para></entry>
|
|
<entry>
|
|
<para>When you call this function, it sets this parameter to the pointer to
|
|
the newly created <olink targetptr="bdalx">LDAPMemCache</olink> structure.</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garqb"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if the cache for the specified
|
|
connection handle was retrieved successfully.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if an invalid parameter
|
|
was passed to the function.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
|
|
allocated.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_SIZELIMIT_EXCEEDED</errorcode> if the initial
|
|
size of the cache (specified by the size argument) is too small.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garqf"><title>Description</title>
|
|
<para>The <function>ldap_memcache_init</function> function creates an in-memory,
|
|
client-side cache that you can use to cache search requests. The function
|
|
passes back a pointer to an <olink targetptr="bdalx">LDAPMemCache</olink> structure,
|
|
which represents the cache. You should call the <olink targetptr="bdatj">ldap_memcache_set
|
|
</olink> function to associate this cache with an LDAP connection handle (an
|
|
<olink targetptr="bdakj">LDAP</olink> structure).</para>
|
|
<para>The cache uses search criteria as the key to cached items. When you
|
|
send a search request, the cache checks the search criteria to determine if
|
|
that request has been cached previously. If the request was cached, the search
|
|
results are read from the cache. To flush the cache, call the <olink targetptr="bdatg">ldap_memcache_flush</olink> function. When you are done
|
|
with the cache, you can free it from memory by calling the <olink targetptr="bdatf">ldap_memcache_destroy</olink> function.</para>
|
|
<note><para>On Windows systems, if the <olink targetptr="bdati">ldap_memcache_init
|
|
</olink> function returns an <errorcode>LDAP_PARAM_ERROR</errorcode> result
|
|
code, verify that your client is using the version of the <literal>nsldap32v30.dll
|
|
</literal> file provided with the &DirectorySDKForC;.</para></note>
|
|
</sect3>
|
|
<sect3 id="garpz"><title>See Also</title>
|
|
<para><olink targetptr="bdalx">LDAPMemCache</olink>, <olink targetptr="bdatj">ldap_memcache_set
|
|
</olink> , <olink targetptr="bdatg">ldap_memcache_flush</olink>, <olink targetptr="bdatf">ldap_memcache_destroy</olink>, <olink targetptr="bdatk">ldap_memcache_update
|
|
</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdatj"><title><function>ldap_memcache_set</function></title>
|
|
<para>The <function>ldap_memcache_set</function> function associates an in-memory
|
|
cache with an LDAP connection handle.</para>
|
|
<sect3 id="garpr"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_memcache_set( LDAP *ld, LDAPMemCache *cache );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garqp"><title>Parameters</title>
|
|
<table frame="topbot" id="garpl"><title><function>ldap_memcache_set</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>cache</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdalx">LDAPMemCache</olink> structure,
|
|
which represents the cache that you want used for this connection.</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garpy"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if the cache for the specified
|
|
connection handle was retrieved successfully.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if an invalid parameter
|
|
was passed to the function.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_SIZELIMIT_EXCEEDED</errorcode> if the initial
|
|
size of the cache (specified by the size argument) is too small.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garqa"><title>Description</title>
|
|
<para>The <function>ldap_memcache_set</function> function associates a cache
|
|
(created by calling <olink targetptr="bdati">ldap_memcache_init</olink>) with
|
|
an LDAP connection handle. You can call this function if you want to associate
|
|
a cache with multiple LDAP connection handles. For example, you can call the <olink targetptr="bdath">ldap_memcache_get</olink> function to get the cache associated
|
|
with one connection, then you can call <function>ldap_memcache_set</function> to
|
|
associate the cache with another connection.</para>
|
|
<para>After you call this function, search requests made over the specified
|
|
LDAP connection will use this cache. Calling the <olink targetptr="bdawh">ldap_unbind
|
|
</olink> function will disassociate the cache from the LDAP connection handle.</para>
|
|
</sect3>
|
|
<sect3 id="garpa"><title>See Also</title>
|
|
<para><olink targetptr="bdati">ldap_memcache_init</olink>, <olink targetptr="bdath">ldap_memcache_get</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdatk"><title><function>ldap_memcache_update</function></title>
|
|
<para>The <function>ldap_memcache_update</function> function checks the cache
|
|
for items that have expired and removes them.</para>
|
|
<sect3 id="garot"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
void ldap_memcache_update( LDAPMemCache *cache );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garql"><title>Parameters</title>
|
|
<table frame="topbot" id="garou"><title><function>ldap_memcache_update</function> Function
|
|
Parameter</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>cache</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdalx">LDAPMemCache</olink> structure,
|
|
which represents the cache that you want to updated.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garox"><title>Description</title>
|
|
<para>The <function>ldap_memcache_update</function> function checks the cache
|
|
for items that have expired and removes them. This check is typically done
|
|
as part of the way the cache normally works. You do not need to call this
|
|
function unless you want to update the cache at this point in time.</para>
|
|
<tip><para>This function is only useful in a multithreaded application, since
|
|
it will not return until the cache is destroyed.</para></tip>
|
|
</sect3>
|
|
<sect3 id="garqg"><title>See Also</title>
|
|
<para><olink targetptr="bdatg">ldap_memcache_flush</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdatl"><title><function>ldap_memfree</function></title>
|
|
<para>The <function>ldap_memfree</function> function frees memory allocated
|
|
by an LDAP API function call.</para>
|
|
<sect3 id="garqc"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
void ldap_memfree( void *p );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garpf"><title>Parameters</title>
|
|
<table frame="topbot" id="garpx"><title><function>ldap_memfree</function> Function
|
|
Parameter</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>p</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to memory used by the LDAP library.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garoz"><title>Example</title>
|
|
<para><olink targetptr="ldap-memfree-example">Example 21–33</olink> frees
|
|
the memory allocated by the <olink targetptr="bdask">ldap_get_dn</olink> function.
|
|
</para>
|
|
<example id="ldap-memfree-example"><title>Using <function>ldap_memfree</function></title>
|
|
<programlisting>#include <ldap.h>
|
|
...
|
|
LDAP *ld;
|
|
char *dn;
|
|
LDAPMessage *entry;
|
|
...
|
|
/* Get the distinguished name (DN) for an entry */
|
|
dn = ldap_get_dn( ld, entry );
|
|
...
|
|
/* When you are finished working with the DN, free the memory allocated. */
|
|
ldap_memfree( dn );
|
|
...</programlisting>
|
|
</example>
|
|
</sect3>
|
|
<sect3 id="garpe"><title>See Also</title>
|
|
<para><olink targetptr="bdase">ldap_free_friendlymap</olink>, <olink targetptr="bdasi">ldap_free_urldesc</olink>, <olink targetptr="bdatv">ldap_msgfree
|
|
</olink>, <olink targetptr="bdaxc">ldap_value_free</olink>, <olink targetptr="bdaxd">ldap_value_free_len</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdatm"><title><function>ldap_modify</function></title>
|
|
<para>The <function>ldap_modify</function> function modifies an existing entry
|
|
in the directory asynchronously.</para>
|
|
<note><para>This is an older function included in the SDK for backward-compatibility.
|
|
If you are writing a new LDAP client, use <olink targetptr="bdatn">ldap_modify_ext
|
|
</olink> instead.</para></note>
|
|
<sect3 id="garpj"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_modify( LDAP *ld, const char *dn, LDAPMod **mods );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garqq"><title>Parameters</title>
|
|
<table frame="topbot" id="garqi"><title><function>ldap_modify</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>dn</literal></para></entry>
|
|
<entry>
|
|
<para>DN of the entry to modify.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>mods</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to a <literal>NULL</literal> terminated array of pointers to <olink targetptr="bdalz">LDAPMod</olink> structures representing the attributes that
|
|
you want to modify.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garpo"><title>Returns</title>
|
|
<para>Returns the message ID of the <function>ldap_modify</function> operation.
|
|
To check the result of this operation, call <olink targetptr="bdauu">ldap_result</olink> and <olink targetptr="bdauv">ldap_result2error</olink>. For a list of possible result
|
|
codes for an LDAP modify operation, see <olink targetptr="bdato">ldap_modify_ext_s
|
|
</olink>.</para></sect3>
|
|
<sect3 id="garqk"><title>Description</title>
|
|
<para>Please use the newer version of this function, <olink targetptr="bdatn">ldap_modify_ext
|
|
</olink> .</para></sect3>
|
|
<sect3 id="garqe"><title>Example</title>
|
|
<para><olink targetptr="ldap-modify-example">Example 21–34</olink> uses
|
|
the asynchronous <function>ldap_modify</function> function to modify the entry
|
|
for <emphasis>Barbara Jensen</emphasis> in the directory. It makes the following
|
|
changes to the entry:</para>
|
|
<itemizedlist>
|
|
<listitem><para>Adds the <literal>homePhone</literal> attribute.</para>
|
|
</listitem>
|
|
<listitem><para>Changes the <literal>telephoneNumber</literal> attribute.</para>
|
|
</listitem>
|
|
<listitem><para>Removes the <literal>facsimileTelephoneNumber</literal> attribute.
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
<example id="ldap-modify-example"><title>Using <function>ldap_modify</function></title>
|
|
<programlisting>#include <ldap.h>
|
|
...
|
|
LDAP *ld;
|
|
LDAPMod *list_of_attrs[4];
|
|
LDAPMod attribute1, attribute2, attribute3;
|
|
LDAPMessage *result;
|
|
int msgid, rc;
|
|
struct timeval tv;
|
|
|
|
/* Distinguished name of the entry that you want to modify. */
|
|
char *dn = "uid=bjensen,ou=People,dc=example,dc=com";
|
|
|
|
/* Values to add or change */
|
|
char *homePhone_values[] = { "555-1212", NULL };
|
|
char *telephoneNumber_values[] = { "869-5309", NULL };
|
|
|
|
...
|
|
/* Specify each change in separate LDAPMod structures */
|
|
attribute1.mod_type = "homePhone";
|
|
attribute1.mod_op = LDAP_MOD_ADD;
|
|
attribute1.mod_values = homePhone_values;
|
|
attribute2.mod_type = "telephoneNumber";
|
|
attribute2.mod_op = LDAP_MOD_REPLACE;
|
|
attribute2.mod_values = telephoneNumber_values;
|
|
attribute3.mod_type = "facsimileTelephoneNumber";
|
|
attribute3.mod_op = LDAP_MOD_DELETE;
|
|
attribute3.mod_values = NULL;
|
|
/* NOTE: When removing entire attributes, you need to specify a NULL value
|
|
* for the mod_values field. */
|
|
|
|
/* Add the pointers to these LDAPMod structures to an array */
|
|
list_of_attrs[0] = &attribute1;
|
|
list_of_attrs[1] = &attribute2;
|
|
list_of_attrs[2] = &attribute3;
|
|
list_of_attrs[3] = NULL;
|
|
...
|
|
/* Set up the timeout period to wait for the "modify" operation */
|
|
tv.tv_sec = tv.tv_usec = 0;
|
|
|
|
/* Change the entry */
|
|
if ( ( msgid = ldap_modify( ld, dn, list_of_attrs ) ) == -1 ) {
|
|
ldap_perror( ld, "ldap_modify" );
|
|
return( 1 );
|
|
}
|
|
|
|
/* Check to see if the operation has completed */
|
|
while ( ( rc = ldap_result( ld, msgid, 0, &tv, &result ) ) == 0 ) {
|
|
...
|
|
/* do other work while waiting for the operation to complete */
|
|
...
|
|
}
|
|
|
|
/* Check the result to see if any errors occurred */
|
|
ldap_result2error( ld, result, 1 );
|
|
ldap_perror( ld, "ldap_modify" );
|
|
...</programlisting>
|
|
</example>
|
|
</sect3>
|
|
<sect3 id="garpi"><title>See Also</title>
|
|
<para><olink targetptr="bdatn">ldap_modify_ext</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdatn"><title><function>ldap_modify_ext</function></title>
|
|
<para>The <function>ldap_modify_ext</function> function modifies an existing
|
|
entry in the directory asynchronously.</para>
|
|
<note><para><olink targetptr="bdatn">ldap_modify_ext</olink> is a new version
|
|
of the <olink targetptr="bdatm">ldap_modify</olink> function. If you are writing
|
|
a new LDAP client, use <olink targetptr="bdatn">ldap_modify_ext</olink>.</para>
|
|
</note>
|
|
<sect3 id="garpw"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_modify_ext( LDAP *ld, const char *dn, LDAPMod **mods,
|
|
LDAPControl **serverctrls, LDAPControl **clientctrls,
|
|
int *msgidp );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garpd"><title>Parameters</title>
|
|
<table frame="topbot" id="garpp"><title><function>ldap_modify_ext</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>dn</literal></para></entry>
|
|
<entry>
|
|
<para>DN of the entry to modify.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>mods</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to a <literal>NULL</literal> terminated array of pointers to <olink targetptr="bdalz">LDAPMod</olink> structures representing the attributes that
|
|
you want to modify.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>serverctrls</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
|
|
representing LDAP server controls that apply to this operation. If you do
|
|
not want to pass any server controls, specify <literal>NULL</literal> for
|
|
this argument.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>clientctrls</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
|
|
representing LDAP client controls that apply to this operation. If you do
|
|
not want to pass any client controls, specify <literal>NULL</literal> for
|
|
this argument.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>msgidp</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an integer that will be set to the message ID of the LDAP
|
|
operation. To check the result of this operation, call <olink targetptr="bdauu">ldap_result
|
|
</olink> and <olink targetptr="bdaun">ldap_parse_result</olink>.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garow"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if an invalid parameter
|
|
was passed to the function.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_ENCODING_ERROR</errorcode> if an error occurred
|
|
when BER-encoding the control.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_SERVER_DOWN</errorcode> if the LDAP server
|
|
did not receive the request or if the connection to the server was lost.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
|
|
allocated.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_NOT_SUPPORTED</errorcode> if controls are
|
|
included in your request (for example, as a session preference) and your LDAP
|
|
client does not specify that it is using the LDAP v3. Make sure that you set
|
|
the version of your LDAP client to version 3 before calling this function.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garpc"><title>Description</title>
|
|
<para>The <function>ldap_modify_ext</function> modifies an entry in the directory
|
|
asynchronous; it does not directly return results. If you want the results
|
|
to be returned directly by the function, call the synchronous function <olink targetptr="bdato">ldap_modify_ext_s</olink> instead. In order to get the results
|
|
of this LDAP modify operation, you need to call the <olink targetptr="bdauu">ldap_result
|
|
</olink> and the <olink targetptr="bdaun">ldap_parse_result</olink> functions.
|
|
To make changes to an entry to the directory, you need to specify the following
|
|
information:</para>
|
|
<itemizedlist>
|
|
<listitem><para>A unique DN identifying the new entry</para><para>Use the
|
|
<literal>dn</literal> argument to specify the DN of the entry you want to
|
|
modify.</para></listitem>
|
|
<listitem><para>A set of attributes for the new entry</para><para>Create an <olink targetptr="bdalz">LDAPMod</olink> structure for changes that you want to make
|
|
to an attribute. Create an array of these <olink targetptr="bdalz">LDAPMod</olink> structures
|
|
and pass the array as the <literal>mods</literal> argument.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garpb"><title>See Also</title>
|
|
<para><olink targetptr="bdato">ldap_modify_ext_s</olink>, <olink targetptr="bdauu">ldap_result</olink>, <olink targetptr="bdaun">ldap_parse_result
|
|
</olink>, <olink targetptr="bdalz">LDAPMod</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdato"><title><function>ldap_modify_ext_s</function></title>
|
|
<para>The <function>ldap_modify_ext_s</function> modifies an existing entry
|
|
in the directory synchronously.</para>
|
|
<note><para><olink targetptr="bdato">ldap_modify_ext_s</olink> is a new version
|
|
of the <olink targetptr="bdatp">ldap_modify_s</olink> function. If you are
|
|
writing a new LDAP client, use <olink targetptr="bdato">ldap_modify_ext_s</olink>.
|
|
</para></note>
|
|
<sect3 id="garph"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_modify_ext_s( LDAP *ld, const char *dn, LDAPMod **mods,
|
|
LDAPControl **serverctrls, LDAPControl **clientctrls );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garov"><title>Parameters</title>
|
|
<table frame="topbot" id="garpt"><title><function>ldap_modify_ext_s</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>dn</literal></para></entry>
|
|
<entry>
|
|
<para>DN of the entry to modify.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>mods</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to a <literal>NULL</literal> terminated array of pointers to <olink targetptr="bdalz">LDAPMod</olink> structures representing the attributes that
|
|
you want to modify.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>serverctrls</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
|
|
representing LDAP server controls that apply to this operation. If you do
|
|
not want to pass any server controls, specify <literal>NULL</literal> for
|
|
this argument.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>clientctrls</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
|
|
representing LDAP client controls that apply to this operation. If you do
|
|
not want to pass any client controls, specify <literal>NULL</literal> for
|
|
this argument.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garqj"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if an invalid parameter
|
|
was passed to the function.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_ENCODING_ERROR</errorcode> if an error occurred
|
|
when BER-encoding the control.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_SERVER_DOWN</errorcode> if the LDAP server
|
|
did not receive the request or if the connection to the server was lost.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
|
|
allocated.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_LOCAL_ERROR</errorcode> if an error occurred
|
|
when receiving the results from the server.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_DECODING_ERROR</errorcode> if an error occurred
|
|
when decoding the BER-encoded results from the server.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_NOT_SUPPORTED</errorcode> if controls are
|
|
included in your request (for example, as a session preference) and your LDAP
|
|
client does not specify that it is using the LDAP v3. Make sure that you set
|
|
the version of your LDAP client to version 3 before calling this function.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<note><para>&cnDirectoryServer; and other LDAP server products may send result
|
|
codes in addition to those described. For example, the server may have loaded
|
|
a plug-in that returns custom result codes. Check your LDAP server documentation
|
|
for other result codes.</para></note>
|
|
</sect3>
|
|
<sect3 id="garqh"><title>Description</title>
|
|
<para>The <function>ldap_modify_ext_s</function> modifies an entry in the
|
|
directory. <function>ldap_modify_ext_s</function> is a synchronous function,
|
|
which directly returns the results of the operation. If you want to perform
|
|
other operations while waiting for the results of this operation, call the
|
|
asynchronous function <olink targetptr="bdatn">ldap_modify_ext</olink> instead.</para>
|
|
<para>To make changes to an entry to the directory, you need to specify the
|
|
following information:</para>
|
|
<itemizedlist>
|
|
<listitem><para>A unique DN identifying the new entry</para><para>Use the
|
|
<literal>dn</literal> argument to specify the DN of the entry that you want
|
|
to modify.</para></listitem>
|
|
<listitem><para>A set of attributes for the new entry</para><para>Create an <olink targetptr="bdalz">LDAPMod</olink> structure for change that you want to make
|
|
to an attribute. Create an array of these <olink targetptr="bdalz">LDAPMod</olink> structures
|
|
and pass the array as the <literal>mods</literal> argument.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garpk"><title>See Also</title>
|
|
<para><olink targetptr="bdatn">ldap_modify_ext</olink>, <olink targetptr="bdalz">
|
|
LDAPMod</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdatp"><title><function>ldap_modify_s</function></title>
|
|
<para>The <function>ldap_modify_s</function> function modifies an existing
|
|
entry in the directory synchronously.</para>
|
|
<note><para>This is an older function that is included in the SDK for backward-compatibility.
|
|
If you are writing a new LDAP client, use <olink targetptr="bdato">ldap_modify_ext_s
|
|
</olink> instead.</para></note>
|
|
<sect3 id="garpn"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_modify_s( LDAP *ld, const char *dn, LDAPMod **mods );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garoy"><title>Parameters</title>
|
|
<table frame="topbot" id="garqo"><title><function>ldap_modify_s</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>dn</literal></para></entry>
|
|
<entry>
|
|
<para>DN of the entry to modify.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>mods</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to a <literal>NULL</literal> terminated array of pointers to <olink targetptr="bdalz">LDAPMod</olink> structures representing the attributes that
|
|
you want to modify.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garpm"><title>Returns</title>
|
|
<para>For a list of possible result codes for an LDAP modify operation, see <olink targetptr="bdato">ldap_modify_ext_s</olink>.</para></sect3>
|
|
<sect3 id="garpq"><title>Description</title>
|
|
<para>Use the newer version of this function, <olink targetptr="bdato">ldap_modify_ext_s
|
|
</olink> .</para></sect3>
|
|
<sect3 id="garqd"><title>Example</title>
|
|
<para><olink targetptr="ldap-modify-s-example">Example 21–35</olink> uses
|
|
the synchronous <function>ldap_modify_s</function> function to makes the following
|
|
changes to the <literal>Barbara Jensen</literal> entry:</para>
|
|
<itemizedlist>
|
|
<listitem><para>Adds the <literal>homePhone</literal> attribute.</para>
|
|
</listitem>
|
|
<listitem><para>Changes the <literal>telephoneNumber</literal> attribute.</para>
|
|
</listitem>
|
|
<listitem><para>Removes the <literal>facsimileTelephoneNumber</literal> attribute.
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
<example id="ldap-modify-s-example"><title>Using <function>ldap_modify_s</function></title>
|
|
<programlisting>#include <ldap.h>
|
|
...
|
|
LDAP *ld;
|
|
LDAPMod *list_of_attrs[4];
|
|
LDAPMod attribute1, attribute2, attribute3;
|
|
LDAPControl **srvrctrls, **clntctrls;
|
|
|
|
/* Distinguished name of the entry that you want to modify. */
|
|
char *dn = "uid=bjensen,ou=People,dc=example,dc=com";
|
|
|
|
/* Values to add or change */
|
|
char *homePhone_values[] = { "555-1212", NULL };
|
|
char *telephoneNumber_values[] = { "869-5309", NULL };
|
|
|
|
...
|
|
/* Specify each change in separate LDAPMod structures */
|
|
attribute1.mod_type = "homePhone";
|
|
attribute1.mod_op = LDAP_MOD_ADD;
|
|
attribute1.mod_values = homePhone_values;
|
|
attribute2.mod_type = "telephoneNumber";
|
|
attribute2.mod_op = LDAP_MOD_REPLACE;
|
|
attribute2.mod_values = telephoneNumber_values;
|
|
attribute3.mod_type = "facsimileTelephoneNumber";
|
|
attribute3.mod_op = LDAP_MOD_DELETE;
|
|
attribute3.mod_values = NULL;
|
|
/* NOTE: When removing entire attributes, you need to specify a NULL value
|
|
* for the mod_values or mod_bvalues field. */
|
|
|
|
/* Add the pointers to these LDAPMod structures to an array */
|
|
list_of_attrs[0] = &attribute1;
|
|
list_of_attrs[1] = &attribute2;
|
|
list_of_attrs[2] = &attribute3;
|
|
list_of_attrs[3] = NULL;
|
|
...
|
|
/* Change the entry */
|
|
if ( ldap_modify_s( ld, dn, list_of_attrs ) != LDAP_SUCCESS ) {
|
|
ldap_perror( ld, "ldap_modify_s" );
|
|
return( 1 );
|
|
}
|
|
...</programlisting>
|
|
</example>
|
|
</sect3>
|
|
<sect3 id="garpg"><title>See Also</title>
|
|
<para><olink targetptr="bdato">ldap_modify_ext_s</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdatq"><title><function>ldap_modrdn</function></title>
|
|
<note><para>This function is deprecated and should not be used. It is included
|
|
in <literal>ldap-deprecated.h</literal> for backward-compatibility. Use <olink targetptr="bdaus">ldap_rename</olink> instead.</para></note>
|
|
<sect3 id="bdatr"><title><function>ldap_modrdn_s</function></title>
|
|
<note><para>This function is deprecated and should not be used. It is included
|
|
in <literal>ldap-deprecated.h</literal> for backward-compatibility. Use <olink targetptr="bdaut">ldap_rename_s</olink> instead.</para></note>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="bdats"><title><function>ldap_modrdn2</function></title>
|
|
<note><para>This function is deprecated and should not be used. It is included
|
|
in <literal>ldap-deprecated.h</literal> for backward-compatibility. Use <olink targetptr="bdaus">ldap_rename</olink> instead.</para></note>
|
|
<para>The <function>ldap_modrdn2</function> function changes the relative
|
|
distinguished name (RDN) of an entry in the directory asynchronously.</para>
|
|
<sect3 id="garpu"><title>Syntax</title>
|
|
<programlisting>#include <ldap-deprecated.h>
|
|
int ldap_modrdn2( LDAP *ld, const char *dn, const char *newrdn,
|
|
int deleteoldrdn );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garos"><title>Parameters</title>
|
|
<table frame="topbot" id="garqn"><title><function>ldap_modrdn2</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>dn</literal></para></entry>
|
|
<entry>
|
|
<para>DN of the entry to modify.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>newrdn</literal></para></entry>
|
|
<entry>
|
|
<para>New RDN to assign to the entry.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>deleteoldrdn</literal></para></entry>
|
|
<entry>
|
|
<para>If this is a non-zero value, the old RDN is not retained as a value
|
|
in the modified entry. If <literal>0</literal>, the old RDN is retained as
|
|
an attribute in the modified entry.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garpv"><title>Returns</title>
|
|
<para>Returns the message ID of the <function>ldap_modrdn2</function> operation.
|
|
To check the result of this operation, call <olink targetptr="bdauu">ldap_result</olink> and <olink targetptr="bdauv">ldap_result2error</olink>. For a list of possible result
|
|
codes, see <olink targetptr="bdaus">ldap_rename</olink>.</para></sect3>
|
|
<sect3 id="garps"><title>Description</title>
|
|
<para>Please use the newer version of this function, <olink targetptr="bdaus">ldap_rename
|
|
</olink> .</para></sect3>
|
|
<sect3 id="garqw"><title>Example</title>
|
|
<para><olink targetptr="ldap-modrdn2-example">Example 21–36</olink> uses
|
|
the asynchronous <function>ldap_modrdn2</function> function to change the
|
|
RDN of an entry from <literal>uid=bjensen</literal> to <literal>uid=babs</literal>.
|
|
The code removes the existing RDN <literal>bjensen</literal> from the <literal>uid
|
|
</literal> attribute of the entry.</para>
|
|
<example id="ldap-modrdn2-example"><title>Using <function>ldap_modrdn2</function></title>
|
|
<programlisting>#include <ldap-deprecated.h>
|
|
...
|
|
LDAP *ld;
|
|
LDAPMessage *result;
|
|
int msgid, rc;
|
|
struct timeval tv;
|
|
|
|
/* Distinguished name of the entry that you want to rename. */
|
|
char *dn = "uid=bjensen,ou=People,dc=example,dc=com";
|
|
|
|
/* New relative distinguished name (RDN) of the entry */
|
|
char *rdn = "uid=babs";
|
|
...
|
|
/* Set up the timeout period to wait for the "modify RDN" operation */
|
|
tv.tv_sec = tv.tv_usec = 0;
|
|
|
|
/* Rename the entry */
|
|
if ( ( msgid = ldap_modrdn2( ld, dn, rdn, 1 ) ) == -1 ) {
|
|
ldap_perror( ld, "ldap_modrdn2" );
|
|
return( 1 );
|
|
}
|
|
|
|
/* Check to see if the operation has completed */
|
|
while ( ( rc = ldap_result( ld, msgid, 0, &tv, &result ) ) == 0 ) {
|
|
...
|
|
/* do other work while waiting for the operation to complete */
|
|
...
|
|
}
|
|
|
|
/* Check the result to see if any errors occurred */
|
|
ldap_result2error( ld, result, 1 );
|
|
ldap_perror( ld, "ldap_modrdn2" );
|
|
...</programlisting>
|
|
</example>
|
|
</sect3>
|
|
<sect3 id="garry"><title>See Also</title>
|
|
<para><olink targetptr="bdaus">ldap_rename</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdatt"><title><function>ldap_modrdn2_s</function></title>
|
|
<note><para>This function is deprecated and should not be used. It is included
|
|
in <literal>ldap-deprecated.h</literal> for backward-compatibility. Use <olink targetptr="bdaut">ldap_rename_s</olink> instead.</para></note>
|
|
<para>The <function>ldap_modrdn2_s</function> function changes the relative
|
|
distinguished name (RDN) of an entry in the directory synchronously.</para>
|
|
<sect3 id="garra"><title>Syntax</title>
|
|
<programlisting>#include <ldap-deprecated.h>
|
|
int ldap_modrdn2_s( LDAP *ld, const char *dn,
|
|
const char *newrdn, int deleteoldrdn );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garrh"><title>Parameters</title>
|
|
<table frame="topbot" id="garsa"><title><function>ldap_modrdn2_s</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>dn</literal></para></entry>
|
|
<entry>
|
|
<para>DN of the entry to modify.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>newrdn</literal></para></entry>
|
|
<entry>
|
|
<para>New RDN to assign to the entry.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>deleteoldrdn</literal></para></entry>
|
|
<entry>
|
|
<para>If this is a non-zero value, the old RDN is not retained as a value
|
|
in the modified entry. If <literal>0</literal>, the old RDN is retained as
|
|
an attribute in the modified entry.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garru"><title>Returns</title>
|
|
<para>For a list of possible result codes, see <olink targetptr="bdaut">ldap_rename_s
|
|
</olink> .</para></sect3>
|
|
<sect3 id="garqy"><title>Description</title>
|
|
<para>Please use the newer version of this function, <olink targetptr="bdaut">ldap_rename_s
|
|
</olink> .</para></sect3>
|
|
<sect3 id="garre"><title>Example</title>
|
|
<para><olink targetptr="ldap-modrdn2-s-example">Example 21–37</olink> uses
|
|
the synchronous <function>ldap_modrdn2_s</function> function to change the
|
|
RDN of an entry from <literal>uid=bjensen</literal> to <literal>uid=babs</literal>.
|
|
The code removes the existing RDN <literal>babs</literal> from the <literal>uid</literal> attribute
|
|
of the entry.</para>
|
|
<example id="ldap-modrdn2-s-example"><title>Using <function>ldap_modrdn2_s</function></title>
|
|
<programlisting>#include <ldap.h>
|
|
...
|
|
LDAP *ld;
|
|
|
|
/* Distinguished name of the entry that you want to rename. */
|
|
char *dn = "uid=bjensen,ou=People,dc=example,dc=com";
|
|
|
|
/* New relative distinguished name (RDN) of the entry */
|
|
char *rdn = "uid=babs";
|
|
...
|
|
/* Rename the entry */
|
|
if ( ldap_modrdn2_s( ld, dn, rdn, 1 ) != LDAP_SUCCESS ) {
|
|
ldap_perror( ld, "ldap_modrdn2_s" );
|
|
return( 1 );
|
|
}
|
|
...</programlisting>
|
|
</example>
|
|
</sect3>
|
|
<sect3 id="garqx"><title>See Also</title>
|
|
<para><olink targetptr="bdaut">ldap_rename_s</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdatu"><title><function>ldap_mods_free</function></title>
|
|
<para>The <function>ldap_mods_free</function> function frees the <olink targetptr="bdalz">LDAPMod</olink> structures that you’ve allocated to
|
|
add or modify entries.</para>
|
|
<note><para>You need to call this function only if you’ve allocated
|
|
memory for these structures yourself. For more information, see the <literal>ldap-extension.h
|
|
</literal> header file.</para></note>
|
|
<sect3 id="garsb"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
void ldap_mods_free( LDAPMod **mods, int freemods );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garri"><title>Parameters</title>
|
|
<table frame="topbot" id="garrk"><title><function>ldap_mods_free</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>mods</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to a <literal>NULL</literal> terminated array of pointers to <olink targetptr="bdalz">LDAPMod</olink> structures.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>freemods</literal></para></entry>
|
|
<entry>
|
|
<para>If this is a non-zero value, frees the array of pointers as well as
|
|
the <olink targetptr="bdalz">LDAPMod</olink> structures. If <literal>0</literal>,
|
|
just frees the <olink targetptr="bdalz">LDAPMod</olink> structures.</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garrz"><title>Example</title>
|
|
<para><olink targetptr="ldap-mods-free-example">Example 21–38</olink> allocates
|
|
memory for <olink targetptr="bdalz">LDAPMod</olink> structures and frees them
|
|
when done.</para>
|
|
<example id="ldap-mods-free-example"><title>Using <function>ldap_mods_free</function></title>
|
|
<programlisting>#include <stdio.h>
|
|
#include <ldap.h>
|
|
...
|
|
LDAP *ld;
|
|
char *dn;
|
|
int i, msgid;
|
|
LDAPMod **mods;
|
|
...
|
|
/* Construct the array of values to add */
|
|
mods = ( LDAPMod ** ) malloc(( NMODS + 1 ) * sizeof( LDAPMod * ));
|
|
if ( mods == NULL ) {
|
|
fprintf( stderr, "Cannot allocate memory for mods array\n" );
|
|
}
|
|
for ( i = 0; i < NMODS; i++ ) {
|
|
if (( mods[ i ] = ( LDAPMod * ) malloc( sizeof( LDAPMod ))) == NULL) {
|
|
fprintf( stderr, "Cannot allocate memory for mods element\n" );
|
|
exit( 1 );
|
|
}
|
|
}
|
|
...
|
|
/* Code for filling the structures goes here. */
|
|
...
|
|
/* Initiate the add operation */
|
|
if (( msgid = ldap_add( ld, dn, mods )) < 0 ) {
|
|
ldap_perror( ld, "ldap_add" );
|
|
ldap_mods_free( mods, 1 );
|
|
return( 1 );
|
|
}
|
|
...</programlisting>
|
|
</example>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="bdatv"><title><function>ldap_msgfree</function></title>
|
|
<para>The <function>ldap_msgfree</function> function frees the memory allocated
|
|
for a result by <olink targetptr="bdauu">ldap_result</olink> or <olink targetptr="bdavb">ldap_search_s</olink>.</para>
|
|
<sect3 id="garqu"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_msgfree( LDAPMessage *lm );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garrf"><title>Parameters</title>
|
|
<table frame="topbot" id="garrv"><title><function>ldap_msgfree</function> Function
|
|
Parameter</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>lm</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to the result to be freed from memory.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garrm"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><literal>LDAP_RES_BIND</literal> indicates that the <olink targetptr="bdaly">LDAPMessage</olink> structure contains the result of an
|
|
LDAP bind operation.</para></listitem>
|
|
<listitem><para><literal>LDAP_RES_SEARCH_ENTRY</literal> indicates that the <olink targetptr="bdaly">LDAPMessage</olink> structure contains an entry found during
|
|
an LDAP search operation.</para></listitem>
|
|
<listitem><para><literal>LDAP_RES_SEARCH_REFERENCE</literal> indicates that
|
|
the <olink targetptr="bdaly">LDAPMessage</olink> structure contains an LDAP
|
|
v3 search reference (a referral to another LDAP server) found during an LDAP
|
|
search operation.</para></listitem>
|
|
<listitem><para><literal>LDAP_RES_SEARCH_RESULT</literal> indicates that the <olink targetptr="bdaly">LDAPMessage</olink> structure contains the result of an
|
|
LDAP search operation.</para></listitem>
|
|
<listitem><para><literal>LDAP_RES_MODIFY</literal> indicates that the <olink targetptr="bdaly">LDAPMessage</olink> structure contains the result of an
|
|
LDAP modify operation.</para></listitem>
|
|
<listitem><para><literal>LDAP_RES_ADD</literal> indicates that the <olink targetptr="bdaly">LDAPMessage</olink> structure contains the result of an
|
|
LDAP add operation.</para></listitem>
|
|
<listitem><para><literal>LDAP_RES_DELETE</literal> indicates that the <olink targetptr="bdaly">LDAPMessage</olink> structure contains the result of an
|
|
LDAP delete operation.</para></listitem>
|
|
<listitem><para><literal>LDAP_RES_MODRDN</literal> or <literal>LDAP_RES_RENAME</literal> indicates
|
|
that the <olink targetptr="bdaly">LDAPMessage</olink> structure contains the
|
|
result of an LDAP modify DN operation.</para></listitem>
|
|
<listitem><para><literal>LDAP_RES_COMPARE</literal> indicates that the <olink targetptr="bdaly">LDAPMessage</olink> structure contains the result of an
|
|
LDAP compare operation.</para></listitem>
|
|
<listitem><para><literal>LDAP_RES_EXTENDED</literal> indicates that the <olink targetptr="bdaly">LDAPMessage</olink> structure contains the result of an
|
|
LDAP v3 extended operation.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if the operation times
|
|
out.</para></listitem>
|
|
<listitem><para><literal>-1</literal> indicates that the <literal>lm</literal> argument
|
|
is not a pointer to a valid <olink targetptr="bdaly">LDAPMessage</olink> structure.
|
|
</para></listitem>
|
|
<listitem><para>If unsuccessful, returns the LDAP error code for the operation.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garqz"><title>Example</title>
|
|
<para><olink targetptr="ldap-msgfree-example">Example 21–39</olink> frees
|
|
the results of a search.</para>
|
|
<example id="ldap-msgfree-example"><title>Using <function>ldap_msgfree</function></title>
|
|
<programlisting>#include <stdio.h>
|
|
#include <ldap.h>
|
|
...
|
|
LDAP *ld;
|
|
LDAPMessage *result;
|
|
char *my_searchbase = "dc=example,dc=com";
|
|
char *my_filter = "(sn=Jensen)";
|
|
char *get_attr[] = { "cn", "mail", NULL };
|
|
...
|
|
/* Search the directory */
|
|
if ( ldap_search_s( ld, my_searchbase, LDAP_SCOPE_SUBTREE, my_filter,
|
|
get_attr, 0, &result ) != LDAP_SUCCESS ) {
|
|
ldap_perror( ld, "ldap_search_s" );
|
|
return( 1 );
|
|
}
|
|
...
|
|
/* Free the results when done */
|
|
ldap_msgfree( result );
|
|
...</programlisting>
|
|
</example>
|
|
</sect3>
|
|
<sect3 id="garro"><title>See Also</title>
|
|
<para><olink targetptr="bdauu">ldap_result</olink>, <olink targetptr="bdavb">ldap_search_s
|
|
</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdatw"><title><function>ldap_msgid</function></title>
|
|
<para>The <function>ldap_msgid</function> function determines the message
|
|
ID of a result obtained by calling <olink targetptr="bdauu">ldap_result</olink> or <olink targetptr="bdavb">ldap_search_s</olink>.</para>
|
|
<sect3 id="garrn"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_msgid( LDAPMessage *lm );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garqv"><title>Parameters</title>
|
|
<table frame="topbot" id="garrc"><title><function>ldap_msgid</function> Function
|
|
Parameter</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>lm</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to the result to check.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garrd"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para>The message ID if successful.</para></listitem>
|
|
<listitem><para><literal>-1</literal> if unsuccessful.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garrx"><title>Example</title>
|
|
<para><olink targetptr="ldap-msgid-example">Example 21–40</olink> prints
|
|
the message ID from the result obtained from a synchronous LDAP search operation.
|
|
</para>
|
|
<example id="ldap-msgid-example"><title>Using <function>ldap_msgid</function></title>
|
|
<programlisting>#include <stdio.h>
|
|
#include <ldap.h>
|
|
...
|
|
LDAP *ld;
|
|
LDAPMessage *result;
|
|
...
|
|
/* Perform a search */
|
|
if ( ldap_search_s( ld, MY_SEARCHBASE, LDAP_SCOPE_SUBTREE, MY_FILTER,
|
|
NULL, 0, &result ) != LDAP_SUCCESS ) {
|
|
ldap_perror( ld, "ldap_search_s" );
|
|
return( 1 );
|
|
}
|
|
|
|
/* Get and print the message ID */
|
|
if ( ldap_msgid( result ) != -1 ) {
|
|
printf( "Message ID: %d\n" );
|
|
} else {
|
|
printf( "An error occurred.\n" );
|
|
}
|
|
...</programlisting>
|
|
</example>
|
|
</sect3>
|
|
<sect3 id="garrj"><title>See Also</title>
|
|
<para><olink targetptr="bdatx">ldap_msgtype</olink>, <olink targetptr="bdauu">ldap_result
|
|
</olink> , <olink targetptr="bdavb">ldap_search_s</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdatx"><title><function>ldap_msgtype</function></title>
|
|
<indexterm>
|
|
<primary>C SDK functions</primary>
|
|
<secondary><function>ldap_msgtype</function></secondary>
|
|
</indexterm><indexterm>
|
|
<primary><function>ldap_msgtype</function></primary>
|
|
</indexterm>
|
|
<para>The <function>ldap_msgtype</function> function determines the type of
|
|
result obtained by calling <olink targetptr="bdauu">ldap_result</olink> or
|
|
<olink targetptr="bdavb">ldap_search_s</olink>.</para>
|
|
<sect3 id="garqr"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_msgtype( LDAPMessage *lm );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garrg"><title>Parameters</title>
|
|
<table frame="topbot" id="garrs"><title><function>ldap_msgtype</function> Function
|
|
Parameter</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>lm</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to the <olink targetptr="bdaly">LDAPMessage</olink> structure
|
|
to check.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garrp"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><literal>LDAP_RES_BIND</literal> indicates that the <olink targetptr="bdaly">LDAPMessage</olink> structure contains the result of an
|
|
LDAP bind operation.</para></listitem>
|
|
<listitem><para><literal>LDAP_RES_SEARCH_ENTRY</literal> indicates that the <olink targetptr="bdaly">LDAPMessage</olink> structure contains an entry found during
|
|
an LDAP search operation.</para></listitem>
|
|
<listitem><para><literal>LDAP_RES_SEARCH_REFERENCE</literal> indicates that
|
|
the <olink targetptr="bdaly">LDAPMessage</olink> structure contains an LDAP
|
|
v3 search reference (a referral to another LDAP server) found during an LDAP
|
|
search operation.</para></listitem>
|
|
<listitem><para><literal>LDAP_RES_SEARCH_RESULT</literal> indicates that the <olink targetptr="bdaly">LDAPMessage</olink> structure contains the result of an
|
|
LDAP search operation.</para></listitem>
|
|
<listitem><para><literal>LDAP_RES_MODIFY</literal> indicates that the <olink targetptr="bdaly">LDAPMessage</olink> structure contains the result of an
|
|
LDAP modify operation.</para></listitem>
|
|
<listitem><para><literal>LDAP_RES_ADD</literal> indicates that the <olink targetptr="bdaly">LDAPMessage</olink> structure contains the result of an
|
|
LDAP add operation.</para></listitem>
|
|
<listitem><para><literal>LDAP_RES_DELETE</literal> indicates that the <olink targetptr="bdaly">LDAPMessage</olink> structure contains the result of an
|
|
LDAP delete operation.</para></listitem>
|
|
<listitem><para><literal>LDAP_RES_MODRDN</literal> or <literal>LDAP_RES_RENAME</literal> indicates
|
|
that the <olink targetptr="bdaly">LDAPMessage</olink> structure contains the
|
|
result of an LDAP modify DN operation.</para></listitem>
|
|
<listitem><para><literal>LDAP_RES_COMPARE</literal> indicates that the <olink targetptr="bdaly">LDAPMessage</olink> structure contains the result of an
|
|
LDAP compare operation.</para></listitem>
|
|
<listitem><para><literal>LDAP_RES_EXTENDED</literal> indicates that the <olink targetptr="bdaly">LDAPMessage</olink> structure contains the result of an
|
|
LDAP v3 extended operation.</para></listitem>
|
|
<listitem><para><literal>-1</literal> indicates that the <literal>lm</literal> argument
|
|
is not a pointer to a valid <olink targetptr="bdaly">LDAPMessage</olink> structure.
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garqt"><title>Example</title>
|
|
<para><olink targetptr="ldap-msgtype-example">Example 21–41</olink> prints
|
|
the message type for a result obtained from a synchronous LDAP search operation.</para>
|
|
<example id="ldap-msgtype-example"><title>Using <function>ldap_msgtype</function></title>
|
|
<programlisting>#include <stdio.h>
|
|
#include <ldap.h>
|
|
...
|
|
LDAP *ld;
|
|
LDAPMessage *result;
|
|
int msgtype;
|
|
...
|
|
/* Perform a search */
|
|
if ( ldap_search_s( ld, MY_SEARCHBASE, LDAP_SCOPE_SUBTREE, MY_FILTER,
|
|
NULL, 0, &result ) != LDAP_SUCCESS ) {
|
|
ldap_perror( ld, "ldap_search_s" );
|
|
return( 1 );
|
|
}
|
|
|
|
/* Get and print the message type */
|
|
msgtype = ldap_msgtype( result );
|
|
if ( msgtype != -1 ) {
|
|
printf( "Message type: %d\n", msgtype );
|
|
} else {
|
|
printf( "An error occurred.\n" );
|
|
}
|
|
...</programlisting>
|
|
</example>
|
|
</sect3>
|
|
<sect3 id="garrl"><title>See Also</title>
|
|
<para><olink targetptr="bdatw">ldap_msgid</olink>, <olink targetptr="bdauu">ldap_result
|
|
</olink> , <olink targetptr="bdavb">ldap_search_s</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaty"><title><function>ldap_multisort_entries</function></title>
|
|
<para>The <function>ldap_multisort_entries</function> function sorts a chain
|
|
of entries retrieved from an LDAP search call (<olink targetptr="bdavb">ldap_search_s
|
|
</olink> or <olink targetptr="bdauu">ldap_result</olink>) by either a specified
|
|
set of attributes in the entries or DN.</para>
|
|
<sect3 id="garrw"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_multisort_entries( LDAP *ld, LDAPMessage **chain,
|
|
char **attr, LDAP_CMP_CALLBACK *cmp );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garrb"><title>Parameters</title>
|
|
<table frame="topbot" id="garsc"><title><function>ldap_multisort_entries</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>chain</literal></para></entry>
|
|
<entry>
|
|
<para>Chain of entries returned by the <olink targetptr="bdauu">ldap_result</olink> or <olink targetptr="bdavb">ldap_search_s</olink> function.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>attr</literal></para></entry>
|
|
<entry>
|
|
<para>Array of attributes to use for sorting the results. If <literal>NULL</literal>,
|
|
results are sorted by DN.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>cmp</literal></para></entry>
|
|
<entry>
|
|
<para>Comparison function used when sorting the values.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garqs"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><literal>0</literal> if successful.</para></listitem>
|
|
<listitem><para><literal>-1</literal> if memory cannot be allocated by this
|
|
function. (The error code <errorcode>LDAP_NO_MEMORY</errorcode> is set in
|
|
the <olink targetptr="bdakj">LDAP</olink> structure. To get the error code,
|
|
call the <olink targetptr="bdasq">ldap_get_lderrno</olink> function.)</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if an invalid parameter
|
|
was passed to the function</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garrr"><title>Example</title>
|
|
<para><olink targetptr="ldap-multisort-entries-example">Example 21–42</olink>
|
|
sorts entries first by the <literal>roomNumber</literal> attribute, then by
|
|
the <literal>telephoneNumber</literal> attribute.</para>
|
|
<example id="ldap-multisort-entries-example"><title>Using <function>ldap_multisort_entries
|
|
</function></title>
|
|
<programlisting>#include <stdio.h>
|
|
#include <string.h>
|
|
#include <ldap.h>
|
|
...
|
|
LDAP *ld;
|
|
LDAPMessage *result;
|
|
char *my_searchbase = "dc=example,dc=com";
|
|
char *my_filter = "(sn=Jensen)";
|
|
char *attrs[3];
|
|
attrs[0] = "roomNumber";
|
|
attrs[1] = "telephoneNumber";
|
|
attrs[2] = NULL;
|
|
...
|
|
/* Search the directory */
|
|
if ( ldap_search_s( ld, my_searchbase, LDAP_SCOPE_SUBTREE, my_filter,
|
|
NULL, 0, &result ) != LDAP_SUCCESS ) {
|
|
ldap_perror( ld, "ldap_search_s" );
|
|
return( 1 );
|
|
}
|
|
|
|
/* Sort the results, using strcasecmp */
|
|
if ( ldap_multisort_entries( ld, &result, attrs, strcasecmp ) !=
|
|
LDAP_SUCCESS ) {
|
|
ldap_perror( ld, "ldap_multisort_entries" );
|
|
return( 1 );
|
|
}
|
|
...</programlisting>
|
|
</example>
|
|
</sect3>
|
|
<sect3 id="garrt"><title>See Also</title>
|
|
<para><olink targetptr="bdauu">ldap_result</olink>, <olink targetptr="bdavb">ldap_search_s
|
|
</olink> , <olink targetptr="bdavk">ldap_sort_entries</olink>, <olink targetptr="bdakz">LDAP_CMP_CALLBACK</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdatz"><title><function>ldap_name2template</function></title>
|
|
<para>The <function>ldap_name2template</function> function obtains a pointer
|
|
to the correct <literal>ldap_disptmpl</literal> structure.</para>
|
|
<sect3 id="garrq"><title>Syntax</title>
|
|
<programlisting>#include <disptmpl.h>
|
|
struct ldap_disptmpl * ldap_name2template( char *name
|
|
struct ldap_disptmpl *tmpllist );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garsr"><title>Parameters</title>
|
|
<table frame="topbot" id="garsy"><title><function>ldap_name2template</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>name</literal></para></entry>
|
|
<entry>
|
|
<para>Name of the template.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>tmpllistp</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to a list of template data structures.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gartl"><title>Returns</title>
|
|
<itemizedlist>
|
|
<listitem><para>If successful, <literal>0</literal> is returned and <literal>tmpllistp
|
|
</literal> is configured.</para></listitem>
|
|
<listitem><para>Upon error:</para>
|
|
<itemizedlist>
|
|
<listitem><para><literal>LDAP_TMPL_ERR_VERSION</literal> if <literal>buf</literal> points
|
|
to data that is newer than can be handled.</para></listitem>
|
|
<listitem><para><literal>LDAP_TMPL_ERR_MEM</literal> if there is a memory
|
|
allocation problem.</para></listitem>
|
|
<listitem><para><literal>LDAP_TMPL_ERR_SYNTAX</literal> if there is a problem
|
|
with the format of the templates buffer or file.</para></listitem>
|
|
<listitem><para><literal>LDAP_TMPL_ERR_FILE</literal> if the file cannot be
|
|
read.</para></listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garsh"><title>Description</title>
|
|
<para><function>ldap_name2template</function> obtains a pointer to the correct
|
|
<literal>ldap_disptmpl</literal> structure. Links to templates can be defined
|
|
by name.</para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaua"><title><function>ldap_next_attribute</function></title>
|
|
<para>The <function>ldap_next_attribute</function> function returns the name
|
|
of the next attribute in an entry returned by <olink targetptr="bdary">ldap_first_entry
|
|
</olink> or <olink targetptr="bdauc">ldap_next_entry</olink>.</para>
|
|
<sect3 id="garsx"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
char * ldap_next_attribute( LDAP *ld, LDAPMessage *entry,
|
|
BerElement *ber);</programlisting>
|
|
</sect3>
|
|
<sect3 id="gartz"><title>Parameters</title>
|
|
<table frame="topbot" id="gartu"><title><function>ldap_next_attribute</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>entry</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to the <olink targetptr="bdaly">LDAPMessage</olink> structure
|
|
representing the entry returned by the <olink targetptr="bdary">ldap_first_entry</olink> or <olink targetptr="bdauc">ldap_next_entry</olink> function.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>ber</literal></para></entry>
|
|
<entry>
|
|
<para>A pointer to a <olink targetptr="bdakh">BerElement</olink> allocated
|
|
to keep track of its current position. Pass this pointer to subsequent calls
|
|
to <function>ldap_next_attribute</function> to step through the entry's attributes.
|
|
</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garte"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para>If successful, returns the name of the next attribute in an
|
|
entry. When you are done using this data, you should free the memory by calling
|
|
the <olink targetptr="bdatl">ldap_memfree</olink> function.</para></listitem>
|
|
<listitem><para>If no more attributes exist in the entry, returns a <literal>NULL
|
|
</literal> .</para></listitem>
|
|
<listitem><para>If unsuccessful, returns a <literal>NULL</literal> and sets
|
|
the appropriate error code in the <olink targetptr="bdakj">LDAP</olink> structure.
|
|
To get the error code, call the <olink targetptr="bdasq">ldap_get_lderrno</olink> function.
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="gartf"><title>Description</title>
|
|
<para>The <olink targetptr="bdarw">ldap_first_attribute</olink> function returns
|
|
a pointer to a <olink targetptr="bdakh">BerElement</olink>. You use this pointer
|
|
with <function>ldap_next_attribute</function> to iterate through the list
|
|
of elements. After the last call to <function>ldap_next_element</function>,
|
|
you should free the <olink targetptr="bdakh">BerElement</olink> pointer using <olink targetptr="bdaqd">ldap_ber_free</olink>. When calling <olink targetptr="bdaqd">ldap_ber_free
|
|
</olink>, make sure to specify that the buffer is not freed (pass <literal>0</literal> for
|
|
the <literal>freebuf</literal> parameter).</para></sect3>
|
|
<sect3 id="garsm"><title>Example</title>
|
|
<para>See the example under <olink targetptr="bdarw">ldap_first_attribute</olink>.
|
|
</para></sect3>
|
|
<sect3 id="gartr"><title>See Also</title>
|
|
<para><olink targetptr="bdarw">ldap_first_attribute</olink>, <olink targetptr="bdasn">ldap_getfirstfilter</olink>, <olink targetptr="bdauc">ldap_next_entry
|
|
</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaub"><title><function>ldap_next_disptmpl</function></title>
|
|
<para>The <function>ldap_next_disptmpl</function> function returns the next
|
|
template in a list.</para>
|
|
<sect3 id="gartt"><title>Syntax</title>
|
|
<programlisting>#include <disptmpl.h>
|
|
struct ldap_disptmpl * ldap_next_disptmpl( struct ldap_disptmpl *tmpllist,
|
|
struct ldap_disptmpl *tmpl );;</programlisting>
|
|
</sect3>
|
|
<sect3 id="gartd"><title>Parameters</title>
|
|
<table frame="topbot" id="gartw"><title><function>ldap_next_disptmpl</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>tmpl</literal></para></entry>
|
|
<entry>
|
|
<para>Defines a template from the template list <parameter>tmpllist</parameter>.
|
|
A <literal>NULL</literal> pointer is returned if <parameter>tmpl</parameter> is
|
|
the last template in the list.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>tmpllistp</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to a list of template data structures typically obtained by
|
|
calling <olink targetptr="bdata">ldap_init_templates</olink>.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garsg"><title>Returns</title>
|
|
<itemizedlist>
|
|
<listitem><para>If successful, <literal>0</literal> is returned and <literal>tmpllistp
|
|
</literal> is configured.</para></listitem>
|
|
<listitem><para>Upon error:</para>
|
|
<itemizedlist>
|
|
<listitem><para><literal>LDAP_TMPL_ERR_VERSION</literal> if <literal>buf</literal> points
|
|
to data that is newer than can be handled.</para></listitem>
|
|
<listitem><para><literal>LDAP_TMPL_ERR_MEM</literal> if there is a memory
|
|
allocation problem.</para></listitem>
|
|
<listitem><para><literal>LDAP_TMPL_ERR_SYNTAX</literal> if there is a problem
|
|
with the format of the templates buffer or file.</para></listitem>
|
|
<listitem><para><literal>LDAP_TMPL_ERR_FILE</literal> if the file cannot be
|
|
read.</para></listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garto"><title>Description</title>
|
|
<para><function>ldap_next_disptmpl</function> returns the template following
|
|
the previous one in the list of templates pointed to by the parameter <literal>tmpllistp
|
|
</literal>. <literal>tmpllistp</literal> is typically obtained by calling <olink targetptr="bdata">ldap_init_templates</olink> .</para></sect3>
|
|
<sect3 id="garso"><title>See Also</title>
|
|
<para><olink targetptr="bdarx">ldap_first_disptmpl</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdauc"><title><function>ldap_next_entry</function></title>
|
|
<para>The <function>ldap_next_entry</function> function returns a pointer
|
|
to the <olink targetptr="bdaly">LDAPMessage</olink> structure representing
|
|
the next directory entry in a chain of search results.</para>
|
|
<sect3 id="gartm"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
LDAPMessage * ldap_next_entry( LDAP *ld, LDAPMessage *entry );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garsk"><title>Parameters</title>
|
|
<table frame="topbot" id="garsn"><title><function>ldap_next_entry</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>entry</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdaly">LDAPMessage</olink> structure
|
|
in a chain of search results.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garth"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para>If successful, returns the pointer to the next <olink targetptr="bdaly">LDAPMessage</olink> structure of the type <literal>LDAP_RES_SEARCH_ENTRY
|
|
</literal> in a chain of search results.</para></listitem>
|
|
<listitem><para>If no more <olink targetptr="bdaly">LDAPMessage</olink> structures
|
|
of the type <literal>LDAP_RES_SEARCH_ENTRY</literal> are in the chain or if
|
|
the function is unsuccessful, returns a <literal>NULLMSG</literal>.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garua"><title>Description</title>
|
|
<para>The <function>ldap_next_entry</function> function returns a pointer
|
|
to the <olink targetptr="bdaly">LDAPMessage</olink> structure representing
|
|
the next directory entry in a chain of search results. You can use this function
|
|
in conjunction with the <olink targetptr="bdary">ldap_first_entry</olink> function
|
|
to iterate through the directory entries in a chain of search results. These
|
|
functions skip over any messages in the chain that do not have the type <literal>
|
|
LDAP_RES_SEARCH_ENTRY</literal> as messages containing directory entries have
|
|
the type <literal>LDAP_RES_SEARCH_ENTRY</literal>.</para></sect3>
|
|
<sect3 id="gartv"><title>See Also</title>
|
|
<para><olink targetptr="bdary">ldap_first_entry</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaud"><title><function>ldap_next_message</function></title>
|
|
<para>The <function>ldap_next_message</function> function returns a pointer
|
|
to the next <olink targetptr="bdaly">LDAPMessage</olink> structure in a chain
|
|
of search results.</para>
|
|
<sect3 id="gartc"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
LDAPMessage * ldap_next_message( LDAP *ld, LDAPMessage *msg );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garsu"><title>Parameters</title>
|
|
<table frame="topbot" id="garsd"><title><function>ldap_next_message</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>msg</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdaly">LDAPMessage</olink> structure
|
|
in a chain of search results.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garsq"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para>If successful, returns the pointer to the next <olink targetptr="bdaly">LDAPMessage</olink> structure in a chain of search results.</para>
|
|
</listitem>
|
|
<listitem><para>If no more <olink targetptr="bdaly">LDAPMessage</olink> structures
|
|
are in the chain or if the function is unsuccessful, returns a <literal>NULLMSG</literal>.
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garsp"><title>Description</title>
|
|
<para>The <function>ldap_next_message</function> function returns a pointer
|
|
to the next <olink targetptr="bdaly">LDAPMessage</olink> structure in a chain
|
|
of search results. You can use this function in conjunction with the <olink targetptr="bdarz">ldap_first_message</olink> function to iterate through
|
|
the chain of search results. You can also call the <olink targetptr="bdatx">ldap_msgtype
|
|
</olink> function to determine if each message contains a matching entry (a
|
|
message of the type <literal>LDAP_RES_SEARCH_ENTRY</literal> ) or a search
|
|
reference (a message of the type <literal>LDAP_RES_SEARCH_REFERENCE</literal>).</para>
|
|
</sect3>
|
|
<sect3 id="garsl"><title>See Also</title>
|
|
<para><olink targetptr="bdarz">ldap_first_message</olink>, <olink targetptr="bdatx">ldap_msgtype</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaue"><title><function>ldap_next_reference</function></title>
|
|
<para>The <function>ldap_next_reference</function> function returns a pointer
|
|
to the <olink targetptr="bdaly">LDAPMessage</olink> structure representing
|
|
the next search reference in a chain of search results.</para>
|
|
<sect3 id="garsf"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
LDAPMessage * ldap_next_reference( LDAP *ld, LDAPMessage *ref );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gartq"><title>Parameters</title>
|
|
<table frame="topbot" id="garse"><title><function>ldap_next_reference</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>msg</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdaly">LDAPMessage</olink> structure
|
|
in a chain of search results.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garst"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para>If successful, returns the pointer to the next <olink targetptr="bdaly">LDAPMessage</olink> structure of the type <literal>LDAP_RES_SEARCH_REFERENCE
|
|
</literal> in a chain of search results.</para></listitem>
|
|
<listitem><para>If no more <olink targetptr="bdaly">LDAPMessage</olink> structures
|
|
of the type <literal>LDAP_RES_SEARCH_REFERENCE</literal> are in the chain
|
|
or if the function is unsuccessful, returns a <literal>NULLMSG</literal>.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="gartg"><title>Description</title>
|
|
<para>The <function>ldap_next_reference</function> function returns a pointer
|
|
to the <olink targetptr="bdaly">LDAPMessage</olink> structure representing
|
|
the next search reference in a chain of search results. You can use this function
|
|
in conjunction with the <olink targetptr="bdasa">ldap_first_reference</olink> function
|
|
to iterate through the search references in a chain of search results.</para>
|
|
<para>These functions skip over any messages in the chain that do not have
|
|
the type <literal>LDAP_RES_SEARCH_REFERENCE</literal>. Messages containing
|
|
search references have the type <literal>LDAP_RES_SEARCH_REFERENCE</literal>,
|
|
continuation references as specified in LDAPv3 that are stored as referral
|
|
entries. Like a referral, each continuation reference itself may contain a
|
|
number of URLs assumed to be equivalent, and the client should use one of
|
|
those URLs.</para></sect3>
|
|
<sect3 id="garsz"><title>See Also</title>
|
|
<para><olink targetptr="bdasa">ldap_first_reference</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdauf"><title><function>ldap_next_searchobj</function></title>
|
|
<para>The <function>ldap_next_searchobj</function> function returns the following
|
|
search preference in a defined list.</para>
|
|
<sect3 id="garty"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
struct ldap_searchobj * ldap_next_searchobj
|
|
( struct ldap_searchobj *sollist, struct ldap_searchobj *so );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garsi"><title>Parameters</title>
|
|
<table frame="topbot" id="garsw"><title><function>ldap_next_searchobj</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>sollist</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to a list of data structures, typically obtained by calling
|
|
<olink targetptr="bdasy">ldap_init_searchprefs</olink>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>so</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to the most recent search object returned in the template list
|
|
<literal>sollist</literal>. The search object returned by <function>ldap_next_searchobj
|
|
</function> follows this one.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gartb"><title>Returns</title>
|
|
<itemizedlist>
|
|
<listitem><para>If successful, a pointer to an <literal>ldap_searchobj</literal> structure.
|
|
</para></listitem>
|
|
<listitem><para>A <literal>NULL</literal> pointer is returned if <literal>so</literal> is
|
|
the last entry in the list.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garts"><title>Description</title>
|
|
<para>The search object returned by <function>ldap_next_searchobj</function> follows
|
|
the one defined by the <literal>so</literal> parameter.</para></sect3>
|
|
<sect3 id="garsv"><title>See Also</title>
|
|
<para><olink targetptr="bdasy">ldap_init_searchprefs</olink>, <olink targetptr="bdasb">ldap_first_searchobj</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaug"><title><function>ldap_next_tmplcol</function></title>
|
|
<para>The <function>ldap_next_tmplcol</function> function returns a pointer
|
|
to the following item (in the column) within a template.</para>
|
|
<sect3 id="gartj"><title>Syntax</title>
|
|
<programlisting>#include <disptmpl.h>
|
|
struct ldap_tmplitem * ldap_next_tmplcol( struct ldap_disptmpl *tmpl,
|
|
struct ldap_tmplitem *row, struct ldap_tmplitem *col );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gartk"><title>Parameters</title>
|
|
<table frame="topbot" id="gartn"><title><function>ldap_next_tmplcol</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>tmpl</literal></para></entry>
|
|
<entry>
|
|
<para>The name of the template to be retrieved.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>row</literal></para></entry>
|
|
<entry>
|
|
<para>The row in which the item is to be retrieved from.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>col</literal></para></entry>
|
|
<entry>
|
|
<para>The column in which the item is to be retrieved from.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garss"><title>Returns</title>
|
|
<itemizedlist>
|
|
<listitem><para>If successful, a pointer to an <literal>ldap_tmplitem</literal> structure.
|
|
</para></listitem>
|
|
<listitem><para>A <literal>NULL</literal> pointer on error or if <literal>col</literal> was
|
|
the last item.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="gartp"><title>Description</title>
|
|
<para><function>ldap_next_tmplcol</function> returns a pointer to the next
|
|
item (in the column) of the row, defined by <literal>row</literal>, within
|
|
the template defined by <literal>tmpl</literal>.</para></sect3>
|
|
<sect3 id="garti"><title>See Also</title>
|
|
<para><olink targetptr="bdasc">ldap_first_tmplcol</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdauh"><title><function>ldap_next_tmplrow</function></title>
|
|
<para>The <function>ldap_next_tmplrow</function> function returns a pointer
|
|
to the following row in a template.</para>
|
|
<sect3 id="garta"><title>Syntax</title>
|
|
<programlisting>#include <disptmpl.h>
|
|
struct ldap_tmplitem * ldap_next_tmplrow( struct ldap_disptmpl *tmpl,
|
|
struct ldap_tmplitem *row );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garsj"><title>Parameters</title>
|
|
<table frame="topbot" id="garub"><title><function>ldap_next_tmplrow</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>tmpl</literal></para></entry>
|
|
<entry>
|
|
<para>The name of the template to be retrieved.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>row</literal></para></entry>
|
|
<entry>
|
|
<para>The row in the template to be retrieved.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gartx"><title>Returns</title>
|
|
<itemizedlist>
|
|
<listitem><para>If successful, a pointer to an <literal>ldap_tmplitem</literal> structure.
|
|
</para></listitem>
|
|
<listitem><para>A <literal>NULL</literal> pointer on error.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garvy"><title>Description</title>
|
|
<para><function>ldap_next_tmplrow</function> returns a pointer to the row
|
|
that follows the one defined by <literal>row</literal> in the template defined
|
|
by <literal>tmpl</literal> .</para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaui"><title><function>ldap_oc2template</function></title>
|
|
<para>The <function>ldap_oc2template</function> function obtains a pointer
|
|
to the correct <literal>ldap_disptmpl</literal> structure.</para>
|
|
<sect3 id="garvr"><title>Syntax</title>
|
|
<programlisting>#include <disptmpl.h>
|
|
struct ldap_disptmpl * ldap_oc2template( char **oclist,
|
|
struct ldap_disptmpl *tmpllist );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garus"><title>Parameters</title>
|
|
<table frame="topbot" id="garvw"><title><function>ldap_oc2template</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>oclist</literal></para></entry>
|
|
<entry>
|
|
<para>A <literal>NULL</literal> terminated array of strings that contains
|
|
the values of the <literal>objectClass</literal> attribute of the entry.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>tmpllistp</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to a list of template data structures.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garvl"><title>Returns</title>
|
|
<itemizedlist>
|
|
<listitem><para>Pointer to the first template where all of the object classes
|
|
listed in one of the template's <literal>dt_oclist</literal> elements are
|
|
contained in <literal>oclist</literal>.</para></listitem>
|
|
<listitem><para>A <literal>NULL</literal> pointer if no appropriate template
|
|
is found.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garvb"><title>Description</title>
|
|
<para><function>ldap_oc2template</function>searches <literal>tmpllist</literal> for
|
|
the best template to use to display an entry that has a specific set of <literal>
|
|
objectClass</literal> values.</para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdauj"><title><function>ldap_open</function></title>
|
|
<note><para>This function is deprecated and should not be used. Use <olink targetptr="bdasv">ldap_init</olink> or <olink targetptr="bdaxr">prldap_init</olink> (IPv6)
|
|
instead.</para></note>
|
|
<para>The <function>ldap_open</function> function opens a connection to an
|
|
LDAP server and allocates an <olink targetptr="bdakj">LDAP</olink> structure
|
|
which is used to identify the connection and maintain per-connection information.
|
|
</para>
|
|
<sect3 id="garui"><title>Syntax</title>
|
|
<programlisting>#include <ldap-deprecated.h>
|
|
ldap_open( const char *host, int port );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garuv"><title>Parameters</title>
|
|
<table frame="topbot" id="garvo"><title><function>ldap_open</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>host</literal></para></entry>
|
|
<entry>
|
|
<para>The hostname on which the LDAP server is running. It may contain a blank-separated
|
|
list of hosts to try to connect to, and each host may optionally be of the
|
|
form <replaceable>host</replaceable>:<replaceable>port</replaceable>. If
|
|
present, <replaceable>port</replaceable> overrides the port parameter. Upon
|
|
successfully making a connection to an LDAP server, <function>ldap_open</function> returns
|
|
a pointer to an <olink targetptr="bdakj">LDAP</olink> structure, which
|
|
should be passed to subsequent calls <olink targetptr="bdaqe">ldap_bind</olink>, <olink targetptr="bdauy">ldap_search</olink></para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>port</literal></para></entry>
|
|
<entry>
|
|
<para>The port number to which to connect. If the default IANA-assigned port
|
|
of 389 is desired, <literal>LDAP_PORT</literal> should be specified as the
|
|
value of port.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garuc"><title>Description</title>
|
|
<para>Please use a newer version of this function, <olink targetptr="bdasv">ldap_init
|
|
</olink> or <olink targetptr="bdaxr">prldap_init</olink> (IPv6).</para></sect3>
|
|
</sect2>
|
|
<sect2 id="ldap-parse-authzid-control"><title><function>ldap_parse_authzid_control
|
|
</function></title>
|
|
<para>The <function>ldap_parse_authzid_control</function> function parses
|
|
the authorization identity bind response control retrieved from the server
|
|
to extract the authorization ID.</para>
|
|
<sect3><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
LDAP_API(int) LDAP_CALL ldap_parse_authzid_control( LDAP *ld,
|
|
LDAPControl **ctrlp, char **authzid );</programlisting>
|
|
</sect3>
|
|
<sect3><title>Parameters</title>
|
|
<table frame="topbot" id="gbgdxa"><title><function>ldap_parse_authzid_control</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2" colsep="0" rowsep="0"><colspec colwidth="50*"><colspec
|
|
colwidth="50*">
|
|
<thead>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>
|
|
<para><parameter>ld</parameter></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><parameter>ctrlp</parameter></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdala">LDAPControl</olink> structure
|
|
retrieved from the server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><parameter>authzid</parameter></para></entry>
|
|
<entry>
|
|
<para>Pointer to string holding the authorization ID.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if any of the arguments
|
|
are invalid.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
|
|
allocated to decode the control returned by the server.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_DECODING_ERROR</errorcode> if an error occurred
|
|
when decoding the BER-encoded message.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_CONTROL_NOT_FOUND</errorcode> if no control
|
|
can be found in the response returned from the server.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_NOT_SUPPORTED</errorcode> if controls are
|
|
included in your request (for example, as a session preference) and your LDAP
|
|
client does not specify that it is using the LDAP v3. Make sure that you set
|
|
the version of your LDAP client to version 3 before calling this function.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3><title>See Also</title>
|
|
<para><olink targetptr="ldap-create-authzid-control">ldap_create_authzid_control</olink></para>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="bdauk"><title><function>ldap_parse_entrychange_control</function></title>
|
|
<para>The <function>ldap_parse_entrychange_control</function> function examines
|
|
a list of controls returned from a persistent search operation, retrieves
|
|
an entry change control, and parses that control for information (such as
|
|
the type of change made to the entry and the change number).</para>
|
|
<note><para>This function implements an extension to the LDAP v3. Entry change
|
|
notification is an optional feature; it may not be supported on all LDAP servers.
|
|
Call this function when interacting with LDAP servers that support this LDAP
|
|
v3 extension.</para></note>
|
|
<sect3 id="garvf"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_parse_entrychange_control( LDAP *ld,
|
|
LDAPControl **ctrls, int *chgtypep, char **prevdnp,
|
|
int *chgnumpresentp, long *chgnump );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garvx"><title>Parameters</title>
|
|
<table frame="topbot" id="garuj"><title><function>ldap_parse_entrychange_control</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>ctrlp</literal></para></entry>
|
|
<entry>
|
|
<para>An array of controls returned by the server. You obtain these controls
|
|
by calling the <olink targetptr="bdasl">ldap_get_entry_controls</olink> function
|
|
on an entry returned by the server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>changetypes</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an integer specifying the type of change made to the entry.
|
|
This field can have one of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><literal>LDAP_CHANGETYPE_ADD</literal> specifies that the
|
|
entry was added to the directory.</para></listitem>
|
|
<listitem><para><literal>LDAP_CHANGETYPE_DELETE</literal> specifies that the
|
|
entry was deleted from the directory.</para></listitem>
|
|
<listitem><para><literal>LDAP_CHANGETYPE_MODIFY</literal> specifies that the
|
|
entry was modified.</para></listitem>
|
|
<listitem><para><literal>LDAP_CHANGETYPE_MODDN</literal> specifies that the
|
|
DN or RDN of the entry was changed (a modify RDN or modify DN operation was
|
|
performed).</para></listitem>
|
|
</itemizedlist>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>prevdnp</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to the previous DN of the entry, if the <literal>changetypes</literal> argument
|
|
is <literal>LDAP_CHANGETYPE_MODDN</literal>. If the <literal>changetypes</literal> argument
|
|
has a different value, this argument is set to <literal>NULL</literal>. When
|
|
done, you can free this by calling the <olink targetptr="bdatl">ldap_memfree</olink> function.
|
|
</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>chgnumpresentp</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an integer specifying whether or not to the change number
|
|
is included in the control. The parameter can have the following possible
|
|
values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><literal>0</literal> specifies that the change number is not
|
|
included.</para></listitem>
|
|
<listitem><para>A non-zero value specifies that the change number is included
|
|
and is available as the <literal>chgnump</literal> argument.</para></listitem>
|
|
</itemizedlist>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>chgnump</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to the change number identifying the change made to the entry,
|
|
if <literal>chgnumpresentp</literal> points to a non-zero value.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garur"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
|
|
allocated.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_DECODING_ERROR</errorcode> if an error occurred
|
|
when BER-decoding the control.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garvg"><title>Description</title>
|
|
<para>The <function>ldap_parse_entrychange_control</function> function can
|
|
be called:</para>
|
|
<itemizedlist>
|
|
<listitem><para>To parse an entry returned from a persistent search operation
|
|
and retrieve an entry change control.</para></listitem>
|
|
<listitem><para>After receiving an entry from a persistent search and retrieving
|
|
the controls from the entry. Call <olink targetptr="bdasl">ldap_get_entry_controls
|
|
</olink> to get the controls.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garvn"><title>See Also</title>
|
|
<para><olink targetptr="bdara">ldap_create_persistentsearch_control</olink>, <olink targetptr="bdasl">ldap_get_entry_controls</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaul"><title><function>ldap_parse_extended_result</function></title>
|
|
<para>The <function>ldap_parse_extended_result</function> function parses
|
|
the results of an LDAP extended operation and retrieves the object identifier
|
|
(OID) and data returned by the server.</para>
|
|
<note><para>This function implements an extension to the LDAP v3. Extended
|
|
operations might not be supported on all LDAP servers. Call this function
|
|
only when interacting with LDAP servers that support this LDAP v3 extension.</para>
|
|
</note>
|
|
<sect3 id="garuf"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_parse_extended_result( LDAP *ld, LDAPMessage *res,
|
|
char **retoidp, struct berval **retdatap, int freeit );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garuw"><title>Parameters</title>
|
|
<table frame="topbot" id="garun"><title><function>ldap_parse_extended_result</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameters</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>res</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to the <olink targetptr="bdaly">LDAPMessage</olink> structure
|
|
containing the results of an LDAP operation.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>retoidp</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to the OID returned by the server after performing the extended
|
|
operation. When done, you can free this by calling the <olink targetptr="bdatl">ldap_memfree
|
|
</olink> function.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>retdatap</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to the pointer to a <olink targetptr="bdakg">berval</olink> structure
|
|
containing the data returned by the server after performing the extended operation.
|
|
When done, you can free this by calling the <olink targetptr="bdaoc">ber_bvfree</olink>
|
|
function.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>freeit</literal></para></entry>
|
|
<entry>
|
|
<para>Specifies whether or not to free the results of the operation (the <olink targetptr="bdaly">LDAPMessage</olink> structure specified by the <literal>res</literal> argument).
|
|
The parameter can have the following possible values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><literal>0</literal> specifies that the result should not
|
|
be freed.</para></listitem>
|
|
<listitem><para>A non-zero value specifies that the result should be freed.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garvu"><title>Returns</title>
|
|
<para>One of the following values, which indicates the result of parsing the
|
|
server’s response:</para>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if any of the arguments
|
|
are invalid.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_DECODING_ERROR</errorcode> if an error occurred
|
|
when decoding the BER-encoded results from the server.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_NOT_SUPPORTED</errorcode> if controls are
|
|
included in your request (for example, as a session preference) and your LDAP
|
|
client does not specify that it is using the LDAP v3. Make sure that you set
|
|
the version of your LDAP client to version 3 before calling this function.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<note><para>This value does not apply to the operation itself.</para></note>
|
|
</sect3>
|
|
<sect3 id="garvv"><title>Description</title>
|
|
<para><function>ldap_parse_extended_result</function> parses the server’s
|
|
response to an extended operation. After you call the <olink targetptr="bdaru">ldap_extended_operation
|
|
</olink> and the <olink targetptr="bdauu">ldap_result</olink> functions,
|
|
you can pass the results to <function>ldap_parse_extended_result</function>.
|
|
This function gets the following data from the server’s response:</para>
|
|
<itemizedlist>
|
|
<listitem><para>The extended operation OID received from the server is passed
|
|
back as the retoidp argument.</para></listitem>
|
|
<listitem><para>The data received from the server is passed back in the <olink targetptr="bdakg">berval</olink> structure as the <literal>retdatap</literal> argument.
|
|
</para></listitem>
|
|
<listitem><para>The LDAP result code for the LDAP extended operation is placed
|
|
in the <literal>ld</literal> structure. You can get the result code by calling
|
|
the <olink targetptr="bdasq">ldap_get_lderrno</olink> function.</para><para>For
|
|
a list of possible result codes for an LDAP extended operation, see <olink targetptr="bdarv">ldap_extended_operation_s</olink> .</para></listitem>
|
|
</itemizedlist>
|
|
<note><para>The LDAP server must support the extended operation. &cnDirectoryServer; supports
|
|
a server plug-in interface that you can use to add support for extended operations.
|
|
</para></note>
|
|
</sect3>
|
|
<sect3 id="garuo"><title>See Also</title>
|
|
<para><olink targetptr="bdarv">ldap_extended_operation_s</olink>, <olink targetptr="bdasq">ldap_get_lderrno</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="ldap-parse-passwd"><title><function>ldap_parse_passwd</function></title>
|
|
<para>The <function>ldap_parse_passwd</function> function lets you examine
|
|
the result of an LDAP Password Modify extended operation to obtain the password
|
|
generated by the server when you reset a password without providing a new
|
|
password value.</para>
|
|
<sect3><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
LDAP_API(int) LDAP_CALL ldap_parse_passwd( LDAP *ld, LDAPMessage *result,
|
|
struct berval *genpasswd );</programlisting>
|
|
</sect3>
|
|
<sect3><title>Parameters</title>
|
|
<table frame="topbot" id="gbgovaa"><title><function>ldap_parse_passwd</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2" colsep="0" rowsep="0"><colspec colwidth="50*"><colspec
|
|
colwidth="50*">
|
|
<thead>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>
|
|
<para><parameter>ld</parameter></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><parameter>result</parameter></para></entry>
|
|
<entry>
|
|
<para>Pointer to the message retrieved using the message ID from <olink targetptr="ldap-passwd">ldap_passwd</olink>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><parameter>genpasswd</parameter></para></entry>
|
|
<entry>
|
|
<para>Pointer to the BER value structure to hold the password generated by
|
|
the server.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if any of the arguments
|
|
are invalid.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
|
|
allocated for the authorization identity.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_DECODING_ERROR</errorcode> if an error occurred
|
|
when decoding the BER-encoded message.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_NOT_SUPPORTED</errorcode> if your LDAP client
|
|
does not specify that it is using LDAP v3.</para><para>Make sure that you
|
|
set the version of your LDAP client to version 3 before calling this function.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="ldap-parse-passwd-result"><title><function>ldap_parse_passwd_result</function></title>
|
|
<para>The <function>ldap_parse_passwd_result</function> function lets you
|
|
examine the result of an LDAP Password Modify extended operation to obtain
|
|
the password generated by the server when you reset a password without providing
|
|
a new password value.</para>
|
|
<sect3><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
LDAP_API(int) LDAP_CALL ldap_parse_passwd_result( LDAP *ld, int *msgidp,
|
|
struct timeval *timeout, struct berval *genpasswd );</programlisting>
|
|
</sect3>
|
|
<sect3><title>Parameters</title>
|
|
<table frame="topbot" id="gbgovaaa"><title><function>ldap_parse_passwd_result</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2" colsep="0" rowsep="0"><colspec colwidth="50*"><colspec
|
|
colwidth="50*">
|
|
<thead>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>
|
|
<para><parameter>ld</parameter></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><parameter>msgidp</parameter></para></entry>
|
|
<entry>
|
|
<para>Pointer to the message ID retrieved using <olink targetptr="ldap-passwd">ldap_passwd
|
|
</olink>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><parameter>timeout</parameter></para></entry>
|
|
<entry>
|
|
<para>Specifies a maximum interval to wait for the selection to complete.
|
|
If <parameter>timeout</parameter> is a <literal>NULL</literal> pointer, the
|
|
select blocks indefinitely. To effect a poll, the <parameter>timeout</parameter> parameter
|
|
should be a non-<literal>NULL</literal> pointer, pointing to a zero-valued <structname>
|
|
timeval</structname> structure.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><parameter>genpasswd</parameter></para></entry>
|
|
<entry>
|
|
<para>Pointer to the BER value structure to hold the password generated by
|
|
the server.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if any of the arguments
|
|
are invalid.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
|
|
allocated for the authorization identity.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_DECODING_ERROR</errorcode> if an error occurred
|
|
when decoding the BER-encoded message.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_NOT_SUPPORTED</errorcode> if your LDAP client
|
|
does not specify that it is using LDAP v3.</para><para>Make sure that you
|
|
set the version of your LDAP client to version 3 before calling this function.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="ldap-parse-pwdpolicy-control"><title><function>ldap_parse_pwdpolicy_control
|
|
</function></title>
|
|
<para>The <function>ldap_parse_pwdpolicy_control</function> function parses
|
|
information about the password policy relative to a user account contained
|
|
in a control returned with a bind, add, modify, or compare result after the <olink targetptr="ldap-create-userstatus-control">ldap_create_userstatus_control</olink> is
|
|
used to create a request control sent to the server. The <function>ldap_parse_pwdpolicy_control
|
|
</function> function populates an <olink targetptr="ldappwdpolicy">LDAPpwdpolicy</olink> structure.
|
|
</para>
|
|
<sect3><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
LDAP_API(int) LDAP_CALL ldap_parse_pwdpolicy_control( LDAP *ld,
|
|
LDAPControl **ctrlp, LDAPpwdpolicy *pp );</programlisting>
|
|
</sect3>
|
|
<sect3><title>Parameters</title>
|
|
<table frame="topbot" id="gbgdx"><title><function>ldap_parse_pwdpolicy_control</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2" colsep="0" rowsep="0"><colspec colwidth="50*"><colspec
|
|
colwidth="50*">
|
|
<thead>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>
|
|
<para><parameter>ld</parameter></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><parameter>ctrlp</parameter></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdala">LDAPControl</olink> structure
|
|
retrieved from the server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><parameter>pp</parameter></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="ldappwdpolicy">LDAPpwdpolicy</olink> structure
|
|
to hold the information about password policy.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if any of the arguments
|
|
are invalid.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
|
|
allocated to decode the control returned by the server.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_DECODING_ERROR</errorcode> if an error occurred
|
|
when decoding the BER-encoded message.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_CONTROL_NOT_FOUND</errorcode> if no control
|
|
can be found in the response returned from the server.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_NOT_SUPPORTED</errorcode> if controls are
|
|
included in your request (for example, as a session preference) and your LDAP
|
|
client does not specify that it is using the LDAP v3. Make sure that you set
|
|
the version of your LDAP client to version 3 before calling this function.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3><title>See Also</title>
|
|
<para><olink targetptr="ldap-create-pwdpolicy-control">ldap_create_pwdpolicy_control
|
|
</olink>, <olink targetptr="ldappwdpolicy">LDAPpwdpolicy</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaum"><title><function>ldap_parse_reference</function></title>
|
|
<para>The <function>ldap_parse_reference</function> function parses search
|
|
references from the results received from an LDAP server.</para>
|
|
<note><para>Search references are part of the LDAP v3. When calling this function,
|
|
make sure that you are working with a server that supports the LDAP v3.</para>
|
|
</note>
|
|
<sect3 id="garvh"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_parse_reference( LDAP *ld, LDAPMessage *ref,
|
|
char ***referralsp, LDAPControl ***serverctrlsp,
|
|
int freeit );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garvp"><title>Parameters</title>
|
|
<table frame="topbot" id="garvd"><title><function>ldap_parse_reference</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>ref</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdaly">LDAPMessage</olink> structure
|
|
of the type <literal>LDAP_RES_SEARCH_REFERENCE</literal>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>referralsp</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an array of strings representing the referrals found by an
|
|
LDAP search operation and returned by the server (applicable only if the LDAP
|
|
operation was a search operation). When done, you can free this by calling
|
|
the <olink targetptr="bdaxc">ldap_value_free</olink> function.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>serverctrlsp</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures,
|
|
which represent the LDAP v3 server controls returned by the server. When done,
|
|
you can free this by calling the <olink targetptr="bdaqt">ldap_controls_free</olink> function.
|
|
</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>freeit</literal></para></entry>
|
|
<entry>
|
|
<para>Specifies whether or not to free the results of the operation (the <olink targetptr="bdaly">LDAPMessage</olink> structure specified by the <literal>res</literal> argument).
|
|
The parameter can have the following possible values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><literal>0</literal> specifies that the result should not
|
|
be freed.</para></listitem>
|
|
<listitem><para>A non-zero value specifies that the result should be freed.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garug"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if any of the arguments
|
|
are invalid.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_DECODING_ERROR</errorcode> if an error occurred
|
|
when decoding the BER-encoded results from the server.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
|
|
allocated.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garvz"><title>Description</title>
|
|
<para>The <function>ldap_parse_reference</function> function parses the referral
|
|
URLs from an <olink targetptr="bdaly">LDAPMessage</olink> structure of the
|
|
type <literal>LDAP_RES_SEARCH_REFERENCE</literal>, continuation references
|
|
as specified in LDAPv3 that are stored as referral entries. Like a referral,
|
|
each continuation reference itself may contain a number of URLs assumed to
|
|
be equivalent, and the client should use one of those URLs.</para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaun"><title><function>ldap_parse_result</function></title>
|
|
<para>The <function>ldap_parse_result</function> function parses the results
|
|
of an LDAP operation received from an LDAP server.</para>
|
|
<sect3 id="garuy"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_parse_result( LDAP *ld, LDAPMessage *res,
|
|
int *errcodep, char **matcheddnp, char **errmsgp,
|
|
char ***referralsp, LDAPControl ***serverctrlsp, int freeit);</programlisting>
|
|
</sect3>
|
|
<sect3 id="garux"><title>Parameters</title>
|
|
<table frame="topbot" id="garvt"><title><function>ldap_parse_result</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>res</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to the <olink targetptr="bdaly">LDAPMessage</olink> structure
|
|
containing the results of an LDAP operation.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>errcodep</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to the LDAP result code specifying the result of the operation.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>matcheddnp</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to a string specifying the portion of a DN that finds an existing
|
|
entry (in cases where the server cannot find the entry specified by a DN).
|
|
When done, you can free this by calling the <olink targetptr="bdatl">ldap_memfree
|
|
</olink> function.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>errmsgp</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an additional error message string sent from the server.
|
|
When done, you can free this by calling the <olink targetptr="bdatl">ldap_memfree
|
|
</olink> function.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>referralsp</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an array of strings representing the referrals returned by
|
|
the server. When done, you can free this by calling the <olink targetptr="bdaxc">
|
|
ldap_value_free</olink> function.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>serverctrlsp</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures,
|
|
which represent the LDAPv3 server controls returned by the server. When done,
|
|
you can free this by calling the <olink targetptr="bdaqt">ldap_controls_free</olink> function.
|
|
</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>freeit</literal></para></entry>
|
|
<entry>
|
|
<para>Specifies whether or not to automatically free the results of the operation
|
|
(the <olink targetptr="bdaly">LDAPMessage</olink> structure specified by the
|
|
<literal>res</literal> argument). The parameter can have the following possible
|
|
values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><literal>0</literal> specifies that the result should not
|
|
be freed.</para></listitem>
|
|
<listitem><para>A non-zero value specifies that the result should be freed.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garuq"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_NO_RESULTS_RETURNED</errorcode> if the specified <olink targetptr="bdaly">LDAPMessage</olink> structure does not contain the result
|
|
of an LDAP operation (for example, if it contains an entry, search reference,
|
|
or chain of search results instead of the result of an LDAP operation).</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_MORE_RESULTS_TO_RETURN</errorcode> if the
|
|
result in the <olink targetptr="bdaly">LDAPMessage</olink> structure is part
|
|
of a chain of results and the last result is not included.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if any of the arguments
|
|
are invalid.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_DECODING_ERROR</errorcode> if an error occurred
|
|
when decoding the BER-encoded results from the server.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
|
|
allocated.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garvj"><title>Description</title>
|
|
<para>The <function>ldap_parse_result</function> function parses the results
|
|
of an LDAP operation (received from an LDAP server) and retrieves:</para>
|
|
<itemizedlist>
|
|
<listitem><para>The LDAP result code that indicates the result of the LDAP
|
|
operation (<literal>errcodep</literal>).</para></listitem>
|
|
<listitem><para>An additional error message (<literal>optional</literal>)
|
|
sent by the server (<literal>errmsgp</literal>).</para></listitem>
|
|
<listitem><para>The portion of the DN that finds an entry, if the server is
|
|
unable to find an entry from a DN that you specify (<literal>matcheddnp</literal>).
|
|
</para></listitem>
|
|
<listitem><para>A set of referrals, if the server does not contain the entries
|
|
that you’ve specified and if the server is configured to refer clients
|
|
to other servers (<literal>referralsp</literal>).</para></listitem>
|
|
<listitem><para>A set of server response controls that are relevant to the
|
|
operation (<literal>serverctrlsp</literal>).</para><para>Calling this function
|
|
creates an array of <olink targetptr="bdala">LDAPControl</olink> structures
|
|
that you can pass to subsequent API functions (such as the <olink targetptr="bdaup">ldap_parse_sort_control</olink> function.</para></listitem>
|
|
</itemizedlist>
|
|
<note><para>This function is not intended to be used to parse entries and
|
|
search references. Use the <olink targetptr="bdatx">ldap_msgtype</olink> function
|
|
to determine the type of result contained in the <olink targetptr="bdaly">LDAPMessage
|
|
</olink> structure. If the result is an entry returned as a search result,
|
|
call the <olink targetptr="bdary">ldap_first_entry</olink> function to retrieve
|
|
the entry. If the result is a search reference, call the <olink targetptr="bdaum">
|
|
ldap_parse_reference</olink> function to retrieve the reference.</para></note>
|
|
</sect3>
|
|
<sect3 id="garuh"><title>See Also</title>
|
|
<para><olink targetptr="bdauu">ldap_result</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdauo"><title><function>ldap_parse_sasl_bind_result</function></title>
|
|
<para>The <function>ldap_parse_sasl_bind_result</function> function parses
|
|
the results of an LDAP SASL bind operation and retrieves data returned by
|
|
the server.</para>
|
|
<note><para>SASL authentication is part of the LDAP v3. When calling this
|
|
function, make sure that you are working with a server that supports the LDAP
|
|
v3.</para></note>
|
|
<sect3 id="garud"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_parse_sasl_bind_result( LDAP *ld, LDAPMessage *res,
|
|
struct berval **servercredp, int freeit );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garvm"><title>Parameters</title>
|
|
<table frame="topbot" id="garum"><title><function>ldap_parse_sals_bind_result</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>res</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to the <olink targetptr="bdaly">LDAPMessage</olink> structure
|
|
containing the results of an LDAP operation.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>servercredp</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to a pointer to an <olink targetptr="bdakg">berval</olink> structure
|
|
containing any challenge or credentials returned by the server. When done,
|
|
you can free this by calling the <olink targetptr="bdaoc">ber_bvfree</olink> function.
|
|
</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>freeit</literal></para></entry>
|
|
<entry>
|
|
<para>Specifies whether or not to free the results of the operation (the <olink targetptr="bdaly">LDAPMessage</olink> structure specified by the <literal>res</literal> argument).
|
|
The parameter can have the following possible values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><literal>0</literal> specifies that the result should not
|
|
be freed.</para></listitem>
|
|
<listitem><para>A non-zero value specifies that the result should be freed.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garue"><title>Returns</title>
|
|
<para>One of the following values, which indicates the result of parsing the
|
|
server’s response:</para>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if any of the arguments
|
|
are invalid.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_DECODING_ERROR</errorcode> if an error occurred
|
|
when decoding the BER-encoded message.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_NOT_SUPPORTED</errorcode> if controls are
|
|
included in your request (for example, as a session preference) and your LDAP
|
|
client does not specify that it is using the LDAP v3. Make sure that you set
|
|
the version of your LDAP client to version 3 before calling this function.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<note><para>This value does not apply to the SASL bind operation itself)</para>
|
|
</note>
|
|
</sect3>
|
|
<sect3 id="garve"><title>Description</title>
|
|
<para>After you call the <olink targetptr="bdauw">ldap_sasl_bind</olink> function
|
|
and the <olink targetptr="bdauu">ldap_result</olink> function, you can pass
|
|
the results to <olink targetptr="bdauo">ldap_parse_sasl_bind_result</olink> for
|
|
parsing. This function gets the following data from the server’s response:</para>
|
|
<itemizedlist>
|
|
<listitem><para>The challenge or credentials sent back from the server are
|
|
passed back in the <olink targetptr="bdakg">berval</olink> structure as the <literal>
|
|
servercredp</literal> argument.</para></listitem>
|
|
<listitem><para>The LDAP result code for the SASL bind operation is placed
|
|
in the <literal>ld</literal> structure. You can get the result code by calling
|
|
the <olink targetptr="bdasq">ldap_get_lderrno</olink> function. (If the result
|
|
code is <errorcode>LDAP_SASL_BIND_IN_PROGRESS</errorcode> , you can call <olink targetptr="bdauw">ldap_sasl_bind</olink> again to send a response to the server’s
|
|
challenge and call <olink targetptr="bdauu">ldap_result</olink> and <olink targetptr="bdauo">ldap_parse_sasl_bind_result</olink> again to get the next
|
|
challenge from the server. For a list of possible result codes for an LDAP
|
|
SASL bind operation, see <olink targetptr="bdauw">ldap_sasl_bind</olink>.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<note><para>The LDAP server must support authentication through SASL mechanisms. &cnDirectoryServer; supports
|
|
a plug-in interface that you can use to add SASL support to the server.</para>
|
|
</note>
|
|
</sect3>
|
|
<sect3 id="garva"><title>See Also</title>
|
|
<para><olink targetptr="bdauw">ldap_sasl_bind</olink>, <olink targetptr="bdasq">
|
|
ldap_get_lderrno</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaup"><title><function>ldap_parse_sort_control</function></title>
|
|
<indexterm>
|
|
<primary>C SDK functions</primary>
|
|
<secondary><function>ldap_parse_sort_control</function></secondary>
|
|
</indexterm><indexterm>
|
|
<primary><function>ldap_parse_sort_control</function></primary>
|
|
</indexterm>
|
|
<para>The <function>parse_sort_control</function> function parses the result
|
|
returned from a search operation that used a server control for sorting search
|
|
results.</para>
|
|
<note><para>This function implements an extension to the LDAP v3. Server-side
|
|
sorting is an optional feature; it may not be supported on all LDAP servers.
|
|
Call this function when interacting with LDAP servers that support this LDAP
|
|
v3 extension</para></note>
|
|
<sect3 id="garvc"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_parse_sort_control( LDAP *ld, LDAPControl **ctrls,
|
|
unsigned long *result, char **attribute );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garuz"><title>Parameters</title>
|
|
<table frame="topbot" id="garup"><title><function>ldap_parse_sort_control</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameters</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>ctrls</literal></para></entry>
|
|
<entry>
|
|
<para>An array of controls returned by the server. You obtain these controls
|
|
by calling the <olink targetptr="bdaun">ldap_parse_result</olink> function
|
|
on the set of results returned by the server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>result</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to the sort control result code retrieved by this function.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>attribute</literal></para></entry>
|
|
<entry>
|
|
<para>If the sorting operation fails, the function sets this to point to the
|
|
name of the attribute that caused the failure. When done, you can free this
|
|
by calling the <olink targetptr="bdatl">ldap_memfree</olink> function.</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garul"><title>Returns</title>
|
|
<para>One of the following values, which indicates the result of parsing the
|
|
server’s response:</para>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if any of the arguments
|
|
are invalid.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
|
|
allocated to decode the control returned by the server.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_DECODING_ERROR</errorcode> if an error occurred
|
|
when decoding the BER-encoded message.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_CONTROL_NOT_FOUND</errorcode> if no control
|
|
can be found in the response returned from the server.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garvk"><title>Description</title>
|
|
<para>Call the <function>ldap_parse_sort_control</function> function as part
|
|
of the process of retrieving sorted search results from a server. First, though,
|
|
call <olink targetptr="bdauu">ldap_result</olink> to get the results, and
|
|
<olink targetptr="bdaun">ldap_parse_result</olink> to parse the server controls
|
|
from the results.</para></sect3>
|
|
<sect3 id="garvi"><title>See Also</title>
|
|
<para><olink targetptr="bdare">ldap_create_sort_control</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="ldap-parse-userstatus-control"><title><function>ldap_parse_userstatus_control
|
|
</function></title>
|
|
<indexterm>
|
|
<primary>C SDK functions</primary>
|
|
<secondary><function>ldap_parse_userstatus_control</function></secondary>
|
|
</indexterm><indexterm>
|
|
<primary><function>ldap_parse_userstatus_control</function></primary>
|
|
</indexterm>
|
|
<para>The <function>ldap_parse_userstatus_control</function> function parses
|
|
information about the status of a user account contained in a control returned
|
|
with an entry resulting from a search request that included the control created
|
|
with <olink targetptr="ldap-create-userstatus-control">ldap_create_userstatus_control
|
|
</olink>. The <function>ldap_parse_userstatus_control</function> function
|
|
populates an <olink targetptr="ldapuserstatus">LDAPuserstatus</olink> structure.</para>
|
|
<sect3><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
LDAP_API(int) LDAP_CALL ldap_parse_userstatus_control( LDAP *ld,
|
|
LDAPControl **ctrlp, LDAPuserstatus *us );</programlisting>
|
|
</sect3>
|
|
<sect3><title>Parameters</title>
|
|
<table frame="topbot" id="gbgdl"><title><function>ldap_parse_userstatus_control</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2" colsep="0" rowsep="0"><colspec colwidth="50*"><colspec
|
|
colwidth="50*">
|
|
<thead>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>
|
|
<para><parameter>ld</parameter></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><parameter>ctrlp</parameter></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdala">LDAPControl</olink> structure
|
|
retrieved with <olink targetptr="bdasl">ldap_get_entry_controls</olink>.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><parameter>us</parameter></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="ldapuserstatus">LDAPuserstatus</olink> structure
|
|
to hold the information about account status.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if any of the arguments
|
|
are invalid.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
|
|
allocated to decode the control returned by the server.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_DECODING_ERROR</errorcode> if an error occurred
|
|
when decoding the BER-encoded message.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_CONTROL_NOT_FOUND</errorcode> if no control
|
|
can be found in the response returned from the server.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_NOT_SUPPORTED</errorcode> if controls are
|
|
included in your request (for example, as a session preference) and your LDAP
|
|
client does not specify that it is using the LDAP v3. Make sure that you set
|
|
the version of your LDAP client to version 3 before calling this function.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3><title>See Also</title>
|
|
<para><olink targetptr="ldap-create-userstatus-control">ldap_create_userstatus_control
|
|
</olink>, <olink targetptr="ldapuserstatus">LDAPuserstatus</olink></para>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="ldap-parse-whoami"><title><function>ldap_parse_whoami</function></title>
|
|
<indexterm>
|
|
<primary>C SDK functions</primary>
|
|
<secondary><function>ldap_parse_whoami</function></secondary>
|
|
</indexterm><indexterm>
|
|
<primary><function>ldap_parse_whoami</function></primary>
|
|
</indexterm>
|
|
<para>The <function>ldap_parse_whoami</function> function retrieves the authorization
|
|
identity from the result of an asynchronous Who am I? extended operation request.
|
|
</para>
|
|
<sect3><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
LDAP_API(int) LDAP_CALL ldap_parse_whoami_result( LDAP *ld,
|
|
LDAPMessage *result, char **authzid );</programlisting>
|
|
</sect3>
|
|
<sect3><title>Parameters</title>
|
|
<table frame="topbot" id="gbgova"><title><function>ldap_parse_whoami</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2" colsep="0" rowsep="0"><colspec colwidth="50*"><colspec
|
|
colwidth="50*">
|
|
<thead>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>
|
|
<para><parameter>ld</parameter></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><parameter>result</parameter></para></entry>
|
|
<entry>
|
|
<para>Pointer to the message retrieved using the message ID from <olink targetptr="ldap-whoami">ldap_whoami</olink>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><parameter>authzid</parameter></para></entry>
|
|
<entry>
|
|
<para>Pointer to the string to hold the authorization identity retrieved for
|
|
the connection.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if any of the arguments
|
|
are invalid.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
|
|
allocated for the authorization identity.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_DECODING_ERROR</errorcode> if an error occurred
|
|
when decoding the BER-encoded message.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_NOT_SUPPORTED</errorcode> if your LDAP client
|
|
does not specify that it is using LDAP v3. Make sure that you set the version
|
|
of your LDAP client to version 3 before calling this function.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="ldap-parse-whoami-result"><title><function>ldap_parse_whoami_result</function></title>
|
|
<indexterm>
|
|
<primary>C SDK functions</primary>
|
|
<secondary><function>ldap_parse_whoami_result</function></secondary>
|
|
</indexterm><indexterm>
|
|
<primary><function>ldap_parse_whoami_result</function></primary>
|
|
</indexterm>
|
|
<para>The <function>ldap_parse_whoami_result</function> function retrieves
|
|
the authorization identity from the result of an asynchronous Who am I? extended
|
|
operation request.</para>
|
|
<sect3><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
LDAP_API(int) LDAP_CALL ldap_parse_whoami_result( LDAP *ld, int *msgidp,
|
|
struct timeval *timeout, char **authzid );</programlisting>
|
|
</sect3>
|
|
<sect3><title>Parameters</title>
|
|
<table frame="topbot" id="gbgov"><title><function>ldap_parse_whoami_result</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2" colsep="0" rowsep="0"><colspec colwidth="50*"><colspec
|
|
colwidth="50*">
|
|
<thead>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>
|
|
<para><parameter>ld</parameter></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><parameter>msgidp</parameter></para></entry>
|
|
<entry>
|
|
<para>Pointer to the message ID retrieved using <olink targetptr="ldap-whoami">ldap_whoami
|
|
</olink>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><parameter>timeout</parameter></para></entry>
|
|
<entry>
|
|
<para>Specifies a maximum interval to wait for the selection to complete.
|
|
If <parameter>timeout</parameter> is a <literal>NULL</literal> pointer, the
|
|
select blocks indefinitely. To effect a poll, the <parameter>timeout</parameter> parameter
|
|
should be a non-<literal>NULL</literal> pointer, pointing to a zero-valued <structname>
|
|
timeval</structname> structure.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><parameter>authzid</parameter></para></entry>
|
|
<entry>
|
|
<para>Pointer to the string to hold the authorization identity retrieved for
|
|
the connection.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if any of the arguments
|
|
are invalid.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
|
|
allocated for the authorization identity.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_DECODING_ERROR</errorcode> if an error occurred
|
|
when decoding the BER-encoded message.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_NOT_SUPPORTED</errorcode> if your LDAP client
|
|
does not specify that it is using LDAP v3. Make sure that you set the version
|
|
of your LDAP client to version 3 before calling this function.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="bdauq"><title><function>ldap_parse_virtuallist_control</function></title>
|
|
<indexterm>
|
|
<primary>C SDK functions</primary>
|
|
<secondary><function>ldap_parse_virtuallist_control</function></secondary>
|
|
</indexterm><indexterm>
|
|
<primary><function>ldap_parse_virtuallist_control</function></primary>
|
|
</indexterm>
|
|
<para>The <function>ldap_parse_virtuallist_control</function> function parses
|
|
the result returned from a search operation that used a server control for
|
|
virtual list views.</para>
|
|
<note><para>This function implements an extension to the LDAP v3. A <emphasis>virtual
|
|
list view</emphasis> is an optional LDAP server feature that may not be supported
|
|
on all LDAP servers.</para></note>
|
|
<sect3 id="garut"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_parse_virtuallist_control( LDAP *ld,
|
|
LDAPControl **ctrls, unsigned long *target_posp,
|
|
unsigned long *list_sizep, int *errcodep );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garuu"><title>Parameters</title>
|
|
<table frame="topbot" id="garvq"><title><function>ldap_parse_virtuallist_control</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameters</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>ctrls</literal></para></entry>
|
|
<entry>
|
|
<para>An array of controls returned by the server. You obtain these controls
|
|
by calling the <olink targetptr="bdaun">ldap_parse_result</olink> function
|
|
on the set of results returned by the server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>target_posp</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an unsigned long that is set by the function. The function
|
|
sets this to the index or offset of the selected entry in the list of entries.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>list_sizep</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an unsigned long that is set by the function. The function
|
|
sets this to the number of entries in the total number of entries in the entire
|
|
list (not just the subset).</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>errcodep</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to the sort control result code retrieved by this function.</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garwa"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if any of the arguments
|
|
are invalid.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
|
|
allocated to decode the control returned by the server.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_DECODING_ERROR</errorcode> if an error occurred
|
|
when decoding the BER-encoded message.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_CONTROL_NOT_FOUND</errorcode> if no control
|
|
can be found in the response returned from the server.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_NOT_SUPPORTED</errorcode> if controls are
|
|
included in your request (for example, as a session preference) and your LDAP
|
|
client does not specify that it is using the LDAP v3. Make sure that you set
|
|
the version of your LDAP client to version 3 before calling this function.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garuk"><title>Description</title>
|
|
<para>The <function>ldap_parse_virtuallist_control</function> function can
|
|
be called:</para>
|
|
<itemizedlist>
|
|
<listitem><para>As part of the process of retrieving a subset of entries from
|
|
a list when working with a virtual list view box.</para></listitem>
|
|
<listitem><para>After, calling <olink targetptr="bdauu">ldap_result</olink> to
|
|
get the results, and <olink targetptr="bdaun">ldap_parse_result</olink> to
|
|
parse the server controls from the results.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garvs"><title>See Also</title>
|
|
<para><olink targetptr="bdarg">ldap_create_virtuallist_control</olink></para>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="ldap-passwd"><title><function>ldap_passwd</function></title>
|
|
<indexterm>
|
|
<primary>C SDK functions</primary>
|
|
<secondary><function>ldap_passwd</function></secondary>
|
|
</indexterm><indexterm>
|
|
<primary><function>ldap_passwd</function></primary>
|
|
</indexterm>
|
|
<para>The <function>ldap_passwd</function> asynchronous function allows you
|
|
to perform an LDAP Password Modify extended operation, as defined in <ulink
|
|
url="http://ietf.org/rfc/rfc3062.txt" type="text_url">RFC 3062</ulink>.</para>
|
|
<sect3><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_passwd( LDAP *ld, struct berval *userid,
|
|
struct berval *oldpasswd, struct berval *newpasswd,
|
|
LDAPControl **serverctrls, LDAPControl **clientctrls,
|
|
int *msgidp );</programlisting>
|
|
</sect3>
|
|
<sect3><title>Parameters</title>
|
|
<table frame="topbot" id="gbgvv"><title><function>ldap_passwd</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2" colsep="0" rowsep="0"><colspec colwidth="50*"><colspec
|
|
colwidth="50*">
|
|
<thead>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>userid</literal></para></entry>
|
|
<entry>
|
|
<para>DN of the user whose password you want to modify.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>oldpasswd</literal></para></entry>
|
|
<entry>
|
|
<para>Old password used before expiration.</para>
|
|
<para>If the password has not yet expired, this is the current password.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>newpasswd</literal></para></entry>
|
|
<entry>
|
|
<para>New password to use after modification</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>serverctrls</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
|
|
representing LDAP server controls that apply to this LDAP operation. If you
|
|
do not want to pass any server controls, specify <literal>NULL</literal> for
|
|
this argument.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>clientctrls</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
|
|
representing LDAP client controls that apply to this LDAP operation. If you
|
|
do not want to pass any client controls, specify <literal>NULL</literal> for
|
|
this argument.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>msgidp</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an integer to be set to the message ID of the operation.</para>
|
|
<para>To check the result of this operation, call the <olink targetptr="bdauu">ldap_result
|
|
</olink> and <olink targetptr="ldap-parse-passwd">ldap_parse_passwd</olink> function,
|
|
or <olink targetptr="ldap-parse-passwd-result">ldap_parse_passwd_result</olink> function.
|
|
</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if an invalid parameter
|
|
was passed to the function.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
|
|
allocated.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_ENCODING_ERROR</errorcode> if an error occurred
|
|
when BER-encoding the control.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_SERVER_DOWN</errorcode> if the LDAP server
|
|
did not receive the request or if the connection to the server was lost.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_NOT_SUPPORTED</errorcode> if your LDAP client
|
|
does not specify that it is using LDAP v3.</para><para>Make sure that you
|
|
set the version of your LDAP client to version 3 before calling this function.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="ldap-passwd-s"><title><function>ldap_passwd_s</function></title>
|
|
<indexterm>
|
|
<primary>C SDK functions</primary>
|
|
<secondary><function>ldap_passwd_s</function></secondary>
|
|
</indexterm><indexterm>
|
|
<primary><function>ldap_passwd_s</function></primary>
|
|
</indexterm>
|
|
<para>The <function>ldap_passwd_s</function> synchronous function allows you
|
|
to perform an LDAP Password Modify extended operation, as defined in <ulink
|
|
url="http://ietf.org/rfc/rfc3062.txt" type="text_url">RFC 3062</ulink>.</para>
|
|
<sect3><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_passwd_s( LDAP *ld, struct berval *userid,
|
|
struct berval *oldpasswd, struct berval *newpasswd,
|
|
struct berval *genpasswd, LDAPControl **serverctrls,
|
|
LDAPControl **clientctrls );</programlisting>
|
|
</sect3>
|
|
<sect3><title>Parameters</title>
|
|
<table frame="topbot" id="gbgvva"><title><function>ldap_passwd</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2" colsep="0" rowsep="0"><colspec colwidth="50*"><colspec
|
|
colwidth="50*">
|
|
<thead>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>userid</literal></para></entry>
|
|
<entry>
|
|
<para>DN of the user whose password you want to modify.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>oldpasswd</literal></para></entry>
|
|
<entry>
|
|
<para>Old password used before expiration.</para>
|
|
<para>If the password has not yet expired, this is the current password.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>newpasswd</literal></para></entry>
|
|
<entry>
|
|
<para>New password to use after modification</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>genpasswd</literal></para></entry>
|
|
<entry>
|
|
<para>New password generated by the server when an expired password is reset,
|
|
but no <literal>newpasswd</literal> value is provided.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>serverctrls</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
|
|
representing LDAP server controls that apply to this LDAP operation. If you
|
|
do not want to pass any server controls, specify <literal>NULL</literal> for
|
|
this argument.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>clientctrls</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
|
|
representing LDAP client controls that apply to this LDAP operation. If you
|
|
do not want to pass any client controls, specify <literal>NULL</literal> for
|
|
this argument.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if an invalid parameter
|
|
was passed to the function.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
|
|
allocated.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_ENCODING_ERROR</errorcode> if an error occurred
|
|
when BER-encoding the control.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_SERVER_DOWN</errorcode> if the LDAP server
|
|
did not receive the request or if the connection to the server was lost.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_NOT_SUPPORTED</errorcode> if your LDAP client
|
|
does not specify that it is using LDAP v3.</para><para>Make sure that you
|
|
set the version of your LDAP client to version 3 before calling this function.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="bdaur"><title><function>ldap_perror</function></title>
|
|
<indexterm>
|
|
<primary>C SDK functions</primary>
|
|
<secondary><function>ldap_perror</function></secondary>
|
|
</indexterm><indexterm>
|
|
<primary><function>ldap_perror</function></primary>
|
|
</indexterm>
|
|
<note><para>This function is deprecated and should not be used. It is included
|
|
in <literal>ldap-deprecated.h</literal> for backward-compatibility. Use <olink targetptr="bdasq">ldap_get_lderrno</olink> instead.</para></note>
|
|
<para>The <function>ldap_perror</function> function prints, to standard output,
|
|
the last LDAP error message.</para>
|
|
<sect3 id="garwu"><title>Syntax</title>
|
|
<programlisting>#include <ldap-deprecated.h>
|
|
void ldap_perror( LDAP *ld, const char *s );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garxv"><title>Parameters</title>
|
|
<table frame="topbot" id="garws"><title><function>ldap_perror</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>s</literal></para></entry>
|
|
<entry>
|
|
<para>Optional text to print out before printing the error message.</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garwf"><title>Description</title>
|
|
<para>Use the newer version of this function, <olink targetptr="bdasq">ldap_get_lderrno
|
|
</olink> .</para></sect3>
|
|
<sect3 id="garwt"><title>Example</title>
|
|
<para><olink targetptr="ldap-perror-example">Example 21–43</olink> prints
|
|
out an error message if the search operation cannot complete successfully.</para>
|
|
<example id="ldap-perror-example"><title>Using <function>ldap_perror</function></title>
|
|
<programlisting>...
|
|
if ( ldap_search_s( ld, my_searchbase, LDAP_SCOPE_SUBTREE, my_filter,
|
|
get_attr, 0, &result ) != LDAP_SUCCESS ) {
|
|
ldap_perror( ld, "ldap_search_s" );
|
|
return( 1 );
|
|
...</programlisting>
|
|
</example>
|
|
</sect3>
|
|
<sect3 id="garwv"><title>See Also</title>
|
|
<para><olink targetptr="bdasq">ldap_get_lderrno</olink>, <olink targetptr="bdarq">ldap_err2string</olink>, <olink targetptr="bdauv">ldap_result2error
|
|
</olink>, <olink targetptr="bdavf">ldap_set_lderrno</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaus"><title><function>ldap_rename</function></title>
|
|
<indexterm>
|
|
<primary>C SDK functions</primary>
|
|
<secondary><function>ldap_rename</function></secondary>
|
|
</indexterm><indexterm>
|
|
<primary><function>ldap_rename</function></primary>
|
|
</indexterm>
|
|
<para>The <function>ldap_rename</function> function changes the DN of an entry
|
|
in the directory asynchronously.</para>
|
|
<note><para><function>ldap_rename</function> is a new version of the <olink targetptr="bdats">ldap_modrdn2</olink> function. If you are writing a new
|
|
LDAP client, you should call <function>ldap_rename</function>.</para></note>
|
|
<sect3 id="garwo"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_rename( LDAP *ld, const char *dn, const char *newrdn,
|
|
const char *newparent, int deleteoldrdn,
|
|
LDAPControl **serverctrls, LDAPControl **clientctrls,
|
|
int *msgidp );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garxu"><title>Parameters</title>
|
|
<table frame="topbot" id="garxx"><title><function>ldap_rename</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>dn</literal></para></entry>
|
|
<entry>
|
|
<para>DN of the entry to rename.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>newrdn</literal></para></entry>
|
|
<entry>
|
|
<para>New Relative Distinguished Name (RDN) to assign to the entry.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>newparent</literal></para></entry>
|
|
<entry>
|
|
<para>DN of the new parent entry you want to move the entry under. Pass <literal>
|
|
NULL</literal> if you do not want to move the entry to a different location
|
|
in the directory tree.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>deleteoldrdn</literal></para></entry>
|
|
<entry>
|
|
<para>Specifies whether or not the old RDN is retained as an attribute of
|
|
the entry. For example, an entry has the following values for the <literal>cn</literal> attribute:
|
|
</para>
|
|
<para><literal>cn: Barbara Jensen</literal></para>
|
|
<para><literal>cn: Babs Jensen</literal></para>
|
|
<para>If you change the RDN to <literal>cn=Barbie Jensen</literal> and pass
|
|
<literal>1</literal> as <literal>deleteoldrdn</literal>, the resulting entry
|
|
has the following values:</para>
|
|
<para><literal>cn: Barbie Jensen</literal></para>
|
|
<para><literal>cn: Babs Jensen</literal></para>
|
|
<para>If instead you pass <literal>0</literal> as <literal>deleteoldrdn</literal>,
|
|
the <literal>Barbara Jensen</literal> value is not removed from the entry:</para>
|
|
<para><literal>cn: Barbie Jensen</literal></para>
|
|
<para><literal>cn: Babs Jensen</literal></para>
|
|
<para><literal>cn: Barbara Jensen</literal></para>
|
|
<para>So, if this is a non-zero value, the old RDN is not retained as a value
|
|
in the entry. If <literal>0</literal>, the old RDN is retained as an attribute
|
|
in the entry.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>serverctrls</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
|
|
representing LDAP server controls that apply to this LDAP operation. If you
|
|
do not want to pass any server controls, specify <literal>NULL</literal> for
|
|
this argument.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>clientctrls</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
|
|
representing LDAP client controls that apply to this LDAP operation. If you
|
|
do not want to pass any client controls, specify <literal>NULL</literal> for
|
|
this argument.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>msgidp</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an integer that will be set to the message ID of the LDAP
|
|
operation. To check the result of this operation, call the <olink targetptr="bdauu">ldap_result</olink> and <olink targetptr="bdaun">ldap_parse_result
|
|
</olink> functions.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garwl"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if any of the arguments
|
|
are invalid.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
|
|
allocated to decode the control returned by the server.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_ENCODING_ERROR</errorcode> if an error occurred
|
|
when BER-encoding the request.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_SERVER_DOWN</errorcode> if the LDAP server
|
|
did not receive the request or if the connection to the server was lost.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_NOT_SUPPORTED</errorcode> if controls are
|
|
included in your request (for example, as a session preference) and your LDAP
|
|
client does not specify that it is using the LDAP v3. Make sure that you set
|
|
the version of your LDAP client to version 3 before calling this function.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garxk"><title>Description</title>
|
|
<para>The <function>ldap_rename</function> changes the DN of an entry in the
|
|
directory and allows you to move the entry under a different parent entry
|
|
in the directory tree. <function>ldap_rename</function> is an asynchronous
|
|
function; it does not directly return results. In order to get the results
|
|
of the LDAP rename operation, you need to call the <olink targetptr="bdauu">ldap_result
|
|
</olink> function and the <olink targetptr="bdaun">ldap_parse_result</olink> function.
|
|
If you want the results to be returned directly by the function, call the
|
|
synchronous function <olink targetptr="bdaut">ldap_rename_s</olink> instead.</para>
|
|
</sect3>
|
|
<sect3 id="garwk"><title>See Also</title>
|
|
<para><olink targetptr="bdaut">ldap_rename_s</olink>, <olink targetptr="bdauu">ldap_result
|
|
</olink>, <olink targetptr="bdaun">ldap_parse_result</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaut"><title><function>ldap_rename_s</function></title>
|
|
<indexterm>
|
|
<primary>C SDK functions</primary>
|
|
<secondary><function>ldap_rename_s</function></secondary>
|
|
</indexterm><indexterm>
|
|
<primary><function>ldap_rename_s</function></primary>
|
|
</indexterm>
|
|
<para>The <function>ldap_rename_s</function> function changes the DN of an
|
|
entry in the directory synchronously.</para>
|
|
<note><para><function>ldap_rename_s</function> is a new version of the <olink targetptr="bdatt">ldap_modrdn2_s</olink> function. If you are writing a new
|
|
LDAP client, you should call <function>ldap_rename_s</function>.</para></note>
|
|
<sect3 id="garxh"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_rename_s( LDAP *ld, const char *dn, const char *newrdn,
|
|
const char *newparent, int deleteoldrdn,
|
|
LDAPControl **serverctrls, LDAPControl **clientctrls );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garxt"><title>Parameters</title>
|
|
<table frame="topbot" id="garyd"><title><function>ldap_rename</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>dn</literal></para></entry>
|
|
<entry>
|
|
<para>DN of the entry to rename.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>newrdn</literal></para></entry>
|
|
<entry>
|
|
<para>New Relative Distinguished Name (RDN) to assign to the entry.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>newparent</literal></para></entry>
|
|
<entry>
|
|
<para>DN of the new parent entry you want to move the entry under. Pass <literal>
|
|
NULL</literal> if you do not want to move the entry to a different location
|
|
in the directory tree.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>deleteoldrdn</literal></para></entry>
|
|
<entry>
|
|
<para>Specifies whether or not the old RDN is retained as an attribute of
|
|
the entry. For example, an entry has the following values for the <literal>cn</literal> attribute:
|
|
</para>
|
|
<para><literal>cn: Barbara Jensen</literal></para>
|
|
<para><literal>cn: Babs Jensen</literal></para>
|
|
<para>If you change the RDN to <literal>cn=Barbie Jensen</literal> and pass
|
|
<literal>1</literal> as <literal>deleteoldrdn</literal>, the resulting entry
|
|
has the following values:</para>
|
|
<para><literal>cn: Barbie Jensen</literal></para>
|
|
<para><literal>cn: Babs Jensen</literal></para>
|
|
<para>If instead you pass <literal>0</literal> as <literal>deleteoldrdn</literal>,
|
|
the <literal>Barbara Jensen</literal> value is not removed from the entry:</para>
|
|
<para><literal>cn: Barbie Jensen</literal></para>
|
|
<para><literal>cn: Babs Jensen</literal></para>
|
|
<para><literal>cn: Barbara Jensen</literal></para>
|
|
<para>So, if this is a non-zero value, the old RDN is not retained as a value
|
|
in the entry. If <literal>0</literal>, the old RDN is retained as an attribute
|
|
in the entry.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>serverctrls</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
|
|
representing LDAP server controls that apply to this operation. If you do
|
|
not want to pass any server controls, specify <literal>NULL</literal> for
|
|
this argument.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>clientctrls</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
|
|
representing LDAP client controls that apply to this operation. If you do
|
|
not want to pass any client controls, specify <literal>NULL</literal> for
|
|
this argument.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garxj"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if any of the arguments
|
|
are invalid.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
|
|
allocated to decode the control returned by the server.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_ENCODING_ERROR</errorcode> if an error occurred
|
|
when BER-encoding the request.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_SERVER_DOWN</errorcode> if the LDAP server
|
|
did not receive the request or if the connection to the server was lost.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_LOCAL_ERROR</errorcode> if an error occurred
|
|
when receiving the results from the server.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_DECODING_ERROR</errorcode> if an error occurred
|
|
when decoding the BER-encoded results from the server.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_NOT_SUPPORTED</errorcode> if controls are
|
|
included in your request (for example, as a session preference) and your LDAP
|
|
client does not specify that it is using the LDAPv3. Make sure that you set
|
|
the version of your LDAP client to version 3 before calling this function.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<note><para>&cnDirectoryServer; and other LDAP server products may send result
|
|
codes in addition to those described. For example, the server may have loaded
|
|
a plug-in that returns custom result codes. Check your LDAP server documentation
|
|
for other result codes.</para></note>
|
|
</sect3>
|
|
<sect3 id="garwq"><title>Description</title>
|
|
<para>The <function>ldap_rename_s</function> changes the DN of an entry in
|
|
the directory and allows you to move the entry under a different parent entry
|
|
in the directory tree. The function <function>ldap_rename_s</function> is
|
|
synchronous; it directly returns the results of the operation. If you want
|
|
to perform other operations while waiting for the results of this operation,
|
|
call the asynchronous function <olink targetptr="bdaus">ldap_rename</olink>.</para>
|
|
</sect3>
|
|
<sect3 id="garxa"><title>See Also</title>
|
|
<para><olink targetptr="bdaus">ldap_rename</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdauu"><title><function>ldap_result</function></title>
|
|
<indexterm>
|
|
<primary>C SDK functions</primary>
|
|
<secondary><function>ldap_result</function></secondary>
|
|
</indexterm><indexterm>
|
|
<primary><function>ldap_result</function></primary>
|
|
</indexterm>
|
|
<para>The function <function>ldap_result</function> waits for and returns
|
|
the result of an LDAP operation initiated by one of the asynchronous LDAP
|
|
API functions.</para>
|
|
<sect3 id="garwz"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_result( LDAP *ld, int msgid, int all,
|
|
struct timeval *timeout, LDAPMessage **result );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garxg"><title>Parameters</title>
|
|
<table frame="topbot" id="garxy"><title><function>ldap_result</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>msgid</literal></para></entry>
|
|
<entry>
|
|
<para>Asynchronous functions return a unique message ID. This parameter takes
|
|
message ID of the operation for which you want the results. To check any operation,
|
|
pass <literal>LDAP_RES_ANY</literal> as the value of this parameter.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>all</literal></para></entry>
|
|
<entry>
|
|
<para>Specifies how the results of a search are returned. This parameter can
|
|
have the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><literal>0</literal> specifies that the results are returned
|
|
one entry at a time, using separate calls to <function>ldap_result</function>.</para>
|
|
</listitem>
|
|
<listitem><para>A non-zero value specifies that all results are returned at
|
|
the same time (after the final search result is obtained by the library).</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>timeout</literal></para></entry>
|
|
<entry>
|
|
<para>Specifies a maximum interval to wait for the selection to complete.
|
|
If <parameter>timeout</parameter> is a <literal>NULL</literal> pointer, the
|
|
select blocks indefinitely. To effect a poll, the <literal>timeout</literal> parameter
|
|
should be a non-<literal>NULL</literal> pointer, pointing to a zero-valued <structname>
|
|
timeval</structname> structure.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>result</literal></para></entry>
|
|
<entry>
|
|
<para>Result of the operation. To interpret the results, pass this to the
|
|
LDAP parsing routines, such as <olink targetptr="bdauv">ldap_result2error</olink>,
|
|
<olink targetptr="bdaun">ldap_parse_result</olink>, and <olink targetptr="bdary">
|
|
ldap_first_entry</olink>.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garwm"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><literal>LDAP_RES_BIND</literal> indicates that the <olink targetptr="bdaly">LDAPMessage</olink> structure contains the result of an
|
|
LDAP bind operation.</para></listitem>
|
|
<listitem><para><literal>LDAP_RES_SEARCH_ENTRY</literal> indicates that the <olink targetptr="bdaly">LDAPMessage</olink> structure contains an entry found during
|
|
an LDAP search operation.</para></listitem>
|
|
<listitem><para><literal>LDAP_RES_SEARCH_REFERENCE</literal> indicates that
|
|
the <olink targetptr="bdaly">LDAPMessage</olink> structure contains an LDAPv3
|
|
search reference (a referral to another LDAP server) found during an LDAP
|
|
search operation.</para></listitem>
|
|
<listitem><para><literal>LDAP_RES_SEARCH_RESULT</literal> indicates that the <olink targetptr="bdaly">LDAPMessage</olink> structure contains the result of an
|
|
LDAP search operation.</para></listitem>
|
|
<listitem><para><literal>LDAP_RES_MODIFY</literal> indicates that the <olink targetptr="bdaly">LDAPMessage</olink> structure contains the result of an
|
|
LDAP modify operation.</para></listitem>
|
|
<listitem><para><literal>LDAP_RES_ADD</literal> indicates that the <olink targetptr="bdaly">LDAPMessage</olink> structure contains the result of an
|
|
LDAP add operation.</para></listitem>
|
|
<listitem><para><literal>LDAP_RES_DELETE</literal> indicates that the <olink targetptr="bdaly">LDAPMessage</olink> structure contains the result of an
|
|
LDAP delete operation.</para></listitem>
|
|
<listitem><para><literal>LDAP_RES_MODDN</literal> or <literal>LDAP_RES_RENAME</literal> indicates
|
|
that the <olink targetptr="bdaly">LDAPMessage</olink> structure contains the
|
|
result of an LDAP modify DN operation.</para></listitem>
|
|
<listitem><para><literal>LDAP_RES_COMPARE</literal> indicates that the <olink targetptr="bdaly">LDAPMessage</olink> structure contains the result of an
|
|
LDAP compare operation.</para></listitem>
|
|
<listitem><para><literal>LDAP_RES_EXTENDED</literal> indicates that the <olink targetptr="bdaly">LDAPMessage</olink> structure contains the result of an
|
|
LDAP v3 extended operation.</para></listitem>
|
|
<listitem><para><literal>-1</literal> indicates that an error occurred. The
|
|
error code is set in the <olink targetptr="bdakj">LDAP</olink> structure.
|
|
To get the error code, call the <olink targetptr="bdasq">ldap_get_lderrno</olink> function.
|
|
</para></listitem>
|
|
<listitem><para><literal>0</literal> indicates that the operation has timed
|
|
out.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garwh"><title>See Also</title>
|
|
<para><olink targetptr="bdaqa">ldap_add_ext</olink>, <olink targetptr="bdaqp">ldap_compare_ext
|
|
</olink> , <olink targetptr="bdari">ldap_delete_ext</olink>, <olink targetptr="bdatn">ldap_modify_ext</olink>, <olink targetptr="bdaus">ldap_rename</olink>, <olink targetptr="bdavi">ldap_simple_bind</olink>, <olink targetptr="bdawm">ldap_url_search
|
|
</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdauv"><title><function>ldap_result2error</function></title>
|
|
<indexterm>
|
|
<primary>C SDK functions</primary>
|
|
<secondary><function>ldap_result2error</function></secondary>
|
|
</indexterm><indexterm>
|
|
<primary><function>ldap_result2error</function></primary>
|
|
</indexterm>
|
|
<note><para>This function is deprecated and should not be used. It is included
|
|
in <literal>ldap-deprecated.h</literal> for backward-compatibility. Use the
|
|
newer version, <olink targetptr="bdaun">ldap_parse_result</olink>.</para></note>
|
|
<para>The <function>ldap_result2error</function> function returns the corresponding
|
|
error code for a result produced by the <olink targetptr="bdauu">ldap_result</olink> and <olink targetptr="bdavb">ldap_search_s</olink> functions.</para>
|
|
<sect3 id="garxo"><title>Syntax</title>
|
|
<programlisting>#include <ldap-deprecated.h>
|
|
int ldap_result2error( LDAP *ld, LDAPMessage *r, int freeit );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garwy"><title>Parameters</title>
|
|
<table frame="topbot" id="garwn"><title><function>ldap_result2error</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>r</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to the <olink targetptr="bdaly">LDAPMessage</olink> structure
|
|
representing the results returned by the <olink targetptr="bdauu">ldap_result</olink> or <olink targetptr="bdauy">ldap_search</olink> function.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>freeit</literal></para></entry>
|
|
<entry>
|
|
<para>Specifies whether or not the result should be freed after the error
|
|
code is extracted. The parameter can have the following possible values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><literal>0</literal> specifies that the result should not
|
|
be freed.</para></listitem>
|
|
<listitem><para>A non-zero value specifies that the result should be freed.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garxe"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para>If successful, sets the error code and other error information
|
|
in the <olink targetptr="bdakj">LDAP</olink> structure and returns the error
|
|
code.</para></listitem>
|
|
<listitem><para>If unsuccessful, returns <errorcode>LDAP_PARAM_ERROR</errorcode>.
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garxm"><title>Example</title>
|
|
<para>See <olink targetptr="bdauu">ldap_result</olink>.</para></sect3>
|
|
<sect3 id="garxi"><title>See Also</title>
|
|
<para><olink targetptr="bdaun">ldap_parse_result</olink>, <olink targetptr="bdasq">ldap_get_lderrno</olink>, <olink targetptr="bdarq">ldap_err2string
|
|
</olink>, <olink targetptr="bdauu">ldap_result</olink>, <olink targetptr="bdavf">
|
|
ldap_set_lderrno</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdauw"><title><function>ldap_sasl_bind</function></title>
|
|
<indexterm>
|
|
<primary>C SDK functions</primary>
|
|
<secondary><function>ldap_sasl_bind</function></secondary>
|
|
</indexterm><indexterm>
|
|
<primary><function>ldap_sasl_bind</function></primary>
|
|
</indexterm>
|
|
<para>The <function>ldap_sasl_bind</function> function authenticates your
|
|
client to an LDAP server using an Simple Authentication and Security Layer
|
|
(SASL) mechanism.</para>
|
|
<note><para>The LDAP server must support authentication through SASL. &cnDirectoryServer; supports
|
|
a server plug-in interface that you can use to add SASL support to the server.</para>
|
|
</note>
|
|
<sect3 id="garxd"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_sasl_bind( LDAP *ld, const char *dn,
|
|
const char *mechanism, const struct berval *cred,
|
|
LDAPControl **serverctrls, LDAPControl **clientctrls,
|
|
int *msgidp );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garwd"><title>Parameters</title>
|
|
<table frame="topbot" id="garwb"><title><function>ldap_sasl_bind</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>dn</literal></para></entry>
|
|
<entry>
|
|
<para>DN of the user who wants to authenticate. For anonymous authentication,
|
|
set this to <literal>NULL</literal>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>mechanism</literal></para></entry>
|
|
<entry>
|
|
<para>Name of the SASL mechanism that you want to use for authentication.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>cred</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to the <olink targetptr="bdakg">berval</olink> structure containing
|
|
the credentials that you want to use for authentication.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>serverctrls</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
|
|
representing LDAP server controls that apply to this operation. If you do
|
|
not want to pass any server controls, specify <literal>NULL</literal> for
|
|
this argument.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>clientctrls</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
|
|
representing LDAP client controls that apply to this operation. If you do
|
|
not want to pass any client controls, specify <literal>NULL</literal> for
|
|
this argument.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>msgidp</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an integer that will be set to the message ID of the LDAP
|
|
operation. To check the result of this operation, call <olink targetptr="bdauu">ldap_result
|
|
</olink> and <olink targetptr="bdauo">ldap_parse_sasl_bind_result</olink> functions.
|
|
</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garxp"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if the SASL bind request
|
|
was sent successfully.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if an invalid parameter
|
|
was passed to the function.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_NOT_SUPPORTED</errorcode> if controls are
|
|
included in your request—for example, as a session preference—and
|
|
your LDAP client does not specify that it is using the LDAP v3. Make sure
|
|
that you set the version of your LDAP client to version 3 before calling this
|
|
function.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_ENCODING_ERROR</errorcode> if an error occurred
|
|
when BER-encoding the request to send to the server.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
|
|
allocated.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_SERVER_DOWN</errorcode> if the LDAP server
|
|
did not receive the request or if the connection to the server was lost.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garwr"><title>Description</title>
|
|
<para>The <function>ldap_sasl_bind</function> function authenticates your
|
|
client to an LDAP server by using a specified SASL mechanism. <function>ldap_sasl_bind
|
|
</function> is an asynchronous function; it does not directly return results.
|
|
If you want the results to be returned directly by the function, call the
|
|
synchronous function <olink targetptr="bdaux">ldap_sasl_bind_s</olink>. In
|
|
order to get the results of the LDAP SASL bind operation, call the <olink targetptr="bdauu">ldap_result</olink>, the <olink targetptr="bdauo">ldap_parse_sasl_bind_result
|
|
</olink>, and the <olink targetptr="bdasq">ldap_get_lderrno</olink> functions.</para>
|
|
</sect3>
|
|
<sect3 id="garxr"><title>See Also</title>
|
|
<para><olink targetptr="bdauu">ldap_result</olink>, <olink targetptr="bdauo">ldap_parse_sasl_bind_result
|
|
</olink> , <olink targetptr="bdasq">ldap_get_lderrno</olink>, <olink targetptr="bdaux">ldap_sasl_bind_s</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaux"><title><function>ldap_sasl_bind_s</function></title>
|
|
<indexterm>
|
|
<primary>C SDK functions</primary>
|
|
<secondary><function>ldap_sasl_bind_s</function></secondary>
|
|
</indexterm><indexterm>
|
|
<primary><function>ldap_sasl_bind_s</function></primary>
|
|
</indexterm>
|
|
<para>The <function>ldap_sasl_bind_s</function> function authenticates your
|
|
client to an LDAP server synchronously using an SASL mechanism.</para>
|
|
<note><para>The LDAP server must support authentication through SASL. &cnDirectoryServer; supports
|
|
a server plug-in interface that you can use to add SASL support to the server.</para><?Pub
|
|
Caret1></note>
|
|
<sect3 id="garwj"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_sasl_bind_s( LDAP *ld, const char *dn,
|
|
const char *mechanism, const struct berval *cred,
|
|
LDAPControl **serverctrls, LDAPControl **clientctrls,
|
|
struct berval **servercredp );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garxn"><title>Parameters</title>
|
|
<table frame="topbot" id="garyb"><title><function>ldap_sasl_bind_s</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>dn</literal></para></entry>
|
|
<entry>
|
|
<para>DN of the user who wants to authenticate. For anonymous authentication,
|
|
set this to <literal>NULL</literal>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>mechanism</literal></para></entry>
|
|
<entry>
|
|
<para>Name of the SASL mechanism that you want to use for authentication.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>cred</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to the <olink targetptr="bdakg">berval</olink> structure containing
|
|
the credentials that you want to use for authentication.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>serverctrls</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
|
|
representing LDAP server controls that apply to this operation. If you do
|
|
not want to pass any server controls, specify <literal>NULL</literal> for
|
|
this argument.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>clientctrls</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
|
|
representing LDAP client controls that apply to this operation. If you do
|
|
not want to pass any client controls, specify <literal>NULL</literal> for
|
|
this argument.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>servercredp</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to a pointer to an <olink targetptr="bdakg">berval</olink> structure
|
|
containing any credentials returned by the server. When done, you can free
|
|
this by calling the <olink targetptr="bdany">ber_alloc</olink> function.</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garxf"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if the SASL bind request
|
|
was sent successfully.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if an invalid parameter
|
|
was passed to the function.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_NOT_SUPPORTED</errorcode> if controls are
|
|
included in your request (for example, as a session preference) and your LDAP
|
|
client does not specify that it is using the LDAPv3. Make sure that you set
|
|
the version of your LDAP client to version 3 before calling this function.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_ENCODING_ERROR</errorcode> if an error occurred
|
|
when BER-encoding the request to send to the server.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_DECODING_ERROR</errorcode> if an error occurred
|
|
when the LDAP API library was decoding the BER-encoded results received from
|
|
the server.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
|
|
allocated.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_SERVER_DOWN</errorcode> if the LDAP server
|
|
did not receive the request or if the connection to the server was lost.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_LOCAL_ERROR</errorcode> if an error occurred
|
|
when receiving the results from the server.</para></listitem>
|
|
</itemizedlist>
|
|
<note><para>&cnDirectoryServer; and other LDAP server products may send result
|
|
codes in addition to those described. For example, the server may have loaded
|
|
a plug-in that returns custom result codes. Check your LDAP server documentation
|
|
for other result codes.</para></note>
|
|
</sect3>
|
|
<sect3 id="garwc"><title>Description</title>
|
|
<para>The <function>ldap_sasl_bind_s</function> function authenticates your
|
|
client to an LDAP server by using a specified SASL mechanism. It is a synchronous
|
|
function, which directly returns the results of the operation. If you want
|
|
to perform other operations while waiting for the results of this operation,
|
|
call the asynchronous function <olink targetptr="bdauw">ldap_sasl_bind</olink>.
|
|
After authenticating a client through SASL, an LDAP server can return a set
|
|
of credentials in the results. The <literal>servercredp</literal> argument
|
|
points to this value.</para></sect3>
|
|
<sect3 id="garxz"><title>See Also</title>
|
|
<para><olink targetptr="bdauw">ldap_sasl_bind</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdauy"><title><function>ldap_search</function></title>
|
|
<indexterm>
|
|
<primary>C SDK functions</primary>
|
|
<secondary><function>ldap_search</function></secondary>
|
|
</indexterm><indexterm>
|
|
<primary><function>ldap_search</function></primary>
|
|
</indexterm>
|
|
<para>The <function>ldap_search</function> function searches the directory
|
|
asynchronously.</para>
|
|
<note><para>This is an older function that is included in the SDK for backward-compatibility.
|
|
If you are writing a new LDAP client, use <olink targetptr="bdauz">ldap_search_ext
|
|
</olink> instead.</para></note>
|
|
<sect3 id="garxc"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_search( LDAP *ld, const char *base, int scope,
|
|
const char* filter, char **attrs, int attrsonly );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garxl"><title>Parameters</title>
|
|
<table frame="topbot" id="garxq"><title><function>ldap_search</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>base</literal></para></entry>
|
|
<entry>
|
|
<para>DN of the entry that serves as the starting point for the search. For
|
|
example, setting base to <literal>dc=example,dc=com</literal> restricts the
|
|
search to entries at <literal>example.com</literal>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>scope</literal></para></entry>
|
|
<entry>
|
|
<para>Scope of the search, which can be one of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><literal>LDAP_SCOPE_BASE</literal> searches the entry specified
|
|
by base.</para></listitem>
|
|
<listitem><para><literal>LDAP_SCOPE_ONELEVEL</literal> searches all entries
|
|
one level beneath the entry specified by base.</para></listitem>
|
|
<listitem><para><literal>LDAP_SCOPE_SUBTREE</literal> searches the entry specified
|
|
by base and all entries at all levels beneath the entry specified by base.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>filter</literal></para></entry>
|
|
<entry>
|
|
<para>String representation of the filter to apply in the search. You can
|
|
specify simple filters with the following syntax:</para>
|
|
<para><literal>(</literal><replaceable>attributetype</replaceable><literal>=</literal> <replaceable>
|
|
attributevalue</replaceable><literal>)</literal></para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>attrs</literal></para></entry>
|
|
<entry>
|
|
<para>A <literal>NULL</literal> terminated array of attribute types to return
|
|
from entries that match filter. If you specify a <literal>NULL</literal>,
|
|
all attributes will be returned.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>attrsonly</literal></para></entry>
|
|
<entry>
|
|
<para>Specifies whether or not attribute values are returned along with the
|
|
attribute types. This parameter can have the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><literal>0</literal> specifies that both attribute types and
|
|
attribute values are returned.</para></listitem>
|
|
<listitem><para><literal>1</literal> specifies that only attribute types are
|
|
returned.</para></listitem>
|
|
</itemizedlist>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garwe"><title>Returns</title>
|
|
<para>Returns the message ID of the <function>ldap_search</function> operation.</para>
|
|
<note><para>To check the result of this operation, call <olink targetptr="bdauu">
|
|
ldap_result</olink> and <olink targetptr="bdauv">ldap_result2error</olink>.
|
|
See <olink targetptr="bdava">ldap_search_ext_s</olink> for a list of possible
|
|
result codes.</para></note>
|
|
</sect3>
|
|
<sect3 id="garww"><title>Description</title>
|
|
<para>Please use the newer version of this function, <olink targetptr="bdauz">ldap_search_ext
|
|
</olink> .</para></sect3>
|
|
<sect3 id="garwg"><title>Example</title>
|
|
<para><olink targetptr="ldap-search-example">Example 21–44</olink> searches
|
|
a directory.</para>
|
|
<example id="ldap-search-example"><title>Using <function>ldap_search</function></title>
|
|
<programlisting>#include "examples.h"
|
|
|
|
static void do_other_work();
|
|
unsigned long global_counter = 0;
|
|
|
|
int
|
|
main( int argc, char **argv )
|
|
{
|
|
LDAP *ld;
|
|
LDAPMessage *result, *e;
|
|
BerElement *ber;
|
|
char *a, *dn;
|
|
char **vals;
|
|
int i, rc, finished, msgid;
|
|
int num_entries = 0;
|
|
struct timeval zerotime;
|
|
|
|
zerotime.tv_sec = zerotime.tv_usec = 0L;
|
|
|
|
/* Get a handle to an LDAP connection. Use prldap_init() for IPv6. */
|
|
if ( (ld = ldap_init( MY_HOST, MY_PORT )) == NULL ) {
|
|
perror( "ldap_init" );
|
|
return( 1 );
|
|
}
|
|
/* authenticate to the directory as nobody */
|
|
if ( ldap_simple_bind_s( ld, NULL, NULL ) != LDAP_SUCCESS ) {
|
|
ldap_perror( ld, "ldap_simple_bind_s" );
|
|
return( 1 );
|
|
}
|
|
/* search for all entries with surname of Jensen */
|
|
if (( msgid = ldap_search( ld, MY_SEARCHBASE, LDAP_SCOPE_SUBTREE,
|
|
MY_FILTER, NULL, 0 )) == -1 ) {
|
|
ldap_perror( ld, "ldap_search" );
|
|
return( 1 );
|
|
}
|
|
|
|
/* Loop, polling for results until finished */
|
|
finished = 0;
|
|
while ( !finished ) {
|
|
/*
|
|
* Poll for results. We call ldap_result with the "all" parameter
|
|
* set to zero. This causes ldap_result() to return exactly one
|
|
* entry if at least one entry is available. This allows us to
|
|
* display the entries as they are received.
|
|
*/
|
|
result = NULL;
|
|
rc = ldap_result( ld, msgid, 0, &zerotime, &result );
|
|
switch ( rc ) {
|
|
case -1:
|
|
/* some error occurred */
|
|
ldap_perror( ld, "ldap_result" );
|
|
return( 1 );
|
|
case 0:
|
|
/* Timeout was exceeded. No entries are ready for retrieval. */
|
|
if ( result != NULL ) {
|
|
ldap_msgfree( result );
|
|
}
|
|
break;
|
|
default:
|
|
/*
|
|
* Either an entry is ready for retrieval, or all entries have
|
|
* been retrieved.
|
|
*/
|
|
if (( e = ldap_first_entry( ld, result )) == NULL ) {
|
|
/* All done */
|
|
finished = 1;
|
|
if ( result != NULL ) {
|
|
ldap_msgfree( result );
|
|
}
|
|
continue;
|
|
}
|
|
/* for each entry print out name + all attrs and values */
|
|
num_entries++;
|
|
if (( dn = ldap_get_dn( ld, e )) != NULL ) {
|
|
printf( "dn: %s\n", dn );
|
|
ldap_memfree( dn );
|
|
}
|
|
for ( a = ldap_first_attribute( ld, e, &ber );
|
|
a != NULL; a = ldap_next_attribute( ld, e, ber ) ) {
|
|
if (( vals = ldap_get_values( ld, e, a )) != NULL ) {
|
|
for ( i = 0; vals[ i ] != NULL; i++ ) {
|
|
printf( "%s: %s\n", a, vals[ i ] );
|
|
}
|
|
ldap_value_free( vals );
|
|
}
|
|
ldap_memfree( a );
|
|
}
|
|
if ( ber != NULL ) {
|
|
ldap_ber_free( ber, 0 );
|
|
}
|
|
printf( "\n" );
|
|
ldap_msgfree( result );
|
|
}
|
|
/* Do other work here while you are waiting... */
|
|
do_other_work();
|
|
}
|
|
|
|
/* All done. Print a summary. */
|
|
printf( "%d entries retrieved. I counted to %ld "
|
|
"while waiting.\n", num_entries, global_counter );
|
|
ldap_unbind( ld );
|
|
return( 0 );
|
|
}
|
|
|
|
/*
|
|
* Perform other work while polling for results. */
|
|
static void
|
|
do_other_work()
|
|
{
|
|
global_counter++;
|
|
}</programlisting>
|
|
</example>
|
|
</sect3>
|
|
<sect3 id="garxs"><title>See Also</title>
|
|
<para><olink targetptr="bdauz">ldap_search_ext</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdauz"><title><function>ldap_search_ext</function></title>
|
|
<indexterm>
|
|
<primary>C SDK functions</primary>
|
|
<secondary><function>ldap_search_ext</function></secondary>
|
|
</indexterm><indexterm>
|
|
<primary><function>ldap_search_ext</function></primary>
|
|
</indexterm>
|
|
<para>The <function>ldap_search_ext</function> function searches the directory
|
|
asynchronously.</para>
|
|
<note><para><function>ldap_search_ext</function> is a new version of the <olink targetptr="bdauy">ldap_search</olink> function. If you are writing a new LDAP
|
|
client, you should call <function>ldap_search_ext</function>.</para></note>
|
|
<sect3 id="garxb"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_search_ext( LDAP *ld, const char *base, int scope,
|
|
const char *filter, char **attrs, int attrsonly,
|
|
LDAPControl **serverctrls, LDAPControl **clientctrls,
|
|
struct timeval *timeoutp, int sizelimit, int *msgidp );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garwi"><title>Parameters</title>
|
|
<table frame="topbot" id="garwp"><title><function>ldap_search_ext</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>base</literal></para></entry>
|
|
<entry>
|
|
<para>DN of the entry that serves as the starting point for the search. For
|
|
example, setting base to <literal>dc=example,dc=com</literal> restricts the
|
|
search to entries at <literal>example.com</literal>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>scope</literal></para></entry>
|
|
<entry>
|
|
<para>Scope of the search, which can be one of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><literal>LDAP_SCOPE_BASE</literal> searches the entry specified
|
|
by base.</para></listitem>
|
|
<listitem><para><literal>LDAP_SCOPE_ONELEVEL</literal> searches all entries
|
|
one level beneath the entry specified by base.</para></listitem>
|
|
<listitem><para><literal>LDAP_SCOPE_SUBTREE</literal> searches the entry specified
|
|
by base and all entries at all levels beneath the entry specified by base.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>filter</literal></para></entry>
|
|
<entry>
|
|
<para>String representation of the filter to apply in the search. You can
|
|
specify simple filters with the following syntax:</para>
|
|
<para><literal>(</literal><replaceable>attributetype</replaceable><literal>=</literal> <replaceable>
|
|
attributevalue</replaceable><literal>)</literal></para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>attrs</literal></para></entry>
|
|
<entry>
|
|
<para>A <literal>NULL</literal> terminated array of attribute types to return
|
|
from entries that match filter. If you specify a <literal>NULL</literal>,
|
|
all attributes will be returned.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>attrsonly</literal></para></entry>
|
|
<entry>
|
|
<para>Specifies whether or not attribute values are returned along with the
|
|
attribute types. This parameter can have the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><literal>0</literal> specifies that both attribute types and
|
|
attribute values are returned.</para></listitem>
|
|
<listitem><para><literal>1</literal> specifies that only attribute types are
|
|
returned.</para></listitem>
|
|
</itemizedlist>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>serverctrls</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
|
|
representing LDAP server controls that apply to this operation. If you do
|
|
not want to pass any server controls, specify <literal>NULL</literal> for
|
|
this argument.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>clientctrls</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
|
|
representing LDAP client controls that apply to this operation. If you do
|
|
not want to pass any client controls, specify <literal>NULL</literal> for
|
|
this argument.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>timeoutp</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to a <literal>timeval</literal> structure specifying the maximum
|
|
time to wait for the results of the search. Pass <literal>NULL</literal> to
|
|
use the default time limit for the current connection. To specify an infinite
|
|
time limit, set the <literal>tv_sec</literal> and <literal>tv_usec</literal> fields
|
|
in the <literal>timeval</literal> structure to 0.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>sizelimit</literal></para></entry>
|
|
<entry>
|
|
<para>Maximum number of results to return in the search. Pass <literal>-1</literal> to
|
|
use the default size limit for the current connection.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>msgidp</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an integer that will be set to the message ID of the LDAP
|
|
operation.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garyc"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if the SASL bind request
|
|
was sent successfully.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if an invalid parameter
|
|
was passed to the function.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_NOT_SUPPORTED</errorcode> if controls are
|
|
included in your request—for example, as a session preference—and
|
|
your LDAP client does not specify that it is using the LDAP v3. Make sure
|
|
that you set the version of your LDAP client to version 3 before calling this
|
|
function.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_ENCODING_ERROR</errorcode> if an error occurred
|
|
when BER-encoding the request to send to the server.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
|
|
allocated.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_SERVER_DOWN</errorcode> if the LDAP server
|
|
did not receive the request or if the connection to the server was lost.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garwx"><title>Description</title>
|
|
<para>The <function>ldap_search_ext</function> function searches the directory
|
|
for matching entries. <function>ldap_search_ext</function> is an asynchronous
|
|
function; it does not directly return results. If you want the results to
|
|
be returned directly by the function, call the synchronous function <olink targetptr="bdava">ldap_search_ext_s</olink> . You can also use this function
|
|
to pass LDAP server controls to the server if you want the server to sort
|
|
the results or if you want to request a persistent search. (See <olink targetptr="bdare">ldap_create_sort_control</olink> and <olink targetptr="bdara">ldap_create_persistentsearch_control
|
|
</olink> for more information.) In order to get the results of the <function>ldap_search_ext
|
|
</function> operation, you need to call the <olink targetptr="bdauu">ldap_result</olink> and
|
|
the <olink targetptr="bdaun">ldap_parse_result</olink> functions.</para></sect3>
|
|
<sect3 id="garya"><title>See Also</title>
|
|
<para><olink targetptr="bdava">ldap_search_ext_s</olink>, <olink targetptr="bdauu">ldap_result</olink>, <olink targetptr="bdaun">ldap_parse_result
|
|
</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdava"><title><function>ldap_search_ext_s</function></title>
|
|
<indexterm>
|
|
<primary>C SDK functions</primary>
|
|
<secondary><function>ldap_search_ext_s</function></secondary>
|
|
</indexterm><indexterm>
|
|
<primary><function>ldap_search_ext_s</function></primary>
|
|
</indexterm>
|
|
<para>The <function>ldap_search_ext_s</function> function searches the directory
|
|
synchronously.</para>
|
|
<note><para><function>ldap_search_ext_s</function> is a new version of the <olink targetptr="bdavb">ldap_search_s</olink> function. If you are writing a new
|
|
LDAP client, you should call <function>ldap_search_ext_s</function>.</para>
|
|
</note>
|
|
<sect3 id="garxw"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_search_ext_s( LDAP *ld, const char *base, int scope,
|
|
const char *filter, char **attrs, int attrsonly,
|
|
LDAPControl **serverctrls, LDAPControl **clientctrls,
|
|
struct timeval *timeoutp, int sizelimit, LDAPMessage **res );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garyx"><title>Parameters</title>
|
|
<table frame="topbot" id="garyl"><title><function>ldap_search_ext_s</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>base</literal></para></entry>
|
|
<entry>
|
|
<para>DN of the entry that serves as the starting point for the search. For
|
|
example, setting base to <literal>dc=example,dc=com</literal> restricts the
|
|
search to entries at <literal>example.com</literal>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>scope</literal></para></entry>
|
|
<entry>
|
|
<para>Scope of the search, which can be one of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><literal>LDAP_SCOPE_BASE</literal> searches the entry specified
|
|
by base.</para></listitem>
|
|
<listitem><para><literal>LDAP_SCOPE_ONELEVEL</literal> searches all entries
|
|
one level beneath the entry specified by base.</para></listitem>
|
|
<listitem><para><literal>LDAP_SCOPE_SUBTREE</literal> searches all entries
|
|
at all levels beneath the entry specified by base.</para></listitem>
|
|
</itemizedlist>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>filter</literal></para></entry>
|
|
<entry>
|
|
<para>String representation of the filter to apply in the search. You can
|
|
specify simple filters with the following syntax:</para>
|
|
<para><literal>(</literal><replaceable>attributetype</replaceable><literal>=</literal> <replaceable>
|
|
attributevalue</replaceable><literal>)</literal></para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>attrs</literal></para></entry>
|
|
<entry>
|
|
<para>A <literal>NULL</literal> terminated array of attribute types to return
|
|
from entries that match filter. If you specify a <literal>NULL</literal>,
|
|
all attributes will be returned.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>attrsonly</literal></para></entry>
|
|
<entry>
|
|
<para>Specifies whether or not attribute values are returned along with the
|
|
attribute types. This parameter can have the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><literal>0</literal> specifies that both attribute types and
|
|
attribute values are returned.</para></listitem>
|
|
<listitem><para><literal>1</literal> specifies that only attribute types are
|
|
returned.</para></listitem>
|
|
</itemizedlist>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>serverctrls</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
|
|
representing LDAP server controls that apply to this operation. If you do
|
|
not want to pass any server controls, specify <literal>NULL</literal> for
|
|
this argument.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>clientctrls</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
|
|
representing LDAP client controls that apply to this operation. If you do
|
|
not want to pass any client controls, specify <literal>NULL</literal> for
|
|
this argument.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>timeoutp</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to a <literal>timeval</literal> structure specifying the maximum
|
|
time to wait for the results of the search.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>sizelimit</literal></para></entry>
|
|
<entry>
|
|
<para>Maximum number of results to return in the search.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>res</literal></para></entry>
|
|
<entry>
|
|
<para>Results of the search (when the call is completed).</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garzm"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if the SASL bind request
|
|
was sent successfully.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if an invalid parameter
|
|
was passed to the function.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_NOT_SUPPORTED</errorcode> if controls are
|
|
included in your request—for example, as a session preference—and
|
|
your LDAP client does not specify that it is using the LDAP v3. Make sure
|
|
that you set the version of your LDAP client to version 3 before calling this
|
|
function.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_FILTER_ERROR</errorcode> if an error occurred
|
|
when parsing and BER-encoding the search filter specified by the filter argument.
|
|
</para></listitem>
|
|
<listitem><para><errorcode>LDAP_TIMEOUT</errorcode> if the search exceeded
|
|
the time specified by the <parameter>timeoutp</parameter> argument.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_ENCODING_ERROR</errorcode> if an error occurred
|
|
when BER-encoding the request to send to the server.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_DECODING_ERROR</errorcode> if an error occurred
|
|
when the LDAP API library was decoding the BER-encoded results received from
|
|
the server.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
|
|
allocated.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_SERVER_DOWN</errorcode> if the LDAP server
|
|
did not receive the request or if the connection to the server was lost.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_LOCAL_ERROR</errorcode> if an error occurred
|
|
when receiving the results from the server.</para></listitem>
|
|
</itemizedlist>
|
|
<note><para>&cnDirectoryServer; and other LDAP server products may send result
|
|
codes in addition to those described. For example, the server may have loaded
|
|
a plug-in that returns custom result codes. Check your LDAP server documentation
|
|
for other result codes.</para></note>
|
|
</sect3>
|
|
<sect3 id="garyz"><title>Description</title>
|
|
<para>The <function>ldap_search_ext_s</function> searches the directory for
|
|
matching entries. The function <function>ldap_search_ext_s</function> is synchronous;
|
|
it directly returns the results of the operation. If you want to perform other
|
|
operations while waiting for the results of this operation, call the asynchronous
|
|
function <olink targetptr="bdauz">ldap_search_ext</olink>. You can also use <function>
|
|
ldap_search_ext_s</function> to pass LDAP server controls to the server if
|
|
you want the server to sort the results or if you want to request a persistent
|
|
search. (See <olink targetptr="bdare">ldap_create_sort_control</olink> and <olink targetptr="bdara">ldap_create_persistentsearch_control</olink> for more information.)
|
|
</para></sect3>
|
|
<sect3 id="garze"><title>See Also</title>
|
|
<para><olink targetptr="bdauz">ldap_search_ext</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdavb"><title><function>ldap_search_s</function></title>
|
|
<indexterm>
|
|
<primary>C SDK functions</primary>
|
|
<secondary><function>ldap_search_s</function></secondary>
|
|
</indexterm><indexterm>
|
|
<primary><function>ldap_search_s</function></primary>
|
|
</indexterm>
|
|
<para>The <function>ldap_search_s</function> function searches the directory
|
|
synchronously.</para>
|
|
<note><para>This is an older function that is included in the SDK for backward-compatibility.
|
|
If you are writing a new LDAP client, use <olink targetptr="bdava">ldap_search_ext_s
|
|
</olink> instead.</para></note>
|
|
<sect3 id="garyr"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_search_s( LDAP *ld, const char *base, int scope,
|
|
const char* filter, char **attrs, int attrsonly,
|
|
LDAPMessage **res );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garzs"><title>Parameters</title>
|
|
<para>This function has the parameters listed in <olink targetptr="bdavb">ldap_search_s
|
|
</olink> .</para>
|
|
<table frame="topbot" id="garzh"><title><function>ldap_search_s</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>base</literal></para></entry>
|
|
<entry>
|
|
<para>DN of the entry that serves as the starting point for the search. For
|
|
example, setting base to <literal>dc=example,dc=com</literal> restricts the
|
|
search to entries at <literal>example.com</literal>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>scope</literal></para></entry>
|
|
<entry>
|
|
<para>Scope of the search, which can be one of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><literal>LDAP_SCOPE_BASE</literal> searches the entry specified
|
|
by base.</para></listitem>
|
|
<listitem><para><literal>LDAP_SCOPE_ONELEVEL</literal> searches all entries
|
|
one level beneath the entry specified by base.</para></listitem>
|
|
<listitem><para><literal>LDAP_SCOPE_SUBTREE</literal> searches all entries
|
|
at all levels beneath the entry specified by base.</para></listitem>
|
|
</itemizedlist>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>filter</literal></para></entry>
|
|
<entry>
|
|
<para>String representation of the filter to apply in the search. You can
|
|
specify simple filters with the following syntax:</para>
|
|
<programlisting>(attributetype=attributevalue)</programlisting>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>attrs</literal></para></entry>
|
|
<entry>
|
|
<para>A <literal>NULL</literal> terminated array of attribute types to return
|
|
from entries that match filter. If you specify a <literal>NULL</literal>,
|
|
all attributes will be returned.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>attrsonly</literal></para></entry>
|
|
<entry>
|
|
<para>Specifies whether or not attribute values are returned along with the
|
|
attribute types. This parameter can have the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><literal>0</literal> specifies that both attribute types and
|
|
attribute values are returned.</para></listitem>
|
|
<listitem><para><literal>1</literal> specifies that only attribute types are
|
|
returned.</para></listitem>
|
|
</itemizedlist>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>res</literal></para></entry>
|
|
<entry>
|
|
<para>Results of the search (when the call is completed).</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garzp"><title>Returns</title>
|
|
<para>For a list of possible result codes for an LDAP search operation, see <olink targetptr="bdava">ldap_search_ext_s</olink>.</para></sect3>
|
|
<sect3 id="garyt"><title>Description</title>
|
|
<para>Use the newer version of this function, <olink targetptr="bdava">ldap_search_ext_s
|
|
</olink> .</para></sect3>
|
|
<sect3 id="garyf"><title>Example</title>
|
|
<para><olink targetptr="ldap-search-s-example">Example 21–45</olink> searches
|
|
the directory for all people whose surname (last name) is <literal>Jensen</literal>.
|
|
</para>
|
|
<example id="ldap-search-s-example"><title>Using <function>ldap_search_s</function></title>
|
|
<programlisting>#include "examples.h"
|
|
|
|
int main( int argc, char **argv )
|
|
{
|
|
LDAP *ld;
|
|
LDAPMessage *result, *e;
|
|
BerElement *ber;
|
|
char *a, *dn;
|
|
char **vals;
|
|
int i;
|
|
/* Get a handle to an LDAP connection. Use prldap_init() for IPv6. */
|
|
if ( (ld = ldap_init( MY_HOST, MY_PORT )) == NULL ) {
|
|
perror( "ldap_init" );
|
|
return( 1 );
|
|
}
|
|
/* authenticate to the directory as nobody */
|
|
if ( ldap_simple_bind_s( ld, NULL, NULL ) != LDAP_SUCCESS ) {
|
|
ldap_perror( ld, "ldap_simple_bind_s" );
|
|
return( 1 );
|
|
}
|
|
/* search for all entries with surname of Jensen */
|
|
if ( ldap_search_s( ld, MY_SEARCHBASE, LDAP_SCOPE_SUBTREE,
|
|
MY_FILTER, NULL, 0, &result ) != LDAP_SUCCESS ) {
|
|
ldap_perror( ld, "ldap_search_s" );
|
|
return( 1 );
|
|
}
|
|
/* for each entry print out name + all attrs and values */
|
|
for ( e = ldap_first_entry( ld, result ); e != NULL;
|
|
e = ldap_next_entry( ld, e ) ) {
|
|
if ( (dn = ldap_get_dn( ld, e )) != NULL ) {
|
|
printf( "dn: %s\n", dn );
|
|
ldap_memfree( dn );
|
|
}
|
|
for ( a = ldap_first_attribute( ld, e, &ber );
|
|
a != NULL; a = ldap_next_attribute( ld, e, ber ) ) {
|
|
if ((vals = ldap_get_values( ld, e, a)) != NULL ) {
|
|
for ( i = 0; vals[i] != NULL; i++ ) {
|
|
printf( "%s: %s\n", a, vals[i] );
|
|
}
|
|
ldap_value_free( vals );
|
|
}
|
|
ldap_memfree( a );
|
|
}
|
|
if ( ber != NULL ) {
|
|
ldap_ber_free( ber, 0 );
|
|
}
|
|
printf( "\n" );
|
|
}
|
|
ldap_msgfree( result );
|
|
ldap_unbind( ld );
|
|
return( 0 );
|
|
}</programlisting>
|
|
</example>
|
|
</sect3>
|
|
<sect3 id="garzt"><title>See Also</title>
|
|
<para><olink targetptr="bdava">ldap_search_ext_s</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdavc"><title><function>ldap_search_st</function></title>
|
|
<indexterm>
|
|
<primary>C SDK functions</primary>
|
|
<secondary><function>ldap_search_st</function></secondary>
|
|
</indexterm><indexterm>
|
|
<primary><function>ldap_search_st</function></primary>
|
|
</indexterm>
|
|
<para>The <function>ldap_search_st</function> function searches the directory
|
|
synchronously within a specified time limit.</para>
|
|
<note><para>This is an older function that is included in the SDK for backward-compatibility.
|
|
If you are writing a new LDAP client, use <olink targetptr="bdava">ldap_search_ext_s
|
|
</olink> instead.</para></note>
|
|
<sect3 id="garzx"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_search_st( LDAP *ld, const char *base, int scope,
|
|
const char* filter, char **attrs, int attrsonly,
|
|
struct timeval *timeout, LDAPMessage **res );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garzy"><title>Parameters</title>
|
|
<table frame="topbot" id="garyv"><title><function>ldap_search_st</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>base</literal></para></entry>
|
|
<entry>
|
|
<para>DN of the entry that serves as the starting point for the search. For
|
|
example, setting base to <literal>dc=example,dc=com</literal> restricts the
|
|
search to entries at <literal>example.com</literal>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>scope</literal></para></entry>
|
|
<entry>
|
|
<para>Scope of the search, which can be one of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><literal>LDAP_SCOPE_BASE</literal> searches the entry specified
|
|
by base.</para></listitem>
|
|
<listitem><para><literal>LDAP_SCOPE_ONELEVEL</literal> searches all entries
|
|
one level beneath the entry specified by base.</para></listitem>
|
|
<listitem><para><literal>LDAP_SCOPE_SUBTREE</literal> searches all entries
|
|
at all levels beneath the entry specified by base.</para></listitem>
|
|
</itemizedlist>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>filter</literal></para></entry>
|
|
<entry>
|
|
<para>String representation of the filter to apply in the search. You can
|
|
specify simple filters with the following syntax:</para>
|
|
<programlisting>(attributetype=attributevalue)</programlisting>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>attrs</literal></para></entry>
|
|
<entry>
|
|
<para>A <literal>NULL</literal> terminated array of attribute types to return
|
|
from entries that match filter. If you specify a <literal>NULL</literal>,
|
|
all attributes will be returned.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>attrsonly</literal></para></entry>
|
|
<entry>
|
|
<para>Specifies whether or not attribute values are returned along with the
|
|
attribute types. This parameter can have the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para>0 specifies that both attribute types and attribute values
|
|
are returned.</para></listitem>
|
|
<listitem><para>1 specifies that only attribute types are returned.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>timeout</literal></para></entry>
|
|
<entry>
|
|
<para>Maximum time to wait for the results of the search.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>res</literal></para></entry>
|
|
<entry>
|
|
<para>Results of the search (when the call is completed).</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garzi"><title>Returns</title>
|
|
<para>For a list of possible result codes for an LDAP search operation, see <olink targetptr="bdava">ldap_search_ext_s</olink>.</para></sect3>
|
|
<sect3 id="garzc"><title>Description</title>
|
|
<para>Please use the newer version of this function, <olink targetptr="bdava">ldap_search_ext_s
|
|
</olink> .</para></sect3>
|
|
<sect3 id="gasae"><title>See Also</title>
|
|
<para><olink targetptr="bdava">ldap_search_ext_s</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdavd"><title><function>ldap_set_filter_additions</function></title>
|
|
<indexterm>
|
|
<primary>C SDK functions</primary>
|
|
<secondary><function>ldap_set_filter_additions</function></secondary>
|
|
</indexterm><indexterm>
|
|
<primary><function>ldap_set_filter_additions</function></primary>
|
|
</indexterm>
|
|
<para>The <function>ldap_set_filter_additions</function> function sets a prefix
|
|
to be prepended and a suffix to be appended to all filters returned by the
|
|
<function>ldap_getfirstfilter</function> and <function>ldap_getnextfilter</function> function
|
|
calls.</para>
|
|
<sect3 id="garzv"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_set_filter_additions( LDAPFiltDesc *lfdp, char *prefix,
|
|
char *suffix );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garym"><title>Parameters</title>
|
|
<table frame="topbot" id="garyp"><title><function>ldap_set_filter_additions</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>lfdp</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdalf">LDAPFiltDesc</olink> structure.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>prefix</literal></para></entry>
|
|
<entry>
|
|
<para>Prefix to prepend to all filters. If <literal>NULL</literal>, no prefix
|
|
is prepended.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>suffix</literal></para></entry>
|
|
<entry>
|
|
<para>Suffix to append to all filters. If <literal>NULL</literal>, no suffix
|
|
is appended.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garzq"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para>If unsuccessful, returns an LDAP error code.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garye"><title>Example</title>
|
|
<para><olink targetptr="ldap-set-filter-additions-example">Example 21–46</olink> loads
|
|
the filter configuration file named <literal>myfilters.conf</literal> into
|
|
memory and adds the prefix <literal>"(&(objectClass=person)"</literal> and
|
|
the suffix <literal>")"</literal> to each filter retrieved.</para>
|
|
<example id="ldap-set-filter-additions-example"><title>Using <function>ldap_set_filter_additions
|
|
</function></title>
|
|
<programlisting>#include <ldap.h>
|
|
...
|
|
LDAPFiltDesc *lfdp;
|
|
char *filter_file = "myfilters.conf";
|
|
char *prefix = "(&(objectClass=person)";
|
|
char *suffix = ")";
|
|
int rc;
|
|
...
|
|
lfdp = ldap_init_getfilter( filter_file );
|
|
rc = ldap_set_filter_additions( ldfp, prefix, suffix );
|
|
if ( rc != LDAP_SUCCESS ) {
|
|
printf( "Error setting filter prefix and suffix\n");
|
|
return( rc );
|
|
}
|
|
...</programlisting>
|
|
</example>
|
|
</sect3>
|
|
<sect3 id="garyk"><title>See Also</title>
|
|
<para><olink targetptr="bdasn">ldap_getfirstfilter</olink>, <olink targetptr="bdasr">ldap_getnextfilter</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdave"><title><function>ldap_setfilteraffixes</function></title>
|
|
<indexterm>
|
|
<primary>C SDK functions</primary>
|
|
<secondary><function>ldap_setfilteraffixes</function></secondary>
|
|
</indexterm><indexterm>
|
|
<primary><function>ldap_setfilteraffixes</function></primary>
|
|
</indexterm>
|
|
<note><para>This function is deprecated and should not be used. It is included
|
|
in <literal>ldap-deprecated.h</literal> for backward-compatibility. Use <olink targetptr="bdavd">ldap_set_filter_additions</olink> instead.</para></note>
|
|
<sect3 id="garzd"><title>See Also</title>
|
|
<para><olink targetptr="bdavd">ldap_set_filter_additions</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdavf"><title><function>ldap_set_lderrno</function></title>
|
|
<indexterm>
|
|
<primary>C SDK functions</primary>
|
|
<secondary><function>ldap_set_lderrno</function></secondary>
|
|
</indexterm><indexterm>
|
|
<primary><function>ldap_set_lderrno</function></primary>
|
|
</indexterm>
|
|
<para>The <function>ldap_set_lderrno</function> function sets an error code
|
|
and information about an error in an <olink targetptr="bdakj">LDAP</olink> structure.
|
|
</para>
|
|
<sect3 id="garzu"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_set_lderrno( LDAP *ld, int e, char *m, char *s );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garzk"><title>Parameters</title>
|
|
<table frame="topbot" id="garyn"><title><function>ldap_set_lderrno</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>e</literal></para></entry>
|
|
<entry>
|
|
<para>The error code that you want to set.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>m</literal></para></entry>
|
|
<entry>
|
|
<para>In the event that an entry for a specified DN cannot be found, set this
|
|
parameter to the portion of the DN that identifies an existing entry.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>s</literal></para></entry>
|
|
<entry>
|
|
<para>The text of the error message that you want associated with this error
|
|
code.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garzf"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para>If unsuccessful, returns an LDAP error code.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garyj"><title>Description</title>
|
|
<para>The <function>ldap_set_lderrno</function> function sets an error code
|
|
and information about an error in an <olink targetptr="bdakj">LDAP</olink> structure.
|
|
You can call this function to set error information that will be retrieved
|
|
by subsequent <olink targetptr="bdasq">ldap_get_lderrno</olink> function calls.</para>
|
|
</sect3>
|
|
<sect3 id="garzw"><title>Example</title>
|
|
<para><olink targetptr="ldap-set-lderrno-example">Example 21–47</olink> attempts
|
|
to perform an operation. If the operation fails, the <errorcode>LDAP_PARAM_ERROR</errorcode> error
|
|
code is placed in the <olink targetptr="bdakj">LDAP</olink> structure.</para>
|
|
<example id="ldap-set-lderrno-example"><title>Using <function>ldap_set_lderrno</function></title>
|
|
<programlisting>#include <ldap.h>
|
|
int rc;
|
|
char *errmsg = "Invalid parameter";
|
|
...
|
|
if ( ldap_my_function() != LDAP_SUCCESS ) {
|
|
rc = ldap_set_lderrno( ld, LDAP_PARAM_ERROR, NULL, errmsg );
|
|
if ( rc != LDAP_SUCCESS ) {
|
|
printf( "Error: %d\nError code could not be set.\n", rc );
|
|
}
|
|
return( rc );
|
|
}
|
|
...</programlisting>
|
|
</example>
|
|
</sect3>
|
|
<sect3 id="garys"><title>See Also</title>
|
|
<para><olink targetptr="bdarq">ldap_err2string</olink>, <olink targetptr="bdaur">
|
|
ldap_perror</olink>, <olink targetptr="bdauv">ldap_result2error</olink></para>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="bdavg"><title><function>ldap_set_option</function></title>
|
|
<indexterm>
|
|
<primary>C SDK functions</primary>
|
|
<secondary><function>ldap_set_option</function></secondary>
|
|
</indexterm><indexterm>
|
|
<primary><function>ldap_set_option</function></primary>
|
|
</indexterm>
|
|
<para>The function <function>ldap_set_option</function> sets session preferences
|
|
in the <olink targetptr="bdakj">LDAP</olink> structure.</para>
|
|
<sect3 id="garyy"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_set_option( LDAP *ld, int option, const void *optdata );</programlisting>
|
|
</sect3>
|
|
<sect3 id="garyw"><title>Parameters</title>
|
|
<table frame="topbot" id="garyh"><title><function>ldap_set_option</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server. If NULL, you are setting
|
|
the default options that will apply to any new LDAP connection handles that
|
|
are subsequently created.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>option</literal></para></entry>
|
|
<entry>
|
|
<para>Option that you want to set. See <olink targetptr="ldap-set-option-options">
|
|
Table 21–182</olink> for available options of this parameter.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>optdata</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to the value of the option that you want to set. Available data
|
|
types are also listed in <olink targetptr="ldap-set-option-options">Table
|
|
21–182</olink>.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
<para>The <literal>option</literal> parameter can have one of the values listed
|
|
in <olink targetptr="ldap-set-option-options">Table 21–182</olink>.</para>
|
|
<table frame="topbot" id="ldap-set-option-options"><title>Options for <function>ldap_set_option
|
|
</function></title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Option</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>LDAP_OPT_API_FEATURE_INFO</literal></para></entry>
|
|
<entry>
|
|
<para>Retrieves information about the revision of a supported LDAP feature.
|
|
This option is READ-ONLY and cannot be set.</para>
|
|
<para>The data type for the <literal>optdata</literal> parameter is <literal>(LDAPAPIFeatureInfo
|
|
*)</literal>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>LDAP_OPT_API_INFO</literal></para></entry>
|
|
<entry>
|
|
<para>Retrieves information about the API implementation at execution time
|
|
(API version, protocol version, the names of supported API extensions with
|
|
their vendor name version, etc.). For details on the structure returned, refer
|
|
to the <literal>ldap.h</literal> header file. This option is READ-ONLY and
|
|
cannot be set.</para>
|
|
<para>The data type for the <literal>optdata</literal> parameter is <literal>(LDAPAPIInfo
|
|
*)</literal>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>LDAP_OPT_CLIENT_CONTROLS</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
|
|
representing the LDAP v3 client controls you want sent with every request
|
|
by default.</para>
|
|
<para>The data type for the <literal>optdata</literal> parameter is <literal>(LDAPControl
|
|
***)</literal>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>LDAP_OPT_DESC</literal></para></entry>
|
|
<entry>
|
|
<para>Socket descriptor underlying the main LDAP connection. The <literal>LBER_SOCKET
|
|
</literal> data type depends on the platform that you are using:</para>
|
|
<itemizedlist>
|
|
<listitem><para><literal>int</literal> in UNIX.</para></listitem>
|
|
<listitem><para><literal>SOCKET</literal> in Windows.</para><para>The data
|
|
type for the <literal>optdata</literal> parameter is <literal>(LBER_SOCKET
|
|
*)</literal>.</para></listitem>
|
|
</itemizedlist>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>LDAP_OPT_DEREF</literal></para></entry>
|
|
<entry>
|
|
<para>Determines how aliases work during a search. <literal>optdata</literal> can
|
|
be one of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><literal>LDAP_DEREF_NEVER</literal> specifies that aliases
|
|
are never dereferenced.</para></listitem>
|
|
<listitem><para><literal>LDAP_DEREF_SEARCHING</literal> specifies that aliases
|
|
are dereferenced when searching under the base object (but not when finding
|
|
the base object).</para></listitem>
|
|
<listitem><para><literal>LDAP_DEREF_FINDING</literal> specifies that aliases
|
|
are dereferenced when finding the base object (but not when searching under
|
|
the base object).</para></listitem>
|
|
<listitem><para><literal>LDAP_DEREF_ALWAYS</literal> specifies that aliases
|
|
are always dereferenced when finding and searching under the base object.</para>
|
|
<para>The data type for the <literal>optdata</literal> parameter is <literal>(int
|
|
*)</literal>.</para></listitem>
|
|
</itemizedlist>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>LDAP_OPT_DNS_FN_PTRS</literal></para></entry>
|
|
<entry>
|
|
<para><emphasis role="strong">DEPRECATED OPTION:</emphasis> Lets you use alternate
|
|
DNS functions for getting the host entry of the LDAP server.</para>
|
|
<para>The data type for the <literal>optdata</literal> parameter is <literal>(struct
|
|
ldap_dns_fns *)</literal>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>LDAP_OPT_ERROR_NUMBER</literal></para></entry>
|
|
<entry>
|
|
<para>Retrieves the result code for the most recent LDAP error that occurred
|
|
in this session.</para>
|
|
<para>The data type for the <literal>optdata</literal> parameter is <literal>(int
|
|
*)</literal>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>LDAP_OPT_ERROR_STRING</literal></para></entry>
|
|
<entry>
|
|
<para>Retrieves the error message returned with the result code for the most
|
|
recent LDAP error that occurred in this session.</para>
|
|
<para>The data type for the <literal>optdata</literal> parameter is <literal>(char
|
|
**)</literal>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>LDAP_OPT_EXTRA_THREAD_FN_PTRS</literal></para></entry>
|
|
<entry>
|
|
<para>Lets you specify the locking and semaphore functions that you want called
|
|
when getting results from the server.</para>
|
|
<para>The data type for the <literal>optdata</literal> parameter is <literal>(struct
|
|
ldap_extra_thread_fns *)</literal>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>LDAP_OPT_HOST_NAME</literal></para></entry>
|
|
<entry>
|
|
<para>Sets the host name (or list of hosts) for the primary LDAP server.</para>
|
|
<para>The data type for the <literal>optdata</literal> parameter is <literal>(char
|
|
**)</literal>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>LDAP_OPT_IO_FN_PTRS</literal></para></entry>
|
|
<entry>
|
|
<para><emphasis role="strong">DEPRECATED OPTION:</emphasis> Lets you use alternate
|
|
communication stacks.</para>
|
|
<para>The data type for the <literal>optdata</literal> parameter is <literal>(struct
|
|
ldap_io_fns *)</literal>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>LDAP_OPT_MATCHED_DN</literal></para></entry>
|
|
<entry>
|
|
<para>Gets the matched DN value returned with the most recent LDAP error that
|
|
occurred for this session.</para>
|
|
<para>The data type for the <literal>optdata</literal> parameter is <literal>(char
|
|
**)</literal></para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>LDAP_OPT_MEMALLOC_FN_PTRS</literal></para></entry>
|
|
<entry>
|
|
<para>Gets a pointer to the callback structure which you previously set.</para>
|
|
<para>The data type for the <literal>optdata</literal> parameter is <literal>(struct
|
|
ldap_memalloc_fnsldap_io_fns *)</literal>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>LDAP_OPT_PROTOCOL_VERSION</literal></para></entry>
|
|
<entry>
|
|
<para>Version of the protocol supported by your client. You can specify either <literal>
|
|
LDAP_VERSION2</literal> or <literal>LDAP_VERSION3</literal>. If no version
|
|
is set, the default is <literal>LDAP_VERSION2</literal>. In order to use LDAP
|
|
v3 features, you need to set the protocol version to <literal>LDAP_VERSION3</literal>.
|
|
</para>
|
|
<para>The data type for the <literal>optdata</literal> parameter is <literal>(int
|
|
*)</literal>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>LDAP_OPT_REBIND_ARG</literal></para></entry>
|
|
<entry>
|
|
<para>Lets you set the last argument passed to the routine specified by <literal>
|
|
LDAP_OPT_REBIND_FN</literal>. You can also set this option by calling the <olink targetptr="bdavh">ldap_set_rebind_proc</olink> function.</para>
|
|
<para>The data type for the <literal>optdata</literal> parameter is <literal>(void
|
|
*)</literal>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>LDAP_OPT_REBIND_FN</literal></para></entry>
|
|
<entry>
|
|
<para>Lets you set the routine to be called when you need to authenticate
|
|
a connection with another LDAP server (for example, during the course of following
|
|
a referral). You can also set this option by calling the <olink targetptr="bdavh">
|
|
ldap_set_rebind_proc</olink> function.</para>
|
|
<para>The data type for the <literal>optdata</literal> parameter is <literal>(LDAP_REBINDPROC_CALLBACK
|
|
*)</literal>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>LDAP_OPT_RECONNECT</literal></para></entry>
|
|
<entry>
|
|
<para>If the connection to the server is lost, determines whether or not the
|
|
same connection handle should be used to reconnect to the server. By default,
|
|
this option is off. To handle failover use following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><literal>LDAP_OPT_ON</literal> specifies that the same connection
|
|
handle can be used to reconnect to the server.</para></listitem>
|
|
<listitem><para><literal>LDAP_OPT_OFF</literal> specifies that you want to
|
|
create a new connection handle to connect to the server.</para><para>The data
|
|
type for the <literal>optdata</literal> parameter is <literal>(int *)</literal>.
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>LDAP_OPT_REFERRALS</literal></para></entry>
|
|
<entry>
|
|
<para>Determines whether or not the client should follow referrals. By default,
|
|
the client follows referrals. <literal>optdata</literal> can be one of the
|
|
following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><literal>LDAP_OPT_ON</literal> specifies that the server should
|
|
follow referrals.</para></listitem>
|
|
<listitem><para><literal>LDAP_OPT_OFF</literal> specifies that the server
|
|
should not follow referrals.</para><para>The data type for the <literal>optdata</literal> parameter
|
|
is <literal>(int *)</literal>.</para></listitem>
|
|
</itemizedlist>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>LDAP_OPT_REFERRAL_HOP_LIMIT</literal></para></entry>
|
|
<entry>
|
|
<para>Maximum number of referrals the client should follow in a sequence.
|
|
In other words, the client can only be referred this number of times before
|
|
it gives up. By default, the maximum number of referrals that the client can
|
|
follow in a sequence is 5 for the initial connection. This limit does not
|
|
apply to individual requests that generate multiple referrals in parallel.</para>
|
|
<para>The data type for the <literal>optdata</literal> parameter is <literal>(int
|
|
*)</literal>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>LDAP_OPT_RESTART</literal></para></entry>
|
|
<entry>
|
|
<para>Determines whether or not LDAP I/O operations should be restarted automatically
|
|
if they are prematurely aborted. <literal>optdata</literal> can be one of
|
|
the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><literal>LDAP_OPT_ON</literal> specifies that I/O operations
|
|
should be restarted automatically.</para></listitem>
|
|
<listitem><para><literal>LDAP_OPT_OFF</literal> specifies that I/O operations
|
|
should not be restarted automatically.</para><para>The data type for the <literal>
|
|
optdata</literal> parameter is <literal>(int *)</literal>.</para></listitem>
|
|
</itemizedlist>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>LDAP_OPT_SERVER_CONTROLS</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
|
|
representing the LDAP v3 server controls you want sent with every request
|
|
by default. Typically, since controls are specific to the type of request,
|
|
you may want to pass the controls using operation-specific functions (such
|
|
as <olink targetptr="bdaqa">ldap_add_ext</olink>) instead.</para>
|
|
<para>The data type for the <literal>optdata</literal> parameter is <literal>(LDAPControl
|
|
***)</literal>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>LDAP_OPT_SIZELIMIT</literal></para></entry>
|
|
<entry>
|
|
<para>Maximum number of entries that should be returned by the server in search
|
|
results. The LDAP server may impose a smaller size limit than the limit you
|
|
specify as the server administrator also has the ability to set this limit.</para>
|
|
<para>The data type for the <literal>optdata</literal> parameter is <literal>(int
|
|
*)</literal>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>LDAP_OPT_SSL</literal></para></entry>
|
|
<entry>
|
|
<para>Determines whether or not SSL is enabled. <literal>optdata</literal> can
|
|
be one of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><literal>LDAP_OPT_ON</literal> specifies that SSL is enabled.</para>
|
|
</listitem>
|
|
<listitem><para><literal>LDAP_OPT_OFF</literal> specifies that SSL is disabled.</para>
|
|
<para>The data type for the <literal>optdata</literal> parameter is <literal>(int
|
|
*)</literal>.</para></listitem>
|
|
</itemizedlist>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>LDAP_OPT_THREAD_FN_PTRS</literal></para></entry>
|
|
<entry>
|
|
<para>Lets you specify the thread function pointers. </para>
|
|
<para>The data type for the <literal>optdata</literal> parameter is <literal>(struct
|
|
ldap_thread_fns *)</literal>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>LDAP_OPT_TIMELIMIT</literal></para></entry>
|
|
<entry>
|
|
<para>Maximum number of seconds that should be spent by the server when answering
|
|
a search request. The LDAP server may impose a shorter time limit than the
|
|
limit you specify as the server administrator also has the ability to set
|
|
this limit.</para>
|
|
<para>The data type for the <literal>optdata</literal> parameter is <literal>(int
|
|
*)</literal>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>LDAP_X_OPT_EXTIO_FN_PTRS</literal></para></entry>
|
|
<entry>
|
|
<para>Extended I/O function callback option.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>LDAP_X_OPT_CONNECT_TIMEOUT</literal></para></entry>
|
|
<entry>
|
|
<para>Value of a time out (expressed in milliseconds) for non-blocking connect
|
|
call.</para>
|
|
<para>The data type for the <literal>optdata</literal> parameter is <literal>(int
|
|
*)</literal>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>LDAP_X_OPT_SOCKBUF</literal></para></entry>
|
|
<entry>
|
|
<para>Socket buffer structure associated to the LDAP connection.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
<para>See also <citerefentry><refentrytitle>ldap_set_option</refentrytitle>
|
|
<manvolnum>3LDAP</manvolnum></citerefentry> for details on <literal>LDAP_OPT_X_SASL*
|
|
</literal> parameters.</para></sect3>
|
|
<sect3 id="garyu"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para><literal>-1</literal> if unsuccessful.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="garzz"><title>Example</title>
|
|
<example id="garza"><title>Using <function>ldap_set_option</function></title>
|
|
<programlisting>#include <stdio.h>
|
|
#include <ldap.h>
|
|
...
|
|
LDAP *ld;
|
|
int max_ret = 100, max_tim = 30;
|
|
char *host = "ldap.sun.com";
|
|
...
|
|
/* Initialize a session with the LDAP server ldap.sun.com:389 */
|
|
/* Use prldap_init() for IPv6 support. */
|
|
if ( ( ld = ldap_init( host, LDAP_PORT ) ) == NULL ) {
|
|
perror( "ldap_init" );
|
|
return( 1 );
|
|
}
|
|
|
|
/* Set the maximum number of entries returned */
|
|
if ( ldap_set_option( ld, LDAP_OPT_SIZELIMIT, &max_ret) !
|
|
LDAP_SUCCESS) {
|
|
ldap_perror( ld, "ldap_set_option" );
|
|
return( 1 );
|
|
}
|
|
...</programlisting>
|
|
</example>
|
|
</sect3>
|
|
<sect3 id="garyg"><title>See Also</title>
|
|
<para><olink targetptr="bdasv">ldap_init</olink>, <olink targetptr="bdaxr">prldap_init
|
|
</olink> (IPv6), <olink targetptr="bdass">ldap_get_option</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdavh"><title><function>ldap_set_rebind_proc</function></title>
|
|
<indexterm>
|
|
<primary>C SDK functions</primary>
|
|
<secondary><function>ldap_set_rebind_proc</function></secondary>
|
|
</indexterm><indexterm>
|
|
<primary><function>ldap_set_rebind_proc</function></primary>
|
|
</indexterm>
|
|
<para>The <function>ldap_set_rebind_proc</function> function sets a <emphasis>rebind
|
|
</emphasis> , which is called by your client to obtain authentication credentials
|
|
when following a referral.</para>
|
|
<sect3 id="gasad"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
void ldap_set_rebind_proc( LDAP *ld,
|
|
LDAP_REBINDPROC_CALLBACK *rebindproc, void *arg );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gasab"><title>Parameters</title>
|
|
<table frame="topbot" id="garzb"><title><function>ldap_set_rebind_proc</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>rebindproc</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to a function called back to obtain bind credentials when a
|
|
new server is contacted during an LDAP referral.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>arg</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an additional argument that you want to pass to the rebind
|
|
function.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garzn"><title>Description</title>
|
|
<para>Call <function>ldap_set_rebind_proc</function> to specify the rebind
|
|
function. This rebind function is called by the LDAP client when following
|
|
a referral to a new LDAP server. It is responsible for obtaining the credentials
|
|
used to authenticate to the new server. For example, suppose LDAP server A
|
|
sends a referral to your client. The referral points your client to LDAP server
|
|
B. When automatically following the referral, your client calls the rebind
|
|
function to obtain a DN and credentials; your client uses these to authenticate
|
|
to server B. By default, if you do not call <function>ldap_set_rebind_proc</function> or
|
|
if you pass <literal>NULL</literal> for the <literal>rebindproc</literal> argument,
|
|
your client authenticates anonymously when following referrals.</para>
|
|
<para>The rebind function that you specify with <function>ldap_set_rebind_proc</function> should
|
|
have the following prototype:</para>
|
|
<programlisting>int LDAP_CALL LDAP_CALLBACK rebindproc( LDAP *ld, char **dnp,
|
|
char **passwdp, int *authmethodp, int freeit, void *arg );</programlisting>
|
|
<note><para><literal>LDAP_CALL</literal> and <literal>LDAP_CALLBACK</literal> are
|
|
used to set up calling conventions, such as Pascal calling conventions on
|
|
Windows. These are defined in the <literal>lber.h</literal> header file.</para>
|
|
</note>
|
|
<para>The following procedure explains what the rebind function is expected
|
|
to do. LDAP clients that are built with &DirectorySDKForC; use this procedure
|
|
when following referrals.</para>
|
|
<task id="garyi"><title>To Follow Referrals</title>
|
|
<procedure>
|
|
<step><para>The LDAP server sends a referral back to the client.</para></step>
|
|
<step><para>The client calls the rebind function, passing
|
|
<literal>0</literal> as the <literal>freeit</literal> argument.
|
|
</para></step>
|
|
<step><para>The rebind function sets the <literal>dnp</literal>,
|
|
<literal>passwdp</literal>, and
|
|
<literal>authmethodp</literal> arguments to point to the following information:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem><para>The <literal>dnp</literal> argument is set to point to the
|
|
DN to be used to authenticate to the new LDAP server.</para>
|
|
<itemizedlist>
|
|
<listitem><para>The <literal>passwdp</literal> argument is set to point to
|
|
the credentials for this DN.</para></listitem>
|
|
<listitem><para>The <literal>authmethodp</literal> argument is set to point
|
|
to the method of authentication used (for example, <literal>LDAP_AUTH_SIMPLE</literal>).
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</step>
|
|
<step><para>If successful, the rebind function returns
|
|
<errorcode>LDAP_SUCCESS</errorcode>
|
|
, and referral processing continues. (If any other value is returned,
|
|
referral processing stops, and that value is returned as the result code for
|
|
the original LDAP request.)</para></step>
|
|
<step><para>The client gets the DN, credentials, and authentication method
|
|
from the arguments of the rebind function and uses this information to authenticate
|
|
to the new LDAP server.</para></step>
|
|
<step><para>The client calls the rebind function again, passing
|
|
<literal>1</literal> as the <literal>freeit</literal> argument.
|
|
</para></step>
|
|
<step><para>The rebind function frees any memory allocated earlier to specify
|
|
the DN and credentials.</para><para>You need to write a rebind function that
|
|
does the following:</para>
|
|
<itemizedlist>
|
|
<listitem><para>If <literal>freeit</literal> is <literal>0</literal>, set
|
|
the following pointers:</para>
|
|
<itemizedlist>
|
|
<listitem><para>Set <literal>dnp</literal> to point to the DN to be used for
|
|
authentication.</para></listitem>
|
|
<listitem><para>Set <literal>passwdp</literal> to point to the credentials
|
|
to be used for authentication.</para></listitem>
|
|
<listitem><para>Set <literal>authmethodp</literal> to point to the method
|
|
of authentication used (for example, <literal>LDAP_AUTH_SIMPLE</literal>).</para>
|
|
<para>You can also make use of the <literal>arg</literal> argument, which
|
|
is a pointer to the argument specified in the <function>ldap_set_rebind_proc</function> function.
|
|
If successful, returns <errorcode>LDAP_SUCCESS</errorcode>. Otherwise, returns
|
|
the appropriate LDAP error code.</para></listitem>
|
|
</itemizedlist>
|
|
<para>If <literal>freeit</literal> is <literal>1</literal>, free any memory
|
|
that you allocated to create the DN and credentials.</para><para>After you
|
|
have defined this function, pass the function name to <function>ldap_set_rebind_proc
|
|
</function> to register your rebind function.</para></listitem>
|
|
</itemizedlist>
|
|
<note><para>In order to use the rebind function, the <literal>LDAP_OPT_REFERRALS</literal> option
|
|
must be set to <literal>LDAP_OPT_ON</literal>, so that your client automatically
|
|
follows referrals. This option is set to <literal>LDAP_OPT_ON</literal> by
|
|
default.</para></note>
|
|
</step>
|
|
</procedure>
|
|
</task>
|
|
</sect3>
|
|
<sect3 id="garzl"><title>Example</title>
|
|
<para><olink targetptr="ldap-set-rebind-proc-example">Example 21–49</olink>
|
|
demonstrates how to write and register a rebind function.</para>
|
|
<example id="ldap-set-rebind-proc-example"><title>Using <function>ldap_set_rebind_proc
|
|
</function></title>
|
|
<programlisting>#include "ldap.h"
|
|
...
|
|
/* Declare your rebind function */
|
|
int rebindproc( LDAP *ld, char **dnp, char **passwdp,
|
|
int *authmethodp, int freeit, void *arg );
|
|
...
|
|
int main( int argc, char **argv )
|
|
{
|
|
LDAP *ld;
|
|
/* Additional argument to be passed to the rebind function */
|
|
char *testarg = "cn=admin,cn=Administrators,cn=config";
|
|
/* Get a handle to an LDAP connection. Use prldap_init() for IPv6. */
|
|
if ( (ld = ldap_init( "directory.example.com", 389 )) == NULL ) {
|
|
perror( "ldap_init" );
|
|
return( 1 );
|
|
}
|
|
/* Specify the function used for reauthentication on referrals */
|
|
ldap_set_rebind_proc( ld, rebindproc, (void *)testarg );
|
|
/* Authenticate */
|
|
if ( ldap_simple_bind_s( ld, "uid=bjensen,ou=People,dc=example,dc=com",
|
|
"hifalutin" ) != LDAP_SUCCESS ) {
|
|
ldap_perror( ld, "ldap_simple_bind_s" );
|
|
return( 1 );
|
|
}
|
|
...
|
|
/* Your code to interact with the LDAP server */
|
|
...
|
|
}
|
|
...
|
|
/* rebindproc is the rebind function responsible for providing the DN,
|
|
credentials, and authentication method used for authenticating the
|
|
client to other Directory Servers.
|
|
The function should set the following arguments:
|
|
- dnp should point to the DN that will be used for authentication.
|
|
- passwdp should point to the credentials used for authentication.
|
|
- authmethodp should point to the method of authentication to be used
|
|
(for example, LDAP_AUTH_SIMPLE).
|
|
The function should return LDAP_SUCCESS if successful or an LDAP
|
|
error code if an error occurs.
|
|
In order to demonstrate how the freeit argument works, this example
|
|
uses strdup() to copy the DN and password. You can also just copy
|
|
string pointers if the DN and password are already available as
|
|
global variables.
|
|
*/
|
|
int LDAP_CALL LDAP_CALLBACK rebindproc(
|
|
LDAP *ld, char **dnp, char **passwdp,
|
|
int *authmethodp, int freeit, void *arg )
|
|
{
|
|
printf( "Rebind function called.\n" );
|
|
switch ( freeit ) {
|
|
/* Your client calls the rebind function with freeit==1 when it needs
|
|
to free any memory you've allocated. */
|
|
case 1:
|
|
printf( "\tFreeing memory.\n" );
|
|
if ( dnp && *dnp ) {
|
|
free( *dnp );
|
|
}
|
|
if ( passwdp && *passwdp ) {
|
|
free( *passwdp );
|
|
}
|
|
break;
|
|
/* Your client calls the rebind function with freeit==0 when it needs
|
|
to get the DN, credentials, and authentication method. */
|
|
case 0:
|
|
printf( "\tGetting DN and credentials.\n" );
|
|
*dnp = strdup( "uid=username,o=OtherServerSuffix" );
|
|
*passwdp = strdup( "23skidoo" );
|
|
*authmethodp = LDAP_AUTH_SIMPLE;
|
|
break;
|
|
default:
|
|
printf( "\tUnknown value of freeit argument: %d\n", freeit );
|
|
break;
|
|
}
|
|
/* If you successfully set the DN and credentials, you should return
|
|
LDAP_SUCCESS. (Any other return code will stop the client from
|
|
automatically following the referral. */
|
|
return LDAP_SUCCESS;
|
|
}</programlisting>
|
|
</example>
|
|
</sect3>
|
|
<sect3 id="garyo"><title>See Also</title>
|
|
<para><olink targetptr="bdavi">ldap_simple_bind</olink>, <olink targetptr="bdavj">ldap_simple_bind_s</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdavi"><title><function>ldap_simple_bind</function></title>
|
|
<indexterm>
|
|
<primary>C SDK functions</primary>
|
|
<secondary><function>ldap_simple_bind</function></secondary>
|
|
</indexterm><indexterm>
|
|
<primary><function>ldap_simple_bind</function></primary>
|
|
</indexterm>
|
|
<para>The <function>ldap_simple_bind</function> function synchronously authenticates
|
|
your client to the LDAP server using a DN and a password.</para>
|
|
<sect3 id="gasac"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_simple_bind(LDAP *ld, const char *who, const char *passwd);</programlisting>
|
|
</sect3>
|
|
<sect3 id="garzr"><title>Parameters</title>
|
|
<table frame="topbot" id="garzj"><title><function>ldap_simple_bind</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>who</literal></para></entry>
|
|
<entry>
|
|
<para>DN of the user who wants to authenticate. For anonymous authentication,
|
|
set this or the <parameter>passwd</parameter> argument to <literal>NULL</literal>.
|
|
</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>passwd</literal></para></entry>
|
|
<entry>
|
|
<para>Password of the user who wants to authenticate. For anonymous authentication,
|
|
set this or the who argument to <literal>NULL</literal>.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="garzg"><title>Returns</title>
|
|
<para>Returns the message ID of the <function>ldap_simple_bind</function> operation.
|
|
To check the result of this operation, call <olink targetptr="bdauu">ldap_result</olink>
|
|
and <olink targetptr="bdauv">ldap_result2error</olink>.</para></sect3>
|
|
<sect3 id="garyq"><title>Description</title>
|
|
<para>The <function>ldap_simple_bind</function> function authenticates to
|
|
the LDAP server. It verifies that the password supplied for authentication
|
|
matches the <literal>userPassword</literal> attribute of the given entry. <function>
|
|
ldap_simple_bind</function> is an asynchronous function; it does not directly
|
|
return results. If you want the results to be returned directly by the function,
|
|
call the synchronous function <olink targetptr="bdavj">ldap_simple_bind_s</olink>.
|
|
</para>
|
|
<note><para>If you specify a DN but no password, your client will bind to
|
|
the server anonymously. If you want a <literal>NULL</literal> password to
|
|
be rejected as an incorrect password, you need to write code to perform the
|
|
check before you call the <function>ldap_simple_bind</function> function.</para>
|
|
<para>The use of this function may be a security threat if used on a non-secured
|
|
connection as the password is transmitted in clear text. For password-based
|
|
authentication, use a secure connection (<olink targetptr="bdavs">ldapssl_init</olink> or <olink targetptr="bdavx">ldapssl_tls_start_s</olink>) or SASL Digest-MD5 mechanism
|
|
(<olink targetptr="bdauw">ldap_sasl_bind</olink> or <olink targetptr="bdaux">ldap_sasl_bind_s
|
|
</olink>).</para></note>
|
|
</sect3>
|
|
<sect3 id="gasaa"><title>Example</title>
|
|
<para><olink targetptr="ldap-simple-bind-example">Example 21–50</olink> calls
|
|
<function>ldap_simple_bind</function> to authenticate the user <literal>Barbara
|
|
Jensen</literal> to the directory.</para>
|
|
<example id="ldap-simple-bind-example"><title>Using <function>ldap_simple_bind</function></title>
|
|
<programlisting>#include <stdio.h>
|
|
#include <ldap.h>
|
|
...
|
|
LDAP *ld;
|
|
char *host = "ldap.sun.com";
|
|
char *dn = "uid=bjensen,ou=People,dc=example,dc=com";
|
|
char *pw = "hifalutin";
|
|
struct timeval zerotime;
|
|
zerotime.tv_sec = zerotime.tv_usec = 0L;
|
|
...
|
|
/* Initialize a session with the LDAP server ldap.example.com:389 */
|
|
/* Use prldap_init() for IPv6 support. */
|
|
if ( ( ld = ldap_init( host, LDAP_PORT ) ) == NULL ) {
|
|
perror( "ldap_init" );
|
|
return( 1 );
|
|
}
|
|
/* Attempt to bind with the LDAP server */
|
|
msgid = ldap_simple_bind( ld, dn, pw );
|
|
|
|
/* Initialize the value returned by ldap_result() */
|
|
rc = 0;
|
|
|
|
/* While the operation is still running, do this: */
|
|
while ( rc == 0 ) {
|
|
... /* do other work while waiting */...
|
|
|
|
/* Check the status of the LDAP operation */
|
|
rc = ldap_result( ld, msgid, NULL, &zerotime, &result );
|
|
switch( rc ) {
|
|
/* If -1 was returned, an error occurred */
|
|
case -1:
|
|
ldap_perror( ld, "Error in results: " );
|
|
return( 1 );
|
|
/* If 0 was returned, the operation is still in progress */
|
|
case 0:
|
|
continue;
|
|
/* If any other value is returned, assume we are done */
|
|
default:
|
|
/* Check if the "bind" operation was successful */
|
|
if ( ldap_result2error( result ) != LDAP_SUCCESS ) {
|
|
ldap_perror( ld, "Error binding to server: " );
|
|
return( 1 );
|
|
}
|
|
}
|
|
}
|
|
...</programlisting>
|
|
</example>
|
|
</sect3>
|
|
<sect3 id="garzo"><title>See Also</title>
|
|
<para><olink targetptr="bdavj">ldap_simple_bind_s</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdavj"><title><function>ldap_simple_bind_s</function></title>
|
|
<indexterm>
|
|
<primary>C SDK functions</primary>
|
|
<secondary><function>ldap_simple_bind_s</function></secondary>
|
|
</indexterm><indexterm>
|
|
<primary><function>ldap_simple_bind_s</function></primary>
|
|
</indexterm>
|
|
<para>The <function>ldap_simple_bind</function> function synchronously authenticates
|
|
your client to the LDAP server using a DN and a password.</para>
|
|
<sect3 id="gasar"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_simple_bind_s( LDAP *ld, const char *who, const char *passwd );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gasax"><title>Parameters</title>
|
|
<table frame="topbot" id="gasbi"><title><function>ldap_simple_bind_s</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>who</literal></para></entry>
|
|
<entry>
|
|
<para>DN of the user who wants to authenticate. For anonymous authentication,
|
|
set this or the <literal>passwd</literal> argument to <literal>NULL</literal>.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>passwd</literal></para></entry>
|
|
<entry>
|
|
<para>Password of the user who wants to authenticate. For anonymous authentication,
|
|
set this or the who argument to <literal>NULL</literal>.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gasah"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if an invalid parameter
|
|
was passed to the function.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_NOT_SUPPORTED</errorcode> if controls are
|
|
included in your request (for example, as a session preference) and your LDAP
|
|
client does not specify that it is using the LDAP v3. Make sure that you set
|
|
the version of your LDAP client to version 3 before calling this function.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_ENCODING_ERROR</errorcode> if an error occurred
|
|
when BER-encoding the request to send to the server.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_DECODING_ERROR</errorcode> if an error occurred
|
|
when the LDAP API library was decoding the BER-encoded results received from
|
|
the server.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
|
|
allocated.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_SERVER_DOWN</errorcode> if the LDAP server
|
|
did not receive the request or if the connection to the server was lost.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_LOCAL_ERROR</errorcode> if an error occurred
|
|
when receiving the results from the server.</para></listitem>
|
|
</itemizedlist>
|
|
<note><para>&cnDirectoryServer; and other LDAP server products may send result
|
|
codes in addition to those described. For example, the server may have loaded
|
|
a plug-in that returns custom result codes. Check your LDAP server documentation
|
|
for other result codes.</para></note>
|
|
</sect3>
|
|
<sect3 id="gascd"><title>Description</title>
|
|
<para>The <function>ldap_simple_bind_s</function> function authenticates to
|
|
the LDAP server. It verifies that the password supplied for authentication
|
|
matches the <literal>userPassword</literal> attribute of the given entry. <function>
|
|
ldap_simple_bind_s</function> is a synchronous function, which directly returns
|
|
the results of the operation. If you want to perform other operations while
|
|
waiting for the results of this operation, call the asynchronous function <olink targetptr="bdavi">ldap_simple_bind</olink> instead.</para>
|
|
<note><para>If you specify a DN but no password, your client will bind to
|
|
the server anonymously. If you want a <literal>NULL</literal> password to
|
|
be rejected as an incorrect password, you need to write code to perform the
|
|
check before you call the <function>ldap_simple_bind_s</function> function.</para>
|
|
<para>The use of this function may be a security threat if used on a non-secured
|
|
connection as the password is transmitted in clear text. For password-based
|
|
authentication, use a secure connection (<olink targetptr="bdavs">ldapssl_init</olink> or <olink targetptr="bdavx">ldapssl_tls_start_s</olink>) or SASL Digest-MD5 mechanism
|
|
(<olink targetptr="bdauw">ldap_sasl_bind</olink> or <olink targetptr="bdaux">ldap_sasl_bind_s
|
|
</olink>).</para></note>
|
|
</sect3>
|
|
<sect3 id="gasak"><title>Example</title>
|
|
<para><olink targetptr="ldap-simple-bind-s-example">Example 21–51</olink>
|
|
uses the synchronous <function>ldap_simple_bind_s</function> function to authenticate
|
|
to the directory as the user <literal>Barbara Jensen</literal>.</para>
|
|
<example id="ldap-simple-bind-s-example"><title>Using <function>ldap_simple_bind_s
|
|
</function></title>
|
|
<programlisting>#include <stdio.h>
|
|
#include <ldap.h>
|
|
...
|
|
LDAP *ld;
|
|
char *host = "ldap.sun.com";
|
|
char *dn = "uid=bjensen,ou=People,dc=example,dc=com";
|
|
char *pw = "hifalutin";
|
|
...
|
|
/* Initialize a session with the LDAP server ldap.sun.com:389 */
|
|
/* Use prldap_init() for IPv6 support. */
|
|
if ( ( ld = ldap_init( host, LDAP_PORT ) ) == NULL ) {
|
|
perror( "ldap_init" );
|
|
return( 1 );
|
|
}
|
|
/* Attempt to bind with the LDAP server */
|
|
if ( ldap_simple_bind_s( ld, dn, pw ) != LDAP_SUCCESS ) {
|
|
ldap_perror( ld, "Authentication failed: " );
|
|
return( 1 );
|
|
}
|
|
...</programlisting>
|
|
</example>
|
|
</sect3>
|
|
<sect3 id="gasap"><title>See Also</title>
|
|
<para><olink targetptr="bdavi">ldap_simple_bind</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdavk"><title><function>ldap_sort_entries</function></title>
|
|
<indexterm>
|
|
<primary>C SDK functions</primary>
|
|
<secondary><function>ldap_sort_entries</function></secondary>
|
|
</indexterm><indexterm>
|
|
<primary><function>ldap_sort_entries</function></primary>
|
|
</indexterm>
|
|
<para>The <function>ldap_sort_entries</function> function sorts a chain of
|
|
entries retrieved from an LDAP search call.</para>
|
|
<sect3 id="gasaq"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_sort_entries( LDAP *ld, LDAPMessage *chain, char *attr,
|
|
LDAP_CMP_CALLBACK *cmp );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gascc"><title>Parameters</title>
|
|
<table frame="topbot" id="gasay"><title><function>ldap_sort_entries</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>chain</literal></para></entry>
|
|
<entry>
|
|
<para>Chain of entries returned by the <olink targetptr="bdauu">ldap_result</olink> or <olink targetptr="bdavb">ldap_search_s</olink> function.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>attr</literal></para></entry>
|
|
<entry>
|
|
<para>Attribute to use when sorting the results. To sort by DN instead of
|
|
by attribute, use <literal>NULL</literal>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>cmp</literal></para></entry>
|
|
<entry>
|
|
<para>Comparison function used when sorting the values.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gasbe"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para>If unsuccessful, returns a <literal>NULL</literal> and sets
|
|
the appropriate error code in the <olink targetptr="bdakj">LDAP</olink> structure.
|
|
To get the error code, call <olink targetptr="bdasq">ldap_get_lderrno</olink>.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="gasaf"><title>Description</title>
|
|
<para>The <function>ldap_sort_entries</function> function sorts a chain of
|
|
entries retrieved from an LDAP search call (<olink targetptr="bdavb">ldap_search_s
|
|
</olink> or <olink targetptr="bdauu">ldap_result</olink>) either by DN or
|
|
a specified attribute in the entries.</para></sect3>
|
|
<sect3 id="gasbj"><title>Example</title>
|
|
<para><olink targetptr="ldap-sort-entries-example">Example 21–52</olink>
|
|
sorts entries by the <literal>roomNumber</literal> attribute.</para>
|
|
<example id="ldap-sort-entries-example"><title>Using <function>ldap_sort_entries</function></title>
|
|
<programlisting>#include <stdio.h>
|
|
#include <string.h>
|
|
#include <ldap.h>
|
|
LDAP *ld;
|
|
LDAPMessage *result;
|
|
char *my_searchbase = "dc=example,dc=com";
|
|
char *my_filter = "(sn=Jensen)";
|
|
char *sortby = "roomNumber";
|
|
...
|
|
/* Search the directory */
|
|
if ( ldap_search_s( ld, my_searchbase, LDAP_SCOPE_SUBTREE, my_filter,
|
|
NULL, 0, &result ) !=
|
|
LDAP_SUCCESS ) {
|
|
ldap_perror( ld, "ldap_search_s" );
|
|
return( 1 );
|
|
}
|
|
/* Sort the results by room number, using strcasecmp */
|
|
if ( ldap_sort_entries( ld, &result, sortby, strcasecmp ) !=
|
|
LDAP_SUCCESS ) {
|
|
ldap_perror( ld, "ldap_sort_entries" );
|
|
return( 1 );
|
|
}
|
|
...</programlisting>
|
|
</example>
|
|
</sect3>
|
|
<sect3 id="gasba"><title>See Also</title>
|
|
<para><olink targetptr="bdaty">ldap_multisort_entries</olink>, <olink targetptr="bdauu">ldap_result</olink>, <olink targetptr="bdavb">ldap_search_s</olink>,
|
|
<olink targetptr="bdakz">LDAP_CMP_CALLBACK</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="ldap-start-tls-s"><title><function>ldap_start_tls_s</function></title>
|
|
<indexterm>
|
|
<primary>C SDK functions</primary>
|
|
<secondary><function>ldap_start_tls_s</function></secondary>
|
|
</indexterm><indexterm>
|
|
<primary><function>ldap_start_tls_s</function></primary>
|
|
</indexterm>
|
|
<para>The <function>ldap_start_tls_s</function> initiates a Start Transport
|
|
Layer Security (TLS) operation as defined in <ulink
|
|
url="http://www.ietf.org/rfc/rfc4513.txt" type="text_url">RFC 4513</ulink>.</para>
|
|
<para>Before using this function, call <olink targetptr="bdavo">ldapssl_client_init
|
|
</olink>, <olink targetptr="bdavp">ldapssl_clientauth_init</olink>, or <olink targetptr="bdavn">ldapssl_advclientauth_init</olink> to initialize use of
|
|
the certificate database.</para>
|
|
<sect3><title>Syntax</title>
|
|
<programlisting>#include <ldap_ssl.h>
|
|
int ldap_start_tls_s( LDAP *ld, LDAPControl **serverctrls,
|
|
LDAPControl **clientctrls );</programlisting>
|
|
</sect3>
|
|
<sect3><title>Parameters</title>
|
|
<table frame="topbot" id="gbgtl"><title><function>ldap_start_tls_s</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2" colsep="0" rowsep="0"><colspec colwidth="50*"><colspec
|
|
colwidth="50*">
|
|
<thead>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>serverctrls</literal></para></entry>
|
|
<entry>
|
|
<para>List of LDAP server controls.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>clientctrls</literal></para></entry>
|
|
<entry>
|
|
<para>List of client controls.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_OPERATIONS_ERROR</errorcode> if TLS has already
|
|
been established.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_PROTOCOL_ERROR</errorcode> if TLS is not supported.
|
|
</para></listitem>
|
|
<listitem><para><errorcode>LDAP_REFERRAL</errorcode> if this server does not
|
|
support TLS, but the server referred to may.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_UNAVAILABLE</errorcode> if the server is shutting
|
|
down, or supports TLS but cannot provide it at this time.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="bdavl"><title><function>ldap_sort_strcasecmp</function></title>
|
|
<indexterm>
|
|
<primary>C SDK functions</primary>
|
|
<secondary><function>ldap_sort_strcasecmp</function></secondary>
|
|
</indexterm><indexterm>
|
|
<primary><function>ldap_sort_strcasecmp</function></primary>
|
|
</indexterm>
|
|
<para>The <function>ldap_sort_strcasecmp</function> routine compares two strings
|
|
and ignores any differences in case when comparing uppercase and lowercase
|
|
characters.</para>
|
|
<sect3 id="gasbc"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_sort_strcasecmp( const char **a, const char **b );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gasbz"><title>Parameters</title>
|
|
<table frame="topbot" id="gasbu"><title><function>ldap_sort_strcasecmp</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>a</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to first string to compare</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>b</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to second string to compare</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gasbp"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para>If <literal>a</literal> is greater than <literal>b</literal>,
|
|
returns a value greater than <literal>0</literal>.</para></listitem>
|
|
<listitem><para>If <literal>a</literal> is equal to <literal>b</literal>,
|
|
returns <literal>0</literal>.</para></listitem>
|
|
<listitem><para>If <literal>a</literal> is less than <literal>b</literal>,
|
|
returns a value less than <literal>0</literal>.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="gasaj"><title>Description</title>
|
|
<para>The <function>ldap_sort_strcasecmp</function> routine compares two strings
|
|
and ignores any differences in case when comparing uppercase and lowercase
|
|
characters. This function is similar to the C function <function>strcasecmp</function>.
|
|
When sorting attribute values with <olink targetptr="bdavl">ldap_sort_strcasecmp</olink>,
|
|
call <function>ldap_sort_strcasecmp</function> to compare the attribute values.</para>
|
|
<note><para>This function works with ASCII values only. For UTF-8 data, the
|
|
comparison result is unspecified.</para></note>
|
|
</sect3>
|
|
<sect3 id="gasau"><title>See Also</title>
|
|
<para><olink targetptr="bdavl">ldap_sort_strcasecmp</olink>, <olink targetptr="bdamt">LDAP_VALCMP_CALLBACK</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdavm"><title><function>ldap_sort_values</function></title>
|
|
<indexterm>
|
|
<primary>C SDK functions</primary>
|
|
<secondary><function>ldap_sort_values</function></secondary>
|
|
</indexterm><indexterm>
|
|
<primary><function>ldap_sort_values</function></primary>
|
|
</indexterm>
|
|
<para>The <function>ldap_sort_values</function> function sorts an array of
|
|
values retrieved from an <olink targetptr="bdast">ldap_get_values</olink> call.</para>
|
|
<sect3 id="gasas"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_sort_values( LDAP *ld, char **vals,
|
|
LDAP_VALCMP_CALLBACK cmp );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gasca"><title>Parameters</title>
|
|
<table frame="topbot" id="gasbf"><title><function>ldap_sort_values</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>vals</literal></para></entry>
|
|
<entry>
|
|
<para>The array of values to sort.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>cmp</literal></para></entry>
|
|
<entry>
|
|
<para>Comparison function used when sorting the values. In the <olink targetptr="bdavl">ldap_sort_strcasecmp</olink> function, the comparison function
|
|
must pass <literal>char **</literal> parameters. Because of this, you need
|
|
to use the <olink targetptr="bdavl">ldap_sort_strcasecmp</olink> function,
|
|
rather than a function like <function>strcasecmp</function>.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gasby"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para>If unsuccessful, returns an LDAP error code.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="gascf"><title>Example</title>
|
|
<para><olink targetptr="ldap-sort-values-example">Example 21–53</olink> sorts
|
|
the values of attributes before printing them.</para>
|
|
<example id="ldap-sort-values-example"><title>Using <function>ldap_sort_values</function></title>
|
|
<programlisting>#include <stdio.h>
|
|
#include <string.h>
|
|
#include <ldap.h>
|
|
...
|
|
LDAP *ld;
|
|
LDAPMessage *result, *e;
|
|
BerElement *ber;
|
|
char *a, *dn;
|
|
char **vals;
|
|
int i;
|
|
char *my_searchbase = "dc=example,dc=com";
|
|
char *my_filter = "(sn=Jensen)";
|
|
...
|
|
if ( ( vals = ldap_get_values( ld, e, a ) ) != NULL ) {
|
|
/* Sort the values of the attribute */
|
|
if ( ldap_sort_values( ld, vals, strcasecmp ) ) != LDAP_SUCCESS ) {
|
|
ldap_perror( ld, "ldap_sort_values" );
|
|
return( 1 );
|
|
}
|
|
/* Print the values of the attribute */
|
|
for ( i = 0; vals[i] != NULL; i++ ) {
|
|
printf( "%s: %s\n", a, vals[i] );
|
|
}
|
|
/* Free the values from memory */
|
|
ldap_value_free( vals );
|
|
}
|
|
...</programlisting>
|
|
</example>
|
|
</sect3>
|
|
<sect3 id="gasaz"><title>See Also</title>
|
|
<para><olink targetptr="bdast">ldap_get_values</olink>, <olink targetptr="bdavl">
|
|
ldap_sort_strcasecmp</olink>, <olink targetptr="bdamt">LDAP_VALCMP_CALLBACK</olink>.
|
|
</para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdavn"><title><function>ldapssl_advclientauth_init</function></title>
|
|
<indexterm>
|
|
<primary>C SDK functions</primary>
|
|
<secondary><function>ldap_ldapssl_*</function></secondary>
|
|
</indexterm><indexterm>
|
|
<primary><function>ldap_ldapssl_*</function></primary>
|
|
</indexterm>
|
|
<para>The <function>ldapssl_advclientauth_init</function> function initialize
|
|
the secure parts (Security and SSL) of the runtime for use by a client application
|
|
that may want to do SSL client authentication.</para>
|
|
<sect3 id="gasal"><title>Syntax</title>
|
|
<programlisting>#include <ldap_ssl.h>
|
|
int LDAP_CALL ldapssl_advclientauth_init( char *certdbpath,
|
|
void *certdbhandle, int needkeydb, char *keydbpath,
|
|
void *keydbhandle, int needsecmoddb, char *secmodpath,
|
|
const int sslstrength);</programlisting>
|
|
</sect3>
|
|
<sect3 id="gasbh"><title>Parameters</title>
|
|
<note><para>Please see the description of the <literal>sslstrength</literal> value
|
|
and note the potential problems that can be caused by passing in wrong host
|
|
and port name values.</para></note>
|
|
<table frame="topbot" id="gasbs"><title><function>ldapssl_advclientauth_init</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>certdbpath</literal></para></entry>
|
|
<entry>
|
|
<para>Specifies the path to the database containing certificates for your
|
|
client. You can include the database filename in the path (for example, <literal>
|
|
/usr/mozilla/</literal> <replaceable>cert_file_name</replaceable><literal>.db</literal>).
|
|
</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>certdbhandle</literal></para></entry>
|
|
<entry>
|
|
<para>Pass a <literal>NULL</literal> value for this. (This parameter is not
|
|
currently used.)</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>needkeydb</literal></para></entry>
|
|
<entry>
|
|
<para>Specifies whether or not the private key database needs to be opened
|
|
for use. This parameter can have one of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para>If it is a non-zero value, the function opens the private
|
|
key database, which is identified by the <literal>keydbpath</literal> argument.</para>
|
|
</listitem>
|
|
<listitem><para>If <literal>0</literal>, the function does not open the private
|
|
key database.</para></listitem>
|
|
</itemizedlist>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>keydbpath</literal></para></entry>
|
|
<entry>
|
|
<para>Specifies the path to the database containing the private key certified
|
|
by your certificate. You can include the database filename in the path (for
|
|
example, <literal>/usr/mozilla/</literal><replaceable>key_file_name</replaceable><literal>
|
|
.db</literal>).</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>needsecmoddb</literal></para></entry>
|
|
<entry>
|
|
<para>Specifies whether or not the security module database file needs to
|
|
be opened for use. This parameter can have one of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para>If it is a non-zero value, the function opens the security
|
|
module database, which is identified by the <literal>keydbpath</literal> argument.
|
|
</para></listitem>
|
|
<listitem><para>If <literal>0</literal>, the function does not open the security
|
|
modules database.</para></listitem>
|
|
</itemizedlist>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>secmodpath</literal></para></entry>
|
|
<entry>
|
|
<para>Path to the database containing security modules. You can include the
|
|
database filename in the path (for example, <literal>/usr/mozilla/</literal><replaceable>
|
|
secmod_file_name</replaceable> <literal>.db</literal>).</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>sslstrength</literal></para></entry>
|
|
<entry>
|
|
<para>Specifies how the server certificate is evaluated. It takes one of the
|
|
following:</para>
|
|
<itemizedlist>
|
|
<listitem><para><literal>LDAPSSL_AUTH_WEAK</literal> indicates that you accept
|
|
the server’s certificate without checking the for certificate authority
|
|
(CA) that issued the certificate.</para></listitem>
|
|
<listitem><para><literal>LDAPSSL_AUTH_CERT</literal> indicates that you accept
|
|
the server’s certificate only if you trust the CA that issued the certificate.
|
|
</para></listitem>
|
|
<listitem><para><literal>LDAPSSL_AUTH_CNCHECK</literal> indicates that you
|
|
accept the server’s certificate only if you trust the CA that issued
|
|
the certificate and if the value of the <literal>cn</literal> attribute is
|
|
the DNS hostname of the server. If this option is selected, ensure that the <literal>
|
|
defhost</literal> parameter passed to <olink targetptr="bdavs">ldapssl_init</olink> consists
|
|
of only one hostname and not a list of hosts. Furthermore, the port number
|
|
must be passed via the <literal>defport</literal> parameter, and cannot be
|
|
passed via a <replaceable>host</replaceable>: <replaceable>port</replaceable> option.
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gascg"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><literal>0</literal> if successful.</para></listitem>
|
|
<listitem><para><literal>-1</literal> if unsuccessful.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="gasbo"><title>Description</title>
|
|
<para>You can call <function>ldapssl_advclientauth_init</function> to initialize
|
|
your client application for SSL and certificate-based client authentication.
|
|
This function is similar to <olink targetptr="bdavp">ldapssl_clientauth_init</olink> and
|
|
allows you to:</para>
|
|
<itemizedlist>
|
|
<listitem><para>Specify the name and path of a security module database.</para>
|
|
</listitem>
|
|
<listitem><para>Specify the method used to verify the server’s certificate.
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
<note><para>You must call <function>ldapssl_advclientauth_init</function> before
|
|
calling <olink targetptr="bdavs">ldapssl_init</olink> to connect to the server.</para>
|
|
</note>
|
|
</sect3>
|
|
<sect3 id="gasbt"><title>Example</title>
|
|
<para><olink targetptr="ldapssl-advclientauth-init-example">Example 21–54</olink> initializes
|
|
a client before connecting with a secure LDAP server.</para>
|
|
<example id="ldapssl-advclientauth-init-example"><title>Using <function>ldapssl_advclientauth_init
|
|
</function></title>
|
|
<programlisting>#include <ldap.h>
|
|
#include <ldap_ssl.h>
|
|
#include <stdio.h>
|
|
...
|
|
/* Initialize client, using mozilla’s certificate database */
|
|
if ( ldapssl_advclientauth_init( "/u/mozilla/.netscape/
|
|
<replaceable>cert_file_name</replaceable>.db",
|
|
NULL, 1, "/u/mozilla/.netscape/
|
|
<replaceable>key_file_name</replaceable>.db", NULL , 1,
|
|
"/u/mozilla/.netscape/
|
|
<replaceable>secmod_file_name</replaceable>.db", LDAPSSL_AUTH_CNCHECK) < 0 ) {
|
|
perror( "ldap_advclientauth_init" );
|
|
return( 1 );
|
|
}
|
|
}
|
|
...</programlisting>
|
|
</example>
|
|
</sect3>
|
|
<sect3 id="gasai"><title>See Also</title>
|
|
<para><olink targetptr="bdasv">ldap_init</olink>, <olink targetptr="bdaxr">prldap_init
|
|
</olink> (IPv6), <olink targetptr="bdavp">ldapssl_clientauth_init</olink>, <olink targetptr="bdavs">ldapssl_init</olink>, <olink targetptr="bdavt">ldapssl_install_routines
|
|
</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdavo"><title><function>ldapssl_client_init</function></title>
|
|
<para>The <function>ldapssl_client_init</function> function initializes the
|
|
secure parts (Security and SSL) of the runtime for use by your client application
|
|
to connect to a secure LDAP server over SSL.</para>
|
|
<sect3 id="gasbm"><title>Syntax</title>
|
|
<programlisting>#include <ldap_ssl.h>
|
|
int ldapssl_client_init( const char *certdbpath, void *certdbhandle );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gasaw"><title>Parameters</title>
|
|
<table frame="topbot" id="gasbb"><title><function>ldapssl_client_init</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>certdbpath</literal></para></entry>
|
|
<entry>
|
|
<para>Specifies the path to the database containing certificates for your
|
|
client.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>certdbhandle</literal></para></entry>
|
|
<entry>
|
|
<para>Pass a <literal>NULL</literal> value for this. (This parameter is not
|
|
used currently.)</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gasbk"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><literal>0</literal> if successful.</para></listitem>
|
|
<listitem><para><literal>-1</literal> if unsuccessful.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="gasbn"><title>Description</title>
|
|
<para>You can call the <function>ldapssl_client_init</function> function to
|
|
initialize your client application for SSL. It is only called once and returns <literal>
|
|
0</literal> if all goes well. If you plan to use certificate-based authentication,
|
|
you should call either the <olink targetptr="bdavp">ldapssl_clientauth_init</olink> or
|
|
the <olink targetptr="bdavn">ldapssl_advclientauth_init</olink> function.</para>
|
|
<note><para>You must call <function>ldapssl_client_init</function> before
|
|
calling the <olink targetptr="bdavs">ldapssl_init</olink> function to connect
|
|
to the server, or the <olink targetptr="ldap-start-tls-s">ldap_start_tls_s</olink> function
|
|
to start transport layer security.</para></note>
|
|
</sect3>
|
|
<sect3 id="gasbx"><title>Example</title>
|
|
<para><olink targetptr="ldapssl-client-init-example">Example 21–55</olink>
|
|
initializes a client before connecting with a secure LDAP server.</para>
|
|
<example id="ldapssl-client-init-example"><title>Using <function>ldapssl_client_init
|
|
</function></title>
|
|
<programlisting role="fragment">#include <ldap.h>
|
|
#include <ldap_ssl.h>
|
|
#include <stdio.h>
|
|
...
|
|
/* Initialize client using a certificate database
|
|
copied from &cnDirectoryServer;. */
|
|
if ( ldapssl_client_init( "/local/client/alias/", NULL ) < 0) {
|
|
printf( "Failed to initialize SSL client...\n" );
|
|
return( 1 );
|
|
}</programlisting>
|
|
<para>The <parameter>certdbpath</parameter> is a path to the file system directory
|
|
containing the certificate database files. For example:</para>
|
|
<screen>$ ls /local/client/alias/*.db
|
|
/local/client/alias/cert8.db
|
|
/local/client/alias/key3.db
|
|
/local/client/alias/secmod.db
|
|
$</screen>
|
|
</example>
|
|
</sect3>
|
|
<sect3 id="gasce"><title>See Also</title>
|
|
<para><olink targetptr="ldap-start-tls-s">ldap_start_tls_s</olink>, <olink targetptr="bdasv">ldap_init</olink>, <olink targetptr="bdaxr">prldap_init</olink> (IPv6), <olink targetptr="bdavs">ldapssl_init</olink>, <olink targetptr="bdavt">ldapssl_install_routines
|
|
</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdavp"><title><function>ldapssl_clientauth_init</function></title>
|
|
<para>The <function>ldapssl_clientauth_init</function> function initializes
|
|
your client application to connect to a secure LDAP server over SSL and to
|
|
use certificate-based client authentication.</para>
|
|
<sect3 id="gasag"><title>Syntax</title>
|
|
<programlisting>#include <ldap_ssl.h>
|
|
int ldapssl_clientauth_init( char *certdbpath, void *certdbhandle,
|
|
int needkeydb, char *keydbpath, void *keydbhandle );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gascb"><title>Parameters</title>
|
|
<table frame="topbot" id="gasan"><title><function>ldapssl_clientauth_init</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>certdbpath</literal></para></entry>
|
|
<entry>
|
|
<para>Specifies the path to the database containing certificates for your
|
|
client. You can include the database filename in the path (for example, <literal>
|
|
/usr/mozilla/</literal> <replaceable>cert_file_name</replaceable><literal>.db</literal>).
|
|
</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>needkeydb</literal></para></entry>
|
|
<entry>
|
|
<para>Specifies whether or not the private key database needs to be opened
|
|
for use. This parameter can have one of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para>If it is a non-zero value, the function opens the private
|
|
key database, which is identified by the keydbpath argument.</para></listitem>
|
|
<listitem><para>If <literal>0</literal>, the function does not open the private
|
|
key database.</para></listitem>
|
|
</itemizedlist>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>keydbpath</literal></para></entry>
|
|
<entry>
|
|
<para>Specifies the path to the database containing the private key certified
|
|
by your certificate. You can include the database filename in the path (for
|
|
example, /usr/mozilla/ <replaceable>key_file_name</replaceable>.db).</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>certdbhandle</literal></para></entry>
|
|
<entry>
|
|
<para>Pass a <literal>NULL</literal> value for this. (This parameter is not
|
|
currently used.)</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gasav"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><literal>0</literal> if successful.</para></listitem>
|
|
<listitem><para><literal>-1</literal> if unsuccessful.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="gasat"><title>Description</title>
|
|
<para>You can call the <function>ldapssl_clientauth_init</function> function
|
|
to initialize your client application for SSL and certificate-based client
|
|
authentication. However, if you need to specify the name and path of the security
|
|
modules database or if you need to specify how the server’s certificate
|
|
will be verified, you should call the <function>ldapssl_advclientauth_init</function> function
|
|
instead.</para>
|
|
<note><para>You must call <function>ldapssl_clientauth_init</function> before
|
|
calling <olink targetptr="bdavs">ldapssl_init</olink> to connect to the server.</para>
|
|
</note>
|
|
</sect3>
|
|
<sect3 id="gasbr"><title>Example</title>
|
|
<para><olink targetptr="ldapssl-clientauth-init-example">Example 21–56</olink>
|
|
initializes a client before connecting with a secure LDAP server.</para>
|
|
<example id="ldapssl-clientauth-init-example"><title>Using <function>ldapssl_clientauth_init
|
|
</function></title>
|
|
<programlisting>#include <ldap.h>
|
|
#include <ldap_ssl.h>
|
|
#include <stdio.h>
|
|
...
|
|
/* Initialize client, using mozilla’s certificate database */
|
|
if ( ldapssl_clientauth_init( "/u/mozilla/.netscape/
|
|
<replaceable>cert_file_name</replaceable>.db", NULL, 1,
|
|
"/u/mozilla/.netscape/
|
|
<replaceable>key_file_name</replaceable>.db", NULL ) < 0 ) {
|
|
perror( "ldap_clientauth_init" );
|
|
return( 1 );
|
|
}
|
|
}
|
|
...</programlisting>
|
|
</example>
|
|
</sect3>
|
|
<sect3 id="gasbq"><title>See Also</title>
|
|
<para><olink targetptr="bdasv">ldap_init</olink>, <olink targetptr="bdaxr">prldap_init
|
|
</olink> (IPv6), <olink targetptr="bdavs">ldapssl_init</olink>, <olink targetptr="bdavt">ldapssl_install_routines</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdavq"><title><function>ldapssl_enable_clientauth</function></title>
|
|
<para>The <function>ldapssl_enable_clientauth</function> function enables
|
|
SSL client authentication on the given connection (passed using the <literal>ld</literal> parameter).
|
|
</para>
|
|
<sect3 id="gasbg"><title>Syntax</title>
|
|
<programlisting>#include <ldap_ssl.h>
|
|
int ldapssl_enable_clientauth( LDAP *ld, char *keynickname,
|
|
char *keypasswd, char *certnickname );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gasbl"><title>Parameters</title>
|
|
<table frame="topbot" id="gasbv"><title><function>ldapssl_enable_clientauth</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>keynickname</literal></para></entry>
|
|
<entry>
|
|
<para>Pass an empty string, <literal>""</literal>, for this value. (This parameter
|
|
is not currently used.)</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>keypasswd</literal></para></entry>
|
|
<entry>
|
|
<para>Password to the encrypted private key database.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>certnickname</literal></para></entry>
|
|
<entry>
|
|
<para>Nickname of the certificate that you want to use for client authentication.
|
|
</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gasbd"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><literal>0</literal> if successful.</para></listitem>
|
|
<listitem><para><literal>-1</literal> if unsuccessful.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="gasao"><title>See Also</title>
|
|
<para><olink targetptr="bdavp">ldapssl_clientauth_init</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdavr"><title><function>ldapssl_err2string</function></title>
|
|
<para>The <function>ldapssl_err2string</function> function returns the corresponding
|
|
error message for an SSL-specific error code.</para>
|
|
<sect3 id="gasbw"><title>Syntax</title>
|
|
<programlisting>#include <ldap_ssl.h>
|
|
const char * LDAP_CALL ldapssl_err2string ( const int prerrno );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gasam"><title>Parameters</title>
|
|
<table frame="topbot" id="gasef"><title><function>ldapssl_err2string</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>prerrno</literal></para></entry>
|
|
<entry>
|
|
<para>The SSL error code that you want interpreted into an error message.</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gascj"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para>If successful, returns the corresponding error message for
|
|
the given error code.</para></listitem>
|
|
<listitem><para>If unsuccessful (for example, if the error code is not a known
|
|
SSL error code), returns a pointer to the string <literal>Unknown error.</literal></para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="gasck"><title>Description</title>
|
|
<para><function>ldapssl_err2string</function> provides support for SSL-specific
|
|
error messages that are not covered by the regular message routine <olink targetptr="bdarq">ldap_err2string</olink>. If any <function>ldapssl_*</function> function
|
|
returns an error code that is unknown to <olink targetptr="bdarq">ldap_err2string
|
|
</olink>–it returns <literal>Unknown error</literal>– this function
|
|
should be called to determine the SSL-specific error message. To check for
|
|
SSL errors, call <function>ldapssl_err2string</function> after you call any
|
|
of the following SSL initialization functions:</para>
|
|
<itemizedlist>
|
|
<listitem><para><olink targetptr="bdavo">ldapssl_client_init</olink></para>
|
|
</listitem>
|
|
<listitem><para><olink targetptr="bdavp">ldapssl_clientauth_init</olink></para>
|
|
</listitem>
|
|
<listitem><para><olink targetptr="bdavn">ldapssl_advclientauth_init</olink></para>
|
|
</listitem>
|
|
<listitem><para><olink targetptr="bdavu">ldapssl_pkcs_init</olink></para><para>The
|
|
errors returned by these functions are usually related to certificate database
|
|
corruption, missing certificates in a certificate database, client authentication
|
|
failures, and other general SSL errors.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="gasdg"><title>See Also</title>
|
|
<para><olink targetptr="bdavo">ldapssl_client_init</olink>, <olink targetptr="bdavp">ldapssl_clientauth_init</olink>, <olink targetptr="bdavn">ldapssl_advclientauth_init
|
|
</olink>, <olink targetptr="bdavu">ldapssl_pkcs_init</olink>, <olink targetptr="bdarq">ldap_err2string</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdavs"><title><function>ldapssl_init</function></title>
|
|
<para>The <function>ldapssl_init</function> function initializes the LDAP
|
|
library for SSL and installs the I/O routines for SSL.</para>
|
|
<sect3 id="gasdy"><title>Syntax</title>
|
|
<programlisting>#include <ldap_ssl.h>
|
|
LDAP *ldapssl_init( const char *defhost, int defport, int defsecure );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gascv"><title>Parameters</title>
|
|
<table frame="topbot" id="gascs"><title><function>ldapssl_init</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>defhost</literal></para></entry>
|
|
<entry>
|
|
<para>Connect to this LDAP server, if no other server is specified.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>defport</literal></para></entry>
|
|
<entry>
|
|
<para>Connect to this server port, if no other port is specified. To specify
|
|
the default port 389, use <literal>LDAP_PORT</literal> as the value for this
|
|
parameter.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>defsecure</literal></para></entry>
|
|
<entry>
|
|
<para>Determines whether or not to establish the default connection over SSL.
|
|
Set this to a non-zero value to establish the default connection over SSL.</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gascy"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para>If successful, returns a pointer to an <olink targetptr="bdakj">LDAP
|
|
</olink> structure, which should be passed to subsequent calls to other LDAP
|
|
API functions.</para></listitem>
|
|
<listitem><para>If unsuccessful, returns <returnvalue>-1</returnvalue>.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="gascx"><title>Description</title>
|
|
<para><function>ldapssl_init</function> allocates an <olink targetptr="bdakj">LDAP
|
|
</olink> structure but does not open an initial connection. Before calling
|
|
this function, call <olink targetptr="bdavo">ldapssl_client_init</olink> to
|
|
initialize your client for SSL.</para>
|
|
<note><para>Calling this function is equivalent to calling <olink targetptr="bdasv">ldap_init</olink> or <olink targetptr="bdaxr">prldap_init</olink> (IPv6)
|
|
followed by <olink targetptr="bdavt">ldapssl_install_routines</olink> and <olink targetptr="bdavg">ldap_set_option</olink> to set the <literal>LDAP_OPT_SSL</literal> option
|
|
to <literal>LDAP_OPT_ON</literal>.</para></note>
|
|
</sect3>
|
|
<sect3 id="gasds"><title>Example</title>
|
|
<para><olink targetptr="ldapssl-init-example">Example 21–57</olink> connects
|
|
your client to a secure LDAP server.</para>
|
|
<example id="ldapssl-init-example"><title>Using <function>ldapssl_init</function></title>
|
|
<programlisting>#include <ldap.h>
|
|
#include <ldap_ssl.h>
|
|
#include <stdio.h>
|
|
...
|
|
/* Initialize client, using mozilla’s certificate database */
|
|
if ( ldapssl_client_init( "/u/mozilla/.netscape/
|
|
<replaceable>cert_file_name</replaceable>.db", NULL ) < 0) {
|
|
printf( "Failed to initialize SSL client...\n" );
|
|
return( 1 );
|
|
}
|
|
/* get a handle to an LDAP connection */
|
|
if ( (ld = ldapssl_init( "cert.example.com", LDAPS_PORT, 1 )) == NULL {
|
|
perror( "ldapssl_init" );
|
|
return( 1 );
|
|
}
|
|
...
|
|
/* Client can now perform LDAP operations on the secure LDAP server */
|
|
...</programlisting>
|
|
</example>
|
|
</sect3>
|
|
<sect3 id="gasdm"><title>See Also</title>
|
|
<para><olink targetptr="bdasv">ldap_init</olink>, <olink targetptr="bdaxr">prldap_init
|
|
</olink> (IPv6), <olink targetptr="bdavo">ldapssl_client_init</olink>, <olink targetptr="bdavt">ldapssl_install_routines</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdavt"><title><function>ldapssl_install_routines</function></title>
|
|
<para>The <function>ldapssl_install_routines</function> function installs
|
|
the I/O routines that enable SSL over LDAP.</para>
|
|
<sect3 id="gasdq"><title>Syntax</title>
|
|
<programlisting>#include <ldap_ssl.h>
|
|
int ldapssl_install_routines( LDAP *ld );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gascu"><title>Parameters</title>
|
|
<table frame="topbot" id="gasdc"><title><function>ldapssl_install_routines</function> Function
|
|
Parameter</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gascm"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><literal>0</literal> if successful.</para></listitem>
|
|
<listitem><para><literal>-1</literal> if unsuccessful.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="gascz"><title>Description</title>
|
|
<para>You need to call <function>ldapssl_install_routines</function> in combination
|
|
with <olink targetptr="bdasv">ldap_init</olink> or <olink targetptr="bdaxr">prldap_init
|
|
</olink> (IPv6) and <olink targetptr="bdavg">ldap_set_option</olink>. As an
|
|
alternative, you can call <olink targetptr="bdavs">ldapssl_init</olink> rather
|
|
than these three functions.</para>
|
|
<note><para>As is the case with the <olink targetptr="bdavs">ldapssl_init</olink> function,
|
|
you need to call <olink targetptr="bdavo">ldapssl_client_init</olink> to initialize
|
|
your client for SSL before calling <function>ldapssl_install_routines</function>.
|
|
</para></note>
|
|
</sect3>
|
|
<sect3 id="gasdh"><title>Example</title>
|
|
<para><olink targetptr="ldapssl-install-routines-example-example">Example
|
|
21–58</olink> connects your client to a secure LDAP server.</para>
|
|
<example id="ldapssl-install-routines-example-example"><title>Using <function>ldapssl_install_routines
|
|
</function></title>
|
|
<programlisting>#include <ldap.h>
|
|
#include <ldap_ssl.h>
|
|
#include <stdio.h>
|
|
...
|
|
/* Initialize client, using mozilla’s certificate database */
|
|
if ( ldapssl_client_init( "/u/mozilla/.netscape/
|
|
<replaceable>cert_file_name</replaceable>.db", NULL ) < 0) {
|
|
printf( "Failed to initialize SSL client...\n" );
|
|
return( 1 );
|
|
}
|
|
/* Get the handle to an LDAP connection. Use prldap_init() for IPv6. */
|
|
if ( (ld = ldap_init( MY_HOST, 636 )) == NULL ) {
|
|
perror( "ldap_init" );
|
|
return( 1 );
|
|
}
|
|
|
|
/* Load SSL routines */
|
|
if ( ldapssl_install_routines( ld ) != LDAP_SUCCESS ) {
|
|
ldap_perror( ld, "ldapssl_install_routines" );
|
|
return( 1 );
|
|
}
|
|
|
|
/* Set the option to use SSL with the default connection */
|
|
if (ldap_set_option( ld, LDAP_OPT_SSL, LDAP_OPT_ON ) != LDAP_SUCCESS) {
|
|
ldap_perror( ld, "ldap_set_option" );
|
|
return( 1 );
|
|
}
|
|
...</programlisting>
|
|
</example>
|
|
</sect3>
|
|
<sect3 id="gaseb"><title>See Also</title>
|
|
<para><olink targetptr="bdasv">ldap_init</olink>, <olink targetptr="bdaxr">prldap_init
|
|
</olink> (IPv6), <olink targetptr="bdavs">ldapssl_init</olink>, <olink targetptr="bdavo">ldapssl_client_init</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdavu"><title><function>ldapssl_pkcs_init</function></title>
|
|
<note><para>This function is deprecated and should not be used. It is included
|
|
in <literal>ldap-deprecated.h</literal> for backward-compatibility.</para>
|
|
</note>
|
|
<para>The <function>ldap_pcks_init</function> function provides thread-safe
|
|
SSL initialization.</para>
|
|
<sect3><title>Syntax</title>
|
|
<programlisting>int ldapssl_pkcs_init( const struct ldapssl_pkcs_fns *pfns);</programlisting>
|
|
</sect3>
|
|
<sect3 id="gasdp"><title>Description</title>
|
|
<para>The <function>ldap_pkcs_init</function> structure sets up callbacks
|
|
for the security library to obtain required runtime information. It should
|
|
be used in place of <olink targetptr="bdavo">ldapssl_client_init</olink>, <olink targetptr="bdavp">ldapssl_clientauth_init</olink>, and <olink targetptr="bdavn">ldapssl_advclientauth_init
|
|
</olink>.</para>
|
|
<note><para>The &DirectorySDKForC; uses the Public Key Cryptography Standard
|
|
(PKCS) API implemented in Network Security Services (NSS) to provide SSL security
|
|
support. Specifically, NSS implements the security API as defined in the PKCS#11
|
|
standard.</para></note>
|
|
<para>Because <function>ldap_pkcs_init</function> is based on the <literal>ldapssl_pkcs_fns
|
|
</literal> structure, you do not need to know all of the security parameters
|
|
at initialization, unlike the other SSL initialization functions (<function>ldapssl_*_init
|
|
</function>), which require all security parameters to be known at the time
|
|
of initialization. <olink targetptr="ldapssl-pkcs-fns-example">Example 21–59
|
|
</olink> defines the <literal>ldapssl_pkcs_fns</literal> structure.</para>
|
|
<example id="ldapssl-pkcs-fns-example"><title><structname>ldapssl_pkcs_fns</structname> Structure
|
|
Definition</title>
|
|
<programlisting>typedef int (LDAP_PKCS_GET_TOKEN_CALLBACK)
|
|
(void *context, char **tokenname);
|
|
typedef int (LDAP_PKCS_GET_PIN_CALLBACK)
|
|
(void *context, const char *tokenname, char **tokenpin);
|
|
typedef int (LDAP_PKCS_GET_CERTPATH_CALLBACK)
|
|
(void *context, char **certpath);
|
|
typedef int (LDAP_PKCS_GET_KEYPATH_CALLBACK)(void *context,
|
|
char **keypath);
|
|
typedef int (LDAP_PKCS_GET_MODPATH_CALLBACK)
|
|
(void *context, char **modulepath);
|
|
typedef int (LDAP_PKCS_GET_CERTNAME_CALLBACK)
|
|
(void *context, char **certname);
|
|
typedef int (LDAP_PKCS_GET_DONGLEFILENAME_CALLBACK)
|
|
(void *context, char **filename);
|
|
|
|
#define PKCS_STRUCTURE_ID 1
|
|
struct ldapssl_pkcs_fns {
|
|
int local_structure_id;
|
|
void *local_data;
|
|
LDAP_PKCS_GET_CERTPATH_CALLBACK *pkcs_getcertpath;
|
|
LDAP_PKCS_GET_CERTNAME_CALLBACK *pkcs_getcertname;
|
|
LDAP_PKCS_GET_KEYPATH_CALLBACK *pkcs_getkeypath;
|
|
LDAP_PKCS_GET_MODPATH_CALLBACK *pkcs_getmodpath;
|
|
LDAP_PKCS_GET_PIN_CALLBACK *pkcs_getpin;
|
|
LDAP_PKCS_GET_TOKEN_CALLBACK *pkcs_gettokenname;
|
|
LDAP_PKCS_GET_DONGLEFILENAME_CALLBACK *pkcs_getdonglefilename;
|
|
};</programlisting>
|
|
</example>
|
|
</sect3>
|
|
<sect3><title>Parameters</title>
|
|
<table frame="topbot"><title><function>ldapssl_pkcs_init</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>pfns</literal></para></entry>
|
|
<entry>
|
|
<para>Specifies the <literal>ldap_pkcs_fns</literal> structure for initialization.
|
|
</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gasdt"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para>0 is successful.</para></listitem>
|
|
<listitem><para>-1 if unsuccessful.</para></listitem>
|
|
<listitem><para><replaceable>n</replaceable> (a positive integer) denotes
|
|
a Netscape Portable Runtime (NSPR) error as returned by the <function>PR_GetError
|
|
</function> NSPR function.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="gasdi"><title>See Also</title>
|
|
<para><olink targetptr="bdavo">ldapssl_client_init</olink>, <olink targetptr="bdavp">ldapssl_clientauth_init</olink>, <olink targetptr="bdavn">ldapssl_advclientauth_init
|
|
</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdavv"><title><function>ldapssl_serverauth_init</function></title>
|
|
<para>The <function>ldapssl_serverauth_init</function> function is a server-authentication
|
|
only version of <olink targetptr="bdavp">ldapssl_clientauth_init</olink>.</para>
|
|
<sect3 id="gascp"><title>Syntax</title>
|
|
<programlisting>#include <ldap_ssl.h>
|
|
int ldapssl_serverauth_init(
|
|
const char *certdbpath, void *certdbhandle, const int sslstrength );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gasdj"><title>Parameters</title>
|
|
<note><para>Please see the description of the <literal>sslstrength</literal> value
|
|
and note the potential problems that can be caused by passing in wrong host
|
|
and port name values.</para></note>
|
|
<table frame="topbot" id="gascn"><title><function>ldapssl_serverauth_init</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>certdbpath</literal></para></entry>
|
|
<entry>
|
|
<para>Specifies the path to the database containing certificates for your
|
|
client. You can include the database filename in the path (for example, /usr/mozilla/cert_file_name.db).
|
|
</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>certdbhandle</literal></para></entry>
|
|
<entry>
|
|
<para>Pass a <literal>NULL</literal> value for this. (This parameter is not
|
|
currently used.)</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>sslstrength</literal></para></entry>
|
|
<entry>
|
|
<para>Specifies how the server certificate is evaluated. It takes one of the
|
|
following:</para>
|
|
<itemizedlist>
|
|
<listitem><para><literal>LDAPSSL_AUTH_WEAK</literal> indicates that you accept
|
|
the server’s certificate without checking the for certificate authority
|
|
(CA) that issued the certificate.</para></listitem>
|
|
<listitem><para><literal>LDAPSSL_AUTH_CERT</literal> indicates that you accept
|
|
the server’s certificate only if you trust the CA that issued the certificate.
|
|
</para></listitem>
|
|
<listitem><para><literal>LDAPSSL_AUTH_CNCHECK</literal> indicates that you
|
|
accept the server’s certificate only if you trust the CA that issued
|
|
the certificate and if the value of the <literal>cn</literal> attribute is
|
|
the DNS hostname of the server. If this option is selected, please ensure
|
|
that the <literal>defhost</literal> parameter passed to <olink targetptr="bdavs">
|
|
ldapssl_init</olink> consists of only one hostname and not a list of hosts.
|
|
Furthermore, the port number must be passed via the <literal>defport</literal> parameter,
|
|
and cannot be passed via a <replaceable>host</replaceable>: <replaceable>port</replaceable> option.
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gaseg"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><literal>0</literal> if successful.</para></listitem>
|
|
<listitem><para><literal>-1</literal> if unsuccessful.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="gasdw"><title>Description</title>
|
|
<para><function>ldapssl_serverauth_init</function> is a server-authentication
|
|
only version of <olink targetptr="bdavp">ldapssl_clientauth_init</olink>.
|
|
This function allows the <literal>sslstrength</literal> parameter to be passed
|
|
in.</para></sect3>
|
|
<sect3 id="gasde"><title>See Also</title>
|
|
<para><olink targetptr="bdasv">ldap_init</olink>, <olink targetptr="bdaxr">prldap_init
|
|
</olink> (IPv6), <olink targetptr="bdavs">ldapssl_init</olink>, <olink targetptr="bdavt">ldapssl_install_routines</olink>, <olink targetptr="bdavp">ldapssl_clientauth_init
|
|
</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdavw"><title><function>ldapssl_set_strength</function></title>
|
|
<para>The <function>ldapssl_set_strength</function> sets the SSL strength
|
|
for an existing SSL-enabled LDAP session handle.</para>
|
|
<sect3 id="gasdo"><title>Syntax</title>
|
|
<programlisting>#include <ldap_ssl.h>
|
|
int LDAP_CALL ldapssl_set_strength( LDAP *ld, int sslstrength );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gascl"><title>Parameters</title>
|
|
<note><para>See the description of the <literal>sslstrength</literal> value
|
|
and note the potential problems that can be caused by passing in wrong host
|
|
and port name values.</para></note>
|
|
<table frame="topbot" id="gasee"><title><function>ldapssl_set_strength</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server. If value is <literal>NULL</literal>,
|
|
the default for the new LDAP session handles is set.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>sslstrength</literal></para></entry>
|
|
<entry>
|
|
<para>Specifies how the server certificate is evaluated. It takes one of the
|
|
following:</para>
|
|
<itemizedlist>
|
|
<listitem><para><literal>LDAPSSL_AUTH_WEAK</literal> indicates that you accept
|
|
the server’s certificate without checking the for certificate authority
|
|
(CA) that issued the certificate.</para></listitem>
|
|
<listitem><para><literal>LDAPSSL_AUTH_CERT</literal> indicates that you accept
|
|
the server’s certificate only if you trust the CA that issued the certificate.
|
|
</para></listitem>
|
|
<listitem><para><literal>LDAPSSL_AUTH_CNCHECK</literal> indicates that you
|
|
accept the server’s certificate only if you trust the CA that issued
|
|
the certificate and if the value of the <literal>cn</literal> attribute is
|
|
the DNS hostname of the server. If this option is selected, please ensure
|
|
that the <literal>defhost</literal> parameter passed to <olink targetptr="bdavs">
|
|
ldapssl_init</olink> consists of only one hostname and not a list of hosts.
|
|
Furthermore, the port number must be passed via the <literal>defport</literal> parameter,
|
|
and cannot be passed via a <replaceable>host</replaceable>: <replaceable>port</replaceable> option.
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="bdavx"><title><function>ldapssl_tls_start_s</function></title>
|
|
<para>The <function>ldapssl_tls_start_s</function> function starts an SSL
|
|
handshake on a previously established non-secure connection.</para>
|
|
<sect3 id="gasdk"><title>Syntax</title>
|
|
<programlisting>#include <ldap_ssl.h>
|
|
LDAP_API(int) LDAP_CALL ldapssl_tls_start_s( LDAP *ld, int defsecure,
|
|
char *certdbpath, char *keydbpath, char ***referralsp );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gasec"><title>Parameters</title>
|
|
<table frame="topbot" id="gasdv"><title><function>ldapssl_tls_start_s</function> Function
|
|
Parameter</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>defsecure</literal></para></entry>
|
|
<entry>
|
|
<para>Determines whether or not to establish the default connection over SSL.
|
|
Set this to a non-zero value to establish the default connection over SSL.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>certdbpath</literal></para></entry>
|
|
<entry>
|
|
<para>Specifies the path to the database containing certificates for your
|
|
client. You can include the database filename in the path (for example, /usr/mozilla/cert_file_name.db).
|
|
</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>keydbpath</literal></para></entry>
|
|
<entry>
|
|
<para>Specifies the path to the database containing the private key certified
|
|
by your certificate. You can include the database filename in the path (for
|
|
example, <literal>/usr/mozilla/</literal><replaceable>key_file_name</replaceable><literal>
|
|
.db</literal>).</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>referralsp</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an array of strings representing the referrals found by an
|
|
LDAP search operation and returned by the server (applicable only if the LDAP
|
|
operation was a search operation). When done, you can free this by calling
|
|
the <function>ldap_value_free</function> function.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gasea"><title>Description</title>
|
|
<para>The <function>ldapssl_tls_start_s</function> function starts an SSL
|
|
handshake on a previously established non-secure connection.</para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdavy"><title><function>ldap_str2charray</function></title>
|
|
<indexterm>
|
|
<primary>C SDK functions</primary>
|
|
<secondary><function>ldap_str2charray</function></secondary>
|
|
</indexterm><indexterm>
|
|
<primary><function>ldap_str2charray</function></primary>
|
|
</indexterm>
|
|
<para>This function is deprecated and should not be used. It is included in
|
|
<literal>ldap-deprecated.h</literal> for backward-compatibility.</para>
|
|
<sect3 id="bdavz"><title><function>ldap_tmplattrs</function></title>
|
|
<indexterm>
|
|
<primary>C SDK functions</primary>
|
|
<secondary><function>ldap_tmplattrs</function></secondary>
|
|
</indexterm><indexterm>
|
|
<primary><function>ldap_tmplattrs</function></primary>
|
|
</indexterm>
|
|
<para>The <function>ldap_tmplattrs</function> function obtains a pointer to
|
|
the correct <literal>ldap_disptmpl</literal> structure.</para></sect3>
|
|
<sect3 id="gased"><title>Syntax</title>
|
|
<programlisting>#include <disptmpl.h>
|
|
char ** ldap_tmplattrs( struct ldap_disptmpl *tmpl, char **includeattrs,
|
|
int exclude, unsigned long syntaxmask );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gasci"><title>Parameters</title>
|
|
<table frame="topbot" id="gasdd"><title><function>ldap_tmplattrs</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>tmpl</literal></para></entry>
|
|
<entry>
|
|
<para>The name of the template to be retrieved.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>includeattrs</literal></para></entry>
|
|
<entry>
|
|
<para>A null terminated array of attributes that should always be included
|
|
(it may be <literal>NULL</literal> if no extra attributes are required).</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>exclude</literal></para></entry>
|
|
<entry>
|
|
<para>If <literal>0</literal>, only attributes where the logical AND of the
|
|
template item syntax id and the <parameter>syntaxmask</parameter> is non-zero
|
|
are included. If non-zero, attributes where the logical AND of the template
|
|
item syntax id and the <parameter>syntaxmask</parameter> is non-zero are excluded.
|
|
</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>syntaxmask</literal></para></entry>
|
|
<entry>
|
|
<para>When non-zero, it is used to restrict the attribute set returned.</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gasdz"><title>Returns</title>
|
|
<itemizedlist>
|
|
<listitem><para><literal>A NULL</literal> terminated array that contains the
|
|
names of attributes that need to be retrieved if the template, defined by <literal>
|
|
tmpl</literal> , is to be used to display an entry.</para></listitem>
|
|
<listitem><para>A <literal>NULL</literal> pointer on error.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="gasdl"><title>Description</title>
|
|
<para>The attribute list should be freed using <olink targetptr="bdaxc">ldap_value_free
|
|
</olink> .</para></sect3>
|
|
<sect3 id="gasdx"><title>See Also</title>
|
|
<para><olink targetptr="bdaxc">ldap_value_free</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdawa"><title><function>ldap_tmplerr2string</function></title>
|
|
<indexterm>
|
|
<primary>C SDK functions</primary>
|
|
<secondary><function>ldap_tmplerr2string</function></secondary>
|
|
</indexterm><indexterm>
|
|
<primary><function>ldap_tmplerr2string</function></primary>
|
|
</indexterm>
|
|
<para>The <function>ldap_templerr2string</function> function returns a string
|
|
representation of the error passed in the parameter.</para>
|
|
<sect3 id="gasch"><title>Syntax</title>
|
|
<programlisting>#include <disptmpl.h>
|
|
char * ldap_tmplerr2string( int err );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gasdf"><title>Parameters</title>
|
|
<table frame="topbot" id="gaseh"><title><function>ldap_tmplerr2string</function> Function
|
|
Parameter</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>err</literal></para></entry>
|
|
<entry>
|
|
<para>Error returned.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="bdawb"><title><function>ldap_ufn_search_c</function></title>
|
|
<indexterm>
|
|
<primary>C SDK functions</primary>
|
|
<secondary><function>ldap_ufn_*</function></secondary>
|
|
</indexterm><indexterm>
|
|
<primary><function>ldap_ufn_*</function></primary>
|
|
</indexterm>
|
|
<note><para>This function will be deprecated and should not be used. It is
|
|
included in <literal>ldap-to-be-deprecated.h</literal> for backward-compatibility.
|
|
</para></note>
|
|
<sect3 id="bdawc"><title><function>ldap_ufn_search_ct</function></title>
|
|
<note><para>This function will be deprecated and should not be used. It is
|
|
included in <literal>ldap-to-be-deprecated.h</literal> for backward-compatibility.
|
|
</para></note>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="bdawd"><title><function>ldap_ufn_search_s</function></title>
|
|
<note><para>This function will be deprecated and should not be used. It is
|
|
included in <literal>ldap-to-be-deprecated.h</literal> for backward-compatibility.
|
|
</para></note>
|
|
<sect3 id="bdawe"><title><function>ldap_ufn_setfilter</function></title>
|
|
<note><para>This function will be deprecated and should not be used. It is
|
|
included in <literal>ldap-to-be-deprecated.h</literal> for backward-compatibility.
|
|
</para></note>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="bdawf"><title><function>ldap_ufn_setprefix</function></title>
|
|
<note><para>This function will be deprecated and should not be used. It is
|
|
included in <literal>ldap-to-be-deprecated.h</literal> for backward-compatibility.
|
|
</para></note>
|
|
<sect3 id="bdawg"><title><function>ldap_ufn_timeout</function></title>
|
|
<note><para>This function will be deprecated and should not be used. It is
|
|
included in <literal>ldap-to-be-deprecated.h</literal> for backward-compatibility.
|
|
</para></note>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="bdawh"><title><function>ldap_unbind</function></title>
|
|
<indexterm>
|
|
<primary>C SDK functions</primary>
|
|
<secondary><function>ldap_unbind</function></secondary>
|
|
</indexterm><indexterm>
|
|
<primary><function>ldap_unbind</function></primary>
|
|
</indexterm>
|
|
<para>The <function>ldap_unbind</function> function unbinds from the directory,
|
|
terminates the current association, and frees the resources contained in the
|
|
<olink targetptr="bdakj">LDAP</olink> structure.</para>
|
|
<sect3 id="gasco"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_unbind( LDAP *ld );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gasda"><title>Parameters</title>
|
|
<table frame="topbot" id="gascr"><title><function>ldap_unbind</function> Function
|
|
Parameter</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gascw"><title>Returns</title>
|
|
<para>For a list of possible results for an LDAP unbind operation, see <olink targetptr="bdawi">ldap_unbind_s</olink>.</para></sect3>
|
|
<sect3 id="gascq"><title>Description</title>
|
|
<para>The <function>ldap_unbind</function> function unbinds from the directory,
|
|
terminates the current association, and frees the resources contained in the
|
|
<olink targetptr="bdakj">LDAP</olink> structure. The three unbind functions
|
|
(<olink targetptr="bdawh">ldap_unbind</olink> , <olink targetptr="bdawi">ldap_unbind_s
|
|
</olink>, and <olink targetptr="bdawj">ldap_unbind_ext</olink>) all work
|
|
synchronously in the sense that they send an unbind request to the server,
|
|
close all open connections associated with the LDAP session handle, and dispose
|
|
of all resources associated with the session handle before returning.</para>
|
|
<note><para>There is no server response to an LDAP unbind operation. All three
|
|
of the unbind functions return <errorcode>LDAP_SUCCESS</errorcode> (or another
|
|
LDAP error code if the request cannot be sent to the LDAP server). After a
|
|
call to one of the unbind functions, the session handle <literal>ld</literal> is
|
|
invalid and it is illegal to make any further calls using it.</para></note>
|
|
</sect3>
|
|
<sect3 id="gasdb"><title>Example</title>
|
|
<para><olink targetptr="ldap-unbind-example">Example 21–60</olink> closes
|
|
the current connection with the LDAP server.</para>
|
|
<example id="ldap-unbind-example"><title>Using <function>ldap_unbind</function></title>
|
|
<programlisting>#include <ldap.h>
|
|
...
|
|
LDAP *ld;
|
|
...
|
|
/* After completing your LDAP operations with the server, close the
|
|
connection. */
|
|
if ( ldap_unbind( ld ) != LDAP_SUCCESS ) {
|
|
ldap_perror( ld, "Error while unbinding from the directory" );
|
|
return( 1 );
|
|
}
|
|
...</programlisting>
|
|
</example>
|
|
</sect3>
|
|
<sect3 id="gasct"><title>See Also</title>
|
|
<para><olink targetptr="bdawi">ldap_unbind_s</olink>, <olink targetptr="bdawj">ldap_unbind_ext
|
|
</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdawi"><title><function>ldap_unbind_s</function></title>
|
|
<indexterm>
|
|
<primary>C SDK functions</primary>
|
|
<secondary><function>ldap_unbind_s</function></secondary>
|
|
</indexterm><indexterm>
|
|
<primary><function>ldap_unbind_s</function></primary>
|
|
</indexterm>
|
|
<para>The <function>ldap_unbind_s</function> function unbinds from the directory,
|
|
terminates the current association, and frees the resources contained in the <olink targetptr="bdakj">LDAP</olink> structure.</para>
|
|
<sect3 id="gasdn"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_unbind_s( LDAP *ld );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gasdr"><title>Parameters</title>
|
|
<table frame="topbot" id="gasdu"><title><function>ldap_unbind_s</function> Function
|
|
Parameter</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gasgg"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_ENCODING_ERROR</errorcode> if an error occurred
|
|
when BER-encoding the request.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_SERVER_DOWN</errorcode> if the LDAP server
|
|
did not receive the request or if the connection to the server was lost.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
|
|
allocated.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="gasfd"><title>Description</title>
|
|
<para>The <function>ldap_unbind_s</function> function unbinds from the directory,
|
|
terminates the current association, and frees the resources contained in the <olink targetptr="bdakj">LDAP</olink> structure. The three unbind functions ( <olink targetptr="bdawh">ldap_unbind</olink>, <olink targetptr="bdawi">ldap_unbind_s</olink>,
|
|
and <olink targetptr="bdawj">ldap_unbind_ext</olink>) all work synchronously
|
|
in the sense that they send an unbind request to the server, close all open
|
|
connections associated with the LDAP session handle, and dispose of all resources
|
|
associated with the session handle before returning.</para>
|
|
<note><para>There is no server response to an LDAP unbind operation. All three
|
|
of the unbind functions return <errorcode>LDAP_SUCCESS</errorcode> (or another
|
|
LDAP error code if the request cannot be sent to the LDAP server). After a
|
|
call to one of the unbind functions, the session handle <literal>ld</literal> is
|
|
invalid and it is illegal to make any further calls using it.</para></note>
|
|
</sect3>
|
|
<sect3 id="gasga"><title>Example</title>
|
|
<para><olink targetptr="ldap-unbind-s-example">Example 21–61</olink> closes
|
|
the current connection with the LDAP server.</para>
|
|
<example id="ldap-unbind-s-example"><title>Using <function>ldap_unbind_s</function></title>
|
|
<programlisting>#include <ldap.h>
|
|
...
|
|
LDAP *ld;
|
|
...
|
|
/* After completing your LDAP operations with the server, close the
|
|
connection. */
|
|
if ( ldap_unbind_s( ld ) != LDAP_SUCCESS ) {
|
|
ldap_perror( ld, "Error while unbinding from the directory" );
|
|
return( 1 );
|
|
}
|
|
...</programlisting>
|
|
</example>
|
|
</sect3>
|
|
<sect3 id="gasej"><title>See Also</title>
|
|
<para><olink targetptr="bdawh">ldap_unbind</olink>, <olink targetptr="bdawj">ldap_unbind_ext
|
|
</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdawj"><title><function>ldap_unbind_ext</function></title>
|
|
<indexterm>
|
|
<primary>C SDK functions</primary>
|
|
<secondary><function>ldap_unbind_ext</function></secondary>
|
|
</indexterm><indexterm>
|
|
<primary><function>ldap_unbind_ext</function></primary>
|
|
</indexterm>
|
|
<para>The <function>ldap_unbind_ext</function> function unbinds from the directory,
|
|
terminates the current association, and frees the resources contained in the <olink targetptr="bdakj">LDAP</olink> structure.</para>
|
|
<sect3 id="gasew"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_unbind_ext( LDAP *ld, LDAPControl **serverctrls,
|
|
LDAPControl **clientctrls );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gaset"><title>Parameters</title>
|
|
<table frame="topbot" id="gasfa"><title><function>ldap_unbind_ext</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>serverctrls</literal></para></entry>
|
|
<entry>
|
|
<para>List of LDAP server controls.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>clientctrls</literal></para></entry>
|
|
<entry>
|
|
<para>List of client controls.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gasgh"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_ENCODING_ERROR</errorcode> if an error occurred
|
|
when BER-encoding the request.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_SERVER_DOWN</errorcode> if the LDAP server
|
|
did not receive the request or if the connection to the server was lost.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
|
|
allocated.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_NOT_SUPPORTED</errorcode> if controls are
|
|
included in your request (for example, as a session preference) and your LDAP
|
|
client does not specify that it is using the LDAP v3. Make sure that you set
|
|
the version of your LDAP client to version 3 before calling this function.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="gasfi"><title>Description</title>
|
|
<para>The <function>ldap_unbind_ext</function> function unbinds from the directory,
|
|
terminates the current association, and frees the resources contained in the <olink targetptr="bdakj">LDAP</olink> structure. The three unbind functions (<olink targetptr="bdawh">ldap_unbind</olink>, <olink targetptr="bdawi">ldap_unbind_s</olink>,
|
|
and <olink targetptr="bdawj">ldap_unbind_ext</olink>) all work synchronously
|
|
in the sense that they send an unbind request to the server, close all open
|
|
connections associated with the LDAP session handle, and dispose of all resources
|
|
associated with the session handle before returning.</para>
|
|
<note><para>Unlike the other two unbind functions, <function>ldap_unbind_ext</function> allows
|
|
you to explicitly include both server and client controls in your unbind request.
|
|
However, since there is no server response to an unbind request, there is
|
|
no way to receive a response from a server control that is included.</para>
|
|
</note>
|
|
</sect3>
|
|
<sect3 id="gasff"><title>See Also</title>
|
|
<para><olink targetptr="bdawh">ldap_unbind</olink>, <olink targetptr="bdawi">ldap_unbind_s
|
|
</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdawk"><title><function>ldap_url_parse</function></title>
|
|
<indexterm>
|
|
<primary>C SDK functions</primary>
|
|
<secondary><function>ldap_url_parse</function></secondary>
|
|
</indexterm><indexterm>
|
|
<primary><function>ldap_url_parse</function></primary>
|
|
</indexterm>
|
|
<para>The <function>ldap_url_parse</function> function parses an LDAP URL
|
|
into its components.</para>
|
|
<sect3 id="gasex"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_url_parse( const char *url, LDAPURLDesc **ludpp );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gasel"><title>Parameters</title>
|
|
<table frame="topbot" id="gasfj"><title><function>ldap_url_parse</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>url</literal></para></entry>
|
|
<entry>
|
|
<para>The URL that you want to check.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>ludpp</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to a structure containing the components of the URL.</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gasfp"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para><literal>LDAP_URL_ERR_NOTLDAP</literal> if the URL does not
|
|
begin with the <literal>ldap://</literal> or <literal>ldaps:// prefix</literal>.</para>
|
|
</listitem>
|
|
<listitem><para><literal>LDAP_URL_ERR_NODN</literal> if the URL missing trailing
|
|
slash after host or port.</para></listitem>
|
|
<listitem><para><literal>LDAP_URL_ERR_BADSCOPE</literal> if the scope within
|
|
the URL is invalid.</para></listitem>
|
|
<listitem><para><literal>LDAP_URL_ERR_MEM</literal> if not enough free memory
|
|
is available for this operation.</para></listitem>
|
|
<listitem><para><literal>LDAP_URL_ERR_PARAM</literal> if an invalid argument
|
|
was passed to the function.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="gasfb"><title>Example</title>
|
|
<para><olink targetptr="ldap-url-parse-example-code">Example 21–62</olink> parses
|
|
an LDAP URL and prints out each component of it.</para>
|
|
<example id="ldap-url-parse-example-code"><title>Using <function>ldap_url_parse</function></title>
|
|
<programlisting>#include <stdio.h>
|
|
#include <ldap.h>
|
|
...
|
|
char *my_url = "ldap://ldap.example.com:1389/dc=example,dc=com?
|
|
cn,mail,telephoneNumber?sub?(sn=Jensen)";
|
|
LDAPURLDesc *ludpp;
|
|
int res, i;
|
|
...
|
|
if ( ( res = ldap_url_parse( my_url, &ludpp ) ) != 0 ) {
|
|
switch( res ){
|
|
case LDAP_URL_ERR_NOTLDAP:
|
|
printf( "URL does not begin with \"ldap://\"\n" );
|
|
break;
|
|
case LDAP_URL_ERR_NODN:
|
|
printf( "URL missing trailing slash after host or port\n" );
|
|
break;
|
|
case LDAP_URL_ERR_BADSCOPE:
|
|
printf( "URL contains an invalid scope\n" );
|
|
break;
|
|
case LDAP_URL_ERR_MEM:
|
|
printf( "Not enough memory\n" );
|
|
break;
|
|
default:
|
|
printf( "Unknown error\n" );
|
|
}
|
|
return( 1 );
|
|
}
|
|
printf( "Components of the URL:\n" );
|
|
printf( "Host name: %s\n", ludpp->lud_host );
|
|
printf( "Port number: %d\n", ludpp->lud_port );
|
|
if ( ludpp->lud_dn != NULL ) {
|
|
printf( "Base entry: %s\n", ludpp->lud_dn );
|
|
} else {
|
|
printf( "Base entry: Root DN\n" );
|
|
}
|
|
if ( ludpp->lud_attrs != NULL ) {
|
|
printf( "Attributes returned: \n" );
|
|
for ( i=0; ludpp->lud_attrs[i] != NULL; i++ ) {
|
|
printf( "\t%s\n", ludpp->lud_attrs[i] );
|
|
}
|
|
} else {
|
|
printf( "No attributes returned.\n" );
|
|
}
|
|
printf( "Scope of the search: " );
|
|
switch( ludpp->lud_scope ) {
|
|
case LDAP_SCOPE_BASE:
|
|
printf( "base\n" );
|
|
break;
|
|
case LDAP_SCOPE_ONELEVEL:
|
|
printf( "one\n" );
|
|
break;
|
|
case LDAP_SCOPE_SUBTREE:
|
|
printf( "sub\n" );
|
|
break;
|
|
default:
|
|
printf( "Unknown scope\n" );
|
|
}
|
|
printf( "Filter: %s\n", ludpp->lud_filter );
|
|
...</programlisting>
|
|
</example>
|
|
</sect3>
|
|
<sect3 id="gaser"><title>See Also</title>
|
|
<para><olink targetptr="bdasi">ldap_free_urldesc</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdawl"><title><function>ldap_url_parse_no_defaults</function></title>
|
|
<indexterm>
|
|
<primary>C SDK functions</primary>
|
|
<secondary><function>ldap_url_parse_no_defaults</function></secondary>
|
|
</indexterm><indexterm>
|
|
<primary><function>ldap_url_parse_no_defaults</function></primary>
|
|
</indexterm>
|
|
<para>The <function>ldap_url_parse_no_defaults</function> function parses
|
|
an LDAP URL into its components.</para>
|
|
<sect3 id="gasfw"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_url_parse_no_defaults( const char *url, LDAPURLDesc **ludpp,
|
|
int dn_required );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gaseq"><title>Parameters</title>
|
|
<table frame="topbot" id="gasfy"><title><function>ldap_url_parse_no_defaults</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>url</literal></para></entry>
|
|
<entry>
|
|
<para>The URL that you want to check.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>ludpp</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to a structure containing the components of the URL.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>dn_required</literal></para></entry>
|
|
<entry>
|
|
<para>Specifies if a DN must be present in the URL. Set to <literal>0</literal>,
|
|
the DN is not required. Set to <literal>1</literal>, the function will return
|
|
an error <literal>LDAP_URL_ERR_NODN</literal> if no DN is present.</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gasfm"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para><literal>LDAP_URL_ERR_NODN</literal> if a required DN is not
|
|
present.</para></listitem>
|
|
<listitem><para><literal>LDAP_URL_ERR_NOTLDAP</literal> if the URL does not
|
|
begin with the ldap:// or ldaps:// prefix.</para></listitem>
|
|
<listitem><para><literal>LDAP_URL_ERR_NODN</literal> if the URL missing trailing
|
|
slash after host or port.</para></listitem>
|
|
<listitem><para><literal>LDAP_URL_ERR_BADSCOPE</literal> if the scope within
|
|
the URL is invalid.</para></listitem>
|
|
<listitem><para><literal>LDAP_URL_ERR_MEM</literal> if not enough free memory
|
|
is available for this operation.</para></listitem>
|
|
<listitem><para><literal>LDAP_URL_ERR_PARAM</literal> if an invalid argument
|
|
was passed to the function.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="gasez"><title>Description</title>
|
|
<para>The <function>ldap_url_parse_no_defaults</function> function does not
|
|
set any default value in the fields that would be absent from the URL (for
|
|
example, the port number).</para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdawm"><title><function>ldap_url_search</function></title>
|
|
<indexterm>
|
|
<primary>C SDK functions</primary>
|
|
<secondary><function>ldap_url_search</function></secondary>
|
|
</indexterm><indexterm>
|
|
<primary><function>ldap_url_search</function></primary>
|
|
</indexterm>
|
|
<para>The <function>ldap_url_search</function> function searches the directory
|
|
asynchronously for matching entries, based on the contents of the URL.</para>
|
|
<sect3 id="gasfv"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_url_search( LDAP *ld, const char *url, int attrsonly );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gasfl"><title>Parameters</title>
|
|
<table frame="topbot" id="gasem"><title><function>ldap_url_search</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>url</literal></para></entry>
|
|
<entry>
|
|
<para>LDAP URL specifying a search of the directory.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>attrsonly</literal></para></entry>
|
|
<entry>
|
|
<para>Specifies whether or not attribute values are returned along with the
|
|
attribute types. This parameter can have the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><literal>0</literal> specifies that both attribute types and
|
|
attribute values are returned.</para></listitem>
|
|
<listitem><para><literal>1</literal> specifies that only attribute types are
|
|
returned.</para></listitem>
|
|
</itemizedlist>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gasfc"><title>Returns</title>
|
|
<para>Returns the message ID of the <olink targetptr="bdawm">ldap_url_search</olink> operation.
|
|
To check the result of this operation, call <olink targetptr="bdauu">ldap_result</olink>
|
|
and <olink targetptr="bdauv">ldap_result2error</olink>.</para></sect3>
|
|
<sect3 id="gasfz"><title>Description</title>
|
|
<para><function>ldap_url_search</function> searches the directory for matching
|
|
entries, based on the contents of the URL. <function>ldap_url_search</function> is
|
|
an asynchronous function; it does not directly return results. If you want
|
|
the results to be returned directly by the function, call the synchronous
|
|
function <olink targetptr="bdawn">ldap_url_search_s</olink>.</para></sect3>
|
|
<sect3 id="gasft"><title>Example</title>
|
|
<para><olink targetptr="ldap-url-search-example-code">Example 21–63</olink> returns
|
|
the message ID.</para>
|
|
<example id="ldap-url-search-example-code"><title>Using <function>ldap_url_search
|
|
</function></title>
|
|
<programlisting>#include "examples.h"
|
|
|
|
static void do_other_work();
|
|
unsigned long global_counter = 0;
|
|
|
|
int
|
|
main( int argc, char **argv )
|
|
{
|
|
char *my_url = "ldap://ldap.example.com/dc=example,dc=com?
|
|
cn,mail,telephoneNumber?sub?(sn=Jensen)";
|
|
LDAP *ld;
|
|
LDAPMessage *result, *e;
|
|
BerElement *ber;
|
|
char *a, *dn;
|
|
char **vals;
|
|
int i, rc, finished, msgid;
|
|
int num_entries = 0;
|
|
struct timeval zerotime;
|
|
|
|
zerotime.tv_sec = zerotime.tv_usec = 0L;
|
|
|
|
/* Get a handle to an LDAP connection. Use prldap_init() for IPv6. */
|
|
if ( (ld = ldap_init( MY_HOST, MY_PORT )) == NULL ) {
|
|
perror( "ldap_init" );
|
|
return( 1 );
|
|
}
|
|
/* authenticate to the directory as nobody */
|
|
if ( ldap_simple_bind_s( ld, NULL, NULL ) != LDAP_SUCCESS ) {
|
|
ldap_perror( ld, "ldap_simple_bind_s" );
|
|
return( 1 );
|
|
}
|
|
/* search for all entries with surname of Jensen */
|
|
if (( msgid = ldap_url_search( ld, my_url, 0 )) == -1 ) {
|
|
ldap_perror( ld, "ldap_url_search" );
|
|
return( 1 );
|
|
}
|
|
|
|
/* Loop, polling for results until finished */
|
|
finished = 0;
|
|
while ( !finished ) {
|
|
/*
|
|
* Poll for results. We call ldap_result with the "all" parameter
|
|
* set to zero. This causes ldap_result() to return exactly one
|
|
* entry if at least one entry is available. This allows us to
|
|
* display the entries as they are received.
|
|
*/
|
|
result = NULL;
|
|
rc = ldap_result( ld, msgid, 0, &zerotime, &result );
|
|
switch ( rc ) {
|
|
case -1:
|
|
/* some error occurred */
|
|
ldap_perror( ld, "ldap_result" );
|
|
return( 1 );
|
|
case 0:
|
|
/* Timeout was exceeded. No entries are ready for retrieval. */
|
|
if ( result != NULL ) {
|
|
ldap_msgfree( result );
|
|
}
|
|
break;
|
|
default:
|
|
/*
|
|
* Either an entry is ready for retrieval, or all entries have
|
|
* been retrieved.
|
|
*/
|
|
if (( e = ldap_first_entry( ld, result )) == NULL ) {
|
|
/* All done */
|
|
finished = 1;
|
|
if ( result != NULL ) {
|
|
ldap_msgfree( result );
|
|
}
|
|
continue;
|
|
}
|
|
/* for each entry print out name + all attrs and values */
|
|
num_entries++;
|
|
if (( dn = ldap_get_dn( ld, e )) != NULL ) {
|
|
printf( "dn: %s\n", dn );
|
|
ldap_memfree( dn );
|
|
}
|
|
for ( a = ldap_first_attribute( ld, e, &ber );
|
|
a != NULL; a = ldap_next_attribute( ld, e, ber ) ) {
|
|
if (( vals = ldap_get_values( ld, e, a )) != NULL ) {
|
|
for ( i = 0; vals[ i ] != NULL; i++ ) {
|
|
printf( "%s: %s\n", a, vals[ i ] );
|
|
}
|
|
ldap_value_free( vals );
|
|
}
|
|
ldap_memfree( a );
|
|
}
|
|
if ( ber != NULL ) {
|
|
ldap_ber_free( ber, 0 );
|
|
}
|
|
printf( "\n" );
|
|
ldap_msgfree( result );
|
|
}
|
|
/* Do other work here while you are waiting... */
|
|
do_other_work();
|
|
}
|
|
|
|
/* All done. Print a summary. */
|
|
printf( "%d entries retrieved. I counted to %ld "
|
|
"while I was waiting.\n", num_entries,
|
|
global_counter );
|
|
ldap_unbind( ld );
|
|
return( 0 );
|
|
}
|
|
|
|
/*
|
|
* Perform other work while polling for results. */
|
|
static void
|
|
do_other_work()
|
|
{
|
|
global_counter++;
|
|
}</programlisting>
|
|
</example>
|
|
</sect3>
|
|
<sect3 id="gasei"><title>See Also</title>
|
|
<para><olink targetptr="bdawn">ldap_url_search_s</olink>, <olink targetptr="bdauu">ldap_result</olink>, <olink targetptr="bdauv">ldap_result2error
|
|
</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdawn"><title><function>ldap_url_search_s</function></title>
|
|
<indexterm>
|
|
<primary>C SDK functions</primary>
|
|
<secondary><function>ldap_url_search_s</function></secondary>
|
|
</indexterm><indexterm>
|
|
<primary><function>ldap_url_search_s</function></primary>
|
|
</indexterm>
|
|
<para>The <function>ldap_url_search_s</function> function searches the directory
|
|
synchronously for matching entries, based on the contents of the URL.</para>
|
|
<sect3 id="gaseu"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_url_search_s( LDAP *ld, const char *url,
|
|
int attrsonly, LDAPMessage **res );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gasfk"><title>Parameters</title>
|
|
<table frame="topbot" id="gasge"><title><function>ldap_url_search_s</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>url</literal></para></entry>
|
|
<entry>
|
|
<para>LDAP URL specifying a search of the directory.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>attrsonly</literal></para></entry>
|
|
<entry>
|
|
<para>Specifies whether or not attribute values are returned along with the
|
|
attribute types. This parameter can have the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><literal>0</literal> specifies that both attribute types and
|
|
attribute values are returned.</para></listitem>
|
|
<listitem><para><literal>1</literal> specifies that only attribute types are
|
|
returned.</para></listitem>
|
|
</itemizedlist>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>res</literal></para></entry>
|
|
<entry>
|
|
<para>Results of the search (when the call is completed).</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gasep"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para>If unsuccessful, returns the LDAP error code for the operation.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="gasfo"><title>Description</title>
|
|
<para>The <function>ldap_url_search_s</function> function searches the directory
|
|
for matching entries, based on the contents of the URL. <function>ldap_url_search_s
|
|
</function> is a synchronous function, which directly returns the results
|
|
of the operation. If you want to perform other operations while waiting for
|
|
the results of this operation, call the asynchronous function <olink targetptr="bdawm">ldap_url_search</olink>.</para></sect3>
|
|
<sect3 id="gasfg"><title>Example</title>
|
|
<para><olink targetptr="ldap-url-search-s-example">Example 21–64</olink>
|
|
processes a search request from an LDAP URL.</para>
|
|
<example id="ldap-url-search-s-example"><title>Using <function>ldap_url_search_s</function></title>
|
|
<programlisting>#include <stdio.h>
|
|
#include <ldap.h>
|
|
...
|
|
LDAP *ld;
|
|
LDAPMessage *result;
|
|
char *my_url = "ldap://ldap.example.com/dc=example,dc=com?
|
|
cn,mail,telephoneNumber?sub?(sn=Jensen)";
|
|
...
|
|
/* Process the search request in the URL */
|
|
if ( ldap_url_search_s( ld, my_url, 0, &result ) != LDAP_SUCCESS ) {
|
|
ldap_perror( ld, "ldap_url_search_s" );
|
|
return( 1 );
|
|
}
|
|
...</programlisting>
|
|
</example>
|
|
</sect3>
|
|
<sect3 id="gasgf"><title>See Also</title>
|
|
<para><olink targetptr="bdauy">ldap_search</olink>, <olink targetptr="bdavc">ldap_search_st
|
|
</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdawo"><title><function>ldap_url_search_st</function></title>
|
|
<indexterm>
|
|
<primary>C SDK functions</primary>
|
|
<secondary><function>ldap_url_search_st</function></secondary>
|
|
</indexterm><indexterm>
|
|
<primary><function>ldap_url_search_st</function></primary>
|
|
</indexterm>
|
|
<para>The <function>ldap_url_search_st</function> function searches the directory,
|
|
synchronously within a specified time limit, for matching entries, based on
|
|
the contents of the URL.</para>
|
|
<sect3 id="gasek"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_url_search_st( LDAP *ld, const char *url, int attrsonly,
|
|
struct timeval *timeout, LDAPMessage **res );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gasfe"><title>Parameters</title>
|
|
<table frame="topbot" id="gasgb"><title><function>ldap_url_search_st</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>url</literal></para></entry>
|
|
<entry>
|
|
<para>LDAP URL specifying a search of the directory.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>attrsonly</literal></para></entry>
|
|
<entry>
|
|
<para>Specifies whether or not attribute values are returned along with the
|
|
attribute types. This parameter can have the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><literal>0</literal> specifies that both attribute types and
|
|
attribute values are returned.</para></listitem>
|
|
<listitem><para><literal>1</literal> specifies that only attribute types are
|
|
returned.</para></listitem>
|
|
</itemizedlist>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>timeout</literal></para></entry>
|
|
<entry>
|
|
<para>Maximum time to wait for the results of the search.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>res</literal></para></entry>
|
|
<entry>
|
|
<para>Results of the search (when the call is completed).</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gasey"><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if any of the arguments
|
|
are invalid.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_ENCODING_ERROR</errorcode> if an error occurred
|
|
when BER-encoding the request.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_SERVER_DOWN</errorcode> if the LDAP server
|
|
did not receive the request or if the connection to the server was lost.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
|
|
allocated.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_LOCAL_ERROR</errorcode> if an error occurred
|
|
when receiving the results from the server.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_DECODING_ERROR</errorcode> if an error occurred
|
|
when decoding the BER-encoded results from the server.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_FILTER_ERROR</errorcode> if an error occurred
|
|
when parsing and BER-encoding the search filter specified by the filter argument.
|
|
</para></listitem>
|
|
<listitem><para><errorcode>LDAP_TIMEOUT</errorcode> if the search exceeded
|
|
the time specified by the <literal>timeoutp</literal> argument.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_NOT_SUPPORTED</errorcode> if controls are
|
|
included in your request (for example, as a session preference) and your LDAP
|
|
client does not specify that it is using the LDAP v3. Make sure that you set
|
|
the version of your LDAP client to version 3 before calling this function.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<note><para>&cnDirectoryServer; and other LDAP server products may send result
|
|
codes in addition to those described. For example, the server may have loaded
|
|
a plug-in that returns custom result codes. Check your LDAP server documentation
|
|
for other result codes.</para></note>
|
|
</sect3>
|
|
<sect3 id="gasfq"><title>Description</title>
|
|
<para>The <function>ldap_url_search_st</function> function searches the directory
|
|
for matching entries, based on the contents of the URL. This function works
|
|
like <olink targetptr="bdawn">ldap_url_search_s</olink> and lets you specify
|
|
a time out period for the search.</para></sect3>
|
|
<sect3 id="gasfs"><title>See Also</title>
|
|
<para><olink targetptr="bdauy">ldap_search</olink>, <olink targetptr="bdavb">ldap_search_s
|
|
</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdawp"><title><function>ldap_utf8characters</function></title>
|
|
<indexterm>
|
|
<primary>C SDK functions</primary>
|
|
<secondary><function>ldap_utf8characters</function></secondary>
|
|
</indexterm><indexterm>
|
|
<primary><function>ldap_utf8characters</function></primary>
|
|
</indexterm>
|
|
<para>The <function>ldap_utf8characters</function> function accepts a Unicode
|
|
string and returns the number of characters.</para>
|
|
<sect3 id="gaseo"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
size_t ldap_utf8characters( const char* );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gasen"><title>Parameters</title>
|
|
<table frame="topbot" id="gasgc"><title><function>ldap_utf8characters</function> Function
|
|
Parameter</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>char</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to a UTF-8 string.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gasev"><title>Returns</title>
|
|
<para>Returns the number of UTF-8 characters in the <literal>0</literal> terminated
|
|
array.</para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdawq"><title><function>ldap_utf8copy</function></title>
|
|
<indexterm>
|
|
<primary>C SDK functions</primary>
|
|
<secondary><function>ldap_utf8copy</function></secondary>
|
|
</indexterm><indexterm>
|
|
<primary><function>ldap_utf8copy</function></primary>
|
|
</indexterm>
|
|
<para>The <function>ldap_utf8copy</function> function accepts a Unicode string
|
|
and copies the characters to a destination.</para>
|
|
<sect3 id="gases"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_utf8copy( char* dst, const char* src );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gasfx"><title>Parameters</title>
|
|
<table frame="topbot" id="gasgd"><title><function>ldap_utf8copy</function> Function
|
|
Parameter</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>dst</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to a destination for the copied characters.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>src</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to a UTF-8 string to copy.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gasfh"><title>Description</title>
|
|
<para><function>ldap_utf8copy</function> copies a character from <literal>src</literal> to
|
|
<literal>dst</literal>. This function handles any valid UTF-8 character (including
|
|
<literal>\0</literal> and ASCII).</para></sect3>
|
|
<sect3 id="gasfn"><title>Returns</title>
|
|
<para>The number of characters copied.</para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdawr"><title><function>ldap_utf8getcc</function></title>
|
|
<indexterm>
|
|
<primary>C SDK functions</primary>
|
|
<secondary><function>ldap_utf8getcc</function></secondary>
|
|
</indexterm><indexterm>
|
|
<primary><function>ldap_utf8getcc</function></primary>
|
|
</indexterm>
|
|
<para>The <function>ldap_utf8getcc</function> function gets one UCS-4 character
|
|
and moves the pointer to the next character.</para>
|
|
<sect3 id="gasfu"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
unsigned long ldap_utf8getcc( const char** src );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gasfr"><title>Parameters</title>
|
|
<table frame="topbot" id="gashv"><title><function>ldap_utf8getcc</function> Function
|
|
Parameter</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>src</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to a UCS-4 character.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="bdaws"><title><function>ldap_utf8isalnum</function></title>
|
|
<indexterm>
|
|
<primary>C SDK functions</primary>
|
|
<secondary><function>ldap_utf8isalnum</function></secondary>
|
|
</indexterm><indexterm>
|
|
<primary><function>ldap_utf8isalnum</function></primary>
|
|
</indexterm>
|
|
<para>The <function>ldap_utf8isalnum</function> function determines whether
|
|
the character is an alphanumeric one.</para>
|
|
<sect3 id="gasgw"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_utf8isalnum( char* s );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gashi"><title>Parameters</title>
|
|
<table frame="topbot" id="gasgs"><title><function>ldap_utf8isalnum</function> Function
|
|
Parameter</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>s</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to a UTF-8 character.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="bdawt"><title><function>ldap_utf8isalpha</function></title>
|
|
<indexterm>
|
|
<primary>C SDK functions</primary>
|
|
<secondary><function>ldap_utf8isalpha</function></secondary>
|
|
</indexterm><indexterm>
|
|
<primary><function>ldap_utf8isalpha</function></primary>
|
|
</indexterm>
|
|
<para>The <function>ldap_utf8isalpha</function> function determines whether
|
|
the character is a letter.</para>
|
|
<sect3 id="gasgi"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_utf8isalpha( char* s );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gashl"><title>Parameters</title>
|
|
<table frame="topbot" id="gasgl"><title><function>ldap_utf8isalpha</function> Function
|
|
Parameter</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>s</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to a UTF-8 character.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="bdawu"><title><function>ldap_utf8isdigit</function></title>
|
|
<indexterm>
|
|
<primary>C SDK functions</primary>
|
|
<secondary><function>ldap_utf8isdigit</function></secondary>
|
|
</indexterm><indexterm>
|
|
<primary><function>ldap_utf8isdigit</function></primary>
|
|
</indexterm>
|
|
<para>The <function>ldap_utf8isdigit</function> function determines whether
|
|
the character is a number.</para>
|
|
<sect3 id="gasgu"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_utf8isdigit( char* s );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gashp"><title>Parameters</title>
|
|
<table frame="topbot" id="gasgv"><title><function>ldap_utf8isdigit</function> Function
|
|
Parameter</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>s</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to a UTF-8 character.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="bdawv"><title><function>ldap_utf8isspace</function></title>
|
|
<indexterm>
|
|
<primary>C SDK functions</primary>
|
|
<secondary><function>ldap_utf8isspace</function></secondary>
|
|
</indexterm><indexterm>
|
|
<primary><function>ldap_utf8isspace</function></primary>
|
|
</indexterm>
|
|
<para>The <function>ldap_utf8isspace</function> function determines whether
|
|
the character is a space, tab, newline, return or formfeed.</para>
|
|
<sect3 id="gasgj"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_utf8isspace( char* s );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gasgq"><title>Parameters</title>
|
|
<table frame="topbot" id="gashj"><title><function>ldap_utf8isspace</function> Function
|
|
Parameter</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>s</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to a UTF-8 character.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="bdaww"><title><function>ldap_utf8len</function></title>
|
|
<indexterm>
|
|
<primary>C SDK functions</primary>
|
|
<secondary><function>ldap_utf8len</function></secondary>
|
|
</indexterm><indexterm>
|
|
<primary><function>ldap_utf8len</function></primary>
|
|
</indexterm>
|
|
<para>The <function>ldap_utf8len</function> function accepts a Unicode string
|
|
and returns the number of bytes it contains.</para>
|
|
<sect3 id="gashf"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_utf8len( const char* );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gashr"><title>Parameters</title>
|
|
<table frame="topbot" id="gashs"><title><function>ldap_utf8len</function> Function
|
|
Parameter</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>char</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to a UTF-8 string.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="bdawx"><title><function>ldap_utf8next</function></title>
|
|
<indexterm>
|
|
<primary>C SDK functions</primary>
|
|
<secondary><function>ldap_utf8next</function></secondary>
|
|
</indexterm><indexterm>
|
|
<primary><function>ldap_utf8next</function></primary>
|
|
</indexterm>
|
|
<para>The <function>ldap_utf8next</function> function accepts a character
|
|
and returns a pointer to the character immediately following it.</para>
|
|
<sect3 id="gashq"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
char* ldap_utf8next( char* );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gasgk"><title>Parameters</title>
|
|
<table frame="topbot" id="gasht"><title><function>ldap_utf8next</function> Function
|
|
Parameter</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>char</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to a UTF-8 character.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="bdawy"><title><function>ldap_utf8prev</function></title>
|
|
<indexterm>
|
|
<primary>C SDK functions</primary>
|
|
<secondary><function>ldap_utf8prev</function></secondary>
|
|
</indexterm><indexterm>
|
|
<primary><function>ldap_utf8prev</function></primary>
|
|
</indexterm>
|
|
<para>The <function>ldap_utf8prev</function> function accepts a character
|
|
and returns a pointer to the previous character.</para>
|
|
<sect3 id="gashg"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
char* ldap_utf8prev( char* );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gasgn"><title>Parameters</title>
|
|
<table frame="topbot" id="gashn"><title><function>ldap_utf8prev</function> Function
|
|
Parameter</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>char</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to a UTF-8 character.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="bdawz"><title><function>ldap_utf8strtok_r</function></title>
|
|
<indexterm>
|
|
<primary>C SDK functions</primary>
|
|
<secondary><function>ldap_utf8strtok_r</function></secondary>
|
|
</indexterm><indexterm>
|
|
<primary><function>ldap_utf8strtok_r</function></primary>
|
|
</indexterm>
|
|
<para>The <function>ldap_utf8strtok_r</function> function gets the next token
|
|
from a string.</para>
|
|
<sect3 id="gashd"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
char* ldap_utf8strtok_r( char* src, const char* brk, char** next);</programlisting>
|
|
</sect3>
|
|
<sect3 id="gasha"><title>Parameters</title>
|
|
<table frame="topbot" id="gashw"><title><function>ldap_utf8strtok_r</function> Function
|
|
Parameter</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>src</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to a UTF-8 string from which to extract token.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>brk</literal></para></entry>
|
|
<entry>
|
|
<para>Points to a <literal>NULL</literal> terminated set of delimiter characters.
|
|
</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>next</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to the next token.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gashm"><title>Returns</title>
|
|
<para>Returns a pointer to the next token. If there are no remaining tokens,
|
|
returns a <literal>NULL</literal> pointer.</para></sect3>
|
|
</sect2>
|
|
<sect2 id="ldap-whoami"><title><function>ldap_whoami</function></title>
|
|
<indexterm>
|
|
<primary>C SDK functions</primary>
|
|
<secondary><function>ldap_whoami</function></secondary>
|
|
</indexterm><indexterm>
|
|
<primary><function>ldap_whoami</function></primary>
|
|
</indexterm>
|
|
<para>The <function>ldap_whoami</function> function sends an asynchronous
|
|
Who am I? extended operation request to determine the authorization identity
|
|
associated with a connection.</para>
|
|
<sect3><title>Syntax</title>
|
|
<programlisting>LDAP_API(int) LDAP_CALL ldap_whoami( LDAP *ld, LDAPControl **serverctrls,
|
|
LDAPControl **clientctrls, int *msgidp );</programlisting>
|
|
</sect3>
|
|
<sect3><title>Parameters</title>
|
|
<table frame="topbot" id="gbgpi"><title><function>ldap_whoami</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2" colsep="0" rowsep="0"><colspec colwidth="50*"><colspec
|
|
colwidth="50*">
|
|
<thead>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>serverctrls</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
|
|
representing LDAP server controls that apply to this operation. If you do
|
|
not want to pass any server controls, specify <literal>NULL</literal> for
|
|
this argument.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>clientctrls</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
|
|
representing LDAP client controls that apply to this operation. If you do
|
|
not want to pass any client controls, specify <literal>NULL</literal> for
|
|
this argument.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><parameter>msgidp</parameter></para></entry>
|
|
<entry>
|
|
<para>Pointer to the message ID for this asynchronous call, for use with <olink targetptr="ldap-parse-whoami-result">ldap_parse_whoami_result</olink>, or
|
|
to retrieve the result for use with <olink targetptr="ldap-parse-whoami">ldap_parse_whoami
|
|
</olink>.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if any of the arguments
|
|
are invalid.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_ENCODING_ERROR</errorcode> if an error occurred
|
|
when BER-encoding the request.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_SERVER_DOWN</errorcode> if the LDAP server
|
|
did not receive the request or if the connection to the server was lost.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
|
|
allocated.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="ldap-whoami-s"><title><function>ldap_whoami_s</function></title>
|
|
<indexterm>
|
|
<primary>C SDK functions</primary>
|
|
<secondary><function>ldap_whoami_s</function></secondary>
|
|
</indexterm><indexterm>
|
|
<primary><function>ldap_whoami_s</function></primary>
|
|
</indexterm>
|
|
<para>The <function>ldap_whoami_s</function> function sends a synchronous
|
|
Who am I? extended operation request to determine the authorization identity
|
|
associated with a connection.</para>
|
|
<sect3><title>Syntax</title>
|
|
<programlisting>LDAP_API(int) LDAP_CALL ldap_whoami_s( LDAP *ld, LDAPControl **serverctrls,
|
|
LDAPControl **clientctrls, char **authzid );</programlisting>
|
|
</sect3>
|
|
<sect3><title>Parameters</title>
|
|
<table frame="topbot" id="gbgpia"><title><function>ldap_whoami_s</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2" colsep="0" rowsep="0"><colspec colwidth="50*"><colspec
|
|
colwidth="50*">
|
|
<thead>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an <olink targetptr="bdakj">LDAP</olink> structure containing
|
|
information about the connection to the LDAP server.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>serverctrls</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
|
|
representing LDAP server controls that apply to this operation. If you do
|
|
not want to pass any server controls, specify <literal>NULL</literal> for
|
|
this argument.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>clientctrls</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to an array of <olink targetptr="bdala">LDAPControl</olink> structures
|
|
representing LDAP client controls that apply to this operation. If you do
|
|
not want to pass any client controls, specify <literal>NULL</literal> for
|
|
this argument.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><parameter>authzid</parameter></para></entry>
|
|
<entry>
|
|
<para>Pointer to the string to hold the authorization identity retrieved from
|
|
the server.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3><title>Returns</title>
|
|
<para>One of the following values:</para>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> if any of the arguments
|
|
are invalid.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_ENCODING_ERROR</errorcode> if an error occurred
|
|
when BER-encoding the request.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_SERVER_DOWN</errorcode> if the LDAP server
|
|
did not receive the request or if the connection to the server was lost.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_NO_MEMORY</errorcode> if memory cannot be
|
|
allocated.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="bdaxa"><title><function>ldap_vals2html</function></title>
|
|
<indexterm>
|
|
<primary>C SDK functions</primary>
|
|
<secondary><function>ldap_vals2html</function></secondary>
|
|
</indexterm><indexterm>
|
|
<primary><function>ldap_vals2html</function></primary>
|
|
</indexterm>
|
|
<para>The <function>ldap_vals2html</function> function writes the HTML representation
|
|
of a set of values.</para>
|
|
<sect3 id="gasgp"><title>Syntax</title>
|
|
<programlisting>#include <disptmpl.h>
|
|
int ldap_vals2html( LDAP *ld, char *buf, char **vals, char *label,
|
|
int labelwidth, unsigned long syntaxid, writeptype writeproc,
|
|
void *writeparm, char *eol, int rdncount, char *urlprefix );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gasgr"><title>Parameters</title>
|
|
<table frame="topbot" id="gashc"><title><function>ldap_vals2html</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>The LDAP pointer obtained by a previous call to <olink targetptr="bdauj">ldap_open
|
|
</olink> .</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>buf</literal></para></entry>
|
|
<entry></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>vals</literal></para></entry>
|
|
<entry>
|
|
<para>A NULL terminated list of values, usually obtained by a call to <olink targetptr="bdast">ldap_get_values</olink>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>label</literal></para></entry>
|
|
<entry>
|
|
<para>A string (usually a friendly form of an LDAP attribute name) shown next
|
|
to the values.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>labelwidth</literal></para></entry>
|
|
<entry>
|
|
<para>Specifies the label margin (the number of blank spaces displayed to
|
|
the left of the values). If zero is passed, a default label width is used.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>syntaxid</literal></para></entry>
|
|
<entry>
|
|
<para>Display template attribute syntax identifier for a list of predefined <literal>
|
|
LDAP_SYN_...</literal> values.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>writeproc</literal></para></entry>
|
|
<entry>
|
|
<para><function>writeproc</function> function should be declared as:</para>
|
|
<para><literal>int writeproc( writeparm, p, len )</literal></para>
|
|
<para><literal>void *writeparm;</literal></para>
|
|
<para><literal>char *p;</literal></para>
|
|
<para><literal>int len;</literal></para>
|
|
<para>where <literal>p</literal> is a pointer to text to be written and <literal>
|
|
len</literal> is the length of the text. <parameter>p</parameter> is guaranteed
|
|
to be zero terminated.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>writeparm</literal></para></entry>
|
|
<entry>
|
|
<para>A pointer to a structure that will be passed as the first parameter
|
|
of the <function>writeproc</function> procedure. Typically, this is used to
|
|
pass the file descriptor of the file to write to.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>eol</literal></para></entry>
|
|
<entry>
|
|
<para>Lines of text are terminated with this string.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>rdncount</literal></para></entry>
|
|
<entry>
|
|
<para>Limits the number of components that are displayed for DN attributes.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>urlprefix</literal></para></entry>
|
|
<entry>
|
|
<para>Starting text to use when constructing an LDAP URL. The default
|
|
is the string <literal>ldap://</literal></para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gashe"><title>Returns</title>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para>An LDAP error code on error.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="gasgz"><title>Description</title>
|
|
<para><function>ldap_vals2html</function> produces HTML output of a single
|
|
set of LDAP attribute values.</para></sect3>
|
|
<sect3 id="gasgm"><title>See Also</title>
|
|
<para><olink targetptr="bdaxb">ldap_vals2text</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaxb"><title><function>ldap_vals2text</function></title>
|
|
<indexterm>
|
|
<primary>C SDK functions</primary>
|
|
<secondary><function>ldap_vals2text</function></secondary>
|
|
</indexterm><indexterm>
|
|
<primary><function>ldap_vals2text</function></primary>
|
|
</indexterm>
|
|
<para>The <function>ldap_vals2text</function> function writes the text representation
|
|
of an LDAP entry.</para>
|
|
<sect3 id="gasgt"><title>Syntax</title>
|
|
<programlisting>#include <disptmpl.h>
|
|
int ldap_vals2text( LDAP *ld, char *buf, char **vals, char *label,
|
|
int labelwidth, unsigned long syntaxid, writeptype writeproc,
|
|
void *writeparm, char *eol, int rdncount );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gashb"><title>Parameters</title>
|
|
<table frame="topbot" id="gasgx"><title><function>ldap_vals2text</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>The LDAP pointer obtained by a previous call to <olink targetptr="bdauj">ldap_open
|
|
</olink> .</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>buf</literal></para></entry>
|
|
<entry></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>vals</literal></para></entry>
|
|
<entry>
|
|
<para>A <literal>NULL</literal> terminated list of values, usually obtained
|
|
by a call to <olink targetptr="bdast">ldap_get_values</olink>.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>label</literal></para></entry>
|
|
<entry>
|
|
<para>A string (usually a friendly form of an LDAP attribute name) shown next
|
|
to the values.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>labelwidth</literal></para></entry>
|
|
<entry>
|
|
<para>Specifies the label margin (the number of blank spaces displayed to
|
|
the left of the values). If zero is passed, a default label width is used.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>syntaxid</literal></para></entry>
|
|
<entry>
|
|
<para>Display template attribute syntax identifier for a list of predefined <literal>
|
|
LDAP_SYN_...</literal> values.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>writeproc</literal></para></entry>
|
|
<entry>
|
|
<para><function>writeproc</function> function should be declared as:</para>
|
|
<para><literal>int writeproc( writeparm, p, len )</literal></para>
|
|
<para><literal>void *writeparm;</literal></para>
|
|
<para><literal>char *p;</literal></para>
|
|
<para><literal>int len;</literal></para>
|
|
<para>where <literal>p</literal> is a pointer to text to be written and <literal>
|
|
len</literal> is the length of the text. <parameter>p</parameter> is guaranteed
|
|
to be zero terminated.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>writeparm</literal></para></entry>
|
|
<entry>
|
|
<para>A pointer to a structure that will be passed as the first parameter
|
|
of the <function>writeproc</function> procedure. Typically, this is used to
|
|
pass the file descriptor of the file to write to.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>eol</literal></para></entry>
|
|
<entry>
|
|
<para>Lines of text are terminated with this string.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>rdncount</literal></para></entry>
|
|
<entry>
|
|
<para>Limits the number of components that are displayed for DN attributes.</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gasho"><title>Returns</title>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para>An LDAP error code on error.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="gashk"><title>Description</title>
|
|
<para><function>ldap_vals2text</function> produces a text representation of
|
|
a single set of LDAP attribute values.</para></sect3>
|
|
<sect3 id="gasgo"><title>See Also</title>
|
|
<para><olink targetptr="bdaxa">ldap_vals2html</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaxc"><title><function>ldap_value_free</function></title>
|
|
<indexterm>
|
|
<primary>C SDK functions</primary>
|
|
<secondary><function>ldap_value_free</function></secondary>
|
|
</indexterm><indexterm>
|
|
<primary><function>ldap_value_free</function></primary>
|
|
</indexterm>
|
|
<para>The <function>ldap_value_free</function> function frees an array of
|
|
values from memory.</para>
|
|
<sect3 id="gashu"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
void ldap_value_free( char **values );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gasgy"><title>Parameters</title>
|
|
<table frame="topbot" id="gashh"><title><function>ldap_value_free</function> Function
|
|
Parameter</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>values</literal></para></entry>
|
|
<entry>
|
|
<para>Array of values.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gasin"><title>Description</title>
|
|
<para>Use the <olink targetptr="bdaxd">ldap_value_free_len</olink> function
|
|
if the values are <olink targetptr="bdakg">berval</olink> structures.</para>
|
|
</sect3>
|
|
<sect3 id="gasir"><title>Example</title>
|
|
<para>See the example under <olink targetptr="bdast">ldap_get_values</olink>.</para>
|
|
</sect3>
|
|
<sect3 id="gashz"><title>See Also</title>
|
|
<para><olink targetptr="bdast">ldap_get_values</olink>, <olink targetptr="bdaxd">
|
|
ldap_value_free_len</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaxd"><title><function>ldap_value_free_len</function></title>
|
|
<indexterm>
|
|
<primary>C SDK functions</primary>
|
|
<secondary><function>ldap_value_free_len</function></secondary>
|
|
</indexterm><indexterm>
|
|
<primary><function>ldap_value_free_len</function></primary>
|
|
</indexterm>
|
|
<para>The <function>ldap_value_free_len</function> function frees an array
|
|
of <olink targetptr="bdakg">berval</olink> structures from memory.</para>
|
|
<sect3 id="gasjg"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
void ldap_value_free_len( struct berval **values );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gasip"><title>Parameters</title>
|
|
<table frame="topbot" id="gasjc"><title><function>ldap_value_free_len</function> Function
|
|
Parameter</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>values</literal></para></entry>
|
|
<entry>
|
|
<para>Array of <structname>berval</structname> structures.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gasjj"><title>Description</title>
|
|
<para>Use the <olink targetptr="bdaxc">ldap_value_free</olink> function instead
|
|
of this function if the values are string values.</para></sect3>
|
|
<sect3 id="gasjq"><title>Example</title>
|
|
<para>See the example under <olink targetptr="bdasu">ldap_get_values_len</olink>.
|
|
</para></sect3>
|
|
<sect3 id="gasid"><title>See Also</title>
|
|
<para><olink targetptr="bdast">ldap_get_values</olink>, <olink targetptr="bdasu">
|
|
ldap_get_values_len</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaxe"><title><function>ldap_version</function></title>
|
|
<indexterm>
|
|
<primary>C SDK functions</primary>
|
|
<secondary><function>ldap_version</function></secondary>
|
|
</indexterm><indexterm>
|
|
<primary><function>ldap_version</function></primary>
|
|
</indexterm>
|
|
<note><para>This function is deprecated and should not be used. It is included
|
|
in <literal>ldap-deprecated.h</literal> for backward-compatibility. Please
|
|
use <olink targetptr="bdass">ldap_get_option</olink> with <literal>LDAP_OPT_API_INFO
|
|
</literal> and an <literal>LDAPAPIInfo</literal> structure.</para></note>
|
|
<para>The <function>ldap_version</function> function gets version information
|
|
about the &DirectorySDKForC; libraries.</para>
|
|
<sect3 id="gasiu"><title>Syntax</title>
|
|
<programlisting>#include <ldap.h>
|
|
int ldap_version( LDAPVersion *ver );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gasio"><title>Parameters</title>
|
|
<table frame="topbot" id="gasjr"><title><function>ldap_version</function> Function
|
|
Parameter</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ver</literal></para></entry>
|
|
<entry>
|
|
<para><olink targetptr="bdamu">LDAPVersion</olink> structure returning version
|
|
information. If you only want the SDK version, you can pass <literal>NULL</literal> for
|
|
this parameter.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gasik"><title>Returns</title>
|
|
<para>The version number of the &DirectorySDKForC;, multiplied by 100.
|
|
For example, for version 1.0, the function returns 100.</para></sect3>
|
|
<sect3 id="gasiw"><title>See Also</title>
|
|
<para><olink targetptr="bdass">ldap_get_option</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaxf"><title><function>ldap_x_calloc</function></title>
|
|
<indexterm>
|
|
<primary>C SDK functions</primary>
|
|
<secondary><function>ldap_x_*</function></secondary>
|
|
</indexterm><indexterm>
|
|
<primary><function>ldap_x_*</function></primary>
|
|
</indexterm>
|
|
<para>The <function>ldap_x_calloc</function> function allocates space for
|
|
an array of elements.</para>
|
|
<sect3 id="gasib"><title>Syntax</title>
|
|
<programlisting>#include <ldap-extension.h>
|
|
void *ldap_x_calloc( size_t nelem, size_t elsize );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gasji"><title>Parameters</title>
|
|
<table frame="topbot" id="gasjk"><title><function>ldap_x_calloc</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>nelem</literal></para></entry>
|
|
<entry>
|
|
<para>Number of elements for which memory is to be allocated.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>elsize</literal></para></entry>
|
|
<entry>
|
|
<para>Size of each element.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gasiy"><title>Returns</title>
|
|
<itemizedlist>
|
|
<listitem><para>If successful, returns a pointer to the space.</para></listitem>
|
|
<listitem><para>If there is no available memory, returns a <literal>NULL</literal> pointer.
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="gasic"><title>See Also</title>
|
|
<para><olink targetptr="bdaxg">ldap_x_free</olink>, <olink targetptr="bdaxl">ldap_x_malloc
|
|
</olink> , <olink targetptr="bdaxm">ldap_x_realloc</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaxg"><title><function>ldap_x_free</function></title>
|
|
<para>The <function>ldap_x_free</function> function frees allocated memory.</para>
|
|
<sect3 id="gasif"><title>Syntax</title>
|
|
<programlisting>#include <ldap-extension.h>
|
|
void ldap_x_free( void *ptr );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gasjo"><title>Parameters</title>
|
|
<table frame="topbot" id="gasjh"><title><function>ldap_x_free</function> Function
|
|
Parameter</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ptr</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to the block of memory to be freed.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gasiz"><title>See Also</title>
|
|
<para><olink targetptr="bdaxf">ldap_x_calloc</olink>, <olink targetptr="bdaxl">ldap_x_malloc
|
|
</olink>, <olink targetptr="bdaxm">ldap_x_realloc</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaxh"><title><function>ldap_x_hostlist_first</function></title>
|
|
<para>The <function>ldap_x_hostlist_first</function> function returns the
|
|
first host and port defined in a host list file.</para>
|
|
<sect3 id="gasii"><title>Syntax</title>
|
|
<programlisting>#include <ldap-extension.h>
|
|
int ldap_x_hostlist_first( char *hostlist, int defport, char **hostp,
|
|
int *portp, struct ldap_x_hostlist_status **statusp );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gasim"><title>Description</title>
|
|
<para><function>ldap_x_hostlist_first</function> parses a space-separated
|
|
host list (useful for implementing an extended I/O CONNECT callback function)
|
|
and returns the first host and port defined.</para></sect3>
|
|
<sect3 id="gashx"><title>Returns</title>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para>If unsuccessful returns a valid LDAP API error code.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<note><para>A <literal>NULL</literal> or zero-length <parameter>hostlist</parameter> causes
|
|
the host <literal>127.0.0.1</literal> to be returned.</para></note>
|
|
</sect3>
|
|
<sect3 id="gasjm"><title>See Also</title>
|
|
<para><olink targetptr="bdanc">ldap_x_hostlist_status</olink>, <olink targetptr="bdamx">LDAP_X_EXTIOF_CONNECT_CALLBACK</olink>,</para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaxi"><title><function>ldap_x_hostlist_next</function></title>
|
|
<para>The <function>ldap_x_hostlist_next</function> function returns the host
|
|
and port defined in a host list file following the previous host and port
|
|
returned.</para>
|
|
<sect3 id="gasia"><title>Syntax</title>
|
|
<programlisting>#include <ldap-extension.h>
|
|
int ldap_x_hostlist_next( char **hostp, int *portp,
|
|
struct ldap_x_hostlist_status **statusp );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gasju"><title>Description</title>
|
|
<para>This utility parses a space-separated host list (useful for implementing
|
|
an extended I/O CONNECT callback function) and returns the host and port defined
|
|
following the previous host and port returned.</para></sect3>
|
|
<sect3 id="gasix"><title>Returns</title>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful. If no more
|
|
hosts are available, <literal>LDAP_SUCCESS</literal> is returned but <literal>hostp
|
|
</literal> is set to <literal>NULL</literal>.</para></listitem>
|
|
<listitem><para>If unsuccessful returns a valid LDAP API error code.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<note><para>A <literal>NULL</literal> or zero-length <parameter>hostlist</parameter> causes
|
|
the host <literal>127.0.0.1</literal> to be returned.</para></note>
|
|
</sect3>
|
|
<sect3 id="gasiq"><title>See Also</title>
|
|
<para><olink targetptr="bdanc">ldap_x_hostlist_status</olink>, <olink targetptr="bdamx">LDAP_X_EXTIOF_CONNECT_CALLBACK</olink>,</para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaxj"><title><function>ldap_x_hostlist_status</function></title>
|
|
<sect3 id="gasie"><title>See Also</title>
|
|
<para><olink targetptr="bdaxh">ldap_x_hostlist_first</olink>, <olink targetptr="bdaxi">ldap_x_hostlist_next</olink>, <olink targetptr="bdamx">LDAP_X_EXTIOF_CONNECT_CALLBACK
|
|
</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaxk"><title><function>ldap_x_hostlist_statusfree</function></title>
|
|
<sect3 id="gasjw"><title>See Also</title>
|
|
<para><olink targetptr="bdaxh">ldap_x_hostlist_first</olink>, <olink targetptr="bdaxi">ldap_x_hostlist_next</olink>, <olink targetptr="bdamx">LDAP_X_EXTIOF_CONNECT_CALLBACK
|
|
</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaxl"><title><function>ldap_x_malloc</function></title>
|
|
<para>The <function>ldap_x_malloc</function> function allocates space for
|
|
an object.</para>
|
|
<sect3 id="gasjf"><title>Syntax</title>
|
|
<programlisting>#include <ldap-extension.h>
|
|
void *ldap_x_malloc( size_t size );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gasij"><title>Parameters</title>
|
|
<table frame="topbot" id="gashy"><title><function>ldap_x_malloc</function> Function
|
|
Parameter</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>size</literal></para></entry>
|
|
<entry>
|
|
<para>Specifies the size for the allocated block of memory.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gasil"><title>See Also</title>
|
|
<para><olink targetptr="bdaxg">ldap_x_free</olink>, <olink targetptr="bdaxf">ldap_x_calloc
|
|
</olink> , <olink targetptr="bdaxm">ldap_x_realloc</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaxm"><title><function>ldap_x_realloc</function></title>
|
|
<para>The <function>ldap_x_realloc</function> function changes the size of
|
|
a block of memory.</para>
|
|
<sect3 id="gasih"><title>Syntax</title>
|
|
<programlisting>#include <ldap-extension.h>
|
|
void *ldap_x_realloc( void *ptr, size_t size );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gasjb"><title>Parameters</title>
|
|
<table frame="topbot" id="gasjl"><title><function>ldap_x_realloc</function> Function
|
|
Parameter</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ptr</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to a block of memory.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>size</literal></para></entry>
|
|
<entry>
|
|
<para>Specifies the new size of the block.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gasiv"><title>See Also</title>
|
|
<para><olink targetptr="bdaxg">ldap_x_free</olink>, <olink targetptr="bdaxf">ldap_x_calloc
|
|
</olink> , <olink targetptr="bdaxl">ldap_x_malloc</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaxn"><title><function>prldap_get_default_socket_info</function></title>
|
|
<indexterm>
|
|
<primary>C SDK functions</primary>
|
|
<secondary><function>prldap_*</function></secondary>
|
|
</indexterm><indexterm>
|
|
<primary><function>prldap_*</function></primary>
|
|
</indexterm>
|
|
<para>The <function>prldap_get_default_socket_info</function> function retrieves
|
|
default socket information.</para>
|
|
<sect3 id="gasig"><title>Syntax</title>
|
|
<programlisting>#include <ldappr.h>
|
|
int prldap_get_default_socket_info( LDAP *ld, PRLDAPSocketInfo *soip );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gasjn"><title>Parameters</title>
|
|
<table frame="topbot" id="gasjt"><title><function>prldap_get_default_socket_info</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>fd</literal></para></entry>
|
|
<entry>
|
|
<para>The session handle returned from <olink targetptr="bdaxr">prldap_init</olink>.
|
|
</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>soip</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to a structure containing socket specific information.</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gasjs"><title>Returns</title>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para>An LDAP API error code if an error occurs.</para></listitem>
|
|
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> is returned if <literal>ld
|
|
</literal> is <literal>NULL</literal>.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="gasit"><title>See Also</title>
|
|
<para><olink targetptr="bdaxt">prldap_set_default_socket_info</olink></para>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="bdaxo"><title><function>prldap_get_session_info</function></title>
|
|
<para>The <function>prldap_get_session_info</function> function retrieves
|
|
application-specific data.</para>
|
|
<sect3 id="gasis"><title>Syntax</title>
|
|
<programlisting>#include <ldappr.h>
|
|
int prldap_get_session_info( LDAP *ld, void *sessionarg,
|
|
PRLDAPSessionInfo *seip );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gasja"><title>Parameters</title>
|
|
<table frame="topbot" id="gasjd"><title><function>prldap_get_session_info</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>The session handle returned from <olink targetptr="bdaxr">prldap_init</olink>.
|
|
If <literal>NULL</literal>, the functions are installed as the default functions
|
|
for all new LDAP handles.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>seip</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to a structure with session information data.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gasjp"><title>Returns</title>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para>An LDAP API error code if an error occurs.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="gasje"><title>Description</title>
|
|
<para>The <function>prldap_get_session_option</function> function retrieves
|
|
an option for an LDAP session handle or a session argument that is passed
|
|
to the <literal>CONNECT</literal> , <literal>POLL</literal>, <literal>NEWHANDLE</literal>,
|
|
or <literal>DISPOSEHANDLE</literal> extended I/O callbacks.</para></sect3>
|
|
<sect3 id="gasjv"><title>See Also</title>
|
|
<para><olink targetptr="bdaxu">prldap_set_session_info</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaxp"><title><function>prldap_get_session_option</function></title>
|
|
<para>The <function>prldap_get_session_option</function> function retrieves
|
|
an option specific to the <literal>prldap</literal> layer.</para>
|
|
<sect3 id="gasla"><title>Syntax</title>
|
|
<programlisting>#include <ldappr.h>
|
|
int prldap_get_session_option( LDAP *ld, void *sessionarg,
|
|
int option, ... );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gasll"><title>Returns</title>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para>An LDAP API error code if an error occurs.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="gaskn"><title>Description</title>
|
|
<para>The <function>prldap_get_session_option</function> function retrieves
|
|
an option for an LDAP session handle or a session argument that is passed
|
|
to the <literal>CONNECT</literal> , <literal>POLL</literal>, <literal>NEWHANDLE</literal>,
|
|
or <literal>DISPOSEHANDLE</literal> extended I/O callbacks.</para></sect3>
|
|
<sect3 id="gaslm"><title>See Also</title>
|
|
<para><olink targetptr="bdaxv">prldap_set_session_option</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaxq"><title><function>prldap_get_socket_info</function></title>
|
|
<para>The <function>prldap_get_socket_info</function> function retrieves socket-specific
|
|
information based on parameters passed to the extended I/O callback functions.</para>
|
|
<sect3 id="gaskd"><title>Syntax</title>
|
|
<programlisting>#include <ldappr.h>
|
|
int prldap_get_socket_info( int fd, void *socketarg,
|
|
PRLDAPSocketInfo *soip );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gasle"><title>Parameters</title>
|
|
<table frame="topbot" id="gasjy"><title><function>prldap_get_socket_info</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>fd</literal></para></entry>
|
|
<entry>
|
|
<para>The session handle returned from <olink targetptr="bdaxr">prldap_init</olink>.
|
|
</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>soip</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to a structure containing socket information data.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gaskr"><title>Returns</title>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para>An LDAP API error code if an error occurs.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="gaskw"><title>See Also</title>
|
|
<para><olink targetptr="bdaxw">prldap_set_socket_info</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaxr"><title><function>prldap_init</function></title>
|
|
<para>The <function>prldap_init</function> function creates a new session
|
|
handle with Netscape Portable Runtime (NSPR) I/O, threading, support for IPv6,
|
|
and DNS functions installed.</para>
|
|
<sect3 id="gasli"><title>Syntax</title>
|
|
<programlisting>#include <ldappr.h>
|
|
LDAP * prldap_init( const char *defhost, int defport, int shared );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gaskp"><title>Parameters</title>
|
|
<table frame="topbot" id="gaskh"><title><function>prldap_init</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>defhost</literal></para></entry>
|
|
<entry>
|
|
<para>Space-delimited list of one or more host names (or IP address in dotted
|
|
notation, such as <literal>192.168.0.99</literal>) of the LDAP servers that
|
|
you want the LDAP client to connect to. The names can be in <replaceable>hostname
|
|
</replaceable>: <replaceable>portnumber</replaceable> format (in which case, <replaceable>
|
|
portnumber</replaceable> overrides the port number specified by the <parameter>defport
|
|
</parameter> argument.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>defport</literal></para></entry>
|
|
<entry>
|
|
<para>Default port number of the LDAP server. To specify the standard LDAP
|
|
port (port 389), use <literal>LDAP_PORT</literal> as the value for this parameter.
|
|
</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>shared</literal></para></entry>
|
|
<entry>
|
|
<para>Pass a non-zero value if you plan to use this LDAP handle for more than
|
|
one thread.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gaslb"><title>Returns</title>
|
|
<itemizedlist>
|
|
<listitem><para>Pointer to LDAP session handle if successful.</para></listitem>
|
|
<listitem><para><literal>NULL</literal> if an error occurs.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="gaskx"><title>Description</title>
|
|
<para>To be able to use LDAP over Internet Protocol, version 6, <acronym>IPv6</acronym>,
|
|
this function should be used rather than <olink targetptr="bdasv">ldap_init</olink>.
|
|
</para></sect3>
|
|
<sect3 id="gaslf"><title>See Also</title>
|
|
<para><olink targetptr="bdaxs">prldap_install_routines</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaxs"><title><function>prldap_install_routines</function></title>
|
|
<para>The <function>prldap_install_routines</function> function installs Netscape
|
|
Portable Runtime (NSPR) I/O, threading, and DNS functions so they can be used
|
|
by the LDAP session handle.</para>
|
|
<sect3 id="gaslh"><title>Syntax</title>
|
|
<programlisting>#include <ldappr.h>
|
|
int prldap_install_routines( LDAP *ld, int shared );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gaskb"><title>Parameters</title>
|
|
<table frame="topbot" id="gaske"><title><function>prldap_install_routines</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>The session handle returned from <olink targetptr="bdaxr">prldap_init</olink>.
|
|
If <literal>NULL</literal>, the functions are installed as the default functions
|
|
for all new LDAP handles.</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>shared</literal></para></entry>
|
|
<entry>
|
|
<para>Pass a non-zero value if you plan to use this LDAP handle for more than
|
|
one thread.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gasko"><title>Returns</title>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para>An LDAP API error code if an error occurs.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="gaska"><title>See Also</title>
|
|
<para><olink targetptr="bdaxr">prldap_init</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaxt"><title><function>prldap_set_default_socket_info</function></title>
|
|
<para>The <function>prldap_set_default_socket_info</function> function sets
|
|
default socket information.</para>
|
|
<sect3 id="gaslc"><title>Syntax</title>
|
|
<programlisting>#include <ldappr.h>
|
|
int prldap_set_default_socket_info( LDAP *ld, PRLDAPSocketInfo *soip );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gaskq"><title>Parameters</title>
|
|
<table frame="topbot" id="gasku"><title><function>prldap_set_default_socket_info</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>fd</literal></para></entry>
|
|
<entry>
|
|
<para>The session handle returned from <olink targetptr="bdaxr">prldap_init</olink>.
|
|
</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>soip</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to a structure containing socket specific information.</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gaskv"><title>Returns</title>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para><errorcode>LDAP_PARAM_ERROR</errorcode> is returned if <literal>ld
|
|
</literal> is <literal>NULL</literal>.</para></listitem>
|
|
<listitem><para>An LDAP API error code if an error occurs.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="gaslj"><title>See Also</title>
|
|
<para><olink targetptr="bdaxq">prldap_get_socket_info</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaxu"><title><function>prldap_set_session_info</function></title>
|
|
<para>The <function>prldap_set_session_info</function> function sets application-specific
|
|
data.</para>
|
|
<sect3 id="gaslk"><title>Syntax</title>
|
|
<programlisting>#include <ldappr.h>
|
|
int prldap_set_session_info( LDAP *ld, void *sessionarg,
|
|
PRLDAPSessionInfo *seip );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gaslg"><title>Parameters</title>
|
|
<table frame="topbot" id="gaskz"><title><function>prldap_set_session_info</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>The session handle returned from <olink targetptr="bdaxr">prldap_init</olink>.
|
|
</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>seip</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to a structure containing session information data.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gaskm"><title>Returns</title>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para>An LDAP API error code if an error occurs.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="gaskt"><title>Description</title>
|
|
<para>The <function>prldap_set_session_info</function> function sets application-specific
|
|
data for an LDAP session handle or a session argument that is passed to the
|
|
<literal>CONNECT</literal>, <literal>POLL</literal>, <literal>NEWHANDLE</literal>,
|
|
or <literal>DISPOSEHANDLE</literal> extended I/O callbacks.</para></sect3>
|
|
<sect3 id="gaskj"><title>See Also</title>
|
|
<para><olink targetptr="bdaxo">prldap_get_session_info</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaxv"><title><function>prldap_set_session_option</function></title>
|
|
<para>The <function>prldap_set_session_option</function> function sets a session
|
|
option specific to the <literal>prldap</literal> layer.</para>
|
|
<sect3 id="gasjx"><title>Syntax</title>
|
|
<programlisting>#include <ldappr.h>
|
|
int prldap_set_session_option( LDAP *ld, void *sessionarg,
|
|
int option, ... );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gasjz"><title>Parameters</title>
|
|
<table frame="topbot" id="gasld"><title><function>prldap_set_session_option</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>ld</literal></para></entry>
|
|
<entry>
|
|
<para>The session handle returned from <olink targetptr="bdaxr">prldap_init</olink>.
|
|
</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>option</literal></para></entry>
|
|
<entry></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gaskc"><title>Returns</title>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para>An LDAP API error code if an error occurs.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="gaskf"><title>Description</title>
|
|
<para>The <function>prldap_set_session_option</function> function sets an
|
|
option for an LDAP session handle or a session argument that is passed to
|
|
the <literal>CONNECT</literal> , <literal>POLL</literal>, <literal>NEWHANDLE</literal>,
|
|
or <literal>DISPOSEHANDLE</literal> extended I/O callbacks.</para></sect3>
|
|
<sect3 id="gaskl"><title>See Also</title>
|
|
<para><olink targetptr="bdaxp">prldap_get_session_option</olink></para></sect3>
|
|
</sect2>
|
|
<sect2 id="bdaxw"><title><function>prldap_set_socket_info</function></title>
|
|
<para>The <function>prldap_set_socket_info</function> function sets socket
|
|
information.</para>
|
|
<sect3 id="gaskg"><title>Syntax</title>
|
|
<programlisting>#include <ldappr.h>
|
|
int prldap_set_socket_info( int fd, void *socketarg,
|
|
PRLDAPSocketInfo *soip );</programlisting>
|
|
</sect3>
|
|
<sect3 id="gasks"><title>Parameters</title>
|
|
<table frame="topbot" id="gaski"><title><function>prldap_set_socket_info</function> Function
|
|
Parameters</title>
|
|
<tgroup cols="2"><colspec colnum="1" colwidth="50*"><colspec colnum="2"
|
|
colwidth="50*">
|
|
<thead>
|
|
<row>
|
|
<entry>
|
|
<para>Parameter</para></entry>
|
|
<entry>
|
|
<para>Description</para></entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep="1">
|
|
<entry>
|
|
<para><literal>fd</literal></para></entry>
|
|
<entry>
|
|
<para>The session handle returned from <olink targetptr="bdaxr">prldap_init</olink>.
|
|
</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para><literal>soip</literal></para></entry>
|
|
<entry>
|
|
<para>Pointer to a structure containing socket information data.</para></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</sect3>
|
|
<sect3 id="gaskk"><title>Returns</title>
|
|
<itemizedlist>
|
|
<listitem><para><errorcode>LDAP_SUCCESS</errorcode> if successful.</para>
|
|
</listitem>
|
|
<listitem><para>An LDAP API error code if an error occurs.</para></listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
<sect3 id="gasky"><title>Description</title>
|
|
<para>The <function>prldap_set_socket_info</function> function sets socket-specific
|
|
information based on parameters passed to the extended I/O callback functions.
|
|
For more information, see the <literal>ldappr.h</literal> header file.</para>
|
|
</sect3>
|
|
<sect3 id="gasnf"><title>See Also</title>
|
|
<para><olink targetptr="bdaxq">prldap_get_socket_info</olink></para></sect3>
|
|
</sect2>
|
|
</sect1>
|
|
</chapter>
|