NWDSListByClassAndName(3nw)


NWDSListByClassAndName -- lists a Directory object's immediate subordinates, restricting the list to subordinate objects matching a specified object class and/or name

Synopsis

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

NWDSCCODE N_API NWDSListByClassAndName (NWDSContextHandle context, pnstr8 objectName, pnstr8 className, pnstr8 subordinateName, pnint32 iterationHandle, 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 subordinates are to be listed.

className
(IN) Points to a class name to be used as a filter. This can be NULL.

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

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

subordinates
(OUT) Points to a result buffer containing a list of subordinate objects matching the search criteria.

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

0xFFFFFE0D
UNI_NO_DEFAULT

0xFFFFFE0F
UNI_HANDLE_MISMATCH

0xFFFFFEB5
ERR_NULL_POINTER

Notices

NWDSListByClassAndName controls the list output with filters on the class and/or name.

If the context 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.

The name given for className's filter is the name of an object class, such as User, Computer, or Server.

The value given for subordinateName's filter can be one of the following:

The location of the subordinate object(s) in the Directory tree is immediately subordinate to the object specified by objectName. It is not relative to the current name context in the Directory specified by context.

The relationship between className and subordinateName is an ``AND'' relationship.

When className and subordinateName are provided, a list of immediate subordinate objects restricted by both filters is returned.

When className is NULL and subordinateName is NULL, a list of all immediate subordinates is returned.

When className is provided and subordinateName is NULL, a list of immediate subordinates restricted only by className's filter is returned.

When className is NULL and subordinateName is provided, a list of immediate subordinates restricted only by subordinateName's filter is returned.

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

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

Before the initial call to NWDSListByClassAndName, set the contents of the iteration handle pointed to by iterationHandle 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 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 NWDSListByClassAndName with a value of DSV_SEARCH 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.

Follow these steps to remove the contents from the result buffer:

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

  2. Remove the object names from the result buffer by calling NWDSGetObjectName once for each object name in the result buffer.

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)
30 January 1998
© 1998 The Santa Cruz Operation, Inc. All rights reserved.