Lists container objects subordinate to a specific eDirectory object.
#include <nwnet.h> or #include <nwdsdsa.h> N_EXTERN_LIBRARY (NWDSCCODE) NWDSListContainers ( NWDSContextHandle context, pnstr8 object, pnint_ptr iterationHandle, pBuf_T subordinates);
uses netwin32 Function NWDSListContainers (context : NWDSContextHandle; object : 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 subordinate container objects are to be listed.
(IN/OUT) Points to information needed to resume subsequent iterations of NWDSListContainers. This should be initially set to NO_MORE_ITERATIONS.
(OUT) Points to a result buffer containing a list of subordinate container objects.
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 |
0xFE01 |
ERR_BAD_CONTEXT |
0xFE0D |
UNI_NO_DEFAULT |
0xFE0F |
UNI_HANDLE_MISMATCH |
nonzero value |
Nonzero values indicate errors. See |
The name specified by objectName is relative to the current name context in context if partial dot format is used and the DCV_CANONICALIZE_NAMES flag is set. It can be typed or untyped. For more information, see Section 1.1, Context Handles.
iterationHandle controls retrieval of search results larger than the result buffer pointed to by subordinates.
Before the initial call to NWDSListContainers, set the iterationHandle parameter to NO_MORE_ITERATIONS.
If the result buffer holds the complete results when NWDSListContainers returns from its initial call, the location pointed to by iterationHandle is set to NO_MORE_ITERATIONS. If iterationHandle is not set to NO_MORE_ITERATIONS, use the iteration handle for subsequent calls to NWDSListContainers to obtain further portions of the results. When the results are completely retrieved, the contents of iterationHandle will be set to NO_MORE_ITERATIONS.
NOTE:On large networks, iterative processes, such as NWDSListContainers, 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 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 contents of the result buffer pointed to by subordinates are overwritten with each subsequent call to NWDSListContainers. Remove the contents from the result buffer before each subsequent call to NWDSListContainers.
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.