HP-UX Directory Server 8.1 plug-in reference

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 “How matching rules are identified”, and
“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 “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 “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 “Handling
sorting by matching rules”.
In all these situations, the server uses the matching rule OID to find the plug-in responsible for
handling the rule. Refer to “How the server associates plug-ins with OIDs”, for details.
88 Writing matching rule plug-ins