Chapter 3 Calling the Front-End API Functions

This chapter explains how to use the Netscape Directory Server's front-end API functions to accomplish various tasks. You can call these functions in your plug-in to interact with the client (for example, send results or result codes), log messages, and work with entries, attributes, and filters.

In general, the Directory Server includes front-end API functions that allow you to do the following:

• Logging Messages
• Adding Notes to Access Log Entries
• Sending Data to the Client
• Determining if an Operation Was Abandoned
• Working with Entries and Attributes
• Working with Search Filters
• Working with Distinguished Names
• Checking Passwords

slapi_log_error( SLAPI_LOG_PLUGIN, "searchdn_preop_search",
"*** PREOPERATION SEARCH PLUGIN ***\n");

This function generates a message similar to the following:

[01/Oct/1997:02:24:18 -0700] searchdn_preop_search - *** PREOPERATION SEARCH PLUGIN ***

Make sure that the Directory Server is configured to log messages that have the severity that you specify (for example, SLAPI_LOG_PLUGIN). For more information, see "Setting the Log Level of the Server" on page  48.

When the default back-end database processes a search operation, it attempts to use indexes to narrow down the list of candidates matching the search criteria. If the back-end is unable to use indexes to narrow down the list, it appends the following string to the access log entry for the search:

notes="U"

If you are writing your own back-end database search function, you can append this note to access log entries by setting the SLAPI_OPERATION_NOTES parameter to the flag SLAPI_OP_NOTE_UNINDEXED.

This parameter identifies any notes that need to be appended to access log entries. At the current time, SLAPI_OP_NOTE_UNINDEXED is the only value that you can set for this parameter. In future releases, additional flags will be defined. You will be able to bitwise OR combinations of flags to specify different combinations of notes.

The server appends these notes and writes out the access log entries whenever sending a result or search entry back to the client.

• If you need to send a result code back to the client (for example, to report an error or a successful result to an LDAP operation), call the slapi_send_ldap_result() function (see "slapi_send_ldap_result()" on page  341 for details).

Note that you should only send one result per operation back to the client.

• If you are fulfilling a search request and need to send matching entries back to the client, call the slapi_send_ldap_search_entry() function for each entry (see "slapi_send_ldap_search_entry()" on page  343 for details).
• If you need to refer the LDAP request to a different LDAP server, call the slapi_send_ldap_referral() function (see "slapi_send_ldap_referral()" on page  339 for details).

slapi_send_ldap_result( pb, LDAP_SUCCESS, NULL, "The operation was processed successfully.\n", 0, NULL );

To determine if an operation has been abandoned, call the slapi_op_abandoned() function (see "slapi_op_abandoned()" on page  325 for details). For example:

if ( slapi_op_abandoned( pb ) ) {

slapi_log_error( SLAPI_LOG_PLUGIN, "my_function", "The operation was abandoned.\n" );

return 1;

}

If you need to manipulate these entries, you can call the following front-end routines:

Table 3.1 Front-end functions for manipulating entries and attributes

To do this:	Call this function
Allocate memory for a new entry	slapi_entry_alloc()
Copy an entry	slapi_entry_dup()
Free an unused entry from memory	slapi_entry_free()
Convert an entry to a string representation (in LDIF format) and vice versa	slapi_entry2str(), slapi_str2entry()
Get or set the DN for an entry	slapi_entry_get_dn(), slapi_entry_set_dn()
Verify that an entry complies with the schema	slapi_entry_schema_check()
Get the attributes of an entry	slapi_entry_first_attr(), slapi_entry_next_attr()
Find the values for a specified attribute	slapi_entry_attr_find()
Merge an attribute and its values into an entry	slapi_entry_attr_merge()
Add values to an attribute in an entry	slapi_entry_add_values()
Delete values from an attribute in an entry	slapi_entry_delete_values()

These functions are described in more detail in the next sections.

Creating a New Entry

In some situations, you may want to create a new entry.

• To allocate memory for an entry, call the slapi_entry_alloc() function (see "slapi_entry_alloc()" on page  271 for details).

