Lists the immediate subordinates for an eDirectory object and places restrictions on the subordinate's names, classes, modification times, and object types.
#include <nwnet.h>
or
#include <nwdsdsa.h>
N_EXTERN_LIBRARY (NWDSCCODE) NWDSExtSyncList (
NWDSContextHandle context,
pnstr8 objectName,
pnstr8 className,
pnstr8 subordinateName,
pnint_ptr iterationHandle,
pTimeStamp_T timeStamp,
nbool onlyContainers,
pBuf_T subordinates);
uses netwin32
Function NWDSExtSyncList
(context : NWDSContextHandle;
objectName : pnstr8;
className : pnstr8;
subordinateName : pnstr8;
iterationHandle : pnint_ptr;
timeStamp : pTimeStamp_T;
onlyContainers : nbool;
subordinates : pBuf_T
) : NWDSCCODE;
(IN) Specifies the NDS context for the request.
(IN) Points to the name of the object whose immediate subordinate objects are to be listed.
(IN) Points to a class name to be used as a filter (can contain wildcards).
(IN) Points to an object name to be used as a filter (can contain wildcards).
(IN/OUT) Points to information needed to resume subsequent iterations of NWDSExtSyncList. This should be set to NO_MORE_ITERATIONS initially.
(IN) Points to an object-modification time to be used as a filter (can be NULL).
(IN) Specifies whether the results should include only container objects: TRUE=only container objects; FALSE=other objects.
(OUT) Points to a Buf_T containing a list of subordinate objects matching the filters.
|
0x0000 0000 |
SUCCESSFUL |
|
nonzero value |
Nonzero values indicate errors. See |
The name specified by className’s filter is the name of an object class, such as User, Computer, or Server. It can be a specific name or a string containing wildcards. A wildcard can be a zero-length string, or a string containing asterisks (*):
"" or "*" specifies all class names.
"U*" specifies all class names beginning with "U".
The value given for subordinateName ’s filter can be one of the following:
The left-most name of an object, such as Adam or Graphics Printer.
A string with asterisks (*), such as A* or Gr*.
A zero length string ("" ), which means any name is valid.
The following examples show how to use wildcards for untyped names:
c* Any object whose left-most name begins with a "c"
character.
M*y Any object beginning with "M" and ending with "y"
such as Mary.
If the wildcard name specified for subordinateName includes a type, such as "CN," the name must include the equals (=) sign. The following examples show how to use wildcards for typed names:
cn=* Any object whose left-most name is a common name.
cn=c* Any object whose left-most name is a common name
and begin with "c."
o*=* Any object whose left-most name is of an attribute
type beginning with an "o," such as O or OU.
o*=c* Any object whose left-most name is of an attribute
type beginning with an "o," and whose name begins
with "c."
The timeStamp filter restricts the result to objects having modification times greater than or equal to the time specified in timeStamp.
When filling out TimeStamp_T, set eventID to zero, replicaNum to zero, and wholeSeconds to the appropriate value.
The iterationHandle parameter controls retrieval of results larger than the result buffer pointed to by subordinates.
Before the initial call to NWDSExtSyncList, set the contents of the iteration handle pointed to by iterationHandle to NO_MORE_ITERATIONS.
If the result buffer holds the complete results when NWDSExtSyncList returns from its initial call, the location pointed to by iterationHandle is NO_MORE_ITERATIONS. If the iteration handle is not NO_MORE_ITERATIONS, use the iteration handle for subsequent calls to NWDSExtSyncList to obtain further portions of the results. When the results are completely retrieved, the contents of the iteration handle will be NO_MORE_ITERATIONS.
To end the List operation before the complete results have been retrieved, call NWDSCloseIteration with a value of DSV_SEARCH to free memory and states associated with the List operation.
The onlyContainers parameter specifies whether the results should be restricted to include information for container objects only. If onlyContainers is FALSE (0), the result contains information for objects of all object types. If any other value is given, only information for container objects is returned.
Allocate the result buffer pointed to by subordinates by calling NWDSAllocBuf. The result buffer does not need to be initialized because it is a result buffer.
The contents of the result buffer pointed to by subordinates is overwritten with each subsequent call to NWDSExtSyncList. Remove the contents from the result buffer before each subsequent call to NWDSExtSyncList.
The results of NWDSExtSyncList are not ordered and might not be in alphabetical order.
For more information, see Retrieving Results from eDirectory Output Buffers.
NOTE:On large networks, iterative processes, such as NWDSExtSyncList, might take a long time to complete. For example, listing all of the User objects on a corporate network might be too time consuming. These processes can be interrupted or aborted using NWDSCloseIteration.
Developers should use NWDSCloseIteration to allow users of their applications to abort an iterative process that is taking too long to complete.