Agenda File overview

The Agenda File API is the interface to the data stored in an agenda file. This data represents diary information, for instance appointments, to-dos and anniversaries.

The API can be used to store, manipulate and retrieve the information held in the file. For example, the information can be filtered to create and populate lists of instances for a day or month, or which belong to a particular to-do list.

Other useful operations which are supported by this API include:

iteration (i.e. go to the next or previous instance)
merging and tidying agenda files — merging means adding the entries and to-do lists contained in one agenda file into another file; tidying means deleting, moving or copying a subset of a file's entries or to-do lists into another file
vCalendar support, so that individual or multiple entries can be converted to and from vEvents or vTodos and written to/read from a stream, converting the text between Unicode and other character sets as necessary
maintaining to-do lists — a to-do list is a list of to-do entries with a name, a unique ID and a sort order. To-do lists are held in an ordered list — one agenda file can contain many to-do lists.

The Agenda File API is closely related to the following APIs: —

All the other Agenda model sub-APIs (Agenda Entry and Instance, Agenda Server Client Side, To-do List and Agenda Model Utilities). The agenda server is used to allow shared access to the agenda file by more than one client. All Agenda File API function calls which access data in an agenda file make an asynchronous request to the server. The use of the agenda server is normally invisible to the user of the Agenda File API.

File Stores. Agenda files are implemented as permanent file stores (see class CPermanentFileStore). These are stores implemented as files in the file system. This implementation is appropriate for agenda files because they are accessed in a similar way to a database — an application only loads the subset of data from the file which it needs to work with. When it has finished with this data, it is written back to the file. This implementation also means that agenda files cannot be embedded.

File Server Client Side. Many functions in the Agenda File API raise a panic if they are called before a file has been opened. You can either create a new file, or open an existing one. When opening an existing file, you must specify the filename; when creating a new file, you must specify a connection to the file server and a filename.

Alarm Server. All types of entry can have an alarm. The next outstanding alarm (or next few outstanding alarms) in an agenda file must be added to the alarm server's alarm queue in order to be handled by the alarm server. The agenda file API provides a class (CAgnAlarm) to do this.

Versit. vEvents and vTodos can be imported into an agenda file and in the process are converted into agenda entries. Conversely, agenda entries can be exported from the agenda file as vEvents and vTodos.

The Agenda File API has the following key concepts: —

The agenda model. The most important classes in the Agenda File API are the model classes. There is a choice of three agenda models — which model is used depends on the type of application:

The entry model (CAgnEntryModel) is the interface to the entries and to-do lists in the file. Repeating entries are represented by a single entry object. The entry model should be used if the application has no user interface, such as a format conversion application.
The indexed model (CAgnIndexedModel) extends the entry model: it adds indexes of the data, which allows the information to be filtered before entries are read. The indexed model can be used for greater efficiency than the instance model by applications which have no user interface and which need to access only a subset of the data in the file.
The instance model (CAgnModel) extends the indexed model: it provides a separate object for each instance of a repeating entry. This makes it most suitable for use by applications that need to show repeating entries in a user interface.

The model's mode. The agenda model can be used in client mode or in normal (non-client) mode. Client mode means that the model is a client of the agenda server. When the model is in normal mode, the server is not used, so that the model data is accessed directly, preventing other applications from accessing it until the file is closed. Applications written for EPOC Release 5 or later should only use the model in client mode. Normal mode has been preserved so that applications written before EPOC Release 5 are compatible.

Change notification. You can set up one or more observers to observe an agenda file. Observers are notified whenever an entry or a to-do list is added, updated or deleted. Before an observer can start receiving notification of changes, it must be registered with the observer controller. The observer controller is owned by the agenda model.

Filtering. Different types of entry filter are provided — general filters and more specialised filters. Filters identify which entry types should be involved when tidying or searching the file or when populating a list of instances or of entry symbols. The filter is usually used in combination with a date or date range.

Progress monitoring. Some operations which affect the whole agenda file can be long running, for example opening, saving, merging and tidying. In order to provide the user with progress information, these operations all take place asynchronously (with the exception that opening the file can take place either synchronously or asynchronously). This means that when the operation is being carried out, the model enters a blocked state (so it is not available for use) and progress information is periodically reported using a progress callback object. This object also reports on how the operation completed.

Agenda File Overview

Purpose

Architectural relationships

Description

See also