This function returns a pointer to a new entry of the opaque datatype Slapi_Entry. You can call other front-end functions to set the DN and attributes of this entry.

• To make a copy of an entry, call the slapi_entry_dup() function (see "slapi_entry_dup()" on page  282 for details).

This function returns a pointer to a new entry of the datatype Slapi_Entry that contains the copied data.

Converting Between Entries and Strings

Entries can be stored in LDIF files. When stored in these files, entries are converted into a string representation. The following format is the LDIF string representation for a directory entry:

dn:[:] <dn>\n

[<attr>:[:] <value>\n]

[<attr>:[:] <value>\n]

[<space><continuedvalue>\n]*

...

If you want to continue the specification of a value on additional lines (in other words, if the value wraps around to another line), use a single space (the ASCII 32 character) at the beginning of subsequent lines. For example:

dn: cn=Jake Lup

 inski, ou=Accoun

 ting, o=air

 ius.com

If a double-colon is used after a type, it means the value after the double-colon is encoded as a base 64 string. Data is sometimes encoded as a base 64 string if (for example) the value contains a non-printing character or newline.

To get the string representation of an entry (and vice versa), call the following functions:

• To convert an entry from the datatype Slapi_Entry to its LDIF string representation, call the slapi_entry2str() function (see "slapi_entry2str()" on page  268 for details).

This function returns the LDIF string representation of the entry or NULL if an error occurs. When you no longer need to use the string, you should free it from memory by calling the slapi_ch_free() function.

• To convert an LDIF string representation back to an entry of the datatype Slapi_Entry, call the slapi_str2entry() function (see "slapi_str2entry()" on page  345 for details).

This function returns an entry of the datatype Slapi_Entry. If an error occurred during the conversion process, the function returns NULL instead.

When you are done working with the entry, you should call the slapi_entry_free() function (see "slapi_entry_free()" on page  284 for details).

Getting and Setting the DN of an Entry

You can call the following two front-end routines to get and set the DN for an entry:

• To get the DN for an entry, call the slapi_entry_get_dn() function (see "slapi_entry_get_dn()" on page  285 for details).
• To set the DN for an entry, call the slapi_entry_set_dn() function (see "slapi_entry_set_dn()" on page  289 for details).

Before you add or modify an entry in the database, you may want to verify that the new or changed entry still complies with the schema.

To see if an entry complies with the schema, call the slapi_entry_schema_check() function (see "slapi_entry_schema_check()" on page  288 for details).

Getting the Attributes and Values of an Entry

To get the attributes and values of an entry, call the following functions:

• To iterate through the attributes of an entry, call the slapi_entry_first_attr() function to get the first attribute, and then call the slapi_entry_next_attr() function to get subsequent attributes (see "slapi_entry_first_attr()" on page  283 and "slapi_entry_next_attr()" on page  286 for details).

Both functions return a pointer to the current attribute. To get the next attribute in the entry, pass this pointer to the cookie parameter of the slapi_entry_next_attr() function.

• To get the values of a specific attribute, call the slapi_entry_attr_find() function (see "slapi_entry_attr_find()" on page  273 for details).

You can also call some of the front-end routines to add or remove values in an entry:

• To add new values to an entry, call the slapi_entry_add_values() function (see "slapi_entry_add_values()" on page  270 for details).
• To remove values from an entry, call the slapi_entry_delete_values() function (see "slapi_entry_delete_values()" on page  281 for details).
• In certain situations, you may want to add an attribute and its values to an entry while not replacing any attribute values that already exist. To do this, call the slapi_entry_attr_merge() function (see "slapi_entry_attr_merge()" on page  277 for details).

If you need to manipulate these search filters, you can call the following front-end routines:

Table 3.2 Front-end functions for manipulating filters

