Home

	Expand Search

Open Client Client-Library/C Reference Manual

Chapter 2 Topics

Callbacks

Directory callbacks

Directory callbacks

The ct_ds_lookup routine and the application's directory callback provide the mechanism which an application uses to examine the contents of directory entries.

When an application calls ct_ds_lookup to begin a directory search, Client-Library retrieves the appropriate entries from the directory and then calls the directory callback once for each entry. Each time the callback is invoked, it receives a pointer to one directory object structure. Each directory object structure contains a copy of information read from a directory entry.

Client-Library calls the directory callback once for each entry retrieved, as long as the callback returns CS_CONTINUE. When the callback returns CS_SUCCEED, Client-Library discards any remaining objects that the callback has not received.

The directory callback calls only the Client-Library routines ct_con_props, ct_config, ct_ds_objinfo, and ct_ds_dropobj. On an asynchronous connection, the application uses the completion callback to call other Client-Library routines (see Table 2-2).

A directory callback is defined as follows:

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 a 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 are found, numentries includes the current object. If no entries are 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.

A directory callback typically performs the following to collect and optionally process the results of a directory search:

1. Checks the values of status and numentries to determine whether the search was successful and whether entries were returned.

   • A status value of CS_SUCCEED indicates that the search was successful.

   • A numentries value greater than 0 indicates that entries were found.

2. Either saves the pointer to the directory object; or copies any information that it wants to keep (using ct_ds_objinfo to extract the information), then frees the directory object's memory with ct_ds_dropobj.

3. Returns control to Client-Library in one of the following ways:

   • Returns CS_SUCCEED to drop all remaining unexamined entries

   • Returns CS_CONTINUE so that Client-Library calls the callback routine again to process the next object returned by the directory search

If a search is successful, Client-Library invokes the directory callback with numentries as the total number of entries to be examined. If the search finds no entries, numentries is 0. If the search finds one or more entries, numentries gives the number of unexamined entries including the current entry.

The application examines all the entries simply by returning CS_CONTINUE from the callback each time Client-Library invokes the callback. ct_ds_lookup invokes the callback repeatedly until one of the following conditions is satisfied:

• The callback returns CS_SUCCEED.

• The callback has received every directory object in the search results. If the callback returns CS_CONTINUE when numentries is 0 or 1, it is not invoked again before ct_ds_lookup completes.

• If the callback returns a value other than CS_CONTINUE or CS_SUCCEED, the current Client-Library response is the same as for CS_SUCCEED. However, this behavior may change in future versions. To ensure compatibility with future versions, applications should return only CS_CONTINUE or CS_SUCCEED from directory callbacks.

If asynchronous network I/O is in effect for the connection, all invocations of the directory callback occur before Client-Library invokes the application's completion callback.

If synchronous network I/O is in effect for the connection, all invocations of the directory callback occur before ct_ds_lookup returns.

Directory callbacks are used with ct_ds_lookup. See the ct_ds_lookup reference page for an example directory callback.