Lists the immediate subordinates for an eDirectory object and restricts the list to subordinate objects matching a specified object class and/or name.
#include <nwnet.h>
or
#include <nwdsdsa.h>
N_EXTERN_LIBRARY (NWDSCCODE) NWDSListByClassAndName (
NWDSContextHandle context,
pnstr8 objectName,
pnstr8 className,
pnstr8 subordinateName,
pnint_ptr iterationHandle,
pBuf_T subordinates ;)
uses netwin32
Function NWDSListByClassAndName
(context : NWDSContextHandle;
objectName : pnstr8;
className : pnstr8;
subordinateName : pnstr8;
iterationHandle : pnint_ptr;
subordinates : pBuf_T
) : NWDSCCODE;
(IN) Specifies the NDS context for the request.
(IN) Points to the name of the object whose subordinates are to be listed.
(IN) Points to a class name to be used as a filter. This can be NULL.
(IN) Points to an object name to be used as a filter. This can be NULL.
(IN/OUT) Points to information needed to resume subsequent iterations of NWDSListByClassAndName (set to NO_MORE_ITERATIONS initially).
(OUT) Points to a result buffer containing a list of subordinate objects matching the search criteria.
These are common return values.
|
0x0000 0000 |
SUCCESSFUL |
|
0x8996 |
SERVER_OUT_OF_MEMORY |
|
0x89E2 |
TOO_FEW_FRAGMENTS |
|
0x89E3 |
TOO_MANY_FRAGMENTS |
|
0x89E4 |
PROTOCOL_VIOLATION |
|
0x89E5 |
SIZE_LIMIT_EXCEEDED |
|
0x89FD |
UNKNOWN_REQUEST |
|
0x89FD |
INVALID_PACKET_LENGTH |
|
0x89FE |
BAD_PACKET |
|
0x89FF |
Failure not related to eDirectory |
|
0xFE0D |
UNI_NO_DEFAULT |
|
0xFE0F |
UNI_HANDLE_MISMATCH |
|
0xFEB5 |
ERR_NULL_POINTER |
|
nonzero value |
Nonzero values indicate errors. See |
NWDSListByClassAndName controls the list output with filters on the class, on the name, or on both.
If the context handle is set for partial dot names and the flag associated with DCV_TYPELESS_NAMES is set, the returned list of object names in the buffer will be typeless. If the flag is off, the returned list will contain typed names. For more information, see Section 1.1, Context Handles.
The name given for the className ’s filter is the name of an object's base class, such as User, Computer, or NCP Server.
The value given for the 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*.
NULL, which means any name is valid.
The location of the subordinate object(s) in the eDirectory tree is immediately subordinate to the object specified by objectName. It is not relative to the current name context in eDirectory specified by context.
The relationship between className and subordinateName is an "AND" relationship.
When className and subordinateName are provided, the list of immediate subordinate objects is restricted by both filters.
When className is NULL and subordinateName is NULL, all the immediate subordinates are returned.
When className is provided and subordinateName is NULL, the list of immediate subordinates restricted only by className’s filter.
When className is NULL and subordinateName is provided, the list of immediate subordinates is restricted only by subordinateName’s filter.
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 has a naming
attribute beginning with an "o," such as O or OU.
o*=c* Any object whose left-most name has a naming
attribute beginning with an "o," and whose name
begins with "c."
The iterationHandle parameter controls retrieval of search results larger than the result buffer pointed to by subordinates.
Before the initial call to NWDSListByClassAndName, set the iterationHandle parameter to NO_MORE_ITERATIONS.
If the result buffer holds the complete results when NWDSListByClassAndName returns from its initial call, the location pointed to by iterationHandle is set to NO_MORE_ITERATIONS. If the iterationHandle is not set to NO_MORE_ITERATIONS, use the iteration handle for subsequent calls to NWDSListByClassAndName 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 NWDSListByClassAndName, 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 use NWDSCloseIteration to allow users of their applications to abort an iterative process that is taking too long to complete.
To end the List operation before the complete results have been retrieved, call NWDSCloseIteration with a value of DSV_LIST to free memory and states associated with the List operation.
Allocate the result buffer pointed to by subordinates, by calling NWDSAllocBuf. This result buffer does not need to be initialized because it is a result buffer. For more information on reading the results, see Retrieving Results from eDirectory Output Buffers.