ct_ds_lookup

Description

Initiate or cancel a directory lookup operation.

Syntax

CS_RETCODE ct_ds_lookup(connection, 
              action, reqid, lookup_info,
              userdata)
 
 CS_CONNECTION           connection;
 CS_INT                              action;
 CS_INT                              *reqid;
 CS_DS_LOOKUP_INFO   *lookup_info;
 CS_VOID                            *userdata;

Parameters

connection: A pointer to a CS_CONNECTION structure. A CS_CONNECTION structure contains information about a particular connection.

action

One of the following symbolic values:

Action	Function performed
CS_CLEAR	Cancel the directory lookup operation specified by reqid. Supported for asynchronous connections only.
CS_SET	Initiate a directory lookup operation.

reqid

A pointer to a CS_INT variable.

When action is CS_SET, Client- Library returns the request identifier in *reqid.

When action is CS_CLEAR, *reqid specifies the request ID of the operation to cancel.

lookup_info

The address of a CS_DS_LOOKUP_INFO structure.

A CS_DS_LOOKUP_INFO structure is defined as follows:

typedef struct _cs_ds_lookup_info

         CS_OID          *objclass;

         CS_CHAR         *path;

         CS_INT          pathlen;

         CS_DS_OBJECT    *attrfilter;

         CS_DS_OBJECT    *attrselect;

 } CS_DS_LOOKUP_INFO;

When action is CS_SET, set the fields of *lookup_info as follows:

**Table 3-21: Contents of *lookup_info for a ct_ds_lookup(CS_SET) call**
Field	Set to
objclass	The address of a CS_OID structure that specifies the class of directory objects to search for. objclass->oid_buffer contains the OID string for the object class and objclass->oid_length specifies the length of the OID string (not counting any null terminator). ct_ds_lookup finds only those directory entries whose class matches the contents of lookup_info->objclass.
path	Reserved. Set to NULL to ensure compatibility with future versions of Client-Library.
pathlen	Reserved. Set to 0 to ensure compatibility with future versions of Client-Library.
attrfilter	Reserved. Set to NULL to ensure compatibility with future versions of Client-Library.
attrselect	Reserved. Set to NULL to ensure compatibility with future versions of Client-Library.

In asynchronous mode, the contents of *lookup_info and the pointers contained in it must remain valid until the connection’s completion callback or ct_poll indicates that the request has completed or was canceled.

When action is CS_CLEAR, lookup_info must be passed as NULL.

userdata

The address of user-allocated data to pass into the directory callback.

When action is CS_SET, userdata is optional and can be passed as NULL. If ct_ds_lookup finds matching directory entries, Client-Library invokes the connection’s directory callback. The directory callback receives the address specified as userdata. userdata provides a means for the callback to communicate the search results back to the mainline code where ct_ds_lookup was called.

When action is CS_CLEAR, userdata must be passed as (CS_VOID *) NULL.

Returns

ct_ds_lookup returns the following values:

Return value	Meaning
CS_SUCCEED	The routine completed successfully
CS_FAIL	The routine failed
CS_PENDING	Asynchronous network I/O is in effect. See “Asynchronous programming”. On platforms where Client-Library does not use thread-driven I/O, applications must always poll for ct_ds_lookup completions even when the connection’s CS_NETIO setting is CS_ASYNC_IO.
CS_BUSY	An asynchronous operation is already pending for this connection. See “Asynchronous programming”.
CS_CANCELED	The lookup request was canceled by the application. Lookup requests can be canceled only on asynchronous connections.

Examples

Example 1

For an explanation of the steps in this example, see Chapter 9, “Using Directory Services,” in the Open Client Client-Library/C Programmer’s Guide.

Usage

ct_ds_lookup initiates or cancels a directory lookup request.
ct_ds_lookup, ct_ds_objinfo, and the connection’s directory callback routine provide a mechanism for Client-Library applications to view directory entries. The typical process is outlined below.
1. The application installs a directory callback to handle the search results.
2. (Network-based directories only.) The application sets the CS_DS_DITBASE connection property to specify the subtree to be searched.
3. (Network-based directories only.) The application sets any other necessary directory service properties to constrain the search.
4. The application calls ct_ds_lookup to initiate the directory search.
5. Client-Library calls the application’s directory callback once for each directory entry found. Each invocation of the callback receives a CS_DS_OBJECT pointer, that provides an abstract view of the directory entry’s contents.
6. The application examines each object by calling ct_ds_objinfo as many times as necessary. This can be done in the callback or in the mainline code.
7. When the application is finished with the directory objects returned by the search, it frees the memory associated with them by calling ct_ds_dropobj.

Directory callbacks

The results of directory searches are returned to the connection’s directory callback. Client-Library invokes the directory callback once for each entry found in the search, and each invocation receives a pointer to a CS_DS_OBJECT that describes the entry.
Before beginning a search, the application must install a directory callback with ct_callback(CS_DS_LOOKUP_CB) to receive the search results. Otherwise, the results are discarded.
See “Defining a directory callback” for a description of directory callbacks.

