Chapter 11   Writing Matching Rule Plug-ins

In an extensible match filter, the client specifies that it wants to use the matching rule to compare a specified value against the values of entries in the directory. (For example, an extensible match filter might find all entries in which the sn attribute "sounds like" melon.)

An extensible match filter contains the following information:

• The OID of the matching rule or the attribute type that you want to search (or both).
  
  
• The value for which to search.
  
  
• A preference indicating whether or not to search the attributes in the DN also.

For example, if the OID "1.2.3.4" identifies a matching rule that performs "sounds like" matches, the following extensible match filter attempts to find entries where the mail attribute "sounds like" moxie.

(mail:1.2.3.4:=moxie)

In the search filter, the client can specify the OID (that identifies a matching rule) and the attribute type. This indicates that the value in the filter should be compared against the attribute using the matching rule.

For example, if the OID 1.2.3.4 specifies a "sound-alike" match and if the string representation of the search filter is:

(uid:1.2.3.4:=moxie)

the client wants to find entries in which the value of the uid attribute sounds like moxie.

Although the LDAPv3 standard allows clients to omit the OID or the attribute type, at this time, the Netscape Directory Server only supports extensible match filters that specify both the OID and attribute type.

The filter can also specify a preference indicating whether to search the attributes in the DN as well. For example, if the OID 1.2.3.4 specifies a "sound-alike" match and if the string representation of the search filter is

(sn:dn:1.2.3.4:=moxie)

then the client wants to find all entries in which the value of the sn attribute or the attributes in the DN (for example, uid, cn, ou, or o) sound like moxie.

Directory Serveralready includes support for certain matching rules, which are used to determine the collation order and operator for searches of international data.

You can enable the Directory Server to handle your own matching rules for extensible match searches by defining your own matching rules plug-ins and registering them with the server.

You can also build indexes to improve the performance of search operations that use extended match filters.

The matching rule plug-in consists of the following:

• An indexer function. Optional.
  
  
• A filter function.
  
  
• A filter function that uses the index to speed up searches. Optional.
  
  
• A function to destroy a filter. Optional.
  
  
• A function to destroy an indexer. Optional.
  
  
• A factory function to create filters.
  
  
• A factory function to create indexers. Optional.
  
  
• A close function to clean up before server shutdown. Optional.
  
  
• An initialization function to register the factory functions and the close function.

When the server starts up and loads the matching rule plug-in, it calls the initialization function. In this function, you pass the server the pointers to the factory functions and the close function. The server calls these functions when needed. See How Matching Rules Are Identified and How the Server Associates Plug-ins with OIDs for details.

Matching rules are identified by OID. When the server encounters an OID in the following situations, it attempts to find the matching rule plug-in that handles the matching rule with that OID.

The server can encounter a matching rule OID in the following situations:

• When reading in the server configuration file, the server may encounter an index directive that specifies the OID of the matching rule. For example:
  
  index <attribute_name> <filter_type> <matching_rule_oid>
  
  If the OID is associated with a matching rule plug-in, the server adds this OID to the list of matching rule OIDs to use for indexing.
  
  For information on setting up the server to index based on matching rule, see Indexing Based on Matching Rules.

When the server encounters the OID for a matching rule, it attempts to find the plug-in associated with that matching rule.

If no plug-in is associated with the matching rule, the server calls each matching rule plug-in to find one that handles the specified matching rule.

When the server finds a plug-in that handles the matching rule, the server creates an association between the plug-in and the matching rule OID for future reference.

If no matching rule plug-in supports the specified OID, the server returns an LDAP_UNAVAILABLE_CRITICAL_EXTENSION error back to the client.

The server uses parameter blocks as a means to pass information to and from plug-in functions.

When calling your matching rule plug-in functions, the server will create a new Slapi_PBlock parameter block, set some input parameters, and pass the parameter block to your function. After retrieving output parameters from the block, the server typically frees the parameter block from memory.

In general, you should not expect a parameter block to be passed from plug-in function to plug-in function. The value of a parameter set by one plug-in function may not necessarily be accessible to other plug-in functions since each function is usually passed a new and different parameter block.

When the server encounters a matching rule OID in an index directive in the server configuration file, the server determines which plug-in supports the matching rule identified by the OID. See How the Server Associates Plug-ins with OIDs for details.

