Searches a branch of the eDirectory tree for objects satisfying a specified set of requirements.
#include <nwnet.h>
or
#include <nwdsdsa.h>
N_EXTERN_LIBRARY (NWDSCCODE) NWDSSearch (
NWDSContextHandle context,
pnstr8 baseObjectName,
nint scope,
nbool8 searchAliases,
pBuf_T filter,
nuint32 infoType,
nbool8 allAttrs,
pBuf_T attrNames,
pnint_ptr iterationHandle,
nint32 countObjectsToSearch,
pnint32 countObjectsSearched,
pBuf_T objectInfo);
uses netwin32
Function NWDSSearch
(context : NWDSContextHandle;
baseObjectName : pnstr8;
scope : nint;
searchAliases : nbool8;
filter : pBuf_T;
infoType : nuint32;
allAttrs : nbool8;
attrNames : pBuf_T;
iterationHandle : pnint_ptr;
countObjectsToSearch : nint32;
countObjectsSearched : pnint32;
objectInfo : pBuf_T
) : NWDSCCODE;
(IN) Specifies the NDS context for the request.
(IN) Points to the name of a subtree root to be searched.
(IN) Specifies the depth of the search (see Section 5.22, Scope Flags).
(IN) Specifies whether to dereference subordinate aliases in the search:
(IN) Points to a search filter constructed by calling the NWDSAddFilterToken function. This parameter must be specified (cannot be NULL). To specify no filtering (return all values) construct a filter equivalent to objectclass=*.
(IN) Specifies the type of information to return (see Section 5.16, Information Types for Search and Read).
(IN) Specifies the scope of the information to return:
(IN) Points to the names of the attributes for which information is to be returned.
(IN/OUT) Points to information needed to resume subsequent iterations of NWDSSearch.
(IN) Reserved for future use.
(OUT) Points to the number of objects searched by the server.
(OUT) Points to an output buffer containing the names of the objects along with any requested attribute values satisfying the search.
|
0x0000 0000 |
SUCCESSFUL |
|
nonzero value |
Nonzero values indicate errors. See |
NWDSSearch succeeds if the base object is located, regardless of whether there are any subordinates to the base object.
If a replica-specific error is returned, NWDSSearch tries an alternate replica for the partition. If none of the alternate replicas can be contacted, 0 results are returned without an accompanying error. Please confirm that your client can contact all servers in the tree.
The baseObjectName parameter identifies the object (or possibly the root) to which the search 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. For more information, see Section 5.6, Context Keys and Flags.
Aliases among the subordinates of the base object are dereferenced during the search unless the searchAliases parameter is FALSE. If the searchAliases parameter is TRUE, the search continues in the subtree of the aliased object.
The filter parameter eliminates objects not of interest to the application. Information is returned only on objects that satisfy the filter. For information on building a search filter, see Section 1.4, Search Requests. For step-by-step instructions, see Searching eDirectory.
The infoType, allAttrs, nd 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. In this case, the value returned by NWDSSearch determines whether the specified object exists, or whether access to the object is allowed.
The iterationHandle parameter controls the retrieval results that are larger than the result buffer pointed to by the objectInfo parameter.
Before calling NWDSSearch initially, set the contents of the iteration handle pointed to by the iterationHandle parameter to NO_MORE_ITERATIONS.
If the result buffer holds the complete results when NWDSSearch returns from its initial call, the location pointed to by the iterationHandle parameter is set to NO_MORE_ITERATIONS. If the iteration handle is not set to NO_MORE_ITERATIONS, use the iteration handle for subsequent calls to NWDSSearch to obtain further portions of the results. When the results are completely retrieved, the contents of the iteration handle will be set to NO_MORE_ITERATIONS.
NOTE:On large networks, iterative processes, such as NWDSSearch, might take a lot of time to complete. For example, listing all of the User objects on a corporate network might be too time consuming. Developers should call the NWDSCloseIteration function to allow users of their applications to abort an iterative process that is taking too long to complete.
To end the Search operation before the complete results have been retrieved, call NWDSCloseIteration with a value of DSV_SEARCH to free memory and states associated with the Search operation.
The level of granularity for partial results is an individual attribute value. If the attribute is a multivalued attribute and its values are split across two or more calls to NWDSSearch, the current object name, object info, and attribute name is repeated in each subsequent result buffer.
For example code, see ndssearc.c.
NOTE:Currently, because of aliasing, searching a subtree can result (1) in duplicate entries or (2) in an infinite loop.