JavaScript is required to for searching.
Skip Navigation Links
Exit Print View
Oracle Directory Server Enterprise Edition Developer's Guide 11 g Release 1 (
search filter icon
search icon

Document Information


Part I Directory Server Plug-In API Guide

1.  Before You Start Writing Plug-Ins

2.  Changes to the Plug-In API Since Directory Server 5.2

3.  Getting Started With Directory Server Plug-Ins

4.  Working With Entries Using Plug-Ins

5.  Extending Client Request Handling Using Plug-Ins

6.  Handling Authentication Using Plug-Ins

7.  Performing Internal Operations With Plug-Ins

8.  Writing Entry Store and Entry Fetch Plug-Ins

9.  Writing Extended Operation Plug-Ins

10.  Writing Matching Rule Plug-Ins

How Matching Rule Plug-Ins Work

What a Matching Rule Is

Requesting a Matching Rule

What a Matching Rule Plug-In Does

Example Matching Rule Plug-In

Configuring Matching Rule Plug-Ins

Registering Matching Rule Plug-Ins

Handling Extensible Match Filters

How Directory Server Handles Extensible Match Searches

Filter Matching Function

Subtype Matches

Thread Safety and Filter Matching Functions

Filter Index Function

Input Parameters for Filter Index Functions

Output Parameters for Filter Index Functions

Thread Safety and Filter Index Functions

Filter Factory Function

Input Parameters for Filter Factory Functions

Output Parameters for Filter Factory Functions

Thread Safety and Filter Factory Functions

Filter Object Destructor Function

Indexing Entries According to a Matching Rule

How Directory Server Handles the Index

Indexer Function

Input Parameters for Indexers

Output Parameter for Indexers

Thread Safety and Indexers

Indexer Factory Function

Input Parameters for Indexer Factory Functions

Output Parameters for Indexer Factory Functions

Thread Safety and Indexer Factory Functions

Indexer Object Destructor Function

Enabling Sorting According to a Matching Rule

How Directory Server Performs Sorting According to a Matching Rule

Handling an Unknown Matching Rule

Internal List of Correspondences

OIDs Not in the Internal List

11.  Writing Password Storage Scheme Plug-Ins

12.  Writing Password Quality Check Plug-Ins

13.  Writing Computed Attribute Plug-Ins

Part II Directory Server Plug-In API Reference

14.  Data Type and Structure Reference

15.  Function Reference, Part I

16.  Function Reference, Part II

17.  Parameter Block Reference

A.  NameFinder Application

Prerequisite Software

Deploying NameFinder

Configuring NameFinder to Access Your Directory

Customizing NameFinder


Example Matching Rule Plug-In

The example code cited in this chapter, from install-path/examples/matchingrule.c, mimics functionality installed by default with Directory Server. For this reason, you do not need to build and load the plug-in unless you modify the plug-in to implement your own matching rule. The example uses a different OID from the plug-in that is provided with Directory Server. Therefore, the sample plug-in does not interfere with the existing plug-in if you do choose to load the sample.

Configuring Matching Rule Plug-Ins

Matching rule plug-ins have type matchingrule. Directory Server plug-ins can depend on matching rule plug-ins by type. Directory Server cannot load plug-ins unless plug-ins of the type the plug-ins depend on load without error.

Refer to Plugging Libraries Into Directory Server for details on loading plug-in configuration entries into Directory Server.

Registering Matching Rule Plug-Ins

Matching rule plug-ins include factory functions. Factory functions provide function pointers to the indexing or filter match routines dynamically. You therefore register only the factory functions as part of the plug-in initialization function.

A plug-in that handles both indexing and matching registers both factory functions and a description, as shown in the following example.

Example 10-1 Registering Matching Rule Factory Functions (matchingrule.c)

#include "slapi-plugin.h"

static Slapi_PluginDesc plg_desc = {
    "caseExactMatchingRule",           /* Plug-in identifier           */
    "Oracle Corporation (test)",       /* Vendor name                  */
    "",                      /* Plug-in revision number      */
    "Case Exact Matching Rule plug-in" /* Plug-in description          */

#ifdef _WIN32
plg_init(Slapi_PBlock * pb)
    int                       rc;
    /* Matching rule factory functions are registered using
     * the parameter block structure. Other functions are then
     * registered dynamically by the factory functions.
     * This means that a single matching rule plug-in may handle
     * a number of different matching rules.                           */
    rc  = slapi_pblock_set(
        (void *)plg_indexer_create
    rc |= slapi_pblock_set(
        (void *)plg_filter_create
    rc |= slapi_pblock_set(
        (void *)&plg_desc

    /* Register the matching rules themselves. */

    return rc;

Here, plg_init() is the plug-in initialization function, plg_indexer_create() is the indexer factory, plg_filter_create() is the filter factory, and plg_desc is the plug-in description structure.

If your plug-in uses private data, set SLAPI_PLUGIN_PRIVATE in the parameter block as a pointer to the private data structure.

Example 10-2 Registering a Matching Rule (matchingrule.c)

Register matching rules by using slapi_matchingrule_register() as shown here rather than using slapi_pblock_set() in the initialization function.

#include "slapi-plugin.h"

#define PLG_DESC      "Case Exact Matching on Directory String" \
                      " [defined in X.520]"
#define PLG_NAME      "caseExactMatch"
/* This OID is for examples only and is not intended for reuse. The
 * official OID for this matching rule is                    */
#define PLG_OID       ""

#ifdef _WIN32
plg_init(Slapi_PBlock * pb)
    Slapi_MatchingRuleEntry * mrentry = slapi_matchingrule_new();
    int                       rc;
    /* Register matching rule factory functions.*/

    /* Matching rules themselves are registered using a
     * Slapi_MatchingRuleEntry structure, not the parameter
     * block structure used when registering plug-in functions.
     * This plug-in registers only one matching rule. Yours
     * may register many matching rules.                               */
    rc |= slapi_matchingrule_set(
        (void *)slapi_ch_strdup(PLG_DESC)
    rc |= slapi_matchingrule_set(
        (void *)slapi_ch_strdup(PLG_NAME)
    rc |= slapi_matchingrule_set(
        (void *)slapi_ch_strdup(PLG_OID)
    rc |= slapi_matchingrule_set(
        SLAPI_MATCHINGRULE_SYNTAX,     /* Here you use DirectoryString.*/
        (void *)slapi_ch_strdup("")
    rc |= slapi_matchingrule_register(mrentry);
    slapi_matchingrule_free(&mrentry, 1);

    return rc;