Creates a list iterator object and returns a pointer to it for subsequent function calls.
#include <nwnet.h>
or
#include <nwitr.h>
NWDSCCODE NWDSItrCreateList (
NWDSContextHandle context,
pnstr8 baseObjectName,
pnstr8 className,
pnstr8 subordinateName,
nuint32 scalability,
nuint32 timeout,
pnuint_ptr pIterator);
(IN) Specifies the context to use for the request.
(IN) Specifies the starting object to use for the search (usually a container object).
(IN) Specifies an optional filter to restrict the list to the specified object class. It may be NULL to include all classes in the list.
(IN) Specifies an optional filter to restrict the list to objects that match the specified RDN. The RDN may include wildcards. It may be NULL to include all names in the list.
(IN) Specifies whether the function can connect to servers running version of NDS other than NDS 8.
(IN) Specifies the time (in milliseconds) for completing the command.
(OUT) Points to the iterator object returned to the caller.
|
0x0000 0000 |
SUCCESSFUL |
|
ERR_QUERY_TIMEOUT |
Indicates the function reached its timeout limit before it could create the iterator object |
|
nonzero value |
Nonzero values indicate errors. See |
The iterator object returned in the pIterator parameter is used in all other iterator APIs. When the application is done with the iterator object, the iterator object must be destroyed by calling the NWDSItrDestroy function.
This function is similar to the NWDSListByClassAndName function. The big difference is that the list is sorted.
NOTE:The iterator creation process on an NDS 8 server is quick because the container indexes are already created. On servers with previous versions of NDS, the creation process can be slow. Since the index is not already created, the process includes building a list of all the objects in the container and then sorting them. If there are thousands of objects in the container, the task can take such a long time to complete that the application, making the call, appears to malfunction or hang.
The baseObjectName parameter identifies the object (or possibly the root) to which the list is relative. If the string is empty, the current context is selected as the base object.
Aliases are dereferenced while locating the base object unless the context flag associated with DCV_DEREF_ALIASES is not set. The information returned is affected by the context handle flags. For more information, see Context Keys and Flags
(“NDK: Novell eDirectory Core Services”).
The scalability parameter uses the following values:
In emulation mode, the timeout parameter is used to measure the time for reading the data and does not include the time for resolving the name.
NOTE:Don’t confuse the iterator object with the iteration handle. For more information, see Section 1.1, Iterator Objects.
For sample code, see Section 4.3, Creating and Using a List Iterator: Example.