Novell Doc: NDK: Novell eDirectory Iterator Services

1.6 Retrieval of Data

The data retrieval functions return entries to the user relative to the current position.

Function	Description
NWDSItrGetCurrent	Returns the entry at the current position, leaving the position unchanged.
NWDSItrGetNext	Returns “n” entries starting from the current position, including the current entry. The position is moved to the next unread entry.
NWDSItrGetPrev	Returns the previous “n” entries in reverse sort order, not including the current entry. The position is moved to the last entry read, which is closest to the top of the list.

The following sections describe how these functions work and their common characteristics. These include

1.6.1 Iteration Handles and Result Buffers

All data retrieval functions have an iteration handle parameter and a result buffer parameter. The iteration handle is used to retrieve additional information when the requested information does not fit in the result buffer. The default buffer size is 4 KB (DEFAULT_MESSAGE_LEN). However, you can set it to a smaller size or to a larger size, depending the types of data your application uses. The maximum size is 63 KB (MAX_MESSAGE_LEN).

You must set the iteration handle to -1 the first time you call a “Get” function. If the iteration handle is still set to -1 after the call, all the data has been retrieved. If it has any other value, all of the data could not fit in the result buffer. You should unpack the data from the buffer and then repeatedly call the function to retrieve additional data until the iteration handle is set to -1.

1.6.2 Data Unpacking Functions

Information is retrieved from the result buffers with the same specialized functions that are used to retrieve information from the result buffers of the NWDSRead and NWDSSearch functions. Since the NWDSItrCreateSearch function supports only two information types (attribute names and attribute names with values), the iterator functions do not need as many specialized functions as NWDSRead to retrieve data. The data retrieval functions ( NWDSItrGetCurrent, NWDSItrGetNext, and NWDSItrGetPrev) require the following functions to unpack the data from the result buffer.

Function	Description
NWDSGetObjectCount	Returns the number of objects whose information is stored in the result buffer.
NWDSGetObjectName	Returns the name of the current object and the count of attributes associated with the object.
NWDSGetAttrName	Returns the attribute's name and the number of values associated with the attribute. If values are not requested in the information type, the number of values is always zero.
NWDSGetAttrVal	Returns the attribute's value. This function must be called for each value associated with the attribute.
NWDSComputeAttrValSize	Returns the size of the attribute's value. This function is required only if you don't know the size of the attribute.

For step-by-step instructions for retrieving data, see Section 2.2, Retrieving and Unpacking Object and Attribute Name Data and Section 2.3, Retrieving and Unpacking Object, Attribute, and Value Data.

1.6.3 Count of Objects in the List

The NWDSItrCount function returns the number of entries left in the list, starting from the current position. In very large lists, this might take a long time. A timeout value in seconds and a maxCount parameter might be supplied to limit the time NWDSItrCount can take, which allows for estimation of the total count. For example, starting from the top of the list, a 2-second count might return a timeout status and a count of 10,000 entries. Calling NWDSGetPosition might indicate the position is now at the 20% mark. Therefore, a reasonable estimate for the total count is 50,000. Specifying zero for both timeout and maxCount will return an exact count no matter how long it takes.