Chapter 5   Front-End API Functions

In some situations, you might need to create a new entry. There are two basic ways to do this:

• By allocating memory for a new entry.
  
  To allocate memory for a new entry, call the slapi_entry_alloc() function. This function returns a pointer to a new entry of the opaque datatype Slapi_Entry. Once you create a new entry, you should call other front-end routines to set the DN and attributes of the entry.

• By copying an existing entry.
  
  To make a copy of an existing entry, call the slapi_entry_dup() routine. This function returns a pointer to a new entry of the datatype Slapi_Entry that contains the copied data.

When you are finished using the entry, you should free it from memory by calling the slapi_entry_free() function.

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=Jane Doe
inski, ou=Accoun
ting, o=ex
ample.com

Refer to the Netscape Directory Server Administrator's Guide for details on DN syntax.

If a double-colon is used after a data type, it signifies that the value after the double-colon is encoded as a base-64 string. Data is sometimes encoded as a base-64 string. For example, it might be encoded this way if the value contains a non-printing character or newline.

To get the LDIF 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_filter_free() function.
  
  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.
  
  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.

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.
• To set the DN for an entry, call the slapi_entry_set_dn() function.

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 database schema.

To see if an entry complies with the schema, call the slapi_entry_schema_check() function.

There are two basic ways to obtain the attributes and values of an entry:

• You can iterate through the attributes of the entry, testing each one to see if it is the needed attribute.
  
  
• You can use the slapi_entry_attr_find() function to see if an entry has a specific attribute.

Once you find the attribute you are looking for, use slapi_attr_value_find() to return the value of that attribute.

You can also call front-end routines to add or remove attributes and values in an entry. The front-end provides the following functionality:

• To add new values to an entry, call the slapi_entry_add_values_sv() function.
  
  
• To remove values from an entry, call slapi_entry_delete_values_sv().
  
  
• 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_sv() function.

To determine if a DN is the root DN, call slapi_dn_isroot(). This function returns 1 if the specified DN is the root DN of the local database. It returns 0 if the DN is not the root DN.

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

cn=Babs Jensen,ou=Product Development,o=Example Corporation,c=US

In this case, one of the suffixes is:

o=Example Corporation,c=US

This suffix indicates that the Babs Jensen entry is located in the Example Corporation subtree in the directory tree.

To determine if a value is a suffix for a DN, call slapi_dn_issuffix(). To determine if a DN is one of the suffixes served by the backend, call the slapi_dn_isbesuffix() function.

To get a copy of the parent DN for a DN, call the slapi_dn_parent() function or the slapi_dn_beparent() function.

These functions return the parent DN of dn. If dn is a suffix served by the backend, slapi_dn_beparent() will return NULL.

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

If you need to compare DNs (for example, if you are searching your database for a particular DN), you should normalize the DNs that you are comparing to ensure that they are properly compared.

You can use the following front-end function to normalize and convert the case of a DN:

• Use slapi_dn_normalize() normalize a DN.
  
  
• Use slapi_dn_ignore_case() to convert all characters in a DN to lowercase.
  
  
• Use slapi_dn_normalize_case() to both normalize the DN and convert all characters in the DN to lowercase.
  

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.

Getting the Filter Type

To determine the type of filter you are using, call slapi_filter_get_choice(). This function returns the filter type, which can be any one of the following values:

To get the search criteria 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 slapi_filter_get_ava().
  
  
• If the filter type is LDAP_FILTER_PRESENT, you can get the attribute type that the filter is searching for by calling the slapi_filter_get_type() function.
  
  
• If the filter type is LDAP_FILTER_SUBSTRINGS, you can get the attribute type that the filter searches for by calling slapi_filter_get_subfilt().
  
  
• 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.

Both of these functions will return either a filter component of the complex filter or a NULL value, according to the following:

• If slapi_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_list_next() returns a NULL, the component returned by the call is the last component in the complex filter.
  

A search filter can be represented by either the datatype Slapi_Filter or as a string. 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 it is to construct a filter from the type Slapi_Filter.

To convert the string representation of a filter into a filter of the datatype Slapi_Filter, call the slapi_str2filter() function.

When you are done working with the filter, you should free it by calling the slapi_filter_free() function.

You can use AND, OR and NOT to combine different filters to create a complex filter. To do this, call the slapi_filter_join() function.

The slapi_filter_join() 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().

Filters of the type LDAP_FILTER_NOT can have only one component. If the filter type (ftype) is LDAP_FILTER_NOT, you must pass a NULL value for the second filter when calling slapi_filter_join().