NWDSSearch(3nw)

Synopsis

   #include <nwnet.h> 
   or 
   #include <nwdsdsa.h> 
   
 
   NWDSCCODE N_API NWDSSearch 
     (NWDSContextHandle   context, 
      pnstr8              baseObjectName, 
      nint                scope, 
      nbool8              searchAliases, 
      pBuf_T              filter, 
      nuint32             infoType, 
      nbool8              allAttrs, 
      pBuf_T              attrNames, 
      pnint32             iterationHandle, 
      nint32              countObjectsToSearch, 
      pnint32             countObjectsSearched, 
      pBuf_T              objectInfo); 

Description

context

(IN) Specifies the Directory context for the request.

baseObjectName

(IN) Points to the name of a subtree root to be searched.

scope

(IN) Specifies the depth of the search.

searchAliases

(IN) Specifies whether to dereference aliases in the search subtree. If TRUE, aliases will be dereferenced.

filter

(IN) Points to a search filter constructed by calling NWDSAddFilterToken.

infoType

(IN) Specifies the type of information to be returned.

allAttrs

(IN) Specifies the scope of the request. If TRUE, information concerning all attributes is requested; if FALSE, only attributes named in attrNames is requested.

attrNames

(IN) Points to the names of the attributes for which information is to be returned.

iterationHandle

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

countObjectsToSearch

(IN) Specifies the number of objects for the server to search before the server returns to the client.

countObjectsSearched

(OUT) Points to the number of objects searched by the server.

objectInfo

(OUT) Points to an output buffer containing the names of the objects along with any requested attribute values satisfying the search.

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

NWDSSearch succeeds if the base object is located, regardless of whether there are any subordinates to the base object.

baseObjectName identifies the object (or possibly the root) to which the search is relative. If the string is empty, the current context is selected as the base object.

scope takes one of three possible values:

0	DS_SEARCH_ENTRY	Search applies only to the base object.
1	DS_SEARCH_SUBORDINATES	Search applies only to the immediate subordinates of the base object.
2	DS_SEARCH_SUBTREE	Search applies to the base object and all of its subordinates.

 
 ----------------------------------------------------------------- 
| 0    |  DS_SEARCH_ENTRY       |  Search applies only to the    | 
|      |                        |  base object.                  | 
|------|------------------------|--------------------------------| 
| 1    |  DS_SEARCH_SUBORDINATES|  Search applies only to the    | 
|      |                        |  immediate subordinates of the | 
|      |                        |  base object.                  | 
|------|------------------------|--------------------------------| 
| 2    |  DS_SEARCH_SUBTREE     |  Search applies to the base    | 
|      |                        |  object and all of its         | 
|      |                        |  subordinates.                 | 
|------|------------------------|--------------------------------| 

Aliases are dereferenced while locating the base object unless the context flag associated with DCV_DEREF_ALIASES is not set. Aliases among the subordinates of the base object are dereferenced during the search unless searchAliases is FALSE. If searchAliases is TRUE, the search continues in the subtree of the aliased object.

filter eliminates objects not of interest to the application. Information is returned only on objects which satisfy the filter.

infoType, allAttrs, and attrNames indicate what attribute information is requested.

infoType specifies whether both attribute names and attribute values are requested. True specifies attribute names only; FALSE specifies attribute names and values.

If allAttrs is TRUE, information about all attributes associated with the object is requested and attrNames is ignored (in which case, attrNames can be NULL). If allAttrs is FALSE, only the attributes specified byattrNames are requested.

If allAttrs is FALSE and attrNames is NULL, no attribute information is returned. infoType is not meaningful. In this case, the return value of NWDSRead determines whether the specified object exists, or whether access to the object is allowed.

The buffer pointed to by attrNames is used to explicitly specify the attributes to be returned.

iterationHandle controls the retrieval results that are larger than the result buffer pointed to by objectInfo.

Before calling NWDSSearch initially, set the contents of the iteration handle pointed to by iterationHandle to NO_MORE_ITERATIONS.

If the result buffer holds the complete results when NWDSSearch returns from its initial call, 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 NWDSSearch 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 Search operation before the complete results have been retrieved, call NWDSCloseIteration with a value of DSV_SEARCH to free memory and states associated with the Search operation.

The level of granularity for partial results is an individual attribute value. If the attribute is a multivalued attribute and its values are split across two or more calls to NWDSSearch, the current object name, object info, and attribute name is repeated in each subsequent result buffer.

Currently, because of aliasing, searching a subtree can result (1) in duplicate entries or (2) in an infinite loop.

Follow these steps to search a region of the Direction:

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

2. To select information for selected attributes, go to step 3. Otherwise, go to step 6.

3. Allocate the request buffer by calling NWDSAllocBuf.

4. Initialize the request buffer for a DSV_SEARCH operation by calling NWDSInitBuf.

5. Place the names of the desired attributes into the request buffer by calling NWDSPutAttrName once for each attribute name.

6. To specify a search filter, go to step 7. Otherwise, go to step 11.

7. Allocate a filter expression tree by calling NWDSAllocFilter.

8. Place the search-filter conditions in the expression tree by calling NWDSAddFilterToken once for each search token.

9. Allocate a filter buffer by calling NWDSAllocBuf.

10. Store the search-filter expression tree in the filter buffer by calling NWDSPutFilter.

11. Call NWDSSearch.

12. Determine the number of objects whose information is stored in the buffer by calling NWDSGetObjectCount.

13. Get the name of the current objec tin the buffer and the count of attributes associated with the object by calling NWDSGetObjectName.

14. Retrieve the name of the attribute and the count of values associated with the attribute by calling NWDSGetAttrName.

15. For each value associated with the attribute, retrieve the value by calling NWDSGetAttrVal.

16. Loop to step 14 until all attribute information for the object has been read.

17. Loop to step 13 until the information for all objects in the buffer has been retrieved.

18. Free the filter buffer by calling NWDSFreeBuf.

19. Free the request buffer by calling NWDSFreeBuf.

20. Free the reply buffer by calling NWDSFreeBuf.

You must pull all information from the result buffer even if you do not plan to use it.

Services

Directory

NCP calls

0x2222 23 17

Get File Server Information

0x2222 23 22

Get Station's Logged Info (old)

0x2222 23 28G

et Station's Logged Info

0x2222 104 01

Ping for NDS NCP

0x2222 104 02

Send NDS Fragmented Request/Reply

References