After authenticating to an eDirectory tree, the most common tasks are those associated with adding information to the tree (objects and attribute values), modifying the information, and reading (searching and comparing) the existing information. This section provides procedures for these kinds of tasks:
To add an object to eDirectory, follow these steps:
Allocate memory for the request buffer by calling NWDSAllocBuf.
Set the iterationHandle to NO_MORE_ITERATIONS.
Initialize the request buffer for a DSV_ADD_ENTRY (7) operation by calling NWDSInitBuf.
For each attribute to be supplied for the object, first store the attribute’s name in the result buffer by calling NWDSPutAttrName. Then store the associated value(s) in the result buffer by calling NWDSPutAttrVal once for each value.
You must supply the mandatory values for the object class as dictated by the schema.
Create the new object by calling NWDSAddObject.
Free the request buffer by calling NWDSFreeBuf.
NOTE:The name of the object is specified by objectName. The naming attribute is mandatory, but it is specified in the call. It is does not have to be explicitly placed in the objectInfo buffer.
Follow these steps to compare an object’s attribute value with another value:
Allocate a request buffer by calling NWDSAllocBuf.
Initialize the request buffer for a DSV_COMPARE operation by calling NWDSInitBuf.
Place the name of the attribute whose value you want to compare into the request buffer by calling NWDSPutAttrName.
Place the value you want to compare into the buffer by calling NWDSPutAttrVal.
Compare the values by calling NWDSCompare.
Check matched to see if the values matched.
Free the request buffer by calling NWDSFreeBuf.
There is no need to prepare a buffer when performing this task.
To delete an Object, call NWDSRemoveObject
This function requires only the context handle and the name of the object to be removed, as shown in the following example:
ccode = NWDSRemoveObject(contextHandle, objectName);
NOTE:You cannot remove an object that contains subordinates. All objects in a container must be removed before the container object can be removed.
Determine an object’s effective privileges on another object by following these steps:
Allocate the result buffer by calling NWDSAllocBuf. This buffer does not need to be initialized since it is a result buffer.
If you want to retrieve information for selected attributes, complete Steps 3 through 5. To retrieve information for all of the object’s attributes, skip to Step 6.
Allocate the request buffer by calling NWDSAllocBuf.
Initialize the request buffer for a DSV_READ operation by calling NWDSInitBuf.
Place the attribute names in the request buffer by calling NWDSPutAttrName once for each attribute name.
Set iterationHandle to NO_MORE_ITERATIONS.
Determine the number of attributes in the result buffer by calling NWDSGetAttrCount.
For each attribute in the result buffer, retrieve the information by calling NWDSGetAttrVal.
If the iteration handle is not equal to NO_MORE_ITERATIONS, loop to Step 7. Otherwise, go to Step 11.
Free the request buffer by calling NWDSFreeBuf.
Free the result buffer by calling NWDSFreeBuf.
eDirectory fills results buffers with discrete units of information. If the whole unit cannot fit into the buffer, the entire unit will be withheld until the next iteration. For NWDSListAttrsEffectiveRights, a unit of information consists of an attribute name and privilege.
If you need information on aborting an iterative operation, see Controlling Iterations.
The steps for determining the addresses on a server where an object is located are as follows:
Allocate a result buffer by calling NWDSAllocBuf. This buffer does not need to be initialized since it is a result buffer.
Call NWDSGetAttrCount to determine the number of attributes stored in the result buffer.
Call NWDSGetAttrName to retrieve the attribute name (network address) and the count of attribute values.
For each attribute value, call NWDSComputeAttrValSize to find the size of the current address in the result buffer.
Allocate a block of memory the size of the attribute value.
Retrieve the current address from the result buffer by calling NWDSGetAttrVal and passing in the pointer allocated in Step 5.
When NWDSGetAttrVal returns, typecast the pointer to be a pointer to Net_Address_T, to access the information.
Free the allocated memory before retrieving the next address. (Network addresses can be different sizes.)
Loop to Step 4 until all addresses have been removed from the result buffer.
This task finds all of the immediate subordinates of an object.
Allocate memory for the output buffer by calling NWDSAllocBuf.
Set the iteration handle to NO_MORE_ITERATIONS.
Call NWDSList.
Determine the number of subordinate objects in the output buffer by calling NWDSGetObjectCount.
Call NWDSGetObjectName for each subordinate object in the output buffer.
If the iteration handle is not equal to NO_MORE_ITERATIONS, loop to Step 3. Otherwise, go to Step 7.
Free the output buffer by calling NWDSFreeBuf.
If you need information on aborting an iterative operation, see Controlling Iterations.
Modifying objects that already exist in eDirectory is very similar to adding a new object.
Allocate a data buffer by calling NWDSAllocBuf.
Initialize the buffer for a DSV_MODIFY_ENTRY (9) operation by calling NWDSInitBuf.
For each attribute value to be modified, place the desired changes into the buffer using NWDSPutChange and NWDSPutAttrVal.
NWDSPutChange is used to indicate which attribute is to be modified, and NWDSPutAttrVal places the new attribute value into the buffer.
Also, a value can be modified by placing a combination of DS_REMOVE_VALUE and DS_ADD_VALUE change records in the same request buffer. This allows the operations to be completed by calling NWDSModifyObject once.
On multivalued attributes
If you want to remove a value and add a new value, you must place two changes in the request buffer: one to remove the old value using the DS_REMOVE_VALUE flag and one to add the new value with the DS_ADD_VALUE flag.
If you want to ensure the attribute has a value without triggering synchronization, use NWDSCompare (comparison operations are faster than read or write operations).
If you want to ensure the attribute has a value, its timesstamp is updated, and synchronization is triggered, use NWDSModifyObject with the DS_OVERWRITE_VALUE flag as the changeType.
The attrName parameter simply refers to a text string containing the attribute name (for example “Surname”). The buf parameter points to a buffer that has been allocated by calling NWDSAllocBuf and initialized by calling NWDSInitBuf. Make sure you use the DSV_MODIFY_ENTRY operation when you initialize the buffer. The changeType parameter refers to an integer value that defines what type of operation will be made on the named attribute. See Section 5.5, Change Types for Modifying Objects.
Make the modification by calling NWDSModifyObject.
Remember, if an attempt is made to modify the Object Class attribute on NDS 7.xx and below, an error is returned. NDS 8 and above allows modifications to the Object Class attribute (see Adding an Auxiliary Class to an eDirectory Object).
Auxiliary class are only supported on servers running NDS 8 or higher. If you connect to a server running an earlier version of eDirectory that has a replica with the object, you cannot added the auxiliary class to the object because the Object Class attribute cannot be modified. To add an auxiliary class, you must use a connection to a server that is running NDS 8 and that also has a replica with the object.
The following steps assume that you have connected to an NDS 8 server and that the auxiliary class is defined in the eDirectory schema. Auxiliary classes are added to the schema just like other schema definitions. (For more information, see Creating a Class Definition.)
To add an auxiliary class to a User object, complete the following steps.
Allocate a data buffer by calling NWDSAllocBuf.
Initialize the buffer for a DSV_MODIFY_ENTRY (9) operation by calling NWDSInitBuf.
Use the NWDSPutChange function to put the Object Class attribute in the data buffer and NWDSPutAttrVal function to put the name of the auxiliary class in the data buffer.
Auxiliary classes can have mandatory attributes. If the class you added in Step 3 has mandatory attributes, you must put the attribute name and its value into the same data buffer that adds the auxiliary class to the Object Class attribute. Use the functions listed in Step 3 to add any mandatory attributes.
Values for optional attributes can be added now or later.
Add the auxiliary class by calling NWDSModifyObject.
You can add and delete only auxiliary class values from the Object Class attribute. The values that define the object's base class and its super classes are protected so that they cannot be deleted.
Read the attributes of an object by following these steps:
Allocate memory for the output buffer by calling NWDSAllocBuf.
If you are requesting information for all attributes, skip to Step 6.
Call NWDSAllocBuf to allocate memory for the input buffer.
Call NWDSInitBuf to initialize the input buffer for a DSV_READ operation.
Call NWDSPutAttrName once for each attribute name being placed in the input buffer.
Set iteration handle to NO_MORE_ITERATIONS.
Set infoType to DS_ATTRIBUTE_VALUES.
Call NWDSRead.
Call NWDSGetAttrCount to determine the number of attributes in the output buffer.
Call NWDSGetAttrName to retrieve the name of the current attribute and the number of its values from the output buffer.
Call NWDSComputeAttrValSize to determine the size of the attribute value; then allocate a block of memory that size.
Call NWDSGetAttrVal to read the attribute value. For multivalued attributes, call this function for each of the values.
Free the memory that was allocated in Step 11.
If all of the attribute information has not been read from the output buffer, loop to Step 10.
If the iteration handle is not equal to NO_MORE_ITERATIONS, loop to Step 8.
If an input buffer was allocated, free the input buffer by calling NWDSFreeBuf.
Free the output buffer by calling NWDSFreeBuf.
The results of NWDSRead are not ordered and might not appear in alphabetical order.
If infoType is set to DS_ATTRIBUTE_VALUES, specifying the Read operation should return both attribute names and values. You must retrieve the information in the correct order; attribute name first, then all of the values associated with the attribute. Then you must retrieve the next attribute name and its values and so on. Otherwise, NWDSGetAttrName will return erroneous information.
If you need information on aborting an iterative operation, see Controlling Iterations.
Searching eDirectory is presented here as a sequential list of subordinate tasks to accomplish.
Follow these steps to search a region of eDirectory:
Call NWDSAllocBuf to allocate the result buffer. This buffer does not need to be initialized because it is a result buffer.
To search selected attributes, go to Step 3. Otherwise, go to Step 6.
Call NWDSAllocBuf to allocate the request buffer.
Call NWDSInitBuf to initialize the request buffer for a DSV_SEARCH operation.
Call NWDSPutAttrName once for each attribute name to place the names of the desired attributes into the request buffer.
Call NWDSAllocFilter to allocate a filter expression tree.
Call NWDSAddFilterToken once for each search token to place the search-filter conditions in the expression tree.
To select all objects, use the filter
FTOK_BASECLS *
Call NWDSAllocBuf to allocate a filter buffer.
Call NWDSInitBuf to initialize the request buffer for a DSV_SEARCH_FILTER operation.
Call NWDSPutFilter to store the search-filter expression tree in the filter buffer.
Call NWDSSearch to start the search. Make sure iterationHandle is set to NO_MORE_ITERATIONS before calling the function.
Call NWDSGetObjectCount to determine the number of objects whose information is stored in the result buffer.
Call NWDSGetObjectName to get the name of the current object in the buffer and the count of attributes associated with the object.
Call NWDSGetAttrName to retrieve the name of the attribute and the count of values associated with the attribute.
Call NWDSComputeAttrValSize to determine the size of the attribute value; then allocate a block of memory that size.
For each value associated with the attribute, call NWDSGetAttrVal to retrieve the value.
Free the memory that was allocated in Step15.
Loop to Step 14 until all attribute information for the object has been read.
Loop to Step 13 until the information for all objects in the buffer has been retrieved.
If the iteration handle is not equal to NO_MORE_ITERATIONS, loop to Step 11.
Call NWDSFreeBuf to free the filter buffer.
Call NWDSFreeBuf to free the request buffer.
Call NWDSFreeBuf to free the result buffer.
You must pull all information from the result buffer even if you do not plan to use it.
Currently, because of aliasing, searching a subtree can result (1) in duplicate entries or (2) in an infinite loop.
If you need information on aborting an iterative operation, see Controlling Iterations.