The server gets the OID returned in the SLAPI_PLUGIN_MR_OID parameter and associates this OID with the rest of the attribute indexing information (such as the attribute type and the type of index) for future reference.

When adding, modifying, or deleting the values of an attribute, the server will check this information to determine if the attribute is indexed. See How the Server Updates the Index, for information on how attributes are indexed.

When a value is added, modified, or removed from an attribute in an entry (or when the RDN of an entry is changed), the server does the following if that attribute has an index that uses matching rules:

1. In a new Slapi_PBlock parameter block, the server sets the following parameters:
   
   
   • Sets the OID in the SLAPI_PLUGIN_MR_OID parameter.
     
     
   • Sets the attribute type (of the value being added, modified, or removed) in the SLAPI_PLUGIN_MR_TYPE parameter.
   
   
2. Next, the server calls the indexer factory function (specified in the SLAPI_PLUGIN_MR_INDEXER_CREATE_FN parameter) for the plug-in to create the indexer object.
   
   
3. The server generates the index keys for the values to be added or deleted:
   
   
   • The server first verifies that the SLAPI_PLUGIN_MR_INDEX_FN parameter specifies an indexer function and the parameter specifies the official OID of the matching rule.
     
     
   • If these are both set, the server sets the SLAPI_PLUGIN_MR_VALUES parameter to the array of berval structures containing the new or modified values that need to be indexed and calls the indexer function.
     
     
   • Next, the server gets the value of the SLAPI_PLUGIN_MR_KEYS parameter, which is an array of berval structures containing the keys corresponding to the values.
   
   
4. The server inserts or deletes the keys and values in the index for that attribute.
   
   
5. The server calls the indexer destructor function (specified in the SLAPI_PLUGIN_MR_DESTROY_FN parameter) to free the indexer object.

When the server is done, it frees any parameter blocks that were allocated during this process.

The indexer factory function takes a single Slapi_PBlock argument. This function should be thread-safe. The server may call this function concurrently.

The indexer factory function should do the following:

1. Get the OID from the SLAPI_PLUGIN_MR_OID parameter, and determine whether that OID is supported by your plug-in.
   
   
   • If the OID is not supported, you need to return the result code LDAP_UNAVAILABLE_CRITICAL_EXTENSION.
     
     
   • If the OID is supported, continue with this process.
     
     
2. Get the value of the SLAPI_PLUGIN_MR_USAGE parameter. This parameter should have one of the following values:
   
   
   • If the value is SLAPI_PLUGIN_MR_USAGE_SORT, the server is calling your function to sort search results. See Handling Sorting by Matching Rules for more information.
     
     
   • If the value is SLAPI_PLUGIN_MR_USAGE_INDEX, the server is calling your function to index an entry.
   
   You can use this information to set different information in the indexer object or to set a different indexer function, based on whether the function is being called to index or to sort.
   
   
3. You can also get any data that you set in the SLAPI_PLUGIN_PRIVATE parameter during initialization. (See Writing an Initialization Function.)
   
   
4. Create an indexer object containing any information that you want passed to the indexer function.
   
   
5. Set the following parameters:
   
   
   • Set the SLAPI_PLUGIN_MR_OID parameter to the official OID of the matching rule (if the value of that parameter is not the official OID).
     
     
   • Set the SLAPI_PLUGIN_OBJECT parameter to the indexer object.
     
     
   • Set the parameter to the indexer function. (See Writing the Indexer Function.)
     
     
   • Set the parameter to the function responsible for freeing any memory allocated by the factory function, such as the indexer object. See Writing a Destructor Function for details.
     
     
6. Return 0 (or the result code LDAP_SUCCESS) if everything completed successfully.

The following table summarizes the different parameters that the indexer factory function should get and set in the parameter block that is passed in.

Table 11-1   Input and Output Parameters Available to an Indexer Factory Function

The indexer function takes a single Slapi_PBlock argument. This function will never be called for the same indexer object concurrently. (If you plan to manipulate global variables, keep in mind that the server can call this function concurrently for different indexer objects.)

The indexer function should do the following:

1. Get the values of the following parameters:
   
   
   • Get the indexer object from theSLAPI_PLUGIN_OBJECT parameter (if the parameter is set).
     
     
   • Get the array of values that you want indexed from theSLAPI_PLUGIN_MR_VALUES parameter.
   
   
