<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-8390D842-B8A3-5042-952D-73240DB30D6B" xml:lang="en"><title>Message

Server and Store Overview</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>This section provides an overview of the functionality and the architecture

of Message Server and Store. </p>

<section><title>Purpose</title> <p>The following services that are provided

by this component can be used by the client application: </p> <ul>

<li id="GUID-67C56ED5-6996-585F-A6EB-DB64E3956DF8"><p><xref href="GUID-5CFA3F21-3E42-5B53-8EC1-BC0F7F0E8136.dita">Storing

Messages</xref>  </p> </li>

<li id="GUID-452071CE-E72F-5BE7-AF45-E4EA1C085E18"><p><xref href="GUID-4CD6C5CC-A91B-56BE-825F-5B10B63627DA.dita"> Handling

Client Requests</xref>  </p> </li>

<li id="GUID-F4732AD3-EB59-52E5-B3EF-E8C1D8B527E2"><p><xref href="GUID-2FAB8281-569A-52BE-8BC8-A2D378068706.dita">Caching</xref> </p> </li>

<li id="GUID-89ED7AA5-5DBB-5D7D-AE80-739813964183"><p><xref href="GUID-32C1FC8B-F7D2-5275-BDF2-0D662551294C.dita"> Searching

and Sorting Messages</xref>  </p> </li>

</ul> </section>

<section><title>Architecture</title> <p>Message type-dependent operations,

such as address handling, are called by client applications using client MTMs

and UI MTMs. These MTMs then access the appropriate Message Store and alter

it as required. </p> <p>The following figure shows the logical structure of

the Message Server. Dashed boxes indicate components that can be developed

by third-parties. </p> <fig id="GUID-F469ED0A-E43F-5260-B86E-3EFE3CBA0DBB">

<title>              Logical structure of Messaging Middleware architecture

           </title>

<image href="GUID-0259868F-8F88-5D9D-A9DE-9309C3BFBA85_d0e488704_href.png" placement="inline"/>

</fig><note> No lower-level communication components are shown, as the architecture

is designed to be independent of any particular communication protocol. Instead,

communication libraries are accessed as needed by Server MTMs. For example,

an SMTP MTM would use TCP/IP, while the SMS MTM would use the Telephony Server

(ETel).</note> <dl>

<dlentry>

<dt>Application/App UI</dt>

<dd><p>This represents a message client application. </p> </dd>

</dlentry>

<dlentry>

<dt>User Interface MTM, Client-side MTM, UI Data MTM, Server-side MTM Bases</dt>

<dd><p>These are base classes required for implementing protocol-specific

MTM components. User Interface and UI Data MTMs handle user interface functionality

and resources. Client-side MTMs provide message data handling functions. Server-side

MTMs provide message transport functions. </p> </dd>

</dlentry>

<dlentry>

<dt>Concrete User Interface MTM, Concrete Client-side MTM, Concrete UI Data

MTM, Concrete Server-side MTM</dt>

<dd><p>These represent instances of MTM components written to implement a

particular messaging protocol. </p> </dd>

</dlentry>

<dlentry>

<dt>Message Server</dt>

<dd><p>The Message Server handles all requests to access or manipulate message

data. Where necessary, it passes requests to the protocol-specific message

transport components, the Server-side MTMs. </p> </dd>

</dlentry>

<dlentry>

<dt>Session</dt>

<dd><p>Sessions allow client-side components to issue requests to the Message

Server. There are a number of classes provided to clients that allow message

entries to be manipulated. </p> </dd>

</dlentry>

</dl> <p>The <filepath>msgs.dll</filepath> library provides a client-side

session class called <xref href="GUID-2DA04D96-F0AD-3FDC-9E36-1C27D889AF4B.dita"><apiname>CMsvSession</apiname></xref> . Client applications

typically create an instance of this class on start-up. Instances of Client

MTMs, User Interface (UI) MTMs and high-level client library classes maintain

a reference to the client application’s session object, to make requests if

needed. </p> <p>Message client applications, Client MTMs and UI MTMs manipulate

entries through <xref href="GUID-5A23B804-2C06-3407-9D48-1BFB212D699F.dita"><apiname>TMsvEntry</apiname></xref> and <xref href="GUID-85BBE389-81F7-3E2F-A789-446D9BE2CC49.dita"><apiname>CMsvEntry</apiname></xref> classes.

The entry currently being operated on is called the context. A 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. </p> <p>Operations

such as creating, deleting, sorting and accessing body text, or changing an

index entry, which are independent of the message-type, are requested by client

applications and MTMs through <xref href="GUID-BC3D2A73-3E8C-3D0C-8E18-5E35AA431D99.dita"><apiname>CMvsEntry</apiname></xref> or <xref href="GUID-681B56F3-B3A2-3147-B25A-FD69451F4A1D.dita"><apiname>CMsvServerEntry</apiname></xref>.

The Message Server may either perform such operations itself or delegate them

to a server MTM. </p> </section>

<section><title>Description</title> <p>The Message Server is the core component

in the Messaging Middleware module. It accepts asynchronous requests from

clients through a kernel-maintained session. It performs the following functions: </p> <ul>

<li id="GUID-55C60AD4-DCFD-5C31-AA33-1D081FFE2A47"><p> <b>Controls access

to message data</b>  </p> <p>In response to client requests, the Message Server

delegates temporary, exclusive access to message data, so that more than one

client cannot edit the same message at the same time. It is the responsibility

of Message Server to keep the message data in workable order, and cope with

events such as failure recovery. </p> </li>

<li id="GUID-BA07A6D4-194D-5908-9139-1A86F0D0C9E3"><p> <b>Delegates requests

