|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-8390D842-B8A3-5042-952D-73240DB30D6B" xml:lang="en"><title>Message |
|
13 Server and Store Overview</title><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <p>This section provides an overview of the functionality and the architecture |
|
15 of Message Server and Store. </p> |
|
16 <section><title>Purpose</title> <p>The following services that are provided |
|
17 by this component can be used by the client application: </p> <ul> |
|
18 <li id="GUID-67C56ED5-6996-585F-A6EB-DB64E3956DF8"><p><xref href="GUID-5CFA3F21-3E42-5B53-8EC1-BC0F7F0E8136.dita">Storing |
|
19 Messages</xref> </p> </li> |
|
20 <li id="GUID-452071CE-E72F-5BE7-AF45-E4EA1C085E18"><p><xref href="GUID-4CD6C5CC-A91B-56BE-825F-5B10B63627DA.dita"> Handling |
|
21 Client Requests</xref> </p> </li> |
|
22 <li id="GUID-F4732AD3-EB59-52E5-B3EF-E8C1D8B527E2"><p><xref href="GUID-2FAB8281-569A-52BE-8BC8-A2D378068706.dita">Caching</xref> </p> </li> |
|
23 <li id="GUID-89ED7AA5-5DBB-5D7D-AE80-739813964183"><p><xref href="GUID-32C1FC8B-F7D2-5275-BDF2-0D662551294C.dita"> Searching |
|
24 and Sorting Messages</xref> </p> </li> |
|
25 </ul> </section> |
|
26 <section><title>Architecture</title> <p>Message type-dependent operations, |
|
27 such as address handling, are called by client applications using client MTMs |
|
28 and UI MTMs. These MTMs then access the appropriate Message Store and alter |
|
29 it as required. </p> <p>The following figure shows the logical structure of |
|
30 the Message Server. Dashed boxes indicate components that can be developed |
|
31 by third-parties. </p> <fig id="GUID-F469ED0A-E43F-5260-B86E-3EFE3CBA0DBB"> |
|
32 <title> Logical structure of Messaging Middleware architecture |
|
33 </title> |
|
34 <image href="GUID-0259868F-8F88-5D9D-A9DE-9309C3BFBA85_d0e281248_href.png" placement="inline"/> |
|
35 </fig><note> No lower-level communication components are shown, as the architecture |
|
36 is designed to be independent of any particular communication protocol. Instead, |
|
37 communication libraries are accessed as needed by Server MTMs. For example, |
|
38 an SMTP MTM would use TCP/IP, while the SMS MTM would use the Telephony Server |
|
39 (ETel).</note> <dl> |
|
40 <dlentry> |
|
41 <dt>Application/App UI</dt> |
|
42 <dd><p>This represents a message client application. </p> </dd> |
|
43 </dlentry> |
|
44 <dlentry> |
|
45 <dt>User Interface MTM, Client-side MTM, UI Data MTM, Server-side MTM Bases</dt> |
|
46 <dd><p>These are base classes required for implementing protocol-specific |
|
47 MTM components. User Interface and UI Data MTMs handle user interface functionality |
|
48 and resources. Client-side MTMs provide message data handling functions. Server-side |
|
49 MTMs provide message transport functions. </p> </dd> |
|
50 </dlentry> |
|
51 <dlentry> |
|
52 <dt>Concrete User Interface MTM, Concrete Client-side MTM, Concrete UI Data |
|
53 MTM, Concrete Server-side MTM</dt> |
|
54 <dd><p>These represent instances of MTM components written to implement a |
|
55 particular messaging protocol. </p> </dd> |
|
56 </dlentry> |
|
57 <dlentry> |
|
58 <dt>Message Server</dt> |
|
59 <dd><p>The Message Server handles all requests to access or manipulate message |
|
60 data. Where necessary, it passes requests to the protocol-specific message |
|
61 transport components, the Server-side MTMs. </p> </dd> |
|
62 </dlentry> |
|
63 <dlentry> |
|
64 <dt>Session</dt> |
|
65 <dd><p>Sessions allow client-side components to issue requests to the Message |
|
66 Server. There are a number of classes provided to clients that allow message |
|
67 entries to be manipulated. </p> </dd> |
|
68 </dlentry> |
|
69 </dl> <p>The <filepath>msgs.dll</filepath> library provides a client-side |
|
70 session class called <xref href="GUID-2DA04D96-F0AD-3FDC-9E36-1C27D889AF4B.dita"><apiname>CMsvSession</apiname></xref> . Client applications |
|
71 typically create an instance of this class on start-up. Instances of Client |
|
72 MTMs, User Interface (UI) MTMs and high-level client library classes maintain |
|
73 a reference to the client application’s session object, to make requests if |
|
74 needed. </p> <p>Message client applications, Client MTMs and UI MTMs manipulate |
|
75 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. |
|
76 The entry currently being operated on is called the context. A client application |
|
77 can begin by setting the context to the root entry. By finding the children |
|
78 of this initial entry, and then their children in turn, any entry can be found. </p> <p>Operations |
|
79 such as creating, deleting, sorting and accessing body text, or changing an |
|
80 index entry, which are independent of the message-type, are requested by client |
|
81 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>. |
|
82 The Message Server may either perform such operations itself or delegate them |
|
83 to a server MTM. </p> </section> |
|
84 <section><title>Description</title> <p>The Message Server is the core component |
|
85 in the Messaging Middleware module. It accepts asynchronous requests from |
|
86 clients through a kernel-maintained session. It performs the following functions: </p> <ul> |
|
87 <li id="GUID-55C60AD4-DCFD-5C31-AA33-1D081FFE2A47"><p> <b>Controls access |
|
88 to message data</b> </p> <p>In response to client requests, the Message Server |
|
89 delegates temporary, exclusive access to message data, so that more than one |
|
90 client cannot edit the same message at the same time. It is the responsibility |
|
91 of Message Server to keep the message data in workable order, and cope with |
|
92 events such as failure recovery. </p> </li> |
|
93 <li id="GUID-BA07A6D4-194D-5908-9139-1A86F0D0C9E3"><p> <b>Delegates requests |
|
94 to Server MTMs</b> </p> <p>Message Server must identify requests, such as |
|
95 sending a message that requires protocol-specific functionality, and load |
|
96 the appropriate Server MTM. </p> </li> |
|
97 </ul> <p id="GUID-8E01ADD0-A706-54B2-8159-E65C33274C30"><b>Message Store</b> </p> <p>Message |
|
98 Server provides persistent storage of messages and messaging account settings |
|
99 by providing a Message Store. The Message Store contains message data in a |
|
100 variable number of entries in a tree view, each of which is referenced by |
|
101 a unique identifier. This concept is known as a <xref href="GUID-D099551B-6E99-5210-B44A-693012A29DD1.dita">dictionary |
|
102 file store</xref>. Each entry in the tree can represent an email account, |
|
103 folder of messages, message part and so on. </p> <p>Message Store is secured |
|
104 in a protected data-caged area of Message Server. Message Server allows multiple |
|
105 read-only and a single read-write access to a message in the Message Store |
|
106 at given time. It also accepts copy and delete requests from clients trusted |
|
107 with <codeph>WriteUserData</codeph> capability. When a copy or delete is requested, |
|
108 the message server first flags itself as unavailable and then locks the files |
|
109 before attempting to process them. </p> <p>Message settings are stored in |
|
110 the Central Repository and attachment information is stored in the Message |
|
111 Store. MTMs can create additional streams in the message store to hold MTM-specific |
|
112 message data. Usually, at least one stream is devoted to non-generic header |
|
113 information such as recipient information. </p> <p>When Message Server starts, |
|
114 the Message Store is created unless there is already a Message Store present. |
|
115 Message Server initially creates the Message Store with just a root entry |
|
116 and then creates standard folders defined in the <filepath>msgs.rsc</filepath> resource |
|
117 file. Finally the Message Server runs <filepath>mailinit.exe</filepath> to |
|
118 customise of the Message Store. The behaviour of <filepath>mailinit.exe</filepath> is |
|
119 defined by the UI family of the device, such as Series 60 or UIQ. However, |
|
120 the typical behaviour is to load each of the UI MTMs and allow each to perform |
|
121 any message type specific initialisation. For example, the SMS plug-in typically |
|
122 creates a default service entry. </p> </section> |
|
123 <section><title>API summary</title> <p>The storage abstractions through which |
|
124 client applications access the various types of storage are key to the Messaging |
|
125 Middleware module. </p> <ul> |
|
126 <li id="GUID-5F7B2622-1FCB-57AB-B98B-32BED95E4CA5"><p>The <xref href="GUID-85BBE389-81F7-3E2F-A789-446D9BE2CC49.dita"><apiname>CMsvEntry</apiname></xref> API |
|
127 access and acts on a particular Message Server entry. The main functions of |
|
128 this API are to provide means to: </p> <ul> |
|
129 <li id="GUID-A14A770E-2425-59C5-BCEC-A8C209B246CE"><p>access the various types |
|
130 of storage associated with an entry </p> </li> |
|
131 <li id="GUID-991A0D61-A67C-5BA0-B943-BFF5D60839B2"><p>discover and access |
|
132 other entries that the entry owns (its children) </p> </li> |
|
133 </ul> </li> |
|
134 <li id="GUID-40BDE827-355F-54E5-BFB3-DEF160FC8B4B"><p> <xref href="GUID-681B56F3-B3A2-3147-B25A-FD69451F4A1D.dita"><apiname>CMsvServerEntry</apiname></xref> is |
|
135 similar to <xref href="GUID-85BBE389-81F7-3E2F-A789-446D9BE2CC49.dita"><apiname>CMsvEntry</apiname></xref>, but used only by Server MTMs. </p> </li> |
|
136 <li id="GUID-54D77E17-1B5E-529F-916B-A628DA022901"><p> <xref href="GUID-5A23B804-2C06-3407-9D48-1BFB212D699F.dita"><apiname>TMsvEntry</apiname></xref> encapsulates |
|
137 an index entry the Message Server index. </p> </li> |
|
138 <li id="GUID-DDF9FB6B-02EB-5976-8072-95FCD25FED49"><p> <xref href="GUID-8CB90FA2-A6CF-3FA2-81FF-7D22EFD9C2CE.dita"><apiname>CMsvStore</apiname></xref> encapsulates |
|
139 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 |
|
140 Store</xref>. </p> </li> |
|
141 <li id="GUID-A17D856C-EE8C-5339-9EE8-108D8AE1229F"><p> <xref href="GUID-4E2B0CEA-1EDA-3452-895D-3CE1B59FD8FD.dita"><apiname>MMsvAttachmentManager</apiname></xref> class |
|
142 is a pure virtual interface class that defines the APIs to be used for attachment |
|
143 management in the Messaging Framework. </p> </li> |
|
144 </ul> </section> |
|
145 <section><title>Typical uses</title> <ul> |
|
146 <li id="GUID-7669F08C-0D4A-5DB1-A965-EC6178B82568"><p>Configuring the Message |
|
147 Server ans Store </p> </li> |
|
148 <li id="GUID-B915A682-265E-58B9-A66A-DE9194685952"><p>Writing MTMs </p> </li> |
|
149 <li id="GUID-3DB37ED4-44D6-56EE-B8C0-D5BFD31567E4"><p>Searching and sorting |
|
150 messages </p> </li> |
|
151 <li id="GUID-7E268EA1-922D-5657-885A-298E29135603"><p>Processing emails in |
|
152 chunks </p> </li> |
|
153 </ul> </section> |
|
154 </conbody><related-links> |
|
155 <link href="GUID-54AB166A-8B24-5065-92AD-5FC1BF3ED89C.dita"><linktext>Messaging |
|
156 Framework</linktext></link> |
|
157 <link href="GUID-44CF5471-564E-5790-935B-51193A4978D6.dita"><linktext>Message Server |
|
158 and Store Concepts</linktext></link> |
|
159 <link href="GUID-DD27A452-8B0F-5C6D-A2E6-FC21145468B6.dita"><linktext>Message Server |
|
160 and Store Tutorials</linktext></link> |
|
161 </related-links></concept> |