EPOC   SDK Home Glossary Indexes Previous Next Up

Message server


Contents


Overview

The Message Server is a standard EPOC server, which accepts asynchronous requests from clients via a kernel-maintained session. It performs two key functions:

The Message Server and any loaded Server-side MTMs exist in the same process space. The design allows clients to access the combined functionality of the Message Server and the Server-side MTMs through a single server interface.


Storage overview

Section Contents

The data for the items in the messaging system—attachments, folders, and message services as well as messages—can be stored in three places:

Some entry types do not usually have associated message stores or binary files: for example, folders, being simple, can be wholly described by an index entry.


Index

As the Message Server is expected to run continuously, it maintains the index in memory. A copy of the index is persisted in the file system, so that it can be restored in the event of a system reset or Message Server failure.

Some fields only apply to particular types of entry (such as messages or services); other fields can be interpreted differently for different entry types.


Message store

A message store contains message data in a variable number of streams, each of which is referenced by a unique identifier. This concept is known in EPOC as a dictionary file store.

By default, every message store has a stream holding a CRichText object, containing the message body text in rich text format. This allows generic message client applications to access body text without knowledge of the message type. The Message Server uses another stream to backup the entry’s index data: MTMs and message client applications should not access this stream.

MTMs can create additional streams in a message store to hold MTM-specific message data. Usually, at least one stream is devoted to non-generic header information, such as recipient information.

The Message Server allows multiple read-only and a single read/write access to a message store at any one time.


Binary files

Any entry can have binary files associated with it. These are stored in a directory, created by the Message Server, that is unique to the entry. The Message Server does not otherwise control the contents of such directories.


Storage abstractions

The abstractions through which applications access the various types of storage are key to the Messaging Architecture. Briefly:


Client requests

According to the EPOC client/server architecture, clients issue requests through handle objects to kernel-maintained sessions. The Messaging Architecture libraries provide a suitable session handle class called CMsvSession. Message client applications typically create an instance of this class upon start-up. Instances of Client-side MTMs, User Interface MTMs, and high-level client library classes maintain a reference to the message client application’s session object, so that they can make requests as needed.

Message client applications, Client-side MTMs and User Interface MTMs manipulate entries through two classes, TMsvEntry and CMsvEntry. The entry currently being operated on is called the context. A message client application can begin by setting the context to the root entry. By finding the children of this initial entry, and then their children in turn, any entry can be found.

Message type-independent operations, which include creation, deletion, sorting, body text access, and index entry changing, are requested by message client applications and MTMs via CMvsEntry or CMsvServerEntry. The Message Server carries out such operations itself.

Message type-dependent operations (such as address handling) are called by message client applications from Client-side and User Interface MTMs. These then access the appropriate message store and alter it as required.


Request handling

The central purpose of the Message Server is to accept and carry out requests from clients, which include message client applications, Client-side MTMs, and User Interface MTMs. Typical requests include changing the structure/contents of the local folders, sending and receiving of messages through different services, changing the contents/structure of remote mailboxes, and MTM-specific requests.

Some asynchronous requests, such as sending a fax, can take considerable time to complete. In order to be responsive, message client applications may well need to change the context (the message entry being operated on by an instance of CMsvEntry) while a request is being processed. To allow this to happen, the request functions return an active object, called an operation object, with base class CMsvOperation, that is then responsible for the request. The CMsvEntry object has no further interest in that request and is free to change context. A client then uses the operation active object in the standard ways, such as waiting for request completion, and cancelling the request. Additionally, the operation class supports a progress function, which returns an MTM-specific progress descriptor, containing, for example, the number of pages that have so far been sent. User Interface MTMs implement a function to display this progress information to the user. Once the client is signalled that the request has completed, it can check the final progress information, before deleting the operation object.

For each request that the Message Server receives, it creates an operation object of its own. This object checks to see if a Server-side MTM is required to carry out the request, and, if so, calls the server-side registry to create it. The operation object then calls the appropriate function on the MTM object, which carries out the request asynchronously. While this is happening, the Message Server may receive further requests requiring the same Server-side MTM. The Message Server queues such requests and passes them to the MTM object consecutively.


Message services

A service is a useful abstraction that collects settings information—usually to set up communication protocols, such as ISP settings—and specific folders for a given single instance of an MTM. What this means in concrete terms, and the implied behaviour, can be quite different in different MTMs. Using ER5’s MTMs as examples,

If a service can contain entries, opening the service from within a message client application should display these entries.

Editing a service should allow the user to change the settings through a suitable dialog. It is up to the MTM to provide a dialog for entering and editing suitable settings, and to store them in a suitable stream. In order that settings can be easily accessed both by server-side and client-side MTM components, the code to store and access settings is normally implemented in a separate library.

Deleting a service removes the service entry, and the settings associated with it. The usual meaning of this is that the user no longer wishes to send or retrieve messages with that service.


Message folders

Folders are used by the Messaging Architecture to hold groups of other entries. Folders can be :


Messages

The storage format of a message can be summarised from the preceding discussion as follows:

Type

Storage

Generic header and message state information

Index entry

MTM-specific header information

MTM-specific stream in an associated message store

Message body

Default rich text object stream in message store. Note that this can be empty if the message body contains no text (for example, a fax composed of image files).

Attachments

Attachments are described in index entries belonging to the relevant message entry. The files themselves are stored in the message’s associated directory.


Structure

Entries can be regarded as being organised in a tree structure. The parent of each entry is recorded in the index entry's details.

The following figure shows how services are placed below a root entry. Folders and messages can be children of the services, and then, in turn, of other folders.

Index structure

The boxes with heavy outlines indicate the services and folders that always exist. The other boxes give example entries.

Validity

The structure means that an index entry must conform to certain rules to be considered valid:

EPOC       SDK Home Glossary Indexes Previous Next Up