2. Generate index keys for these values, and set the SLAPI_PLUGIN_MR_KEYS parameter to the array of these keys.
   
   
3. Return 0 (or the result code LDAP_SUCCESS) if everything completed successfully.

The server adds or removes the keys and the corresponding values from the appropriate indexes.

The following table summarizes the different parameters that the indexer function should get and set in the parameter block that is passed in.

Table 11-2    Input and Output Parameters Available to an Indexer Function 

When the server processes a search request that has an extensible match filter, the server does the following:

1. First, the server finds the plug-in associated with this OID, if an association between the OID and plug-in has already been made.
   
   If no association has been made yet, the server attempts to find a matching rule plug-in that handles the OID. See How the Server Associates Plug-ins with OIDs for details.
   
   
2. Next, the server attempts to generate a list of search result candidates from the indexes. In a new Slapi_PBlock parameter block, the server does the following:
   
   
   • The server puts the filter object in the SLAPI_PLUGIN_OBJECT parameter and calls the filter index function (specified in the SLAPI_PLUGIN_MR_FILTER_INDEX_FN parameter).
   
   
   • The server checks the value of the SLAPI_PLUGIN_MR_QUERY_OPERATOR parameter. If the operator is a known type (such as SLAPI_OP_EQUAL), the server will use the operator when searching the index for candidates. For details, see Query Operators in Matching Rules.
     
     
   • The server sets the SLAPI_PLUGIN_MR_VALUES parameter to each of the values specified in the filter and calls the indexer function (which is specified in the SLAPI_PLUGIN_MR_INDEX_FN parameter) to generate the key (specified in the SLAPI_PLUGIN_MR_KEYS parameter).
     
     
   • The server uses the keys and the query operator to find potential candidates in the indexes.
   
   The server considers all entries to be potential candidates if at least one of the following is true:
   
   
   • The matching rule plug-in has no indexer function (specified in the SLAPI_PLUGIN_MR_INDEX_FN parameter).
     
     
   • No index applies to the search (for example, if the query operator does not correspond to an index).
     
     
   • No keys are generated for the specified values.
     
     
3. For each candidate entry, the server checks to see if the entry matches the search filter by doing the following:
   
   
   • The server calls the filter matching function (which is specified in the SLAPI_PLUGIN_MR_FILTER_MATCH_FN parameter), passing in the filter object, the entry, and the attributes of the entry.
     
     
   • If the entry does not match but the search request also specifies that the attributes in the DN should be searched, the server calls the filter matching function again, passing in the filter object, the entry, and the attributes in the DN.
   
   The server checks the value returned by the filter matching function:
   
   
   • If the function returns 0, the entry matched the search filter.
     
     
   • If the function returns -1, the entry did not match the search filter.
     
     
   • If the function returns an LDAP error code (a positive value), an error occurred.
     
     
4. If the entry matches the filter, the server verifies that the entry is in the scope of the search before returning the entry to the LDAP client as a search result.

As mentioned in How the Server Handles the Filter, the server uses a query operator when searching the index for possible candidates.

This applies to the ldbm default backend database. If you are using your own backend or if you have not set up indexing by matching rules, the server does not make use of the query operator.

The server checks the value of the SLAPI_PLUGIN_MR_QUERY_OPERATOR parameter to determine which operator is specified. The following table lists the possible values for this parameter.

Table 11-3    Query Operators in Extensible Match Filters 

The filter factory function takes a single Slapi_PBlock argument. This function should be thread-safe. The server may call this function concurrently. (Each incoming LDAP request is handled by a separate thread. Multiple threads may call this function if processing multiple requests that have extensible match filters.)

The filter factory function should do the following:

1. Get the OID from the SLAPI_PLUGIN_MR_OID parameter and determine whether or not that OID is supported by your plug-in.
   
   
   • If the OID is not supported, you need to return the result code LDAP_UNAVAILABLE_CRITICAL_EXTENSION. The server will send this back to the client.
     
     
   • If the OID is supported, continue with this process.
     
     
2. Get and check the values of the SLAPI_PLUGIN_MR_TYPE and SLAPI_PLUGIN_MR_VALUE parameters.The values of these parameters are the attribute type and value specified in the extensible match filter.
   
   
3. You can also get any data that you set in the SLAPI_PLUGIN_PRIVATE parameter during initialization. See Writing an Initialization Function.
   
   
4. Create a filter object, putting the following information in the object:
   
   
   • The official OID of the matching rule. Optional.
     
     
   • The attribute type specified in the filter.
     
     
   • The value specified in the filter.
     
     
   • Any additional data that you want made available to the filter index function (for example, the query operator, if specified in the filter).
   
   The server will call your filter index function at a later time to extract this information from the filter object.
   
   