To do this:	Call this function
Determine if an entry matches a filter's criteria	slapi_filter_test()
Get the filter type	slapi_filter_get_choice()
Get the attribute type and value used for comparison in an attribute-value assertion filter (only applicable to LDAP_FILTER_EQUALITY, LDAP_FILTER_GE, LDAP_FILTER_LE, and LDAP_FILTER_APPROX searches)	slapi_filter_get_ava()
Get the type of attribute that the filter is searching for (only applicable to LDAP_FILTER_PRESENT searches)	slapi_filter_get_type()
Get the substring pattern used for the filter (applicable only to LDAP_FILTER_SUBSTRING searches)	slapi_filter_get_subfilt()
Convert a string representation of a filter to a filter of the datatype Slapi_Filter	slapi_str2filter()
Construct a new LDAP_FILTER_AND, LDAP_FILTER_OR, or LDAP_FILTER_NOT filter from other filters	slapi_filter_join()
Get the components of a filter (only applicable to LDAP_FILTER_AND, LDAP_FILTER_OR, and LDAP_FILTER_NOT searches)	slapi_filter_list_first(), slapi_filter_list_next()
Free a filter from memory	slapi_filter_free()

Determining if an Entry Matches a Filter

After retrieving a filter from the SLAPI_SEARCH_FILTER parameter of the parameter block, you can call the slapi_filter_test() function to determine if entries in your database match the filter (see "slapi_filter_test()" on page  299 for details).

Getting the Filter Type

To determine the type of filter you are using, call the slapi_filter_get_choice() function (see "slapi_filter_get_choice()" on page  292 for details). This function returns the filter type. The filter type can be one of the following values:

Table 3.3 Types of filters

Filter Type	Description
LDAP_FILTER_AND	The search should find entries matching all filters that are specified in this complex filter.
LDAP_FILTER_OR	The search should find entries matching any filter specified in this complex filter.
LDAP_FILTER_NOT	The search should find entries not matching the specified filter.
LDAP_FILTER_EQUALITY	The search should find entries that contain a value equal to the specified attribute value.
LDAP_FILTER_SUBSTRINGS	The search should find entries that contain a value matching the specified substrings.
LDAP_FILTER_GE	The search should find entries that contain a value greater than or equal to the specified attribute value.
LDAP_FILTER_LE	The search should find entries that contain a value less than or equal to the specified attribute value.
LDAP_FILTER_PRESENT	The search should find entries that contain the specified attribute.
LDAP_FILTER_APPROX	The search should find entries that contain a value approximately matching the specified attribute value.

Getting the Search Criteria

To get the search critieria specified by a search filter, call one of the following functions:

• If the filter type is LDAP_FILTER_EQUALITY, LDAP_FILTER_GE, LDAP_FILTER_LE, or LDAP_FILTER_APPROX, you can get the attribute and value used in the filter by calling the slapi_filter_get_ava() function (see "slapi_filter_get_ava()" on page  291 for details).
• If the filter type is LDAP_FILTER_PRESENT, you can get the attribute type that the filter searches for. To get this attribute, call the slapi_filter_get_type() function (see "slapi_filter_get_type()" on page  295 for details).
• If the filter type is LDAP_FILTER_SUBSTRINGS, you can get the attribute type that the filter searches for. To get this attribute, call the slapi_filter_get_subfilt() function (see "slapi_filter_get_subfilt()" on page  294 for details).
• To get the components of a complex filter of the type LDAP_FILTER_AND, LDAP_FILTER_OR, or LDAP_FILTER_NOT, call the slapi_filter_list_first() and slapi_filter_list_next() functions (see "slapi_filter_list_first()" on page  297 and "slapi_filter_list_next()" on page  298 for details).

Both functions return a filter component of the complex filter or a NULL value:

• If slapi_filter_list_first() returns a NULL, the complex filter is not of the type LDAP_FILTER_AND, LDAP_FILTER_OR, or LDAP_FILTER_NOT.
• If slapi_filter_list_next() returns a NULL, the component returned by the call is the last component in the complex filter.

Converting a String to a Filter

Search filters can be represented by the datatype Slapi_Filter or as strings. (In a parameter block for a search operation, SLAPI_SEARCH_FILTER is a filter of the datatype Slapi_Filter, and SLAPI_SEARCH_STRFILTER is the string representation of that filter.) In general, it is easier to specify a filter as a string than to construct a filter of the type Slapi_Filter.

