ldapSearchReqstLim(3ibx) — Subroutines
NAME
ldapSearchReqstLim − Conducts an asynchronous search through a directory tree, and sets limitations on the search time and on the number of entries returned.
SYNOPSIS
| #include <libldap.h> | ||
| int ldapSearchReqstLim( | LDAP_t ∗ldap_handle, | |
| char ∗base, | ||
| int scope, | ||
| char ∗filter, | ||
| char ∗∗attribute_names, | ||
| int no_attributes_flag, | ||
| int size_limit, | ||
| int time_limit ); |
MODIFIED PARAMETER
ldap_handleAn address of an LDAP handler; this call modifies the handle so that a subsequent call to the ldapFirstEntry function succeeds.
INPUT PARAMETERS
baseThe address of a string containing a distinguished name. This name is the node (directory entry) in the directory tree with which to begin the search.
scopeOne of the following LDAP_SCOPE_constraint constants that constrain the area of the tree in which to search:
| LDAP_SCOPE_BASE | Search only the directory | |
| entry specified by the base | ||
| parameter; this is also | ||
| called the "search base." | ||
| LDAP_SCOPE_ONELEVEL | Search the base and one level | |
| down in the tree. | ||
| LDAP_SCOPE_SUBTREE | Search the whole subtree | |
| that begins with the base | ||
| node. |
filterAn address of a string containing an expression. When evaluated against an attribute in a directory entry, the expression must evaluate to TRUE in order for the search to return a given entry. A search filter has the following format:
(operator (expression) (expression))
The operator item is one of the following logical operators:
| Operator | Name | Description |
| | | OR | TRUE, if either expression is |
| TRUE. | ||
| & | AND | TRUE, if both expressions are |
| TRUE. | ||
| ! | NOT | TRUE, if the expression is not |
| TRUE. |
Here is the format for the expression item in the previous format description:
attribute_name operator2 attribute_value
The attribute_name item is an attribute name defined in the schema. The attribute_value item is the attribute value for which the server searches. The operator2 item can be one of the following operators:
| Operator | Name | Description |
| = | Equals | The server returns directory entries whose |
| attribute values exactly match the |
||
| attribute_value in the search filter. |
||
| For example, (commonName=Pete) results in the |
||
| server returning entries with the commonName |
||
| attribute value "Pete". | ||
| ~= | Approximate | The server returns directory entries that |
| "approximately match" the attribute values |
||
| attribute_value in the search filter. |
||
| For example, (surname~=Olson) results in the |
||
| server returning entries with the surname |
||
| attribute values "Olson" or "Olsen". | ||
| =∗ | Present | The server returns all directory entries |
| that have the attribute_name specified |
||
| in the filter. For example, (surname=∗) results |
||
| in the server returning entries that have a |
||
| surname attribute name, regardless of the |
||
| attribute’s value. |
attribute_namesAn array of strings containing the list of attribute names that you would like returned in the entry_chain parameter of the ldapSearchResult. The search returns only the requested attributes names. Also, the search may not return the names in the order in which you specified them in this parameter.
If you specify an invalid attribute name, the server ignores it.
no_attributes_flagAn integer that, if TRUE, indicates that ldapSearchReqst should return only the attribute names, and, if FALSE, indicates that this function should return both the names and the values.
size_limitAn integer that specifies the maximum number of entries to return.
time_limitAn integer that specifies the maximum number of seconds for the search.
DESCRIPTION
After you call ldapSearchReqstLim, you can either call ldapPoll periodically or wait until the time_limit has expired to determine whether the asynchronous search is complete. When it is complete, call the ldapSearchResult function to read the directory-entry chain.
Since you cannot be certain of the order in which the server will be able to respond to your asynchronous requests, you should make only one asynchronous search request at a time for a given LDAP handle. Once the request completes (or once you abandon the request), you can make another asynchronous search request on that handle.
RETURNS
One of the LDAP standard return values: LDAP_message.
RELATED INFORMATION
Functions: ldapAbandon(3), ldapFirstEntry(3), ldapPoll(3), ldapSearchReqst(3), ldapSearchResult(3), ldapSearchWLim(3).