CXCGeneralData

alpha version, October 2000

<<<sorry, this document is slightly out of date. Temporarily, check it please against the header file; we shall soon provide a documentation upgrade>>>

So as to be flexible enough, the input and output data must be represented by proprietary classes in the XConversion framework. The data objects are relatively complicated, to be able to support properly all the different data available to be converted, from a plain ASCII text file to a quite complicated stream store or, say, the contents of the Agenda server. Thence, abstract classes are used here: the public classes described below define the API, while the framework actually uses hidden subclasses of them. All the API classes are named CXC<something>Data.

Each the data object contains an embedded CXCDataType; it specifies the type of the data, represented by the CXC*Data object.

The basic CXCGeneralData API, inherited by all the other data classes, is quite simple:

-CXCDataType *dataType;

It just returns the embedded data type.

-BOOL isInputData;

Informs whether this particular data is used for input or for output.

-CXString *filename;

The full filename (including path and extension) of the file which is represented by the data object; nil if the data are not in a file.

Note that the data might not be in a file (they can lay in the clipboard, or whatever); never try therefore to use the file directly--the framework opens or closes it automatically when needed. The filename is provided just for information; a conversion might eg. want to export a comment into a HTML file from which original file the HTML was created.

-void commit;

The commit method flushes all output buffers to disk (or to the place where the output data are stored). It does nothing for input data. You can call it as soon as you want to; or you can skip it, for it is called automatically before the data object is deallocated.

Should you implement your own CXCGeneralData concrete subclass, do not forget to call this from the dealloc method.

-void removeIfPossible;

This method is called by the framework code for output data when conversion was aborted; it removes the partial data. Unless you implement your own CXCGeneralData concrete subclass, you don't need even to know it is there.

Currently the following API CXCGeneralData subclasses are available:

CXCStreamData represent a binary or textual stream of data, like a plain file, one Epoc stream or alike;
CXCStreamStoreData represent an Epoc stream store. It is seldom used directly; rather it serves as an intermediate class for
CXCDictionaryStoreData, which represent a store with a stream dictionary; all the Epoc application files are represented by a CXCDictionaryStoreData hidden concrete subclasses.

There will be more API subclasses available soon; eg. a CXCRichTextData, able to represent any formatted text (whether it lays inside an Epoc Word application document or a Jotter page) is currently in development.

It is also possible for a filter DLL to define its own CXCGeneralData concrete subclasses, but the appropriate documentation is not finished yet.