7.4. Processing an LDAP Search Operation

The server processes an LDAP search operation in two stages:
  1. First, the server gets a list of candidate entries, using an index (if applicable).
    For example, for a search filter that finds entries where mail=a*, the server checks the index for the mail attribute (if the index exists), finds the keys that start with a, and generates a list of matching entries.
    If no applicable index exists, all entries are considered to be candidates.
    To get the list of candidates, the server calls the backend search function. For details, refer to Section 7.4.1, “Getting the List of Candidates”.
  2. Next, the server iterates through each candidate in the list and determines if the candidate matches the search criteria.
    If an entry matches the criteria, the server sends the entry to the client.
    To check each candidate, the server calls the backend next_candidate function for each candidate in the list. For details, refer to Section 7.4.2, “Iterating through Candidates”.
The rest of this section explains these stages in more detail.

7.4.1. Getting the List of Candidates

When the Directory Server receives an LDAP search request, the frontend gets information about the search (such as the scope and base DN). The frontend normalizes the base DN by calling the slapi_sdn_get_ndn() function and determines if the base DN identifies a DSA-specific entry (DSE). If so, the frontend handles the search request directly and does not pass it to the backend search function.
If the base DN is not a DSE, the frontend finds the backend that services the suffix specified in the base DN. The frontend then passes the search criteria to the search function for that backend.
The frontend makes this information available to pre-operation and post-operation plug-in functions in the form of parameters in a parameter block.

Table 7.2. Table of Information Available during an LDAP Search Operation

Parameter ID Data Type Description
SLAPI_SEARCH_TARGET char * DN of the base entry in the search operation (the starting point of the search).
SLAPI_ORIGINAL_TARGET_DN char * The original DN sent by the client (this DN is normalized by SLAPI_SEARCH_TARGET); read-only parameter.
SLAPI_SEARCH_SCOPE int The scope of the search. The scope can be one of the following values:
  • LDAP_SCOPE_BASE
  • LDAP_SCOPE_ONELEVEL
  • LDAP_SCOPE_SUBTREE
SLAPI_SEARCH_DEREF int Method for handling aliases in a search. This method can be one of the following values:
  • LDAP_DEREF_NEVER
  • LDAP_DEREF_SEARCHING
  • LDAP_DEREF_FINDING
  • LDAP_DEREF_ALWAYS
SLAPI_SEARCH_SIZELIMIT int Maximum number of entries to return in the search results.
SLAPI_SEARCH_TIMELIMIT int Maximum amount of time (in seconds) allowed for the search operation.
SLAPI_SEARCH_FILTER Slapi_Filter * Slapi_Filter struct (an opaque data structure) representing the filter to be used in the search.
SLAPI_SEARCH_STRFILTER char * String representation of the filter to be used in the search.
SLAPI_SEARCH_ATTRS char ** Array of attribute types to be returned in the search results.
SLAPI_SEARCH_ATTRSONLY int Specifies whether the search results return attribute types only or attribute types and values. (0 means return both attributes and values; 1 means return attribute types only).
Your search function should return 0 if successful. Call the slapi_pblock_set() function to assign the set of search results to the SLAPI_SEARCH_RESULT_SET parameter in the parameter block.
The frontend then uses this function in conjunction with the next entry function (refer to Section 7.4.2, “Iterating through Candidates”) to iterate through the result set. The frontend sends each result back to the client and continues updates the SLAPI_NENTRIES parameter with the current number of entries sent back to the client.
If a result is actually a referral, the frontend sends the referral back to the client and updates the SLAPI_SEARCH_REFERRALS parameter with the list of referral URLs.
Finally, after sending the last entry to the client, the frontend sends an LDAP result message specifying the number of entries found.

7.4.2. Iterating through Candidates

In addition to the parameters specified in Section 7.4, “Processing an LDAP Search Operation”, the next entry function has access to the following parameters (which are set by the frontend and the backend during the course of executing a search operation):

Table 7.3. Table of Information Available to the next entry Function

Parameter ID Data Type Description
SLAPI_SEARCH_RESULT_SET void * Set of search results. These data are specific to the backend processing the search. Any plug-in functions should not touch this value.
SLAPI_SEARCH_RESULT_ENTRY Slapi_Entry * Entry returned from iterating through the results set. This next entry function actually sets this parameter.
SLAPI_SEARCH_RESULT_ENTRY_EXT void * Reserved for future use. The context identifying the last result sent in the results set. This next entry function actually sets this parameter.
SLAPI_NENTRIES int Number of search results found.
SLAPI_SEARCH_REFERRALS struct berval ** NULL-terminated array of the URLs to other LDAP servers to which the current server is referring the client.
The next entry function should get the next result specified in the set of results in the SLAPI_SEARCH_RESULT_SET parameter. The function should set this next entry as the value of the SLAPI_SEARCH_RESULT_ENTRY parameter in the parameter block, and the next entry function should return 0 if successful.
The next entry function should set the SLAPI_SEARCH_RESULT_ENTRY parameter to NULL and return -1 if one of the following situations occurs:
  • The operation is abandoned (you can check this by calling the slapi_op_abandoned() function).
  • The time limit has been exceeded.
  • The maximum number of entries has been exceeded.
If no more entries exist in the set of results, the next entry function should set the SLAPI_SEARCH_RESULT_ENTRY parameter to NULL and return 0.