Table of Contents | Previous | Next | Index

Netscape Directory SDK 3.0 for C Programmer’s Guide
Chapter 18 Functions

ldap_search_ext()

Searches the directory asynchronously.

Syntax

#include <ldap.h>
int ldap_search_ext( LDAP *ld, const char *base, int scope, 
   const char *filter, char **attrs, int attrsonly, 
   LDAPControl **serverctrls, LDAPControl **clientctrls, 
   struct timeval *timeoutp, int sizelimit, int *msgidp );

This function is a new version of the ldap_search() function. If you are writing a new LDAP client, you should call this function instead of ldap_search().

You can 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 on these controls.)

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() instead. (For more information on asynchronous and synchronous functions, see "Calling Synchronous and Asynchronous Functions" on page 80.)

In order to get the results of the LDAP search operation, you need to call the ldap_result() function and the ldap_parse_result() function. (See "Getting Results Asynchronously" on page 121 for details.) For a list of possible result codes for an LDAP search operation, see the result code documentation for the ldap_search_ext_s() function.

For more information on searching the directory, see Chapter 6, "Searching the Directory".

Example

See the example under "Example: Searching the Directory (Asynchronous)" on page 140.

ld	Connection handle, which is a pointer to an `LDAP` structure containing information about the connection to the LDAP server.
base	Distinguished name (DN) of the entry that serves as the starting point for the search. For example, setting `base` to `"o=Airius.com"` restricts the search to entries at Airius.com.
scope	Scope of the search, which can be one of the following values: `LDAP_SCOPE_BASE` searches the entry specified by `base`. `LDAP_SCOPE_ONELEVEL` searches all entries one level beneath the entry specified by `base`. `LDAP_SCOPE_SUBTREE` searches the entry specified by `base` and all entries at all levels beneath the entry specified by `base`.
filter	String representation of the filter to apply in the search. You can specify simple filters with the following syntax: `(``attributetype``=``attributevalue``)` For details on the syntax for filters, see "Specifying a Search Filter" on page 113.
attrs	A NULL-terminated array of attribute types to return from entries that match filter. If you specify a NULL, all attributes will be returned.
attrsonly	Specifies whether or not attribute values are returned along with the attribute types. This parameter can have the following values: 0 specifies that both attribute types and attribute values are returned. 1 specifies that only attribute types are returned.
serverctrls	Pointer to an array of `LDAPControl` structures representing LDAP server controls that apply to this LDAP operation. If you do not want to pass any server controls, specify NULL for this argument.
clientctrls	Pointer to an array of `LDAPControl` structures representing LDAP client controls that apply to this LDAP operation. If you do not want to pass any client controls, specify NULL for this argument.
timeoutp	Pointer to a `timeval` structure specifying the maximum time to wait for the results of the search. Pass NULL to use the default time limit for the current connection. To specify an infinite time limit, set the `tv_sec` and `tv_usec` fields in the `timeval` structure to 0.
sizelimit	Maximum number of results to return in the search. Pass -1 to use the default size limit for the current connection.
msgidp	Pointer to an integer that will be set to the message ID of the LDAP operation. To check the result of this operation, call `ldap_result()` and `ldap_parse_result()` functions.

ldap_search_ext()

Syntax

Parameters

Returns

Description

Example

See Also