to Server MTMs</b>  </p> <p>Message Server must identify requests, such as

sending a message that requires protocol-specific functionality, and load

the appropriate Server MTM. </p> </li>

</ul> <p id="GUID-8E01ADD0-A706-54B2-8159-E65C33274C30"><b>Message Store</b> </p> <p>Message

Server provides persistent storage of messages and messaging account settings

by providing a Message Store. The Message Store contains message data in a

variable number of entries in a tree view, each of which is referenced by

a unique identifier. This concept is known as a <xref href="GUID-D099551B-6E99-5210-B44A-693012A29DD1.dita">dictionary

file store</xref>. Each entry in the tree can represent an email account,

folder of messages, message part and so on. </p> <p>Message Store is secured

in a protected data-caged area of Message Server. Message Server allows multiple

read-only and a single read-write access to a message in the Message Store

at given time. It also accepts copy and delete requests from clients trusted

with <codeph>WriteUserData</codeph> capability. When a copy or delete is requested,

the message server first flags itself as unavailable and then locks the files

before attempting to process them. </p> <p>Message settings are stored in

the Central Repository and attachment information is stored in the Message

Store. MTMs can create additional streams in the message store to hold MTM-specific

message data. Usually, at least one stream is devoted to non-generic header

information such as recipient information. </p> <p>When Message Server starts,

the Message Store is created unless there is already a Message Store present.

Message Server initially creates the Message Store with just a root entry

and then creates standard folders defined in the <filepath>msgs.rsc</filepath> resource

file. Finally the Message Server runs <filepath>mailinit.exe</filepath> to

customise of the Message Store. The behaviour of <filepath>mailinit.exe</filepath> is

defined by the UI family of the device, such as Series 60 or UIQ. However,

the typical behaviour is to load each of the UI MTMs and allow each to perform

any message type specific initialisation. For example, the SMS plug-in typically

creates a default service entry. </p> </section>

<section><title>API summary</title> <p>The storage abstractions through which

client applications access the various types of storage are key to the Messaging

Middleware module. </p> <ul>

<li id="GUID-5F7B2622-1FCB-57AB-B98B-32BED95E4CA5"><p>The <xref href="GUID-85BBE389-81F7-3E2F-A789-446D9BE2CC49.dita"><apiname>CMsvEntry</apiname></xref> API

access and acts on a particular Message Server entry. The main functions of

this API are to provide means to: </p> <ul>

<li id="GUID-A14A770E-2425-59C5-BCEC-A8C209B246CE"><p>access the various types

of storage associated with an entry </p> </li>

<li id="GUID-991A0D61-A67C-5BA0-B943-BFF5D60839B2"><p>discover and access

other entries that the entry owns (its children) </p> </li>

</ul> </li>

<li id="GUID-40BDE827-355F-54E5-BFB3-DEF160FC8B4B"><p> <xref href="GUID-681B56F3-B3A2-3147-B25A-FD69451F4A1D.dita"><apiname>CMsvServerEntry</apiname></xref> is

similar to <xref href="GUID-85BBE389-81F7-3E2F-A789-446D9BE2CC49.dita"><apiname>CMsvEntry</apiname></xref>, but used only by Server MTMs. </p> </li>

<li id="GUID-54D77E17-1B5E-529F-916B-A628DA022901"><p> <xref href="GUID-5A23B804-2C06-3407-9D48-1BFB212D699F.dita"><apiname>TMsvEntry</apiname></xref> encapsulates

an index entry the Message Server index. </p> </li>

<li id="GUID-DDF9FB6B-02EB-5976-8072-95FCD25FED49"><p> <xref href="GUID-8CB90FA2-A6CF-3FA2-81FF-7D22EFD9C2CE.dita"><apiname>CMsvStore</apiname></xref> encapsulates

an entry’s <xref href="GUID-8390D842-B8A3-5042-952D-73240DB30D6B.dita#GUID-8390D842-B8A3-5042-952D-73240DB30D6B/GUID-8E01ADD0-A706-54B2-8159-E65C33274C30">Message

Store</xref>. </p> </li>

<li id="GUID-A17D856C-EE8C-5339-9EE8-108D8AE1229F"><p> <xref href="GUID-4E2B0CEA-1EDA-3452-895D-3CE1B59FD8FD.dita"><apiname>MMsvAttachmentManager</apiname></xref> class

is a pure virtual interface class that defines the APIs to be used for attachment

management in the Messaging Framework. </p> </li>

</ul> </section>

<section><title>Typical uses</title> <ul>

<li id="GUID-7669F08C-0D4A-5DB1-A965-EC6178B82568"><p>Configuring the Message

Server ans Store </p> </li>

<li id="GUID-B915A682-265E-58B9-A66A-DE9194685952"><p>Writing MTMs </p> </li>

<li id="GUID-3DB37ED4-44D6-56EE-B8C0-D5BFD31567E4"><p>Searching and sorting

messages </p> </li>

<li id="GUID-7E268EA1-922D-5657-885A-298E29135603"><p>Processing emails in

chunks </p> </li>

</ul> </section>

</conbody><related-links>

<link href="GUID-54AB166A-8B24-5065-92AD-5FC1BF3ED89C.dita"><linktext>Messaging

Framework</linktext></link>

<link href="GUID-44CF5471-564E-5790-935B-51193A4978D6.dita"><linktext>Message Server

and Store Concepts</linktext></link>

<link href="GUID-DD27A452-8B0F-5C6D-A2E6-FC21145468B6.dita"><linktext>Message Server

and Store Tutorials</linktext></link>