CXCDictionaryStoreData: CXCStreamStoreData

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>>>

The Epoc applications use a stream store, which contains a stream dictionary; this type is supported by the CXCDictionaryStoreData class. Note: the framework currently makes this data type for Epoc application data only. Perhaps there should be a way to open it for different stores as well, should they contain the stream dictionary; seemingly the Epoc API does not support that, though?!?

Note this is a CXCStreamStoreData subclass, so all the CXCStreamStoreData services are available in the API as well.

A dictionary stream store with Epoc application data must contain an application identifier stream (otherwise Epoc won't be able to open that file). You can forget this bore with CXCDictionaryStoreData, for the stream is written into an output data automatically.

-CDictionaryStore *dictionaryStore;

The dictionaryStore method returns the store the same way the store method did; they can be used both, the only difference is in the type is casted to the CDictionaryStore here.

-CStreamDictionary *_rootDictionary;

This way the root dictionary is available in case you need to use it directly (eg. for some application engine from the Epoc SDK).

There are some basic services for the stream access for which you do not need to use the root dictionary directly:

-void readEpocStreamFor(unsigned uid,RDictionaryReadStream &stream); -void writeEpocStreamFor(unsigned uid,RDictionaryWriteStream &stream);

The low-level stream access is provided through the readEpocStreamFor and writeEpocStreamFor methods: they just open the appropriate stream for reading or writing, finding it in the stream dictionary by the UID given. You must use the Epoc services to use the stream and to close it. Mainly the methods are available for the benefit of the Epoc application engines, which generally use streams directly; should you want to use the stream yourself, use the much more flexible and convenient methods below:

-CXCStreamData *readDataFor(unsigned uid); -CXCStreamData *writeDataFor(unsigned uid);

For the more convenient access there are the readDataFor and writeDataFor methods, which provide the read/write streams as well, but embed them into CXCStreamData objects. You then use the abstract objects, whilst the embedded streams are closed automatically when the objects are released. Thence eg. your filter modules can properly share them. Besides, the CXCStreamData class offers quite rich and luxurious API, much more convenient than the plain stream services offered by the Epoc API.

-unsigned epocUid; -void setEpocUid(unsigned uid);

Since the UID1 and UID2 are fixed for the Epoc application data stores, there are only methods epocUid and setEpocUid to get and set the UID3, whilst the UID1/2 are set automatically to the proper values.