11.3. Indexing Based on Matching Rules

This section explains how to set up the server to index entries using a matching rule.

Note

You also need to define an initialization function to register your indexer factory function.

11.3.1. How the Server Sets Up the Index

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. Refer to Section 11.2.3, “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 (for example, the attribute type and the type of index) for future reference.
When adding, modifying, or deleting the values of an attribute, the server checks this information to determine if the attribute is indexed. Refer to Section 11.3.2, “How the Server Updates the Index”, for information on how attributes are indexed.

11.3.2. How the Server Updates the Index

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 performs the following tasks 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 SLAPI_PLUGIN_MR_OID 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.
At the end of the process, the server frees any parameter blocks that were allocated during the process.

11.3.3. Writing the Indexer Factory Function

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 perform the following tasks:
  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. Refer to Section 11.5, “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. (Refer to Section 11.7, “Writing an Initialization Function”.)
  4. Create an indexer object containing any information that you want to pass 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 SLAPI_PLUGIN_MR_INDEX_FN parameter to the indexer function. (Refer to Section 11.3.5, “Writing the Indexer Function”.)
    • Set the SLAPI_PLUGIN_DESTROY_FN parameter to the function responsible for freeing any memory allocated by the factory function, such as the indexer object. refer to Section 11.3.3, “Writing the Indexer Factory Function”, for details.
  6. Return 0 (or the result code LDAP_SUCCESS) if everything completed successfully.

11.3.4. Getting and Setting Parameters in Indexer Factory Functions

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

Parameter Name Data Type Description
SLAPI_PLUGIN_MR_OID char * Input parameter. Matching rule OID (if any) specified in the index directive.
SLAPI_PLUGIN_MR_TYPE char * Input parameter. Attribute type (if any) specified in the index directive.
SLAPI_PLUGIN_MR_USAGE unsigned int Input parameter. Specifies the intended use of the indexer object. This parameter can have one of the following values:
  • SLAPI_PLUGIN_MR_USAGE_INDEX specifies that the indexer object should be used to index entries.
  • SLAPI_PLUGIN_MR_USAGE_SORT specifies that the indexer object should be used to sort entries.
You can use this to specify different information in the indexer object or different indexer functions, based on whether the plug-in is used for indexing or sorting. For information on sorting search results, refer to Section 11.5, “Handling Sorting by Matching Rules”.
SLAPI_PLUGIN_PRIVATE void * Input parameter. Pointer to any private data originally specified in the initialization function. Refer to Section 11.7, “Writing an Initialization Function”, for details.
SLAPI_PLUGIN_MR_OID char * Output parameter. Official matching rule OID of the index.
SLAPI_PLUGIN_MR_INDEX_FN void * (function pointer) Output parameter. Name of the function called by the server to generate a list of keys used for indexing a set of values.
SLAPI_PLUGIN_DESTROY_FN void * (function pointer) Output parameter. Name of the function to be called to free the indexer object.
SLAPI_PLUGIN_OBJECT void * Output parameter. Pointer to the indexer object created by your factory function.

11.3.5. Writing the Indexer 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, remember that the server can call this function concurrently for different indexer objects.)
The indexer function should perform the following tasks:
  1. Get the values of the following parameters:
    • Get the indexer object from the SLAPI_PLUGIN_OBJECT parameter (if the parameter is set).
    • Get the array of values that you want indexed from the SLAPI_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.

11.3.6. Getting and Setting Parameters in Indexer Functions

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

Parameter Name Data Type Description
SLAPI_PLUGIN_MR_VALUES struct berval ** Input parameter. Pointer to an array of berval structures containing the values of the entry's attributes that need to be indexed.
SLAPI_PLUGIN_OBJECT void * Input parameter. Pointer to the indexer object created by the indexer factory function. Refer to Section 11.3.3, “Writing the Indexer Factory Function”, for details.
SLAPI_PLUGIN_MR_KEYS struct berval ** Output parameter. Keys generated for the values specified in the SLAPI_PLUGIN_MR_VALUES parameter. The server creates indexes using these keys.