<?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_d0e277562_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>
</related-links></concept>