NWDSExtSyncSearch(3nw)

Synopsis

   #include <nwnet.h> 
   or 
   #include <nwdsdsa.h> 
   
 
   NWDSCCODE N_API NWDSExtSyncSearch 
     (NWDSContextHandle   context, 
      pnstr8              baseObjectName, 
      nint                scope, 
      nbool8              searchAliases, 
      pBuf_T              filter 
      pTimeStamp_T        timeStamp, 
      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.

filter

(IN) Points to a Buf_T containing a search filter. This parameter must be specified (cannot be NULL).

timeStamp

(IN) Points to an object-modification time to further restrict the filter provided by filter. This parameter must be specified (cannot be NULL).

infoType

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

allAttrs

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

attrNames

(IN) Points to a Buf_T containing the attribute names for which information is to be returned.

iterationHandle

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

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 Buf_T 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

NWDSExtSyncSearch succeeds if the base object specified by baseObjectName is located, regardless of whether there are any subordinates to return.

baseObjectName identifies the object (or possible the root) from which the search is relative. If the string is a zero-length string (``''), the current name context specified in context is selected as the base object.

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 aliases object.

scope takes one of three possible values:

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

filter eliminates objects not of interest to the application. Information is returned only on objects which satisfy the filter. This filter is created by calling NWDSAllocFilter, NWDSAddFilterToken, and NWDSPutFilter.

When filling out TimeStamp_T, set eventID to zero, replicaNum to zero, and wholeSeconds to the appropriate value.

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

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 by attrNames 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 NWDSExtSyncSearch simply determines whether the object specified by baseObjectName exists, or whether access to the object is allowed.

The request buffer pointed to by attrNames is used to explicitly specify the names of the attributes whose information is to be returned. The request buffer should be prepared by using the following steps:

1. Allocate the request buffer by calling NWDSAllocBuf.

2. Initialize the request buffer for a DS_SEARCH by calling NWDSInitBuf.

3. One-by-one, place the names of the desired attributes into the request buffer by calling NWDSPutAttrName.

On return, the buffer pointed to by objectInfo contains the information for objects matching the search criteria, along with the requested attribute information. The contents of the request buffer must be retrieved using the following steps:

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

2. Get the name of the current object in the result buffer and the count of attributes associated with the object by calling NWDSGetObjectName.

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

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

5. Loop to step 3 until all attribute information for the object has been read.

6. Loop to step 2 until the information for all of the objects in the result buffer has been retrieved.

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

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

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

If, when NWDSExtSyncSearch returns from its initial call, 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 NWDSExtSyncSearch 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 multivalued and its values are split across two or more calls to NWDSExtSyncSearch, the current object name, object info, and attribute name repeated the subsequent result buffer.

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

NWDSExtSyncSearch can be useful for detecting changes in objects matching a search direction. However, NWDSExtSyncSearch does not return information about objects that have been deleted or for which your privileges have changed.

Services

Directory

NCP calls

References