13 Writing Computed Attribute Plug-Ins

This chapter describes a plug-in that computes an attribute value when that value is requested by a client application.

This chapter covers the following topics:

Computed Attributes and Performance
Writing a Computed Attribute Plug-In

13.1 Computed Attributes and Performance

Unlike most attributes in Directory Server, computed attributes do not have values stored in the Directory Server database. Computed attributes become available when the values are requested. Therefore, the attribute values must be computed at the time of the request, every time the values are requested.

In general, therefore, computed attributes should be quick to process. Computed attributes that depend on large internal searches, or even access to data not contained in the directory, can be expensive to generate. Therefore, such attributes are not ideal candidates for computed attributes.

Instead computed attributes that generate values quickly from the data at hand are more typical. For example, you might use a computed attribute to count or otherwise process the values of other attributes in an entry. This chapter shows a simple, artificial example that uses the API to get the current time when reading an entry.

13.2 Writing a Computed Attribute Plug-In

This section demonstrates how to write a plug-in that generates the value of an attribute, currentTime.

Only code excerpts are shown in this chapter. The complete code example can be found where you installed Directory Server, install-pathCaret/examples/computed.c.

13.2.1 Initializing the Computed Attribute Plug-In

Plug-ins that compute attribute values register the functions of type slapi_compute_callback_t to compute attributes with slapi_compute_add_evaluator () during initialization with the server.

#include "slapi-plugin.h"

int
compute_init(Slapi_PBlock * pb)
{
    int rc = 0;                        /* 0 means success             */
    rc |= slapi_pblock_set(            /* Plug-in API version         */
        pb,
        SLAPI_PLUGIN_VERSION,
        SLAPI_PLUGIN_CURRENT_VERSION
    );
    rc |= slapi_pblock_set(            /* Plug-in description         */
        pb,
        SLAPI_PLUGIN_DESCRIPTION,
        (void *) &comp_desc;           /* See the code for comp_desc. */
    );
    rc |= slapi_compute_add_evaluator(compute_attrs);
    return rc;
}

Here, compute_attrs() is the function that computes the attribute value.

13.2.2 Computing an Attribute Value

When Directory Server receives a request for the computed attribute value, in this case currentTime, the server calls the functions that are registered to compute attributes. Directory Server provides your function the context, attribute type, and entry with which to compute the attribute.

Your function must therefore check the attribute type to see whether your function should handle the computation. If your function does not handle the attribute type in question, return -1. If your function can handle the attribute, your function must determine the value or values of the attribute. Your function must then add the computed content to the result that the server returns. The following code excerpt shows the compute_attrs () function generating a current time string for the attribute value.

#include "slapi-plugin.h"

/* Compute an attribute called currentTime                        */
static int
compute_attrs(
    computed_attr_context  * context,
    char                   * type,
    Slapi_Entry            * entry,
    slapi_compute_output_t   outfn
)
{
    /* If the attribute type is not recognized return -1.         */
    int rc = -1;

    if (slapi_attr_type_cmp("currentTime", type, 2) == 0) {
        Slapi_Attr  * time_attr;
        time_t        now;
        char          current_time[30];
        Slapi_Value * time_value;
        int           rc = 0;

        /* Construct the computed attribute.                      */
        time_attr = slapi_attr_new();
        slapi_attr_init(time_attr, type);
        now = time(NULL);
        ctime_r(&now;, current_time, 30);
        current_time[(int)strlen(current_time) - 1] = '\0';
        time_value = slapi_value_new_string(current_time);
        slapi_attr_add_value(time_attr, time_value);
        slapi_value_free(&time_value;);

        /* Add the attribute to the result returned.              */
        rc = (*outfn)(context, time_attr, entry);
        attr_done(time_attr);
        return rc;

    /* Handle other computed attributes...
    } else if (slapi_attr_type_cmp("myCompAttr", type, 2) == 0) {
    */

    }
    return rc;
}

Notice the lines of code that add the attribute to the result that is returned. The output function in this case is of type slapi_compute_output_t.

Notice also, when constructing the computed attribute value, that the compute_attrs() function removes the newline character from the string in the ctime_r() function. This removal prevents the attribute value from appearing base64-encoded when the value is displayed by the ldapsearch command.

13.2.3 Testing the Computed Attribute Plug-In

Before you can test the plug-in with the ldapsearch command, you must register the plug-in with Directory Server.

13.2.3.1 To Register the Plug-In

If you have not already done so, build the example plug-in library and activate both plug-in informational logging and the example plug-in.

Build the plug-in.

Hint Use install-path/examples/Makefile or install-path/examples/Makefile64.

Configure Directory Server to log plug-in informational messages and load the plug-in.

$ dsconf create-plugin -F custom-plugin-init-function -G custom-plugin-argument -H lib-path \
-Y custom-plugin-type "Custom Plugin"
$ dsconf enable-plugin "Custom Plugin"

Hint For more information, use the commands specified in the plug-in source file.

Restart Directory Server.
```
$ dsadm restart instance-path
```

13.2.3.2 To use the Computed Attribute Plug-In

Before You Begin

Run a search on the root DSE.

$ ldapsearch -h localhost -p 1389 -b "" -s base "(objectclass=*)" currentTime
    version: 1
    dn:
    currentTime: Fri Feb 17 09:30:28 2006