XConversion

alpha version, October 2000

The Epoc standard libraries offer moderate services, but there is almost no support for format conversions. Though, particularly for mobile computers the Epoc is aimed to a good conversion technology is extremely important. Thence, the XSdk contains an extensive set of classes and services of the XConversion framework, which supports that. The XConversion framework is based on the generic services of the luxury XFoundation framework.

Note that this comprehensible framework is and for ever will be completely free. We want to encourage as wide usage of it as possible, to support a free intergchange of formats under Epoc (besides, you shall see the filter API is designed so that it can be in principle ported even into other operating environments: there are no direct links to the Epoc API). We would extremely appreciate if the XConversion filters are in future made automatically for each new proprietary document formats, and we are willing to support that as widely as we can.

The XConversion framework consists of an open architecture of dynamically loadable filters, and a set of classes which support them; these classes are available in the XConversion DLL. Currently, the architecture of a filter is mainly documented, allowing anybody to make new filters. The usage of filters--ie. support for writing applications, which load and use the filters-- will be documented later.

A filter is a CXCFilter object (it should be in principle a class, but for the historical reasons--C++ does not support classes at all, and the XFoundation framework was not available when the XConversion was firstly proposed--it is an instance). A filter

contains some bookkeeping information (like the filter name);
knows the type(s) of the source and target data;
contains hints, which can be used to guess roughly whether a piece of data can be converted or not (like a suffix for file name);
can create conversions on demand.

A conversion is a CXCConversion object, which performs the actual filtering or, may we say, conversion. It is made by a filter object, and it is given the data which should be converted, and the target type (ie. the format the data should be converted into). Note: In a typical implementation each conversion class will serve just one pair of types--different types will be made by different conversions. Though, this is not assumed by the framework, and one conversion might serve as many types as its programmer wants.

The data type (or format) is fully qualified by a CXCDataType object, which not only represents the data type (like Epoc Word, MBM Epoc Multi Bitmap file, TIFF image, plain text file, WK1 spreadsheet, TAR archive, WAV sound file, RTF text...), but is also used to guess which data type an opened file belongs to.

Finally, the data themselves are represented by a CXCGeneralData object (or, more precisely, by an object of some CXCGeneralData concrete subclass). There is an embedded CXCDataType, and methods for proper access to the data, regardless its actual representation. Therefore, making a filter you will use just, say, a CXCStreamData object to read / write data from / to a stream, freeing yourself from any considerations of the "real meaning" of the stream: the data, in fact, can be in a file, or in one stream in an Epoc stream store, or in the clipboard, or the CXCStreamData might represent just a pipe to another process. Your filter will work properly for all the cases, and you need not to consider them yourself; that is fully addressed by the XConversion framework.

Besides, there are some auxiliary classes, but the rough image of the four classes mentioned above is sufficient for a proper idea of the XConversion mechanism:

a CXCFilter represents the whole filter;
it is given CXCGeneralData objects, which represent the input and output data
- each CXCGeneralData object in turn contains a CXCDataType objects, which represent the type of the data;
using the data / data type information, the CXCFilter makes a CXCConversion object;
which performs the actual conversion.

The actual loadable filter is a polymorphic DLL, which can contain one or more filters. The XConversion framework (particularly the CXCCvFramework class, which will be in details described in future versions of this documentation) scans the Epoc filesystem for these DLLs, loads them in and offers the filter services to concrete applications. There is the XConverter application available, which performs this task; in future, the full XConversion framework will allow any application to do so.

To be able to use any conversion class, you have to include just one header file: the "XConversion.h". The appropriate library is linked in automatically, as soon as you add the XFoundation framework to the project (see the XSdk frameworks system). You might want to have a look at these documents:

What is XConversion: a user-level description of the XConversion suite;

Currently, the XConversion API contains the following classes:

CXCConversion: the main conversion class, performs the format conversion algorithm;
CXCCvFramework: the general services of scanning for the loadable filters and using them. This class is not needed for filter developmentl; instead, it is used by the code which loads and uses the filters;
CXCDataType: specifies a type of data, like TIFF image, Epoc Data file, or RTF Rich Text document;
CXCFilter: the main filter class, makes conversions on demand;
CXCGeneralData and its concrete subclasses: represent actual data and ensure access to them;
CXCProgress: an intermediate between the conversion framework and particular user interface system.

Besides the class system, there are the following documents closely related to the XFoundation:

Filter DLLs and bundles: where and how the filter DLLs are placed;
Examples: comprehensive and commented source examples of some simple filters.