NWDSList(3nw)


NWDSList -- lists the immediate subordinates of an object

Synopsis

   #include <nwnet.h> 
   or 
   #include <nwdsdsa.h> 
   

NWDSCCODE N_API NWDSList (NWDSContextHandle context, pnstr8 object, pnint32 iterationHandle, pBuf_T subordinates);

Description

The parameters are as follows:

context
(IN) Specifies the Directory context for the request.

object
(IN) Points to the name of the object whose immediate subordinates are to to be listed.

iterationHandle
(IN/OUT) Points to information needed to resume subsequent iterations of NWDSList.

subordinates
(OUT) Points to a result buffer containing an Object_Info_T structure for each subordinate.

Return values

0x0000
SUCCESSFUL

Negative Value
Negative values indicate errors. For errors returned by Directory Services, see ``Directory Services OS Errors'' (-001 to -255), ``Directory Services Client Library Errors'' (-301 to -399), or ``Directory Services Agent in the Server Errors'' (-601 to -699).

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 Directory Services

Notices

NWDSList succeeds if the object specified by object is found in the Directory, regardless of whether there is any subordinate information to return.

object points to the name of the object whose immediate subordinates are to be listed. Should the name involve one or more aliases, they are dereferenced unless prohibited by the context flag associated with DCV_DEREF_ALIAS.

The results buffer pointed to by subordinates receives a sequence of Object_Info_T structures containing information about objects subordinate to the specified object.

iterationHandle controls the retrieval of list results larger than the result buffer pointed to by subordinates.

Before the initial call to NWDSList, set the contents of the iteration handle pointed to by iterationHandle to NO_MORE_ITERATIONS.

When NWDSList returns from its initial call, if the result buffer holds the complete results, 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 NWDSList in order 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.

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.

To determine an object's immediate subordinates, follow these steps:

  1. Allocate memory for the result buffer by calling NWDSAllocBuf. This buffer does not need to be initialized since it is a result buffer.

  2. Set the iteration handle to NO_MORE_ITERATIONS.

  3. Call NWDSList.

  4. Determine the number of subordinate objects whose information is contained in the result buffer by calling NWDSGetObjectCount.

  5. Call NWDSGetObjectName for each subordinate object whose information is stored in the buffer.

  6. If the iteration handle is not set to NO_MORE_ITERATIONS, loop to step 3. Otherwise, go to step 7.

  7. Free the result buffer by calling NWDSFreeBuf.

Services

Directory

NCP calls

0x2222 23 17
Get File Server Information

0x2222 23 22
Get Station's Logged Info (old)

0x2222 23 28
Get Station's Logged Info

0x2222 104 01
Ping for NDS NCP

0x2222 104 02
Send NDS Fragmented Request/Reply

References

NWDSSearch(3nw)
30 January 1998
© 1998 The Santa Cruz Operation, Inc. All rights reserved.