Handling Extensible Match Filters
This section explains and demonstrates how to handle extensible match filters corresponding to a matching rule. All matching rule plug-ins must enable filter matching.
How Directory Server Handles Extensible Match Searches
-
When Directory Server receives a search request containing an extensible match filter, the server calls the filter factory function in the plug-in handling the corresponding matching rule. The server passes the filter factory a parameter block containing the extensible match filter information.
-
The filter factory function builds a filter object. The function then sets pointers to the object as well as the appropriate filter matching and filter index functions.
-
The server attempts to look up a set of results in an index rather than searching the entire directory.
In order to read an index, the server calls the filter index function, which helps the server locate the appropriate indexer function.
Directory Server only considers all entries in the directory, which can slow the search considerably if one of the following is the case:
-
No existing index applies to the search
-
The plug-in specifies no indexer function
-
The plug-in generates no keys for the values specified
Directory Server calls the indexer function to generate the keys. Refer to Indexer Function for details about that function.
-
-
Directory Server verifies that the entry is in the scope of the search before returning the entry to the client as a search result.
-
Directory Server frees memory that was allocated for the operation.
The following process describes how Directory Server handles an extensible match search.
The following figure shows how Directory Server processes the search request.
Figure 11–1 Directory Server Performing an Extensible Match Search
The main filter functions are as follows:
Filter Matching Function
The filter matching function takes pointers to the filter object, the entry, and the first attribute to check for a match.
The following figure shows how Directory Server uses the filter matching function.
Figure 11–2 Filter Match Function Context
Notice that the filter matching function returns 0 (match) -1 (no match) or an LDAP error code for each entry processed.
Example 11–3 Filter Match Function (matchingrule.c)
This example shows the filter match function for the case exact matching rule where a match occurs when the two berval structures match.
#include "slapi-plugin.h"
typedef struct plg_filter_t /* For manipulating filter obj. */
{ char * f_type; /* Attribute type to match */
int f_op; /* Type of comparison
* (<, <=, ==, >=, >, substr)
* for the filter. */
struct berval ** f_values; /* Array of values to match */
} plg_filter_t;
/* Check for a match against the filter.
* Returns: 0 filter matched
* -1 filter did not match
* > 0 an LDAP Error code */
static int
plg_filter_match(
void * obj, /* Matching rule object */
Slapi_Entry * entry, /* Entry to match */
Slapi_Attr * attr /* Attributes to match */
)
{
plg_filter_t * fobj = (plg_filter_t *)obj;
struct berval * mrVal = NULL; /* Values handled as bervals... */
Slapi_Value * sval; /* ...and as Slapi_Value structs*/
int rc = -1; /* No match */
if (fobj && fobj->f_type && fobj->f_values && fobj->f_values[0]) {
mrVal = fobj->f_values[0];
/* Iterate through the attributes, matching subtypes. */
for (; attr != NULL; slapi_entry_next_attr(entry, attr, &attr)) {
char * type = NULL; /* Attribute type to check */
if ((slapi_attr_get_type(attr, &type) == 0) &&
(type != NULL) &&
(slapi_attr_type_cmp(fobj->f_type, type, 2) == 0)
) { /* slapi_attr_type_cmp(type1, type2, ==>2<==)
* matches subtypes, too. Refer to the reference
* documentation for details. */
/* Type and subtype match, so iterate through the
* values of the attribute. */
int hint = slapi_attr_first_value(attr, &sval);
while (hint != -1) {
const struct berval * val =
slapi_value_get_berval(sval);
/* The case exact matching rule
* compares the two bervals.
*
* Your matching rule may do
* lots of different checks here. */
rc = slapi_berval_cmp(val, mrVal);
if (rc == 0) { /* Successful match */
/* If you have allocated memory for a custom
* matching rule, do not forget to release it. */
return 0;
}
hint = slapi_attr_next_value(attr, hint, &sval);
}
}
}
}
return rc;
}
Notice that checking for a case exact match involves only slapi_berval_cmp(), which performs a byte by byte comparison. Your plug-in might do something more complex for the comparison.
Subtype Matches
Notice in the code for iterating through the attributes that slapi_attr_type_cmp() takes 2, the value assigned to SLAPI_TYPE_CMP_SUBTYPE, as its third argument. The argument forces a comparison of attribute subtypes, such as the locale of an attribute, in addition to attribute types. Refer to Part II, Directory Server Plug-In API Reference for details on plug-in API functions and their arguments.
Thread Safety and Filter Matching Functions
Directory Server never calls a filter matching function for the same filter object concurrently. Directory Server can, however, call the function concurrently for different filter objects. If you use global variables, ensure that your filter matching function handles such variables safely.
Filter Index Function
The filter index function takes a parameter block from Directory Server. The function also sets pointers in the parameter block, enabling the server to read the index.
Example 11–4 Filter Index Function (matchingrule.c)
This example shows the filter index function for the case exact matching rule where the keys are the same as the values.
#include "slapi-plugin.h"
#define PLG_OID "1.3.6.1.4.1.42.2.27.999.4.1"
#define SUBSYS "CaseExactMatching Plugin"
typedef struct plg_filter_t /* For manipulating filter obj. */
{ char * f_type; /* Attribute type to match */
int f_op; /* Type of comparison
* (<, <=, ==, >=, >, substr)
* for the filter. */
struct berval ** f_values; /* Array of values to match */
} plg_filter_t;
static int
plg_filter_index(Slapi_PBlock * pb)
{
int rc = LDAP_UNAVAILABLE_CRITICAL_EXTENSION;
void * obj = NULL; /* Server lets the plug-in */
plg_filter_t * fobj; /* handle the object type. */
int query_op = SLAPI_OP_EQUAL; /* Only exact matches */
if (!slapi_pblock_get(pb, SLAPI_PLUGIN_OBJECT, &obj)) {
fobj = (plg_filter_t *)obj;
/* Case exact match requires no modifications to
* the at this point. Your plug-in may however
* modify the object, then set it again in the
* parameter block. */
rc = slapi_pblock_set( /* This is for completeness. */
pb, /* Your plug-in may modify */
SLAPI_PLUGIN_OBJECT, /* the object if necessary. */
fobj
);
rc |= slapi_pblock_set( /* Set attr type to match. */
pb,
SLAPI_PLUGIN_MR_TYPE,
fobj->f_type
);
rc |= slapi_pblock_set( /* Set fcn to obtain keys. */
pb,
SLAPI_PLUGIN_MR_INDEX_FN,
(void*)plg_index_entry
);
rc |= slapi_pblock_set( /* Set values to obtain keys. */
pb,
SLAPI_PLUGIN_MR_VALUES,
fobj->f_values
);
rc |= slapi_pblock_set( /* This is for completeness. */
pb, /* Your plug-in may set a */
SLAPI_PLUGIN_MR_OID, /* different MR OID than the */
PLG_OID /* one in the parameter block */
);
rc |= slapi_pblock_set( /* <, <=, ==, >=, >, substr */
pb, /* In this case, == */
SLAPI_PLUGIN_MR_QUERY_OPERATOR,
&query_op
);
}
return rc;
}
This code uses the variables and macros that follow:
-
fobj->ftype indicates the attribute type that is specified in the filter.
-
plg_index_entry() indicates the indexer function for generating keys from values.
-
fobj->values points to the berval array of attribute values.
-
PLG_OID is the object identifier of the matching rule.
-
query_op indicates the query operator from the filter.
Input Parameters for Filter Index Functions
A filter index function can get a pointer to the filter object from SLAPI_PLUGIN_OBJECT in the parameter block.
Output Parameters for Filter Index Functions
A filter index function should set values for at least the following in the parameter block before returning control to Directory Server:
-
SLAPI_PLUGIN_MR_INDEX_FN, the pointer to the indexer for generating the keys
-
SLAPI_PLUGIN_MR_OID
-
SLAPI_PLUGIN_MR_QUERY_OPERATOR
-
SLAPI_PLUGIN_MR_TYPE
-
SLAPI_PLUGIN_MR_VALUES
-
SLAPI_PLUGIN_OBJECT, if modified by your function
Refer to Chapter 18, Parameter Block Reference for details.
Thread Safety and Filter Index Functions
Directory Server never calls a filter index function for the same filter object concurrently. Directory Server can, however, call the function concurrently for different filter objects. If you use global variables, ensure that your function handles such variables safely.
Filter Factory Function
The filter factory function takes a parameter block from Directory Server. The function then sets parameters such that Directory Server can build a list of candidate entries, candidates the server checks for matches.
The following figure shows how the filter factory function operates.
Figure 11–3 Filter Factory Function Context
The following example shows the filter factory function for the case exact matching rule.
Example 11–5 Filter Factory Function (matchingrule.c)
#include "slapi-plugin.h"
#define PLG_OID "1.3.6.1.4.1.42.2.27.999.4.1"
#define SUBSYS "CaseExactMatching Plugin"
/* Functions to obtain connection information for logging. */
static long mypblock_get_msgid( Slapi_PBlock * pb);
static int mypblock_get_connid(Slapi_PBlock * pb);
static int mypblock_get_opid( Slapi_PBlock * pb);
typedef struct plg_filter_t /* For manipulating filter obj. */
{ char * f_type; /* Attribute type to match */
int f_op; /* Type of comparison
* (<, <=, ==, >=, >, substr)
* for the filter. */
struct berval ** f_values; /* Array of values to match */
} plg_filter_t;
static int
plg_filter_create(Slapi_PBlock * pb)
{
int rc = LDAP_UNAVAILABLE_CRITICAL_EXTENSION;
char * mr_oid = NULL; /* MR OID from the server */
char * mr_type = NULL; /* Attr type to match */
struct berval * mr_value = NULL; /* Attr value to match */
plg_filter_t * fobj = NULL; /* Object to create */
if (
slapi_pblock_get(pb, SLAPI_PLUGIN_MR_OID, &mr_oid) ||
(mr_oid == NULL)
) {
slapi_log_error_ex(
-1, /* errorId */
mypblock_get_msgid(pb),
mypblock_get_connid(pb),
mypblock_get_opid(pb),
SUBSYS,
SLAPI_INTERNAL_ERROR,
"plg_filter_create failed: NULL OID values are invalid.\n"
);
}
else if (strcmp(mr_oid, PLG_OID) == 0) {
/* The MR OID from the server is handled by this plug-in. */
if (
(slapi_pblock_get(pb, SLAPI_PLUGIN_MR_TYPE, &mr_type) == 0) &&
(mr_type != NULL) &&
(slapi_pblock_get(pb, SLAPI_PLUGIN_MR_VALUE, &mr_value) == 0) &&
(mr_value != NULL)
) { /* ...provide a pointer to a filter match function. */
int op = SLAPI_OP_EQUAL;
fobj = (plg_filter_t *)slapi_ch_calloc(
1,
sizeof (plg_filter_t)
);
fobj->f_type = slapi_ch_strdup(mr_type);
fobj->f_op = op;
fobj->f_values = (struct berval **)slapi_ch_malloc(
2 * sizeof(struct berval *)
);
fobj->f_values[0] = slapi_ch_bvdup(mr_value);
fobj->f_values[1] = NULL;
rc = slapi_pblock_set( /* Set object destructor. */
pb,
SLAPI_PLUGIN_DESTROY_FN,
(void *)plg_filter_destroy
);
rc |= slapi_pblock_set( /* Set object itself. */
pb,
SLAPI_PLUGIN_OBJECT,
(void *)fobj
);
rc |= slapi_pblock_set( /* Set filter match fcn. */
pb,
SLAPI_PLUGIN_MR_FILTER_MATCH_FN,
(void *)plg_filter_match
);
rc |= slapi_pblock_set( /* Set sorting function. */
pb,
SLAPI_PLUGIN_MR_FILTER_INDEX_FN,
(void *)plg_filter_index
);
if (rc == 0) {
slapi_log_info_ex(
SLAPI_LOG_INFO_AREA_PLUGIN,
SLAPI_LOG_INFO_LEVEL_DEFAULT,
mypblock_get_msgid(pb),
mypblock_get_connid(pb),
mypblock_get_opid(pb),
SUBSYS,
"plg_filter_create (oid %s; type %s) OK\n",
mr_oid, mr_type
);
} else {
slapi_log_error_ex(
-1, /* errorId */
mypblock_get_msgid(pb),
mypblock_get_connid(pb),
mypblock_get_opid(pb),
SUBSYS,
SLAPI_INTERNAL_ERROR,
"plg_filter_create (oid %s; type %s) - pblock error \n",
mr_oid, mr_type
);
}
} else { /* Missing parameters in the pblock */
slapi_log_error_ex(
-1,
mypblock_get_msgid(pb),
mypblock_get_connid(pb),
mypblock_get_opid(pb),
SUBSYS,
"Parameter errors ",
"plg_filter_create: invalid input pblock.\n"
);
}
}
return rc;
}
Notice that this function returns LDAP_UNAVAILABLE_CRITICAL_EXTENSION if the function does not handle the matching rule OID in the parameter block. Refer to Handling an Unknown Matching Rule.
Input Parameters for Filter Factory Functions
A filter factory function can get values for the following from the parameter block:
-
SLAPI_PLUGIN_MR_OID
-
SLAPI_PLUGIN_MR_TYPE
-
SLAPI_PLUGIN_MR_VALUE
-
SLAPI_PLUGIN_PRIVATE, if your plug-in uses private data that is specified in the plug-in initialization function
Output Parameters for Filter Factory Functions
An indexer factory function should set values for the following in the parameter block before returning control to Directory Server:
-
SLAPI_PLUGIN_DESTROY_FN, a pointer to the destructor for the filter object
-
SLAPI_PLUGIN_MR_FILTER_INDEX_FN, a pointer to the filter index function
-
SLAPI_PLUGIN_MR_FILTER_MATCH_FN, a pointer to the filter match function
-
SLAPI_PLUGIN_MR_FILTER_RESET_FN, if required, a pointer to the filter reset function
-
SLAPI_PLUGIN_MR_FILTER_REUSABLE, if required to specify that the filter can be reused
-
SLAPI_PLUGIN_OBJECT, a pointer to the filter object
Refer to Chapter 18, Parameter Block Reference for details.
Thread Safety and Filter Factory Functions
This function must be thread safe. Directory Server can call this function concurrently.
Filter Object Destructor Function
A filter object destructor function frees memory that was allocated for a filter object set up by the filter factory function. Directory Server calls the destructor after the operation completes, passing the parameter block indicating the filter object as the value of SLAPI_PLUGIN_OBJECT.
Directory Server never calls a destructor for the same object concurrently.
Example 11–6 Filter Object and Destructor (matchingrule.c)
This code shows an example object and destructor.
#include "slapi-plugin.h"
typedef struct plg_filter_t /* For manipulating filter obj. */
{ char * f_type; /* Attribute type to match */
int f_op; /* Type of comparison
* (<, <=, ==, >=, >, substr)
* for the filter. */
struct berval ** f_values; /* Array of values to match */
} plg_filter_t;
/* Free memory allocated for the filter object. */
static int
plg_filter_destroy(Slapi_PBlock * pb)
{
void * obj = NULL; /* Server lets the plug-in */
plg_filter_t * fobj = NULL; /* handle the object type. */
if (!slapi_pblock_get(pb, SLAPI_PLUGIN_OBJECT, &obj))
{
fobj = (plg_filter_t *)obj;
if (fobj){
slapi_ch_free((void **)&fobj->f_type);
if (fobj->f_values){
ber_bvecfree(fobj->f_values);
}
slapi_ch_free((void **)&fobj);
}
}
return 0;
}
- © 2010, Oracle Corporation and/or its affiliates