Skip Navigation Links | |
Exit Print View | |
Oracle Directory Server Enterprise Edition Developer's Guide 11 g Release 1 (11.1.1.5.0) |
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 Plug-In Does
Handling Extensible Match Filters
How Directory Server Handles Extensible Match Searches
Thread Safety and Filter Matching Functions
Input Parameters for Filter Index Functions
Output Parameters for Filter Index Functions
Thread Safety and Filter Index Functions
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
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
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
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.
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.
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 */ "11.1.1.3.0", /* Plug-in revision number */ "Case Exact Matching Rule plug-in" /* Plug-in description */ }; #ifdef _WIN32 __declspec(dllexport) #endif int 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( pb, SLAPI_PLUGIN_MR_INDEXER_CREATE_FN, (void *)plg_indexer_create ); rc |= slapi_pblock_set( pb, SLAPI_PLUGIN_MR_FILTER_CREATE_FN, (void *)plg_filter_create ); rc |= slapi_pblock_set( pb, SLAPI_PLUGIN_DESCRIPTION, (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 2.5.13.5. */ #define PLG_OID "1.3.6.1.4.1.42.2.27.999.4.1" #ifdef _WIN32 __declspec(dllexport) #endif int 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( mrentry, SLAPI_MATCHINGRULE_DESC, (void *)slapi_ch_strdup(PLG_DESC) ); rc |= slapi_matchingrule_set( mrentry, SLAPI_MATCHINGRULE_NAME, (void *)slapi_ch_strdup(PLG_NAME) ); rc |= slapi_matchingrule_set( mrentry, SLAPI_MATCHINGRULE_OID, (void *)slapi_ch_strdup(PLG_OID) ); rc |= slapi_matchingrule_set( mrentry, SLAPI_MATCHINGRULE_SYNTAX, /* Here you use DirectoryString.*/ (void *)slapi_ch_strdup("1.3.6.1.4.1.1466.115.121.1.15") ); rc |= slapi_matchingrule_register(mrentry); slapi_matchingrule_free(&mrentry, 1); return rc; }
PLG_DESC is a string that describes the matching rule.
PLG_NAME is a string identifier for the matching rule.
PLG_OID is the object identifier for the matching rule.
The sample plug-in #defines every item. If the plug-in implements several matching rules, the initialization function must register each item.
Notice that plug-ins must register factory functions separately, using slapi_pblock_set().