Defining the directory callback

A directory callback has the following prototype:

 CS_RETCODE CS_PUBLIC 

 directory_cb (connection, reqid, status,

              numentries, ds_object, userdata)

 CS_CONNECTION   *connection;

 CS_INT          reqid;

 CS_RETCODE      status;

 CS_INT          numentries;

 CS_DS_OBJECT    *ds_object;

 CS_VOID         *userdata;

where:

• connection is the pointer to the CS_CONNECTION structure used for the directory lookup.

• reqid is the request identifier returned by the ct_ds_lookup call that began the directory lookup.

• status is the status of the directory lookup request. status can be one of the following values:

  Status value	Meaning
  CS_SUCCEED	Search was successful
  CS_FAIL	Search failed
  CS_CANCELED	Search was canceled with ct_ds_lookup(CS_CLEAR)

• numentries is the count of directory objects remaining to be examined. If entries were found, numentries includes the current object. If no entries were found, numentries is 0.

• ds_object is a pointer to information about one directory object. ds_object is (CS_DS_OBJECT *)NULL if either of the following is true:

  • The directory lookup failed (indicated by a status value that is not equal to CS_SUCCEED), or

  • No matching objects were found (indicated by a numentries value that is 0 or less).

• userdata is a pointer to a user-supplied data area. If the application passes a pointer as ct_ds_lookup’s userdata parameter, then the directory callback receives the same pointer when it is invoked.

  userdata provides a way for the callback to communicate with mainline code.

The callback can return CS_CONTINUE or CS_SUCCEED.

• A return of CS_SUCCEED truncates the search results: Client-Library discards any remaining directory objects and stops invoking the callback.

• A return of CS_CONTINUE causes Client-Library to invoke the callback with the next directory object in the search results.