Content Provider Development Guide › Implementing the Query Function › Query Instance

Query Instance

Searching

A client sends a query by calling ICISContentQuery::Search(). Search() executes the query and returns results.

Searching is a synchronous operation by default, with Search() returning only when it has search results, or if the query fails. See also Synchronous Behavior below.

1. The first thing that Search() does is try to “accept” the query. This is conceptually similar to the queuing of a document with Index(), and is signaled by the Query instance sending a “queued” status report to the client. To send the status report, it uses the ICISStatusCallback interface pointer given as a Search() call parameter.
2. A Content Provider should fail to accept a query only if the Search() call parameters are structurally invalid (for example, a NULL ICISStatusCallback interface pointer), or for other exceptional circumstances, such as failing to allocate memory, or failing to notify the client of the query’s acceptance.

   Note: Notifying the client of the query’s acceptance is an integral part of the process, in a similar fashion to the queuing mechanism for indexing. If calling ICISStatusCallback::ReportStatus() fails, then the Query instance should fail to accept the query. This way, it is not possible to have a situation where a query is accepted but the client has not yet received the “queued” status report for it.

3. If Search() fails to accept the query, it returns an error code. No status report is generated for the query.
4. If Search() succeeds in accepting the query, it sends a “queued” status report for the query. When the query completes, it sends a “completed” status report, independent of whether it was successful. It then returns, either with a success code and the results, or with a failure code (copied from the “completed” status report) and no results.

This mechanism helps ensure that besides incorrect API usage (an issue at the client) and a minimum of unexpected failures (for example, running out of memory), the start and end of a query is always logged. In other words, the acceptance of a query is the expected behavior, even if it fails almost immediately because of trivia such as an invalid parameter value. You should report any failure reason, such as invalid XML syntax, invalid configuration parameter, connection failure to the content database service, inconsistent or invalid search parameters, and others, through the "completed" status report. This approach maximizes information provided through logging.

The Search() call supplies two separate pieces of data: the query configuration parameters, and the query search parameters. It also supplies the ICISStatusCallback interface pointer that the Query instance uses to send status reports to the client about the query.

The Search() method returns search results (if applicable) in the ppSearchResultsXml output parameter. If the search is asynchronous, results (if applicable) are fed through status reports.

See ICISContentProvider.idl for more behavior details.

Canceling a Search

A client can cancel ongoing searches by calling ICISContentQuery::CancelSearch().

See ICISContentProvider.idl for more behavior details.

Synchronous Behavior

A Content Provider must support searching synchronously. This is the default behavior. Synchronous searching means that a call to ICISContentQuery::Search() returns only when it has search results, or if the query fails.

A Content Provider can also support asynchronous searching. If so, this capability must be indicated in the Query function information element (see the XML schema).

The ICISContentIndexer::Search() method implementation must verify if a client wants to run an asynchronous search, and fail if appropriate (for example, with CIS_E_NOT_SUPPORTED).

See ICISContentProvider.idl for more detail about the expected behavior of asynchronous searching and Search() in particular.

Note: The CA DataMinder 14.0 and 14.1 Content Indexer Server (client) does not currently use synchronous indexing. This may change in future releases.

Status Reports

The Query instance sends status reports for a query by calling the ReportStatus() method on the ICISStatusCallback interface pointer that the Query instance received when the client called ICISContentIndexer::Search().

The Query instance must send status reports when:

• The query is accepted.
• The query completes (independent of whether it was successful).

The Query instance may send optional status reports when, for example the query is taking too long.

Multithreading

The implementation of the ICISContentQuery interface must be multithreaded.

A client may call methods on an ICISContentQuery interface pointer from multiple threads.