Creates an iterator object and returns a pointer to it for subsequent function calls.
#include <nwnet.h>
or
#include <nwitr.h>
NWDSCCODE NWDSItrCreateSearch (
NWDSContextHandle context,
pnstr8 baseObjectName,
nint scope,
nbool8 searchAliases,
pBuf_T filter,
pTimeStamp_T pTimeFilter,
nuint32 infoType,
nbool8 allAttrs,
pBuf_T attrNames,
pnstr8 indexSelect,
pnstr8 sortKey,
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 a base object only, its immediate subordinates, or a subtree search (see Scope Flags
(“NDK: Novell eDirectory Core Services”)).
(IN) Specifies whether subordinate alias objects are dereferenced:
(IN) Specifies the search filter.
(IN) Points to a TimeStamp_T
structure containing a modification time stamp to filter with (optional).
(IN) Specifies whether attribute names or attribute names and values should be returned (see Information Types for Search and Read
(NDK: Novell eDirectory Core Services)).
(IN) Specifies if all attributes should be returned:
(IN) Specifies a list of attributes to return if allAttrs is FALSE. Passing NULL specifies no attributes will be returned.
(IN) Specifies an optional string that selects the index that the iterator object can use. Used only on servers running NDS 8.
(IN) Specifies a comma-separated list of attributes that are used to sort the objects in the list. Used only on servers not running NDS 8.
(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.
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”).
Subtree searches are partially supported. If a subtree search is attempted by setting the scope parameter to DS_SEARCH_SUBTREE, the function searches the server's replicas. If the search requires replicas that do not exist on the server, the search returns with the information its has gathered from the server's replicas.
The filter parameter eliminates objects not of interest to the application. The search filter is created in the same manner as the search filter is created for the NWDSSearch function. It allows you to restrict the objects in the list to those objects that match the following types of conditions:
Contain specified attributes
Contain attributes with values equal to, greater than, or less than the specified value
Belong to the same base class
Have attributes with the same modification or creation timestamp
See Search Requests
(NDK: Novell eDirectory Schema Reference) for more information on how to create a search filter.
If an iterator is created with a search filter that produces an empty list, the NWDSItrCreateSearch function succeeds. A list is produced with only the EOF position. Any read or move commands will return ERR_EOF_HIT. The iterator should be destroyed the same as any iterator.
The infoType, allAttrs, and attrNames parameters indicate what attribute information is requested.
If the allAttrs parameter is TRUE, information about all attributes associated with the object is requested and the attrNames parameter is ignored (in which case, the attrNames parameter can be NULL). If the allAttrs parameter is FALSE, only the attributes specified by the attrNames parameter are requested.
If the allAttrs parameter is FALSE and the attrNames parameter is NULL, no attribute information is returned and the infoType parameter is not meaningful.
If the indexSelect parameter is NULL or an empty string, the search filter is used to select the index on NDS 8 servers. If NULL is specified, eDirectory chooses the optimum index to use based on the search filter. To select the index, use one of the following strings:
The sortKey parameter is ignored for NDS 8 servers. For eDirectory servers not running NDS 8, this parameter specifies an attribute string to use to sort the objects. The attribute must have a string syntax. If NULL is passed, "_BaseClass,_RDN" is used. This string is not an attribute but a special symbol that causes the iterator to be sorted first by object's base class, and within the base class, by the object's naming attribute. Up to three attributes can be specified, separated by a comma (for example, "Surname, Given Name, CN"). The first attribute in the list is considered the primary sort key.
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.4, Creating a Search Iterator and Displaying the Results: Example.
NWDSItrClone, NWDSItrDestroy, NWDSItrCreateList, NWDSSearch (“NDK: Novell eDirectory Core Services”)