To convert a string representation of a filter into a filter of the datatype Slapi_Filter, call the slapi_str2filter() function (see "slapi_str2filter()" on page  347 for details).

When you are done working with the filter, you should free it by calling the slapi_filter_free() function (see "slapi_filter_free()" on page  290 for details).

Combining Filters

You can use AND, OR and NOT to combine different filters into a complex filter. To do this, call the slapi_filter_join() function (see "slapi_filter_join()" on page  296 for details).

Note that filters of the type LDAP_FILTER_NOT only have one component. If ftype is LDAP_FILTER_NOT, pass NULL for the second filter.

The function returns the complex filter you've created. When you are done using the complex filter, you should free it by calling slapi_filter_free() function (see "slapi_filter_free()" on page  290 for details).

If you need to manipulate these DNs, you can call the following front-end routines:

Table 3.4 Front-end functions for manipulating DNs

To do this:	Call this function
Determine if a DN is the root DN (the DN of the privileged superuser)	slapi_dn_isroot()
Get a copy of the parent DN	slapi_dn_parent(), slapi_dn_beparent()
Determine if a DN is the child of another DN	slapi_dn_issuffix()
Determine if a DN is a suffix served by one of the server's back-ends	slapi_dn_isbesuffix()
Normalize a DN	slapi_dn_normalize()
Convert all characters in a DN to lowercase	slapi_dn_ignore_case()
Normalize a DN and convert all characters to lowercase	slapi_dn_normalize_case()

Determining if a DN is the Root DN

To determine if a DN is the root DN, call the slapi_dn_isroot() function (see "slapi_dn_isroot()" on page  263 for details).

Working with DN Suffixes

A suffix of a DN identifies a subtree in the directory tree where the DN is located. For example, for the following DN:

cn=Babs Jensen, ou=Product Development, o=Ace Industries, c=US

one of the suffixes is:

o=Ace Industry, c=US

which indicates that the Babs Jensen entry is located in the Ace Industry subtree in the directory tree.

The suffix directive in the slapd.conf configuration file determines which DNs are served by a particular back-end. For example, if the suffix directive is:

suffix "o=Ace Industry, c=US"

the entries within the "o=Ace Industry, c=US" subtree are served by this back-end.

To determine if a value is a suffix for a DN, call the slapi_dn_issuffix() function (see "slapi_dn_issuffix()" on page  264 for details).

To determine if a DN is one of the suffixes served by the back-end, call the slapi_dn_isbesuffix() function (see "slapi_dn_isbesuffix()" on page  261 for details).

Getting the Parent DN of a DN

To get a copy of the parent DN for a DN, call the slapi_dn_parent() function or the slapi_dn_beparent() function (see "slapi_dn_isparent()" on page  262 and "slapi_dn_beparent()" on page  259 for details).

These functions return the parent DN of dn. If dn is a suffix served by the back-end, slapi_dn_beparent() returns NULL.

When you are done working with the parent DN, you should free it from memory by calling free().

Normalizing a DN

If you need to compare DNs (for example, if you are searching your database for a particular DN), you may want to normalize the DNs and make sure that the DNs use the same case.

To normalize and convert the case of a DN, you can call the following functions. Note that these functions operate on the actual DN specified in the argument, not a copy of the DN. If you want to modify a copy of the DN, call the slapi_ch_strdup() function to make a copy of the DN first (see "slapi_ch_strdup()" on page  253 for details).

• slapi_dn_normalize() normalizes the DN (see "slapi_dn_normalize()" on page  265 for details).
• slapi_dn_ignore_case() converts all characters in the DN to lowercase (see "slapi_dn_ignore_case()" on page  260 for details).
• slapi_dn_normalize_case() normalizes the DN and converts all characters in the DN to lowercase (see "slapi_dn_normalize_case()" on page  266 for details).

If you need to determine if a given password is one of the values of the userpassword attribute, you can call the slapi_pw_find() function (see "slapi_pw_find()" on page  330 for details). This function determines which password scheme was used to store the password and uses the appropriate comparison function to compare a given value against the encrypted values of the userpassword attribute.