| Sun Java System LDAP SDK for C Programming Guide |
Chapter 6
Using Filter Configuration FilesIn addition to the search functions detailed in Chapter 5, "Searching a LDAP Directory," Sun™ Java System LDAP SDK for C contains functions for integrating filter configuration files into the search. This chapter explains about filter configuration files and how to use them with the SDK. It contains the following sections:
Filter Configuration FilesFilter configuration files can help simplify the process of selecting the appropriate filter for a search request. A filter configuration file contains a list of filters that you can load and use in your searches. If you are writing a client that allows users to search the directory, you might want to use different search filters tailored for specific types of search criteria. For example, if the user wants to search for this email address:
bjensen@example.com
You might want to use this search filter:
(mail=bjensen@example.com)
Similarly, suppose the search term entered by the user contains numbers, as in:
555-1212
In this case, you might want to use this search filter:
(telephoneNumber=555-1212)
Rather than write code to find and select the appropriate filter, you can include the filters in a filter configuration file. For example, Code Example 6-1 is a section of a filter configuration file specifying one filter for telephone numbers and two filters for email addresses. The telephone number filter is used if the search criteria contains one or more numbers. The email filters are used if the search criteria contains an “at” sign (@).
Note
You should specify the filters in the order that you want them to be used. For example, if you want to apply the (mail=%v) filter before the (mail=%v*) filter, make sure that the filters appear in that order.
The Filter Configuration File Syntax
A filter configuration file has the format illustrated in Code Example 6-2. The variables are discussed in the sections following.
Code Example 6-2 Syntax for Filter Configuration File
tag
pattern1 delimiters filter1-1 desc1-1 [scope]
filter1-2 desc1-2 [scope]
pattern2 delimiters filter2-1 desc2-1 [scope]
...
Tag
A tag identifies a group of filters. You can use different tags to distinguish filters for different types of objects. For example, you can use one tag to represent filters for person entries, another tag to represent filters for organization entries, and so on.
"people"
... (filters for searching "person" entries) ...
"organization"
... (filters for "organization" entries) ...
When you call functions like ldap_getfirstfilter() to retrieve a filter, you can specify a tag (or part of a tag) as a parameter. The tag narrows the list of filters that the function can retrieve.
Patterns
pattern1 and pattern2 are regular expressions used to determine which filter is selected, based on the search criteria. For example, if you specify "^[0-9]" as the pattern for a filter, the filter is selected for all search criteria beginning with a number.
"people"
"^[0-9]" ...
Note
For more information on regular expressions, consult your UNIX® documentation. (For example, documentation on the ed command contains some information on regular expressions.)
Delimiters
Delimiters specifies the delimiters used to distinguish one field from another within the search criteria. For example, if the search criteria consists of a city name and state abbreviation separated by a comma, specify “,” as the delimiter.
Filters
filter1-1, filter1-2, and filter2-1 are filters. Use %v to represent the search criteria. For example, to search e-mail addresses, use the filter (mail=%v). During runtime, if the search criteria bjensen@example.com is entered, the filter becomes (mail=bjensen@example.com).
If the search criteria consists of a number of delimited fields (for example, a "last name, first name" format like "Jensen, Barbara"), use %v1, %v2, ... , %vn to represent the different fields within the search criteria as in:
"people"
"^[A-Z]*," "," (&(sn=%v1)(givenName=%v2))
In this example, the delimiter is a comma. The word before the delimiter replaces %v1 in the filter, and the word after the delimiter replaces %v2 in the filter. If the user searches for:
Jensen, Barbara
The resulting filter is:
(&(sn=Jensen)(givenName=Barbara))
You can also specify ranges of fields. For example, to specify the values in the first three fields, use %v1-3. To specify values from the third field to the last field, use %v3-. To specify the value in the last field, use %v$.
Descriptions
desc1-1, desc1-2, and desc2-1 are phrases briefly describing the filters.
Filter Parameters
Table 6-1 lists the parameters that can be used within a filter.
Table 6-1 Filter Parameters
Parameter
Description
%v
This parameter means that the entire search criteria is inserted in place of %v. For example, if the filter is (mail=%v), entering the word jensen results in the filter (mail=jensen).
%v$
This parameter means that the last word in the search criteria is inserted in place of %v. For example, if the filter is (sn=%v), entering the words Barbara Jensen results in the filter (sn=Jensen).
%vN
N is a single digit between 1 and 9. This parameter means that the Nth word in the search criteria is inserted in place of %vN. For example, if the filter is (sn=%v2), entering the words Barbara Jensen results in the filter (sn=Jensen).
%vM-N
M and N are single digits between 1 and 9. This parameter means that the sequence of the Mth through the Nth words in the search criteria is inserted in place of %vM-N. For example, if the filter is (cn=%v1-2), entering the words Barbara Jensen results in the filter (cn=Barbara Jensen).
%vN-
N is a single digit between 1 and 9. This parameter means that the sequence of the Nth through the last words in the search criteria is inserted in place of %vN-. For example, if the filter is (cn=%v2-), entering the words Ms. Barbara Jensen results in the filter (cn=Barbara Jensen).
Loading a Filter Configuration FileTo load a filter configuration file, call the ldap_init_getfilter() function. You can also read the filter configuration file from a buffer in memory by calling the ldap_init_getfilter_buf() function. Both functions return a pointer to an LDAPFiltDesc structure, which contains information about the filter. If an error occurs, both functions return NULL.
Retrieving Filters
After loading a filter configuration file into memory, you can retrieve filters based on the search criteria. For example, if the search criteria is an e-mail address (bjensen@example.com), you can have your client automatically search for this value in the mail attribute of person entries.
To retrieve the first filter that matches the search criteria, call the ldap_getfirstfilter() function. To get the next filter that matches the search criteria, call the ldap_getnextfilter() function. Both functions return a pointer to an LDAPFiltInfo structure, which contains information about the filter. Code Example 6-3 retrieves filters that match the search criteria.
Code Example 6-3 Retrieving Configuration Filters
#include <stdio.h>
#include <ldap.h>
...
LDAP *ld;
LDAPMessage *result, *e;
BerElement *ber;
char *a, *dn;
char **vals;
int i;
LDAPFiltDesc *ldfp;
LDAPFiltInfo *ldfi;
char buf[ 80 ]; /* contains the search criteria */
int found;
...
/* Load the filter configuration file into an LDAPFiltDesc structure. */
if ( ( ldfp = ldap_init_getfilter( "myfilters.conf" ) ) == NULL ) {
perror( "Cannot open filter configuration file" );
}
/* Select a filter to use when searching for the value in buf.
Use filters under the "people" tag in the filter configuration file. */
found = 0;
for ( ldfi = ldap_getfirstfilter( ldfp, "people", buf ); ldfi != NULL;
ldfi = ldap_getnextfilter( ldfp ) ) {
/* Use the selected filter to search the directory. */
if ( ldap_search_s( ld, "dc=example,dc=com", ldfi->lfi_scope,
ldfi->lfi_filter, NULL, 0, &result ) != LDAP_SUCCESS ) {
ldap_perror( ld, "ldap_search_s" );
return( 1 );
} else {
/* Once a filter gets results back, stop iterating through
the different filters. */
if ( ( found = ldap_count_entries( ld, result ) > 0 ) ) {
break;
} else {
ldap_msgfree( result );
}
}
}
if ( found == 0 ) {
printf( "No matching entries found.\n" );
} else {
printf( "Found %d match%s where %s \"%s\"\n\n", found,
found == 1 ? "" : "es", ldfi->lfi_desc, buf );
}
ldap_msgfree( result );
ldap_getfilter_free( ldfp );
...
Suppose that the search criteria is bjensen@example.com and the client application finds one matching entry. In this case, the application prints the following output:
Found 1 match where email address is bjensen@example.com
Filter Prefixes and SuffixesIf you need to apply a filter to all searches, you can add a filter prefix and suffix to all filters (rather than add the criteria to all filters). The prefix is automatically added to any filter retrieved through the ldap_getfirstfilter() and ldap_getnextfilter() functions as is the required suffix [)] needed to balance the number of parentheses. For example, suppose you use this filter in a filter configuration file:
(cn=Babs Jensen)
If you retrieve this filter using ldap_getfirstfilter() or ldap_getnextfilter(), you would get a filter that constrains your client searches to person entries for the defined filter:
(&(objectClass=person)(cn=Babs Jensen))
To add a prefix and suffix automatically to all filters retrieved from the filter configuration file, call the ldap_set_filter_additions() function. Code Example 6-4 loads the filter configuration file named myfilters.conf into memory and adds the prefix (&(objectClass=person) and the suffix ) to each filter retrieved.
Code Example 6-4 Adding Prefixes and Suffixes
#include <ldap.h>
...
LDAPFiltDesc *lfdp;
char *filter_file = "myfilters.conf";
char *prefix = "(&(objectClass=person)";
char *suffix = ")";
...
lfdp = ldap_init_getfilter( filter_file );
ldap_setfilteraffixes( lfdp, prefix, suffix );
...
Freeing Filters from MemoryWhen you complete your search, you should free the LDAPFiltDesc structure from memory. To free LDAPFiltDesc, call the ldap_getfilter_free() function. Code Example 6-5 frees LDAPFiltDesc from memory after all searches are completed.
Code Example 6-5 Freeing Filters from Memory
#include <ldap.h>
...
LDAPFiltDesc *lfdp;
char *filter_file = "myfilters.conf";
...
/* Read the filter configuration file into an LDAPFiltDesc structure. */
lfdp = ldap_init_getfilter( filter_file );
...
/* Retrieve filters and perform searches. */
...
/* Free the configuration file (the LDAPFiltDesc structure). */
ldap_getfilter_free( lfdp );
...
Creating Filters ProgrammaticallyYou can build your own filters by calling the ldap_create_filter() function. Code Example 6-6 builds the filter (mail=bjensen@example.com).
Code Example 6-6 Creating Filters
char buf[LDAP_FILT_MAXSIZ];
char *pattern = "(%a=%v);
char *attr = "mail";
char *value = "bjensen@example.com";
...
ldap_create_filter( buf, LDAP_FILT_MAXSIZ, pattern, NULL, NULL, attr,
value, NULL );
...
