5.7. Working with Search Filters

When a client requests an LDAP search operation, the frontend passes the search filter to the backend as part of the parameter block. The filter is passed through the SLAPI_SEARCH_FILTER parameter. A string representation of the filter is also available in the SLAPI_SEARCH_STRFILTER parameter.
To manipulate search filters, call the following frontend routines:

Table 5.3. Frontend Functions for Manipulating Filters

Function Description
slapi_filter_test() Determine if an entry matches a filter's criteria.
slapi_filter_get_choice() Get the filter type.
slapi_filter_get_ava() Get the attribute type and value used for comparison in an attribute-value assertion filter. (Only applicable to the following searches: LDAP_FILTER_EQUALITY, LDAP_FILTER_GE, LDAP_FILTER_LE, and LDAP_FILTER_APPROX.)
slapi_filter_get_type() Get the type of attribute that the filter is searching for. (Only applicable to LDAP_FILTER_PRESENT searches.)
slapi_filter_get_subfilt() Get the substring pattern used for the filter. (Only applicable to LDAP_FILTER_SUBSTRING searches.)
slapi_str2filter() Convert a string representation of a filter to a filter of the data type Slapi_Filter.
slapi_filter_join() Construct a new LDAP_FILTER_AND, LDAP_FILTER_OR, or LDAP_FILTER_NOT filter from other filters.
slapi_filter_list_first()
slapi_filter_list_next()
Get the components of a filter. (Only applicable to LDAP_FILTER_AND, LDAP_FILTER_OR, and LDAP_FILTER_NOT searches.)
slapi_filter_free() Free a filter from memory.

5.7.1. Determining If an Entry Matches a Filter

After retrieving a filter from the SLAPI_SEARCH_FILTER parameter of the parameter block, you can call the slapi_filter_test() function to determine if entries in your database match the filter.

5.7.2. Getting the Filter Type

To determine the type of filter that you are using, call the slapi_filter_get_choice() function. This function returns the filter type, which can be any of the following values:

Table 5.4. Types of Filters

Filter Type Description
LDAP_FILTER_AND Find entries that match all filters that are specified in this complex filter.
LDAP_FILTER_OR Find entries that match any filter specified in this complex filter.
LDAP_FILTER_NOT Find entries that do not match the specified filter.
LDAP_FILTER_EQUALITY Find entries that contain a value equal to the specified attribute value.
LDAP_FILTER_SUBSTRINGS Find entries that contain a value that matches the specified substrings.
LDAP_FILTER_GE Find entries that contain a value greater than or equal to the specified attribute value.
LDAP_FILTER_LE Find entries that contain a value less than or equal to the specified attribute value.
LDAP_FILTER_PRESENT Find entries that contain the specified attribute.
LDAP_FILTER_APPROX Find entries that contain a value approximately matching the specified attribute value.

5.7.3. Getting the Search Criteria

You can use the following functions to retrieve the search criteria specified by a search filter:

Table 5.5. Functions used to Retrieve the Search Criteria Specified by Search Filters

To retrieve the search criteria for this filter type... Use this function...
LDAP_FILTER_EQUALITY
LDAP_FILTER_GE
LDAP_FILTER_LE
LDAP_FILTER_APPROX
slapi_filter_get_ava()
LDAP_FILTER_PRESENT slapi_filter_get_type()
LDAP_FILTER_SUBSTRINGS slapi_filter_get_subfilt()
LDAP_FILTER_AND
LDAP_FILTER_OR
LDAP_FILTER_NOT
slapi_filter_list_first() and slapi_filter_list_next()
Both of these functions will return either a filter component of the complex filter or a NULL value, according to the following:
  • If slapi_list_first() returns a NULL, the complex filter is not of the type LDAP_FILTER_AND, LDAP_FILTER_OR, or LDAP_FILTER_NOT.
  • If slapi_list_next() returns a NULL, the component returned by the call is the last component in the complex filter.

Note

You do not need to free the values returned by the slapi_filter_get_ava(), slapi_filter_get_type(), and slapi_filter_get_subfilt() functions.

5.7.4. Converting a String to a Filter

A search filter can be represented by either the data type Section 14.23, “Slapi_Filter” or as a string. In a parameter block for a search operation, SLAPI_SEARCH_FILTER is a filter of the data type Slapi_Filter and SLAPI_SEARCH_STRFILTER is the string representation of that filter. In general, it is easier to specify a filter as a string than it is to construct a filter from the type Slapi_Filter.
To convert the string representation of a filter into a filter of the data type Slapi_Filter, call the slapi_str2filter() function.
When you have finished working with the filter, you should free it from memory by calling the slapi_filter_free() function.

5.7.5. Creating Complex Filters by Combining Filters

AND, OR and NOT can combine different filters to create a complex filter. The slapi_filter_join() function can create these types of filters.
The slapi_filter_join() function returns the complex filter that you created. When you have finished using the complex filter, you should free it from memory by calling slapi_filter_free().
Filters of the type LDAP_FILTER_NOT can have only one component. If the filter type (ftype) is LDAP_FILTER_NOT, you must pass a NULL value for the second filter when calling slapi_filter_join().