|
| Sun ONE Directory Server 5.2 Plug-In API Programming Guide |
Chapter 4 Working with Entries
This chapter covers plug-in API features for handling directory entries, attributes, attribute values, and Distinguished Names (DNs). It also deals with converting entries to and from LDAP Data Interchange Format (LDIF) strings, and with checking whether entries comply with LDAP schema.
Code excerpts used in this chapter can be found in the ServerRoot/plugins/slapd/slapi/examples/entries.c sample plug-in and the ServerRoot/plugins/slapd/slapi/examples/dns.c sample plug-in.
Refer to the Sun ONE Directory Server Plug-In API Reference for complete reference information concerning the plug-in API functions used in this chapter.
Creating Entries
This section demonstrates how to create a new entry in the directory. Create a new entry either by allocating space and creating a wholly new entry, or by duplicating an existing entry and modifying its values.
New Entries
Create a wholly new entry using slapi_entry_alloc() to allocate the memory required, as shown in Code Example 4-1.
Copies of Entries
Create a copy of an entry with slapi_entry_dup() as shown in Code Example 4-2.
Converting To and From LDIF Representations
This section shows you how to use the plug-in API to convert from entries represented in LDIF to Slapi_Entry structures and from Slapi_Entry structures to LDIF strings.
LDIF files appear as a series of human-readable representations of directory entries, optionally with access control instructions as well. Entries represented in LDIF start with a line for the distinguished name, and continue with optional lines for the attributes as shown in Code Example 4-3.
Code Example 4-3 LDIF Syntax Representing an Entry
dn:[:] dn-value\n
[attribute:[:] value\n]
[attribute:[:] value\n]
[single-space continued-value\n]*
A double colon, ::, indicates that the value is base-64 encoded. This makes it possible, for example, to have a line break in the midst of an attribute value.
As shown in Code Example 4-3, LDIF lines can be folded by leaving a single space at the beginning of the continued line.
Sample LDIF files can be found under ServerRoot/slapd-serverID/ldif/. Code Example 4-4 shows two entries represented in LDIF.
Refer to the Sun ONE Directory Server Reference Manual for details on LDIF syntax.
Converting an LDIF String to a Slapi_Entry Structure
This can be done using slapi_str2entry(). The function takes as its two arguments the string to convert and an int holding flags of the form SLAPI_STR2ENTRY_* in slapi-plugin.h. It returns a pointer to a Slapi_Entry if successful, NULL otherwise, as in Code Example 4-5.
Here SLAPI_STR2ENTRY_ADDRDNVALS adds any missing Relative Distinguished Name (RDN) values, as specified in slapi-plugin.h where supported flags for slapi_str2entry() are listed.
Converting a Slapi_Entry Structure to an LDIF String
This can be done using slapi_entry2str(). This function takes as its two arguments the entry to convert and an int to hold the length of the string returned. It returns a char * to the LDIF if successful, NULL otherwise, as in Code Example 4-5.
Getting Entry Attributes and Attribute Values
This section demonstrates how to iterate through real attributes of an entry. Real attributes contrast with virtual attributes generated by Directory Server for advanced entry management using roles and Class of Service (CoS). You may use this technique when looking through the list of attributes belonging to an entry. If you know the entry contains a particular attribute, slapi_entry_attr_find() returns a pointer to the attribute directly.
Iteration through attribute values can be done using slapi_attr_first_value() and slapi_attr_next_value() together as shown in Code Example 4-6.
When working with virtual attributes such as those used for CoS, you may use slapi_vattr_list_attrs() to obtain the complete list of both real and virtual attributes belonging to an entry.
Adding and Removing Attribute Values
This section demonstrates how to add and remove attributes and their values.
Adding Attribute Values
If the attribute name and value are strings, you may be able to use slapi_entry_add_string(), as in Code Example 4-7 that builds an entry by first setting the DN, then adding attributes with string values.
When working with values that already exist or are not strings, you may use slapi_entry_add_values_sv() to add new values to an attribute of an entry, or slapi_entry_attr_merge_sv() to merge new values with the existing values of an attribute. The function slapi_entry_add_values_sv() returns an error when duplicates of the new values already exist; slapi_entry_attr_merge_sv() does not. Code Example 4-8 demonstrates slapi_entry_attr_merge_sv().
If the attribute exists in the entry, slapi_entry_attr_merge_sv() merges the specified values into the set of existing values. If the attribute does not exist, slapi_entry_attr_merge_sv() adds the attribute with the specified values.
Removing Attribute Values
Remove attribute values using slapi_entry_delete_string() or slapi_entry_delete_values_sv().
Verifying Schema Compliance for an Entry
This section demonstrates how to check that an entry is valid with respect to the directory schema known to Directory Server. Verify schema compliance for an entry using slapi_entry_check(). Its two arguments are a pointer to a parameter block and a pointer to the entry, as shown in Code Example 4-9.
Notice the parameter block pointer argument is NULL. Leave the parameter block pointer argument NULL unless the plug-in is used in a replicated environment and you do not want schema compliance verification carried out for replicated operations.
Handling Entry Distinguished Names (DNs)
This section demonstrates how to work with Distinguished Names to:
- Determine the parent DN of a given DN
- Determine the suffix DN with which the entry DN is associated
- Identify whether a root suffix is served by the backend
- Set the DN of the entry
- Normalize the DN of the entry for comparison with other entries
- Determine whether the entry DN is that of the directory superuser
Getting the Parent and Suffix DNs
This can be done using slapi_dn_parent(). This function returns the parent, whereas slapi_dn_beparent() returns the suffix associated with the entry, as shown in Code Example 4-10.
Notice the suffix and parent DNs may be the same if the tree is shallow. For example, if the bind_DN here is uid=yyorgens,ou=People,dc=example,dc=com, then the parent is ou=People,dc=example,dc=com, and so is the suffix.
Checking Whether a Suffix is Served Locally
This can be done using slapi_dn_isbesuffix(), which takes as its two arguments a parameter block and a char * to the root suffix DN, as demonstrated in Code Example 4-11.
Notice we use slapi_dn_isbesuffix() to climb the tree. Notice also that slapi_dn_parent() keeps gnawing away at the DN until it is NULL. The parent does not necessarily correspond to an actual entry.
Getting and Setting Entry DNs
This can be done using slapi_entry_get_dn() and slapi_entry_set_dn(). Code Example 4-9 demonstrates changing the DN of a copy of an entry, using slapi_entry_set_dn(). Notice the use of slapi_ch_strdup() to ensure the old DN in the copy is not used.
Normalizing a DN
Before comparing DNs, you may want to normalize the DNs to prevent the comparison from failing due to extra white space or different capitalization. You may normalize a DN using slapi_dn_normalize(), or slapi_dn_normalize_case() as shown in Code Example 4-12.
The function slapi_dn_normalize_case() works directly on the char * DN passed as an argument to perform "case ignore matching" as specified, but not defined, for X.500. Use slapi_ch_strdup() to make a copy first if you do not want to modify the original.
Is This the Directory Manager?
Answer this question using slapi_dn_isroot(). The bind for the directory superuser, however, as for anonymous users, is handled as a special case. For such users, the server front end handles the bind before calling pre-operation bind plug-ins.