The server processes an LDAP search operation in two stages:
The rest of this section explains these stages in more detail.
Getting the List of Candidates
In the parameter block, the SLAPI_PLUGIN_DB_SEARCH_FN parameter specifies the database search function.
When the Directory Server receives an LDAP search request, the front-end gets information about the search (such as the scope and base DN). The front-end normalizes the base DN (by calling the slapi_dn_normalize() function) and determines if the base DN identifies a DSA-specific entry (DSE). If so, the front-end handles the search request directly and does not pass it to the database search function.
If the base DN is not a DSE, the front-end finds the back-end that services the suffix specified in the base DN. The front-end then passes the search criteria to the search function for that back-end.
The front-end makes this information available to pre-operation, database, and post-operation plug-in functions in the form of parameters in a parameter block. .
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 front-end then uses this function in conjunction with the "next entry" function (see "Iterating through Candidates" on page 104) to iterate through the result set. The front-end 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 front-end 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 front-end sends an LDAP result message specifying the number of entries found.
Iterating through Candidates
In the parameter block, the SLAPI_PLUGIN_DB_NEXT_SEARCH_ENTRY_FN parameter specifies the database function used to iterate through the list of candidates and determine if each candidate matches the search criteria.
In addition to the parameters specified in "Processing an LDAP Search Operation" on page 101, the "next entry" function has access to the following parameters (which are set by the front-end and the back-end during the course of executing a search operation): .
The "next entry" function should get the next result specified in the set of results in the parameter SLAPI_SEARCH_RESULT_SET. 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:
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.