How to use the model classes

• To construct a model call NewL() for the required class.

• To open the model call OpenL() to open the model, associating it with a file from which to read/write data.

A model must be constructed and then opened before it can be used. Opening the model associates it with a file (document) containing agenda data. Agenda data is accessed via the agenda server, provided by RAgnServ.

The following example shows how to construct and open the model and connect to the agenda server.

RAgendaServ* agnServer = RAgendaServ::NewL(); // allocate and construct server
CleanupStack::PushL(agnServer);
agnServer->Connect(); // connect to the agenda server
CleanupClosePushL(*agnServer); // guarantees that the server's Close() method gets called

CAgnEntryModel* model = CAgnEntryModel::NewL(); // allocate and construct model
CleanupStack::PushL(model);
model->SetServer(agnServer); // set server pointer for model
model->OpenL(fileName) // Open file using server
// ...Use agenda model API as normal - invokes corresponding server functions
CleanupStack::PopAndDestroy(3); // model, close session with server, agnServer

Note that a separate instance of the RAgendaServ class is required for each agenda file that is open — only one file can be open at any one time in the same server session.

The agenda model has a state which at any time has one of three states (defined by CAgnEntryModel), ENoFile, EBlocked, or EOk. When a model is created using NewL(), it has a state of ENoFile, to indicate that although the object has been constructed it cannot yet access any data as it has not been associated with a file (document).

NewL() takes a single argument, a pointer to a function supplied by the application. This function is called when the model's state moves either to or from the EBlocked state. While the model is being opened its state is EBlocked; as soon as the process of opening the model has completed, its state changes to EOk.

OpenL() may take different parameters depending on whether you are opening an entry model or an instance (or indexed) model.

For the instance and indexed models, OpenL() may take additional parameters which allow the model to be opened either synchronously or asynchronously. The advantage of opening the model asynchronously is that it allows progress information to be displayed in the user interface while the model is being opened — especially useful when opening large agenda documents.

The aProgressCallBack argument is a pointer to a class supplying a function, MAgnProgressCallBack::Progress(), which is called at intervals while the model is being opened and which is passed a percentage value indicating how far the open action has completed. Implementing this requires an active scheduler. One of the application classes, typically the class implementing the user interface view, should be derived from the mixin class MAgnProgressCallBack, and should implement MAgnProgressCallBack::Progress().

To get entries from the model, you have to use a different method depending on whether you are using the instance model or the entry model.

To get entries from the entry model:

• Use an entry iterator (class RAgendaServ).

• Use next the function CAgnEntryModel::FetchEntryL() to get one entry at a time. This function takes one argument, the ID of the entry, which is provided by the entry iterator.

• To get entries from the instance model, use CAgnModel::PopulateDayInstanceListL(), or any of the other Populate…() functions. These return a list of instance IDs that match the criteria given in the arguments to the function.

• Use these IDs to fetch individual instances using CAgnModel::FetchInstanceL() or CAgnModel::FetchInstanceLC(). The arguments passed to the Populate…() functions include a filter (see TAgnFilter), which can be used to limit the types of instances that are retrieved into the list.

To add an entry to the model, use CAgnEntryModel::AddEntryL() (entry model) or CAgnModel::AddEntryL() (instance model).

To update an existing entry, use CAgnEntryModel::UpdateEntryL(). To update an instance, use CAgnModel::UpdateInstanceL().

To delete an entry, use CAgnEntryModel::DeleteEntryL(). To delete an instance use CAgnModel::DeleteInstanceL().