NWDSExtSyncList(3nw)


NWDSExtSyncList -- lists Directory object's immediate subordinates

Synopsis

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

NWDSCCODE N_API NWDSExtSyncList (NWDSContextHandle context, pnstr8 objectName, pnstr8 className, pnstr8 subordinateName, pnint32 iterationHandle, pTimeStamp_T timeStamp, nbool onlyContainers, pBuf_T subordinates);

Description

The parameters are as follows:

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

objectName
(IN) Points to the name of the object whose immediate subordinate objects are to be listed.

className
(IN) Points to a class name to be used as a filter (can contain wildcards).

subordinateName
(IN) Points to an object name to be used as a filter (can contain wildcards).

iterationHandle
(IN/OUT) Points to information needed to resume subsequent iterations of NWDSExtSyncList. This should be set to NO_MORE_ITERATIONS initially.

timeStamp
(IN) Points to an object-modification time to be used as a filter (can be NULL).

onlyContainers
(IN) Specifies whether the results should include only container objects: TRUE=only container objects; FALSE=other objects.

subordinates
(OUT) Points to a Buf_T containing a list of subordinate objects matching the filters.

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).

Notices

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 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.''
timeStamp's 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.

iterationHandle controls retrieval of search 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, when NWDSExtSyncList returns from its initial call, the result buffer holds the complete results, 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 in order 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.

onlyContainers 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.

Take the following steps to remove the contents from the result buffer:

  1. Determine the number of object names in the result buffer by calling NWDSGetObjectCount.

  2. For each object name in the result buffer, call NWDSGetObjectName to retrieve the object name.
The results of NWDSExtSyncList are not ordered and might not be in alphabetical order.

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

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