Mozilla LDAP SDK Programmer's Guide/LDAP C SDK Function Reference: Difference between revisions

Jump to navigation Jump to search

Mozilla LDAP SDK Programmer's Guide/LDAP C SDK Function Reference (view source)

Revision as of 10:06, 8 February 2011

6,958 bytes added ,  8 February 2011
Typo
(Moving here from my user page)
 
(Typo)
Line 676: Line 676:
== Functions Alphabetically  ==
== Functions Alphabetically  ==


This sections lists the functions in alphabetical order.  
This section lists the functions in alphabetical order.  


=== ber_alloc()  ===
=== ber_alloc()  ===
Line 682: Line 682:
The ber_alloc() function is used to allocate a new Basic Encoding Rules (BER) BerElement structure.  
The ber_alloc() function is used to allocate a new Basic Encoding Rules (BER) BerElement structure.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;lber.h&gt;
<pre>#include &lt;lber.h&gt;
   BerElement* ber_alloc( void );</pre>  
   BerElement* ber_alloc( void );</pre>  
'''Parameters'''


'''Parameters'''
<br> This function has no parameters.


<br> '''Returns'''


This function has no parameters.
<br>
 
 
'''Returns'''
 


*If successful, a pointer to the newly allocated BerElement structure.  
*If successful, a pointer to the newly allocated BerElement structure.  
*If unsuccessful, a <tt>NULL</tt> pointer.
*If unsuccessful, a <tt>NULL</tt> pointer.


<br> '''Description'''


'''Description'''
<br> ber_alloc() is used to allocate a new BerElement structure for encoding data with the BER.  
 
 
ber_alloc() is used to allocate a new BerElement structure for encoding data with the BER.  
 
 
'''See Also'''


<br> '''See Also'''


ber_printf(), BerElement  
<br> ber_printf(), BerElement  


=== ber_alloc_t()  ===
=== ber_alloc_t()  ===
Line 716: Line 708:
The ber_alloc_t() function constructs and returns a BerElement structure.  
The ber_alloc_t() function constructs and returns a BerElement structure.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;lber.h&gt;
<pre>#include &lt;lber.h&gt;
   BerElement* ber_alloc_t( int options );</pre>  
   BerElement* ber_alloc_t( int options );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ber_alloc_t() Function Parameter"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ber_alloc_t() Function Parameter"
Line 735: Line 725:
|}
|}


<br> '''Returns'''


'''Returns'''
<br>
 


*If successful, a pointer to the newly allocated BerElement structure.  
*If successful, a pointer to the newly allocated BerElement structure.  
*If unsuccessful, a <tt>NULL</tt> pointer.
*If unsuccessful, a <tt>NULL</tt> pointer.


<br> '''Description'''


'''Description'''
<br> This function is the same as ber_alloc() except it has an option.  
 
 
This function is the same as ber_alloc() except it has an option.  
 
 
'''See Also'''


<br> '''See Also'''


ber_printf(), BerElement  
<br> ber_printf(), BerElement  


=== ber_bvecfree()  ===
=== ber_bvecfree()  ===
Line 758: Line 744:
The ber_bvecfree() function frees an array of berval structures.  
The ber_bvecfree() function frees an array of berval structures.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;lber.h&gt;
<pre>#include &lt;lber.h&gt;
   void ber_bvecfree( struct berval **bv );</pre>  
   void ber_bvecfree( struct berval **bv );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ber_bvecfree() Function Parameter"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ber_bvecfree() Function Parameter"
Line 777: Line 761:
|}
|}


<br> '''Description'''


'''Description'''
<br> Each berval in the array is freed using ber_bvfree(), and then the array itself is freed.  
 
 
Each berval in the array is freed using ber_bvfree(), and then the array itself is freed.  
 
 
'''See Also'''


<br> '''See Also'''


ber_bvfree()  
<br> ber_bvfree()  


=== ber_bvdup()  ===
=== ber_bvdup()  ===
Line 793: Line 773:
The ber_bvdup() function returns a copy of a berval structure.  
The ber_bvdup() function returns a copy of a berval structure.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;lber.h&gt;
<pre>#include &lt;lber.h&gt;
   berval* ber_bvdup( const struct berval *bv );</pre>  
   berval* ber_bvdup( const struct berval *bv );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ber_bvdup() Function Parameter"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ber_bvdup() Function Parameter"
Line 812: Line 790:
|}
|}


<br> '''Returns'''


'''Returns'''
<br>
 


*If successful, a pointer to the newly allocated berval structure.  
*If successful, a pointer to the newly allocated berval structure.  
*If unsuccessful, a <tt>NULL</tt> pointer.
*If unsuccessful, a <tt>NULL</tt> pointer.


<br> '''Description'''


'''Description'''
<br> The ber_bvdup() function returns a copy of a berval structure. The data referenced in the structure is also duplicated. The <tt>bv_val</tt> field in the returned berval points to a different area of memory than the <tt>bv_val</tt> field in the argument berval.  
 
 
The ber_bvdup() function returns a copy of a berval structure. The data referenced in the structure is also duplicated. The <tt>bv_val</tt> field in the returned berval points to a different area of memory than the <tt>bv_val</tt> field in the argument berval.  


=== ber_bvfree()  ===
=== ber_bvfree()  ===
Line 829: Line 805:
The ber_bvfree() function frees a berval structure.  
The ber_bvfree() function frees a berval structure.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;lber.h&gt;
<pre>#include &lt;lber.h&gt;
   void ber_bvfree( struct berval *bv );</pre>  
   void ber_bvfree( struct berval *bv );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ber_bvfree() Function Parameter"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ber_bvfree() Function Parameter"
Line 848: Line 822:
|}
|}


<br> '''Description'''


'''Description'''
<br> The ber_bvfree() function frees a berval structure from memory. Call this function to free a berval passed back from the ldap_extended_operation_s() , ldap_parse_extended_result(), ldap_sasl_bind_s(), or ldap_parse_sasl_bind_result() functions.  
 
 
The ber_bvfree() function frees a berval structure from memory. Call this function to free a berval passed back from the ldap_extended_operation_s() , ldap_parse_extended_result(), ldap_sasl_bind_s(), or ldap_parse_sasl_bind_result() functions.  
 
 
'''See Also'''


<br> '''See Also'''


ldap_extended_operation_s(), ldap_parse_extended_result(), ldap_sasl_bind_s() , ldap_parse_sasl_bind_result()  
<br> ldap_extended_operation_s(), ldap_parse_extended_result(), ldap_sasl_bind_s() , ldap_parse_sasl_bind_result()  


=== ber_dup()  ===
=== ber_dup()  ===
Line 864: Line 834:
The ber_dup() function returns a copy of a BerElement structure.  
The ber_dup() function returns a copy of a BerElement structure.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;lber.h&gt;
<pre>#include &lt;lber.h&gt;
   BerElement* ber_dup( BerElement *ber );</pre>  
   BerElement* ber_dup( BerElement *ber );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ber_dup() Function Parameter"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ber_dup() Function Parameter"
Line 883: Line 851:
|}
|}


<br> '''Returns'''


'''Returns'''
<br>
 


*If successful, a pointer to the newly allocated BerElement structure.  
*If successful, a pointer to the newly allocated BerElement structure.  
*If unsuccessful, a <tt>NULL</tt> pointer.
*If unsuccessful, a <tt>NULL</tt> pointer.


<br> '''Description'''


'''Description'''
<br> The ber_dup() function returns a copy of a BerElement structure.  
 
 
The ber_dup() function returns a copy of a BerElement structure.  


=== ber_first_element()  ===
=== ber_first_element()  ===
Line 900: Line 866:
The ber_first_element() function is used to return the tag and length of the first element in a set or sequence.  
The ber_first_element() function is used to return the tag and length of the first element in a set or sequence.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;lber.h&gt;
<pre>#include &lt;lber.h&gt;
unsigned long ber_first_element( BerElement *ber, unsigned long *len,
unsigned long ber_first_element( BerElement *ber, unsigned long *len,
   char **last );</pre>  
   char **last );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ber_first_element() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ber_first_element() Function Parameters"
Line 926: Line 890:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> <tt>NULL</tt> pointer is returned on error.


<br> '''Description'''


<tt>NULL</tt> pointer is returned on error.  
<br> The ber_first_element() 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 ber_next_element() .  


<br> '''See Also'''


'''Description'''
<br> ber_next_element()


=== ber_flatten()  ===


The ber_first_element() 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 ber_next_element() .  
The ber_flatten() function allocates a berval structure whose contents are taken from a source BerElement structure.  


<br> '''Syntax'''
<pre>#include &lt;lber.h&gt;
  int ber_flatten( BerElement *ber, struct berval **bvPtr );</pre>
'''Parameters'''


'''See Also'''
<br>  
 
 
ber_next_element()
 
=== ber_flatten()  ===
 
The ber_flatten() function allocates a berval structure whose contents are taken from a source BerElement structure.
 
 
'''Syntax'''
 
<pre>#include &lt;lber.h&gt;
  int ber_flatten( BerElement *ber, struct berval **bvPtr );</pre>
 
'''Parameters'''
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ber_flatten() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ber_flatten() Function Parameters"
Line 970: Line 926:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> Returns <tt>0</tt> on success and <tt>-1</tt> on error.  
 
 
Returns <tt>0</tt> on success and <tt>-1</tt> on error.
 
 
'''Description'''
 
 
This function is usually used when encoding LDAP v3 controls or extended operations values.  


<br> '''Description'''


'''See Also'''
<br> This function is usually used when encoding LDAP v3 controls or extended operations values.


<br> '''See Also'''


ber_bvfree()  
<br> ber_bvfree()  


=== ber_free()  ===
=== ber_free()  ===
Line 992: Line 942:
The ber_free() function frees a BerElement structure previously allocated with ber_alloc() , ber_alloc_t(), ber_init(), or the ldap_first_attribute() and ldap_next_attribute() search functions.  
The ber_free() function frees a BerElement structure previously allocated with ber_alloc() , ber_alloc_t(), ber_init(), or the ldap_first_attribute() and ldap_next_attribute() search functions.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
   void ber_free( BerElement *ber, int freebuf );</pre>  
   void ber_free( BerElement *ber, int freebuf );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ber_free() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ber_free() Function Parameters"
Line 1,014: Line 962:
|}
|}


<br> '''Description'''


'''Description'''
<br> This function frees a BerElement 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.  
 
 
This function frees a BerElement 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.  


'''Note:''' To retrieve attributes from a search result entry, you need to call either the ldap_first_attribute() or ldap_next_attribute() function. When freeing structures allocated by these functions, you should specify <tt>0</tt> for the <tt>freebuf</tt> argument. Otherwise, it should always be set to <tt>1</tt>.  
'''Note:''' To retrieve attributes from a search result entry, you need to call either the ldap_first_attribute() or ldap_next_attribute() function. When freeing structures allocated by these functions, you should specify <tt>0</tt> for the <tt>freebuf</tt> argument. Otherwise, it should always be set to <tt>1</tt>.  


<br> '''Example'''


'''Example'''
<br> the following example frees the BerElement structure allocated by the ldap_first_attribute() function.  
 
 
the following example frees the BerElement structure allocated by the ldap_first_attribute() function.  
<pre>LDAP *ld;
<pre>LDAP *ld;
LDAPMessage *a, *e;
LDAPMessage *a, *e;
Line 1,042: Line 986:
}
}
...</pre>  
...</pre>  
'''See Also'''


'''See Also'''
<br> ber_alloc(), ber_alloc_t() , ber_init(), ldap_first_attribute(), ldap_next_attribute()  
 
 
ber_alloc(), ber_alloc_t() , ber_init(), ldap_first_attribute(), ldap_next_attribute()  


=== ber_get_boolean()  ===
=== ber_get_boolean()  ===
Line 1,052: Line 994:
The ber_get_boolean() function is used to read a boolean value.  
The ber_get_boolean() function is used to read a boolean value.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;lber.h&gt;
<pre>#include &lt;lber.h&gt;
unsigned long ber_get_boolean( BerElement *ber,
unsigned long ber_get_boolean( BerElement *ber,
   int *boolval );</pre>  
   int *boolval );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ber_get_boolean() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ber_get_boolean() Function Parameters"
Line 1,075: Line 1,015:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> The value is returned on success and <tt>LBER_ERROR</tt> (<tt>-1</tt>) on failure.  
 
 
The value is returned on success and <tt>LBER_ERROR</tt> (<tt>-1</tt>) on failure.  


=== ber_get_int()  ===
=== ber_get_int()  ===
Line 1,085: Line 1,023:
The ber_get_int() function tries to interpret the next element as an integer, returning the result in <tt>num</tt>.  
The ber_get_int() function tries to interpret the next element as an integer, returning the result in <tt>num</tt>.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;lber.h&gt;
<pre>#include &lt;lber.h&gt;
unsigned long ber_get_int( BerElement *ber, int *num );</pre>  
unsigned long ber_get_int( BerElement *ber, int *num );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ber_get_int() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ber_get_int() Function Parameters"
Line 1,107: Line 1,043:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> The tag of whatever it finds is returned on success and <tt>LBER_ERROR</tt> (<tt>-1</tt>) on failure.  
 
 
The tag of whatever it finds is returned on success and <tt>LBER_ERROR</tt> (<tt>-1</tt>) on failure.  


=== ber_get_next()  ===
=== ber_get_next()  ===
Line 1,117: Line 1,051:
The ber_get_next() function reads the next BER element.  
The ber_get_next() function reads the next BER element.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;lber.h&gt;
<pre>#include &lt;lber.h&gt;
unsigned long ber_get_next( Sockbuf *sb, unsigned long *len,
unsigned long ber_get_next( Sockbuf *sb, unsigned long *len,
   BerElement *ber );</pre>  
   BerElement *ber );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ber_get_next() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ber_get_next() Function Parameters"
Line 1,143: Line 1,075:
|}
|}


<br> '''Description'''


'''Description'''
<br> ber_get_next() strips off and returns the leading tag, strips off and returns the length of the entire element, and sets up a pointer to <tt>ber</tt> for subsequent calls to decode the element.  
 
 
ber_get_next() strips off and returns the leading tag, strips off and returns the length of the entire element, and sets up a pointer to <tt>ber</tt> for subsequent calls to decode the element.  


=== ber_get_next_buffer()  ===
=== ber_get_next_buffer()  ===
Line 1,157: Line 1,087:
'''Note:''' ber_get_next_buffer_ext() is a new version of the ber_get_next_buffer() function. If you are writing a new LDAP client, use ber_get_next_buffer_ext() .  
'''Note:''' ber_get_next_buffer_ext() is a new version of the ber_get_next_buffer() function. If you are writing a new LDAP client, use ber_get_next_buffer_ext() .  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;lber.h&gt;
<pre>#include &lt;lber.h&gt;
unsigned long ber_get_next_buffer_ext( void *buffer,
unsigned long ber_get_next_buffer_ext( void *buffer,
   size_t buffer_size, unsigned long *len, BerElement *ber,
   size_t buffer_size, unsigned long *len, BerElement *ber,
   unsigned long *Bytes_Scanned, Sockbuf *sb );</pre>  
   unsigned long *Bytes_Scanned, Sockbuf *sb );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ber_get_next_buffer_ext() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ber_get_next_buffer_ext() Function Parameters"
Line 1,197: Line 1,125:
The ber_get_null() function is used to read a <tt>NULL</tt> element.  
The ber_get_null() function is used to read a <tt>NULL</tt> element.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;lber.h&gt;
<pre>#include &lt;lber.h&gt;
unsigned long ber_get_null( BerElement *ber );</pre>  
unsigned long ber_get_null( BerElement *ber );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ber_get_null() Function Parameter"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ber_get_null() Function Parameter"
Line 1,216: Line 1,142:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> Returns the tag of the element it skips over.  
 
 
Returns the tag of the element it skips over.  


=== ber_get_option()  ===
=== ber_get_option()  ===
Line 1,226: Line 1,150:
The ber_get_option() function is used to retrieve information about the API and about the specific implementation being used.  
The ber_get_option() function is used to retrieve information about the API and about the specific implementation being used.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;lber.h&gt;
<pre>#include &lt;lber.h&gt;
int ber_get_option( BerElement *ber, int option, void *value );</pre>  
int ber_get_option( BerElement *ber, int option, void *value );</pre>  
Line 1,235: Line 1,157:
The ber_get_stringa() function is used to allocate memory space into which an octet string is read.  
The ber_get_stringa() function is used to allocate memory space into which an octet string is read.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;lber.h&gt;
<pre>#include &lt;lber.h&gt;
unsigned long ber_get_stringa( BerElement *ber, char **buf );</pre>  
unsigned long ber_get_stringa( BerElement *ber, char **buf );</pre>  
Line 1,244: Line 1,164:
The ber_get_stringal() function is used to allocate memory space into which an octet string and its length are read.  
The ber_get_stringal() function is used to allocate memory space into which an octet string and its length are read.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;lber.h&gt;
<pre>#include &lt;lber.h&gt;
unsigned long ber_get_stringal( BerElement *ber, struct berval **bv );</pre>  
unsigned long ber_get_stringal( BerElement *ber, struct berval **bv );</pre>  
'''Description'''


'''Description'''
<br> It takes a berval structure, and returns the result in this parameter.  
 
 
It takes a berval structure, and returns the result in this parameter.  


=== ber_get_stringb()  ===
=== ber_get_stringb()  ===
Line 1,259: Line 1,175:
The ber_get_stringb() function is used to read an octet string into a preallocated buffer.  
The ber_get_stringb() function is used to read an octet string into a preallocated buffer.  


 
<br> '''Syntax'''  
'''Syntax'''
<pre>#include &lt;lber.h&gt;
 
<pre>#include &lt;lber.h&gt;
unsigned long ber_get_stringb( BerElement *ber, char *buf,
unsigned long ber_get_stringb( BerElement *ber, char *buf,
   unsigned long *len );</pre>  
   unsigned long *len );</pre>  
'''Description'''


'''Description'''
<br> The <tt>len</tt> 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 <tt>NULL</tt> byte.  
 
 
The <tt>len</tt> 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 <tt>NULL</tt> byte.  


=== ber_init()  ===
=== ber_init()  ===
Line 1,275: Line 1,187:
The ber_init() function constructs a new BerElement.  
The ber_init() function constructs a new BerElement.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;lber.h&gt;
<pre>#include &lt;lber.h&gt;
BerElement * ber_init( const struct berval *bv );</pre>  
BerElement * ber_init( const struct berval *bv );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ber_init() Function Parameter"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ber_init() Function Parameter"
Line 1,294: Line 1,204:
|}
|}


<br> '''Returns'''


'''Returns'''
<br>
 


*If successful, returns a new BerElement containing a copy of the data in the <tt>bv</tt> argument.  
*If successful, returns a new BerElement containing a copy of the data in the <tt>bv</tt> argument.  
Line 1,305: Line 1,215:
The ber_init_w_nullchar() function constructs a new BerElement with a <tt>NULL</tt> character.  
The ber_init_w_nullchar() function constructs a new BerElement with a <tt>NULL</tt> character.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;lber.h&gt;
<pre>#include &lt;lber.h&gt;
void ber_init_w_nullchar( BerElement *ber, int options );</pre>  
void ber_init_w_nullchar( BerElement *ber, int options );</pre>  
Line 1,314: Line 1,222:
The ber_next_element() function is used to return the tag and length of the next element in a set or sequence.  
The ber_next_element() function is used to return the tag and length of the next element in a set or sequence.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;lber.h&gt;
<pre>#include &lt;lber.h&gt;
unsigned long ber_next_element( BerElement *ber, unsigned long *len,
unsigned long ber_next_element( BerElement *ber, unsigned long *len,
   char *last );</pre>  
   char *last );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ber_next_element() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ber_next_element() Function Parameters"
Line 1,340: Line 1,246:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> <tt>NULL</tt> pointer is returned on error.  
 
 
<tt>NULL</tt> pointer is returned on error.
 
 
'''Description'''
 
 
The ber_next_element() function is used to return the tag and length of the first element in a set or sequence.  


<br> '''Description'''


'''See Also'''
<br> The ber_next_element() function is used to return the tag and length of the first element in a set or sequence.


<br> '''See Also'''


ber_first_element()  
<br> ber_first_element()  


=== ber_peek_tag()  ===
=== ber_peek_tag()  ===
Line 1,362: Line 1,262:
The ber_peek_tag() function returns the tag of the next element to be parsed in the supplied BerElement structure.  
The ber_peek_tag() function returns the tag of the next element to be parsed in the supplied BerElement structure.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;lber.h&gt;
<pre>#include &lt;lber.h&gt;
unsigned long ber_peek_tag( BerElement *ber, unsigned long *len );</pre>  
unsigned long ber_peek_tag( BerElement *ber, unsigned long *len );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ber_peek_tag() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ber_peek_tag() Function Parameters"
Line 1,384: Line 1,282:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> Returns the tag of the next element to be read in the BerElement structure. <tt>LBER_DEFAULT</tt> is returned if there is no further data to be read.  
 
 
Returns the tag of the next element to be read in the BerElement structure. <tt>LBER_DEFAULT</tt> is returned if there is no further data to be read.  


=== ber_printf()  ===
=== ber_printf()  ===
Line 1,394: Line 1,290:
The ber_printf() function encodes a BER element.  
The ber_printf() function encodes a BER element.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;lber.h&gt;
<pre>#include &lt;lber.h&gt;
ber_printf( BerElement *ber, const char *fmt, ... );</pre>  
ber_printf( BerElement *ber, const char *fmt, ... );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ber_printf() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ber_printf() Function Parameters"
Line 1,432: Line 1,326:
|}
|}


<br> '''Description'''


'''Description'''
<br> State information is kept with the <tt>ber</tt> parameter so multiple calls can be made to ber_printf() to append things to the end of the BerElement. ber_printf() interprets and formats its arguments according to the format string <tt>fmt</tt>. Each character in <tt>fmt</tt> refers to an argument to ber_printf() .  
 
 
State information is kept with the <tt>ber</tt> parameter so multiple calls can be made to ber_printf() to append things to the end of the BerElement. ber_printf() interprets and formats its arguments according to the format string <tt>fmt</tt>. Each character in <tt>fmt</tt> refers to an argument to ber_printf() .  
 
 
'''Returns'''


<br> '''Returns'''


<tt>-1</tt> if there is an error during encoding.  
<br> <tt>-1</tt> if there is an error during encoding.  


=== ber_put_bitstring()  ===
=== ber_put_bitstring()  ===
Line 1,448: Line 1,338:
The ber_put_bitstring() function writes a bitstring value to the given BerElement.  
The ber_put_bitstring() function writes a bitstring value to the given BerElement.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;lber.h&gt;
<pre>#include &lt;lber.h&gt;
int ber_put_bitstring( BerElement *ber, char *str,
int ber_put_bitstring( BerElement *ber, char *str,
   unsigned long bitlen, unsigned long tag );</pre>  
   unsigned long bitlen, unsigned long tag );</pre>  
'''Description'''


'''Description'''
<br> The ber_put_bitstring() function writes <tt>bitlen</tt> bits starting at <tt>str</tt> as a bitstring value to the given BerElement.  
 
 
The ber_put_bitstring() function writes <tt>bitlen</tt> bits starting at <tt>str</tt> as a bitstring value to the given BerElement.  


=== ber_put_boolean()  ===
=== ber_put_boolean()  ===
Line 1,464: Line 1,350:
The ber_put_boolean() function writes a boolean value to a BerElement.  
The ber_put_boolean() function writes a boolean value to a BerElement.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;lber.h&gt;
<pre>#include &lt;lber.h&gt;
int ber_put_boolean( BerElement *ber, int boolval, unsigned long tag );</pre>  
int ber_put_boolean( BerElement *ber, int boolval, unsigned long tag );</pre>  
'''Description'''


'''Description'''
<br> The boolean value is given by <tt>boolval</tt> to the BerElement.  
 
 
The boolean value is given by <tt>boolval</tt> to the BerElement.  


=== ber_put_enum()  ===
=== ber_put_enum()  ===
Line 1,479: Line 1,361:
The ber_put_enum() function writes an enumerated value to a BerElement.  
The ber_put_enum() function writes an enumerated value to a BerElement.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;lber.h&gt;
<pre>#include &lt;lber.h&gt;
int ber_put_enum( BerElement *ber, long num, unsigned long tag );</pre>  
int ber_put_enum( BerElement *ber, long num, unsigned long tag );</pre>  
Line 1,488: Line 1,368:
The ber_put_int() function writes an integer to a BerElement.  
The ber_put_int() function writes an integer to a BerElement.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;lber.h&gt;
<pre>#include &lt;lber.h&gt;
int ber_put_int( BerElement *ber, long num, unsigned long tag );</pre>  
int ber_put_int( BerElement *ber, long num, unsigned long tag );</pre>  
Line 1,497: Line 1,375:
The ber_put_null() function writes a writes a <tt>NULL</tt> element to a BerElement.  
The ber_put_null() function writes a writes a <tt>NULL</tt> element to a BerElement.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;lber.h&gt;
<pre>#include &lt;lber.h&gt;
int ber_put_null( BerElement *ber, unsigned long tag );</pre>  
int ber_put_null( BerElement *ber, unsigned long tag );</pre>  
Line 1,506: Line 1,382:
The ber_put_ostring() function writes bytes to a BerElement() as an octet string.  
The ber_put_ostring() function writes bytes to a BerElement() as an octet string.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;lber.h&gt;
<pre>#include &lt;lber.h&gt;
int ber_put_ostring( BerElement *ber, char *str,
int ber_put_ostring( BerElement *ber, char *str,
Line 1,516: Line 1,390:
The ber_put_seq() function puts a sequence to a BerElement.  
The ber_put_seq() function puts a sequence to a BerElement.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;lber.h&gt;
<pre>#include &lt;lber.h&gt;
int ber_put_seq( BerElement *ber );</pre>  
int ber_put_seq( BerElement *ber );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ber_put_seq() Function Parameter"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ber_put_seq() Function Parameter"
Line 1,535: Line 1,407:
|}
|}


<br> '''Description'''


'''Description'''
<br> The ber_start_seq() function is used to start a sequence in the BerElement. The end of the sequence is marked by the nearest matching call to ber_put_seq().  
 
 
The ber_start_seq() function is used to start a sequence in the BerElement. The end of the sequence is marked by the nearest matching call to ber_put_seq().  


=== ber_put_set()  ===
=== ber_put_set()  ===
Line 1,545: Line 1,415:
The ber_put_set() function puts a set to a BerElement.  
The ber_put_set() function puts a set to a BerElement.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;lber.h&gt;
<pre>#include &lt;lber.h&gt;
int ber_put_set( BerElement *ber );</pre>  
int ber_put_set( BerElement *ber );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ber_put_set() Function Parameter"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ber_put_set() Function Parameter"
Line 1,564: Line 1,432:
|}
|}


<br> '''Description'''


'''Description'''
<br> The ber_start_set() function is used to start a set in the BerElement. The end of the set is marked by the nearest matching call to ber_put_set().


 
=== ber_put_string()  ===
The ber_start_set() function is used to start a set in the BerElement. The end of the set is marked by the nearest matching call to ber_put_set().
 
=== ber_put_string()  ===


The ber_put_string() function writes a <tt>NULL</tt> terminated string (minus the terminating <tt>0</tt>) to a BerElement as an octet string.  
The ber_put_string() function writes a <tt>NULL</tt> terminated string (minus the terminating <tt>0</tt>) to a BerElement as an octet string.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;lber.h&gt;
<pre>#include &lt;lber.h&gt;
int ber_put_string( BerElement *ber, char *str, unsigned long tag );</pre>  
int ber_put_string( BerElement *ber, char *str, unsigned long tag );</pre>  
=== ber_read()  ===
=== ber_read()  ===


 
'''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;lber.h&gt;
<pre>#include &lt;lber.h&gt;
long ber_read( BerElement *ber, char *buf, unsigned long len );</pre>  
long ber_read( BerElement *ber, char *buf, unsigned long len );</pre>  
=== ber_reset()  ===
=== ber_reset()  ===


 
'''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;lber.h&gt;
<pre>#include &lt;lber.h&gt;
void ber_reset( BerElement *ber, int was_writing );</pre>  
void ber_reset( BerElement *ber, int was_writing );</pre>  
Line 1,597: Line 1,457:
The ber_scanf() function decodes a BerElement.  
The ber_scanf() function decodes a BerElement.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;lber.h&gt;
<pre>#include &lt;lber.h&gt;
unsigned long ber_scanf( BerElement *ber, const char *fmt, ... );</pre>  
unsigned long ber_scanf( BerElement *ber, const char *fmt, ... );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ber_scanf() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ber_scanf() Function Parameters"
Line 1,637: Line 1,495:
|}
|}


<br> '''Description'''


'''Description'''
<br> ber_scanf() reads from <tt>ber</tt>, interprets the bytes according to the format string <tt>fmt</tt>, 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.  
 
 
ber_scanf() reads from <tt>ber</tt>, interprets the bytes according to the format string <tt>fmt</tt>, 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.  
 
 
'''See Also'''


<br> '''See Also'''


ber_printf()  
<br> ber_printf()  


=== ber_set_option()  ===
=== ber_set_option()  ===


 
'''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;lber.h&gt;
<pre>#include &lt;lber.h&gt;
int ber_set_option( BerElement *ber, int option, void *value );</pre>  
int ber_set_option( BerElement *ber, int option, void *value );</pre>  
=== ber_set_string_translators()  ===
=== ber_set_string_translators()  ===


 
'''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;lber.h&gt;
<pre>#include &lt;lber.h&gt;
unsigned long ber_skip_tag( BerElement *ber, unsigned long *len );</pre>  
unsigned long ber_skip_tag( BerElement *ber, unsigned long *len );</pre>  
Line 1,667: Line 1,517:
The ber_skip_tag() function advances the pointer to a BerElement past the first tag and length to the next tag.  
The ber_skip_tag() function advances the pointer to a BerElement past the first tag and length to the next tag.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;lber.h&gt;
<pre>#include &lt;lber.h&gt;
unsigned long ber_skip_tag( BerElement *ber, unsigned long *len );</pre>  
unsigned long ber_skip_tag( BerElement *ber, unsigned long *len );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ber_skip_tag() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ber_skip_tag() Function Parameters"
Line 1,689: Line 1,537:
|}
|}


<br> '''Description'''


'''Description'''
<br> ber_skip_tag() should only be used with constructed types and situations when a BER encoding is used as the value of an octet string.  
 
 
ber_skip_tag() should only be used with constructed types and situations when a BER encoding is used as the value of an octet string.  
 
 
'''See Also'''


<br> '''See Also'''


ber_peek_tag()  
<br> ber_peek_tag()  


=== ber_sockbuf_alloc()  ===
=== ber_sockbuf_alloc()  ===


 
'''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;lber.h&gt;
<pre>#include &lt;lber.h&gt;
Sockbuf* ber_sockbuf_alloc( void );</pre>  
Sockbuf* ber_sockbuf_alloc( void );</pre>  
=== ber_sockbuf_free()  ===
=== ber_sockbuf_free()  ===


 
'''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;lber.h&gt;
<pre>#include &lt;lber.h&gt;
void ber_sockbuf_free( Sockbuf* p );</pre>  
void ber_sockbuf_free( Sockbuf* p );</pre>  
=== ber_sockbuf_free_data()  ===
=== ber_sockbuf_free_data()  ===


 
'''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;lber.h&gt;
<pre>#include &lt;lber.h&gt;
void ber_sockbuf_free_data(Sockbuf *p);</pre>  
void ber_sockbuf_free_data(Sockbuf *p);</pre>  
=== ber_sockbuf_get_option()  ===
=== ber_sockbuf_get_option()  ===


 
'''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;lber.h&gt;
<pre>#include &lt;lber.h&gt;
int ber_sockbuf_get_option( Sockbuf *sb, int option, void *value );</pre>  
int ber_sockbuf_get_option( Sockbuf *sb, int option, void *value );</pre>  
=== ber_sockbuf_set_option()  ===
=== ber_sockbuf_set_option()  ===


 
'''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;lber.h&gt;
<pre>#include &lt;lber.h&gt;
int ber_sockbuf_set_option( Sockbuf *sb, int option, void *value );</pre>  
int ber_sockbuf_set_option( Sockbuf *sb, int option, void *value );</pre>  
Line 1,740: Line 1,574:
The ber_special_alloc() function allocates a BerElement structure plus some extra memory.  
The ber_special_alloc() function allocates a BerElement structure plus some extra memory.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;lber.h&gt;
<pre>#include &lt;lber.h&gt;
void* ber_special_alloc( size_t size, BerElement **ppBer );</pre>  
void* ber_special_alloc( size_t size, BerElement **ppBer );</pre>  
'''Returns'''


'''Returns'''
<br> Returns a pointer to the BerElement and a pointer to the extra memory.  
 
 
Returns a pointer to the BerElement and a pointer to the extra memory.  
 
 
'''Description'''


<br> '''Description'''


ber_special_alloc() allocates a ber data buffer within the same block, thus saving a call to calloc later when we read data.  
<br> ber_special_alloc() allocates a ber data buffer within the same block, thus saving a call to calloc later when we read data.  


=== ber_special_free()  ===
=== ber_special_free()  ===
Line 1,761: Line 1,589:
The ber_special_free() function frees an allocated BerElement structure.  
The ber_special_free() function frees an allocated BerElement structure.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;lber.h&gt;
<pre>#include &lt;lber.h&gt;
void ber_special_free( void* buf, BerElement *ber );</pre>  
void ber_special_free( void* buf, BerElement *ber );</pre>  
'''See Also'''


'''See Also'''
<br> ber_special_alloc()  
 
 
ber_special_alloc()  


=== ber_stack_init()  ===
=== ber_stack_init()  ===


 
'''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;lber.h&gt;
<pre>#include &lt;lber.h&gt;
int LDAP_CALL ber_stack_init(BerElement *ber, int options,
int LDAP_CALL ber_stack_init(BerElement *ber, int options,
Line 1,784: Line 1,606:
The ber_start_seq() function is used to start a sequence in a BerElement.  
The ber_start_seq() function is used to start a sequence in a BerElement.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;lber.h&gt;
<pre>#include &lt;lber.h&gt;
int ber_start_seq( BerElement *ber, unsigned long tag );</pre>  
int ber_start_seq( BerElement *ber, unsigned long tag );</pre>  
'''See Also'''


'''See Also'''
<br> ber_put_seq()  
 
 
ber_put_seq()  


=== ber_start_set()  ===
=== ber_start_set()  ===
Line 1,799: Line 1,617:
The ber_start_seq() function is used to start a set in a BerElement.  
The ber_start_seq() function is used to start a set in a BerElement.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;lber.h&gt;
<pre>#include &lt;lber.h&gt;
int ber_start_set( BerElement *ber, unsigned long tag );</pre>  
int ber_start_set( BerElement *ber, unsigned long tag );</pre>  
'''See Also'''


'''See Also'''
<br> ber_put_set()  
 
 
ber_put_set()  


=== ber_svecfree()  ===
=== ber_svecfree()  ===


 
'''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;lber.h&gt;
<pre>#include &lt;lber.h&gt;
void ber_svecfree( char **vals );</pre>  
void ber_svecfree( char **vals );</pre>  
=== ber_write()  ===
=== ber_write()  ===


 
'''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;lber.h&gt;
<pre>#include &lt;lber.h&gt;
long ber_write( BerElement *ber, char *buf,
long ber_write( BerElement *ber, char *buf,
Line 1,830: Line 1,640:
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
int ldap_abandon( LDAP *ld, int msgid );</pre>  
int ldap_abandon( LDAP *ld, int msgid );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_abandon() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_abandon() Function Parameters"
Line 1,847: Line 1,657:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:  
 
 
One of the following values:  


*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
Line 1,863: Line 1,671:
*LDAP_NO_MEMORY if memory cannot be allocated.
*LDAP_NO_MEMORY if memory cannot be allocated.


<br> '''Description'''


'''Description'''
<br> Please use the newer version of this function, ldap_abandon_ext().  
 
 
Please use the newer version of this function, ldap_abandon_ext().  
 
 
'''Example'''


<br> '''Example'''


The following example cancels an ldap_url_search() operation, abandoning the results of the operation.  
<br> The following example cancels an ldap_url_search() operation, abandoning the results of the operation.  
<pre>LDAP *ld;
<pre>LDAP *ld;
char *url = "ldap://ldap.example.com/c=US?o,description?one?o=sales";
char *url = "ldap://ldap.example.com/c=US?o,description?one?o=sales";
Line 1,887: Line 1,691:
}
}
...</pre>  
...</pre>  
'''See Also'''


'''See Also'''
<br> ldap_abandon_ext()  
 
 
ldap_abandon_ext()  


=== ldap_abandon_ext()  ===
=== ldap_abandon_ext()  ===
Line 1,899: Line 1,701:
int ldap_abandon_ext( LDAP *ld, int msgid,
int ldap_abandon_ext( LDAP *ld, int msgid,
   LDAPControl **serverctrls, LDAPControl **clientctrls );</pre>  
   LDAPControl **serverctrls, LDAPControl **clientctrls );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_abandon_ext() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_abandon_ext() Function Parameters"
Line 1,922: Line 1,724:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:  
 
 
One of the following values:  


*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
Line 1,934: Line 1,734:
*LDAP_NO_MEMORY if memory cannot be allocated.
*LDAP_NO_MEMORY if memory cannot be allocated.


<br> '''Description'''


'''Description'''
<br> The ldap_abandon_ext() function cancels an asynchronous LDAP operation that is in progress. For example, if you called ldap_search_ext() to initiate an LDAP search operation on the server, you can call ldap_abandon_ext() to cancel it. When you call ldap_abandon_ext(), the function checks to see if the results of the operation have already been returned. If so, ldap_abandon_ext() deletes the message ID from the queue of pending messages. If the results have not been returned, ldap_abandon_ext() sends a request to abandon the operation. Once cancelled, the results of the operation will not be returned, even if you subsequently call ldap_result() to retrieve them. To identify the operation to be cancelled, specify the message ID of the operation in the <tt>msgid</tt> argument of the ldap_abandon_ext() function.  
 
 
The ldap_abandon_ext() function cancels an asynchronous LDAP operation that is in progress. For example, if you called ldap_search_ext() to initiate an LDAP search operation on the server, you can call ldap_abandon_ext() to cancel it. When you call ldap_abandon_ext(), the function checks to see if the results of the operation have already been returned. If so, ldap_abandon_ext() deletes the message ID from the queue of pending messages. If the results have not been returned, ldap_abandon_ext() sends a request to abandon the operation. Once cancelled, the results of the operation will not be returned, even if you subsequently call ldap_result() to retrieve them. To identify the operation to be cancelled, specify the message ID of the operation in the <tt>msgid</tt> argument of the ldap_abandon_ext() function.  
 
 
'''Example'''


<br> '''Example'''


the following example cancels an ldap_url_search() operation, abandoning the results of the operation. Using ldap_abandon_ext()  
<br> the following example cancels an ldap_url_search() operation, abandoning the results of the operation. Using ldap_abandon_ext()  
<pre>LDAP *ld;
<pre>LDAP *ld;
char *url = "ldap://ldap.example.com/c=US?o,description?one?o=sales";
char *url = "ldap://ldap.example.com/c=US?o,description?one?o=sales";
Line 1,960: Line 1,756:
}
}
...</pre>  
...</pre>  
'''See Also'''


'''See Also'''
<br> ldap_add_ext(), ldap_compare_ext() , ldap_delete_ext(), ldap_extended_operation(), ldap_modify_ext(), ldap_rename(), ldap_sasl_bind , ldap_search_ext(), ldap_simple_bind(), ldap_url_search()  
 
 
ldap_add_ext(), ldap_compare_ext() , ldap_delete_ext(), ldap_extended_operation(), ldap_modify_ext(), ldap_rename(), ldap_sasl_bind , ldap_search_ext(), ldap_simple_bind(), ldap_url_search()  


=== ldap_add()  ===
=== ldap_add()  ===
Line 1,972: Line 1,766:
'''Note:''' This is an older function that is included in the SDK for backward-compatibility. If you are writing a new LDAP client, use ldap_add_ext() instead.  
'''Note:''' This is an older function that is included in the SDK for backward-compatibility. If you are writing a new LDAP client, use ldap_add_ext() instead.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
int ldap_add( LDAP *ld, const char *dn, LDAPMod **attrs );</pre>  
int ldap_add( LDAP *ld, const char *dn, LDAPMod **attrs );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_add() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_add() Function Parameters"
Line 1,997: Line 1,789:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> The message ID of the ldap_add() operation. Please use the newer version of this function, ldap_add_ext() .  
 
 
The message ID of the ldap_add() operation. Please use the newer version of this function, ldap_add_ext() .  
 
 
'''Example'''


<br> '''Example'''


the following example adds a new entry to the directory. Using ldap_add()  
<br> the following example adds a new entry to the directory. Using ldap_add()  
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
...
...
Line 2,063: Line 1,851:
}
}
...</pre>  
...</pre>  
'''See Also'''


'''See Also'''
<br> ldap_add_ext()  
 
 
ldap_add_ext()  


=== ldap_add_ext()  ===
=== ldap_add_ext()  ===
Line 2,075: Line 1,861:
'''Note: '''ldap_add_ext() is a new version of the ldap_add() function. If you are writing a new LDAP client, use ldap_add_ext().  
'''Note: '''ldap_add_ext() is a new version of the ldap_add() function. If you are writing a new LDAP client, use ldap_add_ext().  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
int ldap_add_ext( LDAP *ld, const char *dn, LDAPMod **attrs,
int ldap_add_ext( LDAP *ld, const char *dn, LDAPMod **attrs,
   LDAPControl **serverctrls, LDAPControl **clientctrls,
   LDAPControl **serverctrls, LDAPControl **clientctrls,
   int *msgidp );</pre>  
   int *msgidp );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_add_ext() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_add_ext() Function Parameters"
Line 2,111: Line 1,895:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:  
 
 
One of the following values:  


*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
*LDAP_PARAM_ERROR if any of the arguments are invalid.
*LDAP_PARAM_ERROR if any of the arguments are invalid.  
*LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request.
*LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request.  
*LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.
*LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.  
*LDAP_NO_MEMORY if memory cannot be allocated.
*LDAP_NO_MEMORY if memory cannot be allocated.  
*LDAP_NOT_SUPPORTED 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.
*LDAP_NOT_SUPPORTED 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.


<br> '''Description'''


'''Description'''
<br> The ldap_add_ext() adds a new entry to the directory.  
 
 
The ldap_add_ext() adds a new entry to the directory.  


To add a new entry to the directory, you need to specify:  
To add a new entry to the directory, you need to specify:  


*A unique DN identifying the new entry.<br>Use the <tt>dn</tt> 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 <tt>uid=bjensen,ou=People,dc=example,dc=com</tt> , the entries <tt>ou=People</tt> and <tt>dc=example,dc=com</tt> must already exist in the directory.
*A unique DN identifying the new entry.<br>Use the <tt>dn</tt> 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 <tt>uid=bjensen,ou=People,dc=example,dc=com</tt> , the entries <tt>ou=People</tt> and <tt>dc=example,dc=com</tt> must already exist in the directory.  
*A set of attributes for the new entry.<br>Create an LDAPMod structure for each attribute. Set the <tt>mod_op</tt> field to <tt>0</tt> 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 <tt>mod_op</tt> field to <tt>LDAP_MOD_BVALUES</tt>. Create an array of these LDAPMod structures and pass the array as the <tt>attrs</tt> argument. ldap_add_ext() 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 ldap_result() and ldap_parse_result() functions. If you want the results to be returned directly by the function, call the synchronous function ldap_add_ext_s(). For a list of possible result codes for an LDAP add operation, see the ldap_add_ext_s() function.
*A set of attributes for the new entry.<br>Create an LDAPMod structure for each attribute. Set the <tt>mod_op</tt> field to <tt>0</tt> 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 <tt>mod_op</tt> field to <tt>LDAP_MOD_BVALUES</tt>. Create an array of these LDAPMod structures and pass the array as the <tt>attrs</tt> argument. ldap_add_ext() 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 ldap_result() and ldap_parse_result() functions. If you want the results to be returned directly by the function, call the synchronous function ldap_add_ext_s(). For a list of possible result codes for an LDAP add operation, see the ldap_add_ext_s() function.


<br> '''See Also'''


'''See Also'''
<br> ldap_add_ext_s(), ldap_result, ldap_parse_result(), LDAPMod  
 
 
ldap_add_ext_s(), ldap_result, ldap_parse_result(), LDAPMod  


=== ldap_add_ext_s()  ===
=== ldap_add_ext_s()  ===
Line 2,147: Line 1,925:
int ldap_add_ext_s( LDAP *ld, const char *dn, LDAPMod **attrs,
int ldap_add_ext_s( LDAP *ld, const char *dn, LDAPMod **attrs,
   LDAPControl **serverctrls, LDAPControl **clientctrls );</pre>  
   LDAPControl **serverctrls, LDAPControl **clientctrls );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_add_ext_s() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_add_ext_s() Function Parameters"
Line 2,173: Line 1,951:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:  
 
 
One of the following values:  


*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
*LDAP_PARAM_ERROR if any of the arguments are invalid.
*LDAP_PARAM_ERROR if any of the arguments are invalid.  
*LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request.
*LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request.  
*LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.
*LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.  
*LDAP_NO_MEMORY if memory cannot be allocated.
*LDAP_NO_MEMORY if memory cannot be allocated.  
*LDAP_LOCAL_ERROR if an error occurred when receiving the results from the server.
*LDAP_LOCAL_ERROR if an error occurred when receiving the results from the server.  
*LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded results from the server.
*LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded results from the server.  
*LDAP_NOT_SUPPORTED 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.
*LDAP_NOT_SUPPORTED 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.


'''Note:''' Directory Server 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.  
'''Note:''' Directory Server 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.  


<br> '''Description'''


'''Description'''
<br> The ldap_add_ext_s() function adds a new entry to the directory. To add a new entry to the directory, you need to specify:  
 
 
The ldap_add_ext_s() function adds a new entry to the directory. To add a new entry to the directory, you need to specify:  


*A unique DN identifying the new entry.<br>Use the <tt>dn</tt> 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 <tt>uid=bjensen,ou=People,dc=example,dc=com</tt> , the entries <tt>ou=People</tt> and <tt>dc=example,dc=com</tt> must already exist in the directory.
*A unique DN identifying the new entry.<br>Use the <tt>dn</tt> 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 <tt>uid=bjensen,ou=People,dc=example,dc=com</tt> , the entries <tt>ou=People</tt> and <tt>dc=example,dc=com</tt> must already exist in the directory.  
*A set of attributes for the new entry.<br>Create an LDAPMod structure for each attribute. Set the <tt>mod_op</tt> field to <tt>0</tt> 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 <tt>mod_op</tt> field to <tt>LDAP_MOD_BVALUES</tt>. Create an array of these LDAPMod structures and pass the array as the <tt>attrs</tt> argument. ldap_add_ext_s() 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 ldap_add_ext().
*A set of attributes for the new entry.<br>Create an LDAPMod structure for each attribute. Set the <tt>mod_op</tt> field to <tt>0</tt> 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 <tt>mod_op</tt> field to <tt>LDAP_MOD_BVALUES</tt>. Create an array of these LDAPMod structures and pass the array as the <tt>attrs</tt> argument. ldap_add_ext_s() 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 ldap_add_ext().


<br> '''See Also'''


'''See Also'''
<br> ldap_add_ext(), LDAPMod  
 
 
ldap_add_ext(), LDAPMod  


=== ldap_add_s()  ===
=== ldap_add_s()  ===
Line 2,210: Line 1,982:
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
int ldap_add_s( LDAP *ld, const char *dn, LDAPMod **attrs );</pre>  
int ldap_add_s( LDAP *ld, const char *dn, LDAPMod **attrs );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_add_s() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_add_s() Function Parameters"
Line 2,230: Line 2,002:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> See ldap_add_ext_s() for a list of possible return codes.  
 
 
See ldap_add_ext_s() for a list of possible return codes.
 
 
'''Description'''
 
 
Please use the newer version of this function, ldap_add_ext_s() .  


<br> '''Description'''


'''Example'''
<br> Please use the newer version of this function, ldap_add_ext_s() .


<br> '''Example'''


The following example adds a new entry to the directory.  
<br> The following example adds a new entry to the directory.  
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
...
...
Line 2,287: Line 2,053:
}
}
...</pre>  
...</pre>  
'''See Also'''


'''See Also'''
<br> ldap_add_ext_s()  
 
 
ldap_add_ext_s()  


=== ldap_ber_free()  ===
=== ldap_ber_free()  ===
Line 2,299: Line 2,063:
'''Note:''' This is an older function that is included in the SDK for backward-compatibility. If you are writing a new LDAP client, use ber_free() instead. Except in name, the two functions are identical.  
'''Note:''' This is an older function that is included in the SDK for backward-compatibility. If you are writing a new LDAP client, use ber_free() instead. Except in name, the two functions are identical.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
void ldap_ber_free( BerElement *ber, int freebuf );</pre>  
void ldap_ber_free( BerElement *ber, int freebuf );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_ber_free() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_ber_free() Function Parameters"
Line 2,321: Line 2,083:
|}
|}


<br> '''Description'''


'''Description'''
<br> Please use the newer version of this function, ber_free().  
 
 
Please use the newer version of this function, ber_free().  
 
 
'''See Also'''


<br> '''See Also'''


ber_free()  
<br> ber_free()  


=== ldap_bind()  ===
=== ldap_bind()  ===
<pre>#include &lt;ldap-deprecated.h&gt;
<pre>#include &lt;ldap-deprecated.h&gt;
ldap_bind( LDAP *ld, const char *who, const char *passwd, int method );</pre>  
ldap_bind( LDAP *ld, const char *who, const char *passwd, int method );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_bind() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_bind() Function Parameters"
Line 2,359: Line 2,117:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> ldap_bind() returns the message ID of the request it initiates.  
 
 
ldap_bind() returns the message ID of the request it initiates.
 
 
'''Description'''
 
 
This is an asynchronous function that authenticates a specified entry to the directory. After a connection is made to an LDAP server using ldap_open(), a bind operation must be performed before other operations can be attempted over the connection.  


<br> '''Description'''


'''See Also'''
<br> This is an asynchronous function that authenticates a specified entry to the directory. After a connection is made to an LDAP server using ldap_open(), a bind operation must be performed before other operations can be attempted over the connection.


<br> '''See Also'''


ldap_open(), ldap_init(), prldap_init() (IPv6), ldap_bind_s()  
<br> ldap_open(), ldap_init(), prldap_init() (IPv6), ldap_bind_s()  


=== ldap_bind_s()  ===
=== ldap_bind_s()  ===
Line 2,383: Line 2,135:
ldap_bind_s() can be used when the authentication method needs to be selected at runtime.  
ldap_bind_s() can be used when the authentication method needs to be selected at runtime.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap-deprecated.h&gt;
<pre>#include &lt;ldap-deprecated.h&gt;
ldap_bind_s( LDAP *ld, const char *who, const char *cred, int method );</pre>  
ldap_bind_s( LDAP *ld, const char *who, const char *cred, int method );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_bind_s() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_bind_s() Function Parameters"
Line 2,411: Line 2,161:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> ldap_bind_s() returns an LDAP error indication.  
 
 
ldap_bind_s() returns an LDAP error indication.
 
 
'''Description'''
 
 
This is a synchronous function that authenticates a specified entry to the directory. After a connection is made to an LDAP server using ldap_open() , a bind operation must be performed before other operations can be attempted over the connection.  


<br> '''Description'''


'''See Also'''
<br> This is a synchronous function that authenticates a specified entry to the directory. After a connection is made to an LDAP server using ldap_open() , a bind operation must be performed before other operations can be attempted over the connection.


<br> '''See Also'''


ldap_open(), ldap_init(), prldap_init() (IPv6), ldap_bind()  
<br> ldap_open(), ldap_init(), prldap_init() (IPv6), ldap_bind()  


=== ldap_build_filter()  ===
=== ldap_build_filter()  ===
Line 2,439: Line 2,183:
For more specific information, see the header file <tt>ldap-deprecated.h</tt> .  
For more specific information, see the header file <tt>ldap-deprecated.h</tt> .  


<br> '''See Also'''


'''See Also'''
<br> ldap_memcache_init(), ldap_memcache_set(), ldap_memcache_get(), ldap_memcache_update(), ldap_memcache_flush() , ldap_memcache_destroy()  
 
 
ldap_memcache_init(), ldap_memcache_set(), ldap_memcache_get(), ldap_memcache_update(), ldap_memcache_flush() , ldap_memcache_destroy()  


=== ldap_charray_add()  ===
=== ldap_charray_add()  ===
Line 2,469: Line 2,211:
int ldap_compare( LDAP *ld, const char *dn, const char *attr,
int ldap_compare( LDAP *ld, const char *dn, const char *attr,
   const char *value );</pre>  
   const char *value );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_compare() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_compare() Function Parameters"
Line 2,492: Line 2,234:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> Returns the message ID of the ldap_compare() operation.  
 
 
Returns the message ID of the ldap_compare() operation.  


'''Note:''' To check the result of this operation, call ldap_result() and ldap_result2error(). See ldap_compare_ext_s() function for a list of possible result codes for the LDAP compare operation.  
'''Note:''' To check the result of this operation, call ldap_result() and ldap_result2error(). See ldap_compare_ext_s() function for a list of possible result codes for the LDAP compare operation.  


<br> '''Description'''


'''Description'''
<br> Please use the newer version of this function, ldap_compare_ext() .  
 
 
Please use the newer version of this function, ldap_compare_ext() .  
 
 
'''Example'''


<br> '''Example'''


the following example checks to see if Barbara Jensen has the email address <tt>bjensen@example.com</tt>.  
<br> the following example checks to see if Barbara Jensen has the email address <tt>bjensen@example.com</tt>.  
<pre>#include &lt;stdio.h&gt;
<pre>#include &lt;stdio.h&gt;
#include &lt;ldap.h&gt;
#include &lt;ldap.h&gt;
Line 2,520: Line 2,256:
msg_id = ldap_compare( ld, dn, "mail", "bjensen@example.com" );
msg_id = ldap_compare( ld, dn, "mail", "bjensen@example.com" );
...</pre>  
...</pre>  
'''See Also'''


'''See Also'''
<br> ldap_compare_ext()  
 
 
ldap_compare_ext()  


=== ldap_compare_ext()  ===
=== ldap_compare_ext()  ===
Line 2,533: Line 2,267:
   struct berval *bvalue, LDAPControl **serverctrls,
   struct berval *bvalue, LDAPControl **serverctrls,
   LDAPControl **clientctrls, int *msgidp );</pre>  
   LDAPControl **clientctrls, int *msgidp );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_compare_ext() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_compare_ext() Function Parameters"
Line 2,565: Line 2,299:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:  
 
 
One of the following values:  


*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
*LDAP_PARAM_ERROR if any of the arguments are invalid.
*LDAP_PARAM_ERROR if any of the arguments are invalid.  
*LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request.
*LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request.  
*LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.
*LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.  
*LDAP_NO_MEMORY if memory cannot be allocated.
*LDAP_NO_MEMORY if memory cannot be allocated.  
*LDAP_NOT_SUPPORTED 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.
*LDAP_NOT_SUPPORTED 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.


'''Note:''' To check the result of this operation, call ldap_result() and ldap_parse_result().  
'''Note:''' To check the result of this operation, call ldap_result() and ldap_parse_result().  


<br> '''Returns'''


'''Returns'''
<br> For a list of the possible result codes for an LDAP compare operation, see ldap_compare_ext_s().  
 
 
For a list of the possible result codes for an LDAP compare operation, see ldap_compare_ext_s().
 
 
'''Description'''
 
 
The ldap_compare_ext() function compares the value of an attribute in an entry against a specified value. Because ldap_compare_ext() 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 ldap_compare_ext_s().  


<br> '''Description'''


'''See Also'''
<br> The ldap_compare_ext() function compares the value of an attribute in an entry against a specified value. Because ldap_compare_ext() 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 ldap_compare_ext_s().


<br> '''See Also'''


ldap_compare_ext_s(), ldap_result(), ldap_parse_result()  
<br> ldap_compare_ext_s(), ldap_result(), ldap_parse_result()  


=== ldap_compare_ext_s()  ===
=== ldap_compare_ext_s()  ===
Line 2,602: Line 2,328:
The ldap_compare_ext_s() function synchronously determines if an attribute of an entry contains a specified value.  
The ldap_compare_ext_s() function synchronously determines if an attribute of an entry contains a specified value.  


 
<br> '''Syntax'''  
'''Syntax'''
<pre>#include &lt;ldap.h&gt;
 
<pre>#include &lt;ldap.h&gt;
int ldap_compare_ext_s( LDAP *ld, const char *dn,
int ldap_compare_ext_s( LDAP *ld, const char *dn,
   const char *attr, struct berval *bvalue,
   const char *attr, struct berval *bvalue,
   LDAPControl **serverctrls, LDAPControl **clientctrls );</pre>  
   LDAPControl **serverctrls, LDAPControl **clientctrls );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_compare_ext_s() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_compare_ext_s() Function Parameters"
Line 2,638: Line 2,362:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:


 
*LDAP_COMPARE_TRUE if the entry contains the attribute value.  
One of the following values:
*LDAP_COMPARE_FALSE if the entry does not contain the attribute value.  
 
*LDAP_PARAM_ERROR if any of the arguments&nbsp;are invalid.  
*LDAP_COMPARE_TRUE if the entry contains the attribute value.
*LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request.  
*LDAP_COMPARE_FALSE if the entry does not contain the attribute value.
*LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.  
*LDAP_PARAM_ERROR if any of the arguments&nbsp;are invalid.
*LDAP_NO_MEMORY if memory cannot be allocated.  
*LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request.
*LDAP_LOCAL_ERROR if an error occurred when receiving the results from the server.  
*LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.
*LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded results from the server.  
*LDAP_NO_MEMORY if memory cannot be allocated.
*LDAP_LOCAL_ERROR if an error occurred when receiving the results from the server.
*LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded results from the server.
*LDAP_NOT_SUPPORTED 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.
*LDAP_NOT_SUPPORTED 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.


The ldap_compare_ext_s() function compares the value of an attribute in an entry against a specified value. ldap_compare_ext_s() 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 ldap_compare_ext().  
The ldap_compare_ext_s() function compares the value of an attribute in an entry against a specified value. ldap_compare_ext_s() 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 ldap_compare_ext().  


<br> '''See Also'''


'''See Also'''
<br> ldap_compare_ext()  
 
 
ldap_compare_ext()  


=== ldap_compare_s()  ===
=== ldap_compare_s()  ===
Line 2,668: Line 2,388:
'''Note:''' This is an older function that is included in the SDK for backward-compatibility. If you are writing a new LDAP client, use ldap_compare_ext_s() instead.  
'''Note:''' This is an older function that is included in the SDK for backward-compatibility. If you are writing a new LDAP client, use ldap_compare_ext_s() instead.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
int ldap_compare_s( LDAP *ld, const char *dn,
int ldap_compare_s( LDAP *ld, const char *dn,
   const char *attr, const char *value );</pre>  
   const char *attr, const char *value );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_compare_s() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_compare_s() Function Parameters"
Line 2,697: Line 2,415:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> For a list of the possible result codes for an LDAP compare operation, see ldap_compare_ext_s().  
 
 
For a list of the possible result codes for an LDAP compare operation, see ldap_compare_ext_s().
 
 
'''Description'''
 
 
Please use the newer version of this function, ldap_compare_ext_s() .  


<br> '''Description'''


'''Example'''
<br> Please use the newer version of this function, ldap_compare_ext_s() .


<br> '''Example'''


The following example checks to see if Barbara Jensen has the email address <tt>bjensen@example.com</tt>.  
<br> The following example checks to see if Barbara Jensen has the email address <tt>bjensen@example.com</tt>.  
<pre>#include &lt;stdio.h&gt;
<pre>#include &lt;stdio.h&gt;
#include &lt;ldap.h&gt;
#include &lt;ldap.h&gt;
Line 2,733: Line 2,445:
}
}
...</pre>  
...</pre>  
'''See Also'''


'''See Also'''
<br> ldap_compare_ext_s()  
 
 
ldap_compare_ext_s()  


=== ldap_control_free()  ===
=== ldap_control_free()  ===
Line 2,743: Line 2,453:
The ldap_control_free() function frees an LDAPControl structure from memory.  
The ldap_control_free() function frees an LDAPControl structure from memory.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
void ldap_control_free( LDAPControl *ctrl );</pre>  
void ldap_control_free( LDAPControl *ctrl );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_control_free() Function Parameter"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_control_free() Function Parameter"
Line 2,762: Line 2,470:
|}
|}


<br> '''Description'''


'''Description'''
<br> The ldap_control_free() function frees an LDAPControl structure from memory. You should call this function to free controls that you create; for example, if you call the ldap_create_sort_control() function.  
 
 
The ldap_control_free() function frees an LDAPControl structure from memory. You should call this function to free controls that you create; for example, if you call the ldap_create_sort_control() function.  
 
 
'''See Also'''


<br> '''See Also'''


ldap_controls_free()  
<br> ldap_controls_free()  


=== ldap_controls_free()  ===
=== ldap_controls_free()  ===
Line 2,778: Line 2,482:
The ldap_controls_free() function frees an array of LDAPControl structures from memory.  
The ldap_controls_free() function frees an array of LDAPControl structures from memory.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
void ldap_controls_free( LDAPControl **ctrls );</pre>  
void ldap_controls_free( LDAPControl **ctrls );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_controls_free() Function Parameter"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_controls_free() Function Parameter"
Line 2,797: Line 2,499:
|}
|}


<br> '''Description'''


'''Description'''
<br> The ldap_controls_free() function frees an array of LDAPControl structures from memory. You should call this function to free arrays of controls that you create or any arrays returned by ldap_parse_result().  
 
 
The ldap_controls_free() function frees an array of LDAPControl structures from memory. You should call this function to free arrays of controls that you create or any arrays returned by ldap_parse_result().  
 
 
'''See Also'''


<br> '''See Also'''


ldap_control_free(), ldap_parse_result()  
<br> ldap_control_free(), ldap_parse_result()  


=== ldap_count_entries()  ===
=== ldap_count_entries()  ===
Line 2,813: Line 2,511:
The ldap_count_entries() function returns the number of LDAPMessage structures representing directory entries in a chain of search results.  
The ldap_count_entries() function returns the number of LDAPMessage structures representing directory entries in a chain of search results.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
int ldap_count_entries( LDAP *ld, LDAPMessage *result );</pre>  
int ldap_count_entries( LDAP *ld, LDAPMessage *result );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_count_entries() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_count_entries() Function Parameters"
Line 2,835: Line 2,531:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:  
 
 
One of the following values:  


*If successful, the number of LDAPMessage() structures of the type <tt>LDAP_RES_SEARCH_ENTRY</tt> in a chain of search results. If there are no structures of this type, returns <tt>0</tt>.
*If successful, the number of LDAPMessage() structures of the type <tt>LDAP_RES_SEARCH_ENTRY</tt> in a chain of search results. If there are no structures of this type, returns <tt>0</tt>.
Line 2,845: Line 2,539:
*<tt>-1</tt> if <tt>ld</tt> is not a valid connection handle.
*<tt>-1</tt> if <tt>ld</tt> is not a valid connection handle.


<br> '''Description'''


'''Description'''
<br> The ldap_count_entries() function returns the number of LDAPMessage structures representing directory entries in a chain of search results. These messages have the type <tt>LDAP_RES_SEARCH_ENTRY</tt> .  
 
 
The ldap_count_entries() function returns the number of LDAPMessage structures representing directory entries in a chain of search results. These messages have the type <tt>LDAP_RES_SEARCH_ENTRY</tt> .  


See the examples under ldap_search_ext() and ldap_search_ext_s().  
See the examples under ldap_search_ext() and ldap_search_ext_s().  


<br> '''See Also'''


'''See Also'''
<br> ldap_result(), ldap_search_ext() , ldap_search_ext_s(), ldap_first_entry(), ldap_next_entry(), ldap_first_entry(), ldap_next_message()  
 
 
ldap_result(), ldap_search_ext() , ldap_search_ext_s(), ldap_first_entry(), ldap_next_entry(), ldap_first_entry(), ldap_next_message()  


=== ldap_count_messages()  ===
=== ldap_count_messages()  ===
Line 2,863: Line 2,553:
The ldap_count_messages() function returns the number of LDAPMessage structures in a chain of search results.  
The ldap_count_messages() function returns the number of LDAPMessage structures in a chain of search results.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
int ldap_count_messages( LDAP *ld, LDAPMessage *res );</pre>  
int ldap_count_messages( LDAP *ld, LDAPMessage *res );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_count_messages() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_count_messages() Function Parameters"
Line 2,885: Line 2,573:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:  
 
 
One of the following values:  


*The number of LDAPMessage structures in a chain of search results, if successful. If there are no structures, returns <tt>0</tt>.
*The number of LDAPMessage structures in a chain of search results, if successful. If there are no structures, returns <tt>0</tt>.  
*<tt>-1</tt> if <tt>ld</tt> is not a valid connection handle.
*<tt>-1</tt> if <tt>ld</tt> is not a valid connection handle.


<br> '''Description'''


'''Description'''
<br> The ldap_count_messages() function returns the number of LDAPMessage structures in a chain of search results. The count is the number of search entries plus the number of search references.


'''Note:''' If you pass in a pointer to an LDAPMessage 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.


The ldap_count_messages() function returns the number of LDAPMessage structures in a chain of search results. The count is the number of search entries plus the number of search references.
<br> '''Example'''


'''Note:''' If you pass in a pointer to an LDAPMessage 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.  
<br> See the examples under ldap_search_ext() and ldap_search_ext_s().  


<br> '''See Also'''


'''Example'''
<br> ldap_result(), ldap_search_ext() , ldap_search_ext_s(), ldap_first_message(), ldap_next_message(), ldap_first_entry(), ldap_next_entry() , ldap_first_reference(), ldap_next_reference()  
 
 
See the examples under ldap_search_ext() and ldap_search_ext_s().
 
 
'''See Also'''
 
 
ldap_result(), ldap_search_ext() , ldap_search_ext_s(), ldap_first_message(), ldap_next_message(), ldap_first_entry(), ldap_next_entry() , ldap_first_reference(), ldap_next_reference()  


=== ldap_count_references()  ===
=== ldap_count_references()  ===
Line 2,918: Line 2,598:
The ldap_count_references() function returns the number of LDAPMessage structures representing search references in a chain of search results.  
The ldap_count_references() function returns the number of LDAPMessage structures representing search references in a chain of search results.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
int ldap_count_references( LDAP *ld, LDAPMessage *res );</pre>  
int ldap_count_references( LDAP *ld, LDAPMessage *res );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_count_references() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_count_references() Function Parameters"
Line 2,940: Line 2,618:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:  
 
 
One of the following values:  


*The number of LDAPMessage structures of the type <tt>LDAP_RES_SEARCH_REFERENCE</tt> in a chain of search results, if successful. (If there are no structures of this type, returns <tt>0</tt>.)
*The number of LDAPMessage structures of the type <tt>LDAP_RES_SEARCH_REFERENCE</tt> in a chain of search results, if successful. (If there are no structures of this type, returns <tt>0</tt>.)  
*<tt>-1</tt> if <tt>ld</tt> is not a valid connection handle.
*<tt>-1</tt> if <tt>ld</tt> is not a valid connection handle.


<br> '''Description'''


'''Description'''
<br> The ldap_count_references() function returns the number of LDAPMessage structures representing search references in a chain of search results. These messages have the type <tt>LDAP_RES_SEARCH_REFERENCE</tt>, 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.  
 
 
The ldap_count_references() function returns the number of LDAPMessage structures representing search references in a chain of search results. These messages have the type <tt>LDAP_RES_SEARCH_REFERENCE</tt>, 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.  


See the examples under ldap_search_ext() and ldap_search_ext_s().  
See the examples under ldap_search_ext() and ldap_search_ext_s().  


<br> '''See Also'''


'''See Also'''
<br> ldap_result(), ldap_search_ext() , ldap_search_ext_s(), ldap_first_reference(), ldap_next_reference()  
 
 
ldap_result(), ldap_search_ext() , ldap_search_ext_s(), ldap_first_reference(), ldap_next_reference()  


=== ldap_count_values()  ===
=== ldap_count_values()  ===
Line 2,967: Line 2,639:
The ldap_count_values() function returns the number of values in an array of strings. '''Note:''' Use the ldap_count_values_len() function if the array contains berval structures.  
The ldap_count_values() function returns the number of values in an array of strings. '''Note:''' Use the ldap_count_values_len() function if the array contains berval structures.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
int ldap_count_values( char **values );</pre>  
int ldap_count_values( char **values );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_count_values() Function Parameter"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_count_values() Function Parameter"
Line 2,986: Line 2,656:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:  
 
 
One of the following values:  


*The number of values in the array, if successful.  
*The number of values in the array, if successful.  
*<tt>-1</tt> if unsuccessful.
*<tt>-1</tt> if unsuccessful.


<br> '''Example'''


'''Example'''
<br> The following example counts the number of values assigned to an attribute.  
 
 
The following example counts the number of values assigned to an attribute.  
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
...
...
Line 3,013: Line 2,679:
count = ldap_count_values( vals );
count = ldap_count_values( vals );
...</pre>  
...</pre>  
'''See Also'''


'''See Also'''
<br> ldap_count_values_len(), ldap_get_values()  
 
 
ldap_count_values_len(), ldap_get_values()  


=== ldap_count_values_len()  ===
=== ldap_count_values_len()  ===
Line 3,024: Line 2,688:
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
int ldap_count_values_len( struct berval **vals );</pre>  
int ldap_count_values_len( struct berval **vals );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_count_values_len() Function Parameter"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_count_values_len() Function Parameter"
Line 3,038: Line 2,702:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:  
 
 
One of the following values:  


*The number of values in the array, if successful.  
*The number of values in the array, if successful.  
*<tt>-1</tt> if unsuccessful.
*<tt>-1</tt> if unsuccessful.


<br> '''Example'''


'''Example'''
<br> The following example counts the number of values assigned to an attribute.  
 
 
The following example counts the number of values assigned to an attribute.  
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
LDAP *ld;
LDAP *ld;
Line 3,064: Line 2,724:
count = ldap_count_values_len( vals );
count = ldap_count_values_len( vals );
...</pre>  
...</pre>  
'''See Also'''


'''See Also'''
<br> ldap_count_values(), ldap_get_values_len()  
 
 
ldap_count_values(), ldap_get_values_len()  


=== ldap_create_authzid_control()  ===
=== ldap_create_authzid_control()  ===
Line 3,078: Line 2,736:
Calling ldap_create_authzid_control() creates an LDAP control that you can pass to the ldap_simple_bind() function to retrieve the authorization ID in the response. You call ldap_parse_authzid_control() function on the controls returned with an entry to retrieve a <tt>char *</tt> containing the authorization ID. When you are done with the search, you should free the control by calling the ldap_control_free() function.  
Calling ldap_create_authzid_control() creates an LDAP control that you can pass to the ldap_simple_bind() function to retrieve the authorization ID in the response. You call ldap_parse_authzid_control() function on the controls returned with an entry to retrieve a <tt>char *</tt> containing the authorization ID. When you are done with the search, you should free the control by calling the ldap_control_free() function.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
LDAP_API(int) LDAP_CALL ldap_create_authzid_control( LDAP *ld,
LDAP_API(int) LDAP_CALL ldap_create_authzid_control( LDAP *ld,
   const char ctl_iscritical, LDAPControl **ctrlp );</pre>  
   const char ctl_iscritical, LDAPControl **ctrlp );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_create_authzid_control() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_create_authzid_control() Function Parameters"
Line 3,107: Line 2,763:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:  
 
 
One of the following values:  


*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
*LDAP_PARAM_ERROR if an invalid parameter was passed to the function.
*LDAP_PARAM_ERROR if an invalid parameter was passed to the function.  
*LDAP_NO_MEMORY if memory cannot be allocated.
*LDAP_NO_MEMORY if memory cannot be allocated.  
*LDAP_ENCODING_ERROR if an error occurred when BER-encoding the control.
*LDAP_ENCODING_ERROR if an error occurred when BER-encoding the control.


<br> '''See Also'''


'''See Also'''
<br> ldap_parse_authzid_control()  
 
 
ldap_parse_authzid_control()  


=== ldap_create_filter()  ===
=== ldap_create_filter()  ===
Line 3,128: Line 2,780:
The ldap_create_filter() routine constructs an LDAP search filter.  
The ldap_create_filter() routine constructs an LDAP search filter.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
int ldap_create_filter( char *buf, unsigned long buflen,
int ldap_create_filter( char *buf, unsigned long buflen,
   char *pattern, char *prefix, char *suffix, char *attr,
   char *pattern, char *prefix, char *suffix, char *attr,
   char *value, char **valwords );</pre>  
   char *value, char **valwords );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_create_filter() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_create_filter() Function Parameters"
Line 3,170: Line 2,820:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:  
 
 
One of the following values:  


*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
*LDAP_SIZELIMIT_EXCEEDED if the created filter exceeds the size of the buffer.
*LDAP_SIZELIMIT_EXCEEDED if the created filter exceeds the size of the buffer.  
*LDAP_PARAM_ERROR if an invalid parameter was passed to the function.
*LDAP_PARAM_ERROR if an invalid parameter was passed to the function.


<br> '''Example'''


'''Example'''
<br> The following example builds the filter <tt>(mail=bjensen@example.com)</tt>.  
 
 
The following example builds the filter <tt>(mail=bjensen@example.com)</tt>.  
<pre>char buf[LDAP_FILT_MAXSIZ];
<pre>char buf[LDAP_FILT_MAXSIZ];
char *pattern = "(%a=%v)";
char *pattern = "(%a=%v)";
Line 3,193: Line 2,839:
   NULL, attr, value, NULL );
   NULL, attr, value, NULL );
...</pre>  
...</pre>  
'''See Also'''


'''See Also'''
<br> ldap_init_getfilter(), ldap_init_getfilter_buf(), ldap_getfirstfilter() , ldap_getnextfilter(), ldap_set_filter_additions()  
 
 
ldap_init_getfilter(), ldap_init_getfilter_buf(), ldap_getfirstfilter() , ldap_getnextfilter(), ldap_set_filter_additions()  


=== ldap_create_geteffectiveRights_control()  ===
=== ldap_create_geteffectiveRights_control()  ===
Line 3,203: Line 2,847:
The ldap_create_geteffectiveRights_control() function allows a user having correct privileges to query about the access rights another identity has on one or more entries in the directory.  
The ldap_create_geteffectiveRights_control() function allows a user having correct privileges to query about the access rights another identity has on one or more entries in the directory.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
LDAP_API(int) LDAP_CALL ldap_create_geteffectiveRights_control( LDAP *ld,
LDAP_API(int) LDAP_CALL ldap_create_geteffectiveRights_control( LDAP *ld,
   const char *authzid, const char **attrlist, const char ctl_iscritical,
   const char *authzid, const char **attrlist, const char ctl_iscritical,
   LDAPControl **ctrlp );</pre>  
   LDAPControl **ctrlp );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_create_geteffectiveRights_control() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_create_geteffectiveRights_control() Function Parameters"
Line 3,243: Line 2,885:
   int changetypes, int changesonly, int return_echg_ctls,
   int changetypes, int changesonly, int return_echg_ctls,
   char ctl_iscritical, LDAPControl **ctrlp );</pre>  
   char ctl_iscritical, LDAPControl **ctrlp );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_create_persistentsearch_control() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_create_persistentsearch_control() Function Parameters"
Line 3,287: Line 2,929:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:


 
*LDAP_SUCCESS if successful.  
One of the following values:
 
*LDAP_SUCCESS if successful.  
*LDAP_PARAM_ERROR if an invalid parameter was passed to the function.  
*LDAP_PARAM_ERROR if an invalid parameter was passed to the function.  
*LDAP_NO_MEMORY if memory cannot be allocated.  
*LDAP_NO_MEMORY if memory cannot be allocated.  
Line 3,300: Line 2,940:
when BER-encoding the control.  
when BER-encoding the control.  


<br> '''Description'''


'''Description'''
<br> The ldap_create_persistentsearch_control() function allows you to perform persistent searches. A ''persistent search'' 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 ldap_create_persistentsearch_control() creates an LDAP server control that you can pass to the ldap_search_ext() function.  
 
 
The ldap_create_persistentsearch_control() function allows you to perform persistent searches. A ''persistent search'' 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 ldap_create_persistentsearch_control() creates an LDAP server control that you can pass to the ldap_search_ext() function.  


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 <tt>return_echg_ctls</tt> parameter), the server includes controls with each changed entry it sends back. To retrieve the controls from each entry, call the ldap_get_entry_controls() function. To get data about the changes made to the entry from the control, call the ldap_parse_entrychange_control() function. When you are done with the search, you can cancel the persistent search by calling the ldap_abandon_ext() function. You should also free the control from memory by calling the ldap_control_free() function.  
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 <tt>return_echg_ctls</tt> parameter), the server includes controls with each changed entry it sends back. To retrieve the controls from each entry, call the ldap_get_entry_controls() function. To get data about the changes made to the entry from the control, call the ldap_parse_entrychange_control() function. When you are done with the search, you can cancel the persistent search by calling the ldap_abandon_ext() function. You should also free the control from memory by calling the ldap_control_free() function.  


<br> '''See Also'''


'''See Also'''
<br> ldap_search_ext(), ldap_abandon_ext, ldap_get_entry_controls(), ldap_parse_entrychange_control(), ldap_control_free()  
 
 
ldap_search_ext(), ldap_abandon_ext, ldap_get_entry_controls(), ldap_parse_entrychange_control(), ldap_control_free()  


=== ldap_create_pwdpolicy_control()  ===
=== ldap_create_pwdpolicy_control()  ===
Line 3,322: Line 2,958:
Calling ldap_create_pwdpolicy_control() creates an LDAP control that you can pass to the ldap_simple_bind() functions to retrieve password policy information from bind, modify, add, compare, and potentially extended operation responses including password policy response controls. You call ldap_parse_pwdpolicy_control() function on the controls returned with an entry to retrieve a LDAPpwdpolicy structure containing information about the status of the account. When you are done with the search, you should free the control by calling the ldap_control_free() function.  
Calling ldap_create_pwdpolicy_control() creates an LDAP control that you can pass to the ldap_simple_bind() functions to retrieve password policy information from bind, modify, add, compare, and potentially extended operation responses including password policy response controls. You call ldap_parse_pwdpolicy_control() function on the controls returned with an entry to retrieve a LDAPpwdpolicy structure containing information about the status of the account. When you are done with the search, you should free the control by calling the ldap_control_free() function.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
LDAP_API(int) LDAP_CALL ldap_create_pwdpolicy_control( LDAP *ld,
LDAP_API(int) LDAP_CALL ldap_create_pwdpolicy_control( LDAP *ld,
   const char ctl_iscritical, LDAPControl **ctrlp );</pre>  
   const char ctl_iscritical, LDAPControl **ctrlp );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_create_pwdpolicy_control() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_create_pwdpolicy_control() Function Parameters"
Line 3,351: Line 2,985:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:  
 
 
One of the following values:  


*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
Line 3,362: Line 2,994:
*LDAP_ENCODING_ERROR if an error occurred when BER-encoding the control.
*LDAP_ENCODING_ERROR if an error occurred when BER-encoding the control.


<br> '''See Also'''


'''See Also'''
<br> ldap_parse_pwdpolicy_control(), LDAPpwdpolicy()  
 
 
ldap_parse_pwdpolicy_control(), LDAPpwdpolicy()  


=== ldap_create_proxiedauth_control()  ===
=== ldap_create_proxiedauth_control()  ===
Line 3,374: Line 3,004:
int ldap_create_proxiedauth_control( LDAP *ld, char *authzid,
int ldap_create_proxiedauth_control( LDAP *ld, char *authzid,
   LDAPControl **ctrlp);</pre>  
   LDAPControl **ctrlp);</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_create_proxiedauth_control() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_create_proxiedauth_control() Function Parameters"
Line 3,394: Line 3,024:
|}
|}


<br> '''Description'''


'''Description'''
<br> More information on proxy authorization can be found in the ''LDAP'' Proxied Authorization Control Internet Draft''(http://ietfreport.isoc.org/ids/draft-weltman-ldapv3-proxy-12.txt).''  
 
 
More information on proxy authorization can be found in the ''LDAP'' Proxied Authorization Control Internet Draft''(http://ietfreport.isoc.org/ids/draft-weltman-ldapv3-proxy-12.txt).''  


'''Note:''' 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 LDAP_CONTROL_PROXIEDAUTH, as defined in the ldap-extension.h header file).  
'''Note:''' 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 LDAP_CONTROL_PROXIEDAUTH, as defined in the ldap-extension.h header file).  
Line 3,408: Line 3,036:
int ldap_create_proxyauth_control( LDAP *ld, char *DN,
int ldap_create_proxyauth_control( LDAP *ld, char *DN,
   char ctl_iscritical, LDAPControl **ctrlp);</pre>  
   char ctl_iscritical, LDAPControl **ctrlp);</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_create_proxyauth_control() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_create_proxyauth_control() Function Parameters"
Line 3,434: Line 3,062:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:  
 
 
One of the following values:  


*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
Line 3,446: Line 3,072:
*LDAP_UNAVAILABLE_CRITICAL_EXTENSION if the server does not support proxy authorization and <tt>ctl_iscritical</tt> is set to a non-zero value.
*LDAP_UNAVAILABLE_CRITICAL_EXTENSION if the server does not support proxy authorization and <tt>ctl_iscritical</tt> is set to a non-zero value.


<br> '''See Also'''


'''See Also'''
<br> ldap_control_free()  
 
 
ldap_control_free()  


=== ldap_create_sort_control()  ===
=== ldap_create_sort_control()  ===
Line 3,458: Line 3,082:
'''Note:''' 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.  
'''Note:''' 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.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
int ldap_create_sort_control( LDAP *ld,
int ldap_create_sort_control( LDAP *ld,
   LDAPsortkey **sortKeyList, const char ctl_iscritical,
   LDAPsortkey **sortKeyList, const char ctl_iscritical,
   LDAPControl **ctrlp );</pre>  
   LDAPControl **ctrlp );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_create_sort_control() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_create_sort_control() Function Parameters"
Line 3,488: Line 3,110:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:  
 
 
One of the following values:  


*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
*LDAP_PARAM_ERROR if an invalid parameter was passed to the function.  
*LDAP_PARAM_ERROR if an invalid parameter was passed to the function.  
*LDAP_NO_MEMORY if memory cannot be allocated.  
*LDAP_NO_MEMORY if memory cannot be allocated.  
*LDAP_ENCODING_ERROR if an error occurred when BER-encoding the control.  
*LDAP_ENCODING_ERROR if an error occurred when BER-encoding the control.
 
 
'''Description'''


<br> '''Description'''


The ldap_create_sort_control() 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 ldap_search_ext() and ldap_search_ext_s() functions.  
<br> The ldap_create_sort_control() 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 ldap_search_ext() and ldap_search_ext_s() functions.  


See also ldap_create_sort_keylist(), ldap_search_ext(), ldap_search_ext_s(), ldap_control_free().  
See also ldap_create_sort_keylist(), ldap_search_ext(), ldap_search_ext_s(), ldap_control_free().  
Line 3,511: Line 3,129:
The ldap_create_sort_keylist() function creates an array of LDAPsortkey structures from a string representation of a set of sort keys.  
The ldap_create_sort_keylist() function creates an array of LDAPsortkey structures from a string representation of a set of sort keys.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
int ldap_create_sort_keylist(LDAPsortkey ***sortKeyList,
int ldap_create_sort_keylist(LDAPsortkey ***sortKeyList,
   const char *string_rep);</pre>  
   const char *string_rep);</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_create_sort_keylist() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_create_sort_keylist() Function Parameters"
Line 3,538: Line 3,154:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:  
 
 
One of the following values:  


*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
Line 3,549: Line 3,163:
*<tt>-1</tt> if an error occurred.
*<tt>-1</tt> if an error occurred.


<br> '''Description'''


'''Description'''
<br> Calling the ldap_create_sort_keylist() function allows you to create an array of LDAPsortkey structures from a string representation of a set of sort keys. You can then pass the array to the ldap_create_sort_control() function. The string representation specified by the <tt>string_rep</tt> 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 LDAPsortkey() structures by calling the ldap_free_sort_keylist() function.  
 
 
Calling the ldap_create_sort_keylist() function allows you to create an array of LDAPsortkey structures from a string representation of a set of sort keys. You can then pass the array to the ldap_create_sort_control() function. The string representation specified by the <tt>string_rep</tt> 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 LDAPsortkey() structures by calling the ldap_free_sort_keylist() function.  
 
 
'''See Also'''


<br> '''See Also'''


ldap_create_sort_control(), ldap_free_sort_keylist()  
<br> ldap_create_sort_control(), ldap_free_sort_keylist()  


=== ldap_create_userstatus_control()  ===
=== ldap_create_userstatus_control()  ===
Line 3,569: Line 3,179:
Calling ldap_create_userstatus_control() creates an LDAP control that you can pass to the ldap_search_ext() and ldap_search_ext_s() functions. You call ldap_parse_userstatus_control() function on the controls returned with an entry to retrieve a LDAPuserstatus structure containing information about the status of the account. When you are done with the search, you should free the control by calling the ldap_control_free() function.  
Calling ldap_create_userstatus_control() creates an LDAP control that you can pass to the ldap_search_ext() and ldap_search_ext_s() functions. You call ldap_parse_userstatus_control() function on the controls returned with an entry to retrieve a LDAPuserstatus structure containing information about the status of the account. When you are done with the search, you should free the control by calling the ldap_control_free() function.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
LDAP_API(int) LDAP_CALL ldap_create_userstatus_control( LDAP *ld,
LDAP_API(int) LDAP_CALL ldap_create_userstatus_control( LDAP *ld,
   const char ctl_iscritical, LDAPControl **ctrlp );</pre>  
   const char ctl_iscritical, LDAPControl **ctrlp );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_create_userstatus_control() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_create_userstatus_control() Function Parameters"
Line 3,598: Line 3,206:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:  
 
 
One of the following values:  


*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
*LDAP_PARAM_ERROR if an invalid parameter was passed to the function.  
*LDAP_PARAM_ERROR if an invalid parameter was passed to the function.  
*LDAP_NO_MEMORY if memory cannot be allocated.  
*LDAP_NO_MEMORY if memory cannot be allocated.  
*LDAP_ENCODING_ERROR if an error occurred when BER-encoding the control.  
*LDAP_ENCODING_ERROR if an error occurred when BER-encoding the control.
 
 
'''See Also'''


<br> '''See Also'''


ldap_parse_userstatus_control(), LDAPuserstatus()  
<br> ldap_parse_userstatus_control(), LDAPuserstatus()  


=== ldap_create_virtuallist_control()  ===
=== ldap_create_virtuallist_control()  ===
Line 3,621: Line 3,225:
int ldap_create_virtuallist_control( LDAP *ld,
int ldap_create_virtuallist_control( LDAP *ld,
   LDAPVirtualList *ldvlistp, LDAPControl **ctrlp );</pre>  
   LDAPVirtualList *ldvlistp, LDAPControl **ctrlp );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_create_virtuallist_control() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_create_virtuallist_control() Function Parameters"
Line 3,641: Line 3,245:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:  
 
 
One of the following values:  


*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
*LDAP_PARAM_ERROR if an invalid parameter was passed to the function.  
*LDAP_PARAM_ERROR if an invalid parameter was passed to the function.  
*LDAP_NO_MEMORY if memory cannot be allocated.  
*LDAP_NO_MEMORY if memory cannot be allocated.  
*LDAP_ENCODING_ERROR if an error occurred when BER-encoding the control.  
*LDAP_ENCODING_ERROR if an error occurred when BER-encoding the control.
 


'''Description'''
<br> '''Description'''  


 
<br> The ldap_create_virtuallist_control() 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 LDAPVirtualList structure and pass in a pointer to this structure as the <tt>ldvlistp</tt> argument.  
The ldap_create_virtuallist_control() 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 LDAPVirtualList structure and pass in a pointer to this structure as the <tt>ldvlistp</tt> argument.  


'''Note:''' 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 <tt>LDAP_CONTROL_VLVREQUEST</tt>, as defined in the <tt>ldap.h</tt> header file).  
'''Note:''' 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 <tt>LDAP_CONTROL_VLVREQUEST</tt>, as defined in the <tt>ldap.h</tt> header file).  
Line 3,662: Line 3,262:
Calling ldap_create_virtuallist_control() creates an LDAP control that you can pass to the ldap_search_ext() and ldap_search_ext_s() functions. You also need to pass a server-side sorting control to the search functions. You can call ldap_create_sort_keylist() and ldap_create_sort_control() to create a server-side sorting control. When you are done with the search, you should free the control by calling the ldap_control_free() function.  
Calling ldap_create_virtuallist_control() creates an LDAP control that you can pass to the ldap_search_ext() and ldap_search_ext_s() functions. You also need to pass a server-side sorting control to the search functions. You can call ldap_create_sort_keylist() and ldap_create_sort_control() to create a server-side sorting control. When you are done with the search, you should free the control by calling the ldap_control_free() function.  


<br> '''See Also'''


'''See Also'''
<br> LDAPVirtualList, ldap_parse_virtuallist_control(), ldap_search_ext() , ldap_search_ext_s(), ldap_control_free()  
 
 
LDAPVirtualList, ldap_parse_virtuallist_control(), ldap_search_ext() , ldap_search_ext_s(), ldap_control_free()


=== ldap_delete()  ===
=== ldap_delete()  ===
Line 3,673: Line 3,271:
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
int ldap_delete( LDAP *ld, const char *dn );</pre>  
int ldap_delete( LDAP *ld, const char *dn );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_delete() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_delete() Function Parameters"
Line 3,690: Line 3,288:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> Returns the message ID of the ldap_delete() operation.  
 
 
Returns the message ID of the ldap_delete() operation.  


'''Note:''' To check the result of this operation, call ldap_result and ldap_result2error(). See ldap_delete_ext_s() for a list of possible result codes for the LDAP delete operation.  
'''Note:''' To check the result of this operation, call ldap_result and ldap_result2error(). See ldap_delete_ext_s() for a list of possible result codes for the LDAP delete operation.  


<br> '''Description'''


'''Description'''
<br> Please use the newer version of this function, ldap_delete_ext() .  
 
 
Please use the newer version of this function, ldap_delete_ext() .  
 
 
'''Example'''


<br> '''Example'''


The following example uses the asynchronous ldap_delete() function to remove the entry for <tt>Barbara Jensen</tt> from the directory.  
<br> The following example uses the asynchronous ldap_delete() function to remove the entry for <tt>Barbara Jensen</tt> from the directory.  
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
...
...
Line 3,735: Line 3,327:
ldap_perror( ld, "ldap_delete" );
ldap_perror( ld, "ldap_delete" );
...</pre>  
...</pre>  
'''See Also'''


'''See Also'''
<br> ldap_delete_ext()  
 
 
ldap_delete_ext()  


=== ldap_delete_ext()  ===
=== ldap_delete_ext()  ===
Line 3,747: Line 3,337:
int ldap_delete_ext( LDAP *ld, const char *dn,
int ldap_delete_ext( LDAP *ld, const char *dn,
   LDAPControl **serverctrls, LDAPControl **clientctrls, int *msgidp );</pre>  
   LDAPControl **serverctrls, LDAPControl **clientctrls, int *msgidp );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_delete_ext() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_delete_ext() Function Parameters"
Line 3,773: Line 3,363:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:  
 
 
One of the following values:  


*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
Line 3,784: Line 3,372:
*LDAP_ENCODING_ERROR if an error occurred when BER-encoding the control.  
*LDAP_ENCODING_ERROR if an error occurred when BER-encoding the control.  
*LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.  
*LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.  
*LDAP_NOT_SUPPORTED 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.  
*LDAP_NOT_SUPPORTED 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.


'''Note:''' To check the result of this operation, call ldap_result and ldap_result2error(). See ldap_delete_ext_s() for a list of possible result codes for the LDAP delete operation.  
'''Note:''' To check the result of this operation, call ldap_result and ldap_result2error(). See ldap_delete_ext_s() for a list of possible result codes for the LDAP delete operation.  


<br> '''Description'''


'''Description'''
<br> The ldap_delete_ext() function deletes an entry from the directory, using the <tt>dn</tt> argument to specify the entry that you want to delete. ldap_delete_ext() 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 ldap_delete_ext_s() .  
 
 
The ldap_delete_ext() function deletes an entry from the directory, using the <tt>dn</tt> argument to specify the entry that you want to delete. ldap_delete_ext() 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 ldap_delete_ext_s() .  
 
 
'''See Also'''


<br> '''See Also'''


ldap_delete_ext_s(), ldap_result(), ldap_parse_result()  
<br> ldap_delete_ext_s(), ldap_result(), ldap_parse_result()  


=== ldap_delete_ext_s()  ===
=== ldap_delete_ext_s()  ===
Line 3,806: Line 3,390:
int ldap_delete_ext_s( LDAP *ld, const char *dn,
int ldap_delete_ext_s( LDAP *ld, const char *dn,
   LDAPControl **serverctrls, LDAPControl **clientctrls );</pre>  
   LDAPControl **serverctrls, LDAPControl **clientctrls );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_delete_ext_s() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_delete_ext_s() Function Parameters"
Line 3,829: Line 3,413:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:  
 
 
One of the following values:  
 
 
'''Returns'''


<br> '''Returns'''


One of the following values:  
<br> One of the following values:  


*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
Line 3,848: Line 3,428:
*LDAP_NOT_SUPPORTED 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.  
*LDAP_NOT_SUPPORTED 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.  
*LDAP_LOCAL_ERROR if an error occurred when receiving the results from the server.  
*LDAP_LOCAL_ERROR if an error occurred when receiving the results from the server.  
*LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded results from the server.  
*LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded results from the server.


'''Note:''' Directory Server 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.  
'''Note:''' Directory Server 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.  


<br> '''Description'''


'''Description'''
<br> The ldap_delete_ext_s() function deletes an entry from the directory, using the <tt>dn</tt> argument to specify the entry that you want to delete. ldap_delete_ext_s() 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 ldap_delete_ext() instead.  
 
 
The ldap_delete_ext_s() function deletes an entry from the directory, using the <tt>dn</tt> argument to specify the entry that you want to delete. ldap_delete_ext_s() 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 ldap_delete_ext() instead.  
 
 
'''See Also'''


<br> '''See Also'''


ldap_delete_ext()  
<br> ldap_delete_ext()  


=== ldap_delete_s()  ===
=== ldap_delete_s()  ===
Line 3,869: Line 3,445:
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
int ldap_delete_s(LDAP *ld, const char *dn);</pre>  
int ldap_delete_s(LDAP *ld, const char *dn);</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_delete_s() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_delete_s() Function Parameters"
Line 3,886: Line 3,462:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> For a list of possible result codes for an LDAP delete operation, see the ldap_delete_ext_s() function.  
 
 
For a list of possible result codes for an LDAP delete operation, see the ldap_delete_ext_s() function.
 
 
'''Description'''
 
 
Please use the newer version of this function, ldap_delete_ext_s() .  


<br> '''Description'''


'''Example'''
<br> Please use the newer version of this function, ldap_delete_ext_s() .


<br> '''Example'''


The following example uses the synchronous ldap_delete_s() function to delete the entry for <tt>Barbara Jensen</tt> from the directory.  
<br> The following example uses the synchronous ldap_delete_s() function to delete the entry for <tt>Barbara Jensen</tt> from the directory.  
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
LDAP *ld;
LDAP *ld;
Line 3,914: Line 3,484:
}
}
...</pre>  
...</pre>  
'''See Also'''


'''See Also'''
<br> ldap_delete_ext_s()  
 
 
ldap_delete_ext_s()  


=== ldap_dn2ufn()  ===
=== ldap_dn2ufn()  ===
Line 3,924: Line 3,492:
The ldap_dn2ufn() function converts a DN into a more user-friendly form by stripping off the cryptic type names.  
The ldap_dn2ufn() function converts a DN into a more user-friendly form by stripping off the cryptic type names.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
char * ldap_dn2ufn( const char *dn );</pre>  
char * ldap_dn2ufn( const char *dn );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_dn2ufn() Function Parameter"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_dn2ufn() Function Parameter"
Line 3,943: Line 3,509:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:  
 
 
One of the following values:  


*If successful, returns the DN in its friendlier form.  
*If successful, returns the DN in its friendlier form.  
*If unsuccessful, returns <tt>NULL</tt>.
*If unsuccessful, returns <tt>NULL</tt>.


<br> '''Description'''


'''Description'''
<br> For more information on user friendly naming (UFN), see RFC 1781,&lt;citetitle&gt; Using the OSI Directory to Achieve User Friendly Naming &lt;/citetitle&gt; (&lt;ulink url="http://www.faqs.org/rfcs/rfc1781.html" type="text_url"&gt;&lt;/ulink&gt;).  
 
 
For more information on user friendly naming (UFN), see RFC 1781,&lt;citetitle&gt; Using the OSI Directory to Achieve User Friendly Naming &lt;/citetitle&gt; (&lt;ulink url="http://www.faqs.org/rfcs/rfc1781.html" type="text_url"&gt;&lt;/ulink&gt;).  


=== ldap_entry2html()  ===
=== ldap_entry2html()  ===
Line 3,962: Line 3,524:
The ldap_entry2html() function writes the HTML representation of an LDAP entry.  
The ldap_entry2html() function writes the HTML representation of an LDAP entry.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;disptmpl.h&gt;
<pre>#include &lt;disptmpl.h&gt;
int ldap_entry2html( LDAP *ld, char *buf, LDAPMessage *entry,
int ldap_entry2html( LDAP *ld, char *buf, LDAPMessage *entry,
Line 3,970: Line 3,530:
   writeptype writeproc, void *writeparm, char *eol, int rdncount,
   writeptype writeproc, void *writeparm, char *eol, int rdncount,
   unsigned long opts, char *urlprefix, char *base );</pre>  
   unsigned long opts, char *urlprefix, char *base );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_entry2html() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_entry2html() Function Parameters"
Line 4,024: Line 3,584:
|}
|}


<br> '''Returns'''


'''Returns'''
<br>
 


*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
*An LDAP error code on error.
*An LDAP error code on error.


<br> '''Description'''


'''Description'''
<br> ldap_entry2html() produces an HTML representation of an entry. It behaves exactly like ldap_entry2text() except for the output and the addition of two parameters.  
 
 
ldap_entry2html() produces an HTML representation of an entry. It behaves exactly like ldap_entry2text() except for the output and the addition of two parameters.  
 
 
'''See Also'''


<br> '''See Also'''


ldap_entry2text(), ldap_oc2template  
<br> ldap_entry2text(), ldap_oc2template  


=== ldap_entry2html_search()  ===
=== ldap_entry2html_search()  ===
Line 4,047: Line 3,603:
The ldap_entry2html_search() function determines the appropriate display template to use by calling ldap_oc2template().  
The ldap_entry2html_search() function determines the appropriate display template to use by calling ldap_oc2template().  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;disptmpl.h&gt;
<pre>#include &lt;disptmpl.h&gt;
int ldap_entry2html_search( LDAP *ld, char *dn, char *base,
int ldap_entry2html_search( LDAP *ld, char *dn, char *base,
Line 4,055: Line 3,609:
   char ***defvals, writeptype writeproc, void *writeparm, char *eol,
   char ***defvals, writeptype writeproc, void *writeparm, char *eol,
   int rdncount, unsigned long opts, char *urlprefix );</pre>  
   int rdncount, unsigned long opts, char *urlprefix );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_entry2html_search() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_entry2html_search() Function Parameters"
Line 4,109: Line 3,663:
|}
|}


<br> '''Returns'''


'''Returns'''
<br>
 


*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
*An LDAP error code on error.
*An LDAP error code on error.


<br> '''Description'''


'''Description'''
<br> ldap_entry2html_search() will call ldap_search_s() to retrieve any attribute values to be displayed. It behaves exactly like ldap_entry2text_search(), except the <tt>urlprefix</tt> parameter is required and HTML is the output.  
 
 
ldap_entry2html_search() will call ldap_search_s() to retrieve any attribute values to be displayed. It behaves exactly like ldap_entry2text_search(), except the <tt>urlprefix</tt> parameter is required and HTML is the output.  
 
 
'''See Also'''


<br> '''See Also'''


ldap_search_s(), ldap_entry2text_search(), ldap_init_templates(), ldap_init_templates_buf(), ldap_entry2text()  
<br> ldap_search_s(), ldap_entry2text_search(), ldap_init_templates(), ldap_init_templates_buf(), ldap_entry2text()  


=== ldap_entry2text()  ===
=== ldap_entry2text()  ===
Line 4,132: Line 3,682:
The ldap_entry2text() function writes the text representation of an LDAP entry.  
The ldap_entry2text() function writes the text representation of an LDAP entry.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;disptmpl.h&gt;
<pre>#include &lt;disptmpl.h&gt;
int ldap_entry2text( LDAP *ld, char *buf, LDAPMessage *entry,
int ldap_entry2text( LDAP *ld, char *buf, LDAPMessage *entry,
Line 4,140: Line 3,688:
   writeptype writeproc, void *writeparm, char *eol, int rdncount,
   writeptype writeproc, void *writeparm, char *eol, int rdncount,
   unsigned long opts );</pre>  
   unsigned long opts );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_entry2text() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_entry2text() Function Parameters"
Line 4,188: Line 3,736:
|}
|}


<br> '''Returns'''


'''Returns'''
<br>
 


*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
*An LDAP error code on error.
*An LDAP error code on error.


<br> '''Description'''


'''Description'''
<br> ldap_entry2text() produces a text representation of an entry and writes the text by calling the <tt>writeproc</tt> function. All of the attribute values to be displayed must be present in entry as no interaction with the LDAP server will be performed.  
 
 
ldap_entry2text() produces a text representation of an entry and writes the text by calling the <tt>writeproc</tt> function. All of the attribute values to be displayed must be present in entry as no interaction with the LDAP server will be performed.  
 
 
'''See Also'''


<br> '''See Also'''


ldap_entry2html(), ldap_oc2template  
<br> ldap_entry2html(), ldap_oc2template  


=== ldap_entry2text_search()  ===
=== ldap_entry2text_search()  ===
Line 4,211: Line 3,755:
The ldap_entry2text_search() function determines the appropriate display template to use by calling ldap_oc2template().  
The ldap_entry2text_search() function determines the appropriate display template to use by calling ldap_oc2template().  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;disptmpl.h&gt;
<pre>#include &lt;disptmpl.h&gt;
int ldap_entry2text_search( LDAP *ld, char *dn, char *base,
int ldap_entry2text_search( LDAP *ld, char *dn, char *base,
Line 4,219: Line 3,761:
   char ***defvals, writeptype writeproc, void *writeparm,
   char ***defvals, writeptype writeproc, void *writeparm,
   char *eol, int rdncount, unsigned long opts );</pre>  
   char *eol, int rdncount, unsigned long opts );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_entry2text_search() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_entry2text_search() Function Parameters"
Line 4,270: Line 3,812:
|}
|}


<br> '''Returns'''


'''Returns'''
<br>
 


*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
*An LDAP error code on error.
*An LDAP error code on error.


<br> '''Description'''


'''Description'''
<br> ldap_entry2text_search() will call ldap_search_s() to retrieve any attribute values to be displayed.  
 
 
ldap_entry2text_search() will call ldap_search_s() to retrieve any attribute values to be displayed.  
 
 
'''See Also'''


<br> '''See Also'''


ldap_entry2html_search(), ldap_oc2template(), ldap_search_s(), ldap_init_templates(), ldap_init_templates_buf()  
<br> ldap_entry2html_search(), ldap_oc2template(), ldap_search_s(), ldap_init_templates(), ldap_init_templates_buf()  


=== ldap_err2string()  ===
=== ldap_err2string()  ===
Line 4,293: Line 3,831:
The ldap_err2string() function returns the corresponding error message for an error code.  
The ldap_err2string() function returns the corresponding error message for an error code.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
char * ldap_err2string( int err );</pre>  
char * ldap_err2string( int err );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_err2string() Function Parameter"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_err2string() Function Parameter"
Line 4,312: Line 3,848:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:
 


One of the following values:
*If successful, returns the corresponding error message for the error code.  
*If successful, returns the corresponding error message for the error code.  
*If unsuccessful (for example, if the error code is not a valid LDAP API error code), returns <tt>Unknown error</tt>.  
*If unsuccessful (for example, if the error code is not a valid LDAP API error code), returns <tt>Unknown error</tt>.
 
 
'''Example'''


<br> '''Example'''


The following example sets the variable ''err_msg'' to the error message corresponding to the error code returned by the ldap_simple_bind_s() function.  
<br> The following example sets the variable ''err_msg'' to the error message corresponding to the error code returned by the ldap_simple_bind_s() function.  
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
...
...
Line 4,334: Line 3,867:
err_msg = ldap_err2string( ldap_simple_bind_s( ld, dn, pw ) );
err_msg = ldap_err2string( ldap_simple_bind_s( ld, dn, pw ) );
...</pre>  
...</pre>  
'''See Also'''


'''See Also'''
<br> ldap_get_lderrno(), ldap_perror(), ldap_result2error(), ldap_set_lderrno(), ldapssl_err2string()  
 
 
ldap_get_lderrno(), ldap_perror(), ldap_result2error(), ldap_set_lderrno(), ldapssl_err2string()  


=== ldap_explode_dn()  ===
=== ldap_explode_dn()  ===
Line 4,344: Line 3,875:
The ldap_explode_dn() function converts a DN into its component parts.  
The ldap_explode_dn() function converts a DN into its component parts.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
char ** ldap_explode_dn( const char *dn, int notypes );</pre>  
char ** ldap_explode_dn( const char *dn, int notypes );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_explode_dn() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_explode_dn() Function Parameters"
Line 4,366: Line 3,895:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:  
 
 
One of the following values:  


*If successful, returns a <tt>NULL</tt> terminated array containing the components of the DN.  
*If successful, returns a <tt>NULL</tt> terminated array containing the components of the DN.  
*If unsuccessful, returns <tt>NULL</tt>.
*If unsuccessful, returns <tt>NULL</tt>.


<br> '''Example'''


'''Example'''
<br> The following function call:  
 
 
The following function call:  
<pre>ldap_explode_dn( "uid=bjensen,ou=People,dc=example,dc=com", 0 );</pre>  
<pre>ldap_explode_dn( "uid=bjensen,ou=People,dc=example,dc=com", 0 );</pre>  
returns this array:  
returns this array:  
Line 4,387: Line 3,912:
The component names are not returned in the array:  
The component names are not returned in the array:  
<pre>{ "bjensen", "People", "example.com", NULL }</pre>  
<pre>{ "bjensen", "People", "example.com", NULL }</pre>  
'''See Also'''


'''See Also'''
<br> ldap_explode_rdn(), ldap_get_dn()  
 
 
ldap_explode_rdn(), ldap_get_dn()  


=== ldap_explode_dns()  ===
=== ldap_explode_dns()  ===
Line 4,399: Line 3,922:
The ldap_explode_dns() function takes a DNS-style DN, breaks it up into its component parts, and returns a <tt>NULL</tt> terminated array. For example, the DN <tt>ldap.example.com</tt> will return <tt>{ "ldap", "example", "com", NULL </tt>}. The result can be freed by calling ldap_value_free().  
The ldap_explode_dns() function takes a DNS-style DN, breaks it up into its component parts, and returns a <tt>NULL</tt> terminated array. For example, the DN <tt>ldap.example.com</tt> will return <tt>{ "ldap", "example", "com", NULL </tt>}. The result can be freed by calling ldap_value_free().  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap-to-be-deprecated.h&gt;
<pre>#include &lt;ldap-to-be-deprecated.h&gt;
char ** ldap_explode_dns( const char *dn );</pre>  
char ** ldap_explode_dns( const char *dn );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_explode_dns() Function Parameter"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_explode_dns() Function Parameter"
Line 4,418: Line 3,939:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:
 


One of the following values:
*If successful, returns a <tt>NULL</tt> terminated array containing the components of the DN.  
*If successful, returns a <tt>NULL</tt> terminated array containing the components of the DN.  
*If unsuccessful, returns <tt>NULL</tt>.
*If unsuccessful, returns <tt>NULL</tt>.
Line 4,430: Line 3,950:
The ldap_explode_rdn() function converts a relative distinguished name (RDN) into its component parts.  
The ldap_explode_rdn() function converts a relative distinguished name (RDN) into its component parts.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
char ** ldap_explode_rdn( const char *dn, int notypes );</pre>  
char ** ldap_explode_rdn( const char *dn, int notypes );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_explode_rdn() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_explode_rdn() Function Parameters"
Line 4,452: Line 3,970:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:  
 
 
One of the following values:  


*If successful, returns a <tt>NULL</tt> terminated array containing the components of the RDN.  
*If successful, returns a <tt>NULL</tt> terminated array containing the components of the RDN.  
*If unsuccessful, returns <tt>NULL</tt>.
*If unsuccessful, returns <tt>NULL</tt>.


<br> '''Example'''


'''Example'''
<br> The following function call:  
 
 
The following function call:  
<pre>ldap_explode_rdn( "ou=Sales + cn=Barbara Jensen", 0 );</pre>  
<pre>ldap_explode_rdn( "ou=Sales + cn=Barbara Jensen", 0 );</pre>  
returns this array:  
returns this array:  
<pre>{ "ou=Sales", "cn=Barbara Jensen", NULL }</pre>  
<pre>{ "ou=Sales", "cn=Barbara Jensen", NULL }</pre>  
'''See Also'''


'''See Also'''
<br> ldap_explode_dn(), ldap_get_dn  
 
 
ldap_explode_dn(), ldap_get_dn  


=== ldap_extended_operation()  ===
=== ldap_extended_operation()  ===
Line 4,479: Line 3,991:
The ldap_extended_operation() function sends a request to the server to perform an extended operation asynchronously.  
The ldap_extended_operation() function sends a request to the server to perform an extended operation asynchronously.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
int ldap_extended_operation( LDAP *ld, const char *requestoid,
int ldap_extended_operation( LDAP *ld, const char *requestoid,
   struct berval *requestdata, LDAPControl **serverctrls,
   struct berval *requestdata, LDAPControl **serverctrls,
   LDAPControl **clientctrls, int *msgidp );</pre>  
   LDAPControl **clientctrls, int *msgidp );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_extended_operation() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_extended_operation() Function Parameters"
Line 4,515: Line 4,025:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:
 


One of the following values:
*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
*LDAP_PARAM_ERROR if an invalid parameter was passed to the function.  
*LDAP_PARAM_ERROR if an invalid parameter was passed to the function.  
Line 4,525: Line 4,034:
*LDAP_ENCODING_ERROR if an error occurred when BER-encoding the control.  
*LDAP_ENCODING_ERROR if an error occurred when BER-encoding the control.  
*LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.  
*LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.  
*LDAP_NOT_SUPPORTED 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.  
*LDAP_NOT_SUPPORTED 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.


The ldap_extended_operation() function sends a request to the server to perform an LDAP v3 extended operation. ldap_extended_operation() 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 ldap_extended_operation_s().  
The ldap_extended_operation() function sends a request to the server to perform an LDAP v3 extended operation. ldap_extended_operation() 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 ldap_extended_operation_s().  


<br> '''See Also'''


'''See Also'''
<br> ldap_extended_operation_s(), ldap_result(), ldap_parse_extended_result(), ldap_get_lderrno(), ber_flatten()  
 
 
ldap_extended_operation_s(), ldap_result(), ldap_parse_extended_result(), ldap_get_lderrno(), ber_flatten()  


=== ldap_extended_operation_s()  ===
=== ldap_extended_operation_s()  ===
Line 4,539: Line 4,046:
The ldap_extended_operation_s() function sends a request to the server to perform an extended operation synchronously.  
The ldap_extended_operation_s() function sends a request to the server to perform an extended operation synchronously.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
int ldap_extended_operation_s( LDAP *ld, const char *requestoid,
int ldap_extended_operation_s( LDAP *ld, const char *requestoid,
   struct berval *requestdata, LDAPControl **serverctrls,
   struct berval *requestdata, LDAPControl **serverctrls,
   LDAPControl **clientctrls, char **retoidp, struct berval **retdatap );</pre>  
   LDAPControl **clientctrls, char **retoidp, struct berval **retdatap );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_extended_operation_s() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_extended_operation_s() Function Parameters"
Line 4,578: Line 4,083:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:
 


One of the following values:
*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
*LDAP_PARAM_ERROR if an invalid parameter was passed to the function.  
*LDAP_PARAM_ERROR if an invalid parameter was passed to the function.  
Line 4,590: Line 4,094:
*LDAP_LOCAL_ERROR if an error occurred when receiving the results from the server.  
*LDAP_LOCAL_ERROR if an error occurred when receiving the results from the server.  
*LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded results from the server.  
*LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded results from the server.  
*LDAP_NOT_SUPPORTED 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.  
*LDAP_NOT_SUPPORTED 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.


'''Note:''' Directory Server 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.  
'''Note:''' Directory Server 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.  


<br> '''Description'''


'''Description'''
<br> The ldap_extended_operation_s() function sends a request to the server to perform an LDAP v3 extended operation. See also ldap_extended_operation(), ber_flatten()  
 
 
The ldap_extended_operation_s() function sends a request to the server to perform an LDAP v3 extended operation. See also ldap_extended_operation(), ber_flatten()  


=== ldap_first_attribute()  ===
=== ldap_first_attribute()  ===
Line 4,604: Line 4,106:
The ldap_first_attribute() function returns the name of the first attribute in an entry returned by the ldap_first_entry() , the ldap_next_entry(), or the ldap_result() functions.  
The ldap_first_attribute() function returns the name of the first attribute in an entry returned by the ldap_first_entry() , the ldap_next_entry(), or the ldap_result() functions.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
char * ldap_first_attribute( LDAP *ld, LDAPMessage *entry,
char * ldap_first_attribute( LDAP *ld, LDAPMessage *entry,
   BerElement **ber );</pre>  
   BerElement **ber );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_first_attribute() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_first_attribute() Function Parameters"
Line 4,630: Line 4,130:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:
 


One of the following values:
*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 ldap_memfree() function.  
*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 ldap_memfree() function.  
*If unsuccessful, returns a <tt>NULL</tt> and sets the appropriate error code in the LDAP structure. To get the error code, call the ldap_get_lderrno() function.  
*If unsuccessful, returns a <tt>NULL</tt> and sets the appropriate error code in the LDAP structure. To get the error code, call the ldap_get_lderrno() function.
 
 
'''Example'''


<br> '''Example'''


The following example retrieves each attribute for an entry.  
<br> The following example retrieves each attribute for an entry.  
<pre>#include &lt;stdio.h&gt;
<pre>#include &lt;stdio.h&gt;
#include &lt;ldap.h&gt;
#include &lt;ldap.h&gt;
Line 4,676: Line 4,173:
   }
   }
...</pre>  
...</pre>  
'''See Also'''


'''See Also'''
<br> ldap_first_entry(), ldap_next_entry(), ldap_next_attribute(), BerElement  
 
 
ldap_first_entry(), ldap_next_entry(), ldap_next_attribute(), BerElement  


=== ldap_first_disptmpl()  ===
=== ldap_first_disptmpl()  ===
Line 4,686: Line 4,181:
The ldap_first_disptmpl() function returns the first template in a list.  
The ldap_first_disptmpl() function returns the first template in a list.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;disptmpl.h&gt;
<pre>#include &lt;disptmpl.h&gt;
ldap_first_disptmpl( struct ldap_disptmpl *tmpllist );</pre>  
ldap_first_disptmpl( struct ldap_disptmpl *tmpllist );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_first_disptmpl() Function Parameter"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_first_disptmpl() Function Parameter"
Line 4,705: Line 4,198:
|}
|}


<br> '''Description'''


'''Description'''
<br> ldap_first_disptmpl() returns the first template in the list of templates pointed to by the parameter <tt>tmpllistp</tt>. <tt>tmpllistp</tt> is typically obtained by calling ldap_init_templates() .  
 
 
ldap_first_disptmpl() returns the first template in the list of templates pointed to by the parameter <tt>tmpllistp</tt>. <tt>tmpllistp</tt> is typically obtained by calling ldap_init_templates() .  
 
 
'''See Also'''


<br> '''See Also'''


ldap_next_disptmpl(), ldap_init_templates(), ldap_init_templates_buf()  
<br> ldap_next_disptmpl(), ldap_init_templates(), ldap_init_templates_buf()  


=== ldap_first_entry()  ===
=== ldap_first_entry()  ===
Line 4,721: Line 4,210:
The ldap_first_entry() function returns a pointer to the LDAPMessage structure representing the first directory entry in a chain of search results.  
The ldap_first_entry() function returns a pointer to the LDAPMessage structure representing the first directory entry in a chain of search results.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
LDAPMessage * ldap_first_entry( LDAP *ld, LDAPMessage *result );</pre>  
LDAPMessage * ldap_first_entry( LDAP *ld, LDAPMessage *result );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_first_entry() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_first_entry() Function Parameters"
Line 4,743: Line 4,230:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:  
 
 
One of the following values:  


*If successful, returns the pointer to the first LDAPMessage structure of the type <tt>LDAP_RES_SEARCH_ENTRY</tt> in the chain of search results.  
*If successful, returns the pointer to the first LDAPMessage structure of the type <tt>LDAP_RES_SEARCH_ENTRY</tt> in the chain of search results.  
*If no LDAPMessage structure of the type <tt>LDAP_RES_SEARCH_ENTRY</tt> are in the chain of the search results or if the function is unsuccessful, returns a <tt>NULLMSG</tt>.
*If no LDAPMessage structure of the type <tt>LDAP_RES_SEARCH_ENTRY</tt> are in the chain of the search results or if the function is unsuccessful, returns a <tt>NULLMSG</tt>.


<br> '''Description'''


'''Description'''
<br> The ldap_first_entry() function returns a pointer to the LDAPMessage structure representing the first directory entry in a chain of search results. Search result entries are in messages of the type <tt>LDAP_RES_SEARCH_ENTRY</tt>. You can use this function in conjunction with the ldap_next_entry() 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 <tt>LDAP_RES_SEARCH_ENTRY</tt>. Do not free the LDAPMessage 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.  
 
 
The ldap_first_entry() function returns a pointer to the LDAPMessage structure representing the first directory entry in a chain of search results. Search result entries are in messages of the type <tt>LDAP_RES_SEARCH_ENTRY</tt>. You can use this function in conjunction with the ldap_next_entry() 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 <tt>LDAP_RES_SEARCH_ENTRY</tt>. Do not free the LDAPMessage 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.  
 
 
'''See Also'''


<br> '''See Also'''


ldap_result(), ldap_search_ext() , ldap_search_ext_s(), ldap_next_entry()
<br> ldap_result(), ldap_search_ext() , ldap_search_ext_s(), ldap_next_entry()  


=== ldap_first_message()  ===
=== ldap_first_message()  ===
Line 4,768: Line 4,249:
The ldap_first_message() function returns a pointer to the first LDAPMessage structure in a chain of search results.  
The ldap_first_message() function returns a pointer to the first LDAPMessage structure in a chain of search results.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
LDAPMessage * ldap_first_message( LDAP *ld, LDAPMessage *res );</pre>  
LDAPMessage * ldap_first_message( LDAP *ld, LDAPMessage *res );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_first_message() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_first_message() Function Parameters"
Line 4,790: Line 4,269:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:  
 
 
One of the following values:  


*If successful, returns the pointer to the first LDAPMessage structure in the chain of search results.  
*If successful, returns the pointer to the first LDAPMessage structure in the chain of search results.  
*If no LDAPMessage structures are in the chain or if the function is unsuccessful, returns a <tt>NULLMSG</tt>.
*If no LDAPMessage structures are in the chain or if the function is unsuccessful, returns a <tt>NULLMSG</tt>.
 
 
'''Description'''
 
 
The ldap_first_message() function returns a pointer to the first LDAPMessage structure in a chain of search results. You can use this function in conjunction with the ldap_next_message() function to iterate through the chain of search results. You can also call the ldap_msgtype() function to determine if each message contains a matching entry, a message of the type <tt>LDAP_RES_SEARCH_ENTRY</tt>, or a search reference, a message of the type <tt>LDAP_RES_SEARCH_REFERENCE</tt>. Do not free the LDAPMessage 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.  


<br> '''Description'''


'''See Also'''
<br> The ldap_first_message() function returns a pointer to the first LDAPMessage structure in a chain of search results. You can use this function in conjunction with the ldap_next_message() function to iterate through the chain of search results. You can also call the ldap_msgtype() function to determine if each message contains a matching entry, a message of the type <tt>LDAP_RES_SEARCH_ENTRY</tt>, or a search reference, a message of the type <tt>LDAP_RES_SEARCH_REFERENCE</tt>. Do not free the LDAPMessage 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.


<br> '''See Also'''


ldap_result(), ldap_search_ext() , ldap_search_ext_s(), ldap_next_message(), ldap_first_entry(), ldap_first_reference()  
<br> ldap_result(), ldap_search_ext() , ldap_search_ext_s(), ldap_next_message(), ldap_first_entry(), ldap_first_reference()  


=== ldap_first_reference()  ===
=== ldap_first_reference()  ===
Line 4,815: Line 4,288:
The ldap_first_reference() function returns a pointer to the LDAPMessage structure representing the first search reference in a chain of search results.  
The ldap_first_reference() function returns a pointer to the LDAPMessage structure representing the first search reference in a chain of search results.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
LDAPMessage * ldap_first_reference(LDAP *ld, LDAPMessage *res );</pre>  
LDAPMessage * ldap_first_reference(LDAP *ld, LDAPMessage *res );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_first_reference() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_first_reference() Function Parameters"
Line 4,837: Line 4,308:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:
 


One of the following values:
*If successful, returns the pointer to the first LDAPMessage structure of the type <tt>LDAP_RES_SEARCH_REFERENCE</tt> in the chain of search results.  
*If successful, returns the pointer to the first LDAPMessage structure of the type <tt>LDAP_RES_SEARCH_REFERENCE</tt> in the chain of search results.  
*If no LDAPMessage structures of the type <tt>LDAP_RES_SEARCH_REFERENCE</tt> are in the chain of the search results or if the function is unsuccessful, returns a <tt>NULLMSG</tt>.
*If no LDAPMessage structures of the type <tt>LDAP_RES_SEARCH_REFERENCE</tt> are in the chain of the search results or if the function is unsuccessful, returns a <tt>NULLMSG</tt>.
 
 
'''Description'''
 
 
The ldap_first_reference() function returns a pointer to the LDAPMessage structure representing the first search reference in a chain of search results. Search references are in messages of the type <tt>LDAP_RES_SEARCH_REFERENCE</tt>, 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. You can use this function in conjunction with the ldap_next_reference 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 <tt>LDAP_RES_SEARCH_REFERENCE</tt>. Do not free the LDAPMessage 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.  


<br> '''Description'''


'''See Also'''
<br> The ldap_first_reference() function returns a pointer to the LDAPMessage structure representing the first search reference in a chain of search results. Search references are in messages of the type <tt>LDAP_RES_SEARCH_REFERENCE</tt>, 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. You can use this function in conjunction with the ldap_next_reference 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 <tt>LDAP_RES_SEARCH_REFERENCE</tt>. Do not free the LDAPMessage 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.


<br> '''See Also'''


ldap_result(), ldap_search_ext() , ldap_search_ext_s(), ldap_next_reference(), ldap_first_message()  
<br> ldap_result(), ldap_search_ext() , ldap_search_ext_s(), ldap_next_reference(), ldap_first_message()  


=== ldap_first_searchobj()  ===
=== ldap_first_searchobj()  ===
Line 4,861: Line 4,327:
The ldap_first_searchobj() function returns the first search preference configuration from a data structure defined in the list <tt>solist</tt> .  
The ldap_first_searchobj() function returns the first search preference configuration from a data structure defined in the list <tt>solist</tt> .  


 
<br> '''Syntax'''  
'''Syntax'''
<pre>#include &lt;ldap.h&gt;
 
<pre>#include &lt;ldap.h&gt;
ldap_searchobj * ldap_first_searchobj( struct ldap_searchobj *solist );</pre>  
ldap_searchobj * ldap_first_searchobj( struct ldap_searchobj *solist );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_first_searchobj() Function Parameter"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_first_searchobj() Function Parameter"
Line 4,880: Line 4,344:
|}
|}


<br> '''Description'''


'''Description'''
<br> <tt>ldap_first_searchobj</tt> 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.  
 
 
<tt>ldap_first_searchobj</tt> 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.  
 
 
'''See Also'''


<br> '''See Also'''


ldap_init_searchprefs(), ldap_init_searchprefs_buf()  
<br> ldap_init_searchprefs(), ldap_init_searchprefs_buf()  


=== ldap_first_tmplcol()  ===
=== ldap_first_tmplcol()  ===
Line 4,896: Line 4,356:
The ldap_first_tmplcol() function returns a pointer to the first item within a template.  
The ldap_first_tmplcol() function returns a pointer to the first item within a template.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;disptmpl.h&gt;
<pre>#include &lt;disptmpl.h&gt;
struct ldap_tmplitem * ldap_first_tmplcol( struct ldap_disptmpl *tmpl,
struct ldap_tmplitem * ldap_first_tmplcol( struct ldap_disptmpl *tmpl,
   struct ldap_tmplitem *row );</pre>  
   struct ldap_tmplitem *row );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_first_tmplcol() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_first_tmplcol() Function Parameters"
Line 4,919: Line 4,377:
|}
|}


<br> '''Returns'''


'''Returns'''
<br>
 


*If successful, a pointer to an <tt>ldap_tmplitem</tt> structure.  
*If successful, a pointer to an <tt>ldap_tmplitem</tt> structure.  
*A <tt>NULL</tt> pointer on error.
*A <tt>NULL</tt> pointer on error.


<br> '''Description'''


'''Description'''
<br> ldap_first_tmplcol() returns a pointer to the first item (in the first column) of the row, defined by <tt>row</tt>, within the template defined by <tt>tmpl</tt>.  
 
 
ldap_first_tmplcol() returns a pointer to the first item (in the first column) of the row, defined by <tt>row</tt>, within the template defined by <tt>tmpl</tt>.  
 
 
'''See Also'''


<br> '''See Also'''


ldap_first_tmplrow(), ldap_next_tmplcol()  
<br> ldap_first_tmplrow(), ldap_next_tmplcol()  


=== ldap_first_tmplrow()  ===
=== ldap_first_tmplrow()  ===
Line 4,942: Line 4,396:
The ldap_first_tmplrow() function returns a pointer to the first row of items in a template.  
The ldap_first_tmplrow() function returns a pointer to the first row of items in a template.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;disptmpl.h&gt;
<pre>#include &lt;disptmpl.h&gt;
struct ldap_tmplitem * ldap_first_tmplrow( struct ldap_disptmpl *tmpl );</pre>  
struct ldap_tmplitem * ldap_first_tmplrow( struct ldap_disptmpl *tmpl );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_first_tmplrow() Function Parameter"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_first_tmplrow() Function Parameter"
Line 4,961: Line 4,413:
|}
|}


<br> '''Returns'''


'''Returns'''
<br>
 


*If successful, a pointer to an <tt>ldap_tmplitem</tt> structure.  
*If successful, a pointer to an <tt>ldap_tmplitem</tt> structure.  
*A <tt>NULL</tt> pointer on error.
*A <tt>NULL</tt> pointer on error.


<br> '''See Also'''


'''See Also'''
<br> ldap_next_tmplrow(), ldap_first_tmplcol()  
 
 
ldap_next_tmplrow(), ldap_first_tmplcol()  


=== ldap_free_friendlymap()  ===
=== ldap_free_friendlymap()  ===
Line 4,978: Line 4,428:
The ldap_free_friendlymap() function frees the FriendlyMap structures allocated by the ldap_friendly_name() function when no more calls to it are to be made.  
The ldap_free_friendlymap() function frees the FriendlyMap structures allocated by the ldap_friendly_name() function when no more calls to it are to be made.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
void ldap_free_friendlymap( FriendlyMap *map );</pre>  
void ldap_free_friendlymap( FriendlyMap *map );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_free_friendlymap() Function Parameter"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_free_friendlymap() Function Parameter"
Line 4,997: Line 4,445:
|}
|}


<br> '''Example'''


'''Example'''
<br> The following example frees memory allocated by the ldap_friendly_name() function.  
 
 
The following example frees memory allocated by the ldap_friendly_name() function.  
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
#include &lt;stdio.h&gt;
#include &lt;stdio.h&gt;
Line 5,019: Line 4,465:
ldap_free_friendlymap( map );
ldap_free_friendlymap( map );
...</pre>  
...</pre>  
'''See Also'''


'''See Also'''
<br> ldap_friendly_name(), FriendlyMap()  
 
 
ldap_friendly_name(), FriendlyMap()  


=== ldap_free_searchprefs()  ===
=== ldap_free_searchprefs()  ===
Line 5,029: Line 4,473:
The ldap_free_searchprefs() function disposes of the data structures allocated by ldap_init_searchprefs().  
The ldap_free_searchprefs() function disposes of the data structures allocated by ldap_init_searchprefs().  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
void ldap_free_searchprefs( struct ldap_searchobj *solist );</pre>  
void ldap_free_searchprefs( struct ldap_searchobj *solist );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_free_searchprefs() Function Parameter"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_free_searchprefs() Function Parameter"
Line 5,048: Line 4,490:
|}
|}


<br> '''See Also'''


'''See Also'''
<br> ldap_init_searchprefs(), ldap_init_searchprefs_buf()  
 
 
ldap_init_searchprefs(), ldap_init_searchprefs_buf()  


=== ldap_free_sort_keylist()  ===
=== ldap_free_sort_keylist()  ===
Line 5,058: Line 4,498:
The ldap_free_sort_keylist() function frees the structures allocated by the ldap_create_sort_keylist() function.  
The ldap_free_sort_keylist() function frees the structures allocated by the ldap_create_sort_keylist() function.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
void ldap_free_sort_keylist (LDAPsortkey **sortKeyList);</pre>  
void ldap_free_sort_keylist (LDAPsortkey **sortKeyList);</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_free_sort_keylist() Function Parameter"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_free_sort_keylist() Function Parameter"
Line 5,077: Line 4,515:
|}
|}


<br> '''Description'''


'''Description'''
<br> The ldap_free_sort_keylist() function frees the array of LDAPsortkey structures allocated by the ldap_create_sort_keylist() function. When done sorting results, call this function to free the memory that you have allocated. This function must be called after the ldap_create_sort_control() function has completed.  
 
 
The ldap_free_sort_keylist() function frees the array of LDAPsortkey structures allocated by the ldap_create_sort_keylist() function. When done sorting results, call this function to free the memory that you have allocated. This function must be called after the ldap_create_sort_control() function has completed.  
 
 
'''See Also'''


<br> '''See Also'''


ldap_create_sort_keylist(), ldap_create_sort_control()  
<br> ldap_create_sort_keylist(), ldap_create_sort_control()  


=== ldap_free_templates()  ===
=== ldap_free_templates()  ===
Line 5,093: Line 4,527:
The ldap_free_templates() function disposes of the templates allocated by ldap_init_templates().  
The ldap_free_templates() function disposes of the templates allocated by ldap_init_templates().  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;disptmpl.h&gt;
<pre>#include &lt;disptmpl.h&gt;
void ldap_free_templates( struct ldap_disptmpl *tmpllist );</pre>  
void ldap_free_templates( struct ldap_disptmpl *tmpllist );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_free_templates() Function Parameter"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_free_templates() Function Parameter"
Line 5,112: Line 4,544:
|}
|}


<br> '''Description'''


'''Description'''
<br> ldap_free_templates() releases the templates allocated by ldap_init_templates(). Each template defined in the file is an <tt>ldap_disptmpl</tt> structure.  
 
 
ldap_free_templates() releases the templates allocated by ldap_init_templates(). Each template defined in the file is an <tt>ldap_disptmpl</tt> structure.  


=== ldap_free_urldesc()  ===
=== ldap_free_urldesc()  ===
Line 5,122: Line 4,552:
The ldap_free_urldesc() function frees memory allocated by the ldap_url_parse() function.  
The ldap_free_urldesc() function frees memory allocated by the ldap_url_parse() function.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
void ldap_free_urldesc( LDAPURLDesc *ludp );</pre>  
void ldap_free_urldesc( LDAPURLDesc *ludp );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_free_urldesc() Function Parameter"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_free_urldesc() Function Parameter"
Line 5,141: Line 4,569:
|}
|}


<br> '''Example'''


'''Example'''
<br> The following example parses an LDAP URL and then frees the LDAPURLDesc structure from memory after verifying that the LDAP URL is valid.  
 
 
The following example parses an LDAP URL and then frees the LDAPURLDesc structure from memory after verifying that the LDAP URL is valid.  
<pre>#include &lt;stdio.h&gt;
<pre>#include &lt;stdio.h&gt;
#include &lt;ldap.h&gt;
#include &lt;ldap.h&gt;
Line 5,177: Line 4,603:
ldap_free_urldesc( ludpp );
ldap_free_urldesc( ludpp );
...</pre>  
...</pre>  
'''See Also'''


'''See Also'''
<br> ldap_url_parse()  
 
 
ldap_url_parse()  


=== ldap_friendly_name()  ===
=== ldap_friendly_name()  ===
Line 5,187: Line 4,611:
The ldap_friendly_name() 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. '''Note:''' <tt>ldapfriendly</tt>, located in <tt>lib/ldapcsdk/etc</tt>, is a sample file that maps two letter country codes to their full names. It can be used in context with ldap_friendly_name().  
The ldap_friendly_name() 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. '''Note:''' <tt>ldapfriendly</tt>, located in <tt>lib/ldapcsdk/etc</tt>, is a sample file that maps two letter country codes to their full names. It can be used in context with ldap_friendly_name().  


 
<br> '''Syntax'''  
'''Syntax'''
<pre>#include &lt;ldap.h&gt;
 
<pre>#include &lt;ldap.h&gt;
char * ldap_friendly_name( char *filename, char *uname,
char * ldap_friendly_name( char *filename, char *uname,
   FriendlyMap *map );</pre>  
   FriendlyMap *map );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_friendly_name() function parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_friendly_name() function parameters"
Line 5,213: Line 4,635:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:
 


One of the following values:
*If successful, returns the user-friendly name for the specified identifier.  
*If successful, returns the user-friendly name for the specified identifier.  
*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 <tt>NULL</tt>‚Äö√Ñ√Æreturns the original identifier (the value passed as the <tt>uname</tt> parameter).  
*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 <tt>NULL</tt>—returns the original identifier (the value passed as the <tt>uname</tt> parameter).
 
 
'''Description'''


<br> '''Description'''


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. Unfriendly to Friendly Name Mapping File  
<br> 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. Unfriendly to Friendly Name Mapping File  
<pre>&lt;unfriendly_name&gt;        &lt;friendly_name&gt;
<pre>&lt;unfriendly_name&gt;        &lt;friendly_name&gt;
AD        Andorra
AD        Andorra
Line 5,232: Line 4,651:
AG        Antigua and Barbuda
AG        Antigua and Barbuda
AI        Anguilla</pre>  
AI        Anguilla</pre>  
'''Example'''


'''Example'''
<br> The following example reads in a map of user-friendly names and prints the name corresponding to the standard identifier <tt>IS</tt>.  
 
 
The following example reads in a map of user-friendly names and prints the name corresponding to the standard identifier <tt>IS</tt>.  
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
#include &lt;stdio.h&gt;
#include &lt;stdio.h&gt;
Line 5,252: Line 4,669:
printf( "Friendly Name for VI:&nbsp;%s\n", friendly_name );
printf( "Friendly Name for VI:&nbsp;%s\n", friendly_name );
...</pre>  
...</pre>  
'''See Also'''


'''See Also'''
<br> ldap_free_friendlymap(), FriendlyMap()  
 
 
ldap_free_friendlymap(), FriendlyMap()  


=== ldap_get_dn()  ===
=== ldap_get_dn()  ===
Line 5,262: Line 4,677:
The ldap_get_dn() routine returns the DN for an entry in a chain of search results.  
The ldap_get_dn() routine returns the DN for an entry in a chain of search results.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
char * ldap_get_dn( LDAP *ld, LDAPMessage *entry );</pre>  
char * ldap_get_dn( LDAP *ld, LDAPMessage *entry );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_get_dn() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_get_dn() Function Parameters"
Line 5,284: Line 4,697:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:  
 
 
One of the following values:  


*If successful, returns the DN for the specified entry.  
*If successful, returns the DN for the specified entry.  
*If unsuccessful, returns a <tt>NULL</tt> and sets the appropriate error code in the LDAP structure. To get the error code, call the ldap_get_lderrno() function.
*If unsuccessful, returns a <tt>NULL</tt> and sets the appropriate error code in the LDAP structure. To get the error code, call the ldap_get_lderrno() function.


<br> '''Description'''


'''Description'''
<br> You can get an entry from a chain of search results by calling the ldap_first_entry() and ldap_next_entry() functions.  
 
 
You can get an entry from a chain of search results by calling the ldap_first_entry() and ldap_next_entry() functions.  
 
 
'''Example'''


<br> '''Example'''


The following example prints the DN for each entry found in a search.  
<br> The following example prints the DN for each entry found in a search.  
<pre>#include &lt;stdio.h&gt;
<pre>#include &lt;stdio.h&gt;
#include &lt;ldap.h&gt;
#include &lt;ldap.h&gt;
Line 5,331: Line 4,738:
ldap_msgfree( result );
ldap_msgfree( result );
...</pre>  
...</pre>  
'''See Also'''


'''See Also'''
<br> ldap_first_entry(), ldap_next_entry(), ldap_get_lderrno()  
 
 
ldap_first_entry(), ldap_next_entry(), ldap_get_lderrno()


=== ldap_get_entry_controls()  ===
=== ldap_get_entry_controls()  ===
Line 5,341: Line 4,746:
The ldap_get_entry_controls() function gets the LDAP controls included with a directory entry in a set of search results.  
The ldap_get_entry_controls() function gets the LDAP controls included with a directory entry in a set of search results.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
int ldap_get_entry_controls( LDAP *ld, LDAPMessage *entry,
int ldap_get_entry_controls( LDAP *ld, LDAPMessage *entry,
   LDAPControl ***serverctrlsp );</pre>  
   LDAPControl ***serverctrlsp );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_get_entry_controls() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_get_entry_controls() Function Parameters"
Line 5,367: Line 4,770:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:
 


One of the following values:
*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
*LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded results from the server.  
*LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded results from the server.  
*LDAP_PARAM_ERROR if an invalid parameter was passed to the function.  
*LDAP_PARAM_ERROR if an invalid parameter was passed to the function.  
*LDAP_NO_MEMORY if memory cannot be allocated.  
*LDAP_NO_MEMORY if memory cannot be allocated.
 
 
'''Description'''


<br> '''Description'''


The ldap_get_entry_controls() 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 LDAPControl structures with each structure representing one LDAP control. Other controls are returned with results sent from the server. You can call ldap_parse_result() to retrieve those controls.  
<br> The ldap_get_entry_controls() 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 LDAPControl structures with each structure representing one LDAP control. Other controls are returned with results sent from the server. You can call ldap_parse_result() to retrieve those controls.  


=== ldap_getfilter_free()  ===
=== ldap_getfilter_free()  ===
Line 5,387: Line 4,787:
The ldap_getfilter_free() function frees the memory used by a filter set.  
The ldap_getfilter_free() function frees the memory used by a filter set.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
void ldap_getfilter_free( LDAPFiltDesc *lfdp );</pre>  
void ldap_getfilter_free( LDAPFiltDesc *lfdp );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_getfilter_free() Function Parameter"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_getfilter_free() Function Parameter"
Line 5,406: Line 4,804:
|}
|}


<br> '''Description'''


'''Description'''
<br> Once you call ldap_getfilter_free(), the LDAPFiltDesc structure is no longer valid and cannot be used again.  
 
 
Once you call ldap_getfilter_free(), the LDAPFiltDesc structure is no longer valid and cannot be used again.  
 
 
'''Example'''


<br> '''Example'''


The following example frees the LDAPFiltDesc structure from memory after all searches are completed.  
<br> The following example frees the LDAPFiltDesc structure from memory after all searches are completed.  
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
...
...
Line 5,430: Line 4,824:
ldap_getfilter_free( lfdp );
ldap_getfilter_free( lfdp );
...</pre>  
...</pre>  
'''See Also'''


'''See Also'''
<br> ldap_init_getfilter(), ldap_init_getfilter_buf()  
 
 
ldap_init_getfilter(), ldap_init_getfilter_buf()  


=== ldap_getfirstfilter()  ===
=== ldap_getfirstfilter()  ===
Line 5,440: Line 4,832:
The ldap_getfirstfilter() function retrieves the first filter that is appropriate for a given value.  
The ldap_getfirstfilter() function retrieves the first filter that is appropriate for a given value.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
LDAPFiltInfo * ldap_getfirstfilter( LDAPFiltDesc *lfdp,
LDAPFiltInfo * ldap_getfirstfilter( LDAPFiltDesc *lfdp,
   char *tagpat, char *value );</pre>  
   char *tagpat, char *value );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_getfirstfilter() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_getfirstfilter() Function Parameters"
Line 5,466: Line 4,856:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:  
 
 
One of the following values:  


*If successful, returns a pointer to an LDAPFiltInfo() structure.  
*If successful, returns a pointer to an LDAPFiltInfo() structure.  
Line 5,476: Line 4,864:
*If unsuccessful, returns a <tt>NULL</tt>.
*If unsuccessful, returns a <tt>NULL</tt>.


<br> '''Example'''


'''Example'''
<br> The following example is based on the <tt>getfilt</tt> command-line program example provided with the LDAP C SDK. The program prompts the user to enter search criteria and, based on the criteria entered, it retrieves filters that match the criteria.  
 
 
The following example is based on the <tt>getfilt</tt> command-line program example provided with the LDAP C SDK. The program prompts the user to enter search criteria and, based on the criteria entered, it retrieves filters that match the criteria.  
<pre>#include &lt;stdio.h&gt;
<pre>#include &lt;stdio.h&gt;
#include &lt;ldap.h&gt;
#include &lt;ldap.h&gt;
Line 5,542: Line 4,928:
ldap_getfilter_free( ldfp );
ldap_getfilter_free( ldfp );
...</pre>  
...</pre>  
'''See Also'''


'''See Also'''
<br> ldap_init_getfilter(), ldap_init_getfilter_buf(), ldap_getnextfilter()  
 
 
ldap_init_getfilter(), ldap_init_getfilter_buf(), ldap_getnextfilter()  


=== ldap_get_lang_values()  ===
=== ldap_get_lang_values()  ===
Line 5,552: Line 4,936:
char ** ldap_get_lang_values( LDAP *ld, LDAPMessage *entry,
char ** ldap_get_lang_values( LDAP *ld, LDAPMessage *entry,
   const char *target, char **type );</pre>  
   const char *target, char **type );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_get_lang_values() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_get_lang_values() Function Parameters"
Line 5,575: Line 4,959:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:
 


One of the following values:
*If successful, returns a <tt>NULL</tt> terminated array of the attribute‚Äö√Ñ√¥s values.  
*If successful, returns a <tt>NULL</tt> terminated array of the attribute‚Äö√Ñ√¥s values.  
*If unsuccessful or if no such attribute exists in the entry, returns a <tt>NULL</tt> and sets the appropriate error code in the LDAP structure. To get the error code, call the ldap_get_lderrno() function.
*If unsuccessful or if no such attribute exists in the entry, returns a <tt>NULL</tt> and sets the appropriate error code in the LDAP structure. To get the error code, call the ldap_get_lderrno() function.
 
 
'''Description'''
 
 
Unlike the ldap_get_values() function, if a language subtype is specified, this function first attempts to find and return values that match that subtype‚Äö√Ñ√Æfor example, <tt>cn;lang-en</tt>. If you want to retrieve binary data from an attribute, call the ldap_get_lang_values_len() function.  


<br> '''Description'''


'''See Also'''
<br> Unlike the ldap_get_values() function, if a language subtype is specified, this function first attempts to find and return values that match that subtype—for example, <tt>cn;lang-en</tt>. If you want to retrieve binary data from an attribute, call the ldap_get_lang_values_len() function.


<br> '''See Also'''


ldap_first_entry(), ldap_first_attribute(), ldap_get_lang_values_len() , ldap_get_values(), ldap_next_entry(), ldap_next_attribute()  
<br> ldap_first_entry(), ldap_first_attribute(), ldap_get_lang_values_len() , ldap_get_values(), ldap_next_entry(), ldap_next_attribute()  


=== ldap_get_lang_values_len()  ===
=== ldap_get_lang_values_len()  ===
Line 5,601: Line 4,980:
The ldap_get_lang_values_len() function returns a <tt>NULL</tt> terminated array of pointers to berval structures, each containing the length and pointer to a binary value of an attribute for a given entry.  
The ldap_get_lang_values_len() function returns a <tt>NULL</tt> terminated array of pointers to berval structures, each containing the length and pointer to a binary value of an attribute for a given entry.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap-deprecated.h&gt;
<pre>#include &lt;ldap-deprecated.h&gt;
struct berval ** ldap_get_lang_values_len( LDAP *ld,
struct berval ** ldap_get_lang_values_len( LDAP *ld,
   LDAPMessage *entry, const char *target, char **type );</pre>  
   LDAPMessage *entry, const char *target, char **type );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_get_lang_values_len() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_get_lang_values_len() Function Parameters"
Line 5,630: Line 5,007:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:


One of the following values:
*If successful, returns a <tt>NULL</tt> terminated array of pointers to berval structures, which, in turn, contain pointers to the attribute‚Äö√Ñ√¥s binary values.  
*If successful, returns a <tt>NULL</tt> terminated array of pointers to berval structures, which, in turn, contain pointers to the attribute‚Äö√Ñ√¥s binary values.  
*If unsuccessful or if no such attribute exists in the entry, returns a <tt>NULL</tt> and sets the appropriate error code in the LDAP structure. To get the error code, call the ldap_get_lderrno() function.
*If unsuccessful or if no such attribute exists in the entry, returns a <tt>NULL</tt> and sets the appropriate error code in the LDAP structure. To get the error code, call the ldap_get_lderrno() function.
 
 
'''Description'''
 
 
Use the ldap_get_lang_values() routine if the attribute values are string values.  


<br> '''Description'''


'''See Also'''
<br> Use the ldap_get_lang_values() routine if the attribute values are string values.


<br> '''See Also'''


ldap_first_attribute(), ldap_first_entry(), ldap_get_lang_values(), ldap_next_entry(), ldap_next_attribute()  
<br> ldap_first_attribute(), ldap_first_entry(), ldap_get_lang_values(), ldap_next_entry(), ldap_next_attribute()  


=== ldap_get_lderrno()  ===
=== ldap_get_lderrno()  ===
Line 5,654: Line 5,026:
The ldap_get_lderrno() function gets information about the last error that occurred for an LDAP operation.  
The ldap_get_lderrno() function gets information about the last error that occurred for an LDAP operation.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
int ldap_get_lderrno( LDAP *ld, char **m, char **s );</pre>  
int ldap_get_lderrno( LDAP *ld, char **m, char **s );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_get_lderrno() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_get_lderrno() Function Parameters"
Line 5,679: Line 5,049:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> The LDAP error code for the last operation.  
 
 
The LDAP error code for the last operation.  
 
 
'''Description'''
 
 
ldap_get_lderrno() 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 ldap_next_attribute().
 


'''Example'''
<br> '''Description'''  


<br> ldap_get_lderrno() 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 ldap_next_attribute().


The following example 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.
<br> '''Example'''


<br> The following example 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.
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
LDAP *ld;
LDAP *ld;
Line 5,709: Line 5,072:
}
}
...</pre>  
...</pre>  
If no organizational unit named <tt>People</tt> exists, the matched variable is set to <tt>dc=example,dc=com</tt> .  
If no organizational unit named <tt>People</tt> exists, the matched variable is set to <tt>dc=example,dc=com</tt> .  


<br> '''See Also'''


'''See Also'''
<br> ldap_err2string(), ldap_perror, ldap_result2error(), ldap_set_lderrno()  
 
 
ldap_err2string(), ldap_perror, ldap_result2error(), ldap_set_lderrno()  


=== ldap_getnextfilter()  ===
=== ldap_getnextfilter()  ===
Line 5,722: Line 5,082:
The ldap_getnextfilter() function retrieves the next filter that is appropriate for a given value.  
The ldap_getnextfilter() function retrieves the next filter that is appropriate for a given value.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
LDAPFiltInfo * ldap_getnextfilter( LDAPFiltDesc *lfdp );</pre>  
LDAPFiltInfo * ldap_getnextfilter( LDAPFiltDesc *lfdp );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_getnextfilter() Function Parameter"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_getnextfilter() Function Parameter"
Line 5,741: Line 5,099:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:  
 
 
One of the following values:  


*If successful, returns a pointer to an LDAPFiltInfo() structure.  
*If successful, returns a pointer to an LDAPFiltInfo() structure.  
Line 5,751: Line 5,107:
*If unsuccessful, returns a <tt>NULL</tt>.
*If unsuccessful, returns a <tt>NULL</tt>.


<br> '''Description'''


'''Description'''
<br> Call this function to get subsequent filters after calling ldap_getfirstfilter().  
 
 
Call this function to get subsequent filters after calling ldap_getfirstfilter().
 
 
'''Example'''
 
 
See the following example.  


<br> '''Example'''


'''See Also'''
<br> See the following example.


<br> '''See Also'''


ldap_getfirstfilter()  
<br> ldap_getfirstfilter()  


=== ldap_get_option()  ===
=== ldap_get_option()  ===
Line 5,773: Line 5,123:
The function ldap_get_option() retrieves session preferences from an LDAP structure.  
The function ldap_get_option() retrieves session preferences from an LDAP structure.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
int ldap_get_option( LDAP *ld, int option, void *optdata );</pre>  
int ldap_get_option( LDAP *ld, int option, void *optdata );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_get_option() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_get_option() Function Parameters"
Line 5,913: Line 5,261:
See also ldap_get_option() for details on <tt>LDAP_OPT_X_SASL*</tt> parameters.  
See also ldap_get_option() for details on <tt>LDAP_OPT_X_SASL*</tt> parameters.  


<br> '''Returns'''


'''Returns'''
<br> One of the following values:  
 
 
One of the following values:  


*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
*<tt>-1</tt> if unsuccessful.
*<tt>-1</tt> if unsuccessful.


<br> '''Examples'''


'''Examples'''
<br> The following example gets the session preference for the maximum number of entries to be returned from search operations.  
 
 
The following example gets the session preference for the maximum number of entries to be returned from search operations.  
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
...
...
Line 5,948: Line 5,292:
   /* use the ldai info here */
   /* use the ldai info here */
}</pre>  
}</pre>  
'''See Also'''


'''See Also'''
<br> ldap_init(), prldap_init() (IPv6), ldap_set_option()  
 
 
ldap_init(), prldap_init() (IPv6), ldap_set_option()


=== ldap_get_values()  ===
=== ldap_get_values()  ===
Line 5,958: Line 5,300:
The ldap_get_values() function returns a <tt>NULL</tt> terminated array of an attribute‚Äö√Ñ√¥s string values for a given entry.  
The ldap_get_values() function returns a <tt>NULL</tt> terminated array of an attribute‚Äö√Ñ√¥s string values for a given entry.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
char ** ldap_get_values( LDAP *ld, LDAPMessage *entry,
char ** ldap_get_values( LDAP *ld, LDAPMessage *entry,
   const char *target );</pre>  
   const char *target );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_get_values() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_get_values() Function Parameters"
Line 5,984: Line 5,324:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:
 


One of the following values:
*If successful, returns a <tt>NULL</tt> terminated array of the attribute‚Äö√Ñ√¥s values.  
*If successful, returns a <tt>NULL</tt> terminated array of the attribute‚Äö√Ñ√¥s values.  
*If unsuccessful or if no such attribute exists in the entry, returns a <tt>NULL</tt> and sets the appropriate error code in the LDAP structure. To get the error code, call the ldap_get_lderrno() function.
*If unsuccessful or if no such attribute exists in the entry, returns a <tt>NULL</tt> and sets the appropriate error code in the LDAP structure. To get the error code, call the ldap_get_lderrno() function.
 
 
'''Description'''
 
 
Use the ldap_get_values_len() function if the attribute values are binary.  


<br> '''Description'''


'''Example'''
<br> Use the ldap_get_values_len() function if the attribute values are binary.


<br> '''Example'''


The following example gets and prints the values of an attribute in an entry. This example assumes that all attributes have string values.  
<br> The following example gets and prints the values of an attribute in an entry. This example assumes that all attributes have string values.  
<pre>#include &lt;stdio.h&gt;
<pre>#include &lt;stdio.h&gt;
#include &lt;ldap.h&gt;
#include &lt;ldap.h&gt;
Line 6,035: Line 5,370:
}
}
...</pre>  
...</pre>  
'''See Also'''


'''See Also'''
<br> ldap_first_entry(), ldap_first_attribute(), ldap_get_values_len(), ldap_next_entry(), ldap_next_attribute()  
 
 
ldap_first_entry(), ldap_first_attribute(), ldap_get_values_len(), ldap_next_entry(), ldap_next_attribute()  


=== ldap_get_values_len()  ===
=== ldap_get_values_len()  ===
Line 6,045: Line 5,378:
The ldap_get_values_len() function returns a <tt>NULL</tt> terminated array of pointers to berval structures, each containing the length and pointer to a binary value of an attribute for a given entry.  
The ldap_get_values_len() function returns a <tt>NULL</tt> terminated array of pointers to berval structures, each containing the length and pointer to a binary value of an attribute for a given entry.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
struct berval ** ldap_get_values_len( LDAP *ld,
struct berval ** ldap_get_values_len( LDAP *ld,
  LDAPMessage *entry, const char *target );</pre>  
  LDAPMessage *entry, const char *target );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_get_values_len() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_get_values_len() Function Parameters"
Line 6,071: Line 5,402:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:
 


One of the following values:
*If successful, returns a <tt>NULL</tt> terminated array of pointers to berval structures, which in turn contains pointers to the attribute‚Äö√Ñ√¥s binary values.  
*If successful, returns a <tt>NULL</tt> terminated array of pointers to berval structures, which in turn contains pointers to the attribute‚Äö√Ñ√¥s binary values.  
*If unsuccessful or if no such attribute exists in the entry, returns <tt>NULL</tt> and sets the appropriate error code in the LDAP structure. To get the error code, call the ldap_get_lderrno() function.
*If unsuccessful or if no such attribute exists in the entry, returns <tt>NULL</tt> and sets the appropriate error code in the LDAP structure. To get the error code, call the ldap_get_lderrno() function.
 
 
'''Description'''
 
 
Use the ldap_get_values() routine if the attribute values are string values.  


<br> '''Description'''


'''Example'''
<br> Use the ldap_get_values() routine if the attribute values are string values.


<br> '''Example'''


The following example gets the first value of the <tt>jpegPhoto</tt> attribute and saves the JPEG data to a file.  
<br> The following example gets the first value of the <tt>jpegPhoto</tt> attribute and saves the JPEG data to a file.  
<pre>#include &lt;stdio.h&gt;
<pre>#include &lt;stdio.h&gt;
#include &lt;ldap.h&gt;
#include &lt;ldap.h&gt;
Line 6,127: Line 5,453:
}
}
...</pre>  
...</pre>  
'''See Also'''


'''See Also'''
<br> ldap_first_entry(), ldap_first_attribute(), ldap_get_values(), ldap_next_entry(), ldap_next_attribute()  
 
 
ldap_first_entry(), ldap_first_attribute(), ldap_get_values(), ldap_next_entry(), ldap_next_attribute()  


=== ldap_init()  ===
=== ldap_init()  ===
Line 6,137: Line 5,461:
The ldap_init() function initializes a session with an LDAP server and returns an LDAP structure that represents the context of the connection to that server.  
The ldap_init() function initializes a session with an LDAP server and returns an LDAP structure that represents the context of the connection to that server.  


 
<br> '''Syntax'''  
'''Syntax'''
<pre>#include &lt;ldap.h&gt;
 
<pre>#include &lt;ldap.h&gt;
LDAP * ldap_init( const char *defhost, int defport );</pre>  
LDAP * ldap_init( const char *defhost, int defport );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_init() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_init() Function Parameters"
Line 6,159: Line 5,481:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:
 


One of the following values:
*If successful, returns a pointer to an LDAP() structure.  
*If successful, returns a pointer to an LDAP() structure.  
*If unsuccessful, returns a <tt>NULL</tt>.
*If unsuccessful, returns a <tt>NULL</tt>.


<br> '''Description'''


'''Description'''
<br> The ldap_init() function initializes a session with an LDAP server by allocating an LDAP 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 LDAP structure defaults to LDAP v2. It is highly recommended to set it to LDAP v3 using the ldap_set_option().  
 
 
The ldap_init() function initializes a session with an LDAP server by allocating an LDAP 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 LDAP structure defaults to LDAP v2. It is highly recommended to set it to LDAP v3 using the ldap_set_option().  
<pre>...
<pre>...
LDAP *ld
LDAP *ld
Line 6,184: Line 5,503:
'''Note:''' If you are connecting to a secure LDAP server over SSL, you should be calling the ldapssl_init() function.  
'''Note:''' If you are connecting to a secure LDAP server over SSL, you should be calling the ldapssl_init() function.  


<br> '''Example'''


'''Example'''
<br> The following example initializes a session with the LDAP server at <tt>ldap.example.com:389</tt>, and sets a session preference that identifies the client as an LDAP v3 client.  
 
 
The following example initializes a session with the LDAP server at <tt>ldap.example.com:389</tt>, and sets a session preference that identifies the client as an LDAP v3 client.  
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
...
...
Line 6,210: Line 5,527:
/* Subsequent calls that authenticate to the LDAP server. */
/* Subsequent calls that authenticate to the LDAP server. */
...</pre>  
...</pre>  
'''See Also'''


'''See Also'''
<br> prldap_init() (IPv6), ldap_unbind(), ldap_unbind_s() , ldap_simple_bind(), ldap_simple_bind_s()  
 
 
prldap_init() (IPv6), ldap_unbind(), ldap_unbind_s() , ldap_simple_bind(), ldap_simple_bind_s()  


=== ldap_init_getfilter()  ===
=== ldap_init_getfilter()  ===
Line 6,221: Line 5,536:
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
LDAPFiltDesc * ldap_init_getfilter( char *fname );</pre>  
LDAPFiltDesc * ldap_init_getfilter( char *fname );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_init_getfilter() Function Parameter"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_init_getfilter() Function Parameter"
Line 6,235: Line 5,550:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:  
 
 
One of the following values:  


*If successful, returns a pointer to an LDAPFiltDesc() structure.  
*If successful, returns a pointer to an LDAPFiltDesc() structure.  
Line 6,246: Line 5,559:
the file), returns a <tt>NULL</tt>.  
the file), returns a <tt>NULL</tt>.  


<br> '''Example'''


'''Example'''
<br> The following example loads a filter configuration file named <tt>myfilters.conf</tt> into memory.  
 
 
The following example loads a filter configuration file named <tt>myfilters.conf</tt> into memory.  
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
...
...
Line 6,258: Line 5,569:
lfdp = ldap_init_getfilter( filter_file );
lfdp = ldap_init_getfilter( filter_file );
...</pre>  
...</pre>  
'''See Also'''


'''See Also'''
<br> ldap_init_getfilter_buf(), ldap_getfilter_free()  
 
 
ldap_init_getfilter_buf(), ldap_getfilter_free()  


=== ldap_init_getfilter_buf()  ===
=== ldap_init_getfilter_buf()  ===
Line 6,268: Line 5,577:
The ldap_init_getfilter_buf() function reads LDAP filter configuration information from a buffer and returns a pointer to an LDAPFiltDesc structure.  
The ldap_init_getfilter_buf() function reads LDAP filter configuration information from a buffer and returns a pointer to an LDAPFiltDesc structure.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
LDAPFiltDesc * ldap_init_getfilter_buf(char *buf, long buflen );</pre>  
LDAPFiltDesc * ldap_init_getfilter_buf(char *buf, long buflen );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_init_getfilter_buf() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_init_getfilter_buf() Function Parameters"
Line 6,290: Line 5,597:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:
 


One of the following values:
*If successful, returns a pointer to an LDAPFiltDesc() structure.  
*If successful, returns a pointer to an LDAPFiltDesc() structure.  
*If unsuccessful‚Äö√Ñ√Æfor example, if there is an error reading the file‚Äö√Ñ√Æreturns a <tt>NULL</tt>.  
*If unsuccessful—for example, if there is an error reading the file—returns a <tt>NULL</tt>.
 
 
'''Example'''


<br> '''Example'''


The following example copies the following filter configuration to a buffer in memory and uses this buffer to fill an LDAPFiltDesc structure.  
<br> The following example copies the following filter configuration to a buffer in memory and uses this buffer to fill an LDAPFiltDesc structure.  
<pre>"ldap-example"
<pre>"ldap-example"
"@"      " "    "(mail=%v)"            "email address"
"@"      " "    "(mail=%v)"            "email address"
Line 6,319: Line 5,623:
lfdp = ldap_init_getfilter( filtbuf, strlen( filtbuf ) );
lfdp = ldap_init_getfilter( filtbuf, strlen( filtbuf ) );
...</pre>  
...</pre>  
'''See Also'''


'''See Also'''
<br> ldap_init_getfilter(), ldap_getfilter_free()  
 
 
ldap_init_getfilter(), ldap_getfilter_free()  


=== ldap_init_searchprefs()  ===
=== ldap_init_searchprefs()  ===
Line 6,329: Line 5,631:
The ldap_init_searchprefs() function reads a sequence of search preference configurations from a valid LDAP <tt>searchpref</tt> configuration file.  
The ldap_init_searchprefs() function reads a sequence of search preference configurations from a valid LDAP <tt>searchpref</tt> configuration file.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
int ldap_init_searchprefs( char *file, struct ldap_searchobj **solistp );</pre>  
int ldap_init_searchprefs( char *file, struct ldap_searchobj **solistp );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_init_searchprefs() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_init_searchprefs() Function Parameters"
Line 6,351: Line 5,651:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:
 


One of the following values:
*<tt>LDAP_SEARCHPREF_ERR_VERSION</tt>.  
*<tt>LDAP_SEARCHPREF_ERR_VERSION</tt>.  
*<tt>LDAP_SEARCHPREF_ERR_MEM</tt> if there is a memory allocation problem.  
*<tt>LDAP_SEARCHPREF_ERR_MEM</tt> if there is a memory allocation problem.  
*Upon success, <tt>0</tt> is returned and <tt>solistp</tt> is set to point to a list of search preference data structures.
*Upon success, <tt>0</tt> is returned and <tt>solistp</tt> is set to point to a list of search preference data structures.


<br> '''Description'''


'''Description'''
<br> ldap_init_searchprefs() provides a standard way to access LDAP search preference configuration data.  
 
 
ldap_init_searchprefs() provides a standard way to access LDAP search preference configuration data.  


'''Note:''' 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.  
'''Note:''' 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.  


<br> '''See Also'''


'''See Also'''
<br> ldap_free_searchprefs(), ldap_init_searchprefs_buf()  
 
 
ldap_free_searchprefs(), ldap_init_searchprefs_buf()  


=== ldap_init_searchprefs_buf()  ===
=== ldap_init_searchprefs_buf()  ===
Line 6,378: Line 5,673:
The ldap_init_searchprefs_buf() function reads a sequence of search preference configurations from the parameter, <tt>buf</tt>.  
The ldap_init_searchprefs_buf() function reads a sequence of search preference configurations from the parameter, <tt>buf</tt>.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
int ldap_init_searchprefs_buf( char *buf, long buflen,
int ldap_init_searchprefs_buf( char *buf, long buflen,
   struct ldap_searchobj **solistp );</pre>  
   struct ldap_searchobj **solistp );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_init_searchprefs_buf() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_init_searchprefs_buf() Function Parameters"
Line 6,404: Line 5,697:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:
 


One of the following values:
*<tt>LDAP_SEARCHPREF_ERR_VERSION</tt> if <tt>buf</tt> points to data that is newer than can be handled.  
*<tt>LDAP_SEARCHPREF_ERR_VERSION</tt> if <tt>buf</tt> points to data that is newer than can be handled.  
*<tt>LDAP_SEARCHPREF_ERR_MEM</tt> if there is a memory allocation problem.  
*<tt>LDAP_SEARCHPREF_ERR_MEM</tt> if there is a memory allocation problem.  
*Upon success, <tt>0</tt> is returned and <tt>solistp</tt> is set to point to a list of search preference data structures.
*Upon success, <tt>0</tt> is returned and <tt>solistp</tt> is set to point to a list of search preference data structures.


<br> '''Description'''


'''Description'''
<br> ldap_init_searchprefs_buf() reads a sequence of search preference configurations from <tt>buf</tt>. See also ldap_init_searchprefs(), ldap_free_searchprefs()  
 
 
ldap_init_searchprefs_buf() reads a sequence of search preference configurations from <tt>buf</tt>. See also ldap_init_searchprefs(), ldap_free_searchprefs()  


=== ldap_init_templates()  ===
=== ldap_init_templates()  ===
Line 6,423: Line 5,713:
The ldap_init_templates() function reads a sequence of templates from a valid LDAP template configuration file.  
The ldap_init_templates() function reads a sequence of templates from a valid LDAP template configuration file.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;disptmpl.h&gt;
<pre>#include &lt;disptmpl.h&gt;
int ldap_init_templates( char *file, struct ldap_disptmpl **tmpllistp );</pre>  
int ldap_init_templates( char *file, struct ldap_disptmpl **tmpllistp );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_init_templates() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_init_templates() Function Parameters"
Line 6,445: Line 5,733:
|}
|}


<br> '''Returns'''


'''Returns'''
<br>
 


*If successful, <tt>0</tt> is returned and <tt>tmpllistp</tt> is configured.  
*If successful, <tt>0</tt> is returned and <tt>tmpllistp</tt> is configured.  
Line 6,454: Line 5,742:
**<tt>LDAP_TMPL_ERR_MEM</tt> if there is a memory allocation problem.  
**<tt>LDAP_TMPL_ERR_MEM</tt> if there is a memory allocation problem.  
**<tt>LDAP_TMPL_ERR_SYNTAX</tt> if there is a problem with the format of the templates buffer or file.  
**<tt>LDAP_TMPL_ERR_SYNTAX</tt> if there is a problem with the format of the templates buffer or file.  
**<tt>LDAP_TMPL_ERR_FILE</tt> if the file cannot be read.
**<tt>LDAP_TMPL_ERR_FILE</tt> if the file cannot be read.
 
 
'''Description'''
 
 
ldap_init_templates() reads a sequence of templates from a valid LDAP template configuration file. Each template defined in the file is an <tt>ldap_disptmpl</tt> structure.  


<br> '''Description'''


'''See Also'''
<br> ldap_init_templates() reads a sequence of templates from a valid LDAP template configuration file. Each template defined in the file is an <tt>ldap_disptmpl</tt> structure.


<br> '''See Also'''


ldap_init_templates_buf(), ldap_free_templates()  
<br> ldap_init_templates_buf(), ldap_free_templates()  


=== ldap_init_templates_buf()  ===
=== ldap_init_templates_buf()  ===
Line 6,472: Line 5,756:
The ldap_init_templates_buf() function reads a sequence of templates from a buffer.  
The ldap_init_templates_buf() function reads a sequence of templates from a buffer.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;disptmpl.h&gt;
<pre>#include &lt;disptmpl.h&gt;
int ldap_init_templates_buf( char *buf, long buflen,
int ldap_init_templates_buf( char *buf, long buflen,
   struct ldap_disptmpl **tmpllistp );</pre>  
   struct ldap_disptmpl **tmpllistp );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_init_templates_buf() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_init_templates_buf() Function Parameters"
Line 6,498: Line 5,780:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> If successful, <tt>0</tt> is returned and <tt>tmpllistp</tt> is configured. Upon error:
 


If successful, <tt>0</tt> is returned and <tt>tmpllistp</tt> is configured. Upon error:
*<tt>LDAP_TMPL_ERR_VERSION</tt> if <tt>buf</tt> points to data that is newer than can be handled.  
*<tt>LDAP_TMPL_ERR_VERSION</tt> if <tt>buf</tt> points to data that is newer than can be handled.  
*<tt>LDAP_TMPL_ERR_MEM</tt> if there is a memory allocation problem.  
*<tt>LDAP_TMPL_ERR_MEM</tt> if there is a memory allocation problem.  
*<tt>LDAP_TMPL_ERR_SYNTAX</tt> if there is a problem with the format of the templates buffer or file.  
*<tt>LDAP_TMPL_ERR_SYNTAX</tt> if there is a problem with the format of the templates buffer or file.  
*<tt>LDAP_TMPL_ERR_FILE</tt> if the file cannot be read.  
*<tt>LDAP_TMPL_ERR_FILE</tt> if the file cannot be read.


<br> '''Description'''


'''Description'''
<br> The ldap_init_templates_buf() function reads a sequence of templates from a buffer.


<br> '''See Also'''


The ldap_init_templates_buf() function reads a sequence of templates from a buffer.
<br> ldap_init_templates(), ldap_free_templates()  


=== ldap_is_dns_dn()  ===


'''See Also'''
'''Note:''' This function is deprecated and should not be used. It is included in <tt>ldap-to-be-deprecated.h</tt> for backward-compatibility.


The ldap_is_dns_dn() 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.


ldap_init_templates(), ldap_free_templates()
<br> '''Description'''


=== ldap_is_dns_dn()  ===
<br> This function is specific to LDAP v2 and should not be used when dealing with LDAP v3 servers or data.  
 
'''Note:''' This function is deprecated and should not be used. It is included in <tt>ldap-to-be-deprecated.h</tt> for backward-compatibility.
 
The ldap_is_dns_dn() 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.
 
 
'''Description'''
 
 
This function is specific to LDAP v2 and should not be used when dealing with LDAP v3 servers or data.  


The ldap_is_ldap_url() function determines whether or not a URL is an LDAP URL.  
The ldap_is_ldap_url() function determines whether or not a URL is an LDAP URL.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
int ldap_is_ldap_url( const char *url );</pre>  
int ldap_is_ldap_url( const char *url );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_is_ldap_url() Function Parameter"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_is_ldap_url() Function Parameter"
Line 6,553: Line 5,826:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:  
 
 
One of the following values:  


*<tt>1</tt> if the URL is an LDAP URL.  
*<tt>1</tt> if the URL is an LDAP URL.  
*<tt>0</tt> if the URL is not an LDAP URL.
*<tt>0</tt> if the URL is not an LDAP URL.


<br> '''Description'''


'''Description'''
<br> The ldap_is_ldap_url() function determines whether or not a URL is an LDAP URL. An LDAP URL is a URL with the protocol set to <tt>ldap://</tt> (or <tt>ldaps://</tt>, if the server is communicating over a SSL connection).  
 
 
The ldap_is_ldap_url() function determines whether or not a URL is an LDAP URL. An LDAP URL is a URL with the protocol set to <tt>ldap://</tt> (or <tt>ldaps://</tt>, if the server is communicating over a SSL connection).  
 
 
'''Example'''


<br> '''Example'''


The following example determines if a URL is a LDAP URL.  
<br> The following example determines if a URL is a LDAP URL.  
<pre>#include &lt;stdio.h&gt;
<pre>#include &lt;stdio.h&gt;
#include &lt;ldap.h&gt;
#include &lt;ldap.h&gt;
Line 6,584: Line 5,851:
}
}
...</pre>  
...</pre>  
'''See Also'''


'''See Also'''
<br> ldap_url_parse()  
 
 
ldap_url_parse()  


=== ldap_keysort_entries()  ===
=== ldap_keysort_entries()  ===
Line 6,594: Line 5,859:
The ldap_keysort_entries() function is used for sorting entries.  
The ldap_keysort_entries() function is used for sorting entries.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap-extension.h&gt;
<pre>#include &lt;ldap-extension.h&gt;
int ldap_keysort_entries( LDAP *ld, LDAPMessage **chain,
int ldap_keysort_entries( LDAP *ld, LDAPMessage **chain,
   void *arg, LDAP_KEYGEN_CALLBACK *gen, LDAP_KEYCMP_CALLBACK *cmp,
   void *arg, LDAP_KEYGEN_CALLBACK *gen, LDAP_KEYCMP_CALLBACK *cmp,
   LDAP_KEYFREE_CALLBACK *fre );</pre>  
   LDAP_KEYFREE_CALLBACK *fre );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_keysort_entries() Function Parameter"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_keysort_entries() Function Parameter"
Line 6,630: Line 5,893:
|}
|}


<br> '''See Also'''


'''See Also'''
<br> LDAP_KEYGEN_CALLBACK(), LDAP_KEYCMP_CALLBACK(), LDAP_KEYFREE_CALLBACK()  
 
 
LDAP_KEYGEN_CALLBACK(), LDAP_KEYCMP_CALLBACK(), LDAP_KEYFREE_CALLBACK()  


=== ldap_memcache_destroy()  ===
=== ldap_memcache_destroy()  ===
Line 6,640: Line 5,901:
The ldap_memcache_destroy() function frees an LDAPMemCache structure from memory.  
The ldap_memcache_destroy() function frees an LDAPMemCache structure from memory.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
void ldap_memcache_destroy( LDAPMemCache *cache );</pre>  
void ldap_memcache_destroy( LDAPMemCache *cache );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_memcache_destroy() Function Parameter"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_memcache_destroy() Function Parameter"
Line 6,659: Line 5,918:
|}
|}


<br> '''Description'''


'''Description'''
<br> The ldap_memcache_destroy() function frees the specified LDAPMemCache structure from memory. Call this function after you are done working with a cache.  
 
 
The ldap_memcache_destroy() function frees the specified LDAPMemCache structure from memory. Call this function after you are done working with a cache.  
 
 
'''See Also'''


<br> '''See Also'''


ldap_memcache_init()  
<br> ldap_memcache_init()  


=== ldap_memcache_flush()  ===
=== ldap_memcache_flush()  ===
Line 6,675: Line 5,930:
The ldap_memcache_flush() function flushes items from the specified cache.  
The ldap_memcache_flush() function flushes items from the specified cache.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
void ldap_memcache_flush( LDAPMemCache *cache, char *dn,
void ldap_memcache_flush( LDAPMemCache *cache, char *dn,
   int scope );</pre>  
   int scope );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_memcache_flush() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_memcache_flush() Function Parameters"
Line 6,701: Line 5,954:
|}
|}


<br> '''Description'''


'''Description'''
<br> The ldap_memcache_flush() function flushes search requests from the cache. If the base DN of a search request is within the scope specified by the <tt>dn</tt> and scope arguments, the search request is flushed from the cache. If no DN is specified, the entire cache is flushed.  
 
 
The ldap_memcache_flush() function flushes search requests from the cache. If the base DN of a search request is within the scope specified by the <tt>dn</tt> and scope arguments, the search request is flushed from the cache. If no DN is specified, the entire cache is flushed.  


=== ldap_memcache_get()  ===
=== ldap_memcache_get()  ===
Line 6,711: Line 5,962:
The ldap_memcache_get() function gets the in-memory cache associated with an LDAP connection handle.  
The ldap_memcache_get() function gets the in-memory cache associated with an LDAP connection handle.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
int ldap_memcache_get( LDAP *ld, LDAPMemCache **cachep );</pre>  
int ldap_memcache_get( LDAP *ld, LDAPMemCache **cachep );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_memcache_get() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_memcache_get() Function Parameters"
Line 6,733: Line 5,982:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:
 


One of the following values:
*LDAP_SUCCESS if the cache for the specified connection handle was retrieved successfully.  
*LDAP_SUCCESS if the cache for the specified connection handle was retrieved successfully.  
*LDAP_PARAM_ERROR if an invalid parameter was passed to the function.
*LDAP_PARAM_ERROR if an invalid parameter was passed to the function.
 
 
'''Description'''
 
 
The ldap_memcache_get() function gets the cache associated with the specified connection handle (LDAP 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 ldap_memcache_set() function to associate the cache with another connection.  


<br> '''Description'''


'''See Also'''
<br> The ldap_memcache_get() function gets the cache associated with the specified connection handle (LDAP 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 ldap_memcache_set() function to associate the cache with another connection.


<br> '''See Also'''


ldap_memcache_set()  
<br> ldap_memcache_set()  


=== ldap_memcache_init()  ===
=== ldap_memcache_init()  ===
Line 6,757: Line 6,001:
The ldap_memcache_init() function creates an in-memory cache for your LDAP client that you can associate with an LDAP connection.  
The ldap_memcache_init() function creates an in-memory cache for your LDAP client that you can associate with an LDAP connection.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
int ldap_memcache_init( unsigned long ttl, unsigned long size,
int ldap_memcache_init( unsigned long ttl, unsigned long size,
   char **baseDNs, struct ldap_thread_fns *thread_fns,
   char **baseDNs, struct ldap_thread_fns *thread_fns,
   LDAPMemCache **cachep );</pre>  
   LDAPMemCache **cachep );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_memcache_init() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_memcache_init() Function Parameters"
Line 6,790: Line 6,032:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:
 


One of the following values:
*LDAP_SUCCESS if the cache for the specified connection handle was retrieved successfully.  
*LDAP_SUCCESS if the cache for the specified connection handle was retrieved successfully.  
*LDAP_PARAM_ERROR if an invalid parameter was passed to the function.  
*LDAP_PARAM_ERROR if an invalid parameter was passed to the function.  
*LDAP_NO_MEMORY if memory cannot be allocated.  
*LDAP_NO_MEMORY if memory cannot be allocated.  
*LDAP_SIZELIMIT_EXCEEDED if the initial size of the cache (specified by the size argument) is too small.  
*LDAP_SIZELIMIT_EXCEEDED if the initial size of the cache (specified by the size argument) is too small.
 
 
'''Description'''


<br> '''Description'''


The ldap_memcache_init() function creates an in-memory, client-side cache that you can use to cache search requests. The function passes back a pointer to an LDAPMemCache structure, which represents the cache. You should call the ldap_memcache_set() function to associate this cache with an LDAP connection handle (an LDAP structure). 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 ldap_memcache_flush() function. When you are done with the cache, you can free it from memory by calling the ldap_memcache_destroy() function.  
<br> The ldap_memcache_init() function creates an in-memory, client-side cache that you can use to cache search requests. The function passes back a pointer to an LDAPMemCache structure, which represents the cache. You should call the ldap_memcache_set() function to associate this cache with an LDAP connection handle (an LDAP structure). 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 ldap_memcache_flush() function. When you are done with the cache, you can free it from memory by calling the ldap_memcache_destroy() function.  


'''Note:''' On Windows systems, if the ldap_memcache_init() function returns an LDAP_PARAM_ERROR result code, verify that your client is using the version of the <tt>nsldap32v30.dll</tt> file provided with the LDAP C SDK.  
'''Note:''' On Windows systems, if the ldap_memcache_init() function returns an LDAP_PARAM_ERROR result code, verify that your client is using the version of the <tt>nsldap32v30.dll</tt> file provided with the LDAP C SDK.  


<br> '''See Also'''


'''See Also'''
<br> LDAPMemCache(), ldap_memcache_set() , ldap_memcache_flush(), ldap_memcache_destroy(), ldap_memcache_update()  
 
 
LDAPMemCache(), ldap_memcache_set() , ldap_memcache_flush(), ldap_memcache_destroy(), ldap_memcache_update()  


=== ldap_memcache_set()  ===
=== ldap_memcache_set()  ===
Line 6,818: Line 6,055:
The ldap_memcache_set() function associates an in-memory cache with an LDAP connection handle.  
The ldap_memcache_set() function associates an in-memory cache with an LDAP connection handle.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
int ldap_memcache_set( LDAP *ld, LDAPMemCache *cache );</pre>  
int ldap_memcache_set( LDAP *ld, LDAPMemCache *cache );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_memcache_set() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_memcache_set() Function Parameters"
Line 6,840: Line 6,075:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:
 


One of the following values:
*LDAP_SUCCESS if the cache for the specified connection handle was retrieved successfully.  
*LDAP_SUCCESS if the cache for the specified connection handle was retrieved successfully.  
*LDAP_PARAM_ERROR if an invalid parameter was passed to the function.  
*LDAP_PARAM_ERROR if an invalid parameter was passed to the function.  
*LDAP_SIZELIMIT_EXCEEDED if the initial size of the cache (specified by the size argument) is too small.
*LDAP_SIZELIMIT_EXCEEDED if the initial size of the cache (specified by the size argument) is too small.
 
 
'''Description'''
 
 
The ldap_memcache_set() function associates a cache (created by calling ldap_memcache_init()) 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 ldap_memcache_get() function to get the cache associated with one connection, then you can call ldap_memcache_set() to associate the cache with another connection. After you call this function, search requests made over the specified LDAP connection will use this cache. Calling the ldap_unbind() function will disassociate the cache from the LDAP connection handle.  


<br> '''Description'''


'''See Also'''
<br> The ldap_memcache_set() function associates a cache (created by calling ldap_memcache_init()) 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 ldap_memcache_get() function to get the cache associated with one connection, then you can call ldap_memcache_set() to associate the cache with another connection. After you call this function, search requests made over the specified LDAP connection will use this cache. Calling the ldap_unbind() function will disassociate the cache from the LDAP connection handle.


<br> '''See Also'''


ldap_memcache_init(), ldap_memcache_get()  
<br> ldap_memcache_init(), ldap_memcache_get()  


=== ldap_memcache_update()  ===
=== ldap_memcache_update()  ===
Line 6,865: Line 6,095:
The ldap_memcache_update() function checks the cache for items that have expired and removes them.  
The ldap_memcache_update() function checks the cache for items that have expired and removes them.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
void ldap_memcache_update( LDAPMemCache *cache );</pre>  
void ldap_memcache_update( LDAPMemCache *cache );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_memcache_update() Function Parameter"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_memcache_update() Function Parameter"
Line 6,884: Line 6,112:
|}
|}


<br> '''Description'''


'''Description'''
<br> The ldap_memcache_update() 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.  
 
 
The ldap_memcache_update() 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.  


'''Note:''' This function is only useful in a multithreaded application, since it will not return until the cache is destroyed.  
'''Note:''' This function is only useful in a multithreaded application, since it will not return until the cache is destroyed.  


<br> '''See Also'''


'''See Also'''
<br> ldap_memcache_flush()  
 
 
ldap_memcache_flush()  


=== ldap_memfree()  ===
=== ldap_memfree()  ===
Line 6,902: Line 6,126:
The ldap_memfree() function frees memory allocated by an LDAP API function call.  
The ldap_memfree() function frees memory allocated by an LDAP API function call.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
void ldap_memfree( void *p );</pre>  
void ldap_memfree( void *p );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_memfree() Function Parameter"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_memfree() Function Parameter"
Line 6,921: Line 6,143:
|}
|}


<br> '''Example'''


'''Example'''
<br> the following example frees the memory allocated by the ldap_get_dn() function. Using ldap_memfree()  
 
 
the following example frees the memory allocated by the ldap_get_dn() function. Using ldap_memfree()  
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
...
...
Line 6,938: Line 6,158:
ldap_memfree( dn );
ldap_memfree( dn );
...</pre>  
...</pre>  
'''See Also'''


'''See Also'''
<br> ldap_free_friendlymap(), ldap_free_urldesc(), ldap_msgfree(), ldap_value_free(), ldap_value_free_len()  
 
 
ldap_free_friendlymap(), ldap_free_urldesc(), ldap_msgfree(), ldap_value_free(), ldap_value_free_len()  


=== ldap_modify()  ===
=== ldap_modify()  ===
Line 6,949: Line 6,167:
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
int ldap_modify( LDAP *ld, const char *dn, LDAPMod **mods );</pre>  
int ldap_modify( LDAP *ld, const char *dn, LDAPMod **mods );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_modify() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_modify() Function Parameters"
Line 6,969: Line 6,187:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> Returns the message ID of the ldap_modify() operation. To check the result of this operation, call ldap_result() and ldap_result2error(). For a list of possible result codes for an LDAP modify operation, see ldap_modify_ext_s().  
 
 
Returns the message ID of the ldap_modify() operation. To check the result of this operation, call ldap_result() and ldap_result2error(). For a list of possible result codes for an LDAP modify operation, see ldap_modify_ext_s().
 
 
'''Description'''
 
 
Please use the newer version of this function, ldap_modify_ext() .  


<br> '''Description'''


'''Example'''
<br> Please use the newer version of this function, ldap_modify_ext() .


<br> '''Example'''


The following example uses the asynchronous ldap_modify() function to modify the entry for ''Barbara Jensen'' in the directory. It makes the following changes to the entry:  
<br> The following example uses the asynchronous ldap_modify() function to modify the entry for ''Barbara Jensen'' in the directory. It makes the following changes to the entry:  


*Adds the <tt>homePhone</tt> attribute.  
*Adds the <tt>homePhone</tt> attribute.  
Line 7,039: Line 6,251:
ldap_perror( ld, "ldap_modify" );
ldap_perror( ld, "ldap_modify" );
...</pre>  
...</pre>  
'''See Also'''


'''See Also'''
<br> ldap_modify_ext()  
 
 
ldap_modify_ext()  


=== ldap_modify_ext()  ===
=== ldap_modify_ext()  ===
Line 7,049: Line 6,259:
The ldap_modify_ext() function modifies an existing entry in the directory asynchronously. '''Note:''' ldap_modify_ext() is a new version of the ldap_modify() function. If you are writing a new LDAP client, use ldap_modify_ext().  
The ldap_modify_ext() function modifies an existing entry in the directory asynchronously. '''Note:''' ldap_modify_ext() is a new version of the ldap_modify() function. If you are writing a new LDAP client, use ldap_modify_ext().  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
int ldap_modify_ext( LDAP *ld, const char *dn, LDAPMod **mods,
int ldap_modify_ext( LDAP *ld, const char *dn, LDAPMod **mods,
   LDAPControl **serverctrls, LDAPControl **clientctrls,
   LDAPControl **serverctrls, LDAPControl **clientctrls,
   int *msgidp );</pre>  
   int *msgidp );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_modify_ext() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_modify_ext() Function Parameters"
Line 7,085: Line 6,293:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:
 


One of the following values:
*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
*LDAP_PARAM_ERROR if an invalid parameter was passed to the function.  
*LDAP_PARAM_ERROR if an invalid parameter was passed to the function.  
Line 7,095: Line 6,302:
*LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.  
*LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.  
*LDAP_NO_MEMORY if memory cannot be allocated.  
*LDAP_NO_MEMORY if memory cannot be allocated.  
*LDAP_NOT_SUPPORTED 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.  
*LDAP_NOT_SUPPORTED 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.
 
 
'''Description'''


<br> '''Description'''


The ldap_modify_ext() 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 ldap_modify_ext_s() instead. In order to get the results of this LDAP modify operation, you need to call the ldap_result() and the ldap_parse_result() functions. To make changes to an entry to the directory, you need to specify the following information:  
<br> The ldap_modify_ext() 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 ldap_modify_ext_s() instead. In order to get the results of this LDAP modify operation, you need to call the ldap_result() and the ldap_parse_result() functions. To make changes to an entry to the directory, you need to specify the following information:  


*A unique DN identifying the new entry
*A unique DN identifying the new entry
Line 7,111: Line 6,316:
Create an LDAPMod structure for changes that you want to make to an attribute. Create an array of these LDAPMod structures and pass the array as the <tt>mods</tt> argument.  
Create an LDAPMod structure for changes that you want to make to an attribute. Create an array of these LDAPMod structures and pass the array as the <tt>mods</tt> argument.  


<br> '''See Also'''


'''See Also'''
<br> ldap_modify_ext_s(), ldap_result(), ldap_parse_result(), LDAPMod()  
 
 
ldap_modify_ext_s(), ldap_result(), ldap_parse_result(), LDAPMod()  


=== ldap_modify_ext_s()  ===
=== ldap_modify_ext_s()  ===
Line 7,123: Line 6,326:
int ldap_modify_ext_s( LDAP *ld, const char *dn, LDAPMod **mods,
int ldap_modify_ext_s( LDAP *ld, const char *dn, LDAPMod **mods,
   LDAPControl **serverctrls, LDAPControl **clientctrls );</pre>  
   LDAPControl **serverctrls, LDAPControl **clientctrls );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_modify_ext_s() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_modify_ext_s() Function Parameters"
Line 7,149: Line 6,352:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:
 


One of the following values:
*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
*LDAP_PARAM_ERROR if an invalid parameter was passed to the function.  
*LDAP_PARAM_ERROR if an invalid parameter was passed to the function.  
Line 7,161: Line 6,363:
*LDAP_LOCAL_ERROR if an error occurred when receiving the results from the server.  
*LDAP_LOCAL_ERROR if an error occurred when receiving the results from the server.  
*LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded results from the server.  
*LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded results from the server.  
*LDAP_NOT_SUPPORTED 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.  
*LDAP_NOT_SUPPORTED 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.


'''Note:''' Directory Server 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.  
'''Note:''' Directory Server 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.  


<br> '''Description'''


'''Description'''
<br> The ldap_modify_ext_s() modifies an entry in the directory. ldap_modify_ext_s() 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 ldap_modify_ext() instead. To make changes to an entry to the directory, you need to specify the following information:  
 
 
The ldap_modify_ext_s() modifies an entry in the directory. ldap_modify_ext_s() 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 ldap_modify_ext() instead. To make changes to an entry to the directory, you need to specify the following information:  


*A unique DN identifying the new entry
*A unique DN identifying the new entry
Line 7,179: Line 6,379:
Create an LDAPMod structure for change that you want to make to an attribute. Create an array of these LDAPMod structures and pass the array as the <tt>mods</tt> argument.  
Create an LDAPMod structure for change that you want to make to an attribute. Create an array of these LDAPMod structures and pass the array as the <tt>mods</tt> argument.  


<br> '''See Also'''


'''See Also'''
<br> ldap_modify_ext(), LDAPMod  
 
 
ldap_modify_ext(), LDAPMod  


=== ldap_modify_s()  ===
=== ldap_modify_s()  ===
Line 7,190: Line 6,388:
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
int ldap_modify_s( LDAP *ld, const char *dn, LDAPMod **mods );</pre>  
int ldap_modify_s( LDAP *ld, const char *dn, LDAPMod **mods );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_modify_s() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_modify_s() Function Parameters"
Line 7,210: Line 6,408:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> For a list of possible result codes for an LDAP modify operation, see ldap_modify_ext_s().  
 
 
For a list of possible result codes for an LDAP modify operation, see ldap_modify_ext_s().
 
 
'''Description'''
 
 
Use the newer version of this function, ldap_modify_ext_s() .  


<br> '''Description'''


'''Example'''
<br> Use the newer version of this function, ldap_modify_ext_s() .


<br> '''Example'''


The following example uses the synchronous ldap_modify_s() function to makes the following changes to the <tt>Barbara Jensen</tt> entry:  
<br> The following example uses the synchronous ldap_modify_s() function to makes the following changes to the <tt>Barbara Jensen</tt> entry:  


*Adds the <tt>homePhone</tt> attribute.  
*Adds the <tt>homePhone</tt> attribute.  
Line 7,267: Line 6,459:
}
}
...</pre>  
...</pre>  
'''See Also'''


'''See Also'''
<br> ldap_modify_ext_s()  
 
 
ldap_modify_ext_s()  


=== ldap_modrdn()  ===
=== ldap_modrdn()  ===
Line 7,283: Line 6,473:
The ldap_modrdn2() function changes the relative distinguished name (RDN) of an entry in the directory asynchronously.  
The ldap_modrdn2() function changes the relative distinguished name (RDN) of an entry in the directory asynchronously.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap-deprecated.h&gt;
<pre>#include &lt;ldap-deprecated.h&gt;
int ldap_modrdn2( LDAP *ld, const char *dn, const char *newrdn,
int ldap_modrdn2( LDAP *ld, const char *dn, const char *newrdn,
   int deleteoldrdn );</pre>  
   int deleteoldrdn );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_modrdn2() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_modrdn2() Function Parameters"
Line 7,312: Line 6,500:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> Returns the message ID of the ldap_modrdn2() operation. To check the result of this operation, call ldap_result() and ldap_result2error(). For a list of possible result codes, see ldap_rename().  
 
 
Returns the message ID of the ldap_modrdn2() operation. To check the result of this operation, call ldap_result() and ldap_result2error(). For a list of possible result codes, see ldap_rename().
 
 
'''Description'''
 
 
Please use the newer version of this function, ldap_rename() .  


<br> '''Description'''


'''Example'''
<br> Please use the newer version of this function, ldap_rename() .


<br> '''Example'''


The following example uses the asynchronous ldap_modrdn2() function to change the RDN of an entry from <tt>uid=bjensen</tt> to <tt>uid=babs</tt>. The code removes the existing RDN <tt>bjensen</tt> from the <tt>uid</tt> attribute of the entry.  
<br> The following example uses the asynchronous ldap_modrdn2() function to change the RDN of an entry from <tt>uid=bjensen</tt> to <tt>uid=babs</tt>. The code removes the existing RDN <tt>bjensen</tt> from the <tt>uid</tt> attribute of the entry.  
<pre>#include &lt;ldap-deprecated.h&gt;
<pre>#include &lt;ldap-deprecated.h&gt;
...
...
Line 7,357: Line 6,539:
ldap_perror( ld, "ldap_modrdn2" );
ldap_perror( ld, "ldap_modrdn2" );
...</pre>  
...</pre>  
'''See Also'''


'''See Also'''
<br> ldap_rename()  
 
 
ldap_rename()  


=== ldap_modrdn2_s()  ===
=== ldap_modrdn2_s()  ===
Line 7,367: Line 6,547:
int ldap_modrdn2_s( LDAP *ld, const char *dn,
int ldap_modrdn2_s( LDAP *ld, const char *dn,
   const char *newrdn, int deleteoldrdn );</pre>  
   const char *newrdn, int deleteoldrdn );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_modrdn2_s() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_modrdn2_s() Function Parameters"
Line 7,390: Line 6,570:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> For a list of possible result codes, see ldap_rename_s() .  
 
 
For a list of possible result codes, see ldap_rename_s() .
 
 
'''Description'''
 
 
Please use the newer version of this function, ldap_rename_s() .  


<br> '''Description'''


'''Example'''
<br> Please use the newer version of this function, ldap_rename_s() .


<br> '''Example'''


The following example uses the synchronous ldap_modrdn2_s() function to change the RDN of an entry from <tt>uid=bjensen</tt> to <tt>uid=babs</tt>. The code removes the existing RDN <tt>babs</tt> from the <tt>uid</tt> attribute of the entry.  
<br> The following example uses the synchronous ldap_modrdn2_s() function to change the RDN of an entry from <tt>uid=bjensen</tt> to <tt>uid=babs</tt>. The code removes the existing RDN <tt>babs</tt> from the <tt>uid</tt> attribute of the entry.  
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
...
...
Line 7,421: Line 6,595:
}
}
...</pre>  
...</pre>  
'''See Also'''


'''See Also'''
<br> ldap_rename_s()  
 
 
ldap_rename_s()  


=== ldap_mods_free()  ===
=== ldap_mods_free()  ===
Line 7,433: Line 6,605:
'''Note:''' You need to call this function only if you‚Äö√Ñ√¥ve allocated memory for these structures yourself. For more information, see the <tt>ldap-extension.h</tt> header file.  
'''Note:''' You need to call this function only if you‚Äö√Ñ√¥ve allocated memory for these structures yourself. For more information, see the <tt>ldap-extension.h</tt> header file.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
void ldap_mods_free( LDAPMod **mods, int freemods );</pre>  
void ldap_mods_free( LDAPMod **mods, int freemods );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_mods_free() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_mods_free() Function Parameters"
Line 7,455: Line 6,625:
|}
|}


<br> '''Example'''


'''Example'''
<br> The following example allocates memory for LDAPMod structures and frees them when done.  
 
 
The following example allocates memory for LDAPMod structures and frees them when done.  
<pre>#include &lt;stdio.h&gt;
<pre>#include &lt;stdio.h&gt;
#include &lt;ldap.h&gt;
#include &lt;ldap.h&gt;
Line 7,493: Line 6,661:
The ldap_msgfree() function frees the memory allocated for a result by ldap_result() or ldap_search_s().  
The ldap_msgfree() function frees the memory allocated for a result by ldap_result() or ldap_search_s().  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
int ldap_msgfree( LDAPMessage *lm );</pre>  
int ldap_msgfree( LDAPMessage *lm );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_msgfree() Function Parameter"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_msgfree() Function Parameter"
Line 7,512: Line 6,678:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:
 


One of the following values:
*<tt>LDAP_RES_BIND</tt> indicates that the LDAPMessage structure contains the result of an LDAP bind operation.  
*<tt>LDAP_RES_BIND</tt> indicates that the LDAPMessage structure contains the result of an LDAP bind operation.  
*<tt>LDAP_RES_SEARCH_ENTRY</tt> indicates that the LDAPMessage structure contains an entry found during an LDAP search operation.  
*<tt>LDAP_RES_SEARCH_ENTRY</tt> indicates that the LDAPMessage structure contains an entry found during an LDAP search operation.  
Line 7,531: Line 6,696:
*If unsuccessful, returns the LDAP error code for the operation.
*If unsuccessful, returns the LDAP error code for the operation.


<br> '''Example'''


'''Example'''
<br> The following example frees the results of a search.  
 
 
The following example frees the results of a search.  
<pre>#include &lt;stdio.h&gt;
<pre>#include &lt;stdio.h&gt;
#include &lt;ldap.h&gt;
#include &lt;ldap.h&gt;
Line 7,555: Line 6,718:
ldap_msgfree( result );
ldap_msgfree( result );
...</pre>  
...</pre>  
'''See Also'''


'''See Also'''
<br> ldap_result(), ldap_search_s()  
 
 
ldap_result(), ldap_search_s()  


=== ldap_msgid()  ===
=== ldap_msgid()  ===
Line 7,565: Line 6,726:
The ldap_msgid() function determines the message ID of a result obtained by calling ldap_result() or ldap_search_s().  
The ldap_msgid() function determines the message ID of a result obtained by calling ldap_result() or ldap_search_s().  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
int ldap_msgid( LDAPMessage *lm );</pre>  
int ldap_msgid( LDAPMessage *lm );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_msgid() Function Parameter"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_msgid() Function Parameter"
Line 7,584: Line 6,743:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:  
 
 
One of the following values:  


*The message ID if successful.  
*The message ID if successful.  
*<tt>-1</tt> if unsuccessful.
*<tt>-1</tt> if unsuccessful.


<br> '''Example'''


'''Example'''
<br> The following example prints the message ID from the result obtained from a synchronous LDAP search operation.  
 
 
The following example prints the message ID from the result obtained from a synchronous LDAP search operation.  
<pre>#include &lt;stdio.h&gt;
<pre>#include &lt;stdio.h&gt;
#include &lt;ldap.h&gt;
#include &lt;ldap.h&gt;
Line 7,617: Line 6,772:
}
}
...</pre>  
...</pre>  
'''See Also'''


'''See Also'''
<br> ldap_msgtype(), ldap_result() , ldap_search_s()  
 
 
ldap_msgtype(), ldap_result() , ldap_search_s()  


=== ldap_msgtype()  ===
=== ldap_msgtype()  ===
Line 7,627: Line 6,780:
The ldap_msgtype() function determines the type of result obtained by calling ldap_result() or ldap_search_s().  
The ldap_msgtype() function determines the type of result obtained by calling ldap_result() or ldap_search_s().  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
int ldap_msgtype( LDAPMessage *lm );</pre>  
int ldap_msgtype( LDAPMessage *lm );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_msgtype() Function Parameter"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_msgtype() Function Parameter"
Line 7,646: Line 6,797:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:
 


One of the following values:
*<tt>LDAP_RES_BIND</tt> indicates that the LDAPMessage structure contains the result of an LDAP bind operation.  
*<tt>LDAP_RES_BIND</tt> indicates that the LDAPMessage structure contains the result of an LDAP bind operation.  
*<tt>LDAP_RES_SEARCH_ENTRY</tt> indicates that the LDAPMessage structure contains an entry found during an LDAP search operation.  
*<tt>LDAP_RES_SEARCH_ENTRY</tt> indicates that the LDAPMessage structure contains an entry found during an LDAP search operation.  
Line 7,661: Line 6,811:
*<tt>LDAP_RES_COMPARE</tt> indicates that the LDAPMessage structure contains the result of an LDAP compare operation.  
*<tt>LDAP_RES_COMPARE</tt> indicates that the LDAPMessage structure contains the result of an LDAP compare operation.  
*<tt>LDAP_RES_EXTENDED</tt> indicates that the LDAPMessage structure contains the result of an LDAP v3 extended operation.  
*<tt>LDAP_RES_EXTENDED</tt> indicates that the LDAPMessage structure contains the result of an LDAP v3 extended operation.  
*<tt>-1</tt> indicates that the <tt>lm</tt> argument is not a pointer to a valid LDAPMessage structure.  
*<tt>-1</tt> indicates that the <tt>lm</tt> argument is not a pointer to a valid LDAPMessage structure.
 
 
'''Example'''


<br> '''Example'''


The following example prints the message type for a result obtained from a synchronous LDAP search operation.  
<br> The following example prints the message type for a result obtained from a synchronous LDAP search operation.  
<pre>#include &lt;stdio.h&gt;
<pre>#include &lt;stdio.h&gt;
#include &lt;ldap.h&gt;
#include &lt;ldap.h&gt;
Line 7,689: Line 6,837:
}
}
...</pre>  
...</pre>  
'''See Also'''


'''See Also'''
<br> ldap_msgid(), ldap_result() , ldap_search_s()  
 
 
ldap_msgid(), ldap_result() , ldap_search_s()  


=== ldap_multisort_entries()  ===
=== ldap_multisort_entries()  ===
Line 7,699: Line 6,845:
The ldap_multisort_entries() function sorts a chain of entries retrieved from an LDAP search call (ldap_search_s() or ldap_result()) by either a specified set of attributes in the entries or DN.  
The ldap_multisort_entries() function sorts a chain of entries retrieved from an LDAP search call (ldap_search_s() or ldap_result()) by either a specified set of attributes in the entries or DN.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
int ldap_multisort_entries( LDAP *ld, LDAPMessage **chain,
int ldap_multisort_entries( LDAP *ld, LDAPMessage **chain,
   char **attr, LDAP_CMP_CALLBACK *cmp );</pre>  
   char **attr, LDAP_CMP_CALLBACK *cmp );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_multisort_entries() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_multisort_entries() Function Parameters"
Line 7,728: Line 6,872:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:
 


One of the following values:
*<tt>0</tt> if successful.  
*<tt>0</tt> if successful.  
*<tt>-1</tt> if memory cannot be allocated by this function. (The error code LDAP_NO_MEMORY is set in the LDAP structure. To get the error code, call the ldap_get_lderrno() function.)  
*<tt>-1</tt> if memory cannot be allocated by this function. (The error code LDAP_NO_MEMORY is set in the LDAP structure. To get the error code, call the ldap_get_lderrno() function.)  
*LDAP_PARAM_ERROR if an invalid parameter was passed to the function  
*LDAP_PARAM_ERROR if an invalid parameter was passed to the function
 
 
'''Example'''


<br> '''Example'''


The following example sorts entries first by the <tt>roomNumber</tt> attribute, then by the <tt>telephoneNumber</tt> attribute.  
<br> The following example sorts entries first by the <tt>roomNumber</tt> attribute, then by the <tt>telephoneNumber</tt> attribute.  
<pre>#include &lt;stdio.h&gt;
<pre>#include &lt;stdio.h&gt;
#include &lt;string.h&gt;
#include &lt;string.h&gt;
Line 7,768: Line 6,909:
}
}
...</pre>  
...</pre>  
'''See Also'''


'''See Also'''
<br> ldap_result(), ldap_search_s() , ldap_sort_entries(), LDAP_CMP_CALLBACK()  
 
 
ldap_result(), ldap_search_s() , ldap_sort_entries(), LDAP_CMP_CALLBACK()  


=== ldap_name2template()  ===
=== ldap_name2template()  ===
Line 7,778: Line 6,917:
The ldap_name2template() function obtains a pointer to the correct <tt>ldap_disptmpl</tt> structure.  
The ldap_name2template() function obtains a pointer to the correct <tt>ldap_disptmpl</tt> structure.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;disptmpl.h&gt;
<pre>#include &lt;disptmpl.h&gt;
struct ldap_disptmpl * ldap_name2template( char *name
struct ldap_disptmpl * ldap_name2template( char *name
   struct ldap_disptmpl *tmpllist );</pre>  
   struct ldap_disptmpl *tmpllist );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_name2template() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_name2template() Function Parameters"
Line 7,801: Line 6,938:
|}
|}


<br> '''Returns'''


'''Returns'''
<br>
 


*If successful, <tt>0</tt> is returned and <tt>tmpllistp</tt> is configured.  
*If successful, <tt>0</tt> is returned and <tt>tmpllistp</tt> is configured.  
Line 7,810: Line 6,947:
**<tt>LDAP_TMPL_ERR_MEM</tt> if there is a memory allocation problem.  
**<tt>LDAP_TMPL_ERR_MEM</tt> if there is a memory allocation problem.  
**<tt>LDAP_TMPL_ERR_SYNTAX</tt> if there is a problem with the format of the templates buffer or file.  
**<tt>LDAP_TMPL_ERR_SYNTAX</tt> if there is a problem with the format of the templates buffer or file.  
**<tt>LDAP_TMPL_ERR_FILE</tt> if the file cannot be read.  
**<tt>LDAP_TMPL_ERR_FILE</tt> if the file cannot be read.
 
 
'''Description'''


<br> '''Description'''


ldap_name2template() obtains a pointer to the correct <tt>ldap_disptmpl</tt> structure. Links to templates can be defined by name.  
<br> ldap_name2template() obtains a pointer to the correct <tt>ldap_disptmpl</tt> structure. Links to templates can be defined by name.  


=== ldap_next_attribute()  ===
=== ldap_next_attribute()  ===
Line 7,822: Line 6,957:
The ldap_next_attribute() function returns the name of the next attribute in an entry returned by ldap_first_entry() or ldap_next_entry().  
The ldap_next_attribute() function returns the name of the next attribute in an entry returned by ldap_first_entry() or ldap_next_entry().  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
char * ldap_next_attribute( LDAP *ld, LDAPMessage *entry,
char * ldap_next_attribute( LDAP *ld, LDAPMessage *entry,
   BerElement *ber);</pre>  
   BerElement *ber);</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_next_attribute() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_next_attribute() Function Parameters"
Line 7,848: Line 6,981:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:
 


One of the following values:
*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 ldap_memfree() function.  
*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 ldap_memfree() function.  
*If no more attributes exist in the entry, returns a <tt>NULL</tt> .  
*If no more attributes exist in the entry, returns a <tt>NULL</tt> .  
*If unsuccessful, returns a <tt>NULL</tt> and sets the appropriate error code in the LDAP structure. To get the error code, call the ldap_get_lderrno() function.  
*If unsuccessful, returns a <tt>NULL</tt> and sets the appropriate error code in the LDAP structure. To get the error code, call the ldap_get_lderrno() function.
 
 
'''Description'''
 
 
The ldap_first_attribute() function returns a pointer to a BerElement. You use this pointer with ldap_next_attribute() to iterate through the list of elements. After the last call to ldap_next_element(), you should free the BerElement pointer using ldap_ber_free(). When calling ldap_ber_free(), make sure to specify that the buffer is not freed (pass <tt>0</tt> for the <tt>freebuf</tt> parameter).
 
 
'''Example'''


<br> '''Description'''


See the example under ldap_first_attribute().  
<br> The ldap_first_attribute() function returns a pointer to a BerElement. You use this pointer with ldap_next_attribute() to iterate through the list of elements. After the last call to ldap_next_element(), you should free the BerElement pointer using ldap_ber_free(). When calling ldap_ber_free(), make sure to specify that the buffer is not freed (pass <tt>0</tt> for the <tt>freebuf</tt> parameter).  


<br> '''Example'''


'''See Also'''
<br> See the example under ldap_first_attribute().


<br> '''See Also'''


ldap_first_attribute(), ldap_getfirstfilter(), ldap_next_entry()  
<br> ldap_first_attribute(), ldap_getfirstfilter(), ldap_next_entry()  


=== ldap_next_disptmpl()  ===
=== ldap_next_disptmpl()  ===
Line 7,879: Line 7,005:
The ldap_next_disptmpl() function returns the next template in a list.  
The ldap_next_disptmpl() function returns the next template in a list.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;disptmpl.h&gt;
<pre>#include &lt;disptmpl.h&gt;
struct ldap_disptmpl * ldap_next_disptmpl( struct ldap_disptmpl *tmpllist,
struct ldap_disptmpl * ldap_next_disptmpl( struct ldap_disptmpl *tmpllist,
   struct ldap_disptmpl *tmpl );;</pre>  
   struct ldap_disptmpl *tmpl );;</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_next_disptmpl() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_next_disptmpl() Function Parameters"
Line 7,902: Line 7,026:
|}
|}


<br> '''Returns'''


'''Returns'''
<br>
 


*If successful, <tt>0</tt> is returned and <tt>tmpllistp</tt> is configured.  
*If successful, <tt>0</tt> is returned and <tt>tmpllistp</tt> is configured.  
Line 7,911: Line 7,035:
**<tt>LDAP_TMPL_ERR_MEM</tt> if there is a memory allocation problem.  
**<tt>LDAP_TMPL_ERR_MEM</tt> if there is a memory allocation problem.  
**<tt>LDAP_TMPL_ERR_SYNTAX</tt> if there is a problem with the format of the templates buffer or file.  
**<tt>LDAP_TMPL_ERR_SYNTAX</tt> if there is a problem with the format of the templates buffer or file.  
**<tt>LDAP_TMPL_ERR_FILE</tt> if the file cannot be read.
**<tt>LDAP_TMPL_ERR_FILE</tt> if the file cannot be read.
 
 
'''Description'''
 
 
ldap_next_disptmpl() returns the template following the previous one in the list of templates pointed to by the parameter <tt>tmpllistp</tt>. <tt>tmpllistp</tt> is typically obtained by calling ldap_init_templates() .  


<br> '''Description'''


'''See Also'''
<br> ldap_next_disptmpl() returns the template following the previous one in the list of templates pointed to by the parameter <tt>tmpllistp</tt>. <tt>tmpllistp</tt> is typically obtained by calling ldap_init_templates() .


<br> '''See Also'''


ldap_first_disptmpl()  
<br> ldap_first_disptmpl()  


=== ldap_next_entry()  ===
=== ldap_next_entry()  ===
Line 7,929: Line 7,049:
The ldap_next_entry() function returns a pointer to the LDAPMessage structure representing the next directory entry in a chain of search results.  
The ldap_next_entry() function returns a pointer to the LDAPMessage structure representing the next directory entry in a chain of search results.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
LDAPMessage * ldap_next_entry( LDAP *ld, LDAPMessage *entry );</pre>  
LDAPMessage * ldap_next_entry( LDAP *ld, LDAPMessage *entry );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_next_entry() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_next_entry() Function Parameters"
Line 7,951: Line 7,069:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:
 


One of the following values:
*If successful, returns the pointer to the next LDAPMessage structure of the type <tt>LDAP_RES_SEARCH_ENTRY</tt> in a chain of search results.  
*If successful, returns the pointer to the next LDAPMessage structure of the type <tt>LDAP_RES_SEARCH_ENTRY</tt> in a chain of search results.  
*If no more LDAPMessage structures of the type <tt>LDAP_RES_SEARCH_ENTRY</tt> are in the chain or if the function is unsuccessful, returns a <tt>NULLMSG</tt>.
*If no more LDAPMessage structures of the type <tt>LDAP_RES_SEARCH_ENTRY</tt> are in the chain or if the function is unsuccessful, returns a <tt>NULLMSG</tt>.
 
 
'''Description'''
 
 
The ldap_next_entry() function returns a pointer to the LDAPMessage structure representing the next directory entry in a chain of search results. You can use this function in conjunction with the ldap_first_entry() 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 <tt>LDAP_RES_SEARCH_ENTRY</tt> as messages containing directory entries have the type <tt>LDAP_RES_SEARCH_ENTRY</tt>.  


<br> '''Description'''


'''See Also'''
<br> The ldap_next_entry() function returns a pointer to the LDAPMessage structure representing the next directory entry in a chain of search results. You can use this function in conjunction with the ldap_first_entry() 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 <tt>LDAP_RES_SEARCH_ENTRY</tt> as messages containing directory entries have the type <tt>LDAP_RES_SEARCH_ENTRY</tt>.


<br> '''See Also'''


ldap_first_entry()  
<br> ldap_first_entry()  


=== ldap_next_message()  ===
=== ldap_next_message()  ===
Line 7,975: Line 7,088:
The ldap_next_message() function returns a pointer to the next LDAPMessage structure in a chain of search results.  
The ldap_next_message() function returns a pointer to the next LDAPMessage structure in a chain of search results.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
LDAPMessage * ldap_next_message( LDAP *ld, LDAPMessage *msg );</pre>  
LDAPMessage * ldap_next_message( LDAP *ld, LDAPMessage *msg );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_next_message() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_next_message() Function Parameters"
Line 7,997: Line 7,108:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:
 


One of the following values:
*If successful, returns the pointer to the next LDAPMessage structure in a chain of search results.  
*If successful, returns the pointer to the next LDAPMessage structure in a chain of search results.  
*If no more LDAPMessage structures are in the chain or if the function is unsuccessful, returns a <tt>NULLMSG</tt>.
*If no more LDAPMessage structures are in the chain or if the function is unsuccessful, returns a <tt>NULLMSG</tt>.
 
 
'''Description'''
 
 
The ldap_next_message() function returns a pointer to the next LDAPMessage structure in a chain of search results. You can use this function in conjunction with the ldap_first_message() function to iterate through the chain of search results. You can also call the ldap_msgtype() function to determine if each message contains a matching entry (a message of the type <tt>LDAP_RES_SEARCH_ENTRY</tt> ) or a search reference (a message of the type <tt>LDAP_RES_SEARCH_REFERENCE</tt>).  


<br> '''Description'''


'''See Also'''
<br> The ldap_next_message() function returns a pointer to the next LDAPMessage structure in a chain of search results. You can use this function in conjunction with the ldap_first_message() function to iterate through the chain of search results. You can also call the ldap_msgtype() function to determine if each message contains a matching entry (a message of the type <tt>LDAP_RES_SEARCH_ENTRY</tt> ) or a search reference (a message of the type <tt>LDAP_RES_SEARCH_REFERENCE</tt>).


<br> '''See Also'''


ldap_first_message(), ldap_msgtype()  
<br> ldap_first_message(), ldap_msgtype()  


=== ldap_next_reference()  ===
=== ldap_next_reference()  ===
Line 8,021: Line 7,127:
The ldap_next_reference() function returns a pointer to the LDAPMessage structure representing the next search reference in a chain of search results.  
The ldap_next_reference() function returns a pointer to the LDAPMessage structure representing the next search reference in a chain of search results.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
LDAPMessage * ldap_next_reference( LDAP *ld, LDAPMessage *ref );</pre>  
LDAPMessage * ldap_next_reference( LDAP *ld, LDAPMessage *ref );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_next_reference() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_next_reference() Function Parameters"
Line 8,043: Line 7,147:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:
 


One of the following values:
*If successful, returns the pointer to the next LDAPMessage structure of the type <tt>LDAP_RES_SEARCH_REFERENCE</tt> in a chain of search results.  
*If successful, returns the pointer to the next LDAPMessage structure of the type <tt>LDAP_RES_SEARCH_REFERENCE</tt> in a chain of search results.  
*If no more LDAPMessage structures of the type <tt>LDAP_RES_SEARCH_REFERENCE</tt> are in the chain or if the function is unsuccessful, returns a <tt>NULLMSG</tt>.
*If no more LDAPMessage structures of the type <tt>LDAP_RES_SEARCH_REFERENCE</tt> are in the chain or if the function is unsuccessful, returns a <tt>NULLMSG</tt>.
 
 
'''Description'''
 
 
The ldap_next_reference() function returns a pointer to the LDAPMessage structure representing the next search reference in a chain of search results. You can use this function in conjunction with the ldap_first_reference() 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 <tt>LDAP_RES_SEARCH_REFERENCE</tt>. Messages containing search references have the type <tt>LDAP_RES_SEARCH_REFERENCE</tt>, 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.  


<br> '''Description'''


'''See Also'''
<br> The ldap_next_reference() function returns a pointer to the LDAPMessage structure representing the next search reference in a chain of search results. You can use this function in conjunction with the ldap_first_reference() 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 <tt>LDAP_RES_SEARCH_REFERENCE</tt>. Messages containing search references have the type <tt>LDAP_RES_SEARCH_REFERENCE</tt>, 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.


<br> '''See Also'''


ldap_first_reference()  
<br> ldap_first_reference()  


=== ldap_next_searchobj()  ===
=== ldap_next_searchobj()  ===
Line 8,067: Line 7,166:
The ldap_next_searchobj() function returns the following search preference in a defined list.  
The ldap_next_searchobj() function returns the following search preference in a defined list.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
struct ldap_searchobj * ldap_next_searchobj
struct ldap_searchobj * ldap_next_searchobj
   ( struct ldap_searchobj *sollist, struct ldap_searchobj *so );</pre>  
   ( struct ldap_searchobj *sollist, struct ldap_searchobj *so );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_next_searchobj() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_next_searchobj() Function Parameters"
Line 8,090: Line 7,187:
|}
|}


<br> '''Returns'''


'''Returns'''
<br>
 


*If successful, a pointer to an <tt>ldap_searchobj</tt> structure.  
*If successful, a pointer to an <tt>ldap_searchobj</tt> structure.  
*A <tt>NULL</tt> pointer is returned if <tt>so</tt> is the last entry in the list.  
*A <tt>NULL</tt> pointer is returned if <tt>so</tt> is the last entry in the list.


<br> '''Description'''


'''Description'''
<br> The search object returned by ldap_next_searchobj() follows the one defined by the <tt>so</tt> parameter.


<br> '''See Also'''


The search object returned by ldap_next_searchobj() follows the one defined by the <tt>so</tt> parameter.
<br> ldap_init_searchprefs(), ldap_first_searchobj()  


 
=== ldap_next_tmplcol()  ===
'''See Also'''
 
 
ldap_init_searchprefs(), ldap_first_searchobj()
 
=== ldap_next_tmplcol()  ===


The ldap_next_tmplcol() function returns a pointer to the following item (in the column) within a template.  
The ldap_next_tmplcol() function returns a pointer to the following item (in the column) within a template.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;disptmpl.h&gt;
<pre>#include &lt;disptmpl.h&gt;
struct ldap_tmplitem * ldap_next_tmplcol( struct ldap_disptmpl *tmpl,
struct ldap_tmplitem * ldap_next_tmplcol( struct ldap_disptmpl *tmpl,
   struct ldap_tmplitem *row, struct ldap_tmplitem *col );</pre>  
   struct ldap_tmplitem *row, struct ldap_tmplitem *col );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_next_tmplcol() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_next_tmplcol() Function Parameters"
Line 8,139: Line 7,230:
|}
|}


<br> '''Returns'''


'''Returns'''
<br>
 


*If successful, a pointer to an <tt>ldap_tmplitem</tt> structure.  
*If successful, a pointer to an <tt>ldap_tmplitem</tt> structure.  
*A <tt>NULL</tt> pointer on error or if <tt>col</tt> was the last item.
*A <tt>NULL</tt> pointer on error or if <tt>col</tt> was the last item.
 
 
'''Description'''
 
 
ldap_next_tmplcol() returns a pointer to the next item (in the column) of the row, defined by <tt>row</tt>, within the template defined by <tt>tmpl</tt>.  


<br> '''Description'''


'''See Also'''
<br> ldap_next_tmplcol() returns a pointer to the next item (in the column) of the row, defined by <tt>row</tt>, within the template defined by <tt>tmpl</tt>.


<br> '''See Also'''


ldap_first_tmplcol()  
<br> ldap_first_tmplcol()  


=== ldap_next_tmplrow()  ===
=== ldap_next_tmplrow()  ===
Line 8,162: Line 7,249:
The ldap_next_tmplrow() function returns a pointer to the following row in a template.  
The ldap_next_tmplrow() function returns a pointer to the following row in a template.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;disptmpl.h&gt;
<pre>#include &lt;disptmpl.h&gt;
struct ldap_tmplitem * ldap_next_tmplrow( struct ldap_disptmpl *tmpl,
struct ldap_tmplitem * ldap_next_tmplrow( struct ldap_disptmpl *tmpl,
   struct ldap_tmplitem *row );</pre>  
   struct ldap_tmplitem *row );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_next_tmplrow() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_next_tmplrow() Function Parameters"
Line 8,185: Line 7,270:
|}
|}


<br> '''Returns'''


'''Returns'''
<br>
 


*If successful, a pointer to an <tt>ldap_tmplitem</tt> structure.  
*If successful, a pointer to an <tt>ldap_tmplitem</tt> structure.  
*A <tt>NULL</tt> pointer on error.
*A <tt>NULL</tt> pointer on error.


<br> '''Description'''


'''Description'''
<br> ldap_next_tmplrow() returns a pointer to the row that follows the one defined by <tt>row</tt> in the template defined by <tt>tmpl</tt> .  
 
 
ldap_next_tmplrow() returns a pointer to the row that follows the one defined by <tt>row</tt> in the template defined by <tt>tmpl</tt> .  


=== ldap_oc2template()  ===
=== ldap_oc2template()  ===
Line 8,202: Line 7,285:
The ldap_oc2template() function obtains a pointer to the correct <tt>ldap_disptmpl</tt> structure.  
The ldap_oc2template() function obtains a pointer to the correct <tt>ldap_disptmpl</tt> structure.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;disptmpl.h&gt;
<pre>#include &lt;disptmpl.h&gt;
struct ldap_disptmpl * ldap_oc2template( char **oclist,
struct ldap_disptmpl * ldap_oc2template( char **oclist,
   struct ldap_disptmpl *tmpllist );</pre>  
   struct ldap_disptmpl *tmpllist );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_oc2template() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_oc2template() Function Parameters"
Line 8,225: Line 7,306:
|}
|}


<br> '''Returns'''


'''Returns'''
<br>
 


*Pointer to the first template where all of the object classes listed in one of the template's <tt>dt_oclist</tt> elements are contained in <tt>oclist</tt>.  
*Pointer to the first template where all of the object classes listed in one of the template's <tt>dt_oclist</tt> elements are contained in <tt>oclist</tt>.  
*A <tt>NULL</tt> pointer if no appropriate template is found.  
*A <tt>NULL</tt> pointer if no appropriate template is found.
 
 
'''Description'''


<br> '''Description'''


ldap_oc2template()searches <tt>tmpllist</tt> for the best template to use to display an entry that has a specific set of <tt>objectClass</tt> values.  
<br> ldap_oc2template()searches <tt>tmpllist</tt> for the best template to use to display an entry that has a specific set of <tt>objectClass</tt> values.  


=== ldap_open()  ===
=== ldap_open()  ===
<pre>#include &lt;ldap-deprecated.h&gt;
<pre>#include &lt;ldap-deprecated.h&gt;
ldap_open( const char *host, int port );</pre>  
ldap_open( const char *host, int port );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_open() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_open() Function Parameters"
Line 8,258: Line 7,337:
|}
|}


<br> '''Description'''


'''Description'''
<br> Please use a newer version of this function, ldap_init() or prldap_init() (IPv6).  
 
 
Please use a newer version of this function, ldap_init() or prldap_init() (IPv6).  


=== ldap_parse_authzid_control()  ===
=== ldap_parse_authzid_control()  ===
Line 8,268: Line 7,345:
The ldap_parse_authzid_control() function parses the authorization identity bind response control retrieved from the server to extract the authorization ID.  
The ldap_parse_authzid_control() function parses the authorization identity bind response control retrieved from the server to extract the authorization ID.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
LDAP_API(int) LDAP_CALL ldap_parse_authzid_control( LDAP *ld,
LDAP_API(int) LDAP_CALL ldap_parse_authzid_control( LDAP *ld,
   LDAPControl **ctrlp, char **authzid );</pre>  
   LDAPControl **ctrlp, char **authzid );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_parse_authzid_control() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_parse_authzid_control() Function Parameters"
Line 8,294: Line 7,369:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:
 


One of the following values:
*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
*LDAP_PARAM_ERROR if any of the arguments are invalid.  
*LDAP_PARAM_ERROR if any of the arguments are invalid.  
Line 8,304: Line 7,378:
*LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded message.  
*LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded message.  
*LDAP_CONTROL_NOT_FOUND if no control can be found in the response returned from the server.  
*LDAP_CONTROL_NOT_FOUND if no control can be found in the response returned from the server.  
*LDAP_NOT_SUPPORTED 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.  
*LDAP_NOT_SUPPORTED 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.
 
 
'''See Also'''


<br> '''See Also'''


ldap_create_authzid_control()  
<br> ldap_create_authzid_control()  


=== ldap_parse_entrychange_control()  ===
=== ldap_parse_entrychange_control()  ===
Line 8,318: Line 7,390:
'''Note:''' 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.  
'''Note:''' 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.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
int ldap_parse_entrychange_control( LDAP *ld,
int ldap_parse_entrychange_control( LDAP *ld,
   LDAPControl **ctrls, int *chgtypep, char **prevdnp,
   LDAPControl **ctrls, int *chgtypep, char **prevdnp,
   int *chgnumpresentp, long *chgnump );</pre>  
   int *chgnumpresentp, long *chgnump );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_parse_entrychange_control() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_parse_entrychange_control() Function Parameters"
Line 8,342: Line 7,412:
|-
|-
| <tt>changetypes</tt>  
| <tt>changetypes</tt>  
| Pointer to an integer specifying the type of change made to the entry. This field can have one of the following values:
| Pointer to an integer specifying the type of change made to the entry. This field can have one of the following values:  
*<tt>LDAP_CHANGETYPE_ADD</tt> specifies that the entry was added to the directory.
*<tt>LDAP_CHANGETYPE_ADD</tt> specifies that the entry was added to the directory.  
*<tt>LDAP_CHANGETYPE_DELETE</tt> specifies that the entry was deleted from the directory.
*<tt>LDAP_CHANGETYPE_DELETE</tt> specifies that the entry was deleted from the directory.  
*<tt>LDAP_CHANGETYPE_MODIFY</tt> specifies that the entry was modified.
*<tt>LDAP_CHANGETYPE_MODIFY</tt> specifies that the entry was modified.  
*<tt>LDAP_CHANGETYPE_MODDN</tt> specifies that the DN or RDN of the entry was changed (a modify RDN or modify DN operation was performed).
*<tt>LDAP_CHANGETYPE_MODDN</tt> specifies that the DN or RDN of the entry was changed (a modify RDN or modify DN operation was performed).
|-
|-
| <tt>prevdnp</tt>  
| <tt>prevdnp</tt>  
Line 8,352: Line 7,423:
|-
|-
| <tt>chgnumpresentp</tt>  
| <tt>chgnumpresentp</tt>  
| 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:
| 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:  
*<tt>0</tt> specifies that the change number is not included.
*<tt>0</tt> specifies that the change number is not included.  
*A non-zero value specifies that the change number is included and is available as the <tt>chgnump</tt> argument.
*A non-zero value specifies that the change number is included and is available as the <tt>chgnump</tt> argument.
|-
|-
| <tt>chgnump</tt>  
| <tt>chgnump</tt>  
Line 8,360: Line 7,432:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:
 


One of the following values:
*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
*LDAP_NO_MEMORY if memory cannot be allocated.  
*LDAP_NO_MEMORY if memory cannot be allocated.  
*LDAP_DECODING_ERROR if an error occurred when BER-decoding the control.  
*LDAP_DECODING_ERROR if an error occurred when BER-decoding the control.
 


'''Description'''
<br> '''Description'''  


<br> The ldap_parse_entrychange_control() function can be called:


The ldap_parse_entrychange_control() function can be called:
*To parse an entry returned from a persistent search operation and retrieve an entry change control.  
*To parse an entry returned from a persistent search operation and retrieve an entry change control.  
*After receiving an entry from a persistent search and retrieving the controls from the entry. Call ldap_get_entry_controls() to get the controls.  
*After receiving an entry from a persistent search and retrieving the controls from the entry. Call ldap_get_entry_controls() to get the controls.
 
 
'''See Also'''


<br> '''See Also'''


ldap_create_persistentsearch_control(), ldap_get_entry_controls()  
<br> ldap_create_persistentsearch_control(), ldap_get_entry_controls()  


=== ldap_parse_extended_result()  ===
=== ldap_parse_extended_result()  ===
Line 8,389: Line 7,457:
int ldap_parse_extended_result( LDAP *ld, LDAPMessage *res,
int ldap_parse_extended_result( LDAP *ld, LDAPMessage *res,
   char **retoidp, struct berval **retdatap, int freeit );</pre>  
   char **retoidp, struct berval **retdatap, int freeit );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_parse_extended_result() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_parse_extended_result() Function Parameters"
Line 8,415: Line 7,483:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values, which indicates the result of parsing the server’s response:
 


One of the following values, which indicates the result of parsing the server’s response:
*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
*LDAP_PARAM_ERROR if any of the arguments are invalid.  
*LDAP_PARAM_ERROR if any of the arguments are invalid.  
*LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded results from the server.  
*LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded results from the server.  
*LDAP_NOT_SUPPORTED 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. '''Note:''' This value does not apply to the operation itself.  
*LDAP_NOT_SUPPORTED 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. '''Note:''' This value does not apply to the operation itself.
 


'''Description'''
<br> '''Description'''  


<br> ldap_parse_extended_result() parses the server’s response to an extended operation. After you call the ldap_extended_operation() and the ldap_result() functions, you can pass the results to ldap_parse_extended_result(). This function gets the following data from the server’s response:


ldap_parse_extended_result() parses the server’s response to an extended operation. After you call the ldap_extended_operation() and the ldap_result() functions, you can pass the results to ldap_parse_extended_result(). This function gets the following data from the server’s response:
*The extended operation OID received from the server is passed back as the retoidp argument.  
*The extended operation OID received from the server is passed back as the retoidp argument.  
*The data received from the server is passed back in the berval structure as the <tt>retdatap</tt> argument.  
*The data received from the server is passed back in the berval structure as the <tt>retdatap</tt> argument.  
Line 8,438: Line 7,504:
The ldap_parse_passwd() 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.  
The ldap_parse_passwd() 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.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
LDAP_API(int) LDAP_CALL ldap_parse_passwd( LDAP *ld, LDAPMessage *result,
LDAP_API(int) LDAP_CALL ldap_parse_passwd( LDAP *ld, LDAPMessage *result,
   struct berval *genpasswd );</pre>  
   struct berval *genpasswd );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_parse_passwd() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_parse_passwd() Function Parameters"
Line 8,464: Line 7,528:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:
 


One of the following values:
*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
*LDAP_PARAM_ERROR if any of the arguments are invalid.  
*LDAP_PARAM_ERROR if any of the arguments are invalid.  
*LDAP_NO_MEMORY if memory cannot be allocated for the authorization identity.  
*LDAP_NO_MEMORY if memory cannot be allocated for the authorization identity.  
*LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded message.  
*LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded message.  
*LDAP_NOT_SUPPORTED 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.  
*LDAP_NOT_SUPPORTED 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.


=== ldap_parse_passwd_result()  ===
=== ldap_parse_passwd_result()  ===
Line 8,479: Line 7,542:
The ldap_parse_passwd_result() 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.  
The ldap_parse_passwd_result() 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.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
LDAP_API(int) LDAP_CALL ldap_parse_passwd_result( LDAP *ld, int *msgidp,
LDAP_API(int) LDAP_CALL ldap_parse_passwd_result( LDAP *ld, int *msgidp,
   struct timeval *timeout, struct berval *genpasswd );</pre>  
   struct timeval *timeout, struct berval *genpasswd );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_parse_passwd_result() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_parse_passwd_result() Function Parameters"
Line 8,508: Line 7,569:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:


 
*LDAP_SUCCESS if successful.  
One of the following values:
*LDAP_PARAM_ERROR if any of the arguments are invalid.  
*LDAP_SUCCESS if successful.
*LDAP_PARAM_ERROR if any of the arguments are invalid.  
*LDAP_NO_MEMORY if memory cannot be allocated for the authorization identity.  
*LDAP_NO_MEMORY if memory cannot be allocated for the authorization identity.  
*LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded message.  
*LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded message.  
*LDAP_NOT_SUPPORTED 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.  
*LDAP_NOT_SUPPORTED 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.


=== ldap_parse_pwdpolicy_control()  ===
=== ldap_parse_pwdpolicy_control()  ===
Line 8,523: Line 7,583:
The ldap_parse_pwdpolicy_control() 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 ldap_create_userstatus_control() is used to create a request control sent to the server. The ldap_parse_pwdpolicy_control() function populates an LDAPpwdpolicy structure.  
The ldap_parse_pwdpolicy_control() 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 ldap_create_userstatus_control() is used to create a request control sent to the server. The ldap_parse_pwdpolicy_control() function populates an LDAPpwdpolicy structure.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
LDAP_API(int) LDAP_CALL ldap_parse_pwdpolicy_control( LDAP *ld,
LDAP_API(int) LDAP_CALL ldap_parse_pwdpolicy_control( LDAP *ld,
   LDAPControl **ctrlp, LDAPpwdpolicy *pp );</pre>  
   LDAPControl **ctrlp, LDAPpwdpolicy *pp );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_parse_pwdpolicy_control() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_parse_pwdpolicy_control() Function Parameters"
Line 8,549: Line 7,607:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:
 


One of the following values:
*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
*LDAP_PARAM_ERROR if any of the arguments are invalid.  
*LDAP_PARAM_ERROR if any of the arguments are invalid.  
Line 8,559: Line 7,616:
*LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded message.  
*LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded message.  
*LDAP_CONTROL_NOT_FOUND if no control can be found in the response returned from the server.  
*LDAP_CONTROL_NOT_FOUND if no control can be found in the response returned from the server.  
*LDAP_NOT_SUPPORTED 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.  
*LDAP_NOT_SUPPORTED 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.
 
 
'''See Also'''


<br> '''See Also'''


ldap_create_pwdpolicy_control(), LDAPpwdpolicy()  
<br> ldap_create_pwdpolicy_control(), LDAPpwdpolicy()  


=== ldap_parse_reference()  ===
=== ldap_parse_reference()  ===
Line 8,571: Line 7,626:
The ldap_parse_reference() function parses search references from the results received from an LDAP server. '''Note:''' 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.  
The ldap_parse_reference() function parses search references from the results received from an LDAP server. '''Note:''' 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.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
int ldap_parse_reference( LDAP *ld, LDAPMessage *ref,
int ldap_parse_reference( LDAP *ld, LDAPMessage *ref,
   char ***referralsp, LDAPControl ***serverctrlsp,
   char ***referralsp, LDAPControl ***serverctrlsp,
   int freeit );</pre>  
   int freeit );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_parse_reference() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_parse_reference() Function Parameters"
Line 8,604: Line 7,657:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:
 


One of the following values:
*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
*LDAP_PARAM_ERROR if any of the arguments are invalid.  
*LDAP_PARAM_ERROR if any of the arguments are invalid.  
*LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded results from the server.  
*LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded results from the server.  
*LDAP_NO_MEMORY if memory cannot be allocated.  
*LDAP_NO_MEMORY if memory cannot be allocated.
 
 
'''Description'''


<br> '''Description'''


The ldap_parse_reference() function parses the referral URLs from an LDAPMessage structure of the type <tt>LDAP_RES_SEARCH_REFERENCE</tt>, 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.  
<br> The ldap_parse_reference() function parses the referral URLs from an LDAPMessage structure of the type <tt>LDAP_RES_SEARCH_REFERENCE</tt>, 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.  


=== ldap_parse_result()  ===
=== ldap_parse_result()  ===
Line 8,624: Line 7,674:
The ldap_parse_result() function parses the results of an LDAP operation received from an LDAP server.  
The ldap_parse_result() function parses the results of an LDAP operation received from an LDAP server.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
int ldap_parse_result( LDAP *ld, LDAPMessage *res,
int ldap_parse_result( LDAP *ld, LDAPMessage *res,
   int *errcodep, char **matcheddnp, char **errmsgp,
   int *errcodep, char **matcheddnp, char **errmsgp,
   char ***referralsp, LDAPControl ***serverctrlsp, int freeit);</pre>  
   char ***referralsp, LDAPControl ***serverctrlsp, int freeit);</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_parse_result() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_parse_result() Function Parameters"
Line 8,669: Line 7,717:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:
 


One of the following values:
*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
*LDAP_NO_RESULTS_RETURNED if the specified LDAPMessage 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).  
*LDAP_NO_RESULTS_RETURNED if the specified LDAPMessage 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).  
Line 8,679: Line 7,726:
*LDAP_PARAM_ERROR if any of the arguments are invalid.  
*LDAP_PARAM_ERROR if any of the arguments are invalid.  
*LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded results from the server.  
*LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded results from the server.  
*LDAP_NO_MEMORY if memory cannot be allocated.  
*LDAP_NO_MEMORY if memory cannot be allocated.
 


'''Description'''
<br> '''Description'''  


<br> The ldap_parse_result() function parses the results of an LDAP operation (received from an LDAP server) and retrieves:


The ldap_parse_result() function parses the results of an LDAP operation (received from an LDAP server) and retrieves:
*The LDAP result code that indicates the result of the LDAP operation (<tt>errcodep</tt>).  
*The LDAP result code that indicates the result of the LDAP operation (<tt>errcodep</tt>).  
*An additional error message (<tt>optional</tt>) sent by the server (<tt>errmsgp</tt>).  
*An additional error message (<tt>optional</tt>) sent by the server (<tt>errmsgp</tt>).  
*The portion of the DN that finds an entry, if the server is unable to find an entry from a DN that you specify (<tt>matcheddnp</tt>).  
*The portion of the DN that finds an entry, if the server is unable to find an entry from a DN that you specify (<tt>matcheddnp</tt>).  
*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 (<tt>referralsp</tt>).  
*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 (<tt>referralsp</tt>).  
*A set of server response controls that are relevant to the operation (<tt>serverctrlsp</tt>). Calling this function creates an array of LDAPControl structures that you can pass to subsequent API functions (such as the ldap_parse_sort_control() function.  
*A set of server response controls that are relevant to the operation (<tt>serverctrlsp</tt>). Calling this function creates an array of LDAPControl structures that you can pass to subsequent API functions (such as the ldap_parse_sort_control() function.


See also ldap_result().  
See also ldap_result().  
Line 8,700: Line 7,746:
'''Note:''' 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.  
'''Note:''' 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.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
int ldap_parse_sasl_bind_result( LDAP *ld, LDAPMessage *res,
int ldap_parse_sasl_bind_result( LDAP *ld, LDAPMessage *res,
   struct berval **servercredp, int freeit );</pre>  
   struct berval **servercredp, int freeit );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_parse_sals_bind_result() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_parse_sals_bind_result() Function Parameters"
Line 8,732: Line 7,776:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values, which indicates the result of parsing the server’s response:
 


One of the following values, which indicates the result of parsing the server’s response:
*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
*LDAP_PARAM_ERROR if any of the arguments are invalid.  
*LDAP_PARAM_ERROR if any of the arguments are invalid.  
*LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded message.  
*LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded message.  
*LDAP_NOT_SUPPORTED 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.  
*LDAP_NOT_SUPPORTED 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.


After you call the ldap_sasl_bind() function and the ldap_result() function, you can pass the results to ldap_parse_sasl_bind_result() for parsing. This function gets the following data from the server‚Äö√Ñ√¥s response:  
After you call the ldap_sasl_bind() function and the ldap_result() function, you can pass the results to ldap_parse_sasl_bind_result() for parsing. This function gets the following data from the server‚Äö√Ñ√¥s response:  
*The challenge or credentials sent back from the server are passed back in the berval structure as the <tt>servercredp</tt> argument.  
*The challenge or credentials sent back from the server are passed back in the berval structure as the <tt>servercredp</tt> argument.  
*The LDAP result code for the SASL bind operation is placed in the <tt>ld</tt> structure. You can get the result code by calling the ldap_get_lderrno() function. (If the result code is LDAP_SASL_BIND_IN_PROGRESS , you can call ldap_sasl_bind() again to send a response to the server‚Äö√Ñ√¥s challenge and call ldap_result() and ldap_parse_sasl_bind_result() again to get the next challenge from the server. For a list of possible result codes for an LDAP SASL bind operation, see ldap_sasl_bind().  
*The LDAP result code for the SASL bind operation is placed in the <tt>ld</tt> structure. You can get the result code by calling the ldap_get_lderrno() function. (If the result code is LDAP_SASL_BIND_IN_PROGRESS , you can call ldap_sasl_bind() again to send a response to the server’s challenge and call ldap_result() and ldap_parse_sasl_bind_result() again to get the next challenge from the server. For a list of possible result codes for an LDAP SASL bind operation, see ldap_sasl_bind().


'''Note:''' The LDAP server must support authentication through SASL mechanisms. Directory Server supports a plug-in interface that you can use to add SASL support to the server.  
'''Note:''' The LDAP server must support authentication through SASL mechanisms. Directory Server supports a plug-in interface that you can use to add SASL support to the server.  


<br> '''See Also'''


'''See Also'''
<br> ldap_sasl_bind(), ldap_get_lderrno  
 
 
ldap_sasl_bind(), ldap_get_lderrno  


=== ldap_parse_sort_control()  ===
=== ldap_parse_sort_control()  ===
Line 8,760: Line 7,802:
int ldap_parse_sort_control( LDAP *ld, LDAPControl **ctrls,
int ldap_parse_sort_control( LDAP *ld, LDAPControl **ctrls,
   unsigned long *result, char **attribute );</pre>  
   unsigned long *result, char **attribute );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_parse_sort_control() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_parse_sort_control() Function Parameters"
Line 8,783: Line 7,825:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values, which indicates the result of parsing the server’s response:
 


One of the following values, which indicates the result of parsing the server’s response:
*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
*LDAP_PARAM_ERROR if any of the arguments are invalid.  
*LDAP_PARAM_ERROR if any of the arguments are invalid.  
*LDAP_NO_MEMORY if memory cannot be allocated to decode the control returned by the server.  
*LDAP_NO_MEMORY if memory cannot be allocated to decode the control returned by the server.  
*LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded message.  
*LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded message.  
*LDAP_CONTROL_NOT_FOUND if no control can be found in the response returned from the server.
*LDAP_CONTROL_NOT_FOUND if no control can be found in the response returned from the server.
 
 
'''Description'''
 
 
Call the ldap_parse_sort_control() function as part of the process of retrieving sorted search results from a server. First, though, call ldap_result() to get the results, and ldap_parse_result() to parse the server controls from the results.  


<br> '''Description'''


'''See Also'''
<br> Call the ldap_parse_sort_control() function as part of the process of retrieving sorted search results from a server. First, though, call ldap_result() to get the results, and ldap_parse_result() to parse the server controls from the results.


<br> '''See Also'''


ldap_create_sort_control()  
<br> ldap_create_sort_control()  


=== ldap_parse_userstatus_control()  ===
=== ldap_parse_userstatus_control()  ===
Line 8,810: Line 7,847:
The ldap_parse_userstatus_control() 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 ldap_create_userstatus_control(). The ldap_parse_userstatus_control() function populates an LDAPuserstatus structure.  
The ldap_parse_userstatus_control() 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 ldap_create_userstatus_control(). The ldap_parse_userstatus_control() function populates an LDAPuserstatus structure.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
LDAP_API(int) LDAP_CALL ldap_parse_userstatus_control( LDAP *ld,
LDAP_API(int) LDAP_CALL ldap_parse_userstatus_control( LDAP *ld,
   LDAPControl **ctrlp, LDAPuserstatus *us );</pre>  
   LDAPControl **ctrlp, LDAPuserstatus *us );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_parse_userstatus_control() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_parse_userstatus_control() Function Parameters"
Line 8,836: Line 7,871:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:
 


One of the following values:
*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
*LDAP_PARAM_ERROR if any of the arguments are invalid.  
*LDAP_PARAM_ERROR if any of the arguments are invalid.  
Line 8,846: Line 7,880:
*LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded message.  
*LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded message.  
*LDAP_CONTROL_NOT_FOUND if no control can be found in the response returned from the server.  
*LDAP_CONTROL_NOT_FOUND if no control can be found in the response returned from the server.  
*LDAP_NOT_SUPPORTED 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.  
*LDAP_NOT_SUPPORTED 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.
 
 
'''See Also'''


<br> '''See Also'''


ldap_create_userstatus_control(), LDAPuserstatus()  
<br> ldap_create_userstatus_control(), LDAPuserstatus()  


=== ldap_parse_whoami()  ===
=== ldap_parse_whoami()  ===
Line 8,858: Line 7,890:
The ldap_parse_whoami() function retrieves the authorization identity from the result of an asynchronous Who am I? extended operation request.  
The ldap_parse_whoami() function retrieves the authorization identity from the result of an asynchronous Who am I? extended operation request.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
LDAP_API(int) LDAP_CALL ldap_parse_whoami_result( LDAP *ld,
LDAP_API(int) LDAP_CALL ldap_parse_whoami_result( LDAP *ld,
   LDAPMessage *result, char **authzid );</pre>  
   LDAPMessage *result, char **authzid );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_parse_whoami() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_parse_whoami() Function Parameters"
Line 8,884: Line 7,914:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:
 


One of the following values:
*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
*LDAP_PARAM_ERROR if any of the arguments are invalid.  
*LDAP_PARAM_ERROR if any of the arguments are invalid.  
*LDAP_NO_MEMORY if memory cannot be allocated for the authorization identity.  
*LDAP_NO_MEMORY if memory cannot be allocated for the authorization identity.  
*LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded message.  
*LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded message.  
*LDAP_NOT_SUPPORTED 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.  
*LDAP_NOT_SUPPORTED 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.


=== ldap_parse_whoami_result()  ===
=== ldap_parse_whoami_result()  ===
Line 8,899: Line 7,928:
The ldap_parse_whoami_result() function retrieves the authorization identity from the result of an asynchronous Who am I? extended operation request.  
The ldap_parse_whoami_result() function retrieves the authorization identity from the result of an asynchronous Who am I? extended operation request.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
LDAP_API(int) LDAP_CALL ldap_parse_whoami_result( LDAP *ld, int *msgidp,
LDAP_API(int) LDAP_CALL ldap_parse_whoami_result( LDAP *ld, int *msgidp,
   struct timeval *timeout, char **authzid );</pre>  
   struct timeval *timeout, char **authzid );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_parse_whoami_result() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_parse_whoami_result() Function Parameters"
Line 8,928: Line 7,955:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:
 


One of the following values:
*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
*LDAP_PARAM_ERROR if any of the arguments are invalid.  
*LDAP_PARAM_ERROR if any of the arguments are invalid.  
*LDAP_NO_MEMORY if memory cannot be allocated for the authorization identity.  
*LDAP_NO_MEMORY if memory cannot be allocated for the authorization identity.  
*LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded message.  
*LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded message.  
*LDAP_NOT_SUPPORTED 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.  
*LDAP_NOT_SUPPORTED 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.


=== ldap_parse_virtuallist_control()  ===
=== ldap_parse_virtuallist_control()  ===
Line 8,943: Line 7,969:
The ldap_parse_virtuallist_control() function parses the result returned from a search operation that used a server control for virtual list views. '''Note:''' This function implements an extension to the LDAP v3. A ''virtual'' list view''is an optional LDAP server feature that may not be supported'' on all LDAP servers.  
The ldap_parse_virtuallist_control() function parses the result returned from a search operation that used a server control for virtual list views. '''Note:''' This function implements an extension to the LDAP v3. A ''virtual'' list view''is an optional LDAP server feature that may not be supported'' on all LDAP servers.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
int ldap_parse_virtuallist_control( LDAP *ld,
int ldap_parse_virtuallist_control( LDAP *ld,
   LDAPControl **ctrls, unsigned long *target_posp,
   LDAPControl **ctrls, unsigned long *target_posp,
   unsigned long *list_sizep, int *errcodep );</pre>  
   unsigned long *list_sizep, int *errcodep );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_parse_virtuallist_control() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_parse_virtuallist_control() Function Parameters"
Line 8,976: Line 8,000:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:
 


One of the following values:
*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
*LDAP_PARAM_ERROR if any of the arguments are invalid.  
*LDAP_PARAM_ERROR if any of the arguments are invalid.  
Line 8,986: Line 8,009:
*LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded message.  
*LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded message.  
*LDAP_CONTROL_NOT_FOUND if no control can be found in the response returned from the server.  
*LDAP_CONTROL_NOT_FOUND if no control can be found in the response returned from the server.  
*LDAP_NOT_SUPPORTED 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.  
*LDAP_NOT_SUPPORTED 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.
 


'''Description'''
<br> '''Description'''  


<br> The ldap_parse_virtuallist_control() function can be called:


The ldap_parse_virtuallist_control() function can be called:
*As part of the process of retrieving a subset of entries from a list when working with a virtual list view box.  
*As part of the process of retrieving a subset of entries from a list when working with a virtual list view box.  
*After, calling ldap_result() to get the results, and ldap_parse_result() to parse the server controls from the results.  
*After, calling ldap_result() to get the results, and ldap_parse_result() to parse the server controls from the results.
 
 
'''See Also'''


<br> '''See Also'''


ldap_create_virtuallist_control()  
<br> ldap_create_virtuallist_control()  


=== ldap_passwd()  ===
=== ldap_passwd()  ===
Line 9,006: Line 8,026:
The ldap_passwd() asynchronous function allows you to perform an LDAP Password Modify extended operation, as defined in RFC 3062.  
The ldap_passwd() asynchronous function allows you to perform an LDAP Password Modify extended operation, as defined in RFC 3062.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
int ldap_passwd( LDAP *ld, struct berval *userid,
int ldap_passwd( LDAP *ld, struct berval *userid,
Line 9,014: Line 8,032:
   LDAPControl **serverctrls, LDAPControl **clientctrls,
   LDAPControl **serverctrls, LDAPControl **clientctrls,
   int *msgidp );</pre>  
   int *msgidp );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_passwd() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_passwd() Function Parameters"
Line 9,046: Line 8,064:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:  
 
 
One of the following values:  


*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
Line 9,063: Line 8,079:
The ldap_passwd_s() synchronous function allows you to perform an LDAP Password Modify extended operation, as defined in RFC 3062.  
The ldap_passwd_s() synchronous function allows you to perform an LDAP Password Modify extended operation, as defined in RFC 3062.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
int ldap_passwd_s( LDAP *ld, struct berval *userid,
int ldap_passwd_s( LDAP *ld, struct berval *userid,
Line 9,071: Line 8,085:
   struct berval *genpasswd, LDAPControl **serverctrls,
   struct berval *genpasswd, LDAPControl **serverctrls,
   LDAPControl **clientctrls );</pre>  
   LDAPControl **clientctrls );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_passwd() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_passwd() Function Parameters"
Line 9,103: Line 8,117:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:
 


One of the following values:
*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
*LDAP_PARAM_ERROR if an invalid parameter was passed to the function.  
*LDAP_PARAM_ERROR if an invalid parameter was passed to the function.  
Line 9,113: Line 8,126:
*LDAP_ENCODING_ERROR if an error occurred when BER-encoding the control.  
*LDAP_ENCODING_ERROR if an error occurred when BER-encoding the control.  
*LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.  
*LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.  
*LDAP_NOT_SUPPORTED 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.  
*LDAP_NOT_SUPPORTED 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.


=== ldap_perror()  ===
=== ldap_perror()  ===
<pre>#include &lt;ldap-deprecated.h&gt;
<pre>#include &lt;ldap-deprecated.h&gt;
void ldap_perror( LDAP *ld, const char *s );</pre>  
void ldap_perror( LDAP *ld, const char *s );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_perror() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_perror() Function Parameters"
Line 9,135: Line 8,148:
|}
|}


<br> '''Description'''


'''Description'''
<br> Use the newer version of this function, ldap_get_lderrno() .  
 
 
Use the newer version of this function, ldap_get_lderrno() .  
 
 
'''Example'''


<br> '''Example'''


The following example prints out an error message if the search operation cannot complete successfully.  
<br> The following example prints out an error message if the search operation cannot complete successfully.  
<pre>...
<pre>...
if ( ldap_search_s( ld, my_searchbase, LDAP_SCOPE_SUBTREE, my_filter,
if ( ldap_search_s( ld, my_searchbase, LDAP_SCOPE_SUBTREE, my_filter,
Line 9,153: Line 8,162:
}
}
...</pre>  
...</pre>  
'''See Also'''


'''See Also'''
<br> ldap_get_lderrno(), ldap_err2string(), ldap_result2error(), ldap_set_lderrno()  
 
 
ldap_get_lderrno(), ldap_err2string(), ldap_result2error(), ldap_set_lderrno()  


=== ldap_rename()  ===
=== ldap_rename()  ===
Line 9,165: Line 8,172:
'''Note:''' ldap_rename() is a new version of the ldap_modrdn2() function. If you are writing a new LDAP client, you should call ldap_rename().  
'''Note:''' ldap_rename() is a new version of the ldap_modrdn2() function. If you are writing a new LDAP client, you should call ldap_rename().  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
int ldap_rename( LDAP *ld, const char *dn, const char *newrdn,
int ldap_rename( LDAP *ld, const char *dn, const char *newrdn,
Line 9,173: Line 8,178:
   LDAPControl **serverctrls, LDAPControl **clientctrls,
   LDAPControl **serverctrls, LDAPControl **clientctrls,
   int *msgidp );</pre>  
   int *msgidp );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_rename() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_rename() Function Parameters"
Line 9,208: Line 8,213:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:
 


One of the following values:
*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
*LDAP_PARAM_ERROR if any of the arguments are invalid.  
*LDAP_PARAM_ERROR if any of the arguments are invalid.  
Line 9,218: Line 8,222:
*LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request.  
*LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request.  
*LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.  
*LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.  
*LDAP_NOT_SUPPORTED 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.
*LDAP_NOT_SUPPORTED 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.
 
 
'''Description'''
 
 
The ldap_rename() 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. ldap_rename() 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 ldap_result() function and the ldap_parse_result() function. If you want the results to be returned directly by the function, call the synchronous function ldap_rename_s() instead.  


<br> '''Description'''


'''See Also'''
<br> The ldap_rename() 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. ldap_rename() 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 ldap_result() function and the ldap_parse_result() function. If you want the results to be returned directly by the function, call the synchronous function ldap_rename_s() instead.


<br> '''See Also'''


ldap_rename_s(), ldap_result(), ldap_parse_result()  
<br> ldap_rename_s(), ldap_result(), ldap_parse_result()  


=== ldap_rename_s()  ===
=== ldap_rename_s()  ===
Line 9,239: Line 8,239:
   const char *newparent, int deleteoldrdn,
   const char *newparent, int deleteoldrdn,
   LDAPControl **serverctrls, LDAPControl **clientctrls );</pre>  
   LDAPControl **serverctrls, LDAPControl **clientctrls );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_rename() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_rename() Function Parameters"
Line 9,271: Line 8,271:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:
 


One of the following values:
*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
*LDAP_PARAM_ERROR if any of the arguments are invalid.  
*LDAP_PARAM_ERROR if any of the arguments are invalid.  
Line 9,283: Line 8,282:
*LDAP_LOCAL_ERROR if an error occurred when receiving the results from the server.  
*LDAP_LOCAL_ERROR if an error occurred when receiving the results from the server.  
*LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded results from the server.  
*LDAP_DECODING_ERROR if an error occurred when decoding the BER-encoded results from the server.  
*LDAP_NOT_SUPPORTED 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.  
*LDAP_NOT_SUPPORTED 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.


'''Note:''' Directory Server 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.  
'''Note:''' Directory Server 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.  


<br> '''Description'''


'''Description'''
<br> The ldap_rename_s() 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 ldap_rename_s() 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 ldap_rename().  
 
 
The ldap_rename_s() 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 ldap_rename_s() 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 ldap_rename().  
 
 
'''See Also'''


<br> '''See Also'''


ldap_rename()  
<br> ldap_rename()  


=== ldap_result()  ===
=== ldap_result()  ===
Line 9,303: Line 8,298:
The function ldap_result() waits for and returns the result of an LDAP operation initiated by one of the asynchronous LDAP API functions.  
The function ldap_result() waits for and returns the result of an LDAP operation initiated by one of the asynchronous LDAP API functions.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
int ldap_result( LDAP *ld, int msgid, int all,
int ldap_result( LDAP *ld, int msgid, int all,
   struct timeval *timeout, LDAPMessage **result );</pre>  
   struct timeval *timeout, LDAPMessage **result );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_result() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_result() Function Parameters"
Line 9,338: Line 8,331:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:
 


One of the following values:
*<tt>LDAP_RES_BIND</tt> indicates that the LDAPMessage structure contains the result of an LDAP bind operation.  
*<tt>LDAP_RES_BIND</tt> indicates that the LDAPMessage structure contains the result of an LDAP bind operation.  
*<tt>LDAP_RES_SEARCH_ENTRY</tt> indicates that the LDAPMessage structure contains an entry found during an LDAP search operation.  
*<tt>LDAP_RES_SEARCH_ENTRY</tt> indicates that the LDAPMessage structure contains an entry found during an LDAP search operation.  
Line 9,354: Line 8,346:
*<tt>LDAP_RES_EXTENDED</tt> indicates that the LDAPMessage structure contains the result of an LDAP v3 extended operation.  
*<tt>LDAP_RES_EXTENDED</tt> indicates that the LDAPMessage structure contains the result of an LDAP v3 extended operation.  
*<tt>-1</tt> indicates that an error occurred. The error code is set in the LDAP structure. To get the error code, call the ldap_get_lderrno() function.  
*<tt>-1</tt> indicates that an error occurred. The error code is set in the LDAP structure. To get the error code, call the ldap_get_lderrno() function.  
*<tt>0</tt> indicates that the operation has timed out.  
*<tt>0</tt> indicates that the operation has timed out.


<br> '''See Also'''


'''See Also'''
<br> ldap_add_ext(), ldap_compare_ext() , ldap_delete_ext(), ldap_modify_ext(), ldap_rename(), ldap_simple_bind(), ldap_url_search()


 
=== ldap_result2error()  ===
ldap_add_ext(), ldap_compare_ext() , ldap_delete_ext(), ldap_modify_ext(), ldap_rename(), ldap_simple_bind(), ldap_url_search()
 
=== ldap_result2error()  ===
<pre>#include &lt;ldap-deprecated.h&gt;
<pre>#include &lt;ldap-deprecated.h&gt;
int ldap_result2error( LDAP *ld, LDAPMessage *r, int freeit );</pre>  
int ldap_result2error( LDAP *ld, LDAPMessage *r, int freeit );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_result2error() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_result2error() Function Parameters"
Line 9,388: Line 8,378:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:  
 
 
One of the following values:  


*If successful, sets the error code and other error information in the LDAP structure and returns the error code.  
*If successful, sets the error code and other error information in the LDAP structure and returns the error code.  
*If unsuccessful, returns LDAP_PARAM_ERROR.
*If unsuccessful, returns LDAP_PARAM_ERROR.


<br> '''Example'''


'''Example'''
<br> See ldap_result().  
 
 
See ldap_result().  
 
 
'''See Also'''


<br> '''See Also'''


ldap_parse_result(), ldap_get_lderrno(), ldap_err2string(), ldap_result(), ldap_set_lderrno  
<br> ldap_parse_result(), ldap_get_lderrno(), ldap_err2string(), ldap_result(), ldap_set_lderrno  


=== ldap_sasl_bind()  ===
=== ldap_sasl_bind()  ===
Line 9,415: Line 8,399:
'''Note:''' The LDAP server must support authentication through SASL. Directory Server supports a server plug-in interface that you can use to add SASL support to the server.  
'''Note:''' The LDAP server must support authentication through SASL. Directory Server supports a server plug-in interface that you can use to add SASL support to the server.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
int ldap_sasl_bind( LDAP *ld, const char *dn,
int ldap_sasl_bind( LDAP *ld, const char *dn,
Line 9,423: Line 8,405:
   LDAPControl **serverctrls, LDAPControl **clientctrls,
   LDAPControl **serverctrls, LDAPControl **clientctrls,
   int *msgidp );</pre>  
   int *msgidp );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_sasl_bind() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_sasl_bind() Function Parameters"
Line 9,455: Line 8,437:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:
 


One of the following values:
*LDAP_SUCCESS if the SASL bind request was sent successfully.  
*LDAP_SUCCESS if the SASL bind request was sent successfully.  
*LDAP_PARAM_ERROR if an invalid parameter was passed to the function.  
*LDAP_PARAM_ERROR if an invalid parameter was passed to the function.  
Line 9,465: Line 8,446:
*LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request to send to the server.  
*LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request to send to the server.  
*LDAP_NO_MEMORY if memory cannot be allocated.  
*LDAP_NO_MEMORY if memory cannot be allocated.  
*LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.
*LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.
 
 
'''Description'''
 
 
The ldap_sasl_bind() function authenticates your client to an LDAP server by using a specified SASL mechanism. ldap_sasl_bind() 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 ldap_sasl_bind_s(). In order to get the results of the LDAP SASL bind operation, call the ldap_result(), the ldap_parse_sasl_bind_result(), and the ldap_get_lderrno() functions.  


<br> '''Description'''


'''See Also'''
<br> The ldap_sasl_bind() function authenticates your client to an LDAP server by using a specified SASL mechanism. ldap_sasl_bind() 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 ldap_sasl_bind_s(). In order to get the results of the LDAP SASL bind operation, call the ldap_result(), the ldap_parse_sasl_bind_result(), and the ldap_get_lderrno() functions.


<br> '''See Also'''


ldap_result(), ldap_parse_sasl_bind_result() , ldap_get_lderrno(), ldap_sasl_bind_s()  
<br> ldap_result(), ldap_parse_sasl_bind_result() , ldap_get_lderrno(), ldap_sasl_bind_s()  


=== ldap_sasl_bind_s()  ===
=== ldap_sasl_bind_s()  ===
Line 9,487: Line 8,464:
   LDAPControl **serverctrls, LDAPControl **clientctrls,
   LDAPControl **serverctrls, LDAPControl **clientctrls,
   struct berval **servercredp );</pre>  
   struct berval **servercredp );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_sasl_bind_s() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_sasl_bind_s() Function Parameters"
Line 9,519: Line 8,496:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:
 


One of the following values:
*LDAP_SUCCESS if the SASL bind request was sent successfully.  
*LDAP_SUCCESS if the SASL bind request was sent successfully.  
*LDAP_PARAM_ERROR if an invalid parameter was passed to the function.  
*LDAP_PARAM_ERROR if an invalid parameter was passed to the function.  
Line 9,531: Line 8,507:
*LDAP_NO_MEMORY if memory cannot be allocated.  
*LDAP_NO_MEMORY if memory cannot be allocated.  
*LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.  
*LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.  
*LDAP_LOCAL_ERROR if an error occurred when receiving the results from the server.  
*LDAP_LOCAL_ERROR if an error occurred when receiving the results from the server.


'''Note:''' Directory Server 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.  
'''Note:''' Directory Server 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.  


<br> '''Description'''


'''Description'''
<br> The ldap_sasl_bind_s() 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 ldap_sasl_bind(). After authenticating a client through SASL, an LDAP server can return a set of credentials in the results. The <tt>servercredp</tt> argument points to this value.  
 
 
The ldap_sasl_bind_s() 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 ldap_sasl_bind(). After authenticating a client through SASL, an LDAP server can return a set of credentials in the results. The <tt>servercredp</tt> argument points to this value.  
 
 
'''See Also'''


<br> '''See Also'''


ldap_sasl_bind()  
<br> ldap_sasl_bind()  


=== ldap_search()  ===
=== ldap_search()  ===
Line 9,553: Line 8,525:
int ldap_search( LDAP *ld, const char *base, int scope,
int ldap_search( LDAP *ld, const char *base, int scope,
   const char* filter, char **attrs, int attrsonly );</pre>  
   const char* filter, char **attrs, int attrsonly );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_search() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_search() Function Parameters"
Line 9,589: Line 8,561:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> Returns the message ID of the ldap_search() operation.  
 
 
Returns the message ID of the ldap_search() operation.  


'''Note:''' To check the result of this operation, call ldap_result and ldap_result2error().  
'''Note:''' To check the result of this operation, call ldap_result and ldap_result2error().  
Line 9,599: Line 8,569:
See ldap_search_ext_s() for a list of possible result codes.  
See ldap_search_ext_s() for a list of possible result codes.  


<br> '''Description'''


'''Description'''
<br> Please use the newer version of this function, ldap_search_ext() .  
 
 
Please use the newer version of this function, ldap_search_ext() .  
 
 
'''Example'''


<br> '''Example'''


The following example searches a directory.  
<br> The following example searches a directory.  


<br>  
<br>  
Line 9,723: Line 8,689:
     global_counter++;
     global_counter++;
}</pre>  
}</pre>  
'''See Also'''


'''See Also'''
<br> ldap_search_ext()  
 
 
ldap_search_ext()  


=== ldap_search_ext()  ===
=== ldap_search_ext()  ===
Line 9,737: Line 8,701:
   LDAPControl **serverctrls, LDAPControl **clientctrls,
   LDAPControl **serverctrls, LDAPControl **clientctrls,
   struct timeval *timeoutp, int sizelimit, int *msgidp );</pre>  
   struct timeval *timeoutp, int sizelimit, int *msgidp );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_search_ext() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_search_ext() Function Parameters"
Line 9,788: Line 8,752:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:
 


One of the following values:
*LDAP_SUCCESS if the SASL bind request was sent successfully.  
*LDAP_SUCCESS if the SASL bind request was sent successfully.  
*LDAP_PARAM_ERROR if an invalid parameter was passed to the function.  
*LDAP_PARAM_ERROR if an invalid parameter was passed to the function.  
Line 9,798: Line 8,761:
*LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request to send to the server.  
*LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request to send to the server.  
*LDAP_NO_MEMORY if memory cannot be allocated.  
*LDAP_NO_MEMORY if memory cannot be allocated.  
*LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.
*LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.
 
 
'''Description'''
 
 
The ldap_search_ext() function searches the directory for matching entries. ldap_search_ext() 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 ldap_search_ext_s() . 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 ldap_create_sort_control() and ldap_create_persistentsearch_control() for more information.) In order to get the results of the ldap_search_ext() operation, you need to call the ldap_result() and the ldap_parse_result() functions.  


<br> '''Description'''


'''See Also'''
<br> The ldap_search_ext() function searches the directory for matching entries. ldap_search_ext() 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 ldap_search_ext_s() . 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 ldap_create_sort_control() and ldap_create_persistentsearch_control() for more information.) In order to get the results of the ldap_search_ext() operation, you need to call the ldap_result() and the ldap_parse_result() functions.


<br> '''See Also'''


ldap_search_ext_s(), ldap_result(), ldap_parse_result()  
<br> ldap_search_ext_s(), ldap_result(), ldap_parse_result()  


=== ldap_search_ext_s()  ===
=== ldap_search_ext_s()  ===
Line 9,818: Line 8,777:
'''Note:''' ldap_search_ext_s() is a new version of the ldap_search_s() function. If you are writing a new LDAP client, you should call ldap_search_ext_s().  
'''Note:''' ldap_search_ext_s() is a new version of the ldap_search_s() function. If you are writing a new LDAP client, you should call ldap_search_ext_s().  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
int ldap_search_ext_s( LDAP *ld, const char *base, int scope,
int ldap_search_ext_s( LDAP *ld, const char *base, int scope,
Line 9,826: Line 8,783:
   LDAPControl **serverctrls, LDAPControl **clientctrls,
   LDAPControl **serverctrls, LDAPControl **clientctrls,
   struct timeval *timeoutp, int sizelimit, LDAPMessage **res );</pre>  
   struct timeval *timeoutp, int sizelimit, LDAPMessage **res );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_search_ext_s() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_search_ext_s() Function Parameters"
Line 9,877: Line 8,834:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:
 


One of the following values:
*LDAP_SUCCESS if the SASL bind request was sent successfully.  
*LDAP_SUCCESS if the SASL bind request was sent successfully.  
*LDAP_PARAM_ERROR if an invalid parameter was passed to the function.  
*LDAP_PARAM_ERROR if an invalid parameter was passed to the function.  
Line 9,891: Line 8,847:
*LDAP_NO_MEMORY if memory cannot be allocated.  
*LDAP_NO_MEMORY if memory cannot be allocated.  
*LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.  
*LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.  
*LDAP_LOCAL_ERROR if an error occurred when receiving the results from the server.  
*LDAP_LOCAL_ERROR if an error occurred when receiving the results from the server.


The ldap_search_ext_s() searches the directory for matching entries. The function ldap_search_ext_s() 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 ldap_search_ext(). You can also use &lt;function&gt; ldap_search_ext_s&lt;/function&gt; 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 ldap_create_sort_control() and ldap_create_persistentsearch_control() for more information.)  
The ldap_search_ext_s() searches the directory for matching entries. The function ldap_search_ext_s() 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 ldap_search_ext(). You can also use &lt;function&gt; ldap_search_ext_s&lt;/function&gt; 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 ldap_create_sort_control() and ldap_create_persistentsearch_control() for more information.)  


<br> '''See Also'''


'''See Also'''
<br> ldap_search_ext()  
 
 
ldap_search_ext()  


=== ldap_search_s()  ===
=== ldap_search_s()  ===
Line 9,905: Line 8,859:
The ldap_search_s() function searches the directory synchronously. '''Note:''' This is an older function that is included in the SDK for backward-compatibility. If you are writing a new LDAP client, use ldap_search_ext_s() instead.  
The ldap_search_s() function searches the directory synchronously. '''Note:''' This is an older function that is included in the SDK for backward-compatibility. If you are writing a new LDAP client, use ldap_search_ext_s() instead.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
int ldap_search_s( LDAP *ld, const char *base, int scope,
int ldap_search_s( LDAP *ld, const char *base, int scope,
   const char* filter, char **attrs, int attrsonly,
   const char* filter, char **attrs, int attrsonly,
   LDAPMessage **res );</pre>  
   LDAPMessage **res );</pre>  
'''Parameters'''


'''Parameters'''
<br> This function has the parameters listed in ldap_search_s() .  
 
 
This function has the parameters listed in ldap_search_s() .  


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_search_s() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_search_s() Function Parameters"
Line 9,953: Line 8,903:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> For a list of possible result codes for an LDAP search operation, see ldap_search_ext_s().


<br> '''Description'''


For a list of possible result codes for an LDAP search operation, see ldap_search_ext_s().  
<br> Use the newer version of this function, ldap_search_ext_s() .  


<br> '''Example'''


'''Description'''
<br> The following example searches the directory for all people whose surname (last name) is <tt>Jensen</tt>.  
 
<pre>#include "examples.h"
 
Use the newer version of this function, ldap_search_ext_s() .
 
 
'''Example'''
 
 
The following example searches the directory for all people whose surname (last name) is <tt>Jensen</tt>.  
<pre>#include "examples.h"


int main( int argc, char **argv )
int main( int argc, char **argv )
Line 10,022: Line 8,966:
   return( 0 );
   return( 0 );
}</pre>  
}</pre>  
'''See Also'''


'''See Also'''
<br> ldap_search_ext_s()  
 
 
ldap_search_ext_s()  


=== ldap_search_st()  ===
=== ldap_search_st()  ===
Line 10,035: Line 8,977:
   const char* filter, char **attrs, int attrsonly,
   const char* filter, char **attrs, int attrsonly,
   struct timeval *timeout, LDAPMessage **res );</pre>  
   struct timeval *timeout, LDAPMessage **res );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_search_st() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_search_st() Function Parameters"
Line 10,077: Line 9,019:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> For a list of possible result codes for an LDAP search operation, see ldap_search_ext_s().  
 
 
For a list of possible result codes for an LDAP search operation, see ldap_search_ext_s().
 
 
'''Description'''
 
 
Please use the newer version of this function, ldap_search_ext_s() .  


<br> '''Description'''


'''See Also'''
<br> Please use the newer version of this function, ldap_search_ext_s() .


<br> '''See Also'''


ldap_search_ext_s()  
<br> ldap_search_ext_s()  


=== ldap_set_filter_additions()  ===
=== ldap_set_filter_additions()  ===
Line 10,099: Line 9,035:
The ldap_set_filter_additions() function sets a prefix to be prepended and a suffix to be appended to all filters returned by the ldap_getfirstfilter() and ldap_getnextfilter() function calls.  
The ldap_set_filter_additions() function sets a prefix to be prepended and a suffix to be appended to all filters returned by the ldap_getfirstfilter() and ldap_getnextfilter() function calls.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
int ldap_set_filter_additions( LDAPFiltDesc *lfdp, char *prefix,
int ldap_set_filter_additions( LDAPFiltDesc *lfdp, char *prefix,
   char *suffix );</pre>  
   char *suffix );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_set_filter_additions() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_set_filter_additions() Function Parameters"
Line 10,125: Line 9,059:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:  
 
 
One of the following values:  


*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
*If unsuccessful, returns an LDAP error code.
*If unsuccessful, returns an LDAP error code.


<br> '''Example'''


'''Example'''
<br> The following example loads the filter configuration file named <tt>myfilters.conf</tt> into memory and adds the prefix <tt>"(&amp;(objectClass=person)"</tt> and the suffix <tt>")"</tt> to each filter retrieved.  
 
 
The following example loads the filter configuration file named <tt>myfilters.conf</tt> into memory and adds the prefix <tt>"(&amp;(objectClass=person)"</tt> and the suffix <tt>")"</tt> to each filter retrieved.  
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
...
...
Line 10,154: Line 9,084:
}
}
...</pre>  
...</pre>  
'''See Also'''


'''See Also'''
<br> ldap_getfirstfilter(), ldap_getnextfilter()  
 
 
ldap_getfirstfilter(), ldap_getnextfilter()  


=== ldap_setfilteraffixes()  ===
=== ldap_setfilteraffixes()  ===
Line 10,164: Line 9,092:
'''Note:''' This function is deprecated and should not be used. It is included in <tt>ldap-deprecated.h</tt> for backward-compatibility. Use ldap_set_filter_additions() instead.  
'''Note:''' This function is deprecated and should not be used. It is included in <tt>ldap-deprecated.h</tt> for backward-compatibility. Use ldap_set_filter_additions() instead.  


<br> '''See Also'''


'''See Also'''
<br> ldap_set_filter_additions()  
 
 
ldap_set_filter_additions()  


=== ldap_set_lderrno()  ===
=== ldap_set_lderrno()  ===
Line 10,174: Line 9,100:
The ldap_set_lderrno() function sets an error code and information about an error in an LDAP structure.  
The ldap_set_lderrno() function sets an error code and information about an error in an LDAP structure.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
int ldap_set_lderrno( LDAP *ld, int e, char *m, char *s );</pre>  
int ldap_set_lderrno( LDAP *ld, int e, char *m, char *s );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_set_lderrno() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_set_lderrno() Function Parameters"
Line 10,202: Line 9,126:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:  
 
 
One of the following values:  


*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
*If unsuccessful, returns an LDAP error code.
*If unsuccessful, returns an LDAP error code.


<br> '''Description'''


'''Description'''
<br> The ldap_set_lderrno() function sets an error code and information about an error in an LDAP structure. You can call this function to set error information that will be retrieved by subsequent ldap_get_lderrno() function calls.  
 
 
The ldap_set_lderrno() function sets an error code and information about an error in an LDAP structure. You can call this function to set error information that will be retrieved by subsequent ldap_get_lderrno() function calls.  
 
 
'''Example'''


<br> '''Example'''


The following example attempts to perform an operation. If the operation fails, the LDAP_PARAM_ERROR error code is placed in the LDAP structure.  
<br> The following example attempts to perform an operation. If the operation fails, the LDAP_PARAM_ERROR error code is placed in the LDAP structure.  
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
int rc;
int rc;
Line 10,234: Line 9,152:
}
}
...</pre>  
...</pre>  
'''See Also'''


'''See Also'''
<br> ldap_err2string(), ldap_perror, ldap_result2error()  
 
 
ldap_err2string(), ldap_perror, ldap_result2error()  


=== ldap_set_option()  ===
=== ldap_set_option()  ===
Line 10,244: Line 9,160:
The function ldap_set_option() sets session preferences in the LDAP structure.  
The function ldap_set_option() sets session preferences in the LDAP structure.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
int ldap_set_option( LDAP *ld, int option, const void *optdata );</pre>  
int ldap_set_option( LDAP *ld, int option, const void *optdata );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_set_option() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_set_option() Function Parameters"
Line 10,381: Line 9,295:
See also ldap_set_option() for details on <tt>LDAP_OPT_X_SASL*</tt> parameters.  
See also ldap_set_option() for details on <tt>LDAP_OPT_X_SASL*</tt> parameters.  


<br> '''Returns'''


'''Returns'''
<br> One of the following values:  
 
 
One of the following values:  


*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
*<tt>-1</tt> if unsuccessful.
*<tt>-1</tt> if unsuccessful.


 
<br> '''Example'''  
'''Example'''
 
<pre>#include &lt;stdio.h&gt;
<pre>#include &lt;stdio.h&gt;
#include &lt;ldap.h&gt;
#include &lt;ldap.h&gt;
Line 10,413: Line 9,323:
}
}
...</pre>  
...</pre>  
'''See Also'''


'''See Also'''
<br> ldap_init(), prldap_init() (IPv6), ldap_get_option()  
 
 
ldap_init(), prldap_init() (IPv6), ldap_get_option()


=== ldap_set_rebind_proc()  ===
=== ldap_set_rebind_proc()  ===
Line 10,423: Line 9,331:
The ldap_set_rebind_proc() function sets a ''rebind'', which is called by your client to obtain authentication credentials when following a referral.  
The ldap_set_rebind_proc() function sets a ''rebind'', which is called by your client to obtain authentication credentials when following a referral.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
void ldap_set_rebind_proc( LDAP *ld,
void ldap_set_rebind_proc( LDAP *ld,
   LDAP_REBINDPROC_CALLBACK *rebindproc, void *arg );</pre>  
   LDAP_REBINDPROC_CALLBACK *rebindproc, void *arg );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_set_rebind_proc() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_set_rebind_proc() Function Parameters"
Line 10,449: Line 9,355:
|}
|}


<br> '''Description'''


'''Description'''
<br> Call ldap_set_rebind_proc() 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 ldap_set_rebind_proc() or if you pass <tt>NULL</tt> for the <tt>rebindproc</tt> argument, your client authenticates anonymously when following referrals. The rebind function that you specify with ldap_set_rebind_proc() should have the following prototype:  
 
 
Call ldap_set_rebind_proc() 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 ldap_set_rebind_proc() or if you pass <tt>NULL</tt> for the <tt>rebindproc</tt> argument, your client authenticates anonymously when following referrals. The rebind function that you specify with ldap_set_rebind_proc() should have the following prototype:  
 
<pre>int LDAP_CALL LDAP_CALLBACK rebindproc( LDAP *ld, char **dnp,
<pre>int LDAP_CALL LDAP_CALLBACK rebindproc( LDAP *ld, char **dnp,
   char **passwdp, int *authmethodp, int freeit, void *arg );</pre>  
   char **passwdp, int *authmethodp, int freeit, void *arg );</pre>  
#The LDAP server sends a referral back to the client.  
#The LDAP server sends a referral back to the client.  
#The client calls the rebind function, passing <tt>0</tt> as the <tt>freeit</tt> argument.  
#The client calls the rebind function, passing <tt>0</tt> as the <tt>freeit</tt> argument.  
Line 10,466: Line 9,368:
#If successful, the rebind function returns LDAP_SUCCESS 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.)  
#If successful, the rebind function returns LDAP_SUCCESS 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.)  
#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.  
#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.  
#The client calls the rebind function again, passing <tt>1</tt> as the <tt>freeit</tt> argument.
#The client calls the rebind function again, passing <tt>1</tt> as the <tt>freeit</tt> argument.  
#The rebind function frees any memory allocated earlier to specify the DN and credentials.  
#The rebind function frees any memory allocated earlier to specify the DN and credentials.


You need to write a rebind function that does the following:  
You need to write a rebind function that does the following:  


*If <tt>freeit</tt> is <tt>0</tt>, set the following pointers:
*If <tt>freeit</tt> is <tt>0</tt>, set the following pointers:  
**Set <tt>dnp</tt> to point to the DN to be used for authentication.  
**Set <tt>dnp</tt> to point to the DN to be used for authentication.  
**Set <tt>passwdp</tt> to point to the credentials to be used for authentication.  
**Set <tt>passwdp</tt> to point to the credentials to be used for authentication.  
**Set <tt>authmethodp</tt> to point to the method of authentication used (for example, <tt>LDAP_AUTH_SIMPLE</tt>).  
**Set <tt>authmethodp</tt> to point to the method of authentication used (for example, <tt>LDAP_AUTH_SIMPLE</tt>).


You can also make use of the <tt>arg</tt> argument, which is a pointer to the argument specified in the ldap_set_rebind_proc() function. If successful, returns LDAP_SUCCESS. Otherwise, returns the appropriate LDAP error code. If <tt>freeit</tt> is <tt>1</tt>, free any memory that you allocated to create the DN and credentials.  
You can also make use of the <tt>arg</tt> argument, which is a pointer to the argument specified in the ldap_set_rebind_proc() function. If successful, returns LDAP_SUCCESS. Otherwise, returns the appropriate LDAP error code. If <tt>freeit</tt> is <tt>1</tt>, free any memory that you allocated to create the DN and credentials.  
Line 10,482: Line 9,384:
'''Note:''' In order to use the rebind function, the <tt>LDAP_OPT_REFERRALS</tt> option must be set to <tt>LDAP_OPT_ON</tt>, so that your client automatically follows referrals. This option is set to <tt>LDAP_OPT_ON</tt> by default.  
'''Note:''' In order to use the rebind function, the <tt>LDAP_OPT_REFERRALS</tt> option must be set to <tt>LDAP_OPT_ON</tt>, so that your client automatically follows referrals. This option is set to <tt>LDAP_OPT_ON</tt> by default.  


<br> '''Example'''


'''Example'''
<br> The following example demonstrates how to write and register a rebind function.  
 
 
The following example demonstrates how to write and register a rebind function.  
<pre>#include "ldap.h"
<pre>#include "ldap.h"
...
...
Line 10,565: Line 9,465:
   return LDAP_SUCCESS;
   return LDAP_SUCCESS;
}</pre>  
}</pre>  
'''See Also'''


'''See Also'''
<br> ldap_simple_bind(), ldap_simple_bind_s()  
 
 
ldap_simple_bind(), ldap_simple_bind_s()  


=== ldap_simple_bind()  ===
=== ldap_simple_bind()  ===
Line 10,575: Line 9,473:
The ldap_simple_bind() function synchronously authenticates your client to the LDAP server using a DN and a password.  
The ldap_simple_bind() function synchronously authenticates your client to the LDAP server using a DN and a password.  


 
<br> '''Syntax'''  
'''Syntax'''
<pre>#include &lt;ldap.h&gt;
 
<pre>#include &lt;ldap.h&gt;
int ldap_simple_bind(LDAP *ld, const char *who, const char *passwd);</pre>  
int ldap_simple_bind(LDAP *ld, const char *who, const char *passwd);</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_simple_bind() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_simple_bind() Function Parameters"
Line 10,600: Line 9,496:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> Returns the message ID of the ldap_simple_bind() operation. To check the result of this operation, call ldap_result() and ldap_result2error().  
 
 
Returns the message ID of the ldap_simple_bind() operation. To check the result of this operation, call ldap_result() and ldap_result2error().  
 
 
'''Description'''


<br> '''Description'''


The ldap_simple_bind() function authenticates to the LDAP server. It verifies that the password supplied for authentication matches the <tt>userPassword</tt> attribute of the given entry. &lt;function&gt; ldap_simple_bind&lt;/function&gt; 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 ldap_simple_bind_s().  
<br> The ldap_simple_bind() function authenticates to the LDAP server. It verifies that the password supplied for authentication matches the <tt>userPassword</tt> attribute of the given entry. &lt;function&gt; ldap_simple_bind&lt;/function&gt; 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 ldap_simple_bind_s().  


The following example calls ldap_simple_bind() to authenticate the user <tt>Barbara Jensen</tt> to the directory.  
The following example calls ldap_simple_bind() to authenticate the user <tt>Barbara Jensen</tt> to the directory.  
Line 10,659: Line 9,551:
}
}
...</pre>  
...</pre>  
'''See Also'''


'''See Also'''
<br> ldap_simple_bind_s()  
 
 
ldap_simple_bind_s()  


=== ldap_simple_bind_s()  ===
=== ldap_simple_bind_s()  ===
Line 10,669: Line 9,559:
The ldap_simple_bind() function synchronously authenticates your client to the LDAP server using a DN and a password.  
The ldap_simple_bind() function synchronously authenticates your client to the LDAP server using a DN and a password.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
int ldap_simple_bind_s( LDAP *ld, const char *who, const char *passwd );</pre>  
int ldap_simple_bind_s( LDAP *ld, const char *who, const char *passwd );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_simple_bind_s() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_simple_bind_s() Function Parameters"
Line 10,694: Line 9,582:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:  
 
 
One of the following values:  


*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
Line 10,707: Line 9,593:
*LDAP_NO_MEMORY if memory cannot be allocated.  
*LDAP_NO_MEMORY if memory cannot be allocated.  
*LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.  
*LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.  
*LDAP_LOCAL_ERROR if an error occurred when receiving the results from the server.  
*LDAP_LOCAL_ERROR if an error occurred when receiving the results from the server.


'''Note:''' Directory Server 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.  
'''Note:''' Directory Server 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.  


<br> '''Description'''


'''Description'''
<br> The ldap_simple_bind_s() function authenticates to the LDAP server. It verifies that the password supplied for authentication matches the <tt>userPassword</tt> attribute of the given entry. &lt;function&gt; ldap_simple_bind_s&lt;/function&gt; 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 ldap_simple_bind() instead.  
 
 
The ldap_simple_bind_s() function authenticates to the LDAP server. It verifies that the password supplied for authentication matches the <tt>userPassword</tt> attribute of the given entry. &lt;function&gt; ldap_simple_bind_s&lt;/function&gt; 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 ldap_simple_bind() instead.  


The following example uses the synchronous ldap_simple_bind_s() function to authenticate to the directory as the user <tt>Barbara Jensen</tt>.  
The following example uses the synchronous ldap_simple_bind_s() function to authenticate to the directory as the user <tt>Barbara Jensen</tt>.  
<pre>#include &lt;stdio.h&gt;
<pre>#include &lt;stdio.h&gt;
#include &lt;ldap.h&gt;
#include &lt;ldap.h&gt;
Line 10,739: Line 9,622:
}
}
...</pre>  
...</pre>  
'''See Also'''


'''See Also'''
<br> ldap_simple_bind()  
 
 
ldap_simple_bind()  


=== ldap_sort_entries()  ===
=== ldap_sort_entries()  ===
Line 10,749: Line 9,630:
The ldap_sort_entries() function sorts a chain of entries retrieved from an LDAP search call.  
The ldap_sort_entries() function sorts a chain of entries retrieved from an LDAP search call.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
int ldap_sort_entries( LDAP *ld, LDAPMessage *chain, char *attr,
int ldap_sort_entries( LDAP *ld, LDAPMessage *chain, char *attr,
   LDAP_CMP_CALLBACK *cmp );</pre>  
   LDAP_CMP_CALLBACK *cmp );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_sort_entries() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_sort_entries() Function Parameters"
Line 10,778: Line 9,657:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:  
 
 
One of the following values:  


*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
*If unsuccessful, returns a <tt>NULL</tt> and sets the appropriate error code in the LDAP structure. To get the error code, call ldap_get_lderrno().
*If unsuccessful, returns a <tt>NULL</tt> and sets the appropriate error code in the LDAP structure. To get the error code, call ldap_get_lderrno().
 
 
'''Description'''
 
 
The ldap_sort_entries() function sorts a chain of entries retrieved from an LDAP search call (ldap_search_s() or ldap_result()) either by DN or a specified attribute in the entries.  


<br> '''Description'''


'''Example'''
<br> The ldap_sort_entries() function sorts a chain of entries retrieved from an LDAP search call (ldap_search_s() or ldap_result()) either by DN or a specified attribute in the entries.


<br> '''Example'''


The following example sorts entries by the <tt>roomNumber</tt> attribute.  
<br> The following example sorts entries by the <tt>roomNumber</tt> attribute.  
<pre>#include &lt;stdio.h&gt;
<pre>#include &lt;stdio.h&gt;
#include &lt;string.h&gt;
#include &lt;string.h&gt;
Line 10,821: Line 9,694:
}
}
...</pre>  
...</pre>  
'''See Also'''


'''See Also'''
<br> ldap_multisort_entries(), ldap_result(), ldap_search_s(), LDAP_CMP_CALLBACK()  
 
 
ldap_multisort_entries(), ldap_result(), ldap_search_s(), LDAP_CMP_CALLBACK()  


=== ldap_start_tls_s()  ===
=== ldap_start_tls_s()  ===
Line 10,831: Line 9,702:
The ldap_start_tls_s() initiates a Start Transport Layer Security (TLS) operation as defined in RFC 4513. Before using this function, call ldapssl_client_init(), ldapssl_clientauth_init(), or ldapssl_advclientauth_init() to initialize use of the certificate database.  
The ldap_start_tls_s() initiates a Start Transport Layer Security (TLS) operation as defined in RFC 4513. Before using this function, call ldapssl_client_init(), ldapssl_clientauth_init(), or ldapssl_advclientauth_init() to initialize use of the certificate database.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap_ssl.h&gt;
<pre>#include &lt;ldap_ssl.h&gt;
int ldap_start_tls_s( LDAP *ld, LDAPControl **serverctrls,
int ldap_start_tls_s( LDAP *ld, LDAPControl **serverctrls,
   LDAPControl **clientctrls );</pre>  
   LDAPControl **clientctrls );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_start_tls_s() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_start_tls_s() Function Parameters"
Line 10,857: Line 9,726:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:  
 
 
One of the following values:  


*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
Line 10,873: Line 9,740:
The ldap_sort_strcasecmp() routine compares two strings and ignores any differences in case when comparing uppercase and lowercase characters.  
The ldap_sort_strcasecmp() routine compares two strings and ignores any differences in case when comparing uppercase and lowercase characters.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
int ldap_sort_strcasecmp( const char **a, const char **b );</pre>  
int ldap_sort_strcasecmp( const char **a, const char **b );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_sort_strcasecmp() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_sort_strcasecmp() Function Parameters"
Line 10,895: Line 9,760:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:  
 
 
One of the following values:  


*If <tt>a</tt> is greater than <tt>b</tt>, returns a value greater than <tt>0</tt>.  
*If <tt>a</tt> is greater than <tt>b</tt>, returns a value greater than <tt>0</tt>.  
*If <tt>a</tt> is equal to <tt>b</tt>, returns <tt>0</tt>.  
*If <tt>a</tt> is equal to <tt>b</tt>, returns <tt>0</tt>.  
*If <tt>a</tt> is less than <tt>b</tt>, returns a value less than <tt>0</tt>.  
*If <tt>a</tt> is less than <tt>b</tt>, returns a value less than <tt>0</tt>.
 
 
'''Description'''


<br> '''Description'''


The ldap_sort_strcasecmp() routine compares two strings and ignores any differences in case when comparing uppercase and lowercase characters. This function is similar to the C function strcasecmp(). When sorting attribute values with ldap_sort_strcasecmp(), call ldap_sort_strcasecmp() to compare the attribute values.  
<br> The ldap_sort_strcasecmp() routine compares two strings and ignores any differences in case when comparing uppercase and lowercase characters. This function is similar to the C function strcasecmp(). When sorting attribute values with ldap_sort_strcasecmp(), call ldap_sort_strcasecmp() to compare the attribute values.  


'''Note:''' This function works with ASCII values only. For UTF-8 data, the comparison result is unspecified.  
'''Note:''' This function works with ASCII values only. For UTF-8 data, the comparison result is unspecified.  


<br> '''See Also'''


'''See Also'''
<br> ldap_sort_strcasecmp(), LDAP_VALCMP_CALLBACK()  
 
 
ldap_sort_strcasecmp(), LDAP_VALCMP_CALLBACK()  


=== ldap_sort_values()  ===
=== ldap_sort_values()  ===
Line 10,923: Line 9,782:
The ldap_sort_values() function sorts an array of values retrieved from an ldap_get_values() call.  
The ldap_sort_values() function sorts an array of values retrieved from an ldap_get_values() call.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
int ldap_sort_values( LDAP *ld, char **vals,
int ldap_sort_values( LDAP *ld, char **vals,
   LDAP_VALCMP_CALLBACK cmp );</pre>  
   LDAP_VALCMP_CALLBACK cmp );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_sort_values() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_sort_values() Function Parameters"
Line 10,949: Line 9,806:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:  
 
 
One of the following values:  


*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
*If unsuccessful, returns an LDAP error code.
*If unsuccessful, returns an LDAP error code.


<br> '''Example'''


'''Example'''
<br> The following example sorts the values of attributes before printing them.  
 
 
The following example sorts the values of attributes before printing them.  
<pre>#include &lt;stdio.h&gt;
<pre>#include &lt;stdio.h&gt;
#include &lt;string.h&gt;
#include &lt;string.h&gt;
Line 10,990: Line 9,843:
}
}
...</pre>  
...</pre>  
'''See Also'''


'''See Also'''
<br> ldap_get_values(), ldap_sort_strcasecmp, LDAP_VALCMP_CALLBACK().  
 
 
ldap_get_values(), ldap_sort_strcasecmp, LDAP_VALCMP_CALLBACK().  


=== ldapssl_advclientauth_init()  ===
=== ldapssl_advclientauth_init()  ===
Line 11,000: Line 9,851:
The ldapssl_advclientauth_init() 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.  
The ldapssl_advclientauth_init() 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.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap_ssl.h&gt;
<pre>#include &lt;ldap_ssl.h&gt;
int LDAP_CALL ldapssl_advclientauth_init( char *certdbpath,
int LDAP_CALL ldapssl_advclientauth_init( char *certdbpath,
Line 11,008: Line 9,857:
   void *keydbhandle, int needsecmoddb, char *secmodpath,
   void *keydbhandle, int needsecmoddb, char *secmodpath,
   const int sslstrength);</pre>  
   const int sslstrength);</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldapssl_advclientauth_init() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldapssl_advclientauth_init() Function Parameters"
Line 11,050: Line 9,899:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:  
 
 
One of the following values:  


*<tt>0</tt> if successful.  
*<tt>0</tt> if successful.  
*<tt>-1</tt> if unsuccessful.
*<tt>-1</tt> if unsuccessful.


<br> '''Description'''


'''Description'''
<br> You can call ldapssl_advclientauth_init() to initialize your client application for SSL and certificate-based client authentication. This function is similar to ldapssl_clientauth_init() and allows you to:  
 
 
You can call ldapssl_advclientauth_init() to initialize your client application for SSL and certificate-based client authentication. This function is similar to ldapssl_clientauth_init() and allows you to:  


*Specify the name and path of a security module database.  
*Specify the name and path of a security module database.  
Line 11,070: Line 9,915:
'''Note:''' You must call ldapssl_advclientauth_init() before calling ldapssl_init() to connect to the server.  
'''Note:''' You must call ldapssl_advclientauth_init() before calling ldapssl_init() to connect to the server.  


<br> '''Example'''


'''Example'''
<br> The following example initializes a client before connecting with a secure LDAP server.  
 
 
The following example initializes a client before connecting with a secure LDAP server.  
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
#include &lt;ldap_ssl.h&gt;
#include &lt;ldap_ssl.h&gt;
Line 11,091: Line 9,934:
}
}
...</pre>  
...</pre>  
'''See Also'''


'''See Also'''
<br> ldap_init(), prldap_init() (IPv6), ldapssl_clientauth_init(), ldapssl_init(), ldapssl_install_routines()  
 
 
ldap_init(), prldap_init() (IPv6), ldapssl_clientauth_init(), ldapssl_init(), ldapssl_install_routines()  


=== ldapssl_client_init()  ===
=== ldapssl_client_init()  ===
Line 11,101: Line 9,942:
The ldapssl_client_init() 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.  
The ldapssl_client_init() 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.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap_ssl.h&gt;
<pre>#include &lt;ldap_ssl.h&gt;
int ldapssl_client_init( const char *certdbpath, void *certdbhandle );</pre>  
int ldapssl_client_init( const char *certdbpath, void *certdbhandle );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldapssl_client_init() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldapssl_client_init() Function Parameters"
Line 11,123: Line 9,962:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:  
 
 
One of the following values:  


*<tt>0</tt> if successful.  
*<tt>0</tt> if successful.  
*<tt>-1</tt> if unsuccessful.
*<tt>-1</tt> if unsuccessful.


<br> '''Description'''


'''Description'''
<br> You can call the ldapssl_client_init() function to initialize your client application for SSL. It is only called once and returns <tt>0</tt> if all goes well. If you plan to use certificate-based authentication, you should call either the ldapssl_clientauth_init() or the ldapssl_advclientauth_init() function.  
 
 
You can call the ldapssl_client_init() function to initialize your client application for SSL. It is only called once and returns <tt>0</tt> if all goes well. If you plan to use certificate-based authentication, you should call either the ldapssl_clientauth_init() or the ldapssl_advclientauth_init() function.  


The following example initializes a client before connecting with a secure LDAP server.  
The following example initializes a client before connecting with a secure LDAP server.  
<pre>#include &lt;ldap.h&gt;  
<pre>#include &lt;ldap.h&gt;  
#include &lt;ldap_ssl.h&gt;  
#include &lt;ldap_ssl.h&gt;  
Line 11,149: Line 9,983:
   return( 1 );
   return( 1 );
}</pre>  
}</pre>  
The certdbpath is a path to the file system directory containing the certificate database files. For example:  
The certdbpath is a path to the file system directory containing the certificate database files. For example:  
<pre>$ ls /local/client/alias/*.db
<pre>$ ls /local/client/alias/*.db
/local/client/alias/cert8.db
/local/client/alias/cert8.db
Line 11,157: Line 9,989:
/local/client/alias/secmod.db
/local/client/alias/secmod.db
$</pre>  
$</pre>  
'''See Also'''


'''See Also'''
<br> ldap_start_tls_s(), ldap_init(), prldap_init() (IPv6), ldapssl_init(), ldapssl_install_routines()  
 
 
ldap_start_tls_s(), ldap_init(), prldap_init() (IPv6), ldapssl_init(), ldapssl_install_routines()  


=== ldapssl_clientauth_init()  ===
=== ldapssl_clientauth_init()  ===
Line 11,167: Line 9,997:
The ldapssl_clientauth_init() function initializes your client application to connect to a secure LDAP server over SSL and to use certificate-based client authentication.  
The ldapssl_clientauth_init() function initializes your client application to connect to a secure LDAP server over SSL and to use certificate-based client authentication.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap_ssl.h&gt;
<pre>#include &lt;ldap_ssl.h&gt;
int ldapssl_clientauth_init( char *certdbpath, void *certdbhandle,
int ldapssl_clientauth_init( char *certdbpath, void *certdbhandle,
   int needkeydb, char *keydbpath, void *keydbhandle );</pre>  
   int needkeydb, char *keydbpath, void *keydbhandle );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldapssl_clientauth_init() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldapssl_clientauth_init() Function Parameters"
Line 11,199: Line 10,027:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:  
 
 
One of the following values:  


*<tt>0</tt> if successful.  
*<tt>0</tt> if successful.  
*<tt>-1</tt> if unsuccessful.
*<tt>-1</tt> if unsuccessful.


<br> '''Description'''


'''Description'''
<br> You can call the ldapssl_clientauth_init() 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 ldapssl_advclientauth_init() function instead.  
 
 
You can call the ldapssl_clientauth_init() 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 ldapssl_advclientauth_init() function instead.  


'''Note:''' You must call ldapssl_clientauth_init() before calling ldapssl_init() to connect to the server.  
'''Note:''' You must call ldapssl_clientauth_init() before calling ldapssl_init() to connect to the server.  


<br> '''Example'''


'''Example'''
<br> The following example initializes a client before connecting with a secure LDAP server.  
 
 
The following example initializes a client before connecting with a secure LDAP server.  
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
#include &lt;ldap_ssl.h&gt;
#include &lt;ldap_ssl.h&gt;
Line 11,235: Line 10,057:
}
}
...</pre>  
...</pre>  
'''See Also'''


'''See Also'''
<br> ldap_init(), prldap_init() (IPv6), ldapssl_init(), ldapssl_install_routines()  
 
 
ldap_init(), prldap_init() (IPv6), ldapssl_init(), ldapssl_install_routines()  


=== ldapssl_enable_clientauth()  ===
=== ldapssl_enable_clientauth()  ===
Line 11,245: Line 10,065:
The ldapssl_enable_clientauth() function enables SSL client authentication on the given connection (passed using the <tt>ld</tt> parameter).  
The ldapssl_enable_clientauth() function enables SSL client authentication on the given connection (passed using the <tt>ld</tt> parameter).  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap_ssl.h&gt;
<pre>#include &lt;ldap_ssl.h&gt;
int ldapssl_enable_clientauth( LDAP *ld, char *keynickname,
int ldapssl_enable_clientauth( LDAP *ld, char *keynickname,
   char *keypasswd, char *certnickname );</pre>  
   char *keypasswd, char *certnickname );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldapssl_enable_clientauth() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldapssl_enable_clientauth() Function Parameters"
Line 11,274: Line 10,092:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:  
 
 
One of the following values:  


*<tt>0</tt> if successful.  
*<tt>0</tt> if successful.  
*<tt>-1</tt> if unsuccessful.
*<tt>-1</tt> if unsuccessful.


<br> '''See Also'''


'''See Also'''
<br> ldapssl_clientauth_init()  
 
 
ldapssl_clientauth_init()  


=== ldapssl_err2string()  ===
=== ldapssl_err2string()  ===
Line 11,293: Line 10,107:
The ldapssl_err2string() function returns the corresponding error message for an SSL-specific error code.  
The ldapssl_err2string() function returns the corresponding error message for an SSL-specific error code.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap_ssl.h&gt;
<pre>#include &lt;ldap_ssl.h&gt;
const char * LDAP_CALL ldapssl_err2string ( const int prerrno );</pre>  
const char * LDAP_CALL ldapssl_err2string ( const int prerrno );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldapssl_err2string() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldapssl_err2string() Function Parameters"
Line 11,312: Line 10,124:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:  
 
 
One of the following values:  


*If successful, returns the corresponding error message for the given error code.  
*If successful, returns the corresponding error message for the given error code.  
*If unsuccessful (for example, if the error code is not a known SSL error code), returns a pointer to the string <tt>Unknown error.</tt>  
*If unsuccessful (for example, if the error code is not a known SSL error code), returns a pointer to the string <tt>Unknown error.</tt>
 
 
'''Description'''


<br> '''Description'''


ldapssl_err2string() provides support for SSL-specific error messages that are not covered by the regular message routine ldap_err2string(). If any ldapssl_*() function returns an error code that is unknown to ldap_err2string()‚Äö√Ñ√¨it returns <tt>Unknown error</tt>‚Äö√Ñ√¨ this function should be called to determine the SSL-specific error message. To check for SSL errors, call ldapssl_err2string() after you call any of the following SSL initialization functions:  
<br> ldapssl_err2string() provides support for SSL-specific error messages that are not covered by the regular message routine ldap_err2string(). If any ldapssl_*() function returns an error code that is unknown to ldap_err2string()‚Äö√Ñ√¨it returns <tt>Unknown error</tt>‚Äö√Ñ√¨ this function should be called to determine the SSL-specific error message. To check for SSL errors, call ldapssl_err2string() after you call any of the following SSL initialization functions:  


*ldapssl_client_init()  
*ldapssl_client_init()  
Line 11,334: Line 10,142:
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.  
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.  


<br> '''See Also'''


'''See Also'''
<br> ldapssl_client_init(), ldapssl_clientauth_init(), ldapssl_advclientauth_init(), ldapssl_pkcs_init(), ldap_err2string()  
 
 
ldapssl_client_init(), ldapssl_clientauth_init(), ldapssl_advclientauth_init(), ldapssl_pkcs_init(), ldap_err2string()  


=== ldapssl_init()  ===
=== ldapssl_init()  ===
Line 11,344: Line 10,150:
The ldapssl_init() function initializes the LDAP library for SSL and installs the I/O routines for SSL.  
The ldapssl_init() function initializes the LDAP library for SSL and installs the I/O routines for SSL.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap_ssl.h&gt;
<pre>#include &lt;ldap_ssl.h&gt;
LDAP *ldapssl_init( const char *defhost, int defport, int defsecure );</pre>  
LDAP *ldapssl_init( const char *defhost, int defport, int defsecure );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldapssl_init() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldapssl_init() Function Parameters"
Line 11,369: Line 10,173:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:  
 
 
One of the following values:  


*If successful, returns a pointer to an LDAP() structure, which should be passed to subsequent calls to other LDAP API functions.  
*If successful, returns a pointer to an LDAP() structure, which should be passed to subsequent calls to other LDAP API functions.  
*If unsuccessful, returns -1.
*If unsuccessful, returns -1.


<br> '''Description'''


'''Description'''
<br> ldapssl_init() allocates an LDAP() structure but does not open an initial connection. Before calling this function, call ldapssl_client_init() to initialize your client for SSL.  
 
 
ldapssl_init() allocates an LDAP() structure but does not open an initial connection. Before calling this function, call ldapssl_client_init() to initialize your client for SSL.  


The following example connects your client to a secure LDAP server.  
The following example connects your client to a secure LDAP server.  
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
#include &lt;ldap_ssl.h&gt;
#include &lt;ldap_ssl.h&gt;
Line 11,404: Line 10,203:
/* Client can now perform LDAP operations on the secure LDAP server */
/* Client can now perform LDAP operations on the secure LDAP server */
...</pre>  
...</pre>  
'''See Also'''


'''See Also'''
<br> ldap_init(), prldap_init() (IPv6), ldapssl_client_init(), ldapssl_install_routines()  
 
 
ldap_init(), prldap_init() (IPv6), ldapssl_client_init(), ldapssl_install_routines()  


=== ldapssl_install_routines()  ===
=== ldapssl_install_routines()  ===
Line 11,414: Line 10,211:
The ldapssl_install_routines() function installs the I/O routines that enable SSL over LDAP.  
The ldapssl_install_routines() function installs the I/O routines that enable SSL over LDAP.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap_ssl.h&gt;
<pre>#include &lt;ldap_ssl.h&gt;
int ldapssl_install_routines( LDAP *ld );</pre>  
int ldapssl_install_routines( LDAP *ld );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldapssl_install_routines() Function Parameter"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldapssl_install_routines() Function Parameter"
Line 11,433: Line 10,228:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:  
 
 
One of the following values:  


*<tt>0</tt> if successful.  
*<tt>0</tt> if successful.  
*<tt>-1</tt> if unsuccessful.
*<tt>-1</tt> if unsuccessful.


<br> '''Description'''


'''Description'''
<br> You need to call ldapssl_install_routines() in combination with ldap_init() or prldap_init() (IPv6) and ldap_set_option(). As an alternative, you can call ldapssl_init() rather than these three functions.  
 
 
You need to call ldapssl_install_routines() in combination with ldap_init() or prldap_init() (IPv6) and ldap_set_option(). As an alternative, you can call ldapssl_init() rather than these three functions.  


'''Note:''' As is the case with the ldapssl_init() function, you need to call ldapssl_client_init() to initialize your client for SSL before calling ldapssl_install_routines().  
'''Note:''' As is the case with the ldapssl_init() function, you need to call ldapssl_client_init() to initialize your client for SSL before calling ldapssl_install_routines().  


<br> '''Example'''


'''Example'''
<br> The following example connects your client to a secure LDAP server.  
 
 
The following example connects your client to a secure LDAP server.  
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
#include &lt;ldap_ssl.h&gt;
#include &lt;ldap_ssl.h&gt;
Line 11,481: Line 10,270:
}
}
...</pre>  
...</pre>  
'''See Also'''


'''See Also'''
<br> ldap_init(), prldap_init() (IPv6), ldapssl_init(), ldapssl_client_init()  
 
 
ldap_init(), prldap_init() (IPv6), ldapssl_init(), ldapssl_client_init()  


=== ldapssl_pkcs_init()  ===
=== ldapssl_pkcs_init()  ===
<pre>int ldapssl_pkcs_init( const struct ldapssl_pkcs_fns *pfns);</pre>  
<pre>int ldapssl_pkcs_init( const struct ldapssl_pkcs_fns *pfns);</pre>  
'''Description'''


'''Description'''
<br> The ldap_pkcs_init() structure sets up callbacks for the security library to obtain required runtime information. It should be used in place of ldapssl_client_init(), ldapssl_clientauth_init(), and ldapssl_advclientauth_init().  
 
 
The ldap_pkcs_init() structure sets up callbacks for the security library to obtain required runtime information. It should be used in place of ldapssl_client_init(), ldapssl_clientauth_init(), and ldapssl_advclientauth_init().  


'''Note:''' The LDAP C SDK 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.  
'''Note:''' The LDAP C SDK 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.  
Line 11,524: Line 10,309:
   LDAP_PKCS_GET_DONGLEFILENAME_CALLBACK *pkcs_getdonglefilename;
   LDAP_PKCS_GET_DONGLEFILENAME_CALLBACK *pkcs_getdonglefilename;
};</pre>  
};</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldapssl_pkcs_init() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldapssl_pkcs_init() Function Parameters"
Line 11,538: Line 10,323:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:  
 
 
One of the following values:  


*0 is successful.  
*0 is successful.  
Line 11,548: Line 10,331:
*''n'' (a positive integer) denotes a Netscape Portable Runtime (NSPR) error as returned by the PR_GetError() NSPR function.
*''n'' (a positive integer) denotes a Netscape Portable Runtime (NSPR) error as returned by the PR_GetError() NSPR function.


<br> '''See Also'''


'''See Also'''
<br> ldapssl_client_init(), ldapssl_clientauth_init(), ldapssl_advclientauth_init()  
 
 
ldapssl_client_init(), ldapssl_clientauth_init(), ldapssl_advclientauth_init()


=== ldapssl_serverauth_init()  ===
=== ldapssl_serverauth_init()  ===
Line 11,558: Line 10,339:
The ldapssl_serverauth_init() function is a server-authentication only version of ldapssl_clientauth_init().  
The ldapssl_serverauth_init() function is a server-authentication only version of ldapssl_clientauth_init().  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap_ssl.h&gt;
<pre>#include &lt;ldap_ssl.h&gt;
int ldapssl_serverauth_init(
int ldapssl_serverauth_init(
   const char *certdbpath, void *certdbhandle, const int sslstrength );</pre>  
   const char *certdbpath, void *certdbhandle, const int sslstrength );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldapssl_serverauth_init() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldapssl_serverauth_init() Function Parameters"
Line 11,588: Line 10,367:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:  
 
 
One of the following values:  


*<tt>0</tt> if successful.  
*<tt>0</tt> if successful.  
*<tt>-1</tt> if unsuccessful.
*<tt>-1</tt> if unsuccessful.


<br> '''Description'''


'''Description'''
<br> ldapssl_serverauth_init() is a server-authentication only version of ldapssl_clientauth_init(). This function allows the <tt>sslstrength</tt> parameter to be passed in.  
 
 
ldapssl_serverauth_init() is a server-authentication only version of ldapssl_clientauth_init(). This function allows the <tt>sslstrength</tt> parameter to be passed in.  
 
 
'''See Also'''


<br> '''See Also'''


ldap_init(), prldap_init() (IPv6), ldapssl_init(), ldapssl_install_routines(), ldapssl_clientauth_init()  
<br> ldap_init(), prldap_init() (IPv6), ldapssl_init(), ldapssl_install_routines(), ldapssl_clientauth_init()  


=== ldapssl_set_strength()  ===
=== ldapssl_set_strength()  ===
Line 11,613: Line 10,386:
The ldapssl_set_strength() sets the SSL strength for an existing SSL-enabled LDAP session handle.  
The ldapssl_set_strength() sets the SSL strength for an existing SSL-enabled LDAP session handle.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap_ssl.h&gt;
<pre>#include &lt;ldap_ssl.h&gt;
int LDAP_CALL ldapssl_set_strength( LDAP *ld, int sslstrength );</pre>  
int LDAP_CALL ldapssl_set_strength( LDAP *ld, int sslstrength );</pre>  
'''Parameters'''


'''Parameters'''
<br> '''Note:''' See the description of the <tt>sslstrength</tt> value and note the potential problems that can be caused by passing in wrong host and port name values.  
 
 
'''Note:''' See the description of the <tt>sslstrength</tt> value and note the potential problems that can be caused by passing in wrong host and port name values.  


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldapssl_set_strength() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldapssl_set_strength() Function Parameters"
Line 11,645: Line 10,414:
The ldapssl_tls_start_s() function starts an SSL handshake on a previously established non-secure connection.  
The ldapssl_tls_start_s() function starts an SSL handshake on a previously established non-secure connection.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap_ssl.h&gt;
<pre>#include &lt;ldap_ssl.h&gt;
LDAP_API(int)  LDAP_CALL ldapssl_tls_start_s( LDAP *ld, int defsecure,
LDAP_API(int)  LDAP_CALL ldapssl_tls_start_s( LDAP *ld, int defsecure,
   char *certdbpath, char *keydbpath, char ***referralsp );</pre>  
   char *certdbpath, char *keydbpath, char ***referralsp );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldapssl_tls_start_s() Function Parameter"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldapssl_tls_start_s() Function Parameter"
Line 11,677: Line 10,444:
|}
|}


<br> '''Description'''


'''Description'''
<br> The ldapssl_tls_start_s() function starts an SSL handshake on a previously established non-secure connection.  
 
 
The ldapssl_tls_start_s() function starts an SSL handshake on a previously established non-secure connection.  


=== ldap_str2charray()  ===
=== ldap_str2charray()  ===
Line 11,691: Line 10,456:
The ldap_tmplattrs() function obtains a pointer to the correct <tt>ldap_disptmpl</tt> structure.  
The ldap_tmplattrs() function obtains a pointer to the correct <tt>ldap_disptmpl</tt> structure.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;disptmpl.h&gt;
<pre>#include &lt;disptmpl.h&gt;
char ** ldap_tmplattrs( struct ldap_disptmpl *tmpl, char **includeattrs,
char ** ldap_tmplattrs( struct ldap_disptmpl *tmpl, char **includeattrs,
   int exclude, unsigned long syntaxmask );</pre>  
   int exclude, unsigned long syntaxmask );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_tmplattrs() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_tmplattrs() Function Parameters"
Line 11,720: Line 10,483:
|}
|}


<br> '''Returns'''


'''Returns'''
<br>
 


*<tt>A NULL</tt> terminated array that contains the
*<tt>A NULL</tt> terminated array that contains the
Line 11,730: Line 10,493:
*A <tt>NULL</tt> pointer on error.
*A <tt>NULL</tt> pointer on error.


<br> '''Description'''


'''Description'''
<br> The attribute list should be freed using ldap_value_free() .  
 
 
The attribute list should be freed using ldap_value_free() .  
 
 
'''See Also'''


<br> '''See Also'''


ldap_value_free()  
<br> ldap_value_free()  


=== ldap_tmplerr2string()  ===
=== ldap_tmplerr2string()  ===
Line 11,746: Line 10,505:
The ldap_templerr2string() function returns a string representation of the error passed in the parameter.  
The ldap_templerr2string() function returns a string representation of the error passed in the parameter.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;disptmpl.h&gt;
<pre>#include &lt;disptmpl.h&gt;
char * ldap_tmplerr2string( int err );</pre>  
char * ldap_tmplerr2string( int err );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_tmplerr2string() Function Parameter"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_tmplerr2string() Function Parameter"
Line 11,781: Line 10,538:
The ldap_unbind() function unbinds from the directory, terminates the current association, and frees the resources contained in the LDAP structure.  
The ldap_unbind() function unbinds from the directory, terminates the current association, and frees the resources contained in the LDAP structure.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
int ldap_unbind( LDAP *ld );</pre>  
int ldap_unbind( LDAP *ld );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_unbind() Function Parameter"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_unbind() Function Parameter"
Line 11,800: Line 10,555:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> For a list of possible results for an LDAP unbind operation, see ldap_unbind_s().


<br> '''Description'''


For a list of possible results for an LDAP unbind operation, see ldap_unbind_s().  
<br> The ldap_unbind() function unbinds from the directory, terminates the current association, and frees the resources contained in the LDAP structure. The three unbind functions (ldap_unbind() , ldap_unbind_s(), and ldap_unbind_ext()) 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.  


 
The following example closes the current connection with the LDAP server.  
'''Description'''
 
 
The ldap_unbind() function unbinds from the directory, terminates the current association, and frees the resources contained in the LDAP structure. The three unbind functions (ldap_unbind() , ldap_unbind_s(), and ldap_unbind_ext()) 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.
 
The following example closes the current connection with the LDAP server.  
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
...
...
Line 11,824: Line 10,575:
}
}
...</pre>  
...</pre>  
'''See Also'''


'''See Also'''
<br> ldap_unbind_s(), ldap_unbind_ext()  
 
 
ldap_unbind_s(), ldap_unbind_ext()  


=== ldap_unbind_s()  ===
=== ldap_unbind_s()  ===
Line 11,834: Line 10,583:
The ldap_unbind_s() function unbinds from the directory, terminates the current association, and frees the resources contained in the LDAP structure.  
The ldap_unbind_s() function unbinds from the directory, terminates the current association, and frees the resources contained in the LDAP structure.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
int ldap_unbind_s( LDAP *ld );</pre>  
int ldap_unbind_s( LDAP *ld );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_unbind_s() Function Parameter"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_unbind_s() Function Parameter"
Line 11,853: Line 10,600:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:  
 
 
One of the following values:  


*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
*LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request.  
*LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request.  
*LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.  
*LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.  
*LDAP_NO_MEMORY if memory cannot be allocated.  
*LDAP_NO_MEMORY if memory cannot be allocated.
 
 
'''Description'''


<br> '''Description'''


The ldap_unbind_s() function unbinds from the directory, terminates the current association, and frees the resources contained in the LDAP structure. The three unbind functions ( ldap_unbind(), ldap_unbind_s(), and ldap_unbind_ext()) 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.  
<br> The ldap_unbind_s() function unbinds from the directory, terminates the current association, and frees the resources contained in the LDAP structure. The three unbind functions ( ldap_unbind(), ldap_unbind_s(), and ldap_unbind_ext()) 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.  


'''Note:''' There is no server response to an LDAP unbind operation. All three of the unbind functions return LDAP_SUCCESS (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 <tt>ld</tt> is invalid and it is illegal to make any further calls using it.  
'''Note:''' There is no server response to an LDAP unbind operation. All three of the unbind functions return LDAP_SUCCESS (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 <tt>ld</tt> is invalid and it is illegal to make any further calls using it.  


<br> '''Example'''


'''Example'''
<br> The following example closes the current connection with the LDAP server.  
 
 
The following example closes the current connection with the LDAP server.  
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
...
...
Line 11,888: Line 10,629:
}
}
...</pre>  
...</pre>  
'''See Also'''


'''See Also'''
<br> ldap_unbind(), ldap_unbind_ext()  
 
 
ldap_unbind(), ldap_unbind_ext()  


=== ldap_unbind_ext()  ===
=== ldap_unbind_ext()  ===
Line 11,898: Line 10,637:
The ldap_unbind_ext() function unbinds from the directory, terminates the current association, and frees the resources contained in the LDAP structure.  
The ldap_unbind_ext() function unbinds from the directory, terminates the current association, and frees the resources contained in the LDAP structure.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
int ldap_unbind_ext( LDAP *ld, LDAPControl **serverctrls,
int ldap_unbind_ext( LDAP *ld, LDAPControl **serverctrls,
   LDAPControl **clientctrls );</pre>  
   LDAPControl **clientctrls );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_unbind_ext() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_unbind_ext() Function Parameters"
Line 11,924: Line 10,661:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:  
 
 
One of the following values:  


*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
Line 11,934: Line 10,669:
*LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.  
*LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.  
*LDAP_NO_MEMORY if memory cannot be allocated.  
*LDAP_NO_MEMORY if memory cannot be allocated.  
*LDAP_NOT_SUPPORTED 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.  
*LDAP_NOT_SUPPORTED 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.
 
 
'''Description'''


<br> '''Description'''


The ldap_unbind_ext() function unbinds from the directory, terminates the current association, and frees the resources contained in the LDAP structure. The three unbind functions (ldap_unbind(), ldap_unbind_s(), and ldap_unbind_ext()) 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.  
<br> The ldap_unbind_ext() function unbinds from the directory, terminates the current association, and frees the resources contained in the LDAP structure. The three unbind functions (ldap_unbind(), ldap_unbind_s(), and ldap_unbind_ext()) 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.  


See also ldap_unbind(), ldap_unbind_s()  
See also ldap_unbind(), ldap_unbind_s()  
Line 11,948: Line 10,681:
The ldap_url_parse() function parses an LDAP URL into its components.  
The ldap_url_parse() function parses an LDAP URL into its components.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
int ldap_url_parse( const char *url, LDAPURLDesc **ludpp );</pre>  
int ldap_url_parse( const char *url, LDAPURLDesc **ludpp );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_url_parse() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_url_parse() Function Parameters"
Line 11,970: Line 10,701:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:  
 
 
One of the following values:  


*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
Line 11,980: Line 10,709:
*<tt>LDAP_URL_ERR_NODN</tt> if the URL missing trailing slash after host or port.  
*<tt>LDAP_URL_ERR_NODN</tt> if the URL missing trailing slash after host or port.  
*<tt>LDAP_URL_ERR_BADSCOPE</tt> if the scope within the URL is invalid.  
*<tt>LDAP_URL_ERR_BADSCOPE</tt> if the scope within the URL is invalid.  
*<tt>LDAP_URL_ERR_MEM</tt> if not enough free memory is available for this operation.  
*<tt>LDAP_URL_ERR_MEM</tt> if not enough free memory is available for this operation.  
*<tt>LDAP_URL_ERR_PARAM</tt> if an invalid argument was passed to the function.  
*<tt>LDAP_URL_ERR_PARAM</tt> if an invalid argument was passed to the function.
 
 
'''Example'''


<br> '''Example'''


The following example parses an LDAP URL and prints out each component of it.  
<br> The following example parses an LDAP URL and prints out each component of it.  
<pre>#include &lt;stdio.h&gt;
<pre>#include &lt;stdio.h&gt;
#include &lt;ldap.h&gt;
#include &lt;ldap.h&gt;
Line 12,047: Line 10,774:
printf( "Filter:&nbsp;%s\n", ludpp-&gt;lud_filter );
printf( "Filter:&nbsp;%s\n", ludpp-&gt;lud_filter );
...</pre>  
...</pre>  
'''See Also'''


'''See Also'''
<br> ldap_free_urldesc()  
 
 
ldap_free_urldesc()  


=== ldap_url_parse_no_defaults()  ===
=== ldap_url_parse_no_defaults()  ===
Line 12,057: Line 10,782:
The ldap_url_parse_no_defaults() function parses an LDAP URL into its components.  
The ldap_url_parse_no_defaults() function parses an LDAP URL into its components.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
int ldap_url_parse_no_defaults( const char *url, LDAPURLDesc **ludpp,
int ldap_url_parse_no_defaults( const char *url, LDAPURLDesc **ludpp,
   int dn_required );</pre>  
   int dn_required );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_url_parse_no_defaults() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_url_parse_no_defaults() Function Parameters"
Line 12,083: Line 10,806:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:  
 
 
One of the following values:  


*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
*<tt>LDAP_URL_ERR_NODN</tt> if a required DN is not present.  
*<tt>LDAP_URL_ERR_NODN</tt> if a required DN is not present.  
*<tt>LDAP_URL_ERR_NOTLDAP</tt> if the URL does not begin with the ldap:// or ldaps:// prefix.  
*<tt>LDAP_URL_ERR_NOTLDAP</tt> if the URL does not begin with the ldap:// or ldaps:// prefix.  
*<tt>LDAP_URL_ERR_NODN</tt> if the URL missing trailing slash after host or port.
*<tt>LDAP_URL_ERR_NODN</tt> if the URL missing trailing slash after host or port.  
*<tt>LDAP_URL_ERR_BADSCOPE</tt> if the scope within the URL is invalid.  
*<tt>LDAP_URL_ERR_BADSCOPE</tt> if the scope within the URL is invalid.  
*<tt>LDAP_URL_ERR_MEM</tt> if not enough free memory is available for this operation.  
*<tt>LDAP_URL_ERR_MEM</tt> if not enough free memory is available for this operation.  
*<tt>LDAP_URL_ERR_PARAM</tt> if an invalid argument was passed to the function.  
*<tt>LDAP_URL_ERR_PARAM</tt> if an invalid argument was passed to the function.
 
 
'''Description'''


<br> '''Description'''


The ldap_url_parse_no_defaults() function does not set any default value in the fields that would be absent from the URL (for example, the port number).  
<br> The ldap_url_parse_no_defaults() function does not set any default value in the fields that would be absent from the URL (for example, the port number).  


=== ldap_url_search()  ===
=== ldap_url_search()  ===
Line 12,107: Line 10,826:
The ldap_url_search() function searches the directory asynchronously for matching entries, based on the contents of the URL.  
The ldap_url_search() function searches the directory asynchronously for matching entries, based on the contents of the URL.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
int ldap_url_search( LDAP *ld, const char *url, int attrsonly );</pre>  
int ldap_url_search( LDAP *ld, const char *url, int attrsonly );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_url_search() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_url_search() Function Parameters"
Line 12,135: Line 10,852:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> Returns the message ID of the ldap_url_search() operation. To check the result of this operation, call ldap_result() and ldap_result2error().  
 
 
Returns the message ID of the ldap_url_search() operation. To check the result of this operation, call ldap_result() and ldap_result2error().
 
 
'''Description'''
 
 
ldap_url_search() searches the directory for matching entries, based on the contents of the URL. ldap_url_search() 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 ldap_url_search_s().  


<br> '''Description'''


'''Example'''
<br> ldap_url_search() searches the directory for matching entries, based on the contents of the URL. ldap_url_search() 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 ldap_url_search_s().


<br> '''Example'''


The following example returns the message ID.  
<br> The following example returns the message ID.  
<pre>#include "examples.h"
<pre>#include "examples.h"


Line 12,265: Line 10,976:
     global_counter++;
     global_counter++;
}</pre>  
}</pre>  
'''See Also'''


'''See Also'''
<br> ldap_url_search_s(), ldap_result(), ldap_result2error()  
 
 
ldap_url_search_s(), ldap_result(), ldap_result2error()  


=== ldap_url_search_s()  ===
=== ldap_url_search_s()  ===
Line 12,275: Line 10,984:
The ldap_url_search_s() function searches the directory synchronously for matching entries, based on the contents of the URL.  
The ldap_url_search_s() function searches the directory synchronously for matching entries, based on the contents of the URL.  


 
<br> '''Syntax'''  
'''Syntax'''
<pre>#include &lt;ldap.h&gt;
 
<pre>#include &lt;ldap.h&gt;
int ldap_url_search_s( LDAP *ld, const char *url,
int ldap_url_search_s( LDAP *ld, const char *url,
   int attrsonly, LDAPMessage **res );</pre>  
   int attrsonly, LDAPMessage **res );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_url_search_s() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_url_search_s() Function Parameters"
Line 12,307: Line 11,014:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:  
 
 
One of the following values:  


*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
*If unsuccessful, returns the LDAP error code for the operation.
*If unsuccessful, returns the LDAP error code for the operation.


<br> '''Description'''


'''Description'''
<br> The ldap_url_search_s() function searches the directory for matching entries, based on the contents of the URL. ldap_url_search_s() 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 ldap_url_search().  
 
 
The ldap_url_search_s() function searches the directory for matching entries, based on the contents of the URL. ldap_url_search_s() 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 ldap_url_search().  
 
 
'''Example'''


<br> '''Example'''


The following example processes a search request from an LDAP URL.  
<br> The following example processes a search request from an LDAP URL.  
<pre>#include &lt;stdio.h&gt;
<pre>#include &lt;stdio.h&gt;
#include &lt;ldap.h&gt;
#include &lt;ldap.h&gt;
Line 12,341: Line 11,042:
}
}
...</pre>  
...</pre>  
'''See Also'''


'''See Also'''
<br> ldap_search(), ldap_search_st()  
 
 
ldap_search(), ldap_search_st()  


=== ldap_url_search_st()  ===
=== ldap_url_search_st()  ===
Line 12,351: Line 11,050:
The ldap_url_search_st() function searches the directory, synchronously within a specified time limit, for matching entries, based on the contents of the URL.  
The ldap_url_search_st() function searches the directory, synchronously within a specified time limit, for matching entries, based on the contents of the URL.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
int ldap_url_search_st( LDAP *ld, const char *url, int attrsonly,
int ldap_url_search_st( LDAP *ld, const char *url, int attrsonly,
   struct timeval *timeout, LDAPMessage **res );</pre>  
   struct timeval *timeout, LDAPMessage **res );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_url_search_st() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_url_search_st() Function Parameters"
Line 12,386: Line 11,083:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:  
 
 
One of the following values:  


*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
Line 12,401: Line 11,096:
*LDAP_FILTER_ERROR if an error occurred when parsing and BER-encoding the search filter specified by the filter argument.  
*LDAP_FILTER_ERROR if an error occurred when parsing and BER-encoding the search filter specified by the filter argument.  
*LDAP_TIMEOUT if the search exceeded the time specified by the <tt>timeoutp</tt> argument.  
*LDAP_TIMEOUT if the search exceeded the time specified by the <tt>timeoutp</tt> argument.  
*LDAP_NOT_SUPPORTED 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.  
*LDAP_NOT_SUPPORTED 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.


'''Note:''' Directory Server 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.  
'''Note:''' Directory Server 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.  


<br> '''Description'''


'''Description'''
<br> The ldap_url_search_st() function searches the directory for matching entries, based on the contents of the URL. This function works like ldap_url_search_s() and lets you specify a time out period for the search.  
 
 
The ldap_url_search_st() function searches the directory for matching entries, based on the contents of the URL. This function works like ldap_url_search_s() and lets you specify a time out period for the search.  
 
 
'''See Also'''


<br> '''See Also'''


ldap_search(), ldap_search_s()  
<br> ldap_search(), ldap_search_s()  


=== ldap_utf8characters()  ===
=== ldap_utf8characters()  ===
Line 12,421: Line 11,112:
The ldap_utf8characters() function accepts a Unicode string and returns the number of characters.  
The ldap_utf8characters() function accepts a Unicode string and returns the number of characters.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
size_t ldap_utf8characters( const char* );</pre>  
size_t ldap_utf8characters( const char* );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_utf8characters() Function Parameter"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_utf8characters() Function Parameter"
Line 12,440: Line 11,129:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> Returns the number of UTF-8 characters in the <tt>0</tt> terminated array.  
 
 
Returns the number of UTF-8 characters in the <tt>0</tt> terminated array.  


=== ldap_utf8copy()  ===
=== ldap_utf8copy()  ===
Line 12,450: Line 11,137:
The ldap_utf8copy() function accepts a Unicode string and copies the characters to a destination.  
The ldap_utf8copy() function accepts a Unicode string and copies the characters to a destination.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
int ldap_utf8copy( char* dst, const char* src );</pre>  
int ldap_utf8copy( char* dst, const char* src );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_utf8copy() Function Parameter"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_utf8copy() Function Parameter"
Line 12,472: Line 11,157:
|}
|}


<br> '''Description'''


'''Description'''
<br> ldap_utf8copy() copies a character from <tt>src</tt> to <tt>dst</tt>. This function handles any valid UTF-8 character (including <tt>\0</tt> and ASCII).  
 
 
ldap_utf8copy() copies a character from <tt>src</tt> to <tt>dst</tt>. This function handles any valid UTF-8 character (including <tt>\0</tt> and ASCII).  
 
 
'''Returns'''


<br> '''Returns'''


The number of characters copied.  
<br> The number of characters copied.  


=== ldap_utf8getcc()  ===
=== ldap_utf8getcc()  ===
Line 12,488: Line 11,169:
The ldap_utf8getcc() function gets one UCS-4 character and moves the pointer to the next character.  
The ldap_utf8getcc() function gets one UCS-4 character and moves the pointer to the next character.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
unsigned long ldap_utf8getcc( const char** src );</pre>  
unsigned long ldap_utf8getcc( const char** src );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_utf8getcc() Function Parameter"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_utf8getcc() Function Parameter"
Line 12,511: Line 11,190:
The ldap_utf8isalnum() function determines whether the character is an alphanumeric one.  
The ldap_utf8isalnum() function determines whether the character is an alphanumeric one.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
int ldap_utf8isalnum( char* s );</pre>  
int ldap_utf8isalnum( char* s );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_utf8isalnum() Function Parameter"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_utf8isalnum() Function Parameter"
Line 12,534: Line 11,211:
The ldap_utf8isalpha() function determines whether the character is a letter.  
The ldap_utf8isalpha() function determines whether the character is a letter.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
int ldap_utf8isalpha( char* s );</pre>  
int ldap_utf8isalpha( char* s );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_utf8isalpha() Function Parameter"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_utf8isalpha() Function Parameter"
Line 12,557: Line 11,232:
The ldap_utf8isdigit() function determines whether the character is a number.  
The ldap_utf8isdigit() function determines whether the character is a number.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
int ldap_utf8isdigit( char* s );</pre>  
int ldap_utf8isdigit( char* s );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_utf8isdigit() Function Parameter"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_utf8isdigit() Function Parameter"
Line 12,580: Line 11,253:
The ldap_utf8isspace() function determines whether the character is a space, tab, newline, return or formfeed.  
The ldap_utf8isspace() function determines whether the character is a space, tab, newline, return or formfeed.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
int ldap_utf8isspace( char* s );</pre>  
int ldap_utf8isspace( char* s );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_utf8isspace() Function Parameter"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_utf8isspace() Function Parameter"
Line 12,603: Line 11,274:
The ldap_utf8len() function accepts a Unicode string and returns the number of bytes it contains.  
The ldap_utf8len() function accepts a Unicode string and returns the number of bytes it contains.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
int ldap_utf8len( const char* );</pre>  
int ldap_utf8len( const char* );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_utf8len() Function Parameter"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_utf8len() Function Parameter"
Line 12,626: Line 11,295:
The ldap_utf8next() function accepts a character and returns a pointer to the character immediately following it.  
The ldap_utf8next() function accepts a character and returns a pointer to the character immediately following it.  


 
<br> '''Syntax'''  
'''Syntax'''
<pre>#include &lt;ldap.h&gt;
 
<pre>#include &lt;ldap.h&gt;
char* ldap_utf8next( char* );</pre>  
char* ldap_utf8next( char* );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_utf8next() Function Parameter"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_utf8next() Function Parameter"
Line 12,649: Line 11,316:
The ldap_utf8prev() function accepts a character and returns a pointer to the previous character.  
The ldap_utf8prev() function accepts a character and returns a pointer to the previous character.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
char* ldap_utf8prev( char* );</pre>  
char* ldap_utf8prev( char* );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_utf8prev() Function Parameter"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_utf8prev() Function Parameter"
Line 12,672: Line 11,337:
The ldap_utf8strtok_r() function gets the next token from a string.  
The ldap_utf8strtok_r() function gets the next token from a string.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
char* ldap_utf8strtok_r( char* src, const char* brk, char** next);</pre>  
char* ldap_utf8strtok_r( char* src, const char* brk, char** next);</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_utf8strtok_r() Function Parameter"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_utf8strtok_r() Function Parameter"
Line 12,697: Line 11,360:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> Returns a pointer to the next token. If there are no remaining tokens, returns a <tt>NULL</tt> pointer.  
 
 
Returns a pointer to the next token. If there are no remaining tokens, returns a <tt>NULL</tt> pointer.  


=== ldap_whoami()  ===
=== ldap_whoami()  ===
Line 12,707: Line 11,368:
The ldap_whoami() function sends an asynchronous Who am I? extended operation request to determine the authorization identity associated with a connection.  
The ldap_whoami() function sends an asynchronous Who am I? extended operation request to determine the authorization identity associated with a connection.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>LDAP_API(int) LDAP_CALL ldap_whoami( LDAP *ld, LDAPControl **serverctrls,
<pre>LDAP_API(int) LDAP_CALL ldap_whoami( LDAP *ld, LDAPControl **serverctrls,
   LDAPControl **clientctrls, int *msgidp );</pre>  
   LDAPControl **clientctrls, int *msgidp );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_whoami() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_whoami() Function Parameters"
Line 12,735: Line 11,394:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:  
 
 
One of the following values:  


*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
Line 12,745: Line 11,402:
*LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request.  
*LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request.  
*LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.  
*LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.  
*LDAP_NO_MEMORY if memory cannot be allocated.  
*LDAP_NO_MEMORY if memory cannot be allocated.


=== ldap_whoami_s()  ===
=== ldap_whoami_s()  ===
Line 12,751: Line 11,408:
The ldap_whoami_s() function sends a synchronous Who am I? extended operation request to determine the authorization identity associated with a connection.  
The ldap_whoami_s() function sends a synchronous Who am I? extended operation request to determine the authorization identity associated with a connection.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>LDAP_API(int) LDAP_CALL ldap_whoami_s( LDAP *ld, LDAPControl **serverctrls,
<pre>LDAP_API(int) LDAP_CALL ldap_whoami_s( LDAP *ld, LDAPControl **serverctrls,
   LDAPControl **clientctrls, char **authzid );</pre>  
   LDAPControl **clientctrls, char **authzid );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_whoami_s() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_whoami_s() Function Parameters"
Line 12,779: Line 11,434:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> One of the following values:  
 
 
One of the following values:  


*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
Line 12,789: Line 11,442:
*LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request.  
*LDAP_ENCODING_ERROR if an error occurred when BER-encoding the request.  
*LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.  
*LDAP_SERVER_DOWN if the LDAP server did not receive the request or if the connection to the server was lost.  
*LDAP_NO_MEMORY if memory cannot be allocated.  
*LDAP_NO_MEMORY if memory cannot be allocated.


=== ldap_vals2html()  ===
=== ldap_vals2html()  ===
Line 12,795: Line 11,448:
The ldap_vals2html() function writes the HTML representation of a set of values.  
The ldap_vals2html() function writes the HTML representation of a set of values.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;disptmpl.h&gt;
<pre>#include &lt;disptmpl.h&gt;
int ldap_vals2html( LDAP *ld, char *buf, char **vals, char *label,
int ldap_vals2html( LDAP *ld, char *buf, char **vals, char *label,
   int labelwidth, unsigned long syntaxid, writeptype writeproc,
   int labelwidth, unsigned long syntaxid, writeptype writeproc,
   void *writeparm, char *eol, int rdncount, char *urlprefix );</pre>  
   void *writeparm, char *eol, int rdncount, char *urlprefix );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_vals2html() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_vals2html() Function Parameters"
Line 12,846: Line 11,497:
|}
|}


<br> '''Returns'''


'''Returns'''
<br>
 


*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
*An LDAP error code on error.
*An LDAP error code on error.


<br> '''Description'''


'''Description'''
<br> ldap_vals2html() produces HTML output of a single set of LDAP attribute values.  
 
 
ldap_vals2html() produces HTML output of a single set of LDAP attribute values.  
 
 
'''See Also'''


<br> '''See Also'''


ldap_vals2text()  
<br> ldap_vals2text()  


=== ldap_vals2text()  ===
=== ldap_vals2text()  ===
Line 12,869: Line 11,516:
The ldap_vals2text() function writes the text representation of an LDAP entry.  
The ldap_vals2text() function writes the text representation of an LDAP entry.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;disptmpl.h&gt;
<pre>#include &lt;disptmpl.h&gt;
int ldap_vals2text( LDAP *ld, char *buf, char **vals, char *label,
int ldap_vals2text( LDAP *ld, char *buf, char **vals, char *label,
   int labelwidth, unsigned long syntaxid, writeptype writeproc,
   int labelwidth, unsigned long syntaxid, writeptype writeproc,
   void *writeparm, char *eol, int rdncount );</pre>  
   void *writeparm, char *eol, int rdncount );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_vals2text() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_vals2text() Function Parameters"
Line 12,917: Line 11,562:
|}
|}


<br> '''Returns'''


'''Returns'''
<br>
 


*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
*An LDAP error code on error.
*An LDAP error code on error.


<br> '''Description'''


'''Description'''
<br> ldap_vals2text() produces a text representation of a single set of LDAP attribute values.  
 
 
ldap_vals2text() produces a text representation of a single set of LDAP attribute values.  
 
 
'''See Also'''


<br> '''See Also'''


ldap_vals2html()  
<br> ldap_vals2html()  


=== ldap_value_free()  ===
=== ldap_value_free()  ===
Line 12,940: Line 11,581:
The ldap_value_free() function frees an array of values from memory.  
The ldap_value_free() function frees an array of values from memory.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
void ldap_value_free( char **values );</pre>  
void ldap_value_free( char **values );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_value_free() Function Parameter"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_value_free() Function Parameter"
Line 12,959: Line 11,598:
|}
|}


<br> '''Description'''


'''Description'''
<br> Use the ldap_value_free_len() function if the values are berval structures.  
 
 
Use the ldap_value_free_len() function if the values are berval structures.
 
 
'''Example'''
 
 
See the example under ldap_get_values().  


<br> '''Example'''


'''See Also'''
<br> See the example under ldap_get_values().


<br> '''See Also'''


ldap_get_values(), ldap_value_free_len  
<br> ldap_get_values(), ldap_value_free_len  


=== ldap_value_free_len()  ===
=== ldap_value_free_len()  ===
Line 12,981: Line 11,614:
The ldap_value_free_len() function frees an array of berval structures from memory.  
The ldap_value_free_len() function frees an array of berval structures from memory.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
void ldap_value_free_len( struct berval **values );</pre>  
void ldap_value_free_len( struct berval **values );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_value_free_len() Function Parameter"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_value_free_len() Function Parameter"
Line 13,000: Line 11,631:
|}
|}


<br> '''Description'''


'''Description'''
<br> Use the ldap_value_free() function instead of this function if the values are string values.  
 
 
Use the ldap_value_free() function instead of this function if the values are string values.
 
 
'''Example'''
 
 
See the example under ldap_get_values_len().  


<br> '''Example'''


'''See Also'''
<br> See the example under ldap_get_values_len().


<br> '''See Also'''


ldap_get_values(), ldap_get_values_len  
<br> ldap_get_values(), ldap_get_values_len  


=== ldap_version()  ===
=== ldap_version()  ===
<pre>#include &lt;ldap.h&gt;
<pre>#include &lt;ldap.h&gt;
int ldap_version( LDAPVersion *ver );</pre>  
int ldap_version( LDAPVersion *ver );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_version() Function Parameter"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_version() Function Parameter"
Line 13,035: Line 11,660:
|}
|}


<br> '''Returns'''


'''Returns'''
<br> The version number of the LDAP C SDK, multiplied by 100. For example, for version 1.0, the function returns 100.  
 
 
The version number of the LDAP C SDK, multiplied by 100. For example, for version 1.0, the function returns 100.  
 
 
'''See Also'''


<br> '''See Also'''


ldap_get_option()  
<br> ldap_get_option()  


=== ldap_x_calloc()  ===
=== ldap_x_calloc()  ===
Line 13,051: Line 11,672:
The ldap_x_calloc() function allocates space for an array of elements.  
The ldap_x_calloc() function allocates space for an array of elements.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap-extension.h&gt;
<pre>#include &lt;ldap-extension.h&gt;
void *ldap_x_calloc( size_t nelem, size_t elsize );</pre>  
void *ldap_x_calloc( size_t nelem, size_t elsize );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_x_calloc() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_x_calloc() Function Parameters"
Line 13,073: Line 11,692:
|}
|}


<br> '''Returns'''


'''Returns'''
<br>
 


*If successful, returns a pointer to the space.  
*If successful, returns a pointer to the space.  
*If there is no available memory, returns a <tt>NULL</tt> pointer.
*If there is no available memory, returns a <tt>NULL</tt> pointer.


<br> '''See Also'''


'''See Also'''
<br> ldap_x_free(), ldap_x_malloc() , ldap_x_realloc()  
 
 
ldap_x_free(), ldap_x_malloc() , ldap_x_realloc()  


=== ldap_x_free()  ===
=== ldap_x_free()  ===
Line 13,090: Line 11,707:
The ldap_x_free() function frees allocated memory.  
The ldap_x_free() function frees allocated memory.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap-extension.h&gt;
<pre>#include &lt;ldap-extension.h&gt;
void ldap_x_free( void *ptr );</pre>  
void ldap_x_free( void *ptr );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_x_free() Function Parameter"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_x_free() Function Parameter"
Line 13,109: Line 11,724:
|}
|}


<br> '''See Also'''


'''See Also'''
<br> ldap_x_calloc(), ldap_x_malloc(), ldap_x_realloc()  
 
 
ldap_x_calloc(), ldap_x_malloc(), ldap_x_realloc()  


=== ldap_x_hostlist_first()  ===
=== ldap_x_hostlist_first()  ===
Line 13,119: Line 11,732:
The ldap_x_hostlist_first() function returns the first host and port defined in a host list file.  
The ldap_x_hostlist_first() function returns the first host and port defined in a host list file.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap-extension.h&gt;
<pre>#include &lt;ldap-extension.h&gt;
int ldap_x_hostlist_first( char *hostlist, int defport, char **hostp,
int ldap_x_hostlist_first( char *hostlist, int defport, char **hostp,
   int *portp, struct ldap_x_hostlist_status **statusp );</pre>  
   int *portp, struct ldap_x_hostlist_status **statusp );</pre>  
'''Description'''


'''Description'''
<br> ldap_x_hostlist_first() parses a space-separated host list (useful for implementing an extended I/O CONNECT callback function) and returns the first host and port defined.


<br> '''Returns'''


ldap_x_hostlist_first() parses a space-separated host list (useful for implementing an extended I/O CONNECT callback function) and returns the first host and port defined.
<br>
 
 
'''Returns'''
 


*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
Line 13,140: Line 11,749:
'''Note:''' A <tt>NULL</tt> or zero-length hostlist causes the host <tt>127.0.0.1</tt> to be returned.  
'''Note:''' A <tt>NULL</tt> or zero-length hostlist causes the host <tt>127.0.0.1</tt> to be returned.  


<br> '''See Also'''


'''See Also'''
<br> ldap_x_hostlist_status(), LDAP_X_EXTIOF_CONNECT_CALLBACK(),  
 
 
ldap_x_hostlist_status(), LDAP_X_EXTIOF_CONNECT_CALLBACK(),  


=== ldap_x_hostlist_next()  ===
=== ldap_x_hostlist_next()  ===
Line 13,150: Line 11,757:
The ldap_x_hostlist_next() function returns the host and port defined in a host list file following the previous host and port returned.  
The ldap_x_hostlist_next() function returns the host and port defined in a host list file following the previous host and port returned.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap-extension.h&gt;
<pre>#include &lt;ldap-extension.h&gt;
int ldap_x_hostlist_next( char **hostp, int *portp,
int ldap_x_hostlist_next( char **hostp, int *portp,
   struct ldap_x_hostlist_status **statusp );</pre>  
   struct ldap_x_hostlist_status **statusp );</pre>  
'''Description'''


'''Description'''
<br> 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.


<br> '''Returns'''


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.
<br>
 
 
'''Returns'''
 


*LDAP_SUCCESS if successful. If no more
*LDAP_SUCCESS if successful. If no more
Line 13,174: Line 11,777:
'''Note:''' A <tt>NULL</tt> or zero-length hostlist causes the host <tt>127.0.0.1</tt> to be returned.  
'''Note:''' A <tt>NULL</tt> or zero-length hostlist causes the host <tt>127.0.0.1</tt> to be returned.  


<br> '''See Also'''


'''See Also'''
<br> ldap_x_hostlist_status(), LDAP_X_EXTIOF_CONNECT_CALLBACK(),  
 
 
ldap_x_hostlist_status(), LDAP_X_EXTIOF_CONNECT_CALLBACK(),  


=== ldap_x_hostlist_status()  ===
=== ldap_x_hostlist_status()  ===


'''See Also'''


'''See Also'''
<br> ldap_x_hostlist_first(), ldap_x_hostlist_next(), LDAP_X_EXTIOF_CONNECT_CALLBACK()  
 
 
ldap_x_hostlist_first(), ldap_x_hostlist_next(), LDAP_X_EXTIOF_CONNECT_CALLBACK()  


=== ldap_x_hostlist_statusfree()  ===
=== ldap_x_hostlist_statusfree()  ===


'''See Also'''


'''See Also'''
<br> ldap_x_hostlist_first(), ldap_x_hostlist_next(), LDAP_X_EXTIOF_CONNECT_CALLBACK()  
 
 
ldap_x_hostlist_first(), ldap_x_hostlist_next(), LDAP_X_EXTIOF_CONNECT_CALLBACK()  


=== ldap_x_malloc()  ===
=== ldap_x_malloc()  ===
Line 13,200: Line 11,797:
The ldap_x_malloc() function allocates space for an object.  
The ldap_x_malloc() function allocates space for an object.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap-extension.h&gt;
<pre>#include &lt;ldap-extension.h&gt;
void *ldap_x_malloc( size_t size );</pre>  
void *ldap_x_malloc( size_t size );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_x_malloc() Function Parameter"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_x_malloc() Function Parameter"
Line 13,219: Line 11,814:
|}
|}


<br> '''See Also'''


'''See Also'''
<br> ldap_x_free(), ldap_x_calloc() , ldap_x_realloc()  
 
 
ldap_x_free(), ldap_x_calloc() , ldap_x_realloc()  


=== ldap_x_realloc()  ===
=== ldap_x_realloc()  ===
Line 13,229: Line 11,822:
The ldap_x_realloc() function changes the size of a block of memory.  
The ldap_x_realloc() function changes the size of a block of memory.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldap-extension.h&gt;
<pre>#include &lt;ldap-extension.h&gt;
void *ldap_x_realloc( void *ptr, size_t size );</pre>  
void *ldap_x_realloc( void *ptr, size_t size );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_x_realloc() Function Parameter"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="ldap_x_realloc() Function Parameter"
Line 13,251: Line 11,842:
|}
|}


<br> '''See Also'''


'''See Also'''
<br> ldap_x_free(), ldap_x_calloc() , ldap_x_malloc()  
 
 
ldap_x_free(), ldap_x_calloc() , ldap_x_malloc()  


=== prldap_get_default_socket_info()  ===
=== prldap_get_default_socket_info()  ===
Line 13,261: Line 11,850:
The prldap_get_default_socket_info() function retrieves default socket information.  
The prldap_get_default_socket_info() function retrieves default socket information.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldappr.h&gt;
<pre>#include &lt;ldappr.h&gt;
int prldap_get_default_socket_info( LDAP *ld, PRLDAPSocketInfo *soip );</pre>  
int prldap_get_default_socket_info( LDAP *ld, PRLDAPSocketInfo *soip );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="prldap_get_default_socket_info() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="prldap_get_default_socket_info() Function Parameters"
Line 13,283: Line 11,870:
|}
|}


<br> '''Returns'''


'''Returns'''
<br>
 


*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
Line 13,291: Line 11,878:
*LDAP_PARAM_ERROR is returned if <tt>ld</tt> is <tt>NULL</tt>.
*LDAP_PARAM_ERROR is returned if <tt>ld</tt> is <tt>NULL</tt>.


<br> '''See Also'''


'''See Also'''
<br> prldap_set_default_socket_info()  
 
 
prldap_set_default_socket_info()  


=== prldap_get_session_info()  ===
=== prldap_get_session_info()  ===
Line 13,301: Line 11,886:
The prldap_get_session_info() function retrieves application-specific data.  
The prldap_get_session_info() function retrieves application-specific data.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldappr.h&gt;
<pre>#include &lt;ldappr.h&gt;
int prldap_get_session_info( LDAP *ld, void *sessionarg,
int prldap_get_session_info( LDAP *ld, void *sessionarg,
   PRLDAPSessionInfo *seip );</pre>  
   PRLDAPSessionInfo *seip );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="prldap_get_session_info() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="prldap_get_session_info() Function Parameters"
Line 13,324: Line 11,907:
|}
|}


<br> '''Returns'''


'''Returns'''
<br>
 


*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
*An LDAP API error code if an error occurs.
*An LDAP API error code if an error occurs.


<br> '''Description'''


'''Description'''
<br> The prldap_get_session_option() function retrieves an option for an LDAP session handle or a session argument that is passed to the <tt>CONNECT</tt> , <tt>POLL</tt>, <tt>NEWHANDLE</tt>, or <tt>DISPOSEHANDLE</tt> extended I/O callbacks.  
 
 
The prldap_get_session_option() function retrieves an option for an LDAP session handle or a session argument that is passed to the <tt>CONNECT</tt> , <tt>POLL</tt>, <tt>NEWHANDLE</tt>, or <tt>DISPOSEHANDLE</tt> extended I/O callbacks.  
 


'''See Also'''
<br> '''See Also'''  


 
<br> prldap_set_session_info()  
prldap_set_session_info()  


=== prldap_get_session_option()  ===
=== prldap_get_session_option()  ===
Line 13,347: Line 11,926:
The prldap_get_session_option() function retrieves an option specific to the <tt>prldap</tt> layer.  
The prldap_get_session_option() function retrieves an option specific to the <tt>prldap</tt> layer.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldappr.h&gt;
<pre>#include &lt;ldappr.h&gt;
int prldap_get_session_option( LDAP *ld, void *sessionarg,
int prldap_get_session_option( LDAP *ld, void *sessionarg,
   int option, ... );</pre>  
   int option, ... );</pre>  
'''Returns'''


'''Returns'''
<br>
 


*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
*An LDAP API error code if an error occurs.
*An LDAP API error code if an error occurs.


<br> '''Description'''


'''Description'''
<br> The prldap_get_session_option() function retrieves an option for an LDAP session handle or a session argument that is passed to the <tt>CONNECT</tt> , <tt>POLL</tt>, <tt>NEWHANDLE</tt>, or <tt>DISPOSEHANDLE</tt> extended I/O callbacks.


<br> '''See Also'''


The prldap_get_session_option() function retrieves an option for an LDAP session handle or a session argument that is passed to the <tt>CONNECT</tt> , <tt>POLL</tt>, <tt>NEWHANDLE</tt>, or <tt>DISPOSEHANDLE</tt> extended I/O callbacks.
<br> prldap_set_session_option()  
 
 
'''See Also'''
 
 
prldap_set_session_option()  


=== prldap_get_socket_info()  ===
=== prldap_get_socket_info()  ===
Line 13,376: Line 11,949:
The prldap_get_socket_info() function retrieves socket-specific information based on parameters passed to the extended I/O callback functions.  
The prldap_get_socket_info() function retrieves socket-specific information based on parameters passed to the extended I/O callback functions.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldappr.h&gt;
<pre>#include &lt;ldappr.h&gt;
int prldap_get_socket_info( int fd, void *socketarg,
int prldap_get_socket_info( int fd, void *socketarg,
   PRLDAPSocketInfo *soip );</pre>  
   PRLDAPSocketInfo *soip );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="prldap_get_socket_info() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="prldap_get_socket_info() Function Parameters"
Line 13,399: Line 11,970:
|}
|}


<br> '''Returns'''


'''Returns'''
<br>
 


*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
*An LDAP API error code if an error occurs.
*An LDAP API error code if an error occurs.


<br> '''See Also'''


'''See Also'''
<br> prldap_set_socket_info()  
 
 
prldap_set_socket_info()  


=== prldap_init()  ===
=== prldap_init()  ===
Line 13,416: Line 11,985:
The prldap_init() function creates a new session handle with Netscape Portable Runtime (NSPR) I/O, threading, support for IPv6, and DNS functions installed.  
The prldap_init() function creates a new session handle with Netscape Portable Runtime (NSPR) I/O, threading, support for IPv6, and DNS functions installed.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldappr.h&gt;
<pre>#include &lt;ldappr.h&gt;
LDAP * prldap_init( const char *defhost, int defport, int shared );</pre>  
LDAP * prldap_init( const char *defhost, int defport, int shared );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="prldap_init() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="prldap_init() Function Parameters"
Line 13,441: Line 12,008:
|}
|}


<br> '''Returns'''


'''Returns'''
<br>
 


*Pointer to LDAP session handle if successful.  
*Pointer to LDAP session handle if successful.  
*<tt>NULL</tt> if an error occurs.
*<tt>NULL</tt> if an error occurs.


<br> '''Description'''


'''Description'''
<br> To be able to use LDAP over Internet Protocol, version 6, IPv6, this function should be used rather than ldap_init().  
 
 
To be able to use LDAP over Internet Protocol, version 6, IPv6, this function should be used rather than ldap_init().  
 
 
'''See Also'''


<br> '''See Also'''


prldap_install_routines()  
<br> prldap_install_routines()  


=== prldap_install_routines()  ===
=== prldap_install_routines()  ===
Line 13,464: Line 12,027:
The prldap_install_routines() function installs Netscape Portable Runtime (NSPR) I/O, threading, and DNS functions so they can be used by the LDAP session handle.  
The prldap_install_routines() function installs Netscape Portable Runtime (NSPR) I/O, threading, and DNS functions so they can be used by the LDAP session handle.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldappr.h&gt;
<pre>#include &lt;ldappr.h&gt;
int prldap_install_routines( LDAP *ld, int shared );</pre>  
int prldap_install_routines( LDAP *ld, int shared );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="prldap_install_routines() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="prldap_install_routines() Function Parameters"
Line 13,486: Line 12,047:
|}
|}


<br> '''Returns'''


'''Returns'''
<br>
 


*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
*An LDAP API error code if an error occurs.
*An LDAP API error code if an error occurs.


<br> '''See Also'''


'''See Also'''
<br> prldap_init()  
 
 
prldap_init()  


=== prldap_set_default_socket_info()  ===
=== prldap_set_default_socket_info()  ===
Line 13,503: Line 12,062:
The prldap_set_default_socket_info() function sets default socket information.  
The prldap_set_default_socket_info() function sets default socket information.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldappr.h&gt;
<pre>#include &lt;ldappr.h&gt;
int prldap_set_default_socket_info( LDAP *ld, PRLDAPSocketInfo *soip );</pre>  
int prldap_set_default_socket_info( LDAP *ld, PRLDAPSocketInfo *soip );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="prldap_set_default_socket_info() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="prldap_set_default_socket_info() Function Parameters"
Line 13,525: Line 12,082:
|}
|}


<br> '''Returns'''


'''Returns'''
<br>
 


*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
Line 13,533: Line 12,090:
*An LDAP API error code if an error occurs.
*An LDAP API error code if an error occurs.


<br> '''See Also'''


'''See Also'''
<br> prldap_get_socket_info()  
 
 
prldap_get_socket_info()  


=== prldap_set_session_info()  ===
=== prldap_set_session_info()  ===
Line 13,543: Line 12,098:
The prldap_set_session_info() function sets application-specific data.  
The prldap_set_session_info() function sets application-specific data.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldappr.h&gt;
<pre>#include &lt;ldappr.h&gt;
int prldap_set_session_info( LDAP *ld, void *sessionarg,
int prldap_set_session_info( LDAP *ld, void *sessionarg,
   PRLDAPSessionInfo *seip );</pre>  
   PRLDAPSessionInfo *seip );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="prldap_set_session_info() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="prldap_set_session_info() Function Parameters"
Line 13,566: Line 12,119:
|}
|}


<br> '''Returns'''


'''Returns'''
<br>
 


*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
*An LDAP API error code if an error occurs.
*An LDAP API error code if an error occurs.


<br> '''Description'''


'''Description'''
<br> The prldap_set_session_info() function sets application-specific data for an LDAP session handle or a session argument that is passed to the <tt>CONNECT</tt>, <tt>POLL</tt>, <tt>NEWHANDLE</tt>, or <tt>DISPOSEHANDLE</tt> extended I/O callbacks.  
 
 
The prldap_set_session_info() function sets application-specific data for an LDAP session handle or a session argument that is passed to the <tt>CONNECT</tt>, <tt>POLL</tt>, <tt>NEWHANDLE</tt>, or <tt>DISPOSEHANDLE</tt> extended I/O callbacks.  
 
 
'''See Also'''


<br> '''See Also'''


prldap_get_session_info()  
<br> prldap_get_session_info()  


=== prldap_set_session_option()  ===
=== prldap_set_session_option()  ===
Line 13,589: Line 12,138:
The prldap_set_session_option() function sets a session option specific to the <tt>prldap</tt> layer.  
The prldap_set_session_option() function sets a session option specific to the <tt>prldap</tt> layer.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldappr.h&gt;
<pre>#include &lt;ldappr.h&gt;
int prldap_set_session_option( LDAP *ld, void *sessionarg,
int prldap_set_session_option( LDAP *ld, void *sessionarg,
   int option, ... );</pre>  
   int option, ... );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="prldap_set_session_option() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="prldap_set_session_option() Function Parameters"
Line 13,612: Line 12,159:
|}
|}


<br> '''Returns'''


'''Returns'''
<br>
 


*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
*An LDAP API error code if an error occurs.
*An LDAP API error code if an error occurs.


<br> '''Description'''


'''Description'''
<br> The prldap_set_session_option() function sets an option for an LDAP session handle or a session argument that is passed to the <tt>CONNECT</tt> , <tt>POLL</tt>, <tt>NEWHANDLE</tt>, or <tt>DISPOSEHANDLE</tt> extended I/O callbacks.


<br> '''See Also'''


The prldap_set_session_option() function sets an option for an LDAP session handle or a session argument that is passed to the <tt>CONNECT</tt> , <tt>POLL</tt>, <tt>NEWHANDLE</tt>, or <tt>DISPOSEHANDLE</tt> extended I/O callbacks.
<br> prldap_get_session_option()  
 
 
'''See Also'''
 
 
prldap_get_session_option()  


=== prldap_set_socket_info()  ===
=== prldap_set_socket_info()  ===
Line 13,635: Line 12,178:
The prldap_set_socket_info() function sets socket information.  
The prldap_set_socket_info() function sets socket information.  


 
<br> '''Syntax'''  
'''Syntax'''
 
<pre>#include &lt;ldappr.h&gt;
<pre>#include &lt;ldappr.h&gt;
int prldap_set_socket_info( int fd, void *socketarg,
int prldap_set_socket_info( int fd, void *socketarg,
   PRLDAPSocketInfo *soip );</pre>  
   PRLDAPSocketInfo *soip );</pre>  
'''Parameters'''


'''Parameters'''
<br>
 


{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="prldap_set_socket_info() Function Parameters"
{| width="100%" cellspacing="1" cellpadding="1" border="1" summary="prldap_set_socket_info() Function Parameters"
Line 13,658: Line 12,199:
|}
|}


<br> '''Returns'''


'''Returns'''
<br>
 


*LDAP_SUCCESS if successful.  
*LDAP_SUCCESS if successful.  
*An LDAP API error code if an error occurs.
*An LDAP API error code if an error occurs.


<br> '''Description'''


'''Description'''
<br> The prldap_set_socket_info() function sets socket-specific information based on parameters passed to the extended I/O callback functions. For more information, see the <tt>ldappr.h</tt> header file.  
 
 
The prldap_set_socket_info() function sets socket-specific information based on parameters passed to the extended I/O callback functions. For more information, see the <tt>ldappr.h</tt> header file.  
 
 
'''See Also'''


<br> '''See Also'''


prldap_get_socket_info()
<br> prldap_get_socket_info()
MarkCraig
123

edits

Retrieved from "https://wiki.mozilla.org/Special:MobileDiff/283082"

Navigation menu