- COM Interfacing
-
The Content Provider public interfaces are COM interfaces.
- Clients and Sessions
-
A CA DataMinder component (Content Indexer, Content Proxy, or any other) that connects to a Content Provider is called a client.
When a client creates an object instance of the public coclass, this instance forms a session with the Content Provider. A client may potentially have multiple sessions with a Content Provider. Each session is independent.
- Functions
-
A Content Provider can provide up to two functions: an “Indexer” function and a “Query” function.
- A Content Provider may implement only one of the function (for segregation of functionality across multiple hosts), but will typically implement both functions.
- For each function that it supports, a Content Provider must be able to provide logical instances of it to clients. When a client requests any function instance through a session, the Content Provider creates a logical instance of the function. The Content Provider returns to the client a function-specific COM interface pointer to access the instance. You can therefore have indexer instances and query instances.
- How the COM identity that is underlying an instance is implemented is at the discretion of the Content Provider, but logical segregation must exist. That means, from the point of view of a client session, each function instance is independent, in configuration and in execution, from any other instance and any other function. An exception would be an irrecoverable problem that occurs in a function instance that requires the whole Content Provider to shut down; in this case, all other function instances are obviously affected. Just like for the public coclass, the implementations of the functions must be multithreaded.
- Use of XML
-
The Content Provider and its clients use XML to pass information back and forth.
- Encoding is restricted and constrained to be little-endian UTF-16.
- A Content Provider is responsible for providing XML that is little-endian UTF-16, and that is guaranteed to be valid for the XML schema version it declares to support.
- Own Configuration
-
A Content Provider needs to manage two sets of configuration parameters for itself.
- External database-specific configuration parameters control how the Content Provider interfaces with the third-party database system. For example, this can be a communication port number.
- Internal configuration parameters control how the Content Provider manages itself. For example, this can be a timeout value to report a document indexing operation as failed if the third-party database system has not responded in time.
These configuration parameters are the Content Provider’s responsibility and are entirely under its control. Where and how these parameters are located and set up is up to each Content Provider. We recommend the use of the registry. Clients do not have access to these parameters.
Note: CA Technologies has provisionally defined an ICISConfigure interface together with an example of XML structure. The aim is to pass configuration information from and to a Content Provider (including a Content Provider’s own configuration, for instance to allow GUI-based configuration management). This interface is currently reserved. Do not implement it.
- Own logging
-
- A Content Provider is free to do its own logging (which is recommended).
- A Content Provider does not do any logging for its clients. Each client does its own logging, and depends on status reports from a Content Provider to do so.
- Status Reports
-
Content Providers use Status reports to report on the state of a function instance, on the progress of an operation (including its start) and its outcome (completion), or on the result of an action by a client (feedback). Status reports are also used to return search results and output from GetStatus() calls.
Apart from returning search results etc, there are two reasons why Content Providers generate status reports:
- A client depends on status reports to log the state of its functions in use, and to log the progress of its individual operations. This logging is crucial to keep the customer informed of what is happening, and also for diagnostic purposes.
- A client depends on status reports to control its execution, for example, to keep track of the indexing of documents.
- Status Callback Mechanism
-
- All status reports are made through ICISStatusCallback callback interface pointers supplied by a client. The only exceptions are status reports that are returned directly as an output of an interface method call, for example, ICISContentIndexer::GetStatus().
- A client must pass valid status callback interface pointers to a Content Provider.
- A Content Provider must use the appropriate status callback interface pointers to send status reports, and it must do so on time.
- A Content Provider may aggregate multiple status reports to send through the same status callback interface pointer. It may report them all with one call to ICISStatusCallback::ReportStatus() rather than with multiple individual calls.
- Status codes
-
Status codes are of data type HRESULT.
