Searches a region of the eDirectory tree for objects satisfying a set of specified requirements, including modification time.
#include <nwnet.h>
or
#include <nwdsdsa.h>
N_EXTERN_LIBRARY (NWDSCCODE) NWDSExtSyncSearch (
NWDSContextHandle context,
pnstr8 baseObjectName,
nint scope,
nbool8 searchAliases,
pBuf_T filter
pTimeStamp_T timeStamp,
nuint32 infoType,
nbool8 allAttrs,
pBuf_T attrNames,
pnint_ptr iterationHandle,
nint32 countObjectsToSearch,
pnint32 countObjectsSearched,
pBuf_T objectInfo);
uses netwin32
Function NWDSExtSyncSearch
(context : NWDSContextHandle;
baseObjectName : pnstr8;
scope : nint;
searchAliases : nbool8;
filter : pBuf_T;
timeStamp : pTimeStamp_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 subtree.
(IN) Points to a Buf_T containing a search filter. This parameter must be specified (cannot be NULL).
(IN) Points to an object-modification time to further restrict the filter provided by filter. This parameter must be specified (cannot be NULL).
(IN) Specifies the type of information to be returned (see Section 5.16, Information Types for Search and Read).
(IN) Specifies the scope of the request: TRUE=information concerning all attributes is requested; FALSE=only attributes named in attrNames are requested.
(IN) Points to a Buf_T containing the attribute names for which information is to be returned.
(IN/OUT) Points to information needed to resume subsequent iterations of NWDSExtSyncSearch. This should be set initially to NO_MORE_ITERATIONS.
(IN) Specifies the number of objects for the server to search before the server returns to the client.
(OUT) Points to the number of objects searched by the server.
(OUT) Points to a Buf_T 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 |
NWDSExtSyncSearch succeeds if the base object specified by baseObjectName is located, regardless of whether there are any subordinates to return.
The baseObjectName parameter identifies the object (or possibly the root) from which the search is relative. If the string is a zero-length string (""), the current name context specified in context is selected as the base object.
Aliases of the base object are dereferenced while locating the base object unless the context flag associated with DCV_DEREF_ALIASES is not set.
The searchAliases parameter determines whether the aliases among the subordinates of the base object are dereferenced during the search. If TRUE, the search continues in the subtree of the aliases object. If FALSE, the search returns information about the alias object.
The filter parameter eliminates objects not of interest to the application. Information is returned only on objects that satisfy the filter. This filter is created by calling NWDSAllocFilter, NWDSAddFilterToken, and NWDSPutFilter. For information about creating a filter, see Section 1.4, Search Requests. For step-by-step instructions, see Searching eDirectory.
When filling out TimeStamp_T, set eventID to zero, replicaNum to zero, and wholeSeconds to the appropriate value.
The infoType, allAttrs, and attrNames parameters indicate what attribute information is requested.
If allAttrs is TRUE, information about all attributes associated with the object is requested and attrNames is ignored (in which case, attrNames can be NULL). If allAttrs is FALSE, only the attributes specified by attrNames are requested.
If allAttrs is FALSE and attrNames is NULL, no attribute information is returned, and infoType is not meaningful. In this case, the return value of NWDSExtSyncSearch simply determines whether the object specified by baseObjectName exists, or whether access to the object is allowed.
The request buffer pointed to by attrNames is used to explicitly specify the names of the attributes to be returned. Initialize this buffer with a value of DSV_SEARCH. For more information, see Preparing eDirectory Input Buffers.
On return, the buffer pointed to by objectInfo contains the information for objects matching the search criteria, along with the requested attribute information. This buffer is allocated by calling NWDSAllocBuf, but it is not initialize. For more information on reading the results, see Retrieving Results from eDirectory Output Buffers.
You must retrieve all information from the buffer even if you do not plan to use it.
The iterationHandle parameter controls retrieval of search results larger than the result buffer pointed to by objectInfo.
Before the initial call to NWDSExtSyncSearch, set the iterationHandle parameter to NO_MORE_ITERATIONS.
If the result buffer holds the complete results when NWDSExtSyncSearch returns from its initial call, the location pointed to by iterationHandle 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 NWDSExtSyncSearch 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 NWDSExtSyncSearch, might take a long time to complete. For example, listing all of the User objects on a corporate network might be too time consuming. Developers should use NWDSCloseIteration 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 multivalued and its values are split across two or more calls to NWDSExtSyncSearch, the current object name, object info, and attribute name are repeated in the subsequent result buffer.
NOTE:Currently, because of aliasing, searching a subtree can result 1) in duplicate entries or 2) in an infinite loop.
NWDSExtSyncSearch can be useful for detecting changes in objects matching a search direction. However, NWDSExtSyncSearch does not return information about objects that have been deleted or for which your privileges have changed.