The purpose of eDirectory is to store information in the form of objects that can be accessed easily across the network. eDirectory provides functions for
Listing objects
Reading an object's attributes, attribute values, and extended information
Comparing attribute values
This section describes how to determine what objects are available and how to retrieve the information stored in them. For information on reading schema definitions, see Section 1.13, Read Requests for Schema Information.
For sample code, see the following:
Before you can extract information from an object, you must know what objects are available. That is the purpose of list functions. Essentially, list functions return a list of objects that meet certain conditions.
Each list function provides a method for restricting the list so that it does not include every object in the eDirectory database. Even restricted, many of these functions return more information than the output buffer can hold. These functions use an iteration handle. See the next section for information on using the handle and retrieving all the information.
The iterationHandle parameter controls the retrieval of output data that is larger than the output buffer pointed to by the subordinates parameter in the NWDSList function. Several eDirectory functions (for example, NWDSRead, NWDSReadReferences, and NWDSSearch) use an iteration handle, and they all called it an iterationHandle parameter (the output buffer name varies with the function). Before the initial call to an iterative function, set the contents of the iteration handle pointed to by the iterationHandle parameter to NO_MORE_ITERATIONS.
When the function returns from its initial call, if the output buffer holds the complete results, the value of iterationHandle is set to NO_MORE_ITERATIONS. If the iteration handle is not set to NO_MORE_ITERATIONS, make another call to the function to obtain another portion of the results. When the results are completely retrieved, the value of the iteration handle is once more set to NO_MORE_ITERATIONS.
If you want to end an iterative operation before the complete results have been retrieved, call NWDSCloseIteration to free memory associated with the operation.
Since there is no way to know what a read or list function returns to an output buffer, most of these functions have specialized functions for retrieving the data from the buffer. For example, the NWDSList function returns a list of objects. You would use the following functions to retrieve the information from its output buffer:
|
NWDSGetObjectCount |
Returns the number of objects in the buffer. |
|
NWDSGetObjectName |
Returns a name of an object in the buffer. Must be called for each object. |
If the function returns other information, such as attributes or attributes and values, other functions are provided to find out how many attributes are associated with the object or how many values are associated with an attribute.
When you read eDirectory objects, you are actually talking about retrieving the information that is stored mainly as attributes. For example, a User object could have attributes that include the user’s Surname, Email Address, Title, or Telephone Number attributes. However, the eDirectory database maintains other information about an object, such as when it was created and last modified. You can use the following functions to read information about the object, its attributes, and extended information.
|
Reads the object's attribute information. This is configurable and may include attribute names only, attributes and values, effective privileges, attribute value flags, and attribute creation and modification timestamps. For more information, see Section 5.16, Information Types for Search and Read. |
|
|
Reads object information not stored in the attributes of the object. This includes the base class used to create the object, class flags, the modification time, and the number of objects that are subordinate to this object. |
|
|
Reads values from one or more attributes of the specified object, allowing restrictions on modification time. |
|
|
Returns DSI object information not stored in the attributes of an object.This is configurable and may include information such as object creation and modification timestamps, subordinate object count, and the entry ID of the parent object. If the object is a replica, it may return the entry ID of the partition's root entry, the replica type, purge time, and replica number. For more information, see Section 5.6, Context Keys and Flags. |
|
|
Searches all the replicas on a particular server and returns any objects that contain attributes that reference the specified object. This function can be configurable to also return attribute values. For more information, see Section 5.16, Information Types for Search and Read |
|
|
Reads eDirectory server information from the server the connection handle specifies. This is function can be configurable to return the following information: the number of levels the server is located from the root container, eDirectory version number, OS version, OS name, current UTC time of the server, and the server's eDirectory tree. For more information, see Section 5.19, eDirectory Ping Flags. |
NWDSRead is a representative of eDirectory functions that are configurable. (Others include NWDSSearch, NWDSReadClassDef, and NWDSReadAttrDef.) These functions let you configure the results to be returned.
The eDirectory functions use two methods to configure return results: function parameters and context handle flags.
Function Parameters. Function parameters usually include an infoType parameter that specifies the type of information to return, a boolean parameter that specifies all or only listed items, and a parameter that contains the list of the requested items. For example, the NWDSRead function uses an infoType parameter to specify what attribute information to return, an allAttrs parameter to specify whether all attributes are returned or only specified attributes, and an attrNames parameter which is used to list specific attributes.
If the allAttrs parameter is TRUE, eDirectory returns information for all attributes of the object and the attrNames parameter is ignored. Therefore, the attrNames parameter should be set to NULL. If the allAttrs parameter is FALSE, eDirectory returns the attributes named in the input buffer, which is pointed to by the attrNames parameter.
If the allAttrs parameter is FALSE and the attrNames parameter is NULL, no attribute information is returned. However, you can use the return value of the NWDSRead function to determine whether the object exists or whether access to the object is allowed.
Results are returned in an output buffer that must be allocated by the application. Depending on the size of the output buffer and the amount of information returned, you may need to call a function several times to retrieve all the results.
Context Handle Flags. The flags configure the context handle. Since most eDirectory functions have a context handle parameter, most eDirectory functions are influenced by configuration changes to the context handle. For more information on configuring the context handle, see Section 1.1, Context Handles.
NWDSCompare compares a given value with the values assigned to a specified attribute. For example, you could ask eDirectory to compare whether the Member attribute of a particular group is equal to the name of some User object. If the comparison is TRUE, the user is a member of the group.
NWDSCompare can be a useful alternative to reading an object’s attributes, since it requires less effort on your part to examine the results of the request. Also, depending on your access control rights, you may be able to perform a comparison when you can’t read the information directly.
You initialize buf for a DSV_COMPARE operation and then put an attribute name and value into the buffer. If the proposed value is found, matched returns TRUE; otherwise, matched returns FALSE.