Tutorial: Birthdays - Persistent Storage

This example shows how to use the Carbide.c++ UI Designer for S60 to define the UI of an application and to implement the "real work" in the generated code.

The goals of the application are to:

Persistent Storage

The document class (CBirthdaysDocument) contains the necessary overrides to stream the data to and from disk.

Note: most S60 documentation claims that the document class, inherited from Symbian OS, is deprecated. Probably for the uses of most advanced applications, which need more than a single file, this is true. Our example uses the file loading/storing capabilities of this class for didactic brevity. Probably an advanced application would use a more elaborate mechanism to manage this data.

S60's CAknDocument class turns off support for automatically loading the document when the program starts; we derive our document from CEikDocument to work around this. The document is persisted to a location automatically determined by the application UID and the first TBUF{} struct in <project>.rss. On my system it's "C:\Symbian\9.1\S60_3rd\Epoc32\winscw\c\private\010ae5b3\Birthdays".

We overload the StoreL() and RestoreL() methods of CEikDocument to handle saving and loading. These establish a stream store and a dictionary on that store. We use the application UID to identify the data we are storing or retrieving, then stream out the document into the store.

We store the birthdays as binary streams using RWriteStream and RReadStream. The InternalizeL() and ExternalizeL() methods provided on TBirthday and CBirthdaysDocument are the entry points for this streaming.

Note that these are not part of an interface or virtual function overloads; instead, they are referenced by the template "operator << (RReadStream&, T&)" and "operator >> (RWriteStream&, const T&)" methods.

Given the use of CEikDocument, loading of the birthdays list through RestoreL() is automatic, though saving is still manual. Whenever the list modifies a birthday, it invokes the document's SaveL() method to ensure the latest changes are persisted.