11.2. Understanding Matching Rule Plug-ins

A matching rule plug-in can create filters that the server can use when handling extensible search filters. A matching rule plug-in can also create indexes to index entries for extensible searches.

11.2.1. Functions Defined in Matching Rule Plug-ins

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 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. Refer to Section 11.2.2, “How Matching Rules Are Identified”, and Section 11.2.3, “How the Server Associates Plug-ins with OIDs”, for details.

11.2.2. How Matching Rules Are Identified

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, refer to Section 11.3, “Indexing Based on Matching Rules”.
  • The server may receive an LDAP search request with an “extensible match” filter specifying the OID of the matching rule. For example, a string representation of an extensible match filter might be: 
    (sn:dn:1.2.3.4:=Jensen)
    The search filter above specifies that the server should use the matching rule identified by the OID 1.2.3.4 to search for the value Jensen in the sn attribute and in all attributes in the DN.
    For information on setting up the server to handle extensible match filters, refer to Section 11.4, “Handling Extensible Match Filters”.
  • The server may receive an LDAP search request containing a sorting control, and the sorting control specifies the OID of the matching rule.
    For information on setting up the server to sort based on matching rules, refer to Section 11.5, “Handling Sorting by Matching Rules”.
In all of these situations, the server uses the matching rule OID to find the plug-in responsible for handling the rule. Refer to Section 11.2.3, “How the Server Associates Plug-ins with OIDs”, for details.

11.2.3. How the Server Associates Plug-ins with OIDs

The server associates plug-ins with OIDs using the following process:
  • 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 to the client.

11.2.3.1.  Finding a Plug-in for Indexing

To determine which matching rule plug-in is responsible for indexing an attribute with a given matching rule (based on its OID), the server does the following for each plug-in:
  1. In a new Slapi_PBlock parameter block, the server sets the OID in the SLAPI_PLUGIN_MR_OID parameter.
  2. The server then calls the indexer factory function (specified in the SLAPI_PLUGIN_MR_INDEXER_CREATE_FN parameter) for the plug-in.
  3. The server then checks the SLAPI_PLUGIN_MR_INDEX_FN parameter.
    • If the parameter is NULL, the plug-in does not handle the matching rule specified by that OID.
    • If the parameter returns an indexer function, this plug-in handles the matching rule specified by that OID.
  4. Finally, the server frees the parameter block from memory.
At some point, the server may also call the indexer destructor function (specified in the SLAPI_PLUGIN_MR_DESTROY_FN parameter) to free the indexer object that was created by the indexer factory function.

11.2.3.2.  Finding a Plug-in for Searching

To determine which matching rule plug-in is responsible for handling an extensible match filter for a given matching rule (based on its OID), the server does the following for each plug-in:
  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 type (from the filter) in the SLAPI_PLUGIN_MR_TYPE parameter.
    • Sets the value (from the filter) in the SLAPI_PLUGIN_MR_VALUE parameter.
  2. The server then calls the filter factory function (specified in the SLAPI_PLUGIN_MR_FILTER_CREATE_FN parameter) for the plug-in.
  3. The server checks the SLAPI_PLUGIN_MR_FILTER_MATCH_FN parameter.
    • If the parameter is NULL, the plug-in does not handle the matching rule specified by that OID.
    • If the parameter returns a filter matching function, this plug-in handles the matching rule specified by that OID.
  4. Finally, the server gets the following information from the plug-in for future use:
    • The filter index function specified in the SLAPI_PLUGIN_MR_FILTER_INDEX_FN parameter.
    • The value specified in the SLAPI_PLUGIN_MR_FILTER_REUSABLE parameter.
    • The filter reset function specified in the SLAPI_PLUGIN_MR_FILTER_RESET_FN parameter.
    • The filter object specified in the SLAPI_PLUGIN_OBJECT parameter.
    • The filter destructor function specified in the SLAPI_PLUGIN_DESTROY_FN parameter.
Information specified in the filter object is used by both the filter index function and the filter matching function.

11.2.4. How the Server Uses Parameter Blocks

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 creates a new 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 between plug-in functions. The value of a parameter set by one plug-in function may not necessarily be accessible to other plug-in functions, because each function is usually passed a new and different parameter block.