Initiating directory lookups

ct_ds_lookup(CS_SET) passes a request to the directory driver specified by the current setting of the CS_DS_PROVIDER connection property. See “Directory service provider”.
If the search uses a directory service rather than the interfaces file, then the search finds all directory entries which match these criteria:
- The object class of the entry matches the OID specified by the objclass field in ct_ds_lookup’s lookup_info parameter.
- The entry is under the directory node that is specified as the CS_DS_DITBASE connection property. See “Base for directory searches”.
- The entry is within the depth limit defined by the CS_DS_SEARCH connection property. See “Directory service search depth”. By default, ct_ds_lookup returns only those entries that are located directly beneath the DIT-base node.
If the interfaces file is searched, the search must be for server (CS_OID_SERVERCLASS) objects. A search returns a description of all servers defined in the interfaces file.
Some directory service providers may have access restrictions for directory entries. In this case, the application must provide a value for the CS_DS_PRINCIPAL connection property. See “Directory service principal name”.

Synchronous vs. asynchronous directory lookups

ct_ds_lookup(CS_SET) passes a lookup request to the underlying directory service. The request returns the matching objects to Client-Library. The processing cycle differs for asynchronous and synchronous connections.
If the connection is synchronous, ct_ds_lookup blocks until the lookup request has completed and the application has finished viewing returned objects in the directory callback. Synchronous processing happens as follows:
1. The application’s main-line code calls ct_ds_lookup(CS_SET) to initiate the lookup operation.
2. When the search is complete, Client-Library begins invoking the directory callback and passing the returned objects to the application.
  
  If the search failed for any reason, then Client-Library passes CS_FAIL as the value of the status callback argument.
  
  The callback is invoked repeatedly, once for each object found or until the directory callback returns CS_SUCCEED.
3. ct_ds_lookup returns control to the mainline code.
  
  To provide fully asynchronous support, ct_ds_lookup requires a version of Client-Library that uses thread-driven I/O. With other versions, ct_ds_lookup gives deferred-asynchronous behavior when CS_NETIO is set to CS_ASYNC_IO or CS_DEFER_IO.
If the connection is fully asynchronous or deferred asynchronous, then ct_ds_lookup returns immediately. The detailed process is as follows:
1. The application's mainline code calls ct_ds_lookup(CS_SET) to initiate the lookup operation.
2. Client-Library passes the request to the directory service driver.
  
  If the directory driver accepts the request, ct_ds_lookup returns CS_PENDING. On platforms where Client-Library uses threads, Client-Library spawns an internal worker thread to handle the request at this point.
  
  If the request cannot be queued, ct_ds_lookup returns CS_FAIL.
3. The connection's directory callback is invoked. On a fully asynchronous connection, Client-Library invokes the callback automatically. On a deferred-asynchronous connection, Client-Library invokes the callback when the application calls ct_poll.
  
  If the search returned objects, then the callback is called repeatedly to pass objects to the application until the application has seen all the objects or the callback returns CS_SUCCEED.
  
  If the lookup found no objects, then the callback is called once with the numentries callback argument equal to 0.
  
  If the search failed or was canceled, then the callback is called once with CS_FAIL or CS_CANCELED as the status callback argument.
4. The connection’s completion callback is invoked. On a fully asynchronous connection, Client-Library invokes the completion callback automatically. On a deferred-asynchronous connection, the application must poll for request completion with ct_poll, and ct_poll invokes the callback. The completion callback receives the final return status for the lookup operation (CS_SUCCEED, CS_FAIL, or CS_CANCELLED).
  
  On fully asynchronous connections, the directory and completion callbacks are invoked by an internal Client-Library thread. Make sure that shared data is protected from simultaneous access by mainline code, other application threads, and the callback code executing in the Client-Library thread. The contents of *userdata must also be protected from simultaneous access.

Canceling a directory lookup (asynchronous connections only)

If the connection’s network I/O mode (CS_NETIO property) is fully asynchronous or deferred asynchronous, then a lookup operation can be canceled by calling ct_ds_lookup(CS_CLEAR, &reqid) before the search completes.
- ct_ds_lookup(CS_CLEAR) returns immediately with a status of CS_SUCCEED or CS_FAIL. However, the connection remains busy until the directory provider acknowledges the request. At this point, Client-Library invokes the directory callback and the completion callback, in that order, with a status of CS_CANCELED.
- ct_ds_lookup(CS_CLEAR) cannot be called after the connection’s completion callback or ct_poll has indicated that the search has completed. At this point, the request has been fulfilled, and ct_ds_lookup(CS_CLEAR) will fail.
Applications can also truncate the search results simply by returning CS_SUCCEED rather than CS_CONTINUE from the directory callback.
Lookup requests made on synchronous connections cannot be canceled. However, a time limit for request completion can be set if the underlying directory service provider supports it. See “Directory search time limit”.