5. Set the following parameters:
   
   
   • Set the SLAPI_PLUGIN_MR_OID parameter to the official OID of the matching rule if the value of that parameter is not the official OID. Optional.
     
     
   • Set the SLAPI_PLUGIN_OBJECT parameter to the filter object.
     
     
   • Set the parameter to the filter index function (cf. Writing a Filter Index Function) if you have set up indexes based on this matching rule. Optional.
     
     
   • Set the SLAPI_PLUGIN_MR_FILTER_MATCH_FN parameter to the filter matching function. See Writing a Filter Matching Function.
     
     
   • Set the parameter to the function responsible for freeing the filter object, if you have defined this function. Optional. See Writing a Destructor Function for details.
   
   
6. Return 0 (or the result code LDAP_SUCCESS) if everything completed successfully.

The following table summarizes the different parameters that the filter factory function should get and set in the parameter block that is passed in.

Table 11-4   Input and Output Parameters Available to a Filter Factory Function

The filter index function takes a single Slapi_PBlock argument. This function will never be called for the same filter object concurrently. (If you plan to manipulate global variables, keep in mind that the server can call this function concurrently for different filter objects.)

The filter index function should do the following:

1. Get the filter object from the SLAPI_PLUGIN_OBJECT parameter (if the parameter is set).
   
   
2. Using data from the object, determine and set the values of the following parameters:
   
   
   • Set the SLAPI_PLUGIN_MR_OID parameter to the official OID of the matching rule.
     
     
   • Set the parameter to the attribute type in the filter object.
     
     
   • Set the SLAPI_PLUGIN_MR_VALUES parameter to the values in the filter object.
     
     
   • Set the SLAPI_PLUGIN_MR_QUERY_OPERATOR parameter to the query operator that corresponds to this search filter. See Query Operators in Matching Rules for possible values for this parameter.
     
     
   • Set the SLAPI_PLUGIN_OBJECT parameter to the filter object.
     
     
   • Set the parameter to the indexer function. See Writing the Indexer Function.
     
     
3. Return 0 (or the result code LDAP_SUCCESS) if everything completed successfully.

The following table summarizes the different parameters that the filter index function should get and set in the parameter block that is passed in.

Table 11-5   Input and Output Parameters Available to a Filter Index Function

The filter matching function has the following prototype:

#include "slapi-plugin.h"
typedef int (*mrFilterMatchFn) (void* filter,
Slapi_Entry* entry, Slapi_Attr* attrs);

This function passes the following arguments:

• filter is a pointer to the filter object.
  
  
• entry is a pointer to the Slapi_Entry entry that should be compared against the filter.
  
  
• attrs is the first Slapi_Attr attribute in the entry or in the set of DN attributes. (The extensible match filter might specify that the attributes in the DN of an entry should also be included in the search.)

This function will never be called for the same filter object concurrently. (If you plan to manipulate global variables, keep in mind that the server can call this function concurrently for different filter objects.)

The filter matching function should do the following:

1. From the filter object, get the attribute type, the values, and the query operator.
   
   
2. Find the corresponding attribute in the attributes passed into the function. Make sure to check for subtypes of an attribute (for example, cn=lang-ja) in the filter and in the attributes specified by attrs.
   
   You can call the slapi_attr_type_cmp() function to compare the attribute in the filter against the attributes passed in as arguments.
   
   
3. Using the query operator to determine how the values should be compared, compare the values from the filter against the values in the attribute.
   
   
4. Return one of the following values:
   
   
   • 0 if the values of the attribute match the value specified in the filter.
     
     
   • -1 if the values don't match.
     
     
   • An LDAP error code (a positive number) if an error occurred.

For example, your destructor function can get the indexer object from the SLAPI_PLUGIN_OBJECT parameter and free the object from memory.

This function will never be called for the same indexer or filter object concurrently. (If you plan to manipulate global variables, keep in mind that the server can call this function concurrently for different filter or indexer objects.)

If you register multiple plug-ins with different start and close functions, the functions are called in the order that the plug-ins are registered; in other words, in the order that the plugin directives appear in the server configuration file.