--- a/messagingfw/msgtestfw/TestCases/ScriptedTestCases/SendAs/data/HugeTextFile.txt Mon May 03 12:58:18 2010 +0300
+++ b/messagingfw/msgtestfw/TestCases/ScriptedTestCases/SendAs/data/HugeTextFile.txt Fri Jun 25 16:18:56 2010 +0530
@@ -1,1021 +1,3 @@
-
-
-Messaging Symbian OS v7.0s, v8.0, v8.1, v9.0, v9.1 Architectural Description
-
-Status: Issued
-Team/Department : Messaging / Content & Messaging
-
-Contents
-1 INTRODUCTION 6
-1.1 PURPOSE AND SCOPE 6
-2 SUBSYSTEM OVERVIEW AND BACKGROUND 6
-3 MESSAGING ARCHITECTURE AND APIS 7
-3.1 SUBSYSTEM COMPONENTS 7
-3.1.1 Framework components 7
-3.1.1.1 Message Server and MTM architecture 7
-3.1.1.2 Schedule Send 7
-3.1.1.3 SendAs Version 1 7
-3.1.1.4 SendAs Version 2 7
-3.1.1.5 Watcher Framework 8
-3.1.1.6 Message URL Handler 8
-3.1.1.7 Bio Message Framework 8
-3.1.2 Plug-ins 8
-3.1.2.1 SMS 8
-3.1.2.2 CDMA SMS 8
-3.1.2.3 Email 9
-3.1.2.4 OBEX 9
-3.1.2.5 MMS 9
-3.1.2.6 GMXML 10
-3.1.2.7 Bio Message Plug-ins 10
-3.1.2.8 PCMTM 10
-3.1.2.9 Fax 10
-3.2 GENERAL DESCRIPTION 11
-3.2.1 Messaging / Message Server and MTM Architecture APIs 11
-3.2.1.1 Key Internal Relationships and Dependencies 11
-3.2.1.2 Key External Relationships and Dependencies 12
-3.2.1.3 API Purpose - Further Elaboration 13
-3.2.1.3.1 Message Store 13
-3.2.1.3.2 Data File Storage (pre - v9.0) 15
-3.2.1.3.3 Platform Security Compliant Message Store 16
-3.2.1.3.4 How message centres display the message store 17
-3.2.1.3.5 Message Type Module Architecture 19
-3.2.1.3.6 Message Server Client API 21
-3.2.2 Messaging / Send As APIs 22
-3.2.2.1 Key Relationships and Dependencies 22
-3.2.2.2 API Purpose - Further Elaboration 22
-3.2.2.2.1 SendAs API (pre – v9.0) 22
-3.2.3 Platform Security Compliant SendAs Server (v9.0 onwards) 23
-3.2.4 Messaging / Schedule Send APIs 24
-3.2.4.1 Key Relationships and Dependencies 24
-3.2.4.2 API Purpose - Further Elaboration 24
-3.2.4.2.1 Schedule Send 24
-3.2.5 Messaging / Watchers APIs 25
-3.2.5.1 Key Relationships and Dependencies 25
-3.2.5.2 API Purpose - Further Elaboration 25
-3.2.6 Messaging / Message URL Handler APIs 26
-3.2.6.1 Key Relationships and Dependencies 26
-3.2.6.2 API Purpose - Further Elaboration 26
-3.2.6.2.1 Message URL Handler Application 26
-3.2.6.2.2 Message URL Recognisers 27
-3.2.7 Messaging / SMS APIs 27
-3.2.7.1 Key Internal Relationships and Dependencies 27
-3.2.7.2 Key External Relationships and Dependencies 28
-3.2.7.3 API Purpose - Further Elaboration 28
-3.2.7.3.1 SMS Watchers 28
-3.2.7.3.2 SMS Client MTM 29
-3.2.7.3.3 SMS Utilities 29
-3.2.7.3.4 SMS Server MTM 30
-3.2.8 Messaging / CDMA SMS APIs 31
-3.2.8.1 Key Internal Relationships and Dependencies 31
-3.2.8.2 Key External Relationships and Dependencies 32
-3.2.8.3 API Purpose - Further Elaboration 32
-3.2.8.3.1 CDMA SMS Watchers 32
-3.2.8.3.2 CDMA SMS Client MTM 33
-3.2.8.3.3 CDMA SMS Utilities 33
-3.2.8.3.4 CDMA SMS Server MTM 33
-3.2.8.3.5 Configuration for using CDMA SMS MTM 34
-3.2.9 Messaging / Email APIs 35
-3.2.9.1 Key Internal Relationships and Dependencies 35
-3.2.9.2 Key External Relationships and Dependencies 36
-3.2.9.3 API Purpose - Further Elaboration 36
-3.2.9.3.1 Email Overview 36
-3.2.9.3.2 Email Client Utilities 37
-3.2.9.3.3 Email Server MTM Utilities 37
-3.2.9.3.4 POP3 MTMs 37
-3.2.9.3.5 IMAP4 MTMs 38
-3.2.9.3.6 SMTP MTMs 40
-3.2.9.3.7 Autosend 40
-3.2.10 Messaging / MMS APIs 40
-3.2.10.1 Key Internal Relationships and Dependencies 41
-3.2.10.2 API Purpose - Further Elaboration 41
-3.2.10.2.1 MMS Overview 41
-3.2.10.2.2 MMS Utilities 42
-3.2.10.2.3 MMS Watcher 43
-3.2.10.2.4 MMS Client MTM 43
-3.2.10.2.5 MMS Server MTM 44
-3.2.10.2.6 MMS Codec 45
-3.2.11 Messaging / BIO APIs 46
-3.2.11.1 Key Internal Relationships and Dependencies 46
-3.2.11.2 API Purpose - Further Elaboration 47
-3.2.11.2.1 BIO Overview 47
-3.2.11.2.2 BIO MTM 47
-3.2.11.2.3 BIO Database 48
-3.2.11.2.4 BIO Parsers 48
-3.2.11.2.5 BIF Files and Utilities 48
-3.2.11.2.6 Platform Security Compliant Messaging / BIO APIs 49
-3.2.12 Messaging / OBEX MTM APIs 50
-3.2.12.1 Key Internal Relationships and Dependencies 50
-3.2.12.2 OBEX MTM Overview 50
-3.2.12.2.1 OBEX MTM 50
-3.2.12.2.2 IR MTM 51
-3.2.12.2.3 Bluetooth MTM 51
-3.2.12.2.4 OBEX MTM Utils 52
-3.2.12.2.5 Platform Security Compliant Messaging / OBEX MTM APIs 52
-3.2.13 Messaging / GMXML APIs 52
-3.2.13.1 Key Relationships and Dependencies 52
-3.2.13.2 Overview 53
-3.2.13.2.1 GMXML DOM 53
-3.2.13.2.2 GMXML Parser and Composer 53
-3.2.13.2.3 GMXML SMIL DTD (Validator) 53
-4 SECURITY 54
-4.1 DATA CAGING 54
-4.2 BACKUP AND RESTORE 54
-4.3 CAPABILITY RANGES 54
-4.3.1 Capabilities granted to executables 54
-4.3.2 Capabilities granted to DLLs 55
-4.3.3 Capabilities required to use the subsystem 57
-5 FURTHER INFORMATION 59
-5.1 REFERENCES 59
-5.2 OPEN ISSUES 59
-5.3 GLOSSARY 60
-APPENDIX A - EXAMPLE SEQUENCE DIAGRAMS 62
-A.1 COPY TO A REMOTE SERVICE 62
-A.2 SMTP SESSION 64
-A.3 SMTP EMAIL SEND 66
-
-Table of Figures
-Figure 1 Where Messaging Lives 6
-Figure 2 MTM Relationships 11
-Figure 3 External Dependencies 12
-Figure 4 Message Store 13
-Figure 5 Series 60 Inbox List View 14
-Figure 6 Remote and Local Entries 14
-Figure 7 Email Message 15
-Figure 8 Series 60 Message Centre (Composed from 2 screen shots) 17
-Figure 9 UIQ Message Centre 18
-Figure 10 Messaging MTM Structure (light coloured components are part of messaging subsystem) 19
-Figure 11 Nokia 9210 Outbox List View 20
-Figure 12 SendAs Version 1 Dependencies 22
-Figure 13 SendAs Version 2 Dependencies 23
-Figure 14 Schedule Send Dependencies 24
-Figure 15 Watcher Dependencies 25
-Figure 16 Message URL Handler Dependencies 26
-Figure 17 SMS Internal Dependencies 27
-Figure 18 SMS External Dependencies 28
-Figure 19 CMDA SMS Internal Dependencies 31
-Figure 20 CDMA SMS External Dependencies 32
-Figure 19 Email Internal Dependencies 35
-Figure 20 Email External Dependencies 36
-Figure 21 MMS Internal Dependencies 41
-Figure 22 MMS Utilities External Dependencies 42
-Figure 23 MMS Watcher External Dependencies 43
-Figure 24 MMS Client MTM Dependencies 43
-Figure 25 MMS Server MTM Dependencies 44
-Figure 26 BIO Message Internal Dependencies 46
-Figure 27 Bio Parser External Dependencies 47
-Figure 26 BIO Message Dependencies (v9.0) 49
-Figure 28 OBEX Internal Dependencies 50
-Figure 29 OBEX External Dependencies 51
-Figure 30 IR MTM Dependencies 51
-Figure 31 Bluetooth MTM Dependencies 52
-Figure 32 GMXML Dependencies 52
-Figure 33 Sequence Diagram Showing Copying to a Remote Service 62
-Figure 34 Sequence Diagram Showing a SMTP Session 64
-Figure 35 Sequence Diagram Showing SMTP Transactions during Email Send. 66
-1 Introduction
-1.1 Purpose and Scope
-The Messaging Architectural Description details the architecture and APIs exposed by the Messaging Subsystem. This document does not attempt to list all functionality provided by the messaging subsystem. For details on the functionality provided and the specifications implemented by the messaging subsystem see the Messaging Functional Description [R1]. This document describes the general architecture of messaging subsystem. Information related to a particular release version is mentioned with relevant release number.
-2 Subsystem Overview and Background
-The Messaging Subsystem provides an application level API to handle the storage and transport of different message types. It sits between messaging applications and the lower level subsystems which messaging uses for storage and transmission of messages.
-
-Figure 1 Where Messaging Lives
-The message types that messaging currently supports are Email (POP3, IMAP4 & SMTP), SMS, MMS and OBEX. The set of supported message types is extensible at run time by the use of plug-in modules that are responsible for the transmission and storage of a particular message type. This means that the set of components shown communicating with the network cloud depend on the message types installed.
-3 Messaging Architecture and APIs
-3.1 Subsystem components
-The Messaging subsystem components can be split into two categories: those components that form the framework and those that plug into the framework to support specific message types. This section briefly describes each of the components, more detailed descriptions of the components and their dependencies can be found in later sections of this document.
-3.1.1 Framework components
-3.1.1.1 Message Server and MTM architecture
-The message server is the core component in the messaging subsystem. It provides the message store used to contain messages. The Message Type Module architecture also allows plug-ins to add support for new message types to the messaging subsystem.
-Component Description
-messaging\framework\serverexe Executable that links to the server component and starts the message server
-messaging\framework\server Contains classes that make up both the client and server side of the message server API.
-messaging\framework\mtmbase Base classes for the plug-ins that handle the various message types
-3.1.1.2 Schedule Send
-The Schedule Send component is an extension to the framework that provides support for scheduling of operations such as sending messages. Message type modules that wish to support this functionality can use these support components to implement scheduling. For example the SMS MTM uses this to allow scheduled sending of SMS messages.
-Component Description
-messaging\schedulesend\schedulesendmtm Base classes that handle functionality for message server plug-ins that wish to enable scheduling of sending messages.
-messaging\schedulesend\schedulesendexe Executable use to provide schedule send behaviour.
-3.1.1.3 SendAs Version 1
-This version of SendAs is supported in releases pre - v9.0. SendAs provides a high level API for applications that wish to include a “Send As” menu to allow users to send content via one of the message types supported by messaging. The application using the API does not have to be aware of the message type selected by the user. Note the API does not send the messages.
-Component Description
-messaging\sendas High level API to allow creation of messages.
-3.1.1.4 SendAs Version 2
-From v9.0 and onwards the SendAs has been replaced with client server architecture based SendAs server. The client server architecture enhances secured platform implementation. The SendAs server polices the client application. If it is not trusted with required capabilities the SendAs server will refuse the client access. The client MTM for the message type can send a message with user permission even if the client does not have the correct capabilities.
-Component Description
-messaging\sendAsV2 High level API to allow the creation and sending of messages
-
-3.1.1.5 Watcher Framework
-The watcher framework is a lightweight framework to allow plug-ins to wait on events. For example there is an SMS watcher that waits for incoming SMS messages and delivers them to the message store. The watcher framework will only load plug-ins from ROM.
-Component Description
-messaging\framework\watcher Executable that loads and runs watcher plug-ins.
-3.1.1.6 Message URL Handler
-Support for recognising messaging URLs (mailto:, sms:, fax:, mms:), and then launching an editor with a new message.
-Component Description
-messaging\urlhandler\urlhandler An application that parses the URLs and then creates a correctly addressed message and launches a message editor.
-messaging\urlhandler\recogniser Recognisers that map from the URL schemes to the mime types.
-3.1.1.7 Bio Message Framework
-The Bio Message Framework provides a framework that supports plug-ins to handle messages like vCards and Internet access point set-up messages.
-Component Description
-messaging\biomsg\BDB\BIODB Classes to maintain the database of bio registration files.
-messaging\biomsg\BIFU\BIFU Classes for reading and writing bio registration files
-messaging\biomsg\BIOC\BIOC Bio message client MTM, this is in the framework section as it forms part of the bio messaging framework it is also a plug-in to the messaging framework.
-messaging\biomsg\BIOS\BIOS Bio message server MTM, this is in the framework section as it forms part of the bio messaging framework it is also a plug-in to the messaging framework.
-3.1.2 Plug-ins
-3.1.2.1 SMS
-The SMS plug-ins provide application level support for the Short Message Service messages.
-Component Description
-messaging\biomsg\BioWatchers Plug-ins to the watcher framework to listen for SMS, WSP, and WDP messages and deliver them to the global inbox in the message store.
-messaging\sms\clientmtm A plug-in to the message server framework to provide a generic API for creation of SMS messages (SMS Client MTM & SMS utilities)
-messaging\sms\servermtm A plug-in to the message server framework to provide a generic API for sending of SMS messages (SMS Server MTM)
-3.1.2.2 CDMA SMS
-The CDMA SMS plug-ins provide application level support for the CDMA Short Message Service messages.
-Component Description
-messaging\biomsg\BioWatchersCdma Plug-ins to the watcher framework to listen for CDMA SMS messages and deliver them to the global inbox in the message store.
-messaging\sms\multimode\clientmtm A plug-in to the message server framework to provide a generic API for creation of CDMA SMS messages (CDMA SMS Client MTM)
-messaging\sms\multimode\servermtm A plug-in to the message server framework to provide a generic API for sending of CDMA SMS messages (CDMA SMS Server MTM)
-
-3.1.2.3 Email
-The email plug-ins provide support the POP3, IMAP4 and SMTP email protocols and support for parsing and generating plain test, MIME and M-HTML format email messages.
-Component Description
-messaging\email\clientmtms A plug-in to the message server framework to provide a generic API for creation of email messages (IMAP4 SMTP and POP3 Client MTMs & email utilities)
-messaging\email\imapservermtm A plug-in to the message server framework to provide a generic API for access to a remote IMAP4 server (IMAP4 Server MTM)
-messaging\email\smtpservermtm A plug-in to the message server framework to provide a generic API for access to a remote SMTP server (SMTP Server MTM)
-messaging\email\popservermtm A plug-in to the message server framework to provide generic API for access to remote POP3 server (POP3 Server MTM)
-messaging\email\servermtmutils Email utilities for parsing plain text and MIME email messages. It also provides an abstraction of the TCP/IP sockets for use by the SMTP POP3 and IMAP4 plug-ins.
-messaging\email\autosend An executable that requests SMTP Server MTM to send messages in the outbox. This is used to provide send on next connection functionality and is started by the POP3 and IMAP4 Client MTMs.
-3.1.2.4 OBEX
-The OBEX MTM is a set of plug-ins to the message server that provides support for IR and Bluetooth beaming.
-Component Description
-messaging\obex\btmtm\btclient\group\btcmtm Bluetooth Client MTM
-messaging\obex\btmtm\btserver\group\btsmtm Bluetooth Server MTM
-messaging\obex\irmtm\irclient\group\ircmtm IR Client MTM
-messaging\obex\irmtm\irserver\group\IRSMTM IR Server MTM
-messaging\obex\obexmtm\obexclient\group\obexClientMtm OBEX Client MTM, base classes for the Bluetooth and IR Client MTMs
-messaging\obex\obexmtm\obexserver\group\obexServerMtm OBEX Server MTM, base classes for the Bluetooth and IR Server MTMs
-messaging\obex\obexmtm\obexutil\group\obexMtmUtil OBEX MTM utilities
-3.1.2.5 MMS
-The MMS MTM is a plug-in to the message server that provides support for MMS messages. From v9.0 and onwards MMS MTM and related components are removed.
-Component Description
-messaging\mms\utils MMS Utilities
-messaging\mms\servermtm MMS Server MTM
-messaging\mms\mmswatcherplugins MMS plug-ins to WAP push framework to handle reception of MMS notifications
-messaging\mms\codec MMS utilities for handling MMS codecs
-messaging\mms\clientmtm MMS Client MTM
-3.1.2.6 GMXML
-GMXML is a parser/generator for SMIL presentations for MMS messages.
-Component Description
-messaging\GMXML\XMLParser XML parser designed for parsing of SMIL messages
-messaging\GMXML\XMLDom XML document object model designed for parsing of SMIL messages
-messaging\GMXML\SMILdtd SMIL DTD
-3.1.2.7 Bio Message Plug-ins
-These parsers plug into the bio messaging framework to handle specific types of bio message.
-Component Description
-messaging\biomsg\cbcp\CBCP Compact business card parser
-messaging\biomsg\enp\ENP Email notification parser
-messaging\biomsg\gfp\gfp General file parser
-messaging\biomsg\iacp\IACP Nokia Smart Message Internet Access Parser
-messaging\biomsg\wapp\wapp Nokia/Ericsson OTA Parser
-3.1.2.8 PCMTM
-Plug-in to the message server that provided email synchronisation with a PC. This component has been deprecated in 8.0a and will not been documented in the API section below.
-3.1.2.9 Fax
-Plug-in to the message server that provides fax support. This component has been deprecated in 8.0a and will not been documented in the API section below.
-
-3.2 General Description
-3.2.1 Messaging / Message Server and MTM Architecture APIs
-3.2.1.1 Key Internal Relationships and Dependencies
-
-Figure 2 MTM Relationships
-Figure 2 shows the relationship between the Message Server and the MTM plug-ins. The grey classes are realisations of the MTM interfaces defined by the messaging framework. The message server depends on the Server MTM interface. Messaging Clients depend on the Client, UI and UI Data MTM interfaces and the Message Server Client API.
-3.2.1.2 Key External Relationships and Dependencies
-
-Figure 3 External Dependencies
-The grey package representing the messaging client depends on the Client, UI and UI Data interfaces and the Messaging Client API. The message server then depends on:
-• Charconv – Provides character set conversion routines, used to convert encoded message body text to Unicode body text.
-• EStore – Provides API to handle a stream based store used for the messaging index file and the framework classes for the message store files. (omitted from other dependency diagrams as it is implied by the dependency on the message server)
-• F32 – Provides the file server APIs used to access the file system directories in which messaging stores files containing message data. (omitted from other dependency diagrams)
-• BAFL – Provides API to load the correct messaging resource file dependent on the current language and to register the message store index file with the backup server. (omitted from other dependency diagrams)
-• ETEXT – Rich text APIs used to store body text of messages, this rich text format is a Symbian Proprietary format. (omitted from other dependency diagrams)
-• EUSER – Core Symbian OS utilities such as descriptors, arrays, client / server framework, cleanup stack and others (omitted from this and other dependency diagrams).
-• Central Repository – Centralised and secure storage facility for application settings, the message server stores message settings data in the central repository (from v9.0 and onwards).
-Note that debug only dependencies such as the flogger have been omitted from dependency diagrams.
-3.2.1.3 API Purpose - Further Elaboration
-3.2.1.3.1 Message Store
-The message server provides persistent storage of messages and messaging account settings. It does this by providing a message store consisting of a tree of message entries. Multiple clients can access the message store simultaneously. Each entry in the tree can represent an email account, folder of messages, message part, etc.
-
-Figure 4 Message Store
-Figure 4 shows an example message store. The tree is broken down in to three levels:
-1. The Root entry. This entry is just present to tie the tree structure together
-2. Service entries. There is one local service under which local folders and messages are stored, and zero or more remote services. Remote services represent message accounts.
-3. Message & Folder entries. Messages and folders, under the local service represent messages stored on the device. Messages and folders under remote services represent a local copy of messages that are present on a remote server. For example under a POP3 email service you would have copies of all the messages present on the POP3 email server, or under an SMS service you might find SMS messages that are stored on a SIM.
-The message server controls access to the entries in the store. It enforces the three levels therefore attempts to create message or folder entries directly under the root entry will fail.
-The message server provides three types of storage for each entry in the message store:
-• Index entry - TMsvEntry - intended to provide enough information for UI to display list views as shown in Figure 5. This consists of two strings and various flags (read, complete, has attachments etc).
-• Stream based file store - CMsvStore – provides storage of streams of data associated with UIDs. A standard UID is defined for storing body text. Other UIDs are specific. For example the email MTMs define a UID for storage of MIME headers. Compared to the index entry information this is used to store larger objects and is extensible, at the cost of being slower to access. From v9.0 and onwards CMsvStore provides an Attachment API for managing attachments. The Attachment API should be used as attachments can no longer be accessed directly due to Platform Security.
-• Directory of files – normally used for attachments.
-The only storage type that is always present is the index entry. The stream store and the directory of files are optional.
-
-Figure 5 Series 60 Inbox List View
-
-Figure 6 Remote and Local Entries
-As shown in Figure 6 the message store is split into two sets of entries:
-• Remote entries - entries that are representations of entries stored on a remote store .
-• Local entries - entries not linked to a remote store.
-The message server handles changes to local entries; internally it hands off changes to remote entries to the Server MTM that owns that service. Examples of operations that are handed off to Server MTMs are operations involving copying and moving messages to and from a remote service. See section 3.2.1.3.5 or more information on Server MTMs.
-Each entry within the store has a type:
-Folder – Messages can be grouped into folders. Standard folders such as inbox / outbox and user created folders.
-Message – Storage of the content of a message. Message entries can have child entries used to represent the structure of a message.
-Attachment – These represent attachments under a message entry.
-Root & Local Service Entry – There tie the tree structure together. However the Stream store associated with the root entry is sometimes used by UIs to store preferences e.g. default folder views etc.
-Remote Service - Represents a source and / or destination for messages. They are used to store the settings associated with the source / destination.
-Message Type Specific - MTMs can create other message types for use as child entries to messages they own. For example email uses a tree structure, with a message entry as the root, to represent the MIME structure of an email message; it uses folder entries to represent MIME folders and adds new types for entries representing the html body and text body parts of a message. This is shown in Figure 7.
-
-Figure 7 Email Message
-Using the message store to represent message structure allows reuse of the tree structure and makes it very simple to represent one message embedded in another. However this representation introduces performance issues as it results in each message having multiple files associated with it. The message server also keeps all index entries in memory; therefore this representation increases the memory footprint of the message server. Therefore when designing new MTMs we should think about moving away using multiple index entries to store one message in the message store.
-A default message store is created if the message server starts and no message store is present or a corrupt message store is present. The server will initially create a store with just a root entry, and then the server will create any standard folders defined in the resource file msgs.rsc. Finally the server will check whether an executable ‘mailinit.exe’ is present on the system, if it is present the server will launch the executable to allow customisation of the message store. The behaviour of ‘mailinit.exe’ is defined by the UI family of the device. However the typical behaviour is to load each of the UI Message Type Modules and allow each to perform any message type specific initialisation. For example the SMS plug-in typically creates a default service entry.
-
-3.2.1.3.2 Data File Storage (pre - v9.0)
-This section describes the files used by the message server before release v9.0. For information on the files used for release from v9.0 and onwards see section [3.2.1.3.3.1].
-Filename Access Purpose
-?:\system\Mail\index Private Message server index file, internal to message server
-?:\system\Mail\<8 hex digits> Shared via API Message server store files for services, clients access these via a messaging API.
-?:\system\Mail\<8 hex digits>.new Shared via API Temporary file used during committing message server store files.
-?:\SYSTEM\MAIL\<8 HEX DIGITS>_F\* Shared Files associated with a messaging service. These may be accessed directly by clients.
-?:\system\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits> Shared via API Message server store files for message entries, clients access these via a messaging API.
-?:\system\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits>.new Shared via API Temporary file used whilst committing message server store files.
-?:\system\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits>_F\* Shared Files associated with a message entry. These are accessed directly by clients.
-c:\system\data\msgs.ini Private Stores the drive containing the last used message store
-c:\system\Mtm\Mtm Registry v2 Private Cache of registered MTMs, internal to message server
-C:\system\data\sms_settings.dat Shared Copy of the SMS settings.
-?:\System\Mail\StoreInit.tmp Shared Created when message server runs ‘mailinit.exe’, ‘mailinit.exe’ should delete the file when it has successfully completed.
-?:\System\Mail\storedeleted.tmp Shared Created when message server finds and deletes a corrupt message store. Allows the UI to inform the user about the fact that the message store was corrupt.
-Files that are shown as private should only be accessed by the message server or by connectivity process for backup and restore purposes. Files listed as shared are accessed directly by messaging clients. Files listed as shared via API are accessed by client process but only via messaging APIs.
-3.2.1.3.3 Platform Security Compliant Message Store
-From v9.0 and onwards the message store is stored in the message server's data cage and the settings data are placed in the Central Repository. Access to the message store is only possible via message server APIs and not directly through file access. This leads to secured data storage and secured platform.
-3.2.1.3.3.1 Data caging
-Filename Purpose
-?:\private\<SID>\Mail\index Message server index file, internal to message server
-?:\ private\<SID>\Mail\<8 hex digits> Message server store files for services, clients access these via a messaging API.
-?:\ private\<SID>\Mail\<8 hex digits>.new Temporary file used during committing message server store files.
-?:\ private\<SID>\Mail\<8 hex digits>_F\* Files associated with a messaging service. These may be accessed directly by clients.
-?:\ private\<SID>\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits> Message server store files for message entries, clients access these via a messaging API.
-?:\ private\<SID>\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits>.new Temporary file used whilst committing message server store files.
-?:\ private\<SID>\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits>_F\* Files associated with a message entry. These are accessed directly by clients.
-c:\ private\<SID>\data\msgs.ini Stores the drive containing the last used message store
-c:\ private\<SID>\Mtm\Mtm Registry v2 Cache of registered MTMs, internal to message server
-?:\ private\<SID>\Mail\StoreInit.tmp Access via IPC call
-?:\ private\<SID>\Mail\storedeleted.tmp Created when message server finds and deletes a corrupt message store. Allows the UI to inform the user about the fact that the message store was corrupt.
-?\resource\messaging\bif\*.bif Registration data field with UID used in BIO framework
-
-3.2.1.3.4 How message centres display the message store
-The UI normally provides a Message Centre application to display the structure of the message store to the user. Different UIs map the structure to different views.
-
-Figure 8 Series 60 Message Centre (Composed from 2 screen shots)
-Figure 8 shows the top level view of the message centre application on a Series 60 phone. This shows that the message centre has hidden the local service and shows the standard folders at the same level as the services. Also the SMTP, SMS and MMS services are marked as hidden entries in the message store, and so do not appear in the message application.
-
-Figure 9 UIQ Message Centre
-However Figure 9 shows that the UIQ message centre has no 1-1 mapping from the structure in the message store to the structure shown to the user. Each of the message types is displayed as if its messages were contained in separate folders. Under each of these folders the user is presented with an inbox, outbox, send and drafts folder. This filtering is done in the UI layer as this functionality is not provided by the messaging API.
-3.2.1.3.5 Message Type Module Architecture
-
-Figure 10 Messaging MTM Structure (light coloured components are part of messaging subsystem)
-The MTM architecture is the plug-in scheme provided by the messaging framework to integrate different message transports into the message server. The plug-in scheme consists of four interfaces, the UI MTM, UI Data MTM, Client MTM and Server MTM. The messaging client applications loads and uses the first three which are loaded within the client’s process space. The final one the Server MTM is loaded within the message server process. The APIs for the client facing interfaces are extensible via run time type information provided by the QueryCapability API, and the InvokeAsyncFunction and InvokeSyncFunction APIs.
-3.2.1.3.5.1 UI MTM
-Handles requests from clients to view and edit messages or service settings. The MTM handles interaction with the message centre and as such the exact meaning of the APIs is defined by the UI. However common meanings are:
-• Create – Launches the editor with a new message.
-• Edit – If entry is a message this launches the editor; if entry is a service it edits the settings.
-• View – Launches the message viewer.
-• Display progress of an operation.
-3.2.1.3.5.2 UI data MTM
-This MTM provides fast access to UI components such as menu resources and bitmaps required by message centre for list views etc. Again the exact semantics are UI specific.
-There is a resource file defining UI specific functions, for example the Series 60 Messaging UI checks if the resource file contains text to display in the “New Message” menu.
-The UI data MTM also provides mapping from the message store’s TMsvEntry structure to Icons for the messaging list views and a status string, for example in the case of Nokia 9210 it is used in the outbox view to provide strings like “Resend 01:07” as shown in Figure 11. The class also provides functions to determine what operations are possible with a given entry. Examples of this are APIs that return whether the UI should allow the user to reply to the entry or to delete a service entry. The UI then uses this information to determine which menu options / short-cut keys should be allowed when the user selects a given entry.
-
-Figure 11 Nokia 9210 Outbox List View
-3.2.1.3.5.3 Client MTM
-Provides methods to create / reply and forward messages. Functions the Client MTMs provide are:
-• Create Message.
-• Reply to a Message.
-• Forward a Message.
-• Add / remove Addressees.
-• Add / remove body text.
-• Add / remove subject.
-• Add / remove attachments (the API cannot list attachments).
-The Client MTM interface is used by SendAs to provide a way of creating messages independently of the message type.
-3.2.1.3.5.4 Server MTM
-This is the final interface that makes up an MTM plug-in; it differs from the other three plug-ins in that it is loaded into the message server’s process space. The Server MTM provides access to messages under remote services. It handles connecting to remote servers to handle updating the local cache of these messages or to send messages copied to remote services when messages are copied to a remote service. The message server loads and hands off all message store operations that involve entries under a remote entry, these are the entries on the left-hand side of Figure 6.
-Functions that a Server MTM must implement:
-• Copy/MoveToLocal – called when the message server is asked to move or copy an entry that is currently under a remote service. A Server MTM might map this to retrieving a message from a remote mailbox.
-• Copy/MoveFromLocal – called when the message server is asked to move or copy from under the local service to a destination under a remote service. A Server MTM should map this to sending a message if the MTM supports sending.
-• Create, Delete, Change – called when the message server is asked to perform these operations on entries under a remote service.
-• StartCommand – this API provides a means of extending the API the Server MTM provides. Messaging clients pass a command ID and a selection of entries via the message server to the Server MTM. Examples of commands that Server MTMs might provide are: connect and synchronise the entries under a remote service with the messages on an email server, list SMS messages present on the phones SIM. These commands are MTM specific and therefore clients have to know which MTMs support which commands.
-3.2.1.3.5.5 MTM Registration
-MTMs must be registered with the message server so that clients can query what MTMs are present and the server knows which DLL to load to create a given MTM component. MTMs are registered by providing a resource file containing the MTMs UIDs, human readable name, and for each MTM interface it lists a DLL and the ordinal at which the constructor for that interface exists. The message server will search the ROM drive for MTM registration resource files on start-up and it will automatically register any MTMs found. For registration of MTMs installed on other drives, the message server provides an API to register and de-register an MTM. Registration will persist across a reboot, so an MTM only needs to be registered when it is installed on the system.
-When MTMs are registered or unregistered the message server will send events to all messaging clients with a message server session open.
-3.2.1.3.6 Message Server Client API
-The Messaging Server Client API breaks down into two categories: APIs for manipulation of the message store and utility APIs.
-3.2.1.3.6.1 Message Store manipulation APIs
-Requests from clients to modify the message store fall into three categories:
-1. Operations performed entirely with local entries (entries on the right-hand side of Figure 6) for example requests to create entries in the inbox, delete an entry from the drafts folder etc. The message server handles these operations directly.
-2. Operations that involve a remote entry (entries on the left-hand side of Figure 6) for example requests to delete an entry under a POP3 service, or copy a message to an SMTP service. The message server hands these operations off to the Server MTM that owns the service under which the remote entry is stored. The only exception to this rule is the ChangeAttributes API call. This modifies flags on an index entry and is handled by the message server for both local and remote entries. This means that a Server MTM can not rely on being called when flags like the Unread flag are changed. Note that operations can not involve two remote entries; therefore requests to copy entries between a remote service representing one POP3 account to a remote service representing another POP3 account will fail with an error.
-3. Requests that are explicitly directed at a Server MTM via the TransferCommand API. These commands are just passed to the correct Server MTM by looking up the Service ID and MTM of the first message in the selection passed into the command.
-The message server sends events when entries in the message store are modified to messaging clients that have a session open with the server.
-Where the API provides asynchronous functions to modify the message store or transfer a command to a Server MTM, the functions will return a message server operation object. This object can be used to request progress on operation or cancel the operation. Deleting the operation object returned, or closing the session used to make the request will result in the operation being cancelled, therefore a messaging client must remain running until operations it has requested have either completed or they will be cancelled. See appendix A.1 for an example of an asynchronous copy operation. If a Server MTM operating on the same remote service is already handling an operation, the message server will queue the new operation to be handled when the Server MTM becomes free. Requests for progress of operations that are queued will fail with KErrNotReady. The fact that the queue is based on the remote service ID means that you can have two Server MTMs of the same type running at the same time as long as they are operating on different services. So for example you can have two separate POP3 MTMs running synchronising different remote services with email servers.
-3.2.1.3.6.2 Utility APIs
-1. Access to MTM registries – These allow clients to construct instances of the interfaces an MTM implements.
-2. Register / Unregister an MTM.
-3. Change Drive – The message server closes the current message store and opens one on the drive specified. If no message store is present on the drive specified a new message store is created. The message sever can have only one mail store open at a time, if the current mail store is not available because a the disk the mail store is on is not present then the message server will switch the mail store back to the C: drive if an attempt is made to create a message in the inbox.
-4. Launching Editors – This launches the correct editor for a message. It is implemented by delegating the request to the UI MTM
-3.2.2 Messaging / Send As APIs
-3.2.2.1 Key Relationships and Dependencies
-
-Figure 12 SendAs Version 1 Dependencies
-SendAs version 1 and only present in releases before v9.0. SendAs uses the Messaging Client API to access the registry of Client MTMs and construct the Client MTM interfaces. The Client MTMs are then used for composing the message. SendAs requires clients to implement the MSendAsObserver interface. This interface is responsible for checking the return value of the capability queries made to Client MTMs that require a response and also for rendering message types that require it. The only message type supplied by Symbian that requires rendering is Fax, however this MTM has been removed in 8.0a and future releases.
-3.2.2.2 API Purpose - Further Elaboration
-3.2.2.2.1 SendAs API (pre – v9.0)
-The SendAs API makes use of the Client MTM interface and the Messaging Client API to provide a generic API for creating messages. Note despite the name of this component SendAs does not provide an API to send the message.
-SendAs builds a list of registered MTMs, then queries each MTM to check whether it supports sending, removing those MTMs from the list that do not support sending. This list is then provided to the messaging client application. At this point the application can add more constraints on the list of MTMs; for example it can insist the MTM supports Attachments or more than a certain size of body text. SendAs queries each of the MTMs about the requirements and will drop any MTMs from the list that does not meet them. When the application has finished adding requirements it selects one of the MTMs left in the list and uses that to compose the message, adding addresses, a subject, body text and attachments.
-SendAs supports setting a BIO Type for the message that is composed. This tells the transport that the body text represents a BIO Message. This is used when sending business cards from the contacts application as SMS messages; the contacts application puts the vCard data in the body text of the message and the transport sends it correctly. If the MTM in question supports attachments then the vCard is attached to the message.
-A new CSendAs object must be created for each message the application wishes to create.
-3.2.3 Platform Security Compliant SendAs Server (v9.0 onwards)
-
-Figure 13 SendAs Version 2 Dependencies
-From v9.0 and onwards the CSendAs has been replaced by the SendAs server component. The new SendAs server controls the access to the message store. Some of the key SendAs Server features are listed as follows.
-• Send a message once the capability policing of the client application has been completed.
-• Allow client applications to launch an editor for a specified message type.
-• Allow client applications to query the message type.
-The main client-side API is the RSendAs class. The client applications use this to connect to the Send-As server. The session object on the server-side is an instance of CSendAsSession.
-Client applications create messages using the RSendAsMessage API. Opening an RSendAsMessage object on Send-As server session creates a CSendAsMessage object in the Send-As server. There is a one-to-one mapping between an RSendAsMessage object and a CSendAsMessage object. This allows client applications to create multiple messages concurrently.
-
-3.2.4 Messaging / Schedule Send APIs
-3.2.4.1 Key Relationships and Dependencies
-
-Figure 14 Schedule Send Dependencies
-The Schedule Send Server MTM base class depends on the task scheduler to launch the schedule send executable at the correct time. To send the message with a package of data previously passed into the task scheduler by the Server MTM. The schedule send executable then uses the Messaging Client API to actually perform the requested operation.
-3.2.4.2 API Purpose - Further Elaboration
-3.2.4.2.1 Schedule Send
-The Schedule Send functionality is delivered by four components:
-Server MTM Base Class – The base class provides support to Server MTMs that wish to support scheduled operations.
-Data Structures – These are classes used to represent the data associated with a scheduled operation.
-Executable – The executable is run by the task scheduler at the scheduled time.
-The Task Scheduler – This component is part of the system libraries subsystem. Currently the SMS and Fax Server MTMs support scheduled sending.
-Clients request the Server MTM schedules operations via additional commands passed to TransferCommand API; this is passed to the Server MTM via the message server. The Server MTM packages the operation ID, a selection of message IDs, how often to poll for progress and an MTM specific buffer. It then passes this package of data to the task scheduler requesting that it launches the schedule send executable at the correct time with the packaged information.
-When the task scheduler launches the schedule send executable, it unpacks the schedule information and uses the Messaging Client API to request the Server MTM to perform the operation.
-Schedule Send supports a retry mechanism if the operation fails. The Server MTM has a resource file containing a mapping from the error codes the operation can fail with and actions to be performed. For example the SMS resource file has a mapping such that if the operation fails with an error code indicating a bad phone number the SMS will be set to failed and left in the outbox. Whereas if it fails with a error code indicating temporary network failure the send operation will be scheduled to be resent later with a maximum of three retries.
-3.2.5 Messaging / Watchers APIs
-3.2.5.1 Key Relationships and Dependencies
-
-Figure 15 Watcher Dependencies
-The watcher executable’s dependency on the message server is the result of a performance measure. The watcher process creates a message server session before initialising each of the watcher plug-ins and closes the session when it has finished. This keeps the message server running during initialisation avoiding starting and stopping the message server if each watcher plug-in opens and closes sessions.
-3.2.5.2 API Purpose - Further Elaboration
-The watcher framework consists of an executable that is launched when the device boots. The component that is responsible for launching it depends on the UI family. When the watcher.exe is launched it will load each DLL in z:\system\libs\watchers which has a second UID as KWatcherUid and calls the first DLL entry point to construct a CActive object.
-From v9.0 and onwards watcher DLLs are found by scanning the directory \resource\messaging\watchers for registry files. These files contain the name of a watcher DLL that can be loaded from ROM i.e. z:\sys\bin.
-The framework has retry behaviour if the first entry point leaves, in this case the watcher framework will start a timer and try and construct the watcher object 10 seconds later. Five attempts are made before the watcher plug-in is assumed to have failed completely. Once the watcher framework has constructed all the watchers it starts the active scheduler which should never exit.
-Watcher plug-ins typically make a request to another subsystem such that they will be completed when an external event like a fax line ringing or an SMS being received occurs. When the watcher has completed processing the request it will wait for the next event.
-No support for starting / stopping watchers is provided. This is a limitation that makes watchers unsuitable for operations like listening for messages beamed via IR, as the watcher should only run while the IR port is active.
-3.2.6 Messaging / Message URL Handler APIs
-3.2.6.1 Key Relationships and Dependencies
-
-Figure 16 Message URL Handler Dependencies
-3.2.6.2 API Purpose - Further Elaboration
-The Message URL Handler provides support for creating messages and launching messaging editors from URLs such as mailto:infobot@example.com?subject=current-issue. Note there is no dependency between the Message URL Handler application which processes the URLs and the Message URL Handler recognisers which maps from URLs to mime types.
-3.2.6.2.1 Message URL Handler Application
-This is a Symbian OS application that registers with the application framework that it can handle the mime types: x-epoc-url/fax, x-epoc-url/mailto and x-epoc-url/sms. When launched with a URL it will parse the URL to retrieve the address and other header fields and then use the SendAs API to create a new message with the correct address, headers etc. The application then uses the APIs in the MturUtils class provide by the mtmbase component in the messaging framework to launch the correct editor for the given message type. The application is marked as hidden and therefore should not be listed by UIs in application browsers.
-3.2.6.2.2 Message URL Recognisers
-This is a plug-in to the recogniser framework it will be called when the application framework wishes to recognise a file. Recognisers are called with the file name, in this case a URL, and a buffer containing the start of the file. The message URL recogniser compares the start of the URL with the URL schemes it recognises, if it finds a URL scheme it knows about it maps it to a mime type. The recogniser ignores the buffer passed in.
-Schemes recognised:
-Scheme Mime type
-mailto: X-Epoc-Url/mailto
-fax: X-Epoc-Url/fax
-sms: X-Epoc-Url/sms
-mms: X-Epoc-Url/mms
-See the application framework architectural description for more information on recognisers [R2].
-3.2.7 Messaging / SMS APIs
-3.2.7.1 Key Internal Relationships and Dependencies
-
-Figure 17 SMS Internal Dependencies
-3.2.7.2 Key External Relationships and Dependencies
-
-Figure 18 SMS External Dependencies
-3.2.7.3 API Purpose - Further Elaboration
-3.2.7.3.1 SMS Watchers
-The SMS watchers are made up of two watchers, the nbswatcher.dll and the wapwatcher.dll, and some common base classes in biowatcher.dll. The watchers listen for incoming messages from the SMS stack, part of the nbsprotocols subsystem [R3], and the WAP stack part of the WAP-Stack subsystem [R4].
-3.2.7.3.1.1 NBS Watcher
-The NBS watcher handles reception of SMS messages. When initialised by the watcher framework (see section 3.2.4) the watcher queries the bio messaging database for bio messages that are listed as having a type of ENbs. For each of these bio messages the watcher creates an object that opens a connection to the SMS stack and waits for the particular message type. The message types are either defined by the port number the message will be received on or by a string to watch for at the start of the message. For example Internet Access Configuration Point messages are start with “//SIAP11” and vCards are received on port 226. Finally the watcher listens for all other messages received from the SMS stack.
-When the NBS Watcher receives a non-class 2 SMS message it creates a new entry under the global inbox in the message store. For class 2 messages the entry is created in the class 2 folder as defined by the SMS settings, this may also be the global inbox. The details field of the entry is used to store the phone number of the incoming message or the name of the sender if the watcher finds a match for the phone number in the contacts database. The description field is used to store the first N characters of the SMS message, where N is defined in the SMS settings, or for bio messages the description as retrieved from the bio database. Bio messages also have the BioType field set to the UID of the bio message as retrieved from the bio database. The CSmsHeader class, which is a wrapper around the CSmsMessage class provided by the nbprotocols subsystem [R3], is used to externalise the SMS message to the entry’s CMsvStore. The watcher also places a copy of the body text of the message in the rich text stream of the entry’s CMsvStore.
-The NBS Watcher is also responsible for handing special SMS types including:
-• Replace Type Messages – When the watcher receives a message of this type it will scan the folder the message would have been delivered to for messages that have a matching protocol ID and from address. For each of the messages it checks whether the time stamps from the service centre and discards the older message.
-• Message Indications – The watcher can listen for incoming message waiting indications. The CSmsSettings class defines whether the watcher will listen and whether it will deliver the messages to the inbox or discard them. If the watcher is configured to listen for messages then it will use the SMS utilities in the SMS Client MTM to decode the message to determine the notification type and number of messages, e.g. 3 Email messages waiting, the strings for these messages are in the smss.rss resource file.
-• Delivery Reports – As with Message Indications the watcher can be configured to listen for these and again the SMS utilities get a string from the smss.rss resource file to put in the description field.
-The NBS Watcher handles changes to the bio database using the observer mechanism provided by the bio message database to observe when bio message types are added or removed and starting or stopping the object watching for that bio message type.
-3.2.7.3.1.2 WAP Watcher
-The WAP watcher listens for incoming messages from the WAP stack using the WAP message API [R4]. To determine ports to use to listen for messages the watcher queries the bio message database for bio message types EWsp, EWspSecure, EWap, EWapSecure and registers as an observer of the bio database and so will listen for new bio message with these types as they are added. The watcher stores the messages in the global inbox tagged with the bio type listed in the bio message database.
-3.2.7.3.2 SMS Client MTM
-The SMS Client MTM implements the standard set of Client MTM APIs described in Client MTM. In addition it provides:
-• Access to the CSmsHeader object that is used to represent the SMS message.
-• Access to the SMS settings stored in the associated SMS service.
-• The APIs required by Send As to allow Send As to create SMS messages including setting the bio type of the message to allow clients of Send As to send bio messages such as vCards and vCals. The data of the bio message is stored in the body text of the SMS message.
-• Simple check for valid SMS addresses, and SMS address is considered valid if it contains at least one digit.
-• Reading and writing SIM parameters.
-3.2.7.3.3 SMS Utilities
-These provide:
-• Classes to represent and store SMS messages (CSmsHeader), and SMS settings (CSmsSettings, CSmsMessageSettings) and a SMS number (CSmsNumber).
-• The CSmsHeader class contains and allows clients to access the CSmsMessage class that the nbsprotocols subsystem provides. This contains the entire SMS message and not just the header.
-• Functions to generate descriptions and details fields to store with SMS messages, including decoding special messages such as message indication and status report messages, reading resource file for descriptions strings of special messages, using the contacts database to replace phone numbers with names.
-• API to validate a GSM number.
-• Find the TMsvId of the SMS service entry.
-3.2.7.3.4 SMS Server MTM
-3.2.7.3.4.1 Sending Messages
-The SMS Server MTM handles sending of SMS and WAP messages via the SMS stack and the WAP stack. To support this it implements the CopyFromLocal API inherited from the Server MTM base class. It implements this as sending SMS messages and moving successfully sent messages to the Sent folder. When sending the SMS message the Server MTM checks the bio type of the message and uses the bio database to check the transport type for the bio message. The MTM supports ENbs that is sent via the SMS stack and EWap, EWapSecure that are sent via the WAP stack. The MTM does not support EWsp or EWspSecure although the watchers do support receiving them.
-If a message fails to send, sending is retried according to the settings in the smss.rss resource file as described in the schedule send section 3.2.3.
-3.2.7.3.4.2 Scheduling Messages
-The SMS Server MTM implements scheduled sending API by sub-classing from the schedule send Server MTM (see section 3.2.3). It accepts requests from clients either via the SMS Client MTM InvokeAsync API or via the CMsvSession::TransferCommand API to schedule messages to be sent or to delete existing schedules. When it receives a request to schedule a message it packages up the command and uses the scheduled send functionality to request that the task scheduler ask it to send the messages at a future point in time.
-3.2.7.3.4.3 Phone Store
-The phone store is the name given to storage of SMS messages outside of the message store. In the case of GSM phones this is the SIM. The SMS Server MTM accepts requests from clients to copy/move messages to and from the SIM and delete messages from the SIM. For example when copying to the SIM it packages up the SMS message and passes it to the SMS stack with a request to write it to the SIM. If the class2 folder has been set in the SMS settings class then the Server MTM will copy the SMS message to the SIM and then update the SMS message in the message store with details of the slot on the SIM that has been used to store the SMS and the fact that it is stored on the SIM.
-3.2.7.3.4.4 SIM Parameters
-The Server MTM provides functions to read / write SIM parameters, again these requests are passed to the SMS stack to be processed.
-3.2.8 Messaging / CDMA SMS APIs
-3.2.8.1 Key Internal Relationships and Dependencies
-
-Figure 19 CMDA SMS Internal Dependencies
-3.2.8.2 Key External Relationships and Dependencies
-`
-Figure 20 CDMA SMS External Dependencies
-3.2.8.3 API Purpose - Further Elaboration
-3.2.8.3.1 CDMA SMS Watchers
-The CDMA SMS watchers are made up of six watchers, the cdmanbswatcher.dll, vmnwatcher.dll, wemtwatcher.dll, wmtwatcher.dll, wptwatcher.dll, and the wapwatcher.dll, and some base classes in biowatcher.dll and cdmasocketwatcher. While the WAP watcher is common for both GSM and CDMA, the other watchers: CDMA NBS watcher, VMN watcher, WEMT watcher, WMT watcher, and the WPT watcher are used for CDMA only. The watchers listen for incoming messages from the CDMA SMS stack, part of the nbsprotocols subsystem [R3], and the WAP stack part of the WAP-Stack subsystem [R4].
-3.2.8.3.1.1 CDMA NBS Watcher
-The CDMA NBS watcher is similar to the NBS watcher and it handles bio messages defined in bio database. The CSmsHeader class is extended to wrap around the CCdmaSmsMessage class provided by the nbprotocols subsystem [R3], and is used to externalise the CDMA SMS message.
-For handling special CDMA SMS type, the CDMA NBS watcher is responsible for handling Message Indications as described in section 3.2.7.3.1.1 NBS Watcher.
-3.2.8.3.1.2 WAP Watcher
-The GSM WAP watcher is used to handle CDMA WAP message as well. The WAP watcher listens for incoming messages from the WAP stack, which can listen from the CDMA SMS stack or GSM SMS stack as appropriate. See 3.2.7.3.1.2 for more info about WAP watcher.
-3.2.8.3.1.3 Other CDMA Watchers
-The VMN watcher, WEMT watcher, WMT watcher and WPT watcher are CDMA watchers that handle reception of CDMA SMS messages. All CDMA SMS messages are associated with a teleservice. Therefore, each of the CDMA watchers is responsible for handling one teleservice: VMN watcher handles VMN SMS messages, WEMT watcher handles WEMT SMS messages, WMT watcher handles WMT SMS messages, and WPT watcher handles WPT SMS messages. The CSmsHeader class is reused to externalise the CDMA SMS message.
-The CDMA watchers are also responsible for handling special SMS types including:
-• Duplicate Message – When the watcher receives a duplicate message, it will discard the duplicate message as defined by the CDMA service settings.
-• User Acknowledge – The watcher can listen for user acknowledgment message of its teleservice type.
-• Delivery Acknowledge – The watcher can listen for delivery acknowledgment message of its teleservice type.
-• Read Acknowledge – The watcher can listen for read acknowledgment message of its teleservice type.
-3.2.8.3.2 CDMA SMS Client MTM
-The CDMA SMS Client MTM implements the standard set of Client MTM APIs described in Client MTM. In addition it provides:
-• Access to the CSmsHeader object that is used to represent the SMS message.
-• Access to the SMS settings stored in the associated SMS service. These settings are store in file store pre v9.0 but stored in Central Repository from v9.0 onwards.
-• The APIs required by Send As to allow Send As to create SMS messages including setting the bio type of the message to allow clients of Send As to send bio messages such as vCards and vCals. The data of the bio message is stored in the body text of the SMS message.
-• Simple check for valid SMS addresses, and SMS address is considered valid if it contains at least one digit.
-• Reading and writing SMS messages to R-UIM.
-3.2.8.3.3 CDMA SMS Utilities
-The CDMA version of SMS utilities are binary compatible with the GSM version of SMS utilities. But the classes that store SMS Message (CSMSHeader), and SMS settings (CSmsSettings, CSmsMessageSettings) and SMS number (CSmsNumber) are extended to store CDMA information. The CSmsHeader class is extended to contain and allow clients to access the CCdmaSmsMessage in addition to the CSmsMessage. Other functions provided by the GSM SMS Utilities is also provided by the CDMA version of SMS utilities, see 3.2.7.3.3 for information about GSM SMS Utilities.
-3.2.8.3.4 CDMA SMS Server MTM
-3.2.8.3.4.1 Sending Messages
-The CDMA SMS Server MTM handles sending of CDMA SMS and WAP messages via the CDMA SMS stack and the WAP stack. To support this it implements the CopyFromLocal API inherited from the Server MTM base class. It implements this as sending SMS messages and moving successfully sent messages to the Sent folder. When sending the CDMA SMS message the Server MTM will use the appropriate teleservice type. The MTM supports ENbs that is sent via the SMS stack and EWap, EWapSecure that are sent via the WAP stack. The MTM does not support EWsp or EWspSecure although the watchers do support receiving them.
-If a message fails to send, sending is retried according to the settings in the smss.rss resource file as described in the scheduled send section 3.2.4.
-3.2.8.3.4.2 Scheduling Messages
-The CDMA SMS Server MTM implements scheduled sending API by sub-classing from the schedule send Server MTM similar to implemented in the GSM SMS Server MTM. See 3.2.7.3.4.2 for more information.
-3.2.8.3.4.3 Phone Store
-In the case of CDMA phones, phone store can be phone-based storage or R-UIM based storage. The CDMA SMS Server MTM accepts requests from clients to copy/move messages to and from the phone/R-UIM and delete messages from the phone/R-UIM. For example when copying to the R-UIM it packages up the SMS message and passes it to the CDMA SMS stack with a request to write it to the R-UIM.
-3.2.8.3.5 Configuration for using CDMA SMS MTM
-The CDMA messaging components currently only support single mode, but it is designed such that it can become multimode in the future. Currently, -Dcdma option is used to for selecting CDMA mode for using emulator and building ROM.
-
-
-3.2.9 Messaging / Email APIs
-3.2.9.1 Key Internal Relationships and Dependencies
-
-Figure 19 Email Internal Dependencies
-
-3.2.9.2 Key External Relationships and Dependencies
-
-Figure 20 Email External Dependencies
-3.2.9.3 API Purpose - Further Elaboration
-3.2.9.3.1 Email Overview
-The Email plug-ins consist of a set of utilities and MTMs for POP3, IMAP4 and SMTP. For each email account a pair of services entries is created in the message store. For a POP3 account there will be an SMTP service and a POP3 service, for an IMAP4 account there will be an SMTP service and as IMAP4 service. These entries are used to store the settings for the email transport. Each of the service entries has its related ID set to the other member of the pair. The SMTP service is created invisible so the user only sees the POP3 or IMAP4 service entry, copying a message to the SMTP service will cause the SMTP Server MTM to attempt to send the message. The POP3 and IMAP4 MTMs provide functionality to synchronise with a remote email server this is achieved by extending the Client MTM interface via the InvokeAsync API. Synchronisation of a POP3 or IMAP4 account will result in copying headers and optionally body text and attachments from the email server and creating message entries under the POP3 or IMAP4 service entry.
-Email messages are represented in a common format whether they are being sent via SMTP or downloaded via POP3 or IMAP4. The email client utilities provide the classes for creating and manipulating the entry structure used to store emails. The email server side utilities provide classes to convert between the entry structure used to store emails in the message store and RFC2822 email messages sent to SMTP servers and retrieved from POP3 servers. IMAP4 email messages are parsed by the email server and the IMAP4 Server MTM requests and stores the individual parts of the messages.
-3.2.9.3.2 Email Client Utilities
-The email client utilities are part of the imcm DLL and provide classes for:
-• Storage of email messages including mime headers, RFC2822 headers, attachments, body text and encoding information in the message store
-• Manipulating email messages, for example adding attachments, replying etc.
-• To wrap up the character converters used to convert between standard character sets and Unicode. These make use of the charconv component that is part of the system libraries subsystem.
-• Storage of Email settings in the message store.
-• Progress information for email operations.
-The utilities are used directly by clients to access parts of email messages for display. CImEmailMessage provides the functionality used by clients displaying email messages, including listing attachments, getting body text and resolving URIs in M-HTML messages.
-The Email Client MTMs use the utilities when they are asked to create, reply to and forward messages CImEmailOperation provides the functionality to perform these operations. Each email message is represented by a parent message entry and then entries to represent mime folders and mime parts, see Figure 7 for an example, so adding or deleting mime parts involves walking the tree of entries and inserting / removing entries as appropriate.
-3.2.9.3.3 Email Server MTM Utilities
-The Email Server MTM Utilities are responsible for generating and parsing of RFC2822 format email messages and providing an API to wrap up a TCP/IP connection to a remote email server.
-• Parsing of RFC2822 Email Messages – The utilities provide an API that accepts the text of an RFC2822 email message a line at a time and stores the email message in messaging’s internal format for email messages. See the Email Client Utilities for details of this format. The API handles storing of RFC2822 headers, MIME headers, decoding of Base64 encoded or uuencoded attachments and decoding of text received in character sets supported by the charconv component. This API is only accessible to Server MTMs, as it requires classes that can only be instantiated while running within the message server process. See the Messaging Functional Specification [R1] for detail on which email specifications the utilities support.
-• Generation of RFC2822 Email Messages – The utilities provide an API to convert an email in messaging’s internal format into an RFC2822 email message. The API provides access to the RFC2822 text a line at a time for streaming to an SMTP server. The exact format of the email depends on the settings passed in; the API can generate plain RFC2822 email messages with uuencoded attachments, MIME email messages with Base64 encoded attachments, or M-HTML email messages with Base64 encoded attachments. See the Messaging Functional Specification [R1] for detail on which email specifications the utilities support.
-• TCP/IP socket wrapper – The utilities provide a class that abstracts a TCP/IP socket supplied by the networking subsystem into an API that supports sending and receiving lines of text to / from a remote server. This API is used to connect to remote email servers by each of the email Server MTMs. The API can either create insecure or secure sockets enabling the SSL encryption provided by the networking subsystem. It also supports changing an insecure socket into a secure socket, this enables the email Server MTMs to implement email protocols where the initial connection to the server is insecure and then a secure socket is negotiated before sending or requesting any sensitive information.
-3.2.9.3.4 POP3 MTMs
-The POP3 MTMs implements the functionality to synchronise the local message store with a remote POP3 email server.
-3.2.9.3.4.1 Client MTM
-The POP3 Client MTM implements the standard Client MTM APIs and other extensions:
-• Reply to, forward – These are accessible via the ReplyL and ForwardL APIs of a Client MTM and are implemented as calls to the email utilities class CImEmailOperation.
-• Reply to, forward, create new messages, create receipts and forward as attachment – These are accessible as commands available via the InvokeAsyncFunction API of the Client MTM, they are implemented as calls to CImEmailOperation.
-• Connecting, disconnecting and copying email while connected – These operations are accessible as commands available via the InvokeAsyncFunction API of the Client MTM, they are implemented as calls to the POP3 Server MTM.
-• Querying connection status – This command lets clients know whether the POP3 Server MTM is connected to an email server, and is available via the InvokeAsyncFunction API of the Client MTM. The Client MTM requests the information from the Server MTM.
-• Compound operations – The Client MTM provides functionality to wrap up connecting to email servers, copying / moving new messages or a selection of messages, and then optionally disconnecting. These commands are available via the InvokeAsyncFunction API of the Client MTM. The Client MTM implements this by using the CImPOP3GetMail class which requests the correct sequence of operations from the Server MTM, waiting for each operation to complete before requesting the next one.
-• Send on next connection If the Client MTM gets a request to connect to an email server it will check whether the POP3 settings. If send on next connection is requested it will launch the autosend.exe executable (see section 3.2.7.3.7) to handle sending messages waiting in the outbox.
-• Offline operations – The POP3 Client MTM has a command to cancel offline operations, this is available via the InvokeAsyncFunction API of the Client MTM. The Client MTM passes the request to the Server MTM.
-3.2.9.3.4.2 Server MTM
-The POP3 Server MTM handles the communication with the remote POP3 server and implementation of the POP3 protocol. The MTM uses CImTextServerSession to handle the communication with the email server and CImRecvConvert to parse the email messages downloaded, both are provided by the Email Server MTM Utilities.
-• Connect – The POP3 Server MTM will open a socket to the email server using CImTextServerSession and login user the username / password in the POP3 settings. After a successful connection the Server MTM will attempt to synchronise the current state of headers stored on the email server with the set stored in the message store and then start any pending offline operations. After the connect operation has completed the Server MTM will inform the message server that it is expecting more operations via the CommandExpected API and therefore the message server will not delete and unload the Server MTM.
-• Populate Message – The POP3 Server MTM treats requests to copy a message from and to the POP3 service as a request to download the full message.
-• Offline operations – When the POP3 Server MTM receives a request to copy, move, or delete and is not connected to a POP3 email server the Server MTM will store the operation in the CMsvStore of the entry being modified and perform the operation on the next connection to the email server.
-• Disconnect – When disconnecting from a remote email server the POP3 MTM will run any pending offline operations stored. After the disconnect operation completes the Server MTM will allow the message server to delete and unload the Server MTM by setting the CommandExpected API to false.
-3.2.9.3.5 IMAP4 MTMs
-The IMAP4 Server MTM implements the functionality to synchronise the local message store with a remote IMAP4 email server.
-3.2.9.3.5.1 Client MTM
-The IMAP4 Client MTM implements the standard Client MTM APIs and other extensions:
-• Connecting, disconnecting, synchronising, un/subscribing folders – These operations are accessible as commands available via the InvokeAsyncFunction API of the Client MTM, they are implemented as calls to the IMAP4 Server MTM.
-• Send on next connection – If the Client MTM gets a request to connect to an email server it will check whether the IMAP4 settings. If send on next connection is requested it will launch the autosend.exe executable (see section 3.2.7.3.7) to handle sending messages waiting in the outbox.
-• Reply to, and forward messages – These are accessible via the ReplyL and ForwardL APIs of a Client MTM and are implemented as calls to the email utilities class CImEmailOperation.
-• Reply to, forward, create new, create receipt, forward as attachment – These are accessible as commands available via the InvokeAsyncFunction API of the Client MTM, they are implemented as calls to CImEmailOperation.
-• Querying connection status – These commands let clients know whether the IMAP4 Server MTM is connected to an email server and whether it is currently processing a request. They are available via the InvokeAsyncFunction API of the Client MTM. The Client MTM requests the information from the Server MTM.
-• Compound Connection and synchronisation – The IMAP4 Client MTM provides a compound operation that connects and synchronises with an IMAP4 server. This operation is implemented as a client side object that combines requests to the IMAP4 Server MTM. The client side operation can complete the client request either after the connection, after the connection + sync or after the connection + sync + disconnect. The client will keep requesting that the inbox be resynchronised at a configurable interval so new messages received in the inbox on the server will appear under the IMAP4 inbox. The CImapConnectAndSyncOp class handles these compound operations.
-• Compound Connect and copy / move / populate messages – The IMAP4 Client MTM provides a compound operation that connects to an IMAP4 server and copies moves or populates messages. The implementation is provided by the CImImap4GetMail class which makes calls back into the IMAP4 Client MTM.
-• Offline operations – The IMAP4 Client MTM has a command to cancel offline operations, this is available via the InvokeAsyncFunction API of the Client MTM. The Client MTM passes the request to the Server MTM.
-3.2.9.3.5.2 Server MTM
-The IMAP4 Server MTM handles the communication with the remote IMAP4 server and implementation of the IMAP4 protocol. The MTM uses CImTextServerSession to handle the communication with the email server. The IMAP4 Server MTM opens two connections to the IMAP4 server this enables users to download messages while the Server MTM is performing a background synchronisation if requested by the Client MTM.
-• Connect – The IMAP4 Server MTM will open a socket to the email server using CImTextServerSession and login using the username / password in the IMAP4 settings. After a successful connection the Server MTM will optionally attempt to synchronise the current state of headers stored on the email server with the set stored in the message store and then start any pending offline operations. After the connect operation has completed the Server MTM will inform the message server that it is expecting more operations via the CommandExpected API and therefore the message server will not delete and unload the Server MTM.
-• Copy, Move messages – The IMAP4 Server MTM supports copying and moving messages between folders on the IMAP4 server and between the IMAP4 server and local folders.
-• Delete messages – The IMAP4 Server MTM will mark the email as deleted on the server; however it will not be deleted until the IMAP4 Server MTM disconnects from the server.
-• Folders – The IMAP4 Server MTM will allow folders to be subscribed, unsubscribed, renamed, copied, moved, and created within the IMAP4 service. Subscribing to a folder means that it will be visible to the user and synchronised with the remote server. The inbox is always subscribed.
-• Offline operations – When the IMAP4 Server MTM receives a request to copy, move, or delete and is not connected to an IMAP4 email server the Server MTM will store the operation in the CMsvStore of the entry being modified and perform the operation on the next connection to the email server.
-• Disconnect – When disconnecting from a remote email server the IMAP4 MTM will run any pending offline operations stored. After the disconnect operation completes the Server MTM will allow the message server to delete and unload the Server MTM by setting the CommandExpected API to false.
-
-3.2.9.3.6 SMTP MTMs
-The SMTP MTMs provide functionality to send email messages. They are made up of the Client MTM that is part of the imcm DLL and the Server MTM.
-3.2.9.3.6.1 Client MTM
-The SMTP Client MTM implements the standard Client MTM APIs including the functions required to allow clients of Send As to create email messages.
-3.2.9.3.6.2 Server MTM
-The SMTP MTMs provide functionality to send email messages; it interprets requests to copy entries to an SMTP service as a request to send those messages. In addition it responds to two extended commands via the StartCommand Server MTM interface. These commands are KSMTPMTMIsConnected that responds with whether the Server MTM is currently connected to a remote SMTP server and KSMTPMTMSendOnNextConnection which performs the same operation as copying a selection of messages to an SMTP service. The only difference between the copy operation and the KSMTPMTMSendOnNextConnection operation is that the latter can be called without a selection of messages.
-When the Server MTM receives a request to send messages it builds a selection of messages consisting of the messages passed into the operation and any messages waiting in the outbox to be sent. To determine which messages in the outbox are waiting to be sent the SMTP server checks for messages that have the same service ID as the destination of the send operation and have a sending state of KMsvSendStateWaiting, KMsvSendStateScheduled or KMsvSendStateResend. This means that any request to send messages may result in more messages being sent than explicitly listed in the selection passed to the send operation.
-The Server MTM restores its settings from the SMTP service it has been asked to copy the messages to. Then it connects to the SMTP server using the CImTextServerSession class in the Email Server MTM Utilities, passing in the SMTP server address and TCP/IP port number from the SMTP settings. Then for each message to be sent the Server MTM uses the Email Server MTM utilities to generate an RFC2822 format message to send to the SMTP server, the RFC2822 text is generated on the fly as the data is sent to the SMTP server. If the SMTP server accepts the message to be sent then the Server MTM moves the message to the sent folder and sets its sending state to sent. If the SMTP server rejects the message then the Server MTM leaves the message in the outbox and sets the sending state to failed. Separate emails are generated for BCC recipients to ensure that the SMTP server doesn’t incorrectly include BCC recipients in emails sent to addresses in the To and CC fields of the email.
-3.2.9.3.7 Autosend
-The Autosend component is an executable that is kicked off by the POP3 and IMAP4 Client MTMs if the send on next connection setting is set. This executable will just make a request to the SMTP Server MTM to send messages associated with the SMTP service related to the POP3 or IMAP4 service, wait for the operation to finish and then exit.
-3.2.10 Messaging / MMS APIs
-The MMS module has been removed from v9.0 and onwards.
-3.2.10.1 Key Internal Relationships and Dependencies
-
-Figure 21 MMS Internal Dependencies
-3.2.10.2 API Purpose - Further Elaboration
-3.2.10.2.1 MMS Overview
-The MMS MTM provides functionality for creating, accessing, sending and receiving MMS messages. Messages are sent and received without the client application needing to open or close any kind of session. The management of the MMS session is handled entirely within the MTM.
-MMS clients are alerted when a new message is available for download via the WAP Push mechanism. A WAP push watcher is provided to handle these notifications. After the notification the message can be downloaded over WSP or HTTP. Messages are sent by posting the data over WSP or HTTP. The Symbian MMS implementation can handle sending or receiving MMS message over either protocol.
-MMS messages are based on the MIME format but are binary encoded using WSP. Note that MMS messages are encoded in this way even if they are posted over HTTP as opposed to WSP. The codec component is responsible for this encoding and decoding.
-3.2.10.2.2 MMS Utilities
-3.2.10.2.2.1 Key External Relationships and Dependencies
-
-Figure 22 MMS Utilities External Dependencies
-The MMS utilities provide the message and settings encapsulation classes. The MMS settings and messages are stored in the message store, the MMS utilities provide the interfaces to access this data.
-3.2.10.2.2.2 Settings
-The settings functionality provided by the MMS utilities allows the messaging client to persist MMS settings in the message store. Supported settings include:
- MMSC (MMS server) address
- WSP or HTTP transport
- Autofetch messages on notification
- Preferred IAP for the MMS network connection
-The settings functionality is also used by the server MTM to retrieve the settings prior to message sending or fetching.
-3.2.10.2.2.3 Message Encapsulation
-The message classes provide the message access functionality. Messages can be created, stored, restored and read using these classes. Functionality includes:
- Adding media objects to the message
- Enumerating through media objects
- Adding recipients, subject line, etc. to a message
- Adding other headers to the message, e.g. expiry date
- Finding the appropriate media object for a given URI in the SMIL part (URI resolving)
-The message data is stored in the message store using one entry per message regardless of the number of media objects added to the message. This is preferable to using multiple message entries as it is faster and uses less disk space.
-Most of the message access code is common whether it is being used on the client or server side, however some parts of it are specific. For this reason it is essential that the appropriate client or server side CMmsMessage derived class is used.
-3.2.10.2.3 MMS Watcher
-3.2.10.2.3.1 Key External Relationships and Dependencies
-
-Figure 23 MMS Watcher External Dependencies
-
-The MMS watcher plug-in is responsible for intercepting incoming MMS notifications and delivery reports then taking the appropriate action. It is implemented as a WAP Push watcher plug-in.
-When an MMS notification is received an MMS entry is created in the inbox using the MMS utilities. At this point the entry has its incomplete flag set. If the settings have the autofetch option selected then the MMS watcher initiates the fetch operation via the MMS client MTM.
-If a delivery report is received then the delivered flag is set on the appropriate sent message. If an outgoing message was sent to several recipients then there will be several delivered flags. A delivery report from each recipient will set the appropriate delivered flag.
-3.2.10.2.4 MMS Client MTM
-3.2.10.2.4.1 Key External Relationships and Dependencies
-
-Figure 24 MMS Client MTM Dependencies
-As with most other MTMs the MMS client MTM provides access to the server MTM functionality for messaging clients. It also implements the Send-As interface and reply and forward functionality.
-3.2.10.2.4.2 Send-As Implementation
-The Client MTM Send-As interface is implemented in the MMS Client MTM. The implementation differs slightly from other MTMs because additional presentation content may be generated depending on the media objects that are added. When simple combinations of images, sounds and text are added a SMIL presentation is generated to link them together. This is preferable to simple adding the objects as attachments where some clients render them as a list of files and others fail to render them at all.
-The SMIL data is constructed using templates stored in resource files, the GMXML (SMIL) composer is not used.
-3.2.10.2.4.3 Reply / Forward
-The Client MTM can be used to create replies to received messages or to create forwarded responses. The reply and forwarding operations are performed asynchronously.
-3.2.10.2.5 MMS Server MTM
-3.2.10.2.5.1 Key External Relationships and Dependencies
-
-Figure 25 MMS Server MTM Dependencies
-The Server MTM is the most complicated part the MMS implementation. It handles all of the state information required to send or fetch MMS messages. It is also responsible for managing the HTTP or WSP session and the connections to the phone network.
-3.2.10.2.5.2 Operations
-All MMS server MTM functionality is encapsulated in operations. An operation consists of the setup of a session, the sending, fetching and acknowledgements when appropriate, it then closes the session. The messaging client initiates an operation with a single call to the Client MTM, there is no need for the messaging client to explicitly establish the session or to know about the internal states. However, these internal states are available to the messaging client via the progress structure if this level of user feedback is required.
-Two types of operation are supported, background and foreground:
-A maximum of one foreground operation can be running at any one time. The messaging client can poll the server MTM for the progress of a running foreground operation, likewise it can cancel it if necessary.
-A background operation does not support progress information and can not be cancelled by the messaging client. It is possible to initiate background operations even if other background or foreground operations are pending. However, background operations are queued and a maximum of one will actually be running at any one time.
-The MMS watcher uses a background operation to perform automatic fetching. While the background autofetch is occurring it is still possible to start a foreground operation (such as sending a message) if required.
-3.2.10.2.5.3 Session and Connection Management
-The server MTM uses the HTTP Transport Framework to enable the HTTP or WSP session. HTTP or WSP can be selected at runtime by selecting the appropriate option in the settings. The server MTM is responsible for reading any HTTP proxy details from the CommDB and passing it to the HTTP framework. See the http transport framework architectural description for more information on recognisers [R5]
-The server MTM is also responsible for managing the connection to the phone network. Connections are opened when required using the RConnection mechanism, multi-homing is supported provided that the underlying HTTP framework transport plug-in also supports it.
-3.2.10.2.6 MMS Codec
-The MMS Server MTM is in charge of the state transitions, connection, session, the actual posting and fetching of the data from them, however it does not encode or decode the MMS PDUs. The encoding and decoding is performed by the MMS Codec.
-For decoding the Server MTM passes the Codec the MMS PDU data in a descriptor for processing. If the PDU contains a received MMS message then the message entry is updated with the decoded MMS data.
-For encoding the Server MTM passes a reference to the message store entry containing the un-encoded MMS data. The Codec then encodes it and returns the PDU to the Server MTM in a descriptor.
-
-
-3.2.11 Messaging / BIO APIs
-3.2.11.1 Key Internal Relationships and Dependencies
-
-Figure 26 BIO Message Internal Dependencies
-3.2.11.1.1.1 Key External Relationships and Dependencies
-
-Figure 27 Bio Parser External Dependencies
-
-3.2.11.2 API Purpose - Further Elaboration
-3.2.11.2.1 BIO Overview
-The BIO messaging components have been designed to unify and simplify the way in which system messages are processed. In this context ‘system messages’ refers to messages received on the device which are intended to update some attribute(s) on the system as opposed to being presented to the user. Examples of these types of messages include vCards which are parsed and then displayed to the user and when accepted modify the users contact database and OTA configuration messages which are again parsed before display to the user and if accepted create email accounts or internet access points.
-The BIO messaging components can be broken down into three groups:
-1) The BIO MTM - To initiate the parsing and processing of BIO messages
-2) The BIO Database - Maps port numbers, MIME types, etc. to bio types in order to identify the type of incoming BIO messages.
-3) The BIO Parsers - To parse and process the BIO message payload
-BIO messages are not receive by the bio messaging framework, they come over other message transports for example see section 3.2.6.3.1 on the SMS watchers which describes how the SMS watchers receive bio messages and use the bio framework to tag the messages with the correct bio id.
-3.2.11.2.2 BIO MTM
-The BIO client MTM is called by the messaging client to parse or process a BIO message that has been saved in the message store. It is the responsibility of a BIO watcher to save the BIO message with the BIO flag and the appropriate BIO type set.
-The BIO client MTM does very little, its primary task is to pass on the messaging client request to the server MTM. Two operations are supported, parse and process.
-The messaging client is expected to initiate the parsing of the BIO message before processing it. The parsing step involves analysing the data and storing it in a form that can be displayed to the user via the BIO message viewer.
-Once the message has been parsed the messaging client can initiate the processing of the message.
-The BIO server MTM is responsible for deferring the parsing and processing to the appropriate BIO parser. The behaviour for the parsing and processing steps varies between parsers. See the BIO Parsers section for more information.
-The bio MTM does not support sending messages and therefore does not support reply / forwarding messages. For bio messages sending / reply etc. is supported by the particular MTM that the message is sent over, for example SMS.
-3.2.11.2.3 BIO Database
-The BIO database is used to identify the type of BIO messages. It maps message attributes such as port number, MIME type or leading string to a BIO type. These are attributes are then used by clients of the bio framework to know what ports to listen for messages on. For example the SMS watchers use the leading string to wait for SMS messages that start with that string and when storing those messages in the inbox tag them with the bio id associated with that leading string. See the SMS watcher section 3.2.6.3.1 for more examples of how the BIO database can be used.
-3.2.11.2.4 BIO Parsers
-The BIO parsers are plug-ins for parsing and processing incoming BIO messages. They are invoked by the BIO Server MTM depending on the BIO type of the message being processed. Each BIO parser implements two functions, ParseL and ProcessL. The level of functionality varies between parsers. Some parsers update the final repository with the received data, e.g. WAPP updates the CommDB with the received settings. Some parsers simply save the data in an unparsed state for processing by another component, this secondary parsing is not part of the BIO framework and must be initiated by the messaging client. An example is when GFP saves vCard data as a file as opposed to updating the contacts database, the UI must then invoke the Versit parser to parse the vCard and commit it to the contacts database.
-3.2.11.2.4.1 Generic File Parser (GFP)
-The generic file parser can be used to identify and save a variety of BIO data types, e.g. vCards and vCals. The Generic File Parser does not process the data, it simply saves it in the message store for processing by another component. The file is saved as an attachment of the message entry that was parsed.
-3.2.11.2.4.2 Nokia/Ericsson OTA Parser (WAPP)
-The WAPP parser decodes Nokia/Ericsson OTA messages and updates CommDB to reflect the received settings.
-3.2.11.2.4.3 Nokia Smart Message Internet Access Parser (IACP)
-The IACP parser decodes Nokia Smart Messages and updates the CommDB and messaging settings where appropriate.
-3.2.11.2.5 BIF Files and Utilities
-The BIF files encapsulate the information required for identifying BIO messages, these details may include the expected port number, MIME type or leading string. Different BIO watcher will use different information from these files, for an example see the 3.2.6.3.1. The information can be retrieved from the BIF files by using the BIF utilities. Generally BIO aware clients will access this information via the BIO database. BIF files are resource files previous to the v6.1 release they were binary files generated by biftool.exe.
-3.2.11.2.6 Platform Security Compliant Messaging / BIO APIs
-In the platform security model the BIO parsers are run in the client space rather than in the message server space, as is done in the non-platform secure model. If the BIO parsers are run in the message server space, it allows a client process to gain the capabilities of the message server. IPC policing can protect the message server from this.
-Also, for the message server to be able to load any BIO parser it would need more capabilities than it really requires. By running the BIO parsers in the client space, both these issues are solved. The client process must be trusted with the necessary capabilities to run the specified BIO parser.
-The BIO registry files are located in the \resource\messaging\bif read-only directory. All BIO parser DLLs are located in the \sys\bin protected directory.
-
-Figure 26 BIO Message Dependencies (v9.0)
-The BIO client MTM is responsible for loading the BIO database and BIO utilities to handle parse/process requests from clients.
-The BIO registry files no longer identify the BIO parsers DLLs via their UID – the registry file must use the BIO parser DLL name to identify them.
-3.2.12 Messaging / OBEX MTM APIs
-3.2.12.1 Key Internal Relationships and Dependencies
-
-Figure 28 OBEX Internal Dependencies
-3.2.12.2 OBEX MTM Overview
-The OBEX MTM offers simple IR and Bluetooth beaming functionality. It provides an API that is consistent with other MTMs so that the underlying OBEX APIs do not need to be used directly for beaming applications. The OBEX MTM does not provide OBEX receiving functionality, in order to receive OBEX data the underlying OBEX APIs must be used directly.
-3.2.12.2.1 OBEX MTM
-The OBEX MTM is split into three parts. OBEX MTM DLLs, IR MTM DLLs and Bluetooth MTM DLLs. The OBEX MTM DLLs can not be used on their own they provide the base OBEX MTM functionality for the derived IR and Bluetooth MTMs.
-There are two APIs that can be used to create OBEX messages:
-1) The Send-As API
-2) Linked attachments by filename
-The Send-As API provides an interface consistent with other MTMs, however it requires all attachments to be copied into the message store before they can be sent, this is often undesirable for beaming applications because it is wastes disk space. For this reason a second API is provided that allows attachments to be linked to outgoing messages by filename, when this API is used there is no need to copy the attachments to the message store.
-Unlike many other MTMs after OBEX tries to send a message it is deleted from the outbox whether the sending succeeds or fails.
-3.2.12.2.1.1 OBEX MTM Key External Dependencies
-
-Figure 29 OBEX External Dependencies
-3.2.12.2.2 IR MTM
-The bulk of the OBEX MTM functionality is provided by the OBEX MTM DLLs, the IR MTM itself just sets up the parameters.
-3.2.12.2.2.1 IR MTM Key External Dependencies
-
-Figure 30 IR MTM Dependencies
-3.2.12.2.3 Bluetooth MTM
-The bulk of the OBEX MTM functionality is provided by the OBEX MTM DLLs, the Bluetooth MTM just subclasses from the OBEX MTM and sets up Bluetooth specific parameters.
-3.2.12.2.3.1 Bluetooth MTM Key External Dependencies
-
-Figure 31 Bluetooth MTM Dependencies
-3.2.12.2.4 OBEX MTM Utils
-The OBEX MTM Utils provide utility functionality used by the other OBEX MTM DLLs. The two main areas of functionality provided by this component are:
-1) Filename linking functionality
-2) Bluetooth SDP lookup
-The filename linking functionality is provided in the utilities because linked files must be added by the client side during message creation and need to be read on the server side during sending.
-
-3.2.12.2.5 Platform Security Compliant Messaging / OBEX MTM APIs
-From v9.0 and onwards the service settings of all the derived OBEX MTMs are stored in the Central Repository. The OBEX message is stored in the message store as an attachment – from v9.0 and onwards the Attachment API is used to attach the OBEX message.
-
-3.2.13 Messaging / GMXML APIs
-3.2.13.1 Key Relationships and Dependencies
-
-Figure 32 GMXML Dependencies
-3.2.13.2 Overview
-The GMXML component provides simple XML DOM parsing and validation functionality. It is intended for parsing XML that might be needed in messaging applications, specifically SMIL parsing for MMS rendering. It is not a general purpose XML parser and will not be suitable for some applications, e.g. browsing.
-3.2.13.2.1 GMXML DOM
-The DOM implementation is fit for purpose for SMIL rendering but differs from the standard DOM design in several respects, e.g. attributes are not stored as discrete nodes, for performance reasons they are stored with the element.
-The DOM tree classes are all derived from nodes. Implemented node types include elements, text and comments. The type of each element is stored as a descriptor as opposed to an enum. This is less efficient than storing it as an enum but provides maximum flexibility when dealing with unknown element types.
-Nodes are linked together in a tree structure as might be expected in a DOM implementation. The tree structure exists on the heap.
-3.2.13.2.2 GMXML Parser and Composer
-3.2.13.2.2.1 Parser
-The parser takes XML input from a buffer or file and creates the corresponding DOM structure on the heap.
-The parser is capable of performing some basic validation. In order to validate against a DTD a class that implements the GMXML DTD interface is required. The DTD interface specifies several functions that provide the required validation, e.g. one of the functions determines if a given attribute is valid for a given element. An instance of the DTD class should be passed into the parser when validation is required but can be omitted if no validation is needed.
-3.2.13.2.2.2 Composer
-The composer takes a DOM tree and generates XML output from it. The XML output is written to a file.
-3.2.13.2.3 GMXML SMIL DTD (Validator)
-The SMIL DTD validator class is an implementation of the DTD validator interface. It implements several simple functions that provide the information required to validate SMIL data. An instance of the SMIL DTD validator should be passed into the parser if SMIL validation is required.
-4 Security
-4.1 Data caging
-For data storage in the pre-platform security compliant architecture, refer to section [3.2.1.3.2]
-For the data caging in the platform security compliant architecture of v9.0 and onwards, refer to section [3.2.1.3.3]
-4.2 Backup and restore
-The message server registers the index file with the backup server. When informed about a backup/restore it releases the index file, sending events to messaging clients informing them that the message store is unavailable. When informed it can open the index file again, it checks the time stamp on the index file; if it has changed since the file was released it reloads the index file. If the newly restored index file is found to be corrupt it is deleted and a new message store is created. See the section on page 14 for details on how the message server handles corrupt stores. The client performing the restore should always wipe the existing message store before starting to copy the message store from the backup to the device.
-4.3 Capability ranges
-In the platform security compliant architecture of v9.0 and onwards, the capabilities allocated to messaging sub-systems are as listed in following table.
-4.3.1 Capabilities granted to executables
-The following table lists the executables and their capabilities and also gives a basic example for having the required capability.
-
-Executable Capability Rationale (basic example of capability requirement)
-msexe.exe ProtServ ProtServ is required to allow the msexe.exe to start a protected server. This stops processes without ProtServ from starting a server pretending to be the message server
- ReadDeviceData ReadDeviceData is needed to able to read service settings
- WriteDeviceData WriteDeviceData is needed to able to write service settings
- NetworkServices NetworkServices capability is needed to access network transports (SMS, POP3, SMTP, IMAP4).
- LocalServices LocalServices is needed to be able to access IR and Bluetooth
- ReadUserData ReadUserData is needed to be able to read user data (e.g. service settings).
-watcher.exe ReadDeviceData ReadDeviceData is needed to able to read service settings
- WriteDeviceData WriteDeviceData is needed to able to write service settings
- NetworkServices NetworkServices capability is needed to access network transports (SMS).
- LocalServices LocalServices capability is needed for the plug-ins to access IR and Bluetooth
- ReadUserData ReadUserData is needed to be able to read user data
- WriteUserData WriteUserData is needed to be able to write user data
-autosend.exe ReadUserData ReadUserData capability is needed to be able to read data from Outbox and SMTP server MTM.
- WriteUserData WriteUserData capability is needed to be able to write data in Outbox and SMTP server MTM.
- NetworkServices NetworkServices capability is needed to access network transports (SMS, POP3, SMTP, and IMAP4).
- LocalServices LocalServices capability is needed to access the IR and Bluetooth
-SchSend.exe ReadDeviceData ReadDeviceData is needed to able to read settings data
- NetworkServices NetworkServices capability is needed to access the network transports (SMS, POP3, SMTP, and IMAP4).
- LocalServices LocalServices is needed to be trusted by other MTM
- ReadUserData ReadUserData is needed to be able to read user data.
- WriteUserData WriteUserData is needed to be able to write user data.
-SendAs.exe ReadDeviceData ReadUserData is needed to be able to read data in Outbox.
- WriteDeviceData WriteUserData is needed to be able to write data in Outbox.
- NetworkServices NetworkServices capability is needed to access the network transports (SMS, POP3, SMTP, and IMAP4).
- LocalServices LocalServices is needed to be able to access IR and Bluetooth
-
-4.3.2 Capabilities granted to DLLs
-The assigned Platform Security attributes for DLLs within messaging are outlined in the following table.
-DLL Capability
-bifu.dll All –TCB
-bioc.dll All –TCB
-biodb.dll All –TCB
-bios.dll All –TCB
-biowatcher.dll same as watcher.exe
-biut.dll All –TCB
-cbcp.dll All –TCB
-enp.dll All –TCB
-gfp.dll All –TCB
-iacp.dll All –TCB
-nbswatcher.dll same as watcher.exe
-cdmanbswatcher.dll same as watcher.exe
-CdmaSocketWatcher.dll same as watcher.exe
-VMNWatcher.dll same as watcher.exe
-WEMTWatcher.dll same as watcher.exe
-WMTWatcher.dll same as watcher.exe
-WPTWatcher.dll same as watcher.exe
-wapp.dll All –TCB
-wapwatcher.dll same as watcher.exe
-smildtd.dll All –TCB
-xmldom.dll All –TCB
-xmlparser.dll All –TCB
-smiltranslator.dll All –TCB
-imcm.dll All –TCB
-imps.dll same as msexe.exe
-imut.dll All –TCB
-msgs.dll All –TCB
-msgurlrec.mdl same as AppArc.exe (once it exists; eiksrv in meantime)
-mtur.dll All –TCB
-pops.dll same as msexe.exe
-schsend.dll All –TCB
-send.dll All –TCB
-smcm.dll All –TCB
-smcm_gsm.dll Synonym for smcm.dll
-smcm_cdma.dll Synonym for smcm.dll
-smss.dll same as msexe.exe
-smss_gsm.dll Synonym for smss.dll
-smss_cdma.dll Synonym for smss.dll
-smts.dll same as msexe.exe
-btcmtm.dll All –TCB
-btsmtm.dll same as msexe.exe
-irc.dll All –TCB
-irs.dll same as msexe.exe
-obexclientmtm.dll All –TCB
-obexmtmutil.dll All –TCB
-obexservermtm.dll same as msexe.exe
-
-The reason for setting a high capability to the DLLs is to make it possible for almost anyone to link to them. Although a DLL may have capabilities ALL-TCB (All minus TCB), its real capability is limited by the process which loads the DLL.
-4.3.3 Capabilities required to use the subsystem
-The message subsystem needs to be protected against malicious clients. The following table shows the key capabilities required to do related activities in different components.
-
-Component Related Activity Required Capability and SID
-Message server Create message in local folder No capability required
- Create message in Outbox ReadUserData, WriteUserData and MTM specific capabilities
- Access client MTM ReadUserData, WriteUserData and MTM specific capabilities
-Watcher Allow plug-ins to wait on events (e.g. arrival of SMS) Watcher always polices if the client capabilities are trusted by the watcher framework, else it will not be loaded
-Plug-ins or clients using watcher need the same capabilities as watcher.exe to be able to be loaded by watcher.
-Autosend Send messages in background NetworkService or LocalService required by the message type
-SchSend Scheduling of operations (e.g. sending SMS) SchSend always polices to see if the process was started by the Task Scheduler – if not the process terminates without performing any of the scheduled tasks. Also, the SchSend verifies that only itself and the message server created the scheduled tasks. If this is not the case, SchSend does not performing the scheduled tasks.
-SendAs Create message Draft, move it to Outbox, and send message WriteDeviceData or WriteUserData and other capability required by the message type
-
-5 Further Information
-5.1 References
-No. Document Reference Version Description
-R1 messaging_functional_specification.doc 0.6 Messaging Functional description
-R2 SGL.GT0143.161_App-Framework_Architectural_Description.doc 1.0 App-Framework Architectural Description
-R3 NBProtocols_Subsystem_Architectural_Description.doc 0.2 NBProtocols Architectural Description
-R4 WAP-stack_architectural_analysis.doc 1.0 WAP stack architectural analysis
-R5 HTTP Transport Framework Architectural Description.doc 1.1 HTTP Transport Framework 1.1 Architectural Description
-5.2 Open Issues
-The following issues need to be resolved before this document is completed:
-1. Top-level architecture diagram showing the framework and plug-ins should be added to overview section.
-2. Message store section should talk about removable media.
-3. Define "Message Server Client API" and "Messaging Client API" in the glossary, and ensure it is consistently used in the diagrams
-4. Add a sequence diagram for receiving a vCard over SMS and integrating it into contacts
-5. Add a sequence diagram for sending an SMS
-6. Add a sequence diagram for synchronising a POP3 mail box
-7. Add a sequence diagram for connecting to an IMAP4 mail box and downloading a message
-8. Capability table should be updated after the implementation of server e.g. message server
-9. Sequence diagram may need to be changed to show secured platform operation
-10. In section [3.1.1.4] the server SendAsV2 to find a correct name
-11. Section 3.2.1.3.3.1 Data Caging file 'Mtm Registry v2'may need a correct name
-12. Breakdown diagram showing all DLL, exes, apps in the messaging subsystem for both the pre-v8.0 and post v9.0 in section[3.2]
-13. Needs to say more about how the capabilities are policed and the algorithms used for different operations
-14. The dependecy between the message server and the central repository need to be listed in the email, SMS and OBEX diagrams (e.g. message store)
-15. Section 3.2.1.2 - figure 3 - Central Repository also get used by the Message server, or server MTMs (e.g. POP3), to retrieve account settings the path, required DLL and description are not given
-16. Section 4.3.3 title can be Police requirement of the sub-system, add extra column for SID in the table and list the use of SID. For example SchSend checks for Task Scheduler SID
-
-
-5.3 Glossary
-The following technical terms and abbreviations are used within this document.
-Term Definition
-BIO
-Bearer Independent Object Smart messages e.g. vCards, vCals, and WAP provisioning messages. These can currently be received via the WAP stack, SMS stack, Bluetooth or Infrared.
-BIO Type UID that represents the content type of a BIO Message.
-Message Centre Application that displays list views of messages to the user, allowing the user to perform operations such as copying messages, sending messages creating new messages etc.
-Message Viewer Application for viewing a message.
-Message Editor Application for creating or editing a message
-Message Server Symbian OS Server that handles request to modify the Message Store
-Message Store Store of messages and related information kept in the file system on a Symbian OS device.
-Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
-Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
-Global Inbox A standard folder under the local service which is used to store incoming messages like SMS MMS etc. as opposed to an IMAP4 Inbox which would be under an IMAP4 service and is a representation of the Inbox on an IMAP4 email server.
-Central Repository centralised and secure storage facility for application settings
-OBEX Object exchange protocol, used to send objects such as vCards or files between devices via infrared or Bluetooth.
-GMXML XML parser / generator for use with SMIL formatted messages.
-UID Unique Identifier, a 32 bit number allocated from a registry owned by Symbian
-IPC Inter Process Communication
-MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
-MTM Registry A list of currently installed MTMs maintained by the message server.
-TLS Transport Layer Security, provides encryption of a TCP/IP socket.
-M-HTML Standard for including HTML in MIME email messages see http://www.ietf.org/rfc/rfc2557.txt
-MIME Specification for the format of email message bodies see http://www.ietf.org/rfc/rfc1341.txt
-RFC2822 The standard format for internet mail messages see http://www.ietf.org/rfc/rfc0822.txt
-SMTP Simple Mail Transport Protocol
-SID Secure Identification
-IMAP4 Internet Mail Access Protocol
-POP3 Post Office Protocol Version 3
-NBS Narrow Band Socket, in the messaging context this refers to the socket that is used to talk to the SMS stack for receiving and sending SMS messages
-SMS Short Message Service
-MMS Multimedia Message Service
-WAP Wireless Application Protocol
-WSP WAP Session Protocol
-HTTP Hypertext transfer protocol
-PDU Protocol Data Unit. This is the encoded form of SMS and MMS messages.
-Versit A consortium that defined standard formats for things like contacts (vCard) and calendar entries (vCals)
-SDP Service Discovery Protocol. A Bluetooth protocol that allows an applications to discover which services are available and to determine the characteristics of the services.
-SMIL Synchronized Multimedia Integration Language. Presentation language that is commonly used to define the contents of an MMS message.
-XML Extensible Mark-up Language
-DOM Document Object Model
-DTD Document Type Definition, a schema that defines the structure of an XML document.
-ESTORE Symbian OS component that provides stream based storage. Messaging uses the Permanent file store provided by ESTORE to store its index entries.
-Appendix A - Example Sequence Diagrams
-A.1 Copy to a Remote Service
-
-Figure 33 Sequence Diagram Showing Copying to a Remote Service
-Figure 33 shows a client copying a message to a remote service using the Messaging Client API. The message server then delegates the copy to the SMTP Server MTM. The Server MTM interprets the request as a request to send the message so it opens a connection to a remote SMTP server and sends the message. While the message is being sent the client can retrieve progress information from the CMsvOperation object that was returned by CMsvEntry::CopyL. The dark grey IPC line represents the split between the objects running in the client’s process space on the left and the message server’s process on the right.
-There are four basic steps:
-1. The client opens session with Message Server and creates a CMsvEntry set on the global outbox,
-2. The client then requests an asynchronous copy from the outbox to the SMTP service, a CMsvOperation object is returned. The message server loads the SMTP Server MTM and delegates the copy operation to it.
-3. The client requests progress from the CMsvOperation object, this request is passed through to the SMTP Server MTM. The client may repeat this step multiple times.
-4. The Server MTM finishes sending message. It moves the message to sent folder and completes the message server’s request. The message server completes the CMsvOperation object, which requests the final progress from the message server. The server returns the final progress and deletes the Server MTM. The CMsvOperation then completes the client’s original request.
-This diagram hides all of the internal working of the SMTP Server MTM, for information on this see below.
-A.2 SMTP Session
-
-Figure 34 Sequence Diagram Showing a SMTP Session
-Figure 34 shows the operation of the SMTP Server MTM after a request has come from the message server to copy a message to the SMTP service.
-1. SMTP Server MTM gets the request from the message server, it will build a selection of messages consisting of the union of the selection of messages passed in and the messages in the outbox that are associated with this SMTP service and are ready to be sent. The chain of classes are constructed, and a request is passed to networking to connect to the remote SMTP server, details of the server name and port are retrieved from the settings stored in the SMTP service entry.
-2. The component waits for the SMTP server to respond with a greeting indicating it is willing to talk, then sends EHLO to the server and waits for the response detailing the capabilities of the Server. After this step there could set steps to start using TLS and or SMTP AUTH depending on the SMTP settings.
-3. CImSmtpSession calls back into CMsgOutboxSend to retrieve the next message to be sent, then constructs a CImSmtpFile object to handle sending, for details on the sending see SMTP Email Send. When sending the email has completed the CImSmtpFile object is deleted.
-4. CImSmtpSession calls back into CMsgOutboxSend to retrieve the next message which returns saying there are no more messages. CImSmtpSession sends QUIT to the SMTP server and completes CMsgOutboxSend. CMsgOutboxSend deletes CImSmtpSession which tears down the connection to the SMTP server; it then completes the SMTP Server MTM. The Server MTM will then complete the message server and be deleted.
-A.3 SMTP Email Send
-
-Figure 35 Sequence Diagram Showing SMTP Transactions during Email Send.
-Figure 35 shows a CImSmtpFile object sending an email message to an SMTP server.
-1. Construct a CImSendMessage object, part of the imut component. Reset the SMTP Server
-2. Read address information from the CImHeader object stored in the message store, send address information to SMTP server.
-3. Use CImSendMessage object to read the message from the message store and generate RFC2822 message line by line. Send each line to the server as it is generated.
-4. Complete and send the message by sending a full stop to the SMTP server
-
-
Messaging Symbian OS v7.0s, v8.0, v8.1, v9.0, v9.1 Architectural Description
@@ -1973,15 +955,15 @@
Message Editor Application for creating or editing a message
Message Server Symbian OS Server that handles request to modify the Message Store
Message Store Store of messages and related information kept in the file system on a Symbian OS device.
-Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
-Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
+Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
+Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
Global Inbox A standard folder under the local service which is used to store incoming messages like SMS MMS etc. as opposed to an IMAP4 Inbox which would be under an IMAP4 service and is a representation of the Inbox on an IMAP4 email server.
Central Repository centralised and secure storage facility for application settings
OBEX Object exchange protocol, used to send objects such as vCards or files between devices via infrared or Bluetooth.
GMXML XML parser / generator for use with SMIL formatted messages.
UID Unique Identifier, a 32 bit number allocated from a registry owned by Symbian
IPC Inter Process Communication
-MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
+MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
MTM Registry A list of currently installed MTMs maintained by the message server.
TLS Transport Layer Security, provides encryption of a TCP/IP socket.
M-HTML Standard for including HTML in MIME email messages see http://www.ietf.org/rfc/rfc2557.txt
@@ -2991,15 +1973,15 @@
Message Editor Application for creating or editing a message
Message Server Symbian OS Server that handles request to modify the Message Store
Message Store Store of messages and related information kept in the file system on a Symbian OS device.
-Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
-Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
+Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
+Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
Global Inbox A standard folder under the local service which is used to store incoming messages like SMS MMS etc. as opposed to an IMAP4 Inbox which would be under an IMAP4 service and is a representation of the Inbox on an IMAP4 email server.
Central Repository centralised and secure storage facility for application settings
OBEX Object exchange protocol, used to send objects such as vCards or files between devices via infrared or Bluetooth.
GMXML XML parser / generator for use with SMIL formatted messages.
UID Unique Identifier, a 32 bit number allocated from a registry owned by Symbian
IPC Inter Process Communication
-MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
+MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
MTM Registry A list of currently installed MTMs maintained by the message server.
TLS Transport Layer Security, provides encryption of a TCP/IP socket.
M-HTML Standard for including HTML in MIME email messages see http://www.ietf.org/rfc/rfc2557.txt
@@ -4009,15 +2991,15 @@
Message Editor Application for creating or editing a message
Message Server Symbian OS Server that handles request to modify the Message Store
Message Store Store of messages and related information kept in the file system on a Symbian OS device.
-Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
-Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
+Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
+Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
Global Inbox A standard folder under the local service which is used to store incoming messages like SMS MMS etc. as opposed to an IMAP4 Inbox which would be under an IMAP4 service and is a representation of the Inbox on an IMAP4 email server.
Central Repository centralised and secure storage facility for application settings
OBEX Object exchange protocol, used to send objects such as vCards or files between devices via infrared or Bluetooth.
GMXML XML parser / generator for use with SMIL formatted messages.
UID Unique Identifier, a 32 bit number allocated from a registry owned by Symbian
IPC Inter Process Communication
-MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
+MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
MTM Registry A list of currently installed MTMs maintained by the message server.
TLS Transport Layer Security, provides encryption of a TCP/IP socket.
M-HTML Standard for including HTML in MIME email messages see http://www.ietf.org/rfc/rfc2557.txt
@@ -5027,1033 +4009,15 @@
Message Editor Application for creating or editing a message
Message Server Symbian OS Server that handles request to modify the Message Store
Message Store Store of messages and related information kept in the file system on a Symbian OS device.
-Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
-Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
+Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
+Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
Global Inbox A standard folder under the local service which is used to store incoming messages like SMS MMS etc. as opposed to an IMAP4 Inbox which would be under an IMAP4 service and is a representation of the Inbox on an IMAP4 email server.
Central Repository centralised and secure storage facility for application settings
OBEX Object exchange protocol, used to send objects such as vCards or files between devices via infrared or Bluetooth.
GMXML XML parser / generator for use with SMIL formatted messages.
UID Unique Identifier, a 32 bit number allocated from a registry owned by Symbian
IPC Inter Process Communication
-MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
-MTM Registry A list of currently installed MTMs maintained by the message server.
-TLS Transport Layer Security, provides encryption of a TCP/IP socket.
-M-HTML Standard for including HTML in MIME email messages see http://www.ietf.org/rfc/rfc2557.txt
-MIME Specification for the format of email message bodies see http://www.ietf.org/rfc/rfc1341.txt
-RFC2822 The standard format for internet mail messages see http://www.ietf.org/rfc/rfc0822.txt
-SMTP Simple Mail Transport Protocol
-SID Secure Identification
-IMAP4 Internet Mail Access Protocol
-POP3 Post Office Protocol Version 3
-NBS Narrow Band Socket, in the messaging context this refers to the socket that is used to talk to the SMS stack for receiving and sending SMS messages
-SMS Short Message Service
-MMS Multimedia Message Service
-WAP Wireless Application Protocol
-WSP WAP Session Protocol
-HTTP Hypertext transfer protocol
-PDU Protocol Data Unit. This is the encoded form of SMS and MMS messages.
-Versit A consortium that defined standard formats for things like contacts (vCard) and calendar entries (vCals)
-SDP Service Discovery Protocol. A Bluetooth protocol that allows an applications to discover which services are available and to determine the characteristics of the services.
-SMIL Synchronized Multimedia Integration Language. Presentation language that is commonly used to define the contents of an MMS message.
-XML Extensible Mark-up Language
-DOM Document Object Model
-DTD Document Type Definition, a schema that defines the structure of an XML document.
-ESTORE Symbian OS component that provides stream based storage. Messaging uses the Permanent file store provided by ESTORE to store its index entries.
-Appendix A - Example Sequence Diagrams
-A.1 Copy to a Remote Service
-
-Figure 33 Sequence Diagram Showing Copying to a Remote Service
-Figure 33 shows a client copying a message to a remote service using the Messaging Client API. The message server then delegates the copy to the SMTP Server MTM. The Server MTM interprets the request as a request to send the message so it opens a connection to a remote SMTP server and sends the message. While the message is being sent the client can retrieve progress information from the CMsvOperation object that was returned by CMsvEntry::CopyL. The dark grey IPC line represents the split between the objects running in the client’s process space on the left and the message server’s process on the right.
-There are four basic steps:
-1. The client opens session with Message Server and creates a CMsvEntry set on the global outbox,
-2. The client then requests an asynchronous copy from the outbox to the SMTP service, a CMsvOperation object is returned. The message server loads the SMTP Server MTM and delegates the copy operation to it.
-3. The client requests progress from the CMsvOperation object, this request is passed through to the SMTP Server MTM. The client may repeat this step multiple times.
-4. The Server MTM finishes sending message. It moves the message to sent folder and completes the message server’s request. The message server completes the CMsvOperation object, which requests the final progress from the message server. The server returns the final progress and deletes the Server MTM. The CMsvOperation then completes the client’s original request.
-This diagram hides all of the internal working of the SMTP Server MTM, for information on this see below.
-A.2 SMTP Session
-
-Figure 34 Sequence Diagram Showing a SMTP Session
-Figure 34 shows the operation of the SMTP Server MTM after a request has come from the message server to copy a message to the SMTP service.
-1. SMTP Server MTM gets the request from the message server, it will build a selection of messages consisting of the union of the selection of messages passed in and the messages in the outbox that are associated with this SMTP service and are ready to be sent. The chain of classes are constructed, and a request is passed to networking to connect to the remote SMTP server, details of the server name and port are retrieved from the settings stored in the SMTP service entry.
-2. The component waits for the SMTP server to respond with a greeting indicating it is willing to talk, then sends EHLO to the server and waits for the response detailing the capabilities of the Server. After this step there could set steps to start using TLS and or SMTP AUTH depending on the SMTP settings.
-3. CImSmtpSession calls back into CMsgOutboxSend to retrieve the next message to be sent, then constructs a CImSmtpFile object to handle sending, for details on the sending see SMTP Email Send. When sending the email has completed the CImSmtpFile object is deleted.
-4. CImSmtpSession calls back into CMsgOutboxSend to retrieve the next message which returns saying there are no more messages. CImSmtpSession sends QUIT to the SMTP server and completes CMsgOutboxSend. CMsgOutboxSend deletes CImSmtpSession which tears down the connection to the SMTP server; it then completes the SMTP Server MTM. The Server MTM will then complete the message server and be deleted.
-A.3 SMTP Email Send
-
-Figure 35 Sequence Diagram Showing SMTP Transactions during Email Send.
-Figure 35 shows a CImSmtpFile object sending an email message to an SMTP server.
-1. Construct a CImSendMessage object, part of the imut component. Reset the SMTP Server
-2. Read address information from the CImHeader object stored in the message store, send address information to SMTP server.
-3. Use CImSendMessage object to read the message from the message store and generate RFC2822 message line by line. Send each line to the server as it is generated.
-4. Complete and send the message by sending a full stop to the SMTP server
-
-
-
-
-Messaging Symbian OS v7.0s, v8.0, v8.1, v9.0, v9.1 Architectural Description
-
-Status: Issued
-Team/Department : Messaging / Content & Messaging
-
-Contents
-1 INTRODUCTION 6
-1.1 PURPOSE AND SCOPE 6
-2 SUBSYSTEM OVERVIEW AND BACKGROUND 6
-3 MESSAGING ARCHITECTURE AND APIS 7
-3.1 SUBSYSTEM COMPONENTS 7
-3.1.1 Framework components 7
-3.1.1.1 Message Server and MTM architecture 7
-3.1.1.2 Schedule Send 7
-3.1.1.3 SendAs Version 1 7
-3.1.1.4 SendAs Version 2 7
-3.1.1.5 Watcher Framework 8
-3.1.1.6 Message URL Handler 8
-3.1.1.7 Bio Message Framework 8
-3.1.2 Plug-ins 8
-3.1.2.1 SMS 8
-3.1.2.2 CDMA SMS 8
-3.1.2.3 Email 9
-3.1.2.4 OBEX 9
-3.1.2.5 MMS 9
-3.1.2.6 GMXML 10
-3.1.2.7 Bio Message Plug-ins 10
-3.1.2.8 PCMTM 10
-3.1.2.9 Fax 10
-3.2 GENERAL DESCRIPTION 11
-3.2.1 Messaging / Message Server and MTM Architecture APIs 11
-3.2.1.1 Key Internal Relationships and Dependencies 11
-3.2.1.2 Key External Relationships and Dependencies 12
-3.2.1.3 API Purpose - Further Elaboration 13
-3.2.1.3.1 Message Store 13
-3.2.1.3.2 Data File Storage (pre - v9.0) 15
-3.2.1.3.3 Platform Security Compliant Message Store 16
-3.2.1.3.4 How message centres display the message store 17
-3.2.1.3.5 Message Type Module Architecture 19
-3.2.1.3.6 Message Server Client API 21
-3.2.2 Messaging / Send As APIs 22
-3.2.2.1 Key Relationships and Dependencies 22
-3.2.2.2 API Purpose - Further Elaboration 22
-3.2.2.2.1 SendAs API (pre – v9.0) 22
-3.2.3 Platform Security Compliant SendAs Server (v9.0 onwards) 23
-3.2.4 Messaging / Schedule Send APIs 24
-3.2.4.1 Key Relationships and Dependencies 24
-3.2.4.2 API Purpose - Further Elaboration 24
-3.2.4.2.1 Schedule Send 24
-3.2.5 Messaging / Watchers APIs 25
-3.2.5.1 Key Relationships and Dependencies 25
-3.2.5.2 API Purpose - Further Elaboration 25
-3.2.6 Messaging / Message URL Handler APIs 26
-3.2.6.1 Key Relationships and Dependencies 26
-3.2.6.2 API Purpose - Further Elaboration 26
-3.2.6.2.1 Message URL Handler Application 26
-3.2.6.2.2 Message URL Recognisers 27
-3.2.7 Messaging / SMS APIs 27
-3.2.7.1 Key Internal Relationships and Dependencies 27
-3.2.7.2 Key External Relationships and Dependencies 28
-3.2.7.3 API Purpose - Further Elaboration 28
-3.2.7.3.1 SMS Watchers 28
-3.2.7.3.2 SMS Client MTM 29
-3.2.7.3.3 SMS Utilities 29
-3.2.7.3.4 SMS Server MTM 30
-3.2.8 Messaging / CDMA SMS APIs 31
-3.2.8.1 Key Internal Relationships and Dependencies 31
-3.2.8.2 Key External Relationships and Dependencies 32
-3.2.8.3 API Purpose - Further Elaboration 32
-3.2.8.3.1 CDMA SMS Watchers 32
-3.2.8.3.2 CDMA SMS Client MTM 33
-3.2.8.3.3 CDMA SMS Utilities 33
-3.2.8.3.4 CDMA SMS Server MTM 33
-3.2.8.3.5 Configuration for using CDMA SMS MTM 34
-3.2.9 Messaging / Email APIs 35
-3.2.9.1 Key Internal Relationships and Dependencies 35
-3.2.9.2 Key External Relationships and Dependencies 36
-3.2.9.3 API Purpose - Further Elaboration 36
-3.2.9.3.1 Email Overview 36
-3.2.9.3.2 Email Client Utilities 37
-3.2.9.3.3 Email Server MTM Utilities 37
-3.2.9.3.4 POP3 MTMs 37
-3.2.9.3.5 IMAP4 MTMs 38
-3.2.9.3.6 SMTP MTMs 40
-3.2.9.3.7 Autosend 40
-3.2.10 Messaging / MMS APIs 40
-3.2.10.1 Key Internal Relationships and Dependencies 41
-3.2.10.2 API Purpose - Further Elaboration 41
-3.2.10.2.1 MMS Overview 41
-3.2.10.2.2 MMS Utilities 42
-3.2.10.2.3 MMS Watcher 43
-3.2.10.2.4 MMS Client MTM 43
-3.2.10.2.5 MMS Server MTM 44
-3.2.10.2.6 MMS Codec 45
-3.2.11 Messaging / BIO APIs 46
-3.2.11.1 Key Internal Relationships and Dependencies 46
-3.2.11.2 API Purpose - Further Elaboration 47
-3.2.11.2.1 BIO Overview 47
-3.2.11.2.2 BIO MTM 47
-3.2.11.2.3 BIO Database 48
-3.2.11.2.4 BIO Parsers 48
-3.2.11.2.5 BIF Files and Utilities 48
-3.2.11.2.6 Platform Security Compliant Messaging / BIO APIs 49
-3.2.12 Messaging / OBEX MTM APIs 50
-3.2.12.1 Key Internal Relationships and Dependencies 50
-3.2.12.2 OBEX MTM Overview 50
-3.2.12.2.1 OBEX MTM 50
-3.2.12.2.2 IR MTM 51
-3.2.12.2.3 Bluetooth MTM 51
-3.2.12.2.4 OBEX MTM Utils 52
-3.2.12.2.5 Platform Security Compliant Messaging / OBEX MTM APIs 52
-3.2.13 Messaging / GMXML APIs 52
-3.2.13.1 Key Relationships and Dependencies 52
-3.2.13.2 Overview 53
-3.2.13.2.1 GMXML DOM 53
-3.2.13.2.2 GMXML Parser and Composer 53
-3.2.13.2.3 GMXML SMIL DTD (Validator) 53
-4 SECURITY 54
-4.1 DATA CAGING 54
-4.2 BACKUP AND RESTORE 54
-4.3 CAPABILITY RANGES 54
-4.3.1 Capabilities granted to executables 54
-4.3.2 Capabilities granted to DLLs 55
-4.3.3 Capabilities required to use the subsystem 57
-5 FURTHER INFORMATION 59
-5.1 REFERENCES 59
-5.2 OPEN ISSUES 59
-5.3 GLOSSARY 60
-APPENDIX A - EXAMPLE SEQUENCE DIAGRAMS 62
-A.1 COPY TO A REMOTE SERVICE 62
-A.2 SMTP SESSION 64
-A.3 SMTP EMAIL SEND 66
-
-Table of Figures
-Figure 1 Where Messaging Lives 6
-Figure 2 MTM Relationships 11
-Figure 3 External Dependencies 12
-Figure 4 Message Store 13
-Figure 5 Series 60 Inbox List View 14
-Figure 6 Remote and Local Entries 14
-Figure 7 Email Message 15
-Figure 8 Series 60 Message Centre (Composed from 2 screen shots) 17
-Figure 9 UIQ Message Centre 18
-Figure 10 Messaging MTM Structure (light coloured components are part of messaging subsystem) 19
-Figure 11 Nokia 9210 Outbox List View 20
-Figure 12 SendAs Version 1 Dependencies 22
-Figure 13 SendAs Version 2 Dependencies 23
-Figure 14 Schedule Send Dependencies 24
-Figure 15 Watcher Dependencies 25
-Figure 16 Message URL Handler Dependencies 26
-Figure 17 SMS Internal Dependencies 27
-Figure 18 SMS External Dependencies 28
-Figure 19 CMDA SMS Internal Dependencies 31
-Figure 20 CDMA SMS External Dependencies 32
-Figure 19 Email Internal Dependencies 35
-Figure 20 Email External Dependencies 36
-Figure 21 MMS Internal Dependencies 41
-Figure 22 MMS Utilities External Dependencies 42
-Figure 23 MMS Watcher External Dependencies 43
-Figure 24 MMS Client MTM Dependencies 43
-Figure 25 MMS Server MTM Dependencies 44
-Figure 26 BIO Message Internal Dependencies 46
-Figure 27 Bio Parser External Dependencies 47
-Figure 26 BIO Message Dependencies (v9.0) 49
-Figure 28 OBEX Internal Dependencies 50
-Figure 29 OBEX External Dependencies 51
-Figure 30 IR MTM Dependencies 51
-Figure 31 Bluetooth MTM Dependencies 52
-Figure 32 GMXML Dependencies 52
-Figure 33 Sequence Diagram Showing Copying to a Remote Service 62
-Figure 34 Sequence Diagram Showing a SMTP Session 64
-Figure 35 Sequence Diagram Showing SMTP Transactions during Email Send. 66
-1 Introduction
-1.1 Purpose and Scope
-The Messaging Architectural Description details the architecture and APIs exposed by the Messaging Subsystem. This document does not attempt to list all functionality provided by the messaging subsystem. For details on the functionality provided and the specifications implemented by the messaging subsystem see the Messaging Functional Description [R1]. This document describes the general architecture of messaging subsystem. Information related to a particular release version is mentioned with relevant release number.
-2 Subsystem Overview and Background
-The Messaging Subsystem provides an application level API to handle the storage and transport of different message types. It sits between messaging applications and the lower level subsystems which messaging uses for storage and transmission of messages.
-
-Figure 1 Where Messaging Lives
-The message types that messaging currently supports are Email (POP3, IMAP4 & SMTP), SMS, MMS and OBEX. The set of supported message types is extensible at run time by the use of plug-in modules that are responsible for the transmission and storage of a particular message type. This means that the set of components shown communicating with the network cloud depend on the message types installed.
-3 Messaging Architecture and APIs
-3.1 Subsystem components
-The Messaging subsystem components can be split into two categories: those components that form the framework and those that plug into the framework to support specific message types. This section briefly describes each of the components, more detailed descriptions of the components and their dependencies can be found in later sections of this document.
-3.1.1 Framework components
-3.1.1.1 Message Server and MTM architecture
-The message server is the core component in the messaging subsystem. It provides the message store used to contain messages. The Message Type Module architecture also allows plug-ins to add support for new message types to the messaging subsystem.
-Component Description
-messaging\framework\serverexe Executable that links to the server component and starts the message server
-messaging\framework\server Contains classes that make up both the client and server side of the message server API.
-messaging\framework\mtmbase Base classes for the plug-ins that handle the various message types
-3.1.1.2 Schedule Send
-The Schedule Send component is an extension to the framework that provides support for scheduling of operations such as sending messages. Message type modules that wish to support this functionality can use these support components to implement scheduling. For example the SMS MTM uses this to allow scheduled sending of SMS messages.
-Component Description
-messaging\schedulesend\schedulesendmtm Base classes that handle functionality for message server plug-ins that wish to enable scheduling of sending messages.
-messaging\schedulesend\schedulesendexe Executable use to provide schedule send behaviour.
-3.1.1.3 SendAs Version 1
-This version of SendAs is supported in releases pre - v9.0. SendAs provides a high level API for applications that wish to include a “Send As” menu to allow users to send content via one of the message types supported by messaging. The application using the API does not have to be aware of the message type selected by the user. Note the API does not send the messages.
-Component Description
-messaging\sendas High level API to allow creation of messages.
-3.1.1.4 SendAs Version 2
-From v9.0 and onwards the SendAs has been replaced with client server architecture based SendAs server. The client server architecture enhances secured platform implementation. The SendAs server polices the client application. If it is not trusted with required capabilities the SendAs server will refuse the client access. The client MTM for the message type can send a message with user permission even if the client does not have the correct capabilities.
-Component Description
-messaging\sendAsV2 High level API to allow the creation and sending of messages
-
-3.1.1.5 Watcher Framework
-The watcher framework is a lightweight framework to allow plug-ins to wait on events. For example there is an SMS watcher that waits for incoming SMS messages and delivers them to the message store. The watcher framework will only load plug-ins from ROM.
-Component Description
-messaging\framework\watcher Executable that loads and runs watcher plug-ins.
-3.1.1.6 Message URL Handler
-Support for recognising messaging URLs (mailto:, sms:, fax:, mms:), and then launching an editor with a new message.
-Component Description
-messaging\urlhandler\urlhandler An application that parses the URLs and then creates a correctly addressed message and launches a message editor.
-messaging\urlhandler\recogniser Recognisers that map from the URL schemes to the mime types.
-3.1.1.7 Bio Message Framework
-The Bio Message Framework provides a framework that supports plug-ins to handle messages like vCards and Internet access point set-up messages.
-Component Description
-messaging\biomsg\BDB\BIODB Classes to maintain the database of bio registration files.
-messaging\biomsg\BIFU\BIFU Classes for reading and writing bio registration files
-messaging\biomsg\BIOC\BIOC Bio message client MTM, this is in the framework section as it forms part of the bio messaging framework it is also a plug-in to the messaging framework.
-messaging\biomsg\BIOS\BIOS Bio message server MTM, this is in the framework section as it forms part of the bio messaging framework it is also a plug-in to the messaging framework.
-3.1.2 Plug-ins
-3.1.2.1 SMS
-The SMS plug-ins provide application level support for the Short Message Service messages.
-Component Description
-messaging\biomsg\BioWatchers Plug-ins to the watcher framework to listen for SMS, WSP, and WDP messages and deliver them to the global inbox in the message store.
-messaging\sms\clientmtm A plug-in to the message server framework to provide a generic API for creation of SMS messages (SMS Client MTM & SMS utilities)
-messaging\sms\servermtm A plug-in to the message server framework to provide a generic API for sending of SMS messages (SMS Server MTM)
-3.1.2.2 CDMA SMS
-The CDMA SMS plug-ins provide application level support for the CDMA Short Message Service messages.
-Component Description
-messaging\biomsg\BioWatchersCdma Plug-ins to the watcher framework to listen for CDMA SMS messages and deliver them to the global inbox in the message store.
-messaging\sms\multimode\clientmtm A plug-in to the message server framework to provide a generic API for creation of CDMA SMS messages (CDMA SMS Client MTM)
-messaging\sms\multimode\servermtm A plug-in to the message server framework to provide a generic API for sending of CDMA SMS messages (CDMA SMS Server MTM)
-
-3.1.2.3 Email
-The email plug-ins provide support the POP3, IMAP4 and SMTP email protocols and support for parsing and generating plain test, MIME and M-HTML format email messages.
-Component Description
-messaging\email\clientmtms A plug-in to the message server framework to provide a generic API for creation of email messages (IMAP4 SMTP and POP3 Client MTMs & email utilities)
-messaging\email\imapservermtm A plug-in to the message server framework to provide a generic API for access to a remote IMAP4 server (IMAP4 Server MTM)
-messaging\email\smtpservermtm A plug-in to the message server framework to provide a generic API for access to a remote SMTP server (SMTP Server MTM)
-messaging\email\popservermtm A plug-in to the message server framework to provide generic API for access to remote POP3 server (POP3 Server MTM)
-messaging\email\servermtmutils Email utilities for parsing plain text and MIME email messages. It also provides an abstraction of the TCP/IP sockets for use by the SMTP POP3 and IMAP4 plug-ins.
-messaging\email\autosend An executable that requests SMTP Server MTM to send messages in the outbox. This is used to provide send on next connection functionality and is started by the POP3 and IMAP4 Client MTMs.
-3.1.2.4 OBEX
-The OBEX MTM is a set of plug-ins to the message server that provides support for IR and Bluetooth beaming.
-Component Description
-messaging\obex\btmtm\btclient\group\btcmtm Bluetooth Client MTM
-messaging\obex\btmtm\btserver\group\btsmtm Bluetooth Server MTM
-messaging\obex\irmtm\irclient\group\ircmtm IR Client MTM
-messaging\obex\irmtm\irserver\group\IRSMTM IR Server MTM
-messaging\obex\obexmtm\obexclient\group\obexClientMtm OBEX Client MTM, base classes for the Bluetooth and IR Client MTMs
-messaging\obex\obexmtm\obexserver\group\obexServerMtm OBEX Server MTM, base classes for the Bluetooth and IR Server MTMs
-messaging\obex\obexmtm\obexutil\group\obexMtmUtil OBEX MTM utilities
-3.1.2.5 MMS
-The MMS MTM is a plug-in to the message server that provides support for MMS messages. From v9.0 and onwards MMS MTM and related components are removed.
-Component Description
-messaging\mms\utils MMS Utilities
-messaging\mms\servermtm MMS Server MTM
-messaging\mms\mmswatcherplugins MMS plug-ins to WAP push framework to handle reception of MMS notifications
-messaging\mms\codec MMS utilities for handling MMS codecs
-messaging\mms\clientmtm MMS Client MTM
-3.1.2.6 GMXML
-GMXML is a parser/generator for SMIL presentations for MMS messages.
-Component Description
-messaging\GMXML\XMLParser XML parser designed for parsing of SMIL messages
-messaging\GMXML\XMLDom XML document object model designed for parsing of SMIL messages
-messaging\GMXML\SMILdtd SMIL DTD
-3.1.2.7 Bio Message Plug-ins
-These parsers plug into the bio messaging framework to handle specific types of bio message.
-Component Description
-messaging\biomsg\cbcp\CBCP Compact business card parser
-messaging\biomsg\enp\ENP Email notification parser
-messaging\biomsg\gfp\gfp General file parser
-messaging\biomsg\iacp\IACP Nokia Smart Message Internet Access Parser
-messaging\biomsg\wapp\wapp Nokia/Ericsson OTA Parser
-3.1.2.8 PCMTM
-Plug-in to the message server that provided email synchronisation with a PC. This component has been deprecated in 8.0a and will not been documented in the API section below.
-3.1.2.9 Fax
-Plug-in to the message server that provides fax support. This component has been deprecated in 8.0a and will not been documented in the API section below.
-
-3.2 General Description
-3.2.1 Messaging / Message Server and MTM Architecture APIs
-3.2.1.1 Key Internal Relationships and Dependencies
-
-Figure 2 MTM Relationships
-Figure 2 shows the relationship between the Message Server and the MTM plug-ins. The grey classes are realisations of the MTM interfaces defined by the messaging framework. The message server depends on the Server MTM interface. Messaging Clients depend on the Client, UI and UI Data MTM interfaces and the Message Server Client API.
-3.2.1.2 Key External Relationships and Dependencies
-
-Figure 3 External Dependencies
-The grey package representing the messaging client depends on the Client, UI and UI Data interfaces and the Messaging Client API. The message server then depends on:
-• Charconv – Provides character set conversion routines, used to convert encoded message body text to Unicode body text.
-• EStore – Provides API to handle a stream based store used for the messaging index file and the framework classes for the message store files. (omitted from other dependency diagrams as it is implied by the dependency on the message server)
-• F32 – Provides the file server APIs used to access the file system directories in which messaging stores files containing message data. (omitted from other dependency diagrams)
-• BAFL – Provides API to load the correct messaging resource file dependent on the current language and to register the message store index file with the backup server. (omitted from other dependency diagrams)
-• ETEXT – Rich text APIs used to store body text of messages, this rich text format is a Symbian Proprietary format. (omitted from other dependency diagrams)
-• EUSER – Core Symbian OS utilities such as descriptors, arrays, client / server framework, cleanup stack and others (omitted from this and other dependency diagrams).
-• Central Repository – Centralised and secure storage facility for application settings, the message server stores message settings data in the central repository (from v9.0 and onwards).
-Note that debug only dependencies such as the flogger have been omitted from dependency diagrams.
-3.2.1.3 API Purpose - Further Elaboration
-3.2.1.3.1 Message Store
-The message server provides persistent storage of messages and messaging account settings. It does this by providing a message store consisting of a tree of message entries. Multiple clients can access the message store simultaneously. Each entry in the tree can represent an email account, folder of messages, message part, etc.
-
-Figure 4 Message Store
-Figure 4 shows an example message store. The tree is broken down in to three levels:
-1. The Root entry. This entry is just present to tie the tree structure together
-2. Service entries. There is one local service under which local folders and messages are stored, and zero or more remote services. Remote services represent message accounts.
-3. Message & Folder entries. Messages and folders, under the local service represent messages stored on the device. Messages and folders under remote services represent a local copy of messages that are present on a remote server. For example under a POP3 email service you would have copies of all the messages present on the POP3 email server, or under an SMS service you might find SMS messages that are stored on a SIM.
-The message server controls access to the entries in the store. It enforces the three levels therefore attempts to create message or folder entries directly under the root entry will fail.
-The message server provides three types of storage for each entry in the message store:
-• Index entry - TMsvEntry - intended to provide enough information for UI to display list views as shown in Figure 5. This consists of two strings and various flags (read, complete, has attachments etc).
-• Stream based file store - CMsvStore – provides storage of streams of data associated with UIDs. A standard UID is defined for storing body text. Other UIDs are specific. For example the email MTMs define a UID for storage of MIME headers. Compared to the index entry information this is used to store larger objects and is extensible, at the cost of being slower to access. From v9.0 and onwards CMsvStore provides an Attachment API for managing attachments. The Attachment API should be used as attachments can no longer be accessed directly due to Platform Security.
-• Directory of files – normally used for attachments.
-The only storage type that is always present is the index entry. The stream store and the directory of files are optional.
-
-Figure 5 Series 60 Inbox List View
-
-Figure 6 Remote and Local Entries
-As shown in Figure 6 the message store is split into two sets of entries:
-• Remote entries - entries that are representations of entries stored on a remote store .
-• Local entries - entries not linked to a remote store.
-The message server handles changes to local entries; internally it hands off changes to remote entries to the Server MTM that owns that service. Examples of operations that are handed off to Server MTMs are operations involving copying and moving messages to and from a remote service. See section 3.2.1.3.5 or more information on Server MTMs.
-Each entry within the store has a type:
-Folder – Messages can be grouped into folders. Standard folders such as inbox / outbox and user created folders.
-Message – Storage of the content of a message. Message entries can have child entries used to represent the structure of a message.
-Attachment – These represent attachments under a message entry.
-Root & Local Service Entry – There tie the tree structure together. However the Stream store associated with the root entry is sometimes used by UIs to store preferences e.g. default folder views etc.
-Remote Service - Represents a source and / or destination for messages. They are used to store the settings associated with the source / destination.
-Message Type Specific - MTMs can create other message types for use as child entries to messages they own. For example email uses a tree structure, with a message entry as the root, to represent the MIME structure of an email message; it uses folder entries to represent MIME folders and adds new types for entries representing the html body and text body parts of a message. This is shown in Figure 7.
-
-Figure 7 Email Message
-Using the message store to represent message structure allows reuse of the tree structure and makes it very simple to represent one message embedded in another. However this representation introduces performance issues as it results in each message having multiple files associated with it. The message server also keeps all index entries in memory; therefore this representation increases the memory footprint of the message server. Therefore when designing new MTMs we should think about moving away using multiple index entries to store one message in the message store.
-A default message store is created if the message server starts and no message store is present or a corrupt message store is present. The server will initially create a store with just a root entry, and then the server will create any standard folders defined in the resource file msgs.rsc. Finally the server will check whether an executable ‘mailinit.exe’ is present on the system, if it is present the server will launch the executable to allow customisation of the message store. The behaviour of ‘mailinit.exe’ is defined by the UI family of the device. However the typical behaviour is to load each of the UI Message Type Modules and allow each to perform any message type specific initialisation. For example the SMS plug-in typically creates a default service entry.
-
-3.2.1.3.2 Data File Storage (pre - v9.0)
-This section describes the files used by the message server before release v9.0. For information on the files used for release from v9.0 and onwards see section [3.2.1.3.3.1].
-Filename Access Purpose
-?:\system\Mail\index Private Message server index file, internal to message server
-?:\system\Mail\<8 hex digits> Shared via API Message server store files for services, clients access these via a messaging API.
-?:\system\Mail\<8 hex digits>.new Shared via API Temporary file used during committing message server store files.
-?:\SYSTEM\MAIL\<8 HEX DIGITS>_F\* Shared Files associated with a messaging service. These may be accessed directly by clients.
-?:\system\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits> Shared via API Message server store files for message entries, clients access these via a messaging API.
-?:\system\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits>.new Shared via API Temporary file used whilst committing message server store files.
-?:\system\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits>_F\* Shared Files associated with a message entry. These are accessed directly by clients.
-c:\system\data\msgs.ini Private Stores the drive containing the last used message store
-c:\system\Mtm\Mtm Registry v2 Private Cache of registered MTMs, internal to message server
-C:\system\data\sms_settings.dat Shared Copy of the SMS settings.
-?:\System\Mail\StoreInit.tmp Shared Created when message server runs ‘mailinit.exe’, ‘mailinit.exe’ should delete the file when it has successfully completed.
-?:\System\Mail\storedeleted.tmp Shared Created when message server finds and deletes a corrupt message store. Allows the UI to inform the user about the fact that the message store was corrupt.
-Files that are shown as private should only be accessed by the message server or by connectivity process for backup and restore purposes. Files listed as shared are accessed directly by messaging clients. Files listed as shared via API are accessed by client process but only via messaging APIs.
-3.2.1.3.3 Platform Security Compliant Message Store
-From v9.0 and onwards the message store is stored in the message server's data cage and the settings data are placed in the Central Repository. Access to the message store is only possible via message server APIs and not directly through file access. This leads to secured data storage and secured platform.
-3.2.1.3.3.1 Data caging
-Filename Purpose
-?:\private\<SID>\Mail\index Message server index file, internal to message server
-?:\ private\<SID>\Mail\<8 hex digits> Message server store files for services, clients access these via a messaging API.
-?:\ private\<SID>\Mail\<8 hex digits>.new Temporary file used during committing message server store files.
-?:\ private\<SID>\Mail\<8 hex digits>_F\* Files associated with a messaging service. These may be accessed directly by clients.
-?:\ private\<SID>\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits> Message server store files for message entries, clients access these via a messaging API.
-?:\ private\<SID>\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits>.new Temporary file used whilst committing message server store files.
-?:\ private\<SID>\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits>_F\* Files associated with a message entry. These are accessed directly by clients.
-c:\ private\<SID>\data\msgs.ini Stores the drive containing the last used message store
-c:\ private\<SID>\Mtm\Mtm Registry v2 Cache of registered MTMs, internal to message server
-?:\ private\<SID>\Mail\StoreInit.tmp Access via IPC call
-?:\ private\<SID>\Mail\storedeleted.tmp Created when message server finds and deletes a corrupt message store. Allows the UI to inform the user about the fact that the message store was corrupt.
-?\resource\messaging\bif\*.bif Registration data field with UID used in BIO framework
-
-3.2.1.3.4 How message centres display the message store
-The UI normally provides a Message Centre application to display the structure of the message store to the user. Different UIs map the structure to different views.
-
-Figure 8 Series 60 Message Centre (Composed from 2 screen shots)
-Figure 8 shows the top level view of the message centre application on a Series 60 phone. This shows that the message centre has hidden the local service and shows the standard folders at the same level as the services. Also the SMTP, SMS and MMS services are marked as hidden entries in the message store, and so do not appear in the message application.
-
-Figure 9 UIQ Message Centre
-However Figure 9 shows that the UIQ message centre has no 1-1 mapping from the structure in the message store to the structure shown to the user. Each of the message types is displayed as if its messages were contained in separate folders. Under each of these folders the user is presented with an inbox, outbox, send and drafts folder. This filtering is done in the UI layer as this functionality is not provided by the messaging API.
-3.2.1.3.5 Message Type Module Architecture
-
-Figure 10 Messaging MTM Structure (light coloured components are part of messaging subsystem)
-The MTM architecture is the plug-in scheme provided by the messaging framework to integrate different message transports into the message server. The plug-in scheme consists of four interfaces, the UI MTM, UI Data MTM, Client MTM and Server MTM. The messaging client applications loads and uses the first three which are loaded within the client’s process space. The final one the Server MTM is loaded within the message server process. The APIs for the client facing interfaces are extensible via run time type information provided by the QueryCapability API, and the InvokeAsyncFunction and InvokeSyncFunction APIs.
-3.2.1.3.5.1 UI MTM
-Handles requests from clients to view and edit messages or service settings. The MTM handles interaction with the message centre and as such the exact meaning of the APIs is defined by the UI. However common meanings are:
-• Create – Launches the editor with a new message.
-• Edit – If entry is a message this launches the editor; if entry is a service it edits the settings.
-• View – Launches the message viewer.
-• Display progress of an operation.
-3.2.1.3.5.2 UI data MTM
-This MTM provides fast access to UI components such as menu resources and bitmaps required by message centre for list views etc. Again the exact semantics are UI specific.
-There is a resource file defining UI specific functions, for example the Series 60 Messaging UI checks if the resource file contains text to display in the “New Message” menu.
-The UI data MTM also provides mapping from the message store’s TMsvEntry structure to Icons for the messaging list views and a status string, for example in the case of Nokia 9210 it is used in the outbox view to provide strings like “Resend 01:07” as shown in Figure 11. The class also provides functions to determine what operations are possible with a given entry. Examples of this are APIs that return whether the UI should allow the user to reply to the entry or to delete a service entry. The UI then uses this information to determine which menu options / short-cut keys should be allowed when the user selects a given entry.
-
-Figure 11 Nokia 9210 Outbox List View
-3.2.1.3.5.3 Client MTM
-Provides methods to create / reply and forward messages. Functions the Client MTMs provide are:
-• Create Message.
-• Reply to a Message.
-• Forward a Message.
-• Add / remove Addressees.
-• Add / remove body text.
-• Add / remove subject.
-• Add / remove attachments (the API cannot list attachments).
-The Client MTM interface is used by SendAs to provide a way of creating messages independently of the message type.
-3.2.1.3.5.4 Server MTM
-This is the final interface that makes up an MTM plug-in; it differs from the other three plug-ins in that it is loaded into the message server’s process space. The Server MTM provides access to messages under remote services. It handles connecting to remote servers to handle updating the local cache of these messages or to send messages copied to remote services when messages are copied to a remote service. The message server loads and hands off all message store operations that involve entries under a remote entry, these are the entries on the left-hand side of Figure 6.
-Functions that a Server MTM must implement:
-• Copy/MoveToLocal – called when the message server is asked to move or copy an entry that is currently under a remote service. A Server MTM might map this to retrieving a message from a remote mailbox.
-• Copy/MoveFromLocal – called when the message server is asked to move or copy from under the local service to a destination under a remote service. A Server MTM should map this to sending a message if the MTM supports sending.
-• Create, Delete, Change – called when the message server is asked to perform these operations on entries under a remote service.
-• StartCommand – this API provides a means of extending the API the Server MTM provides. Messaging clients pass a command ID and a selection of entries via the message server to the Server MTM. Examples of commands that Server MTMs might provide are: connect and synchronise the entries under a remote service with the messages on an email server, list SMS messages present on the phones SIM. These commands are MTM specific and therefore clients have to know which MTMs support which commands.
-3.2.1.3.5.5 MTM Registration
-MTMs must be registered with the message server so that clients can query what MTMs are present and the server knows which DLL to load to create a given MTM component. MTMs are registered by providing a resource file containing the MTMs UIDs, human readable name, and for each MTM interface it lists a DLL and the ordinal at which the constructor for that interface exists. The message server will search the ROM drive for MTM registration resource files on start-up and it will automatically register any MTMs found. For registration of MTMs installed on other drives, the message server provides an API to register and de-register an MTM. Registration will persist across a reboot, so an MTM only needs to be registered when it is installed on the system.
-When MTMs are registered or unregistered the message server will send events to all messaging clients with a message server session open.
-3.2.1.3.6 Message Server Client API
-The Messaging Server Client API breaks down into two categories: APIs for manipulation of the message store and utility APIs.
-3.2.1.3.6.1 Message Store manipulation APIs
-Requests from clients to modify the message store fall into three categories:
-1. Operations performed entirely with local entries (entries on the right-hand side of Figure 6) for example requests to create entries in the inbox, delete an entry from the drafts folder etc. The message server handles these operations directly.
-2. Operations that involve a remote entry (entries on the left-hand side of Figure 6) for example requests to delete an entry under a POP3 service, or copy a message to an SMTP service. The message server hands these operations off to the Server MTM that owns the service under which the remote entry is stored. The only exception to this rule is the ChangeAttributes API call. This modifies flags on an index entry and is handled by the message server for both local and remote entries. This means that a Server MTM can not rely on being called when flags like the Unread flag are changed. Note that operations can not involve two remote entries; therefore requests to copy entries between a remote service representing one POP3 account to a remote service representing another POP3 account will fail with an error.
-3. Requests that are explicitly directed at a Server MTM via the TransferCommand API. These commands are just passed to the correct Server MTM by looking up the Service ID and MTM of the first message in the selection passed into the command.
-The message server sends events when entries in the message store are modified to messaging clients that have a session open with the server.
-Where the API provides asynchronous functions to modify the message store or transfer a command to a Server MTM, the functions will return a message server operation object. This object can be used to request progress on operation or cancel the operation. Deleting the operation object returned, or closing the session used to make the request will result in the operation being cancelled, therefore a messaging client must remain running until operations it has requested have either completed or they will be cancelled. See appendix A.1 for an example of an asynchronous copy operation. If a Server MTM operating on the same remote service is already handling an operation, the message server will queue the new operation to be handled when the Server MTM becomes free. Requests for progress of operations that are queued will fail with KErrNotReady. The fact that the queue is based on the remote service ID means that you can have two Server MTMs of the same type running at the same time as long as they are operating on different services. So for example you can have two separate POP3 MTMs running synchronising different remote services with email servers.
-3.2.1.3.6.2 Utility APIs
-1. Access to MTM registries – These allow clients to construct instances of the interfaces an MTM implements.
-2. Register / Unregister an MTM.
-3. Change Drive – The message server closes the current message store and opens one on the drive specified. If no message store is present on the drive specified a new message store is created. The message sever can have only one mail store open at a time, if the current mail store is not available because a the disk the mail store is on is not present then the message server will switch the mail store back to the C: drive if an attempt is made to create a message in the inbox.
-4. Launching Editors – This launches the correct editor for a message. It is implemented by delegating the request to the UI MTM
-3.2.2 Messaging / Send As APIs
-3.2.2.1 Key Relationships and Dependencies
-
-Figure 12 SendAs Version 1 Dependencies
-SendAs version 1 and only present in releases before v9.0. SendAs uses the Messaging Client API to access the registry of Client MTMs and construct the Client MTM interfaces. The Client MTMs are then used for composing the message. SendAs requires clients to implement the MSendAsObserver interface. This interface is responsible for checking the return value of the capability queries made to Client MTMs that require a response and also for rendering message types that require it. The only message type supplied by Symbian that requires rendering is Fax, however this MTM has been removed in 8.0a and future releases.
-3.2.2.2 API Purpose - Further Elaboration
-3.2.2.2.1 SendAs API (pre – v9.0)
-The SendAs API makes use of the Client MTM interface and the Messaging Client API to provide a generic API for creating messages. Note despite the name of this component SendAs does not provide an API to send the message.
-SendAs builds a list of registered MTMs, then queries each MTM to check whether it supports sending, removing those MTMs from the list that do not support sending. This list is then provided to the messaging client application. At this point the application can add more constraints on the list of MTMs; for example it can insist the MTM supports Attachments or more than a certain size of body text. SendAs queries each of the MTMs about the requirements and will drop any MTMs from the list that does not meet them. When the application has finished adding requirements it selects one of the MTMs left in the list and uses that to compose the message, adding addresses, a subject, body text and attachments.
-SendAs supports setting a BIO Type for the message that is composed. This tells the transport that the body text represents a BIO Message. This is used when sending business cards from the contacts application as SMS messages; the contacts application puts the vCard data in the body text of the message and the transport sends it correctly. If the MTM in question supports attachments then the vCard is attached to the message.
-A new CSendAs object must be created for each message the application wishes to create.
-3.2.3 Platform Security Compliant SendAs Server (v9.0 onwards)
-
-Figure 13 SendAs Version 2 Dependencies
-From v9.0 and onwards the CSendAs has been replaced by the SendAs server component. The new SendAs server controls the access to the message store. Some of the key SendAs Server features are listed as follows.
-• Send a message once the capability policing of the client application has been completed.
-• Allow client applications to launch an editor for a specified message type.
-• Allow client applications to query the message type.
-The main client-side API is the RSendAs class. The client applications use this to connect to the Send-As server. The session object on the server-side is an instance of CSendAsSession.
-Client applications create messages using the RSendAsMessage API. Opening an RSendAsMessage object on Send-As server session creates a CSendAsMessage object in the Send-As server. There is a one-to-one mapping between an RSendAsMessage object and a CSendAsMessage object. This allows client applications to create multiple messages concurrently.
-
-3.2.4 Messaging / Schedule Send APIs
-3.2.4.1 Key Relationships and Dependencies
-
-Figure 14 Schedule Send Dependencies
-The Schedule Send Server MTM base class depends on the task scheduler to launch the schedule send executable at the correct time. To send the message with a package of data previously passed into the task scheduler by the Server MTM. The schedule send executable then uses the Messaging Client API to actually perform the requested operation.
-3.2.4.2 API Purpose - Further Elaboration
-3.2.4.2.1 Schedule Send
-The Schedule Send functionality is delivered by four components:
-Server MTM Base Class – The base class provides support to Server MTMs that wish to support scheduled operations.
-Data Structures – These are classes used to represent the data associated with a scheduled operation.
-Executable – The executable is run by the task scheduler at the scheduled time.
-The Task Scheduler – This component is part of the system libraries subsystem. Currently the SMS and Fax Server MTMs support scheduled sending.
-Clients request the Server MTM schedules operations via additional commands passed to TransferCommand API; this is passed to the Server MTM via the message server. The Server MTM packages the operation ID, a selection of message IDs, how often to poll for progress and an MTM specific buffer. It then passes this package of data to the task scheduler requesting that it launches the schedule send executable at the correct time with the packaged information.
-When the task scheduler launches the schedule send executable, it unpacks the schedule information and uses the Messaging Client API to request the Server MTM to perform the operation.
-Schedule Send supports a retry mechanism if the operation fails. The Server MTM has a resource file containing a mapping from the error codes the operation can fail with and actions to be performed. For example the SMS resource file has a mapping such that if the operation fails with an error code indicating a bad phone number the SMS will be set to failed and left in the outbox. Whereas if it fails with a error code indicating temporary network failure the send operation will be scheduled to be resent later with a maximum of three retries.
-3.2.5 Messaging / Watchers APIs
-3.2.5.1 Key Relationships and Dependencies
-
-Figure 15 Watcher Dependencies
-The watcher executable’s dependency on the message server is the result of a performance measure. The watcher process creates a message server session before initialising each of the watcher plug-ins and closes the session when it has finished. This keeps the message server running during initialisation avoiding starting and stopping the message server if each watcher plug-in opens and closes sessions.
-3.2.5.2 API Purpose - Further Elaboration
-The watcher framework consists of an executable that is launched when the device boots. The component that is responsible for launching it depends on the UI family. When the watcher.exe is launched it will load each DLL in z:\system\libs\watchers which has a second UID as KWatcherUid and calls the first DLL entry point to construct a CActive object.
-From v9.0 and onwards watcher DLLs are found by scanning the directory \resource\messaging\watchers for registry files. These files contain the name of a watcher DLL that can be loaded from ROM i.e. z:\sys\bin.
-The framework has retry behaviour if the first entry point leaves, in this case the watcher framework will start a timer and try and construct the watcher object 10 seconds later. Five attempts are made before the watcher plug-in is assumed to have failed completely. Once the watcher framework has constructed all the watchers it starts the active scheduler which should never exit.
-Watcher plug-ins typically make a request to another subsystem such that they will be completed when an external event like a fax line ringing or an SMS being received occurs. When the watcher has completed processing the request it will wait for the next event.
-No support for starting / stopping watchers is provided. This is a limitation that makes watchers unsuitable for operations like listening for messages beamed via IR, as the watcher should only run while the IR port is active.
-3.2.6 Messaging / Message URL Handler APIs
-3.2.6.1 Key Relationships and Dependencies
-
-Figure 16 Message URL Handler Dependencies
-3.2.6.2 API Purpose - Further Elaboration
-The Message URL Handler provides support for creating messages and launching messaging editors from URLs such as mailto:infobot@example.com?subject=current-issue. Note there is no dependency between the Message URL Handler application which processes the URLs and the Message URL Handler recognisers which maps from URLs to mime types.
-3.2.6.2.1 Message URL Handler Application
-This is a Symbian OS application that registers with the application framework that it can handle the mime types: x-epoc-url/fax, x-epoc-url/mailto and x-epoc-url/sms. When launched with a URL it will parse the URL to retrieve the address and other header fields and then use the SendAs API to create a new message with the correct address, headers etc. The application then uses the APIs in the MturUtils class provide by the mtmbase component in the messaging framework to launch the correct editor for the given message type. The application is marked as hidden and therefore should not be listed by UIs in application browsers.
-3.2.6.2.2 Message URL Recognisers
-This is a plug-in to the recogniser framework it will be called when the application framework wishes to recognise a file. Recognisers are called with the file name, in this case a URL, and a buffer containing the start of the file. The message URL recogniser compares the start of the URL with the URL schemes it recognises, if it finds a URL scheme it knows about it maps it to a mime type. The recogniser ignores the buffer passed in.
-Schemes recognised:
-Scheme Mime type
-mailto: X-Epoc-Url/mailto
-fax: X-Epoc-Url/fax
-sms: X-Epoc-Url/sms
-mms: X-Epoc-Url/mms
-See the application framework architectural description for more information on recognisers [R2].
-3.2.7 Messaging / SMS APIs
-3.2.7.1 Key Internal Relationships and Dependencies
-
-Figure 17 SMS Internal Dependencies
-3.2.7.2 Key External Relationships and Dependencies
-
-Figure 18 SMS External Dependencies
-3.2.7.3 API Purpose - Further Elaboration
-3.2.7.3.1 SMS Watchers
-The SMS watchers are made up of two watchers, the nbswatcher.dll and the wapwatcher.dll, and some common base classes in biowatcher.dll. The watchers listen for incoming messages from the SMS stack, part of the nbsprotocols subsystem [R3], and the WAP stack part of the WAP-Stack subsystem [R4].
-3.2.7.3.1.1 NBS Watcher
-The NBS watcher handles reception of SMS messages. When initialised by the watcher framework (see section 3.2.4) the watcher queries the bio messaging database for bio messages that are listed as having a type of ENbs. For each of these bio messages the watcher creates an object that opens a connection to the SMS stack and waits for the particular message type. The message types are either defined by the port number the message will be received on or by a string to watch for at the start of the message. For example Internet Access Configuration Point messages are start with “//SIAP11” and vCards are received on port 226. Finally the watcher listens for all other messages received from the SMS stack.
-When the NBS Watcher receives a non-class 2 SMS message it creates a new entry under the global inbox in the message store. For class 2 messages the entry is created in the class 2 folder as defined by the SMS settings, this may also be the global inbox. The details field of the entry is used to store the phone number of the incoming message or the name of the sender if the watcher finds a match for the phone number in the contacts database. The description field is used to store the first N characters of the SMS message, where N is defined in the SMS settings, or for bio messages the description as retrieved from the bio database. Bio messages also have the BioType field set to the UID of the bio message as retrieved from the bio database. The CSmsHeader class, which is a wrapper around the CSmsMessage class provided by the nbprotocols subsystem [R3], is used to externalise the SMS message to the entry’s CMsvStore. The watcher also places a copy of the body text of the message in the rich text stream of the entry’s CMsvStore.
-The NBS Watcher is also responsible for handing special SMS types including:
-• Replace Type Messages – When the watcher receives a message of this type it will scan the folder the message would have been delivered to for messages that have a matching protocol ID and from address. For each of the messages it checks whether the time stamps from the service centre and discards the older message.
-• Message Indications – The watcher can listen for incoming message waiting indications. The CSmsSettings class defines whether the watcher will listen and whether it will deliver the messages to the inbox or discard them. If the watcher is configured to listen for messages then it will use the SMS utilities in the SMS Client MTM to decode the message to determine the notification type and number of messages, e.g. 3 Email messages waiting, the strings for these messages are in the smss.rss resource file.
-• Delivery Reports – As with Message Indications the watcher can be configured to listen for these and again the SMS utilities get a string from the smss.rss resource file to put in the description field.
-The NBS Watcher handles changes to the bio database using the observer mechanism provided by the bio message database to observe when bio message types are added or removed and starting or stopping the object watching for that bio message type.
-3.2.7.3.1.2 WAP Watcher
-The WAP watcher listens for incoming messages from the WAP stack using the WAP message API [R4]. To determine ports to use to listen for messages the watcher queries the bio message database for bio message types EWsp, EWspSecure, EWap, EWapSecure and registers as an observer of the bio database and so will listen for new bio message with these types as they are added. The watcher stores the messages in the global inbox tagged with the bio type listed in the bio message database.
-3.2.7.3.2 SMS Client MTM
-The SMS Client MTM implements the standard set of Client MTM APIs described in Client MTM. In addition it provides:
-• Access to the CSmsHeader object that is used to represent the SMS message.
-• Access to the SMS settings stored in the associated SMS service.
-• The APIs required by Send As to allow Send As to create SMS messages including setting the bio type of the message to allow clients of Send As to send bio messages such as vCards and vCals. The data of the bio message is stored in the body text of the SMS message.
-• Simple check for valid SMS addresses, and SMS address is considered valid if it contains at least one digit.
-• Reading and writing SIM parameters.
-3.2.7.3.3 SMS Utilities
-These provide:
-• Classes to represent and store SMS messages (CSmsHeader), and SMS settings (CSmsSettings, CSmsMessageSettings) and a SMS number (CSmsNumber).
-• The CSmsHeader class contains and allows clients to access the CSmsMessage class that the nbsprotocols subsystem provides. This contains the entire SMS message and not just the header.
-• Functions to generate descriptions and details fields to store with SMS messages, including decoding special messages such as message indication and status report messages, reading resource file for descriptions strings of special messages, using the contacts database to replace phone numbers with names.
-• API to validate a GSM number.
-• Find the TMsvId of the SMS service entry.
-3.2.7.3.4 SMS Server MTM
-3.2.7.3.4.1 Sending Messages
-The SMS Server MTM handles sending of SMS and WAP messages via the SMS stack and the WAP stack. To support this it implements the CopyFromLocal API inherited from the Server MTM base class. It implements this as sending SMS messages and moving successfully sent messages to the Sent folder. When sending the SMS message the Server MTM checks the bio type of the message and uses the bio database to check the transport type for the bio message. The MTM supports ENbs that is sent via the SMS stack and EWap, EWapSecure that are sent via the WAP stack. The MTM does not support EWsp or EWspSecure although the watchers do support receiving them.
-If a message fails to send, sending is retried according to the settings in the smss.rss resource file as described in the schedule send section 3.2.3.
-3.2.7.3.4.2 Scheduling Messages
-The SMS Server MTM implements scheduled sending API by sub-classing from the schedule send Server MTM (see section 3.2.3). It accepts requests from clients either via the SMS Client MTM InvokeAsync API or via the CMsvSession::TransferCommand API to schedule messages to be sent or to delete existing schedules. When it receives a request to schedule a message it packages up the command and uses the scheduled send functionality to request that the task scheduler ask it to send the messages at a future point in time.
-3.2.7.3.4.3 Phone Store
-The phone store is the name given to storage of SMS messages outside of the message store. In the case of GSM phones this is the SIM. The SMS Server MTM accepts requests from clients to copy/move messages to and from the SIM and delete messages from the SIM. For example when copying to the SIM it packages up the SMS message and passes it to the SMS stack with a request to write it to the SIM. If the class2 folder has been set in the SMS settings class then the Server MTM will copy the SMS message to the SIM and then update the SMS message in the message store with details of the slot on the SIM that has been used to store the SMS and the fact that it is stored on the SIM.
-3.2.7.3.4.4 SIM Parameters
-The Server MTM provides functions to read / write SIM parameters, again these requests are passed to the SMS stack to be processed.
-3.2.8 Messaging / CDMA SMS APIs
-3.2.8.1 Key Internal Relationships and Dependencies
-
-Figure 19 CMDA SMS Internal Dependencies
-3.2.8.2 Key External Relationships and Dependencies
-`
-Figure 20 CDMA SMS External Dependencies
-3.2.8.3 API Purpose - Further Elaboration
-3.2.8.3.1 CDMA SMS Watchers
-The CDMA SMS watchers are made up of six watchers, the cdmanbswatcher.dll, vmnwatcher.dll, wemtwatcher.dll, wmtwatcher.dll, wptwatcher.dll, and the wapwatcher.dll, and some base classes in biowatcher.dll and cdmasocketwatcher. While the WAP watcher is common for both GSM and CDMA, the other watchers: CDMA NBS watcher, VMN watcher, WEMT watcher, WMT watcher, and the WPT watcher are used for CDMA only. The watchers listen for incoming messages from the CDMA SMS stack, part of the nbsprotocols subsystem [R3], and the WAP stack part of the WAP-Stack subsystem [R4].
-3.2.8.3.1.1 CDMA NBS Watcher
-The CDMA NBS watcher is similar to the NBS watcher and it handles bio messages defined in bio database. The CSmsHeader class is extended to wrap around the CCdmaSmsMessage class provided by the nbprotocols subsystem [R3], and is used to externalise the CDMA SMS message.
-For handling special CDMA SMS type, the CDMA NBS watcher is responsible for handling Message Indications as described in section 3.2.7.3.1.1 NBS Watcher.
-3.2.8.3.1.2 WAP Watcher
-The GSM WAP watcher is used to handle CDMA WAP message as well. The WAP watcher listens for incoming messages from the WAP stack, which can listen from the CDMA SMS stack or GSM SMS stack as appropriate. See 3.2.7.3.1.2 for more info about WAP watcher.
-3.2.8.3.1.3 Other CDMA Watchers
-The VMN watcher, WEMT watcher, WMT watcher and WPT watcher are CDMA watchers that handle reception of CDMA SMS messages. All CDMA SMS messages are associated with a teleservice. Therefore, each of the CDMA watchers is responsible for handling one teleservice: VMN watcher handles VMN SMS messages, WEMT watcher handles WEMT SMS messages, WMT watcher handles WMT SMS messages, and WPT watcher handles WPT SMS messages. The CSmsHeader class is reused to externalise the CDMA SMS message.
-The CDMA watchers are also responsible for handling special SMS types including:
-• Duplicate Message – When the watcher receives a duplicate message, it will discard the duplicate message as defined by the CDMA service settings.
-• User Acknowledge – The watcher can listen for user acknowledgment message of its teleservice type.
-• Delivery Acknowledge – The watcher can listen for delivery acknowledgment message of its teleservice type.
-• Read Acknowledge – The watcher can listen for read acknowledgment message of its teleservice type.
-3.2.8.3.2 CDMA SMS Client MTM
-The CDMA SMS Client MTM implements the standard set of Client MTM APIs described in Client MTM. In addition it provides:
-• Access to the CSmsHeader object that is used to represent the SMS message.
-• Access to the SMS settings stored in the associated SMS service. These settings are store in file store pre v9.0 but stored in Central Repository from v9.0 onwards.
-• The APIs required by Send As to allow Send As to create SMS messages including setting the bio type of the message to allow clients of Send As to send bio messages such as vCards and vCals. The data of the bio message is stored in the body text of the SMS message.
-• Simple check for valid SMS addresses, and SMS address is considered valid if it contains at least one digit.
-• Reading and writing SMS messages to R-UIM.
-3.2.8.3.3 CDMA SMS Utilities
-The CDMA version of SMS utilities are binary compatible with the GSM version of SMS utilities. But the classes that store SMS Message (CSMSHeader), and SMS settings (CSmsSettings, CSmsMessageSettings) and SMS number (CSmsNumber) are extended to store CDMA information. The CSmsHeader class is extended to contain and allow clients to access the CCdmaSmsMessage in addition to the CSmsMessage. Other functions provided by the GSM SMS Utilities is also provided by the CDMA version of SMS utilities, see 3.2.7.3.3 for information about GSM SMS Utilities.
-3.2.8.3.4 CDMA SMS Server MTM
-3.2.8.3.4.1 Sending Messages
-The CDMA SMS Server MTM handles sending of CDMA SMS and WAP messages via the CDMA SMS stack and the WAP stack. To support this it implements the CopyFromLocal API inherited from the Server MTM base class. It implements this as sending SMS messages and moving successfully sent messages to the Sent folder. When sending the CDMA SMS message the Server MTM will use the appropriate teleservice type. The MTM supports ENbs that is sent via the SMS stack and EWap, EWapSecure that are sent via the WAP stack. The MTM does not support EWsp or EWspSecure although the watchers do support receiving them.
-If a message fails to send, sending is retried according to the settings in the smss.rss resource file as described in the scheduled send section 3.2.4.
-3.2.8.3.4.2 Scheduling Messages
-The CDMA SMS Server MTM implements scheduled sending API by sub-classing from the schedule send Server MTM similar to implemented in the GSM SMS Server MTM. See 3.2.7.3.4.2 for more information.
-3.2.8.3.4.3 Phone Store
-In the case of CDMA phones, phone store can be phone-based storage or R-UIM based storage. The CDMA SMS Server MTM accepts requests from clients to copy/move messages to and from the phone/R-UIM and delete messages from the phone/R-UIM. For example when copying to the R-UIM it packages up the SMS message and passes it to the CDMA SMS stack with a request to write it to the R-UIM.
-3.2.8.3.5 Configuration for using CDMA SMS MTM
-The CDMA messaging components currently only support single mode, but it is designed such that it can become multimode in the future. Currently, -Dcdma option is used to for selecting CDMA mode for using emulator and building ROM.
-
-
-3.2.9 Messaging / Email APIs
-3.2.9.1 Key Internal Relationships and Dependencies
-
-Figure 19 Email Internal Dependencies
-
-3.2.9.2 Key External Relationships and Dependencies
-
-Figure 20 Email External Dependencies
-3.2.9.3 API Purpose - Further Elaboration
-3.2.9.3.1 Email Overview
-The Email plug-ins consist of a set of utilities and MTMs for POP3, IMAP4 and SMTP. For each email account a pair of services entries is created in the message store. For a POP3 account there will be an SMTP service and a POP3 service, for an IMAP4 account there will be an SMTP service and as IMAP4 service. These entries are used to store the settings for the email transport. Each of the service entries has its related ID set to the other member of the pair. The SMTP service is created invisible so the user only sees the POP3 or IMAP4 service entry, copying a message to the SMTP service will cause the SMTP Server MTM to attempt to send the message. The POP3 and IMAP4 MTMs provide functionality to synchronise with a remote email server this is achieved by extending the Client MTM interface via the InvokeAsync API. Synchronisation of a POP3 or IMAP4 account will result in copying headers and optionally body text and attachments from the email server and creating message entries under the POP3 or IMAP4 service entry.
-Email messages are represented in a common format whether they are being sent via SMTP or downloaded via POP3 or IMAP4. The email client utilities provide the classes for creating and manipulating the entry structure used to store emails. The email server side utilities provide classes to convert between the entry structure used to store emails in the message store and RFC2822 email messages sent to SMTP servers and retrieved from POP3 servers. IMAP4 email messages are parsed by the email server and the IMAP4 Server MTM requests and stores the individual parts of the messages.
-3.2.9.3.2 Email Client Utilities
-The email client utilities are part of the imcm DLL and provide classes for:
-• Storage of email messages including mime headers, RFC2822 headers, attachments, body text and encoding information in the message store
-• Manipulating email messages, for example adding attachments, replying etc.
-• To wrap up the character converters used to convert between standard character sets and Unicode. These make use of the charconv component that is part of the system libraries subsystem.
-• Storage of Email settings in the message store.
-• Progress information for email operations.
-The utilities are used directly by clients to access parts of email messages for display. CImEmailMessage provides the functionality used by clients displaying email messages, including listing attachments, getting body text and resolving URIs in M-HTML messages.
-The Email Client MTMs use the utilities when they are asked to create, reply to and forward messages CImEmailOperation provides the functionality to perform these operations. Each email message is represented by a parent message entry and then entries to represent mime folders and mime parts, see Figure 7 for an example, so adding or deleting mime parts involves walking the tree of entries and inserting / removing entries as appropriate.
-3.2.9.3.3 Email Server MTM Utilities
-The Email Server MTM Utilities are responsible for generating and parsing of RFC2822 format email messages and providing an API to wrap up a TCP/IP connection to a remote email server.
-• Parsing of RFC2822 Email Messages – The utilities provide an API that accepts the text of an RFC2822 email message a line at a time and stores the email message in messaging’s internal format for email messages. See the Email Client Utilities for details of this format. The API handles storing of RFC2822 headers, MIME headers, decoding of Base64 encoded or uuencoded attachments and decoding of text received in character sets supported by the charconv component. This API is only accessible to Server MTMs, as it requires classes that can only be instantiated while running within the message server process. See the Messaging Functional Specification [R1] for detail on which email specifications the utilities support.
-• Generation of RFC2822 Email Messages – The utilities provide an API to convert an email in messaging’s internal format into an RFC2822 email message. The API provides access to the RFC2822 text a line at a time for streaming to an SMTP server. The exact format of the email depends on the settings passed in; the API can generate plain RFC2822 email messages with uuencoded attachments, MIME email messages with Base64 encoded attachments, or M-HTML email messages with Base64 encoded attachments. See the Messaging Functional Specification [R1] for detail on which email specifications the utilities support.
-• TCP/IP socket wrapper – The utilities provide a class that abstracts a TCP/IP socket supplied by the networking subsystem into an API that supports sending and receiving lines of text to / from a remote server. This API is used to connect to remote email servers by each of the email Server MTMs. The API can either create insecure or secure sockets enabling the SSL encryption provided by the networking subsystem. It also supports changing an insecure socket into a secure socket, this enables the email Server MTMs to implement email protocols where the initial connection to the server is insecure and then a secure socket is negotiated before sending or requesting any sensitive information.
-3.2.9.3.4 POP3 MTMs
-The POP3 MTMs implements the functionality to synchronise the local message store with a remote POP3 email server.
-3.2.9.3.4.1 Client MTM
-The POP3 Client MTM implements the standard Client MTM APIs and other extensions:
-• Reply to, forward – These are accessible via the ReplyL and ForwardL APIs of a Client MTM and are implemented as calls to the email utilities class CImEmailOperation.
-• Reply to, forward, create new messages, create receipts and forward as attachment – These are accessible as commands available via the InvokeAsyncFunction API of the Client MTM, they are implemented as calls to CImEmailOperation.
-• Connecting, disconnecting and copying email while connected – These operations are accessible as commands available via the InvokeAsyncFunction API of the Client MTM, they are implemented as calls to the POP3 Server MTM.
-• Querying connection status – This command lets clients know whether the POP3 Server MTM is connected to an email server, and is available via the InvokeAsyncFunction API of the Client MTM. The Client MTM requests the information from the Server MTM.
-• Compound operations – The Client MTM provides functionality to wrap up connecting to email servers, copying / moving new messages or a selection of messages, and then optionally disconnecting. These commands are available via the InvokeAsyncFunction API of the Client MTM. The Client MTM implements this by using the CImPOP3GetMail class which requests the correct sequence of operations from the Server MTM, waiting for each operation to complete before requesting the next one.
-• Send on next connection If the Client MTM gets a request to connect to an email server it will check whether the POP3 settings. If send on next connection is requested it will launch the autosend.exe executable (see section 3.2.7.3.7) to handle sending messages waiting in the outbox.
-• Offline operations – The POP3 Client MTM has a command to cancel offline operations, this is available via the InvokeAsyncFunction API of the Client MTM. The Client MTM passes the request to the Server MTM.
-3.2.9.3.4.2 Server MTM
-The POP3 Server MTM handles the communication with the remote POP3 server and implementation of the POP3 protocol. The MTM uses CImTextServerSession to handle the communication with the email server and CImRecvConvert to parse the email messages downloaded, both are provided by the Email Server MTM Utilities.
-• Connect – The POP3 Server MTM will open a socket to the email server using CImTextServerSession and login user the username / password in the POP3 settings. After a successful connection the Server MTM will attempt to synchronise the current state of headers stored on the email server with the set stored in the message store and then start any pending offline operations. After the connect operation has completed the Server MTM will inform the message server that it is expecting more operations via the CommandExpected API and therefore the message server will not delete and unload the Server MTM.
-• Populate Message – The POP3 Server MTM treats requests to copy a message from and to the POP3 service as a request to download the full message.
-• Offline operations – When the POP3 Server MTM receives a request to copy, move, or delete and is not connected to a POP3 email server the Server MTM will store the operation in the CMsvStore of the entry being modified and perform the operation on the next connection to the email server.
-• Disconnect – When disconnecting from a remote email server the POP3 MTM will run any pending offline operations stored. After the disconnect operation completes the Server MTM will allow the message server to delete and unload the Server MTM by setting the CommandExpected API to false.
-3.2.9.3.5 IMAP4 MTMs
-The IMAP4 Server MTM implements the functionality to synchronise the local message store with a remote IMAP4 email server.
-3.2.9.3.5.1 Client MTM
-The IMAP4 Client MTM implements the standard Client MTM APIs and other extensions:
-• Connecting, disconnecting, synchronising, un/subscribing folders – These operations are accessible as commands available via the InvokeAsyncFunction API of the Client MTM, they are implemented as calls to the IMAP4 Server MTM.
-• Send on next connection – If the Client MTM gets a request to connect to an email server it will check whether the IMAP4 settings. If send on next connection is requested it will launch the autosend.exe executable (see section 3.2.7.3.7) to handle sending messages waiting in the outbox.
-• Reply to, and forward messages – These are accessible via the ReplyL and ForwardL APIs of a Client MTM and are implemented as calls to the email utilities class CImEmailOperation.
-• Reply to, forward, create new, create receipt, forward as attachment – These are accessible as commands available via the InvokeAsyncFunction API of the Client MTM, they are implemented as calls to CImEmailOperation.
-• Querying connection status – These commands let clients know whether the IMAP4 Server MTM is connected to an email server and whether it is currently processing a request. They are available via the InvokeAsyncFunction API of the Client MTM. The Client MTM requests the information from the Server MTM.
-• Compound Connection and synchronisation – The IMAP4 Client MTM provides a compound operation that connects and synchronises with an IMAP4 server. This operation is implemented as a client side object that combines requests to the IMAP4 Server MTM. The client side operation can complete the client request either after the connection, after the connection + sync or after the connection + sync + disconnect. The client will keep requesting that the inbox be resynchronised at a configurable interval so new messages received in the inbox on the server will appear under the IMAP4 inbox. The CImapConnectAndSyncOp class handles these compound operations.
-• Compound Connect and copy / move / populate messages – The IMAP4 Client MTM provides a compound operation that connects to an IMAP4 server and copies moves or populates messages. The implementation is provided by the CImImap4GetMail class which makes calls back into the IMAP4 Client MTM.
-• Offline operations – The IMAP4 Client MTM has a command to cancel offline operations, this is available via the InvokeAsyncFunction API of the Client MTM. The Client MTM passes the request to the Server MTM.
-3.2.9.3.5.2 Server MTM
-The IMAP4 Server MTM handles the communication with the remote IMAP4 server and implementation of the IMAP4 protocol. The MTM uses CImTextServerSession to handle the communication with the email server. The IMAP4 Server MTM opens two connections to the IMAP4 server this enables users to download messages while the Server MTM is performing a background synchronisation if requested by the Client MTM.
-• Connect – The IMAP4 Server MTM will open a socket to the email server using CImTextServerSession and login using the username / password in the IMAP4 settings. After a successful connection the Server MTM will optionally attempt to synchronise the current state of headers stored on the email server with the set stored in the message store and then start any pending offline operations. After the connect operation has completed the Server MTM will inform the message server that it is expecting more operations via the CommandExpected API and therefore the message server will not delete and unload the Server MTM.
-• Copy, Move messages – The IMAP4 Server MTM supports copying and moving messages between folders on the IMAP4 server and between the IMAP4 server and local folders.
-• Delete messages – The IMAP4 Server MTM will mark the email as deleted on the server; however it will not be deleted until the IMAP4 Server MTM disconnects from the server.
-• Folders – The IMAP4 Server MTM will allow folders to be subscribed, unsubscribed, renamed, copied, moved, and created within the IMAP4 service. Subscribing to a folder means that it will be visible to the user and synchronised with the remote server. The inbox is always subscribed.
-• Offline operations – When the IMAP4 Server MTM receives a request to copy, move, or delete and is not connected to an IMAP4 email server the Server MTM will store the operation in the CMsvStore of the entry being modified and perform the operation on the next connection to the email server.
-• Disconnect – When disconnecting from a remote email server the IMAP4 MTM will run any pending offline operations stored. After the disconnect operation completes the Server MTM will allow the message server to delete and unload the Server MTM by setting the CommandExpected API to false.
-
-3.2.9.3.6 SMTP MTMs
-The SMTP MTMs provide functionality to send email messages. They are made up of the Client MTM that is part of the imcm DLL and the Server MTM.
-3.2.9.3.6.1 Client MTM
-The SMTP Client MTM implements the standard Client MTM APIs including the functions required to allow clients of Send As to create email messages.
-3.2.9.3.6.2 Server MTM
-The SMTP MTMs provide functionality to send email messages; it interprets requests to copy entries to an SMTP service as a request to send those messages. In addition it responds to two extended commands via the StartCommand Server MTM interface. These commands are KSMTPMTMIsConnected that responds with whether the Server MTM is currently connected to a remote SMTP server and KSMTPMTMSendOnNextConnection which performs the same operation as copying a selection of messages to an SMTP service. The only difference between the copy operation and the KSMTPMTMSendOnNextConnection operation is that the latter can be called without a selection of messages.
-When the Server MTM receives a request to send messages it builds a selection of messages consisting of the messages passed into the operation and any messages waiting in the outbox to be sent. To determine which messages in the outbox are waiting to be sent the SMTP server checks for messages that have the same service ID as the destination of the send operation and have a sending state of KMsvSendStateWaiting, KMsvSendStateScheduled or KMsvSendStateResend. This means that any request to send messages may result in more messages being sent than explicitly listed in the selection passed to the send operation.
-The Server MTM restores its settings from the SMTP service it has been asked to copy the messages to. Then it connects to the SMTP server using the CImTextServerSession class in the Email Server MTM Utilities, passing in the SMTP server address and TCP/IP port number from the SMTP settings. Then for each message to be sent the Server MTM uses the Email Server MTM utilities to generate an RFC2822 format message to send to the SMTP server, the RFC2822 text is generated on the fly as the data is sent to the SMTP server. If the SMTP server accepts the message to be sent then the Server MTM moves the message to the sent folder and sets its sending state to sent. If the SMTP server rejects the message then the Server MTM leaves the message in the outbox and sets the sending state to failed. Separate emails are generated for BCC recipients to ensure that the SMTP server doesn’t incorrectly include BCC recipients in emails sent to addresses in the To and CC fields of the email.
-3.2.9.3.7 Autosend
-The Autosend component is an executable that is kicked off by the POP3 and IMAP4 Client MTMs if the send on next connection setting is set. This executable will just make a request to the SMTP Server MTM to send messages associated with the SMTP service related to the POP3 or IMAP4 service, wait for the operation to finish and then exit.
-3.2.10 Messaging / MMS APIs
-The MMS module has been removed from v9.0 and onwards.
-3.2.10.1 Key Internal Relationships and Dependencies
-
-Figure 21 MMS Internal Dependencies
-3.2.10.2 API Purpose - Further Elaboration
-3.2.10.2.1 MMS Overview
-The MMS MTM provides functionality for creating, accessing, sending and receiving MMS messages. Messages are sent and received without the client application needing to open or close any kind of session. The management of the MMS session is handled entirely within the MTM.
-MMS clients are alerted when a new message is available for download via the WAP Push mechanism. A WAP push watcher is provided to handle these notifications. After the notification the message can be downloaded over WSP or HTTP. Messages are sent by posting the data over WSP or HTTP. The Symbian MMS implementation can handle sending or receiving MMS message over either protocol.
-MMS messages are based on the MIME format but are binary encoded using WSP. Note that MMS messages are encoded in this way even if they are posted over HTTP as opposed to WSP. The codec component is responsible for this encoding and decoding.
-3.2.10.2.2 MMS Utilities
-3.2.10.2.2.1 Key External Relationships and Dependencies
-
-Figure 22 MMS Utilities External Dependencies
-The MMS utilities provide the message and settings encapsulation classes. The MMS settings and messages are stored in the message store, the MMS utilities provide the interfaces to access this data.
-3.2.10.2.2.2 Settings
-The settings functionality provided by the MMS utilities allows the messaging client to persist MMS settings in the message store. Supported settings include:
- MMSC (MMS server) address
- WSP or HTTP transport
- Autofetch messages on notification
- Preferred IAP for the MMS network connection
-The settings functionality is also used by the server MTM to retrieve the settings prior to message sending or fetching.
-3.2.10.2.2.3 Message Encapsulation
-The message classes provide the message access functionality. Messages can be created, stored, restored and read using these classes. Functionality includes:
- Adding media objects to the message
- Enumerating through media objects
- Adding recipients, subject line, etc. to a message
- Adding other headers to the message, e.g. expiry date
- Finding the appropriate media object for a given URI in the SMIL part (URI resolving)
-The message data is stored in the message store using one entry per message regardless of the number of media objects added to the message. This is preferable to using multiple message entries as it is faster and uses less disk space.
-Most of the message access code is common whether it is being used on the client or server side, however some parts of it are specific. For this reason it is essential that the appropriate client or server side CMmsMessage derived class is used.
-3.2.10.2.3 MMS Watcher
-3.2.10.2.3.1 Key External Relationships and Dependencies
-
-Figure 23 MMS Watcher External Dependencies
-
-The MMS watcher plug-in is responsible for intercepting incoming MMS notifications and delivery reports then taking the appropriate action. It is implemented as a WAP Push watcher plug-in.
-When an MMS notification is received an MMS entry is created in the inbox using the MMS utilities. At this point the entry has its incomplete flag set. If the settings have the autofetch option selected then the MMS watcher initiates the fetch operation via the MMS client MTM.
-If a delivery report is received then the delivered flag is set on the appropriate sent message. If an outgoing message was sent to several recipients then there will be several delivered flags. A delivery report from each recipient will set the appropriate delivered flag.
-3.2.10.2.4 MMS Client MTM
-3.2.10.2.4.1 Key External Relationships and Dependencies
-
-Figure 24 MMS Client MTM Dependencies
-As with most other MTMs the MMS client MTM provides access to the server MTM functionality for messaging clients. It also implements the Send-As interface and reply and forward functionality.
-3.2.10.2.4.2 Send-As Implementation
-The Client MTM Send-As interface is implemented in the MMS Client MTM. The implementation differs slightly from other MTMs because additional presentation content may be generated depending on the media objects that are added. When simple combinations of images, sounds and text are added a SMIL presentation is generated to link them together. This is preferable to simple adding the objects as attachments where some clients render them as a list of files and others fail to render them at all.
-The SMIL data is constructed using templates stored in resource files, the GMXML (SMIL) composer is not used.
-3.2.10.2.4.3 Reply / Forward
-The Client MTM can be used to create replies to received messages or to create forwarded responses. The reply and forwarding operations are performed asynchronously.
-3.2.10.2.5 MMS Server MTM
-3.2.10.2.5.1 Key External Relationships and Dependencies
-
-Figure 25 MMS Server MTM Dependencies
-The Server MTM is the most complicated part the MMS implementation. It handles all of the state information required to send or fetch MMS messages. It is also responsible for managing the HTTP or WSP session and the connections to the phone network.
-3.2.10.2.5.2 Operations
-All MMS server MTM functionality is encapsulated in operations. An operation consists of the setup of a session, the sending, fetching and acknowledgements when appropriate, it then closes the session. The messaging client initiates an operation with a single call to the Client MTM, there is no need for the messaging client to explicitly establish the session or to know about the internal states. However, these internal states are available to the messaging client via the progress structure if this level of user feedback is required.
-Two types of operation are supported, background and foreground:
-A maximum of one foreground operation can be running at any one time. The messaging client can poll the server MTM for the progress of a running foreground operation, likewise it can cancel it if necessary.
-A background operation does not support progress information and can not be cancelled by the messaging client. It is possible to initiate background operations even if other background or foreground operations are pending. However, background operations are queued and a maximum of one will actually be running at any one time.
-The MMS watcher uses a background operation to perform automatic fetching. While the background autofetch is occurring it is still possible to start a foreground operation (such as sending a message) if required.
-3.2.10.2.5.3 Session and Connection Management
-The server MTM uses the HTTP Transport Framework to enable the HTTP or WSP session. HTTP or WSP can be selected at runtime by selecting the appropriate option in the settings. The server MTM is responsible for reading any HTTP proxy details from the CommDB and passing it to the HTTP framework. See the http transport framework architectural description for more information on recognisers [R5]
-The server MTM is also responsible for managing the connection to the phone network. Connections are opened when required using the RConnection mechanism, multi-homing is supported provided that the underlying HTTP framework transport plug-in also supports it.
-3.2.10.2.6 MMS Codec
-The MMS Server MTM is in charge of the state transitions, connection, session, the actual posting and fetching of the data from them, however it does not encode or decode the MMS PDUs. The encoding and decoding is performed by the MMS Codec.
-For decoding the Server MTM passes the Codec the MMS PDU data in a descriptor for processing. If the PDU contains a received MMS message then the message entry is updated with the decoded MMS data.
-For encoding the Server MTM passes a reference to the message store entry containing the un-encoded MMS data. The Codec then encodes it and returns the PDU to the Server MTM in a descriptor.
-
-
-3.2.11 Messaging / BIO APIs
-3.2.11.1 Key Internal Relationships and Dependencies
-
-Figure 26 BIO Message Internal Dependencies
-3.2.11.1.1.1 Key External Relationships and Dependencies
-
-Figure 27 Bio Parser External Dependencies
-
-3.2.11.2 API Purpose - Further Elaboration
-3.2.11.2.1 BIO Overview
-The BIO messaging components have been designed to unify and simplify the way in which system messages are processed. In this context ‘system messages’ refers to messages received on the device which are intended to update some attribute(s) on the system as opposed to being presented to the user. Examples of these types of messages include vCards which are parsed and then displayed to the user and when accepted modify the users contact database and OTA configuration messages which are again parsed before display to the user and if accepted create email accounts or internet access points.
-The BIO messaging components can be broken down into three groups:
-1) The BIO MTM - To initiate the parsing and processing of BIO messages
-2) The BIO Database - Maps port numbers, MIME types, etc. to bio types in order to identify the type of incoming BIO messages.
-3) The BIO Parsers - To parse and process the BIO message payload
-BIO messages are not receive by the bio messaging framework, they come over other message transports for example see section 3.2.6.3.1 on the SMS watchers which describes how the SMS watchers receive bio messages and use the bio framework to tag the messages with the correct bio id.
-3.2.11.2.2 BIO MTM
-The BIO client MTM is called by the messaging client to parse or process a BIO message that has been saved in the message store. It is the responsibility of a BIO watcher to save the BIO message with the BIO flag and the appropriate BIO type set.
-The BIO client MTM does very little, its primary task is to pass on the messaging client request to the server MTM. Two operations are supported, parse and process.
-The messaging client is expected to initiate the parsing of the BIO message before processing it. The parsing step involves analysing the data and storing it in a form that can be displayed to the user via the BIO message viewer.
-Once the message has been parsed the messaging client can initiate the processing of the message.
-The BIO server MTM is responsible for deferring the parsing and processing to the appropriate BIO parser. The behaviour for the parsing and processing steps varies between parsers. See the BIO Parsers section for more information.
-The bio MTM does not support sending messages and therefore does not support reply / forwarding messages. For bio messages sending / reply etc. is supported by the particular MTM that the message is sent over, for example SMS.
-3.2.11.2.3 BIO Database
-The BIO database is used to identify the type of BIO messages. It maps message attributes such as port number, MIME type or leading string to a BIO type. These are attributes are then used by clients of the bio framework to know what ports to listen for messages on. For example the SMS watchers use the leading string to wait for SMS messages that start with that string and when storing those messages in the inbox tag them with the bio id associated with that leading string. See the SMS watcher section 3.2.6.3.1 for more examples of how the BIO database can be used.
-3.2.11.2.4 BIO Parsers
-The BIO parsers are plug-ins for parsing and processing incoming BIO messages. They are invoked by the BIO Server MTM depending on the BIO type of the message being processed. Each BIO parser implements two functions, ParseL and ProcessL. The level of functionality varies between parsers. Some parsers update the final repository with the received data, e.g. WAPP updates the CommDB with the received settings. Some parsers simply save the data in an unparsed state for processing by another component, this secondary parsing is not part of the BIO framework and must be initiated by the messaging client. An example is when GFP saves vCard data as a file as opposed to updating the contacts database, the UI must then invoke the Versit parser to parse the vCard and commit it to the contacts database.
-3.2.11.2.4.1 Generic File Parser (GFP)
-The generic file parser can be used to identify and save a variety of BIO data types, e.g. vCards and vCals. The Generic File Parser does not process the data, it simply saves it in the message store for processing by another component. The file is saved as an attachment of the message entry that was parsed.
-3.2.11.2.4.2 Nokia/Ericsson OTA Parser (WAPP)
-The WAPP parser decodes Nokia/Ericsson OTA messages and updates CommDB to reflect the received settings.
-3.2.11.2.4.3 Nokia Smart Message Internet Access Parser (IACP)
-The IACP parser decodes Nokia Smart Messages and updates the CommDB and messaging settings where appropriate.
-3.2.11.2.5 BIF Files and Utilities
-The BIF files encapsulate the information required for identifying BIO messages, these details may include the expected port number, MIME type or leading string. Different BIO watcher will use different information from these files, for an example see the 3.2.6.3.1. The information can be retrieved from the BIF files by using the BIF utilities. Generally BIO aware clients will access this information via the BIO database. BIF files are resource files previous to the v6.1 release they were binary files generated by biftool.exe.
-3.2.11.2.6 Platform Security Compliant Messaging / BIO APIs
-In the platform security model the BIO parsers are run in the client space rather than in the message server space, as is done in the non-platform secure model. If the BIO parsers are run in the message server space, it allows a client process to gain the capabilities of the message server. IPC policing can protect the message server from this.
-Also, for the message server to be able to load any BIO parser it would need more capabilities than it really requires. By running the BIO parsers in the client space, both these issues are solved. The client process must be trusted with the necessary capabilities to run the specified BIO parser.
-The BIO registry files are located in the \resource\messaging\bif read-only directory. All BIO parser DLLs are located in the \sys\bin protected directory.
-
-Figure 26 BIO Message Dependencies (v9.0)
-The BIO client MTM is responsible for loading the BIO database and BIO utilities to handle parse/process requests from clients.
-The BIO registry files no longer identify the BIO parsers DLLs via their UID – the registry file must use the BIO parser DLL name to identify them.
-3.2.12 Messaging / OBEX MTM APIs
-3.2.12.1 Key Internal Relationships and Dependencies
-
-Figure 28 OBEX Internal Dependencies
-3.2.12.2 OBEX MTM Overview
-The OBEX MTM offers simple IR and Bluetooth beaming functionality. It provides an API that is consistent with other MTMs so that the underlying OBEX APIs do not need to be used directly for beaming applications. The OBEX MTM does not provide OBEX receiving functionality, in order to receive OBEX data the underlying OBEX APIs must be used directly.
-3.2.12.2.1 OBEX MTM
-The OBEX MTM is split into three parts. OBEX MTM DLLs, IR MTM DLLs and Bluetooth MTM DLLs. The OBEX MTM DLLs can not be used on their own they provide the base OBEX MTM functionality for the derived IR and Bluetooth MTMs.
-There are two APIs that can be used to create OBEX messages:
-1) The Send-As API
-2) Linked attachments by filename
-The Send-As API provides an interface consistent with other MTMs, however it requires all attachments to be copied into the message store before they can be sent, this is often undesirable for beaming applications because it is wastes disk space. For this reason a second API is provided that allows attachments to be linked to outgoing messages by filename, when this API is used there is no need to copy the attachments to the message store.
-Unlike many other MTMs after OBEX tries to send a message it is deleted from the outbox whether the sending succeeds or fails.
-3.2.12.2.1.1 OBEX MTM Key External Dependencies
-
-Figure 29 OBEX External Dependencies
-3.2.12.2.2 IR MTM
-The bulk of the OBEX MTM functionality is provided by the OBEX MTM DLLs, the IR MTM itself just sets up the parameters.
-3.2.12.2.2.1 IR MTM Key External Dependencies
-
-Figure 30 IR MTM Dependencies
-3.2.12.2.3 Bluetooth MTM
-The bulk of the OBEX MTM functionality is provided by the OBEX MTM DLLs, the Bluetooth MTM just subclasses from the OBEX MTM and sets up Bluetooth specific parameters.
-3.2.12.2.3.1 Bluetooth MTM Key External Dependencies
-
-Figure 31 Bluetooth MTM Dependencies
-3.2.12.2.4 OBEX MTM Utils
-The OBEX MTM Utils provide utility functionality used by the other OBEX MTM DLLs. The two main areas of functionality provided by this component are:
-1) Filename linking functionality
-2) Bluetooth SDP lookup
-The filename linking functionality is provided in the utilities because linked files must be added by the client side during message creation and need to be read on the server side during sending.
-
-3.2.12.2.5 Platform Security Compliant Messaging / OBEX MTM APIs
-From v9.0 and onwards the service settings of all the derived OBEX MTMs are stored in the Central Repository. The OBEX message is stored in the message store as an attachment – from v9.0 and onwards the Attachment API is used to attach the OBEX message.
-
-3.2.13 Messaging / GMXML APIs
-3.2.13.1 Key Relationships and Dependencies
-
-Figure 32 GMXML Dependencies
-3.2.13.2 Overview
-The GMXML component provides simple XML DOM parsing and validation functionality. It is intended for parsing XML that might be needed in messaging applications, specifically SMIL parsing for MMS rendering. It is not a general purpose XML parser and will not be suitable for some applications, e.g. browsing.
-3.2.13.2.1 GMXML DOM
-The DOM implementation is fit for purpose for SMIL rendering but differs from the standard DOM design in several respects, e.g. attributes are not stored as discrete nodes, for performance reasons they are stored with the element.
-The DOM tree classes are all derived from nodes. Implemented node types include elements, text and comments. The type of each element is stored as a descriptor as opposed to an enum. This is less efficient than storing it as an enum but provides maximum flexibility when dealing with unknown element types.
-Nodes are linked together in a tree structure as might be expected in a DOM implementation. The tree structure exists on the heap.
-3.2.13.2.2 GMXML Parser and Composer
-3.2.13.2.2.1 Parser
-The parser takes XML input from a buffer or file and creates the corresponding DOM structure on the heap.
-The parser is capable of performing some basic validation. In order to validate against a DTD a class that implements the GMXML DTD interface is required. The DTD interface specifies several functions that provide the required validation, e.g. one of the functions determines if a given attribute is valid for a given element. An instance of the DTD class should be passed into the parser when validation is required but can be omitted if no validation is needed.
-3.2.13.2.2.2 Composer
-The composer takes a DOM tree and generates XML output from it. The XML output is written to a file.
-3.2.13.2.3 GMXML SMIL DTD (Validator)
-The SMIL DTD validator class is an implementation of the DTD validator interface. It implements several simple functions that provide the information required to validate SMIL data. An instance of the SMIL DTD validator should be passed into the parser if SMIL validation is required.
-4 Security
-4.1 Data caging
-For data storage in the pre-platform security compliant architecture, refer to section [3.2.1.3.2]
-For the data caging in the platform security compliant architecture of v9.0 and onwards, refer to section [3.2.1.3.3]
-4.2 Backup and restore
-The message server registers the index file with the backup server. When informed about a backup/restore it releases the index file, sending events to messaging clients informing them that the message store is unavailable. When informed it can open the index file again, it checks the time stamp on the index file; if it has changed since the file was released it reloads the index file. If the newly restored index file is found to be corrupt it is deleted and a new message store is created. See the section on page 14 for details on how the message server handles corrupt stores. The client performing the restore should always wipe the existing message store before starting to copy the message store from the backup to the device.
-4.3 Capability ranges
-In the platform security compliant architecture of v9.0 and onwards, the capabilities allocated to messaging sub-systems are as listed in following table.
-4.3.1 Capabilities granted to executables
-The following table lists the executables and their capabilities and also gives a basic example for having the required capability.
-
-Executable Capability Rationale (basic example of capability requirement)
-msexe.exe ProtServ ProtServ is required to allow the msexe.exe to start a protected server. This stops processes without ProtServ from starting a server pretending to be the message server
- ReadDeviceData ReadDeviceData is needed to able to read service settings
- WriteDeviceData WriteDeviceData is needed to able to write service settings
- NetworkServices NetworkServices capability is needed to access network transports (SMS, POP3, SMTP, IMAP4).
- LocalServices LocalServices is needed to be able to access IR and Bluetooth
- ReadUserData ReadUserData is needed to be able to read user data (e.g. service settings).
-watcher.exe ReadDeviceData ReadDeviceData is needed to able to read service settings
- WriteDeviceData WriteDeviceData is needed to able to write service settings
- NetworkServices NetworkServices capability is needed to access network transports (SMS).
- LocalServices LocalServices capability is needed for the plug-ins to access IR and Bluetooth
- ReadUserData ReadUserData is needed to be able to read user data
- WriteUserData WriteUserData is needed to be able to write user data
-autosend.exe ReadUserData ReadUserData capability is needed to be able to read data from Outbox and SMTP server MTM.
- WriteUserData WriteUserData capability is needed to be able to write data in Outbox and SMTP server MTM.
- NetworkServices NetworkServices capability is needed to access network transports (SMS, POP3, SMTP, and IMAP4).
- LocalServices LocalServices capability is needed to access the IR and Bluetooth
-SchSend.exe ReadDeviceData ReadDeviceData is needed to able to read settings data
- NetworkServices NetworkServices capability is needed to access the network transports (SMS, POP3, SMTP, and IMAP4).
- LocalServices LocalServices is needed to be trusted by other MTM
- ReadUserData ReadUserData is needed to be able to read user data.
- WriteUserData WriteUserData is needed to be able to write user data.
-SendAs.exe ReadDeviceData ReadUserData is needed to be able to read data in Outbox.
- WriteDeviceData WriteUserData is needed to be able to write data in Outbox.
- NetworkServices NetworkServices capability is needed to access the network transports (SMS, POP3, SMTP, and IMAP4).
- LocalServices LocalServices is needed to be able to access IR and Bluetooth
-
-4.3.2 Capabilities granted to DLLs
-The assigned Platform Security attributes for DLLs within messaging are outlined in the following table.
-DLL Capability
-bifu.dll All –TCB
-bioc.dll All –TCB
-biodb.dll All –TCB
-bios.dll All –TCB
-biowatcher.dll same as watcher.exe
-biut.dll All –TCB
-cbcp.dll All –TCB
-enp.dll All –TCB
-gfp.dll All –TCB
-iacp.dll All –TCB
-nbswatcher.dll same as watcher.exe
-cdmanbswatcher.dll same as watcher.exe
-CdmaSocketWatcher.dll same as watcher.exe
-VMNWatcher.dll same as watcher.exe
-WEMTWatcher.dll same as watcher.exe
-WMTWatcher.dll same as watcher.exe
-WPTWatcher.dll same as watcher.exe
-wapp.dll All –TCB
-wapwatcher.dll same as watcher.exe
-smildtd.dll All –TCB
-xmldom.dll All –TCB
-xmlparser.dll All –TCB
-smiltranslator.dll All –TCB
-imcm.dll All –TCB
-imps.dll same as msexe.exe
-imut.dll All –TCB
-msgs.dll All –TCB
-msgurlrec.mdl same as AppArc.exe (once it exists; eiksrv in meantime)
-mtur.dll All –TCB
-pops.dll same as msexe.exe
-schsend.dll All –TCB
-send.dll All –TCB
-smcm.dll All –TCB
-smcm_gsm.dll Synonym for smcm.dll
-smcm_cdma.dll Synonym for smcm.dll
-smss.dll same as msexe.exe
-smss_gsm.dll Synonym for smss.dll
-smss_cdma.dll Synonym for smss.dll
-smts.dll same as msexe.exe
-btcmtm.dll All –TCB
-btsmtm.dll same as msexe.exe
-irc.dll All –TCB
-irs.dll same as msexe.exe
-obexclientmtm.dll All –TCB
-obexmtmutil.dll All –TCB
-obexservermtm.dll same as msexe.exe
-
-The reason for setting a high capability to the DLLs is to make it possible for almost anyone to link to them. Although a DLL may have capabilities ALL-TCB (All minus TCB), its real capability is limited by the process which loads the DLL.
-4.3.3 Capabilities required to use the subsystem
-The message subsystem needs to be protected against malicious clients. The following table shows the key capabilities required to do related activities in different components.
-
-Component Related Activity Required Capability and SID
-Message server Create message in local folder No capability required
- Create message in Outbox ReadUserData, WriteUserData and MTM specific capabilities
- Access client MTM ReadUserData, WriteUserData and MTM specific capabilities
-Watcher Allow plug-ins to wait on events (e.g. arrival of SMS) Watcher always polices if the client capabilities are trusted by the watcher framework, else it will not be loaded
-Plug-ins or clients using watcher need the same capabilities as watcher.exe to be able to be loaded by watcher.
-Autosend Send messages in background NetworkService or LocalService required by the message type
-SchSend Scheduling of operations (e.g. sending SMS) SchSend always polices to see if the process was started by the Task Scheduler – if not the process terminates without performing any of the scheduled tasks. Also, the SchSend verifies that only itself and the message server created the scheduled tasks. If this is not the case, SchSend does not performing the scheduled tasks.
-SendAs Create message Draft, move it to Outbox, and send message WriteDeviceData or WriteUserData and other capability required by the message type
-
-5 Further Information
-5.1 References
-No. Document Reference Version Description
-R1 messaging_functional_specification.doc 0.6 Messaging Functional description
-R2 SGL.GT0143.161_App-Framework_Architectural_Description.doc 1.0 App-Framework Architectural Description
-R3 NBProtocols_Subsystem_Architectural_Description.doc 0.2 NBProtocols Architectural Description
-R4 WAP-stack_architectural_analysis.doc 1.0 WAP stack architectural analysis
-R5 HTTP Transport Framework Architectural Description.doc 1.1 HTTP Transport Framework 1.1 Architectural Description
-5.2 Open Issues
-The following issues need to be resolved before this document is completed:
-1. Top-level architecture diagram showing the framework and plug-ins should be added to overview section.
-2. Message store section should talk about removable media.
-3. Define "Message Server Client API" and "Messaging Client API" in the glossary, and ensure it is consistently used in the diagrams
-4. Add a sequence diagram for receiving a vCard over SMS and integrating it into contacts
-5. Add a sequence diagram for sending an SMS
-6. Add a sequence diagram for synchronising a POP3 mail box
-7. Add a sequence diagram for connecting to an IMAP4 mail box and downloading a message
-8. Capability table should be updated after the implementation of server e.g. message server
-9. Sequence diagram may need to be changed to show secured platform operation
-10. In section [3.1.1.4] the server SendAsV2 to find a correct name
-11. Section 3.2.1.3.3.1 Data Caging file 'Mtm Registry v2'may need a correct name
-12. Breakdown diagram showing all DLL, exes, apps in the messaging subsystem for both the pre-v8.0 and post v9.0 in section[3.2]
-13. Needs to say more about how the capabilities are policed and the algorithms used for different operations
-14. The dependecy between the message server and the central repository need to be listed in the email, SMS and OBEX diagrams (e.g. message store)
-15. Section 3.2.1.2 - figure 3 - Central Repository also get used by the Message server, or server MTMs (e.g. POP3), to retrieve account settings the path, required DLL and description are not given
-16. Section 4.3.3 title can be Police requirement of the sub-system, add extra column for SID in the table and list the use of SID. For example SchSend checks for Task Scheduler SID
-
-
-5.3 Glossary
-The following technical terms and abbreviations are used within this document.
-Term Definition
-BIO
-Bearer Independent Object Smart messages e.g. vCards, vCals, and WAP provisioning messages. These can currently be received via the WAP stack, SMS stack, Bluetooth or Infrared.
-BIO Type UID that represents the content type of a BIO Message.
-Message Centre Application that displays list views of messages to the user, allowing the user to perform operations such as copying messages, sending messages creating new messages etc.
-Message Viewer Application for viewing a message.
-Message Editor Application for creating or editing a message
-Message Server Symbian OS Server that handles request to modify the Message Store
-Message Store Store of messages and related information kept in the file system on a Symbian OS device.
-Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
-Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
-Global Inbox A standard folder under the local service which is used to store incoming messages like SMS MMS etc. as opposed to an IMAP4 Inbox which would be under an IMAP4 service and is a representation of the Inbox on an IMAP4 email server.
-Central Repository centralised and secure storage facility for application settings
-OBEX Object exchange protocol, used to send objects such as vCards or files between devices via infrared or Bluetooth.
-GMXML XML parser / generator for use with SMIL formatted messages.
-UID Unique Identifier, a 32 bit number allocated from a registry owned by Symbian
-IPC Inter Process Communication
-MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
+MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
MTM Registry A list of currently installed MTMs maintained by the message server.
TLS Transport Layer Security, provides encryption of a TCP/IP socket.
M-HTML Standard for including HTML in MIME email messages see http://www.ietf.org/rfc/rfc2557.txt
@@ -7063,15 +5027,15 @@
Message Editor Application for creating or editing a message
Message Server Symbian OS Server that handles request to modify the Message Store
Message Store Store of messages and related information kept in the file system on a Symbian OS device.
-Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
-Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
+Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
+Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
Global Inbox A standard folder under the local service which is used to store incoming messages like SMS MMS etc. as opposed to an IMAP4 Inbox which would be under an IMAP4 service and is a representation of the Inbox on an IMAP4 email server.
Central Repository centralised and secure storage facility for application settings
OBEX Object exchange protocol, used to send objects such as vCards or files between devices via infrared or Bluetooth.
GMXML XML parser / generator for use with SMIL formatted messages.
UID Unique Identifier, a 32 bit number allocated from a registry owned by Symbian
IPC Inter Process Communication
-MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
+MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
MTM Registry A list of currently installed MTMs maintained by the message server.
TLS Transport Layer Security, provides encryption of a TCP/IP socket.
M-HTML Standard for including HTML in MIME email messages see http://www.ietf.org/rfc/rfc2557.txt
@@ -8081,1033 +6045,15 @@
Message Editor Application for creating or editing a message
Message Server Symbian OS Server that handles request to modify the Message Store
Message Store Store of messages and related information kept in the file system on a Symbian OS device.
-Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
-Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
+Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
+Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
Global Inbox A standard folder under the local service which is used to store incoming messages like SMS MMS etc. as opposed to an IMAP4 Inbox which would be under an IMAP4 service and is a representation of the Inbox on an IMAP4 email server.
Central Repository centralised and secure storage facility for application settings
OBEX Object exchange protocol, used to send objects such as vCards or files between devices via infrared or Bluetooth.
GMXML XML parser / generator for use with SMIL formatted messages.
UID Unique Identifier, a 32 bit number allocated from a registry owned by Symbian
IPC Inter Process Communication
-MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
-MTM Registry A list of currently installed MTMs maintained by the message server.
-TLS Transport Layer Security, provides encryption of a TCP/IP socket.
-M-HTML Standard for including HTML in MIME email messages see http://www.ietf.org/rfc/rfc2557.txt
-MIME Specification for the format of email message bodies see http://www.ietf.org/rfc/rfc1341.txt
-RFC2822 The standard format for internet mail messages see http://www.ietf.org/rfc/rfc0822.txt
-SMTP Simple Mail Transport Protocol
-SID Secure Identification
-IMAP4 Internet Mail Access Protocol
-POP3 Post Office Protocol Version 3
-NBS Narrow Band Socket, in the messaging context this refers to the socket that is used to talk to the SMS stack for receiving and sending SMS messages
-SMS Short Message Service
-MMS Multimedia Message Service
-WAP Wireless Application Protocol
-WSP WAP Session Protocol
-HTTP Hypertext transfer protocol
-PDU Protocol Data Unit. This is the encoded form of SMS and MMS messages.
-Versit A consortium that defined standard formats for things like contacts (vCard) and calendar entries (vCals)
-SDP Service Discovery Protocol. A Bluetooth protocol that allows an applications to discover which services are available and to determine the characteristics of the services.
-SMIL Synchronized Multimedia Integration Language. Presentation language that is commonly used to define the contents of an MMS message.
-XML Extensible Mark-up Language
-DOM Document Object Model
-DTD Document Type Definition, a schema that defines the structure of an XML document.
-ESTORE Symbian OS component that provides stream based storage. Messaging uses the Permanent file store provided by ESTORE to store its index entries.
-Appendix A - Example Sequence Diagrams
-A.1 Copy to a Remote Service
-
-Figure 33 Sequence Diagram Showing Copying to a Remote Service
-Figure 33 shows a client copying a message to a remote service using the Messaging Client API. The message server then delegates the copy to the SMTP Server MTM. The Server MTM interprets the request as a request to send the message so it opens a connection to a remote SMTP server and sends the message. While the message is being sent the client can retrieve progress information from the CMsvOperation object that was returned by CMsvEntry::CopyL. The dark grey IPC line represents the split between the objects running in the client’s process space on the left and the message server’s process on the right.
-There are four basic steps:
-1. The client opens session with Message Server and creates a CMsvEntry set on the global outbox,
-2. The client then requests an asynchronous copy from the outbox to the SMTP service, a CMsvOperation object is returned. The message server loads the SMTP Server MTM and delegates the copy operation to it.
-3. The client requests progress from the CMsvOperation object, this request is passed through to the SMTP Server MTM. The client may repeat this step multiple times.
-4. The Server MTM finishes sending message. It moves the message to sent folder and completes the message server’s request. The message server completes the CMsvOperation object, which requests the final progress from the message server. The server returns the final progress and deletes the Server MTM. The CMsvOperation then completes the client’s original request.
-This diagram hides all of the internal working of the SMTP Server MTM, for information on this see below.
-A.2 SMTP Session
-
-Figure 34 Sequence Diagram Showing a SMTP Session
-Figure 34 shows the operation of the SMTP Server MTM after a request has come from the message server to copy a message to the SMTP service.
-1. SMTP Server MTM gets the request from the message server, it will build a selection of messages consisting of the union of the selection of messages passed in and the messages in the outbox that are associated with this SMTP service and are ready to be sent. The chain of classes are constructed, and a request is passed to networking to connect to the remote SMTP server, details of the server name and port are retrieved from the settings stored in the SMTP service entry.
-2. The component waits for the SMTP server to respond with a greeting indicating it is willing to talk, then sends EHLO to the server and waits for the response detailing the capabilities of the Server. After this step there could set steps to start using TLS and or SMTP AUTH depending on the SMTP settings.
-3. CImSmtpSession calls back into CMsgOutboxSend to retrieve the next message to be sent, then constructs a CImSmtpFile object to handle sending, for details on the sending see SMTP Email Send. When sending the email has completed the CImSmtpFile object is deleted.
-4. CImSmtpSession calls back into CMsgOutboxSend to retrieve the next message which returns saying there are no more messages. CImSmtpSession sends QUIT to the SMTP server and completes CMsgOutboxSend. CMsgOutboxSend deletes CImSmtpSession which tears down the connection to the SMTP server; it then completes the SMTP Server MTM. The Server MTM will then complete the message server and be deleted.
-A.3 SMTP Email Send
-
-Figure 35 Sequence Diagram Showing SMTP Transactions during Email Send.
-Figure 35 shows a CImSmtpFile object sending an email message to an SMTP server.
-1. Construct a CImSendMessage object, part of the imut component. Reset the SMTP Server
-2. Read address information from the CImHeader object stored in the message store, send address information to SMTP server.
-3. Use CImSendMessage object to read the message from the message store and generate RFC2822 message line by line. Send each line to the server as it is generated.
-4. Complete and send the message by sending a full stop to the SMTP server
-
-
-
-
-Messaging Symbian OS v7.0s, v8.0, v8.1, v9.0, v9.1 Architectural Description
-
-Status: Issued
-Team/Department : Messaging / Content & Messaging
-
-Contents
-1 INTRODUCTION 6
-1.1 PURPOSE AND SCOPE 6
-2 SUBSYSTEM OVERVIEW AND BACKGROUND 6
-3 MESSAGING ARCHITECTURE AND APIS 7
-3.1 SUBSYSTEM COMPONENTS 7
-3.1.1 Framework components 7
-3.1.1.1 Message Server and MTM architecture 7
-3.1.1.2 Schedule Send 7
-3.1.1.3 SendAs Version 1 7
-3.1.1.4 SendAs Version 2 7
-3.1.1.5 Watcher Framework 8
-3.1.1.6 Message URL Handler 8
-3.1.1.7 Bio Message Framework 8
-3.1.2 Plug-ins 8
-3.1.2.1 SMS 8
-3.1.2.2 CDMA SMS 8
-3.1.2.3 Email 9
-3.1.2.4 OBEX 9
-3.1.2.5 MMS 9
-3.1.2.6 GMXML 10
-3.1.2.7 Bio Message Plug-ins 10
-3.1.2.8 PCMTM 10
-3.1.2.9 Fax 10
-3.2 GENERAL DESCRIPTION 11
-3.2.1 Messaging / Message Server and MTM Architecture APIs 11
-3.2.1.1 Key Internal Relationships and Dependencies 11
-3.2.1.2 Key External Relationships and Dependencies 12
-3.2.1.3 API Purpose - Further Elaboration 13
-3.2.1.3.1 Message Store 13
-3.2.1.3.2 Data File Storage (pre - v9.0) 15
-3.2.1.3.3 Platform Security Compliant Message Store 16
-3.2.1.3.4 How message centres display the message store 17
-3.2.1.3.5 Message Type Module Architecture 19
-3.2.1.3.6 Message Server Client API 21
-3.2.2 Messaging / Send As APIs 22
-3.2.2.1 Key Relationships and Dependencies 22
-3.2.2.2 API Purpose - Further Elaboration 22
-3.2.2.2.1 SendAs API (pre – v9.0) 22
-3.2.3 Platform Security Compliant SendAs Server (v9.0 onwards) 23
-3.2.4 Messaging / Schedule Send APIs 24
-3.2.4.1 Key Relationships and Dependencies 24
-3.2.4.2 API Purpose - Further Elaboration 24
-3.2.4.2.1 Schedule Send 24
-3.2.5 Messaging / Watchers APIs 25
-3.2.5.1 Key Relationships and Dependencies 25
-3.2.5.2 API Purpose - Further Elaboration 25
-3.2.6 Messaging / Message URL Handler APIs 26
-3.2.6.1 Key Relationships and Dependencies 26
-3.2.6.2 API Purpose - Further Elaboration 26
-3.2.6.2.1 Message URL Handler Application 26
-3.2.6.2.2 Message URL Recognisers 27
-3.2.7 Messaging / SMS APIs 27
-3.2.7.1 Key Internal Relationships and Dependencies 27
-3.2.7.2 Key External Relationships and Dependencies 28
-3.2.7.3 API Purpose - Further Elaboration 28
-3.2.7.3.1 SMS Watchers 28
-3.2.7.3.2 SMS Client MTM 29
-3.2.7.3.3 SMS Utilities 29
-3.2.7.3.4 SMS Server MTM 30
-3.2.8 Messaging / CDMA SMS APIs 31
-3.2.8.1 Key Internal Relationships and Dependencies 31
-3.2.8.2 Key External Relationships and Dependencies 32
-3.2.8.3 API Purpose - Further Elaboration 32
-3.2.8.3.1 CDMA SMS Watchers 32
-3.2.8.3.2 CDMA SMS Client MTM 33
-3.2.8.3.3 CDMA SMS Utilities 33
-3.2.8.3.4 CDMA SMS Server MTM 33
-3.2.8.3.5 Configuration for using CDMA SMS MTM 34
-3.2.9 Messaging / Email APIs 35
-3.2.9.1 Key Internal Relationships and Dependencies 35
-3.2.9.2 Key External Relationships and Dependencies 36
-3.2.9.3 API Purpose - Further Elaboration 36
-3.2.9.3.1 Email Overview 36
-3.2.9.3.2 Email Client Utilities 37
-3.2.9.3.3 Email Server MTM Utilities 37
-3.2.9.3.4 POP3 MTMs 37
-3.2.9.3.5 IMAP4 MTMs 38
-3.2.9.3.6 SMTP MTMs 40
-3.2.9.3.7 Autosend 40
-3.2.10 Messaging / MMS APIs 40
-3.2.10.1 Key Internal Relationships and Dependencies 41
-3.2.10.2 API Purpose - Further Elaboration 41
-3.2.10.2.1 MMS Overview 41
-3.2.10.2.2 MMS Utilities 42
-3.2.10.2.3 MMS Watcher 43
-3.2.10.2.4 MMS Client MTM 43
-3.2.10.2.5 MMS Server MTM 44
-3.2.10.2.6 MMS Codec 45
-3.2.11 Messaging / BIO APIs 46
-3.2.11.1 Key Internal Relationships and Dependencies 46
-3.2.11.2 API Purpose - Further Elaboration 47
-3.2.11.2.1 BIO Overview 47
-3.2.11.2.2 BIO MTM 47
-3.2.11.2.3 BIO Database 48
-3.2.11.2.4 BIO Parsers 48
-3.2.11.2.5 BIF Files and Utilities 48
-3.2.11.2.6 Platform Security Compliant Messaging / BIO APIs 49
-3.2.12 Messaging / OBEX MTM APIs 50
-3.2.12.1 Key Internal Relationships and Dependencies 50
-3.2.12.2 OBEX MTM Overview 50
-3.2.12.2.1 OBEX MTM 50
-3.2.12.2.2 IR MTM 51
-3.2.12.2.3 Bluetooth MTM 51
-3.2.12.2.4 OBEX MTM Utils 52
-3.2.12.2.5 Platform Security Compliant Messaging / OBEX MTM APIs 52
-3.2.13 Messaging / GMXML APIs 52
-3.2.13.1 Key Relationships and Dependencies 52
-3.2.13.2 Overview 53
-3.2.13.2.1 GMXML DOM 53
-3.2.13.2.2 GMXML Parser and Composer 53
-3.2.13.2.3 GMXML SMIL DTD (Validator) 53
-4 SECURITY 54
-4.1 DATA CAGING 54
-4.2 BACKUP AND RESTORE 54
-4.3 CAPABILITY RANGES 54
-4.3.1 Capabilities granted to executables 54
-4.3.2 Capabilities granted to DLLs 55
-4.3.3 Capabilities required to use the subsystem 57
-5 FURTHER INFORMATION 59
-5.1 REFERENCES 59
-5.2 OPEN ISSUES 59
-5.3 GLOSSARY 60
-APPENDIX A - EXAMPLE SEQUENCE DIAGRAMS 62
-A.1 COPY TO A REMOTE SERVICE 62
-A.2 SMTP SESSION 64
-A.3 SMTP EMAIL SEND 66
-
-Table of Figures
-Figure 1 Where Messaging Lives 6
-Figure 2 MTM Relationships 11
-Figure 3 External Dependencies 12
-Figure 4 Message Store 13
-Figure 5 Series 60 Inbox List View 14
-Figure 6 Remote and Local Entries 14
-Figure 7 Email Message 15
-Figure 8 Series 60 Message Centre (Composed from 2 screen shots) 17
-Figure 9 UIQ Message Centre 18
-Figure 10 Messaging MTM Structure (light coloured components are part of messaging subsystem) 19
-Figure 11 Nokia 9210 Outbox List View 20
-Figure 12 SendAs Version 1 Dependencies 22
-Figure 13 SendAs Version 2 Dependencies 23
-Figure 14 Schedule Send Dependencies 24
-Figure 15 Watcher Dependencies 25
-Figure 16 Message URL Handler Dependencies 26
-Figure 17 SMS Internal Dependencies 27
-Figure 18 SMS External Dependencies 28
-Figure 19 CMDA SMS Internal Dependencies 31
-Figure 20 CDMA SMS External Dependencies 32
-Figure 19 Email Internal Dependencies 35
-Figure 20 Email External Dependencies 36
-Figure 21 MMS Internal Dependencies 41
-Figure 22 MMS Utilities External Dependencies 42
-Figure 23 MMS Watcher External Dependencies 43
-Figure 24 MMS Client MTM Dependencies 43
-Figure 25 MMS Server MTM Dependencies 44
-Figure 26 BIO Message Internal Dependencies 46
-Figure 27 Bio Parser External Dependencies 47
-Figure 26 BIO Message Dependencies (v9.0) 49
-Figure 28 OBEX Internal Dependencies 50
-Figure 29 OBEX External Dependencies 51
-Figure 30 IR MTM Dependencies 51
-Figure 31 Bluetooth MTM Dependencies 52
-Figure 32 GMXML Dependencies 52
-Figure 33 Sequence Diagram Showing Copying to a Remote Service 62
-Figure 34 Sequence Diagram Showing a SMTP Session 64
-Figure 35 Sequence Diagram Showing SMTP Transactions during Email Send. 66
-1 Introduction
-1.1 Purpose and Scope
-The Messaging Architectural Description details the architecture and APIs exposed by the Messaging Subsystem. This document does not attempt to list all functionality provided by the messaging subsystem. For details on the functionality provided and the specifications implemented by the messaging subsystem see the Messaging Functional Description [R1]. This document describes the general architecture of messaging subsystem. Information related to a particular release version is mentioned with relevant release number.
-2 Subsystem Overview and Background
-The Messaging Subsystem provides an application level API to handle the storage and transport of different message types. It sits between messaging applications and the lower level subsystems which messaging uses for storage and transmission of messages.
-
-Figure 1 Where Messaging Lives
-The message types that messaging currently supports are Email (POP3, IMAP4 & SMTP), SMS, MMS and OBEX. The set of supported message types is extensible at run time by the use of plug-in modules that are responsible for the transmission and storage of a particular message type. This means that the set of components shown communicating with the network cloud depend on the message types installed.
-3 Messaging Architecture and APIs
-3.1 Subsystem components
-The Messaging subsystem components can be split into two categories: those components that form the framework and those that plug into the framework to support specific message types. This section briefly describes each of the components, more detailed descriptions of the components and their dependencies can be found in later sections of this document.
-3.1.1 Framework components
-3.1.1.1 Message Server and MTM architecture
-The message server is the core component in the messaging subsystem. It provides the message store used to contain messages. The Message Type Module architecture also allows plug-ins to add support for new message types to the messaging subsystem.
-Component Description
-messaging\framework\serverexe Executable that links to the server component and starts the message server
-messaging\framework\server Contains classes that make up both the client and server side of the message server API.
-messaging\framework\mtmbase Base classes for the plug-ins that handle the various message types
-3.1.1.2 Schedule Send
-The Schedule Send component is an extension to the framework that provides support for scheduling of operations such as sending messages. Message type modules that wish to support this functionality can use these support components to implement scheduling. For example the SMS MTM uses this to allow scheduled sending of SMS messages.
-Component Description
-messaging\schedulesend\schedulesendmtm Base classes that handle functionality for message server plug-ins that wish to enable scheduling of sending messages.
-messaging\schedulesend\schedulesendexe Executable use to provide schedule send behaviour.
-3.1.1.3 SendAs Version 1
-This version of SendAs is supported in releases pre - v9.0. SendAs provides a high level API for applications that wish to include a “Send As” menu to allow users to send content via one of the message types supported by messaging. The application using the API does not have to be aware of the message type selected by the user. Note the API does not send the messages.
-Component Description
-messaging\sendas High level API to allow creation of messages.
-3.1.1.4 SendAs Version 2
-From v9.0 and onwards the SendAs has been replaced with client server architecture based SendAs server. The client server architecture enhances secured platform implementation. The SendAs server polices the client application. If it is not trusted with required capabilities the SendAs server will refuse the client access. The client MTM for the message type can send a message with user permission even if the client does not have the correct capabilities.
-Component Description
-messaging\sendAsV2 High level API to allow the creation and sending of messages
-
-3.1.1.5 Watcher Framework
-The watcher framework is a lightweight framework to allow plug-ins to wait on events. For example there is an SMS watcher that waits for incoming SMS messages and delivers them to the message store. The watcher framework will only load plug-ins from ROM.
-Component Description
-messaging\framework\watcher Executable that loads and runs watcher plug-ins.
-3.1.1.6 Message URL Handler
-Support for recognising messaging URLs (mailto:, sms:, fax:, mms:), and then launching an editor with a new message.
-Component Description
-messaging\urlhandler\urlhandler An application that parses the URLs and then creates a correctly addressed message and launches a message editor.
-messaging\urlhandler\recogniser Recognisers that map from the URL schemes to the mime types.
-3.1.1.7 Bio Message Framework
-The Bio Message Framework provides a framework that supports plug-ins to handle messages like vCards and Internet access point set-up messages.
-Component Description
-messaging\biomsg\BDB\BIODB Classes to maintain the database of bio registration files.
-messaging\biomsg\BIFU\BIFU Classes for reading and writing bio registration files
-messaging\biomsg\BIOC\BIOC Bio message client MTM, this is in the framework section as it forms part of the bio messaging framework it is also a plug-in to the messaging framework.
-messaging\biomsg\BIOS\BIOS Bio message server MTM, this is in the framework section as it forms part of the bio messaging framework it is also a plug-in to the messaging framework.
-3.1.2 Plug-ins
-3.1.2.1 SMS
-The SMS plug-ins provide application level support for the Short Message Service messages.
-Component Description
-messaging\biomsg\BioWatchers Plug-ins to the watcher framework to listen for SMS, WSP, and WDP messages and deliver them to the global inbox in the message store.
-messaging\sms\clientmtm A plug-in to the message server framework to provide a generic API for creation of SMS messages (SMS Client MTM & SMS utilities)
-messaging\sms\servermtm A plug-in to the message server framework to provide a generic API for sending of SMS messages (SMS Server MTM)
-3.1.2.2 CDMA SMS
-The CDMA SMS plug-ins provide application level support for the CDMA Short Message Service messages.
-Component Description
-messaging\biomsg\BioWatchersCdma Plug-ins to the watcher framework to listen for CDMA SMS messages and deliver them to the global inbox in the message store.
-messaging\sms\multimode\clientmtm A plug-in to the message server framework to provide a generic API for creation of CDMA SMS messages (CDMA SMS Client MTM)
-messaging\sms\multimode\servermtm A plug-in to the message server framework to provide a generic API for sending of CDMA SMS messages (CDMA SMS Server MTM)
-
-3.1.2.3 Email
-The email plug-ins provide support the POP3, IMAP4 and SMTP email protocols and support for parsing and generating plain test, MIME and M-HTML format email messages.
-Component Description
-messaging\email\clientmtms A plug-in to the message server framework to provide a generic API for creation of email messages (IMAP4 SMTP and POP3 Client MTMs & email utilities)
-messaging\email\imapservermtm A plug-in to the message server framework to provide a generic API for access to a remote IMAP4 server (IMAP4 Server MTM)
-messaging\email\smtpservermtm A plug-in to the message server framework to provide a generic API for access to a remote SMTP server (SMTP Server MTM)
-messaging\email\popservermtm A plug-in to the message server framework to provide generic API for access to remote POP3 server (POP3 Server MTM)
-messaging\email\servermtmutils Email utilities for parsing plain text and MIME email messages. It also provides an abstraction of the TCP/IP sockets for use by the SMTP POP3 and IMAP4 plug-ins.
-messaging\email\autosend An executable that requests SMTP Server MTM to send messages in the outbox. This is used to provide send on next connection functionality and is started by the POP3 and IMAP4 Client MTMs.
-3.1.2.4 OBEX
-The OBEX MTM is a set of plug-ins to the message server that provides support for IR and Bluetooth beaming.
-Component Description
-messaging\obex\btmtm\btclient\group\btcmtm Bluetooth Client MTM
-messaging\obex\btmtm\btserver\group\btsmtm Bluetooth Server MTM
-messaging\obex\irmtm\irclient\group\ircmtm IR Client MTM
-messaging\obex\irmtm\irserver\group\IRSMTM IR Server MTM
-messaging\obex\obexmtm\obexclient\group\obexClientMtm OBEX Client MTM, base classes for the Bluetooth and IR Client MTMs
-messaging\obex\obexmtm\obexserver\group\obexServerMtm OBEX Server MTM, base classes for the Bluetooth and IR Server MTMs
-messaging\obex\obexmtm\obexutil\group\obexMtmUtil OBEX MTM utilities
-3.1.2.5 MMS
-The MMS MTM is a plug-in to the message server that provides support for MMS messages. From v9.0 and onwards MMS MTM and related components are removed.
-Component Description
-messaging\mms\utils MMS Utilities
-messaging\mms\servermtm MMS Server MTM
-messaging\mms\mmswatcherplugins MMS plug-ins to WAP push framework to handle reception of MMS notifications
-messaging\mms\codec MMS utilities for handling MMS codecs
-messaging\mms\clientmtm MMS Client MTM
-3.1.2.6 GMXML
-GMXML is a parser/generator for SMIL presentations for MMS messages.
-Component Description
-messaging\GMXML\XMLParser XML parser designed for parsing of SMIL messages
-messaging\GMXML\XMLDom XML document object model designed for parsing of SMIL messages
-messaging\GMXML\SMILdtd SMIL DTD
-3.1.2.7 Bio Message Plug-ins
-These parsers plug into the bio messaging framework to handle specific types of bio message.
-Component Description
-messaging\biomsg\cbcp\CBCP Compact business card parser
-messaging\biomsg\enp\ENP Email notification parser
-messaging\biomsg\gfp\gfp General file parser
-messaging\biomsg\iacp\IACP Nokia Smart Message Internet Access Parser
-messaging\biomsg\wapp\wapp Nokia/Ericsson OTA Parser
-3.1.2.8 PCMTM
-Plug-in to the message server that provided email synchronisation with a PC. This component has been deprecated in 8.0a and will not been documented in the API section below.
-3.1.2.9 Fax
-Plug-in to the message server that provides fax support. This component has been deprecated in 8.0a and will not been documented in the API section below.
-
-3.2 General Description
-3.2.1 Messaging / Message Server and MTM Architecture APIs
-3.2.1.1 Key Internal Relationships and Dependencies
-
-Figure 2 MTM Relationships
-Figure 2 shows the relationship between the Message Server and the MTM plug-ins. The grey classes are realisations of the MTM interfaces defined by the messaging framework. The message server depends on the Server MTM interface. Messaging Clients depend on the Client, UI and UI Data MTM interfaces and the Message Server Client API.
-3.2.1.2 Key External Relationships and Dependencies
-
-Figure 3 External Dependencies
-The grey package representing the messaging client depends on the Client, UI and UI Data interfaces and the Messaging Client API. The message server then depends on:
-• Charconv – Provides character set conversion routines, used to convert encoded message body text to Unicode body text.
-• EStore – Provides API to handle a stream based store used for the messaging index file and the framework classes for the message store files. (omitted from other dependency diagrams as it is implied by the dependency on the message server)
-• F32 – Provides the file server APIs used to access the file system directories in which messaging stores files containing message data. (omitted from other dependency diagrams)
-• BAFL – Provides API to load the correct messaging resource file dependent on the current language and to register the message store index file with the backup server. (omitted from other dependency diagrams)
-• ETEXT – Rich text APIs used to store body text of messages, this rich text format is a Symbian Proprietary format. (omitted from other dependency diagrams)
-• EUSER – Core Symbian OS utilities such as descriptors, arrays, client / server framework, cleanup stack and others (omitted from this and other dependency diagrams).
-• Central Repository – Centralised and secure storage facility for application settings, the message server stores message settings data in the central repository (from v9.0 and onwards).
-Note that debug only dependencies such as the flogger have been omitted from dependency diagrams.
-3.2.1.3 API Purpose - Further Elaboration
-3.2.1.3.1 Message Store
-The message server provides persistent storage of messages and messaging account settings. It does this by providing a message store consisting of a tree of message entries. Multiple clients can access the message store simultaneously. Each entry in the tree can represent an email account, folder of messages, message part, etc.
-
-Figure 4 Message Store
-Figure 4 shows an example message store. The tree is broken down in to three levels:
-1. The Root entry. This entry is just present to tie the tree structure together
-2. Service entries. There is one local service under which local folders and messages are stored, and zero or more remote services. Remote services represent message accounts.
-3. Message & Folder entries. Messages and folders, under the local service represent messages stored on the device. Messages and folders under remote services represent a local copy of messages that are present on a remote server. For example under a POP3 email service you would have copies of all the messages present on the POP3 email server, or under an SMS service you might find SMS messages that are stored on a SIM.
-The message server controls access to the entries in the store. It enforces the three levels therefore attempts to create message or folder entries directly under the root entry will fail.
-The message server provides three types of storage for each entry in the message store:
-• Index entry - TMsvEntry - intended to provide enough information for UI to display list views as shown in Figure 5. This consists of two strings and various flags (read, complete, has attachments etc).
-• Stream based file store - CMsvStore – provides storage of streams of data associated with UIDs. A standard UID is defined for storing body text. Other UIDs are specific. For example the email MTMs define a UID for storage of MIME headers. Compared to the index entry information this is used to store larger objects and is extensible, at the cost of being slower to access. From v9.0 and onwards CMsvStore provides an Attachment API for managing attachments. The Attachment API should be used as attachments can no longer be accessed directly due to Platform Security.
-• Directory of files – normally used for attachments.
-The only storage type that is always present is the index entry. The stream store and the directory of files are optional.
-
-Figure 5 Series 60 Inbox List View
-
-Figure 6 Remote and Local Entries
-As shown in Figure 6 the message store is split into two sets of entries:
-• Remote entries - entries that are representations of entries stored on a remote store .
-• Local entries - entries not linked to a remote store.
-The message server handles changes to local entries; internally it hands off changes to remote entries to the Server MTM that owns that service. Examples of operations that are handed off to Server MTMs are operations involving copying and moving messages to and from a remote service. See section 3.2.1.3.5 or more information on Server MTMs.
-Each entry within the store has a type:
-Folder – Messages can be grouped into folders. Standard folders such as inbox / outbox and user created folders.
-Message – Storage of the content of a message. Message entries can have child entries used to represent the structure of a message.
-Attachment – These represent attachments under a message entry.
-Root & Local Service Entry – There tie the tree structure together. However the Stream store associated with the root entry is sometimes used by UIs to store preferences e.g. default folder views etc.
-Remote Service - Represents a source and / or destination for messages. They are used to store the settings associated with the source / destination.
-Message Type Specific - MTMs can create other message types for use as child entries to messages they own. For example email uses a tree structure, with a message entry as the root, to represent the MIME structure of an email message; it uses folder entries to represent MIME folders and adds new types for entries representing the html body and text body parts of a message. This is shown in Figure 7.
-
-Figure 7 Email Message
-Using the message store to represent message structure allows reuse of the tree structure and makes it very simple to represent one message embedded in another. However this representation introduces performance issues as it results in each message having multiple files associated with it. The message server also keeps all index entries in memory; therefore this representation increases the memory footprint of the message server. Therefore when designing new MTMs we should think about moving away using multiple index entries to store one message in the message store.
-A default message store is created if the message server starts and no message store is present or a corrupt message store is present. The server will initially create a store with just a root entry, and then the server will create any standard folders defined in the resource file msgs.rsc. Finally the server will check whether an executable ‘mailinit.exe’ is present on the system, if it is present the server will launch the executable to allow customisation of the message store. The behaviour of ‘mailinit.exe’ is defined by the UI family of the device. However the typical behaviour is to load each of the UI Message Type Modules and allow each to perform any message type specific initialisation. For example the SMS plug-in typically creates a default service entry.
-
-3.2.1.3.2 Data File Storage (pre - v9.0)
-This section describes the files used by the message server before release v9.0. For information on the files used for release from v9.0 and onwards see section [3.2.1.3.3.1].
-Filename Access Purpose
-?:\system\Mail\index Private Message server index file, internal to message server
-?:\system\Mail\<8 hex digits> Shared via API Message server store files for services, clients access these via a messaging API.
-?:\system\Mail\<8 hex digits>.new Shared via API Temporary file used during committing message server store files.
-?:\SYSTEM\MAIL\<8 HEX DIGITS>_F\* Shared Files associated with a messaging service. These may be accessed directly by clients.
-?:\system\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits> Shared via API Message server store files for message entries, clients access these via a messaging API.
-?:\system\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits>.new Shared via API Temporary file used whilst committing message server store files.
-?:\system\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits>_F\* Shared Files associated with a message entry. These are accessed directly by clients.
-c:\system\data\msgs.ini Private Stores the drive containing the last used message store
-c:\system\Mtm\Mtm Registry v2 Private Cache of registered MTMs, internal to message server
-C:\system\data\sms_settings.dat Shared Copy of the SMS settings.
-?:\System\Mail\StoreInit.tmp Shared Created when message server runs ‘mailinit.exe’, ‘mailinit.exe’ should delete the file when it has successfully completed.
-?:\System\Mail\storedeleted.tmp Shared Created when message server finds and deletes a corrupt message store. Allows the UI to inform the user about the fact that the message store was corrupt.
-Files that are shown as private should only be accessed by the message server or by connectivity process for backup and restore purposes. Files listed as shared are accessed directly by messaging clients. Files listed as shared via API are accessed by client process but only via messaging APIs.
-3.2.1.3.3 Platform Security Compliant Message Store
-From v9.0 and onwards the message store is stored in the message server's data cage and the settings data are placed in the Central Repository. Access to the message store is only possible via message server APIs and not directly through file access. This leads to secured data storage and secured platform.
-3.2.1.3.3.1 Data caging
-Filename Purpose
-?:\private\<SID>\Mail\index Message server index file, internal to message server
-?:\ private\<SID>\Mail\<8 hex digits> Message server store files for services, clients access these via a messaging API.
-?:\ private\<SID>\Mail\<8 hex digits>.new Temporary file used during committing message server store files.
-?:\ private\<SID>\Mail\<8 hex digits>_F\* Files associated with a messaging service. These may be accessed directly by clients.
-?:\ private\<SID>\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits> Message server store files for message entries, clients access these via a messaging API.
-?:\ private\<SID>\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits>.new Temporary file used whilst committing message server store files.
-?:\ private\<SID>\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits>_F\* Files associated with a message entry. These are accessed directly by clients.
-c:\ private\<SID>\data\msgs.ini Stores the drive containing the last used message store
-c:\ private\<SID>\Mtm\Mtm Registry v2 Cache of registered MTMs, internal to message server
-?:\ private\<SID>\Mail\StoreInit.tmp Access via IPC call
-?:\ private\<SID>\Mail\storedeleted.tmp Created when message server finds and deletes a corrupt message store. Allows the UI to inform the user about the fact that the message store was corrupt.
-?\resource\messaging\bif\*.bif Registration data field with UID used in BIO framework
-
-3.2.1.3.4 How message centres display the message store
-The UI normally provides a Message Centre application to display the structure of the message store to the user. Different UIs map the structure to different views.
-
-Figure 8 Series 60 Message Centre (Composed from 2 screen shots)
-Figure 8 shows the top level view of the message centre application on a Series 60 phone. This shows that the message centre has hidden the local service and shows the standard folders at the same level as the services. Also the SMTP, SMS and MMS services are marked as hidden entries in the message store, and so do not appear in the message application.
-
-Figure 9 UIQ Message Centre
-However Figure 9 shows that the UIQ message centre has no 1-1 mapping from the structure in the message store to the structure shown to the user. Each of the message types is displayed as if its messages were contained in separate folders. Under each of these folders the user is presented with an inbox, outbox, send and drafts folder. This filtering is done in the UI layer as this functionality is not provided by the messaging API.
-3.2.1.3.5 Message Type Module Architecture
-
-Figure 10 Messaging MTM Structure (light coloured components are part of messaging subsystem)
-The MTM architecture is the plug-in scheme provided by the messaging framework to integrate different message transports into the message server. The plug-in scheme consists of four interfaces, the UI MTM, UI Data MTM, Client MTM and Server MTM. The messaging client applications loads and uses the first three which are loaded within the client’s process space. The final one the Server MTM is loaded within the message server process. The APIs for the client facing interfaces are extensible via run time type information provided by the QueryCapability API, and the InvokeAsyncFunction and InvokeSyncFunction APIs.
-3.2.1.3.5.1 UI MTM
-Handles requests from clients to view and edit messages or service settings. The MTM handles interaction with the message centre and as such the exact meaning of the APIs is defined by the UI. However common meanings are:
-• Create – Launches the editor with a new message.
-• Edit – If entry is a message this launches the editor; if entry is a service it edits the settings.
-• View – Launches the message viewer.
-• Display progress of an operation.
-3.2.1.3.5.2 UI data MTM
-This MTM provides fast access to UI components such as menu resources and bitmaps required by message centre for list views etc. Again the exact semantics are UI specific.
-There is a resource file defining UI specific functions, for example the Series 60 Messaging UI checks if the resource file contains text to display in the “New Message” menu.
-The UI data MTM also provides mapping from the message store’s TMsvEntry structure to Icons for the messaging list views and a status string, for example in the case of Nokia 9210 it is used in the outbox view to provide strings like “Resend 01:07” as shown in Figure 11. The class also provides functions to determine what operations are possible with a given entry. Examples of this are APIs that return whether the UI should allow the user to reply to the entry or to delete a service entry. The UI then uses this information to determine which menu options / short-cut keys should be allowed when the user selects a given entry.
-
-Figure 11 Nokia 9210 Outbox List View
-3.2.1.3.5.3 Client MTM
-Provides methods to create / reply and forward messages. Functions the Client MTMs provide are:
-• Create Message.
-• Reply to a Message.
-• Forward a Message.
-• Add / remove Addressees.
-• Add / remove body text.
-• Add / remove subject.
-• Add / remove attachments (the API cannot list attachments).
-The Client MTM interface is used by SendAs to provide a way of creating messages independently of the message type.
-3.2.1.3.5.4 Server MTM
-This is the final interface that makes up an MTM plug-in; it differs from the other three plug-ins in that it is loaded into the message server’s process space. The Server MTM provides access to messages under remote services. It handles connecting to remote servers to handle updating the local cache of these messages or to send messages copied to remote services when messages are copied to a remote service. The message server loads and hands off all message store operations that involve entries under a remote entry, these are the entries on the left-hand side of Figure 6.
-Functions that a Server MTM must implement:
-• Copy/MoveToLocal – called when the message server is asked to move or copy an entry that is currently under a remote service. A Server MTM might map this to retrieving a message from a remote mailbox.
-• Copy/MoveFromLocal – called when the message server is asked to move or copy from under the local service to a destination under a remote service. A Server MTM should map this to sending a message if the MTM supports sending.
-• Create, Delete, Change – called when the message server is asked to perform these operations on entries under a remote service.
-• StartCommand – this API provides a means of extending the API the Server MTM provides. Messaging clients pass a command ID and a selection of entries via the message server to the Server MTM. Examples of commands that Server MTMs might provide are: connect and synchronise the entries under a remote service with the messages on an email server, list SMS messages present on the phones SIM. These commands are MTM specific and therefore clients have to know which MTMs support which commands.
-3.2.1.3.5.5 MTM Registration
-MTMs must be registered with the message server so that clients can query what MTMs are present and the server knows which DLL to load to create a given MTM component. MTMs are registered by providing a resource file containing the MTMs UIDs, human readable name, and for each MTM interface it lists a DLL and the ordinal at which the constructor for that interface exists. The message server will search the ROM drive for MTM registration resource files on start-up and it will automatically register any MTMs found. For registration of MTMs installed on other drives, the message server provides an API to register and de-register an MTM. Registration will persist across a reboot, so an MTM only needs to be registered when it is installed on the system.
-When MTMs are registered or unregistered the message server will send events to all messaging clients with a message server session open.
-3.2.1.3.6 Message Server Client API
-The Messaging Server Client API breaks down into two categories: APIs for manipulation of the message store and utility APIs.
-3.2.1.3.6.1 Message Store manipulation APIs
-Requests from clients to modify the message store fall into three categories:
-1. Operations performed entirely with local entries (entries on the right-hand side of Figure 6) for example requests to create entries in the inbox, delete an entry from the drafts folder etc. The message server handles these operations directly.
-2. Operations that involve a remote entry (entries on the left-hand side of Figure 6) for example requests to delete an entry under a POP3 service, or copy a message to an SMTP service. The message server hands these operations off to the Server MTM that owns the service under which the remote entry is stored. The only exception to this rule is the ChangeAttributes API call. This modifies flags on an index entry and is handled by the message server for both local and remote entries. This means that a Server MTM can not rely on being called when flags like the Unread flag are changed. Note that operations can not involve two remote entries; therefore requests to copy entries between a remote service representing one POP3 account to a remote service representing another POP3 account will fail with an error.
-3. Requests that are explicitly directed at a Server MTM via the TransferCommand API. These commands are just passed to the correct Server MTM by looking up the Service ID and MTM of the first message in the selection passed into the command.
-The message server sends events when entries in the message store are modified to messaging clients that have a session open with the server.
-Where the API provides asynchronous functions to modify the message store or transfer a command to a Server MTM, the functions will return a message server operation object. This object can be used to request progress on operation or cancel the operation. Deleting the operation object returned, or closing the session used to make the request will result in the operation being cancelled, therefore a messaging client must remain running until operations it has requested have either completed or they will be cancelled. See appendix A.1 for an example of an asynchronous copy operation. If a Server MTM operating on the same remote service is already handling an operation, the message server will queue the new operation to be handled when the Server MTM becomes free. Requests for progress of operations that are queued will fail with KErrNotReady. The fact that the queue is based on the remote service ID means that you can have two Server MTMs of the same type running at the same time as long as they are operating on different services. So for example you can have two separate POP3 MTMs running synchronising different remote services with email servers.
-3.2.1.3.6.2 Utility APIs
-1. Access to MTM registries – These allow clients to construct instances of the interfaces an MTM implements.
-2. Register / Unregister an MTM.
-3. Change Drive – The message server closes the current message store and opens one on the drive specified. If no message store is present on the drive specified a new message store is created. The message sever can have only one mail store open at a time, if the current mail store is not available because a the disk the mail store is on is not present then the message server will switch the mail store back to the C: drive if an attempt is made to create a message in the inbox.
-4. Launching Editors – This launches the correct editor for a message. It is implemented by delegating the request to the UI MTM
-3.2.2 Messaging / Send As APIs
-3.2.2.1 Key Relationships and Dependencies
-
-Figure 12 SendAs Version 1 Dependencies
-SendAs version 1 and only present in releases before v9.0. SendAs uses the Messaging Client API to access the registry of Client MTMs and construct the Client MTM interfaces. The Client MTMs are then used for composing the message. SendAs requires clients to implement the MSendAsObserver interface. This interface is responsible for checking the return value of the capability queries made to Client MTMs that require a response and also for rendering message types that require it. The only message type supplied by Symbian that requires rendering is Fax, however this MTM has been removed in 8.0a and future releases.
-3.2.2.2 API Purpose - Further Elaboration
-3.2.2.2.1 SendAs API (pre – v9.0)
-The SendAs API makes use of the Client MTM interface and the Messaging Client API to provide a generic API for creating messages. Note despite the name of this component SendAs does not provide an API to send the message.
-SendAs builds a list of registered MTMs, then queries each MTM to check whether it supports sending, removing those MTMs from the list that do not support sending. This list is then provided to the messaging client application. At this point the application can add more constraints on the list of MTMs; for example it can insist the MTM supports Attachments or more than a certain size of body text. SendAs queries each of the MTMs about the requirements and will drop any MTMs from the list that does not meet them. When the application has finished adding requirements it selects one of the MTMs left in the list and uses that to compose the message, adding addresses, a subject, body text and attachments.
-SendAs supports setting a BIO Type for the message that is composed. This tells the transport that the body text represents a BIO Message. This is used when sending business cards from the contacts application as SMS messages; the contacts application puts the vCard data in the body text of the message and the transport sends it correctly. If the MTM in question supports attachments then the vCard is attached to the message.
-A new CSendAs object must be created for each message the application wishes to create.
-3.2.3 Platform Security Compliant SendAs Server (v9.0 onwards)
-
-Figure 13 SendAs Version 2 Dependencies
-From v9.0 and onwards the CSendAs has been replaced by the SendAs server component. The new SendAs server controls the access to the message store. Some of the key SendAs Server features are listed as follows.
-• Send a message once the capability policing of the client application has been completed.
-• Allow client applications to launch an editor for a specified message type.
-• Allow client applications to query the message type.
-The main client-side API is the RSendAs class. The client applications use this to connect to the Send-As server. The session object on the server-side is an instance of CSendAsSession.
-Client applications create messages using the RSendAsMessage API. Opening an RSendAsMessage object on Send-As server session creates a CSendAsMessage object in the Send-As server. There is a one-to-one mapping between an RSendAsMessage object and a CSendAsMessage object. This allows client applications to create multiple messages concurrently.
-
-3.2.4 Messaging / Schedule Send APIs
-3.2.4.1 Key Relationships and Dependencies
-
-Figure 14 Schedule Send Dependencies
-The Schedule Send Server MTM base class depends on the task scheduler to launch the schedule send executable at the correct time. To send the message with a package of data previously passed into the task scheduler by the Server MTM. The schedule send executable then uses the Messaging Client API to actually perform the requested operation.
-3.2.4.2 API Purpose - Further Elaboration
-3.2.4.2.1 Schedule Send
-The Schedule Send functionality is delivered by four components:
-Server MTM Base Class – The base class provides support to Server MTMs that wish to support scheduled operations.
-Data Structures – These are classes used to represent the data associated with a scheduled operation.
-Executable – The executable is run by the task scheduler at the scheduled time.
-The Task Scheduler – This component is part of the system libraries subsystem. Currently the SMS and Fax Server MTMs support scheduled sending.
-Clients request the Server MTM schedules operations via additional commands passed to TransferCommand API; this is passed to the Server MTM via the message server. The Server MTM packages the operation ID, a selection of message IDs, how often to poll for progress and an MTM specific buffer. It then passes this package of data to the task scheduler requesting that it launches the schedule send executable at the correct time with the packaged information.
-When the task scheduler launches the schedule send executable, it unpacks the schedule information and uses the Messaging Client API to request the Server MTM to perform the operation.
-Schedule Send supports a retry mechanism if the operation fails. The Server MTM has a resource file containing a mapping from the error codes the operation can fail with and actions to be performed. For example the SMS resource file has a mapping such that if the operation fails with an error code indicating a bad phone number the SMS will be set to failed and left in the outbox. Whereas if it fails with a error code indicating temporary network failure the send operation will be scheduled to be resent later with a maximum of three retries.
-3.2.5 Messaging / Watchers APIs
-3.2.5.1 Key Relationships and Dependencies
-
-Figure 15 Watcher Dependencies
-The watcher executable’s dependency on the message server is the result of a performance measure. The watcher process creates a message server session before initialising each of the watcher plug-ins and closes the session when it has finished. This keeps the message server running during initialisation avoiding starting and stopping the message server if each watcher plug-in opens and closes sessions.
-3.2.5.2 API Purpose - Further Elaboration
-The watcher framework consists of an executable that is launched when the device boots. The component that is responsible for launching it depends on the UI family. When the watcher.exe is launched it will load each DLL in z:\system\libs\watchers which has a second UID as KWatcherUid and calls the first DLL entry point to construct a CActive object.
-From v9.0 and onwards watcher DLLs are found by scanning the directory \resource\messaging\watchers for registry files. These files contain the name of a watcher DLL that can be loaded from ROM i.e. z:\sys\bin.
-The framework has retry behaviour if the first entry point leaves, in this case the watcher framework will start a timer and try and construct the watcher object 10 seconds later. Five attempts are made before the watcher plug-in is assumed to have failed completely. Once the watcher framework has constructed all the watchers it starts the active scheduler which should never exit.
-Watcher plug-ins typically make a request to another subsystem such that they will be completed when an external event like a fax line ringing or an SMS being received occurs. When the watcher has completed processing the request it will wait for the next event.
-No support for starting / stopping watchers is provided. This is a limitation that makes watchers unsuitable for operations like listening for messages beamed via IR, as the watcher should only run while the IR port is active.
-3.2.6 Messaging / Message URL Handler APIs
-3.2.6.1 Key Relationships and Dependencies
-
-Figure 16 Message URL Handler Dependencies
-3.2.6.2 API Purpose - Further Elaboration
-The Message URL Handler provides support for creating messages and launching messaging editors from URLs such as mailto:infobot@example.com?subject=current-issue. Note there is no dependency between the Message URL Handler application which processes the URLs and the Message URL Handler recognisers which maps from URLs to mime types.
-3.2.6.2.1 Message URL Handler Application
-This is a Symbian OS application that registers with the application framework that it can handle the mime types: x-epoc-url/fax, x-epoc-url/mailto and x-epoc-url/sms. When launched with a URL it will parse the URL to retrieve the address and other header fields and then use the SendAs API to create a new message with the correct address, headers etc. The application then uses the APIs in the MturUtils class provide by the mtmbase component in the messaging framework to launch the correct editor for the given message type. The application is marked as hidden and therefore should not be listed by UIs in application browsers.
-3.2.6.2.2 Message URL Recognisers
-This is a plug-in to the recogniser framework it will be called when the application framework wishes to recognise a file. Recognisers are called with the file name, in this case a URL, and a buffer containing the start of the file. The message URL recogniser compares the start of the URL with the URL schemes it recognises, if it finds a URL scheme it knows about it maps it to a mime type. The recogniser ignores the buffer passed in.
-Schemes recognised:
-Scheme Mime type
-mailto: X-Epoc-Url/mailto
-fax: X-Epoc-Url/fax
-sms: X-Epoc-Url/sms
-mms: X-Epoc-Url/mms
-See the application framework architectural description for more information on recognisers [R2].
-3.2.7 Messaging / SMS APIs
-3.2.7.1 Key Internal Relationships and Dependencies
-
-Figure 17 SMS Internal Dependencies
-3.2.7.2 Key External Relationships and Dependencies
-
-Figure 18 SMS External Dependencies
-3.2.7.3 API Purpose - Further Elaboration
-3.2.7.3.1 SMS Watchers
-The SMS watchers are made up of two watchers, the nbswatcher.dll and the wapwatcher.dll, and some common base classes in biowatcher.dll. The watchers listen for incoming messages from the SMS stack, part of the nbsprotocols subsystem [R3], and the WAP stack part of the WAP-Stack subsystem [R4].
-3.2.7.3.1.1 NBS Watcher
-The NBS watcher handles reception of SMS messages. When initialised by the watcher framework (see section 3.2.4) the watcher queries the bio messaging database for bio messages that are listed as having a type of ENbs. For each of these bio messages the watcher creates an object that opens a connection to the SMS stack and waits for the particular message type. The message types are either defined by the port number the message will be received on or by a string to watch for at the start of the message. For example Internet Access Configuration Point messages are start with “//SIAP11” and vCards are received on port 226. Finally the watcher listens for all other messages received from the SMS stack.
-When the NBS Watcher receives a non-class 2 SMS message it creates a new entry under the global inbox in the message store. For class 2 messages the entry is created in the class 2 folder as defined by the SMS settings, this may also be the global inbox. The details field of the entry is used to store the phone number of the incoming message or the name of the sender if the watcher finds a match for the phone number in the contacts database. The description field is used to store the first N characters of the SMS message, where N is defined in the SMS settings, or for bio messages the description as retrieved from the bio database. Bio messages also have the BioType field set to the UID of the bio message as retrieved from the bio database. The CSmsHeader class, which is a wrapper around the CSmsMessage class provided by the nbprotocols subsystem [R3], is used to externalise the SMS message to the entry’s CMsvStore. The watcher also places a copy of the body text of the message in the rich text stream of the entry’s CMsvStore.
-The NBS Watcher is also responsible for handing special SMS types including:
-• Replace Type Messages – When the watcher receives a message of this type it will scan the folder the message would have been delivered to for messages that have a matching protocol ID and from address. For each of the messages it checks whether the time stamps from the service centre and discards the older message.
-• Message Indications – The watcher can listen for incoming message waiting indications. The CSmsSettings class defines whether the watcher will listen and whether it will deliver the messages to the inbox or discard them. If the watcher is configured to listen for messages then it will use the SMS utilities in the SMS Client MTM to decode the message to determine the notification type and number of messages, e.g. 3 Email messages waiting, the strings for these messages are in the smss.rss resource file.
-• Delivery Reports – As with Message Indications the watcher can be configured to listen for these and again the SMS utilities get a string from the smss.rss resource file to put in the description field.
-The NBS Watcher handles changes to the bio database using the observer mechanism provided by the bio message database to observe when bio message types are added or removed and starting or stopping the object watching for that bio message type.
-3.2.7.3.1.2 WAP Watcher
-The WAP watcher listens for incoming messages from the WAP stack using the WAP message API [R4]. To determine ports to use to listen for messages the watcher queries the bio message database for bio message types EWsp, EWspSecure, EWap, EWapSecure and registers as an observer of the bio database and so will listen for new bio message with these types as they are added. The watcher stores the messages in the global inbox tagged with the bio type listed in the bio message database.
-3.2.7.3.2 SMS Client MTM
-The SMS Client MTM implements the standard set of Client MTM APIs described in Client MTM. In addition it provides:
-• Access to the CSmsHeader object that is used to represent the SMS message.
-• Access to the SMS settings stored in the associated SMS service.
-• The APIs required by Send As to allow Send As to create SMS messages including setting the bio type of the message to allow clients of Send As to send bio messages such as vCards and vCals. The data of the bio message is stored in the body text of the SMS message.
-• Simple check for valid SMS addresses, and SMS address is considered valid if it contains at least one digit.
-• Reading and writing SIM parameters.
-3.2.7.3.3 SMS Utilities
-These provide:
-• Classes to represent and store SMS messages (CSmsHeader), and SMS settings (CSmsSettings, CSmsMessageSettings) and a SMS number (CSmsNumber).
-• The CSmsHeader class contains and allows clients to access the CSmsMessage class that the nbsprotocols subsystem provides. This contains the entire SMS message and not just the header.
-• Functions to generate descriptions and details fields to store with SMS messages, including decoding special messages such as message indication and status report messages, reading resource file for descriptions strings of special messages, using the contacts database to replace phone numbers with names.
-• API to validate a GSM number.
-• Find the TMsvId of the SMS service entry.
-3.2.7.3.4 SMS Server MTM
-3.2.7.3.4.1 Sending Messages
-The SMS Server MTM handles sending of SMS and WAP messages via the SMS stack and the WAP stack. To support this it implements the CopyFromLocal API inherited from the Server MTM base class. It implements this as sending SMS messages and moving successfully sent messages to the Sent folder. When sending the SMS message the Server MTM checks the bio type of the message and uses the bio database to check the transport type for the bio message. The MTM supports ENbs that is sent via the SMS stack and EWap, EWapSecure that are sent via the WAP stack. The MTM does not support EWsp or EWspSecure although the watchers do support receiving them.
-If a message fails to send, sending is retried according to the settings in the smss.rss resource file as described in the schedule send section 3.2.3.
-3.2.7.3.4.2 Scheduling Messages
-The SMS Server MTM implements scheduled sending API by sub-classing from the schedule send Server MTM (see section 3.2.3). It accepts requests from clients either via the SMS Client MTM InvokeAsync API or via the CMsvSession::TransferCommand API to schedule messages to be sent or to delete existing schedules. When it receives a request to schedule a message it packages up the command and uses the scheduled send functionality to request that the task scheduler ask it to send the messages at a future point in time.
-3.2.7.3.4.3 Phone Store
-The phone store is the name given to storage of SMS messages outside of the message store. In the case of GSM phones this is the SIM. The SMS Server MTM accepts requests from clients to copy/move messages to and from the SIM and delete messages from the SIM. For example when copying to the SIM it packages up the SMS message and passes it to the SMS stack with a request to write it to the SIM. If the class2 folder has been set in the SMS settings class then the Server MTM will copy the SMS message to the SIM and then update the SMS message in the message store with details of the slot on the SIM that has been used to store the SMS and the fact that it is stored on the SIM.
-3.2.7.3.4.4 SIM Parameters
-The Server MTM provides functions to read / write SIM parameters, again these requests are passed to the SMS stack to be processed.
-3.2.8 Messaging / CDMA SMS APIs
-3.2.8.1 Key Internal Relationships and Dependencies
-
-Figure 19 CMDA SMS Internal Dependencies
-3.2.8.2 Key External Relationships and Dependencies
-`
-Figure 20 CDMA SMS External Dependencies
-3.2.8.3 API Purpose - Further Elaboration
-3.2.8.3.1 CDMA SMS Watchers
-The CDMA SMS watchers are made up of six watchers, the cdmanbswatcher.dll, vmnwatcher.dll, wemtwatcher.dll, wmtwatcher.dll, wptwatcher.dll, and the wapwatcher.dll, and some base classes in biowatcher.dll and cdmasocketwatcher. While the WAP watcher is common for both GSM and CDMA, the other watchers: CDMA NBS watcher, VMN watcher, WEMT watcher, WMT watcher, and the WPT watcher are used for CDMA only. The watchers listen for incoming messages from the CDMA SMS stack, part of the nbsprotocols subsystem [R3], and the WAP stack part of the WAP-Stack subsystem [R4].
-3.2.8.3.1.1 CDMA NBS Watcher
-The CDMA NBS watcher is similar to the NBS watcher and it handles bio messages defined in bio database. The CSmsHeader class is extended to wrap around the CCdmaSmsMessage class provided by the nbprotocols subsystem [R3], and is used to externalise the CDMA SMS message.
-For handling special CDMA SMS type, the CDMA NBS watcher is responsible for handling Message Indications as described in section 3.2.7.3.1.1 NBS Watcher.
-3.2.8.3.1.2 WAP Watcher
-The GSM WAP watcher is used to handle CDMA WAP message as well. The WAP watcher listens for incoming messages from the WAP stack, which can listen from the CDMA SMS stack or GSM SMS stack as appropriate. See 3.2.7.3.1.2 for more info about WAP watcher.
-3.2.8.3.1.3 Other CDMA Watchers
-The VMN watcher, WEMT watcher, WMT watcher and WPT watcher are CDMA watchers that handle reception of CDMA SMS messages. All CDMA SMS messages are associated with a teleservice. Therefore, each of the CDMA watchers is responsible for handling one teleservice: VMN watcher handles VMN SMS messages, WEMT watcher handles WEMT SMS messages, WMT watcher handles WMT SMS messages, and WPT watcher handles WPT SMS messages. The CSmsHeader class is reused to externalise the CDMA SMS message.
-The CDMA watchers are also responsible for handling special SMS types including:
-• Duplicate Message – When the watcher receives a duplicate message, it will discard the duplicate message as defined by the CDMA service settings.
-• User Acknowledge – The watcher can listen for user acknowledgment message of its teleservice type.
-• Delivery Acknowledge – The watcher can listen for delivery acknowledgment message of its teleservice type.
-• Read Acknowledge – The watcher can listen for read acknowledgment message of its teleservice type.
-3.2.8.3.2 CDMA SMS Client MTM
-The CDMA SMS Client MTM implements the standard set of Client MTM APIs described in Client MTM. In addition it provides:
-• Access to the CSmsHeader object that is used to represent the SMS message.
-• Access to the SMS settings stored in the associated SMS service. These settings are store in file store pre v9.0 but stored in Central Repository from v9.0 onwards.
-• The APIs required by Send As to allow Send As to create SMS messages including setting the bio type of the message to allow clients of Send As to send bio messages such as vCards and vCals. The data of the bio message is stored in the body text of the SMS message.
-• Simple check for valid SMS addresses, and SMS address is considered valid if it contains at least one digit.
-• Reading and writing SMS messages to R-UIM.
-3.2.8.3.3 CDMA SMS Utilities
-The CDMA version of SMS utilities are binary compatible with the GSM version of SMS utilities. But the classes that store SMS Message (CSMSHeader), and SMS settings (CSmsSettings, CSmsMessageSettings) and SMS number (CSmsNumber) are extended to store CDMA information. The CSmsHeader class is extended to contain and allow clients to access the CCdmaSmsMessage in addition to the CSmsMessage. Other functions provided by the GSM SMS Utilities is also provided by the CDMA version of SMS utilities, see 3.2.7.3.3 for information about GSM SMS Utilities.
-3.2.8.3.4 CDMA SMS Server MTM
-3.2.8.3.4.1 Sending Messages
-The CDMA SMS Server MTM handles sending of CDMA SMS and WAP messages via the CDMA SMS stack and the WAP stack. To support this it implements the CopyFromLocal API inherited from the Server MTM base class. It implements this as sending SMS messages and moving successfully sent messages to the Sent folder. When sending the CDMA SMS message the Server MTM will use the appropriate teleservice type. The MTM supports ENbs that is sent via the SMS stack and EWap, EWapSecure that are sent via the WAP stack. The MTM does not support EWsp or EWspSecure although the watchers do support receiving them.
-If a message fails to send, sending is retried according to the settings in the smss.rss resource file as described in the scheduled send section 3.2.4.
-3.2.8.3.4.2 Scheduling Messages
-The CDMA SMS Server MTM implements scheduled sending API by sub-classing from the schedule send Server MTM similar to implemented in the GSM SMS Server MTM. See 3.2.7.3.4.2 for more information.
-3.2.8.3.4.3 Phone Store
-In the case of CDMA phones, phone store can be phone-based storage or R-UIM based storage. The CDMA SMS Server MTM accepts requests from clients to copy/move messages to and from the phone/R-UIM and delete messages from the phone/R-UIM. For example when copying to the R-UIM it packages up the SMS message and passes it to the CDMA SMS stack with a request to write it to the R-UIM.
-3.2.8.3.5 Configuration for using CDMA SMS MTM
-The CDMA messaging components currently only support single mode, but it is designed such that it can become multimode in the future. Currently, -Dcdma option is used to for selecting CDMA mode for using emulator and building ROM.
-
-
-3.2.9 Messaging / Email APIs
-3.2.9.1 Key Internal Relationships and Dependencies
-
-Figure 19 Email Internal Dependencies
-
-3.2.9.2 Key External Relationships and Dependencies
-
-Figure 20 Email External Dependencies
-3.2.9.3 API Purpose - Further Elaboration
-3.2.9.3.1 Email Overview
-The Email plug-ins consist of a set of utilities and MTMs for POP3, IMAP4 and SMTP. For each email account a pair of services entries is created in the message store. For a POP3 account there will be an SMTP service and a POP3 service, for an IMAP4 account there will be an SMTP service and as IMAP4 service. These entries are used to store the settings for the email transport. Each of the service entries has its related ID set to the other member of the pair. The SMTP service is created invisible so the user only sees the POP3 or IMAP4 service entry, copying a message to the SMTP service will cause the SMTP Server MTM to attempt to send the message. The POP3 and IMAP4 MTMs provide functionality to synchronise with a remote email server this is achieved by extending the Client MTM interface via the InvokeAsync API. Synchronisation of a POP3 or IMAP4 account will result in copying headers and optionally body text and attachments from the email server and creating message entries under the POP3 or IMAP4 service entry.
-Email messages are represented in a common format whether they are being sent via SMTP or downloaded via POP3 or IMAP4. The email client utilities provide the classes for creating and manipulating the entry structure used to store emails. The email server side utilities provide classes to convert between the entry structure used to store emails in the message store and RFC2822 email messages sent to SMTP servers and retrieved from POP3 servers. IMAP4 email messages are parsed by the email server and the IMAP4 Server MTM requests and stores the individual parts of the messages.
-3.2.9.3.2 Email Client Utilities
-The email client utilities are part of the imcm DLL and provide classes for:
-• Storage of email messages including mime headers, RFC2822 headers, attachments, body text and encoding information in the message store
-• Manipulating email messages, for example adding attachments, replying etc.
-• To wrap up the character converters used to convert between standard character sets and Unicode. These make use of the charconv component that is part of the system libraries subsystem.
-• Storage of Email settings in the message store.
-• Progress information for email operations.
-The utilities are used directly by clients to access parts of email messages for display. CImEmailMessage provides the functionality used by clients displaying email messages, including listing attachments, getting body text and resolving URIs in M-HTML messages.
-The Email Client MTMs use the utilities when they are asked to create, reply to and forward messages CImEmailOperation provides the functionality to perform these operations. Each email message is represented by a parent message entry and then entries to represent mime folders and mime parts, see Figure 7 for an example, so adding or deleting mime parts involves walking the tree of entries and inserting / removing entries as appropriate.
-3.2.9.3.3 Email Server MTM Utilities
-The Email Server MTM Utilities are responsible for generating and parsing of RFC2822 format email messages and providing an API to wrap up a TCP/IP connection to a remote email server.
-• Parsing of RFC2822 Email Messages – The utilities provide an API that accepts the text of an RFC2822 email message a line at a time and stores the email message in messaging’s internal format for email messages. See the Email Client Utilities for details of this format. The API handles storing of RFC2822 headers, MIME headers, decoding of Base64 encoded or uuencoded attachments and decoding of text received in character sets supported by the charconv component. This API is only accessible to Server MTMs, as it requires classes that can only be instantiated while running within the message server process. See the Messaging Functional Specification [R1] for detail on which email specifications the utilities support.
-• Generation of RFC2822 Email Messages – The utilities provide an API to convert an email in messaging’s internal format into an RFC2822 email message. The API provides access to the RFC2822 text a line at a time for streaming to an SMTP server. The exact format of the email depends on the settings passed in; the API can generate plain RFC2822 email messages with uuencoded attachments, MIME email messages with Base64 encoded attachments, or M-HTML email messages with Base64 encoded attachments. See the Messaging Functional Specification [R1] for detail on which email specifications the utilities support.
-• TCP/IP socket wrapper – The utilities provide a class that abstracts a TCP/IP socket supplied by the networking subsystem into an API that supports sending and receiving lines of text to / from a remote server. This API is used to connect to remote email servers by each of the email Server MTMs. The API can either create insecure or secure sockets enabling the SSL encryption provided by the networking subsystem. It also supports changing an insecure socket into a secure socket, this enables the email Server MTMs to implement email protocols where the initial connection to the server is insecure and then a secure socket is negotiated before sending or requesting any sensitive information.
-3.2.9.3.4 POP3 MTMs
-The POP3 MTMs implements the functionality to synchronise the local message store with a remote POP3 email server.
-3.2.9.3.4.1 Client MTM
-The POP3 Client MTM implements the standard Client MTM APIs and other extensions:
-• Reply to, forward – These are accessible via the ReplyL and ForwardL APIs of a Client MTM and are implemented as calls to the email utilities class CImEmailOperation.
-• Reply to, forward, create new messages, create receipts and forward as attachment – These are accessible as commands available via the InvokeAsyncFunction API of the Client MTM, they are implemented as calls to CImEmailOperation.
-• Connecting, disconnecting and copying email while connected – These operations are accessible as commands available via the InvokeAsyncFunction API of the Client MTM, they are implemented as calls to the POP3 Server MTM.
-• Querying connection status – This command lets clients know whether the POP3 Server MTM is connected to an email server, and is available via the InvokeAsyncFunction API of the Client MTM. The Client MTM requests the information from the Server MTM.
-• Compound operations – The Client MTM provides functionality to wrap up connecting to email servers, copying / moving new messages or a selection of messages, and then optionally disconnecting. These commands are available via the InvokeAsyncFunction API of the Client MTM. The Client MTM implements this by using the CImPOP3GetMail class which requests the correct sequence of operations from the Server MTM, waiting for each operation to complete before requesting the next one.
-• Send on next connection If the Client MTM gets a request to connect to an email server it will check whether the POP3 settings. If send on next connection is requested it will launch the autosend.exe executable (see section 3.2.7.3.7) to handle sending messages waiting in the outbox.
-• Offline operations – The POP3 Client MTM has a command to cancel offline operations, this is available via the InvokeAsyncFunction API of the Client MTM. The Client MTM passes the request to the Server MTM.
-3.2.9.3.4.2 Server MTM
-The POP3 Server MTM handles the communication with the remote POP3 server and implementation of the POP3 protocol. The MTM uses CImTextServerSession to handle the communication with the email server and CImRecvConvert to parse the email messages downloaded, both are provided by the Email Server MTM Utilities.
-• Connect – The POP3 Server MTM will open a socket to the email server using CImTextServerSession and login user the username / password in the POP3 settings. After a successful connection the Server MTM will attempt to synchronise the current state of headers stored on the email server with the set stored in the message store and then start any pending offline operations. After the connect operation has completed the Server MTM will inform the message server that it is expecting more operations via the CommandExpected API and therefore the message server will not delete and unload the Server MTM.
-• Populate Message – The POP3 Server MTM treats requests to copy a message from and to the POP3 service as a request to download the full message.
-• Offline operations – When the POP3 Server MTM receives a request to copy, move, or delete and is not connected to a POP3 email server the Server MTM will store the operation in the CMsvStore of the entry being modified and perform the operation on the next connection to the email server.
-• Disconnect – When disconnecting from a remote email server the POP3 MTM will run any pending offline operations stored. After the disconnect operation completes the Server MTM will allow the message server to delete and unload the Server MTM by setting the CommandExpected API to false.
-3.2.9.3.5 IMAP4 MTMs
-The IMAP4 Server MTM implements the functionality to synchronise the local message store with a remote IMAP4 email server.
-3.2.9.3.5.1 Client MTM
-The IMAP4 Client MTM implements the standard Client MTM APIs and other extensions:
-• Connecting, disconnecting, synchronising, un/subscribing folders – These operations are accessible as commands available via the InvokeAsyncFunction API of the Client MTM, they are implemented as calls to the IMAP4 Server MTM.
-• Send on next connection – If the Client MTM gets a request to connect to an email server it will check whether the IMAP4 settings. If send on next connection is requested it will launch the autosend.exe executable (see section 3.2.7.3.7) to handle sending messages waiting in the outbox.
-• Reply to, and forward messages – These are accessible via the ReplyL and ForwardL APIs of a Client MTM and are implemented as calls to the email utilities class CImEmailOperation.
-• Reply to, forward, create new, create receipt, forward as attachment – These are accessible as commands available via the InvokeAsyncFunction API of the Client MTM, they are implemented as calls to CImEmailOperation.
-• Querying connection status – These commands let clients know whether the IMAP4 Server MTM is connected to an email server and whether it is currently processing a request. They are available via the InvokeAsyncFunction API of the Client MTM. The Client MTM requests the information from the Server MTM.
-• Compound Connection and synchronisation – The IMAP4 Client MTM provides a compound operation that connects and synchronises with an IMAP4 server. This operation is implemented as a client side object that combines requests to the IMAP4 Server MTM. The client side operation can complete the client request either after the connection, after the connection + sync or after the connection + sync + disconnect. The client will keep requesting that the inbox be resynchronised at a configurable interval so new messages received in the inbox on the server will appear under the IMAP4 inbox. The CImapConnectAndSyncOp class handles these compound operations.
-• Compound Connect and copy / move / populate messages – The IMAP4 Client MTM provides a compound operation that connects to an IMAP4 server and copies moves or populates messages. The implementation is provided by the CImImap4GetMail class which makes calls back into the IMAP4 Client MTM.
-• Offline operations – The IMAP4 Client MTM has a command to cancel offline operations, this is available via the InvokeAsyncFunction API of the Client MTM. The Client MTM passes the request to the Server MTM.
-3.2.9.3.5.2 Server MTM
-The IMAP4 Server MTM handles the communication with the remote IMAP4 server and implementation of the IMAP4 protocol. The MTM uses CImTextServerSession to handle the communication with the email server. The IMAP4 Server MTM opens two connections to the IMAP4 server this enables users to download messages while the Server MTM is performing a background synchronisation if requested by the Client MTM.
-• Connect – The IMAP4 Server MTM will open a socket to the email server using CImTextServerSession and login using the username / password in the IMAP4 settings. After a successful connection the Server MTM will optionally attempt to synchronise the current state of headers stored on the email server with the set stored in the message store and then start any pending offline operations. After the connect operation has completed the Server MTM will inform the message server that it is expecting more operations via the CommandExpected API and therefore the message server will not delete and unload the Server MTM.
-• Copy, Move messages – The IMAP4 Server MTM supports copying and moving messages between folders on the IMAP4 server and between the IMAP4 server and local folders.
-• Delete messages – The IMAP4 Server MTM will mark the email as deleted on the server; however it will not be deleted until the IMAP4 Server MTM disconnects from the server.
-• Folders – The IMAP4 Server MTM will allow folders to be subscribed, unsubscribed, renamed, copied, moved, and created within the IMAP4 service. Subscribing to a folder means that it will be visible to the user and synchronised with the remote server. The inbox is always subscribed.
-• Offline operations – When the IMAP4 Server MTM receives a request to copy, move, or delete and is not connected to an IMAP4 email server the Server MTM will store the operation in the CMsvStore of the entry being modified and perform the operation on the next connection to the email server.
-• Disconnect – When disconnecting from a remote email server the IMAP4 MTM will run any pending offline operations stored. After the disconnect operation completes the Server MTM will allow the message server to delete and unload the Server MTM by setting the CommandExpected API to false.
-
-3.2.9.3.6 SMTP MTMs
-The SMTP MTMs provide functionality to send email messages. They are made up of the Client MTM that is part of the imcm DLL and the Server MTM.
-3.2.9.3.6.1 Client MTM
-The SMTP Client MTM implements the standard Client MTM APIs including the functions required to allow clients of Send As to create email messages.
-3.2.9.3.6.2 Server MTM
-The SMTP MTMs provide functionality to send email messages; it interprets requests to copy entries to an SMTP service as a request to send those messages. In addition it responds to two extended commands via the StartCommand Server MTM interface. These commands are KSMTPMTMIsConnected that responds with whether the Server MTM is currently connected to a remote SMTP server and KSMTPMTMSendOnNextConnection which performs the same operation as copying a selection of messages to an SMTP service. The only difference between the copy operation and the KSMTPMTMSendOnNextConnection operation is that the latter can be called without a selection of messages.
-When the Server MTM receives a request to send messages it builds a selection of messages consisting of the messages passed into the operation and any messages waiting in the outbox to be sent. To determine which messages in the outbox are waiting to be sent the SMTP server checks for messages that have the same service ID as the destination of the send operation and have a sending state of KMsvSendStateWaiting, KMsvSendStateScheduled or KMsvSendStateResend. This means that any request to send messages may result in more messages being sent than explicitly listed in the selection passed to the send operation.
-The Server MTM restores its settings from the SMTP service it has been asked to copy the messages to. Then it connects to the SMTP server using the CImTextServerSession class in the Email Server MTM Utilities, passing in the SMTP server address and TCP/IP port number from the SMTP settings. Then for each message to be sent the Server MTM uses the Email Server MTM utilities to generate an RFC2822 format message to send to the SMTP server, the RFC2822 text is generated on the fly as the data is sent to the SMTP server. If the SMTP server accepts the message to be sent then the Server MTM moves the message to the sent folder and sets its sending state to sent. If the SMTP server rejects the message then the Server MTM leaves the message in the outbox and sets the sending state to failed. Separate emails are generated for BCC recipients to ensure that the SMTP server doesn’t incorrectly include BCC recipients in emails sent to addresses in the To and CC fields of the email.
-3.2.9.3.7 Autosend
-The Autosend component is an executable that is kicked off by the POP3 and IMAP4 Client MTMs if the send on next connection setting is set. This executable will just make a request to the SMTP Server MTM to send messages associated with the SMTP service related to the POP3 or IMAP4 service, wait for the operation to finish and then exit.
-3.2.10 Messaging / MMS APIs
-The MMS module has been removed from v9.0 and onwards.
-3.2.10.1 Key Internal Relationships and Dependencies
-
-Figure 21 MMS Internal Dependencies
-3.2.10.2 API Purpose - Further Elaboration
-3.2.10.2.1 MMS Overview
-The MMS MTM provides functionality for creating, accessing, sending and receiving MMS messages. Messages are sent and received without the client application needing to open or close any kind of session. The management of the MMS session is handled entirely within the MTM.
-MMS clients are alerted when a new message is available for download via the WAP Push mechanism. A WAP push watcher is provided to handle these notifications. After the notification the message can be downloaded over WSP or HTTP. Messages are sent by posting the data over WSP or HTTP. The Symbian MMS implementation can handle sending or receiving MMS message over either protocol.
-MMS messages are based on the MIME format but are binary encoded using WSP. Note that MMS messages are encoded in this way even if they are posted over HTTP as opposed to WSP. The codec component is responsible for this encoding and decoding.
-3.2.10.2.2 MMS Utilities
-3.2.10.2.2.1 Key External Relationships and Dependencies
-
-Figure 22 MMS Utilities External Dependencies
-The MMS utilities provide the message and settings encapsulation classes. The MMS settings and messages are stored in the message store, the MMS utilities provide the interfaces to access this data.
-3.2.10.2.2.2 Settings
-The settings functionality provided by the MMS utilities allows the messaging client to persist MMS settings in the message store. Supported settings include:
- MMSC (MMS server) address
- WSP or HTTP transport
- Autofetch messages on notification
- Preferred IAP for the MMS network connection
-The settings functionality is also used by the server MTM to retrieve the settings prior to message sending or fetching.
-3.2.10.2.2.3 Message Encapsulation
-The message classes provide the message access functionality. Messages can be created, stored, restored and read using these classes. Functionality includes:
- Adding media objects to the message
- Enumerating through media objects
- Adding recipients, subject line, etc. to a message
- Adding other headers to the message, e.g. expiry date
- Finding the appropriate media object for a given URI in the SMIL part (URI resolving)
-The message data is stored in the message store using one entry per message regardless of the number of media objects added to the message. This is preferable to using multiple message entries as it is faster and uses less disk space.
-Most of the message access code is common whether it is being used on the client or server side, however some parts of it are specific. For this reason it is essential that the appropriate client or server side CMmsMessage derived class is used.
-3.2.10.2.3 MMS Watcher
-3.2.10.2.3.1 Key External Relationships and Dependencies
-
-Figure 23 MMS Watcher External Dependencies
-
-The MMS watcher plug-in is responsible for intercepting incoming MMS notifications and delivery reports then taking the appropriate action. It is implemented as a WAP Push watcher plug-in.
-When an MMS notification is received an MMS entry is created in the inbox using the MMS utilities. At this point the entry has its incomplete flag set. If the settings have the autofetch option selected then the MMS watcher initiates the fetch operation via the MMS client MTM.
-If a delivery report is received then the delivered flag is set on the appropriate sent message. If an outgoing message was sent to several recipients then there will be several delivered flags. A delivery report from each recipient will set the appropriate delivered flag.
-3.2.10.2.4 MMS Client MTM
-3.2.10.2.4.1 Key External Relationships and Dependencies
-
-Figure 24 MMS Client MTM Dependencies
-As with most other MTMs the MMS client MTM provides access to the server MTM functionality for messaging clients. It also implements the Send-As interface and reply and forward functionality.
-3.2.10.2.4.2 Send-As Implementation
-The Client MTM Send-As interface is implemented in the MMS Client MTM. The implementation differs slightly from other MTMs because additional presentation content may be generated depending on the media objects that are added. When simple combinations of images, sounds and text are added a SMIL presentation is generated to link them together. This is preferable to simple adding the objects as attachments where some clients render them as a list of files and others fail to render them at all.
-The SMIL data is constructed using templates stored in resource files, the GMXML (SMIL) composer is not used.
-3.2.10.2.4.3 Reply / Forward
-The Client MTM can be used to create replies to received messages or to create forwarded responses. The reply and forwarding operations are performed asynchronously.
-3.2.10.2.5 MMS Server MTM
-3.2.10.2.5.1 Key External Relationships and Dependencies
-
-Figure 25 MMS Server MTM Dependencies
-The Server MTM is the most complicated part the MMS implementation. It handles all of the state information required to send or fetch MMS messages. It is also responsible for managing the HTTP or WSP session and the connections to the phone network.
-3.2.10.2.5.2 Operations
-All MMS server MTM functionality is encapsulated in operations. An operation consists of the setup of a session, the sending, fetching and acknowledgements when appropriate, it then closes the session. The messaging client initiates an operation with a single call to the Client MTM, there is no need for the messaging client to explicitly establish the session or to know about the internal states. However, these internal states are available to the messaging client via the progress structure if this level of user feedback is required.
-Two types of operation are supported, background and foreground:
-A maximum of one foreground operation can be running at any one time. The messaging client can poll the server MTM for the progress of a running foreground operation, likewise it can cancel it if necessary.
-A background operation does not support progress information and can not be cancelled by the messaging client. It is possible to initiate background operations even if other background or foreground operations are pending. However, background operations are queued and a maximum of one will actually be running at any one time.
-The MMS watcher uses a background operation to perform automatic fetching. While the background autofetch is occurring it is still possible to start a foreground operation (such as sending a message) if required.
-3.2.10.2.5.3 Session and Connection Management
-The server MTM uses the HTTP Transport Framework to enable the HTTP or WSP session. HTTP or WSP can be selected at runtime by selecting the appropriate option in the settings. The server MTM is responsible for reading any HTTP proxy details from the CommDB and passing it to the HTTP framework. See the http transport framework architectural description for more information on recognisers [R5]
-The server MTM is also responsible for managing the connection to the phone network. Connections are opened when required using the RConnection mechanism, multi-homing is supported provided that the underlying HTTP framework transport plug-in also supports it.
-3.2.10.2.6 MMS Codec
-The MMS Server MTM is in charge of the state transitions, connection, session, the actual posting and fetching of the data from them, however it does not encode or decode the MMS PDUs. The encoding and decoding is performed by the MMS Codec.
-For decoding the Server MTM passes the Codec the MMS PDU data in a descriptor for processing. If the PDU contains a received MMS message then the message entry is updated with the decoded MMS data.
-For encoding the Server MTM passes a reference to the message store entry containing the un-encoded MMS data. The Codec then encodes it and returns the PDU to the Server MTM in a descriptor.
-
-
-3.2.11 Messaging / BIO APIs
-3.2.11.1 Key Internal Relationships and Dependencies
-
-Figure 26 BIO Message Internal Dependencies
-3.2.11.1.1.1 Key External Relationships and Dependencies
-
-Figure 27 Bio Parser External Dependencies
-
-3.2.11.2 API Purpose - Further Elaboration
-3.2.11.2.1 BIO Overview
-The BIO messaging components have been designed to unify and simplify the way in which system messages are processed. In this context ‘system messages’ refers to messages received on the device which are intended to update some attribute(s) on the system as opposed to being presented to the user. Examples of these types of messages include vCards which are parsed and then displayed to the user and when accepted modify the users contact database and OTA configuration messages which are again parsed before display to the user and if accepted create email accounts or internet access points.
-The BIO messaging components can be broken down into three groups:
-1) The BIO MTM - To initiate the parsing and processing of BIO messages
-2) The BIO Database - Maps port numbers, MIME types, etc. to bio types in order to identify the type of incoming BIO messages.
-3) The BIO Parsers - To parse and process the BIO message payload
-BIO messages are not receive by the bio messaging framework, they come over other message transports for example see section 3.2.6.3.1 on the SMS watchers which describes how the SMS watchers receive bio messages and use the bio framework to tag the messages with the correct bio id.
-3.2.11.2.2 BIO MTM
-The BIO client MTM is called by the messaging client to parse or process a BIO message that has been saved in the message store. It is the responsibility of a BIO watcher to save the BIO message with the BIO flag and the appropriate BIO type set.
-The BIO client MTM does very little, its primary task is to pass on the messaging client request to the server MTM. Two operations are supported, parse and process.
-The messaging client is expected to initiate the parsing of the BIO message before processing it. The parsing step involves analysing the data and storing it in a form that can be displayed to the user via the BIO message viewer.
-Once the message has been parsed the messaging client can initiate the processing of the message.
-The BIO server MTM is responsible for deferring the parsing and processing to the appropriate BIO parser. The behaviour for the parsing and processing steps varies between parsers. See the BIO Parsers section for more information.
-The bio MTM does not support sending messages and therefore does not support reply / forwarding messages. For bio messages sending / reply etc. is supported by the particular MTM that the message is sent over, for example SMS.
-3.2.11.2.3 BIO Database
-The BIO database is used to identify the type of BIO messages. It maps message attributes such as port number, MIME type or leading string to a BIO type. These are attributes are then used by clients of the bio framework to know what ports to listen for messages on. For example the SMS watchers use the leading string to wait for SMS messages that start with that string and when storing those messages in the inbox tag them with the bio id associated with that leading string. See the SMS watcher section 3.2.6.3.1 for more examples of how the BIO database can be used.
-3.2.11.2.4 BIO Parsers
-The BIO parsers are plug-ins for parsing and processing incoming BIO messages. They are invoked by the BIO Server MTM depending on the BIO type of the message being processed. Each BIO parser implements two functions, ParseL and ProcessL. The level of functionality varies between parsers. Some parsers update the final repository with the received data, e.g. WAPP updates the CommDB with the received settings. Some parsers simply save the data in an unparsed state for processing by another component, this secondary parsing is not part of the BIO framework and must be initiated by the messaging client. An example is when GFP saves vCard data as a file as opposed to updating the contacts database, the UI must then invoke the Versit parser to parse the vCard and commit it to the contacts database.
-3.2.11.2.4.1 Generic File Parser (GFP)
-The generic file parser can be used to identify and save a variety of BIO data types, e.g. vCards and vCals. The Generic File Parser does not process the data, it simply saves it in the message store for processing by another component. The file is saved as an attachment of the message entry that was parsed.
-3.2.11.2.4.2 Nokia/Ericsson OTA Parser (WAPP)
-The WAPP parser decodes Nokia/Ericsson OTA messages and updates CommDB to reflect the received settings.
-3.2.11.2.4.3 Nokia Smart Message Internet Access Parser (IACP)
-The IACP parser decodes Nokia Smart Messages and updates the CommDB and messaging settings where appropriate.
-3.2.11.2.5 BIF Files and Utilities
-The BIF files encapsulate the information required for identifying BIO messages, these details may include the expected port number, MIME type or leading string. Different BIO watcher will use different information from these files, for an example see the 3.2.6.3.1. The information can be retrieved from the BIF files by using the BIF utilities. Generally BIO aware clients will access this information via the BIO database. BIF files are resource files previous to the v6.1 release they were binary files generated by biftool.exe.
-3.2.11.2.6 Platform Security Compliant Messaging / BIO APIs
-In the platform security model the BIO parsers are run in the client space rather than in the message server space, as is done in the non-platform secure model. If the BIO parsers are run in the message server space, it allows a client process to gain the capabilities of the message server. IPC policing can protect the message server from this.
-Also, for the message server to be able to load any BIO parser it would need more capabilities than it really requires. By running the BIO parsers in the client space, both these issues are solved. The client process must be trusted with the necessary capabilities to run the specified BIO parser.
-The BIO registry files are located in the \resource\messaging\bif read-only directory. All BIO parser DLLs are located in the \sys\bin protected directory.
-
-Figure 26 BIO Message Dependencies (v9.0)
-The BIO client MTM is responsible for loading the BIO database and BIO utilities to handle parse/process requests from clients.
-The BIO registry files no longer identify the BIO parsers DLLs via their UID – the registry file must use the BIO parser DLL name to identify them.
-3.2.12 Messaging / OBEX MTM APIs
-3.2.12.1 Key Internal Relationships and Dependencies
-
-Figure 28 OBEX Internal Dependencies
-3.2.12.2 OBEX MTM Overview
-The OBEX MTM offers simple IR and Bluetooth beaming functionality. It provides an API that is consistent with other MTMs so that the underlying OBEX APIs do not need to be used directly for beaming applications. The OBEX MTM does not provide OBEX receiving functionality, in order to receive OBEX data the underlying OBEX APIs must be used directly.
-3.2.12.2.1 OBEX MTM
-The OBEX MTM is split into three parts. OBEX MTM DLLs, IR MTM DLLs and Bluetooth MTM DLLs. The OBEX MTM DLLs can not be used on their own they provide the base OBEX MTM functionality for the derived IR and Bluetooth MTMs.
-There are two APIs that can be used to create OBEX messages:
-1) The Send-As API
-2) Linked attachments by filename
-The Send-As API provides an interface consistent with other MTMs, however it requires all attachments to be copied into the message store before they can be sent, this is often undesirable for beaming applications because it is wastes disk space. For this reason a second API is provided that allows attachments to be linked to outgoing messages by filename, when this API is used there is no need to copy the attachments to the message store.
-Unlike many other MTMs after OBEX tries to send a message it is deleted from the outbox whether the sending succeeds or fails.
-3.2.12.2.1.1 OBEX MTM Key External Dependencies
-
-Figure 29 OBEX External Dependencies
-3.2.12.2.2 IR MTM
-The bulk of the OBEX MTM functionality is provided by the OBEX MTM DLLs, the IR MTM itself just sets up the parameters.
-3.2.12.2.2.1 IR MTM Key External Dependencies
-
-Figure 30 IR MTM Dependencies
-3.2.12.2.3 Bluetooth MTM
-The bulk of the OBEX MTM functionality is provided by the OBEX MTM DLLs, the Bluetooth MTM just subclasses from the OBEX MTM and sets up Bluetooth specific parameters.
-3.2.12.2.3.1 Bluetooth MTM Key External Dependencies
-
-Figure 31 Bluetooth MTM Dependencies
-3.2.12.2.4 OBEX MTM Utils
-The OBEX MTM Utils provide utility functionality used by the other OBEX MTM DLLs. The two main areas of functionality provided by this component are:
-1) Filename linking functionality
-2) Bluetooth SDP lookup
-The filename linking functionality is provided in the utilities because linked files must be added by the client side during message creation and need to be read on the server side during sending.
-
-3.2.12.2.5 Platform Security Compliant Messaging / OBEX MTM APIs
-From v9.0 and onwards the service settings of all the derived OBEX MTMs are stored in the Central Repository. The OBEX message is stored in the message store as an attachment – from v9.0 and onwards the Attachment API is used to attach the OBEX message.
-
-3.2.13 Messaging / GMXML APIs
-3.2.13.1 Key Relationships and Dependencies
-
-Figure 32 GMXML Dependencies
-3.2.13.2 Overview
-The GMXML component provides simple XML DOM parsing and validation functionality. It is intended for parsing XML that might be needed in messaging applications, specifically SMIL parsing for MMS rendering. It is not a general purpose XML parser and will not be suitable for some applications, e.g. browsing.
-3.2.13.2.1 GMXML DOM
-The DOM implementation is fit for purpose for SMIL rendering but differs from the standard DOM design in several respects, e.g. attributes are not stored as discrete nodes, for performance reasons they are stored with the element.
-The DOM tree classes are all derived from nodes. Implemented node types include elements, text and comments. The type of each element is stored as a descriptor as opposed to an enum. This is less efficient than storing it as an enum but provides maximum flexibility when dealing with unknown element types.
-Nodes are linked together in a tree structure as might be expected in a DOM implementation. The tree structure exists on the heap.
-3.2.13.2.2 GMXML Parser and Composer
-3.2.13.2.2.1 Parser
-The parser takes XML input from a buffer or file and creates the corresponding DOM structure on the heap.
-The parser is capable of performing some basic validation. In order to validate against a DTD a class that implements the GMXML DTD interface is required. The DTD interface specifies several functions that provide the required validation, e.g. one of the functions determines if a given attribute is valid for a given element. An instance of the DTD class should be passed into the parser when validation is required but can be omitted if no validation is needed.
-3.2.13.2.2.2 Composer
-The composer takes a DOM tree and generates XML output from it. The XML output is written to a file.
-3.2.13.2.3 GMXML SMIL DTD (Validator)
-The SMIL DTD validator class is an implementation of the DTD validator interface. It implements several simple functions that provide the information required to validate SMIL data. An instance of the SMIL DTD validator should be passed into the parser if SMIL validation is required.
-4 Security
-4.1 Data caging
-For data storage in the pre-platform security compliant architecture, refer to section [3.2.1.3.2]
-For the data caging in the platform security compliant architecture of v9.0 and onwards, refer to section [3.2.1.3.3]
-4.2 Backup and restore
-The message server registers the index file with the backup server. When informed about a backup/restore it releases the index file, sending events to messaging clients informing them that the message store is unavailable. When informed it can open the index file again, it checks the time stamp on the index file; if it has changed since the file was released it reloads the index file. If the newly restored index file is found to be corrupt it is deleted and a new message store is created. See the section on page 14 for details on how the message server handles corrupt stores. The client performing the restore should always wipe the existing message store before starting to copy the message store from the backup to the device.
-4.3 Capability ranges
-In the platform security compliant architecture of v9.0 and onwards, the capabilities allocated to messaging sub-systems are as listed in following table.
-4.3.1 Capabilities granted to executables
-The following table lists the executables and their capabilities and also gives a basic example for having the required capability.
-
-Executable Capability Rationale (basic example of capability requirement)
-msexe.exe ProtServ ProtServ is required to allow the msexe.exe to start a protected server. This stops processes without ProtServ from starting a server pretending to be the message server
- ReadDeviceData ReadDeviceData is needed to able to read service settings
- WriteDeviceData WriteDeviceData is needed to able to write service settings
- NetworkServices NetworkServices capability is needed to access network transports (SMS, POP3, SMTP, IMAP4).
- LocalServices LocalServices is needed to be able to access IR and Bluetooth
- ReadUserData ReadUserData is needed to be able to read user data (e.g. service settings).
-watcher.exe ReadDeviceData ReadDeviceData is needed to able to read service settings
- WriteDeviceData WriteDeviceData is needed to able to write service settings
- NetworkServices NetworkServices capability is needed to access network transports (SMS).
- LocalServices LocalServices capability is needed for the plug-ins to access IR and Bluetooth
- ReadUserData ReadUserData is needed to be able to read user data
- WriteUserData WriteUserData is needed to be able to write user data
-autosend.exe ReadUserData ReadUserData capability is needed to be able to read data from Outbox and SMTP server MTM.
- WriteUserData WriteUserData capability is needed to be able to write data in Outbox and SMTP server MTM.
- NetworkServices NetworkServices capability is needed to access network transports (SMS, POP3, SMTP, and IMAP4).
- LocalServices LocalServices capability is needed to access the IR and Bluetooth
-SchSend.exe ReadDeviceData ReadDeviceData is needed to able to read settings data
- NetworkServices NetworkServices capability is needed to access the network transports (SMS, POP3, SMTP, and IMAP4).
- LocalServices LocalServices is needed to be trusted by other MTM
- ReadUserData ReadUserData is needed to be able to read user data.
- WriteUserData WriteUserData is needed to be able to write user data.
-SendAs.exe ReadDeviceData ReadUserData is needed to be able to read data in Outbox.
- WriteDeviceData WriteUserData is needed to be able to write data in Outbox.
- NetworkServices NetworkServices capability is needed to access the network transports (SMS, POP3, SMTP, and IMAP4).
- LocalServices LocalServices is needed to be able to access IR and Bluetooth
-
-4.3.2 Capabilities granted to DLLs
-The assigned Platform Security attributes for DLLs within messaging are outlined in the following table.
-DLL Capability
-bifu.dll All –TCB
-bioc.dll All –TCB
-biodb.dll All –TCB
-bios.dll All –TCB
-biowatcher.dll same as watcher.exe
-biut.dll All –TCB
-cbcp.dll All –TCB
-enp.dll All –TCB
-gfp.dll All –TCB
-iacp.dll All –TCB
-nbswatcher.dll same as watcher.exe
-cdmanbswatcher.dll same as watcher.exe
-CdmaSocketWatcher.dll same as watcher.exe
-VMNWatcher.dll same as watcher.exe
-WEMTWatcher.dll same as watcher.exe
-WMTWatcher.dll same as watcher.exe
-WPTWatcher.dll same as watcher.exe
-wapp.dll All –TCB
-wapwatcher.dll same as watcher.exe
-smildtd.dll All –TCB
-xmldom.dll All –TCB
-xmlparser.dll All –TCB
-smiltranslator.dll All –TCB
-imcm.dll All –TCB
-imps.dll same as msexe.exe
-imut.dll All –TCB
-msgs.dll All –TCB
-msgurlrec.mdl same as AppArc.exe (once it exists; eiksrv in meantime)
-mtur.dll All –TCB
-pops.dll same as msexe.exe
-schsend.dll All –TCB
-send.dll All –TCB
-smcm.dll All –TCB
-smcm_gsm.dll Synonym for smcm.dll
-smcm_cdma.dll Synonym for smcm.dll
-smss.dll same as msexe.exe
-smss_gsm.dll Synonym for smss.dll
-smss_cdma.dll Synonym for smss.dll
-smts.dll same as msexe.exe
-btcmtm.dll All –TCB
-btsmtm.dll same as msexe.exe
-irc.dll All –TCB
-irs.dll same as msexe.exe
-obexclientmtm.dll All –TCB
-obexmtmutil.dll All –TCB
-obexservermtm.dll same as msexe.exe
-
-The reason for setting a high capability to the DLLs is to make it possible for almost anyone to link to them. Although a DLL may have capabilities ALL-TCB (All minus TCB), its real capability is limited by the process which loads the DLL.
-4.3.3 Capabilities required to use the subsystem
-The message subsystem needs to be protected against malicious clients. The following table shows the key capabilities required to do related activities in different components.
-
-Component Related Activity Required Capability and SID
-Message server Create message in local folder No capability required
- Create message in Outbox ReadUserData, WriteUserData and MTM specific capabilities
- Access client MTM ReadUserData, WriteUserData and MTM specific capabilities
-Watcher Allow plug-ins to wait on events (e.g. arrival of SMS) Watcher always polices if the client capabilities are trusted by the watcher framework, else it will not be loaded
-Plug-ins or clients using watcher need the same capabilities as watcher.exe to be able to be loaded by watcher.
-Autosend Send messages in background NetworkService or LocalService required by the message type
-SchSend Scheduling of operations (e.g. sending SMS) SchSend always polices to see if the process was started by the Task Scheduler – if not the process terminates without performing any of the scheduled tasks. Also, the SchSend verifies that only itself and the message server created the scheduled tasks. If this is not the case, SchSend does not performing the scheduled tasks.
-SendAs Create message Draft, move it to Outbox, and send message WriteDeviceData or WriteUserData and other capability required by the message type
-
-5 Further Information
-5.1 References
-No. Document Reference Version Description
-R1 messaging_functional_specification.doc 0.6 Messaging Functional description
-R2 SGL.GT0143.161_App-Framework_Architectural_Description.doc 1.0 App-Framework Architectural Description
-R3 NBProtocols_Subsystem_Architectural_Description.doc 0.2 NBProtocols Architectural Description
-R4 WAP-stack_architectural_analysis.doc 1.0 WAP stack architectural analysis
-R5 HTTP Transport Framework Architectural Description.doc 1.1 HTTP Transport Framework 1.1 Architectural Description
-5.2 Open Issues
-The following issues need to be resolved before this document is completed:
-1. Top-level architecture diagram showing the framework and plug-ins should be added to overview section.
-2. Message store section should talk about removable media.
-3. Define "Message Server Client API" and "Messaging Client API" in the glossary, and ensure it is consistently used in the diagrams
-4. Add a sequence diagram for receiving a vCard over SMS and integrating it into contacts
-5. Add a sequence diagram for sending an SMS
-6. Add a sequence diagram for synchronising a POP3 mail box
-7. Add a sequence diagram for connecting to an IMAP4 mail box and downloading a message
-8. Capability table should be updated after the implementation of server e.g. message server
-9. Sequence diagram may need to be changed to show secured platform operation
-10. In section [3.1.1.4] the server SendAsV2 to find a correct name
-11. Section 3.2.1.3.3.1 Data Caging file 'Mtm Registry v2'may need a correct name
-12. Breakdown diagram showing all DLL, exes, apps in the messaging subsystem for both the pre-v8.0 and post v9.0 in section[3.2]
-13. Needs to say more about how the capabilities are policed and the algorithms used for different operations
-14. The dependecy between the message server and the central repository need to be listed in the email, SMS and OBEX diagrams (e.g. message store)
-15. Section 3.2.1.2 - figure 3 - Central Repository also get used by the Message server, or server MTMs (e.g. POP3), to retrieve account settings the path, required DLL and description are not given
-16. Section 4.3.3 title can be Police requirement of the sub-system, add extra column for SID in the table and list the use of SID. For example SchSend checks for Task Scheduler SID
-
-
-5.3 Glossary
-The following technical terms and abbreviations are used within this document.
-Term Definition
-BIO
-Bearer Independent Object Smart messages e.g. vCards, vCals, and WAP provisioning messages. These can currently be received via the WAP stack, SMS stack, Bluetooth or Infrared.
-BIO Type UID that represents the content type of a BIO Message.
-Message Centre Application that displays list views of messages to the user, allowing the user to perform operations such as copying messages, sending messages creating new messages etc.
-Message Viewer Application for viewing a message.
-Message Editor Application for creating or editing a message
-Message Server Symbian OS Server that handles request to modify the Message Store
-Message Store Store of messages and related information kept in the file system on a Symbian OS device.
-Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
-Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
-Global Inbox A standard folder under the local service which is used to store incoming messages like SMS MMS etc. as opposed to an IMAP4 Inbox which would be under an IMAP4 service and is a representation of the Inbox on an IMAP4 email server.
-Central Repository centralised and secure storage facility for application settings
-OBEX Object exchange protocol, used to send objects such as vCards or files between devices via infrared or Bluetooth.
-GMXML XML parser / generator for use with SMIL formatted messages.
-UID Unique Identifier, a 32 bit number allocated from a registry owned by Symbian
-IPC Inter Process Communication
-MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
+MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
MTM Registry A list of currently installed MTMs maintained by the message server.
TLS Transport Layer Security, provides encryption of a TCP/IP socket.
M-HTML Standard for including HTML in MIME email messages see http://www.ietf.org/rfc/rfc2557.txt
@@ -10117,1033 +7063,15 @@
Message Editor Application for creating or editing a message
Message Server Symbian OS Server that handles request to modify the Message Store
Message Store Store of messages and related information kept in the file system on a Symbian OS device.
-Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
-Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
+Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
+Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
Global Inbox A standard folder under the local service which is used to store incoming messages like SMS MMS etc. as opposed to an IMAP4 Inbox which would be under an IMAP4 service and is a representation of the Inbox on an IMAP4 email server.
Central Repository centralised and secure storage facility for application settings
OBEX Object exchange protocol, used to send objects such as vCards or files between devices via infrared or Bluetooth.
GMXML XML parser / generator for use with SMIL formatted messages.
UID Unique Identifier, a 32 bit number allocated from a registry owned by Symbian
IPC Inter Process Communication
-MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
-MTM Registry A list of currently installed MTMs maintained by the message server.
-TLS Transport Layer Security, provides encryption of a TCP/IP socket.
-M-HTML Standard for including HTML in MIME email messages see http://www.ietf.org/rfc/rfc2557.txt
-MIME Specification for the format of email message bodies see http://www.ietf.org/rfc/rfc1341.txt
-RFC2822 The standard format for internet mail messages see http://www.ietf.org/rfc/rfc0822.txt
-SMTP Simple Mail Transport Protocol
-SID Secure Identification
-IMAP4 Internet Mail Access Protocol
-POP3 Post Office Protocol Version 3
-NBS Narrow Band Socket, in the messaging context this refers to the socket that is used to talk to the SMS stack for receiving and sending SMS messages
-SMS Short Message Service
-MMS Multimedia Message Service
-WAP Wireless Application Protocol
-WSP WAP Session Protocol
-HTTP Hypertext transfer protocol
-PDU Protocol Data Unit. This is the encoded form of SMS and MMS messages.
-Versit A consortium that defined standard formats for things like contacts (vCard) and calendar entries (vCals)
-SDP Service Discovery Protocol. A Bluetooth protocol that allows an applications to discover which services are available and to determine the characteristics of the services.
-SMIL Synchronized Multimedia Integration Language. Presentation language that is commonly used to define the contents of an MMS message.
-XML Extensible Mark-up Language
-DOM Document Object Model
-DTD Document Type Definition, a schema that defines the structure of an XML document.
-ESTORE Symbian OS component that provides stream based storage. Messaging uses the Permanent file store provided by ESTORE to store its index entries.
-Appendix A - Example Sequence Diagrams
-A.1 Copy to a Remote Service
-
-Figure 33 Sequence Diagram Showing Copying to a Remote Service
-Figure 33 shows a client copying a message to a remote service using the Messaging Client API. The message server then delegates the copy to the SMTP Server MTM. The Server MTM interprets the request as a request to send the message so it opens a connection to a remote SMTP server and sends the message. While the message is being sent the client can retrieve progress information from the CMsvOperation object that was returned by CMsvEntry::CopyL. The dark grey IPC line represents the split between the objects running in the client’s process space on the left and the message server’s process on the right.
-There are four basic steps:
-1. The client opens session with Message Server and creates a CMsvEntry set on the global outbox,
-2. The client then requests an asynchronous copy from the outbox to the SMTP service, a CMsvOperation object is returned. The message server loads the SMTP Server MTM and delegates the copy operation to it.
-3. The client requests progress from the CMsvOperation object, this request is passed through to the SMTP Server MTM. The client may repeat this step multiple times.
-4. The Server MTM finishes sending message. It moves the message to sent folder and completes the message server’s request. The message server completes the CMsvOperation object, which requests the final progress from the message server. The server returns the final progress and deletes the Server MTM. The CMsvOperation then completes the client’s original request.
-This diagram hides all of the internal working of the SMTP Server MTM, for information on this see below.
-A.2 SMTP Session
-
-Figure 34 Sequence Diagram Showing a SMTP Session
-Figure 34 shows the operation of the SMTP Server MTM after a request has come from the message server to copy a message to the SMTP service.
-1. SMTP Server MTM gets the request from the message server, it will build a selection of messages consisting of the union of the selection of messages passed in and the messages in the outbox that are associated with this SMTP service and are ready to be sent. The chain of classes are constructed, and a request is passed to networking to connect to the remote SMTP server, details of the server name and port are retrieved from the settings stored in the SMTP service entry.
-2. The component waits for the SMTP server to respond with a greeting indicating it is willing to talk, then sends EHLO to the server and waits for the response detailing the capabilities of the Server. After this step there could set steps to start using TLS and or SMTP AUTH depending on the SMTP settings.
-3. CImSmtpSession calls back into CMsgOutboxSend to retrieve the next message to be sent, then constructs a CImSmtpFile object to handle sending, for details on the sending see SMTP Email Send. When sending the email has completed the CImSmtpFile object is deleted.
-4. CImSmtpSession calls back into CMsgOutboxSend to retrieve the next message which returns saying there are no more messages. CImSmtpSession sends QUIT to the SMTP server and completes CMsgOutboxSend. CMsgOutboxSend deletes CImSmtpSession which tears down the connection to the SMTP server; it then completes the SMTP Server MTM. The Server MTM will then complete the message server and be deleted.
-A.3 SMTP Email Send
-
-Figure 35 Sequence Diagram Showing SMTP Transactions during Email Send.
-Figure 35 shows a CImSmtpFile object sending an email message to an SMTP server.
-1. Construct a CImSendMessage object, part of the imut component. Reset the SMTP Server
-2. Read address information from the CImHeader object stored in the message store, send address information to SMTP server.
-3. Use CImSendMessage object to read the message from the message store and generate RFC2822 message line by line. Send each line to the server as it is generated.
-4. Complete and send the message by sending a full stop to the SMTP server
-
-
-
-
-Messaging Symbian OS v7.0s, v8.0, v8.1, v9.0, v9.1 Architectural Description
-
-Status: Issued
-Team/Department : Messaging / Content & Messaging
-
-Contents
-1 INTRODUCTION 6
-1.1 PURPOSE AND SCOPE 6
-2 SUBSYSTEM OVERVIEW AND BACKGROUND 6
-3 MESSAGING ARCHITECTURE AND APIS 7
-3.1 SUBSYSTEM COMPONENTS 7
-3.1.1 Framework components 7
-3.1.1.1 Message Server and MTM architecture 7
-3.1.1.2 Schedule Send 7
-3.1.1.3 SendAs Version 1 7
-3.1.1.4 SendAs Version 2 7
-3.1.1.5 Watcher Framework 8
-3.1.1.6 Message URL Handler 8
-3.1.1.7 Bio Message Framework 8
-3.1.2 Plug-ins 8
-3.1.2.1 SMS 8
-3.1.2.2 CDMA SMS 8
-3.1.2.3 Email 9
-3.1.2.4 OBEX 9
-3.1.2.5 MMS 9
-3.1.2.6 GMXML 10
-3.1.2.7 Bio Message Plug-ins 10
-3.1.2.8 PCMTM 10
-3.1.2.9 Fax 10
-3.2 GENERAL DESCRIPTION 11
-3.2.1 Messaging / Message Server and MTM Architecture APIs 11
-3.2.1.1 Key Internal Relationships and Dependencies 11
-3.2.1.2 Key External Relationships and Dependencies 12
-3.2.1.3 API Purpose - Further Elaboration 13
-3.2.1.3.1 Message Store 13
-3.2.1.3.2 Data File Storage (pre - v9.0) 15
-3.2.1.3.3 Platform Security Compliant Message Store 16
-3.2.1.3.4 How message centres display the message store 17
-3.2.1.3.5 Message Type Module Architecture 19
-3.2.1.3.6 Message Server Client API 21
-3.2.2 Messaging / Send As APIs 22
-3.2.2.1 Key Relationships and Dependencies 22
-3.2.2.2 API Purpose - Further Elaboration 22
-3.2.2.2.1 SendAs API (pre – v9.0) 22
-3.2.3 Platform Security Compliant SendAs Server (v9.0 onwards) 23
-3.2.4 Messaging / Schedule Send APIs 24
-3.2.4.1 Key Relationships and Dependencies 24
-3.2.4.2 API Purpose - Further Elaboration 24
-3.2.4.2.1 Schedule Send 24
-3.2.5 Messaging / Watchers APIs 25
-3.2.5.1 Key Relationships and Dependencies 25
-3.2.5.2 API Purpose - Further Elaboration 25
-3.2.6 Messaging / Message URL Handler APIs 26
-3.2.6.1 Key Relationships and Dependencies 26
-3.2.6.2 API Purpose - Further Elaboration 26
-3.2.6.2.1 Message URL Handler Application 26
-3.2.6.2.2 Message URL Recognisers 27
-3.2.7 Messaging / SMS APIs 27
-3.2.7.1 Key Internal Relationships and Dependencies 27
-3.2.7.2 Key External Relationships and Dependencies 28
-3.2.7.3 API Purpose - Further Elaboration 28
-3.2.7.3.1 SMS Watchers 28
-3.2.7.3.2 SMS Client MTM 29
-3.2.7.3.3 SMS Utilities 29
-3.2.7.3.4 SMS Server MTM 30
-3.2.8 Messaging / CDMA SMS APIs 31
-3.2.8.1 Key Internal Relationships and Dependencies 31
-3.2.8.2 Key External Relationships and Dependencies 32
-3.2.8.3 API Purpose - Further Elaboration 32
-3.2.8.3.1 CDMA SMS Watchers 32
-3.2.8.3.2 CDMA SMS Client MTM 33
-3.2.8.3.3 CDMA SMS Utilities 33
-3.2.8.3.4 CDMA SMS Server MTM 33
-3.2.8.3.5 Configuration for using CDMA SMS MTM 34
-3.2.9 Messaging / Email APIs 35
-3.2.9.1 Key Internal Relationships and Dependencies 35
-3.2.9.2 Key External Relationships and Dependencies 36
-3.2.9.3 API Purpose - Further Elaboration 36
-3.2.9.3.1 Email Overview 36
-3.2.9.3.2 Email Client Utilities 37
-3.2.9.3.3 Email Server MTM Utilities 37
-3.2.9.3.4 POP3 MTMs 37
-3.2.9.3.5 IMAP4 MTMs 38
-3.2.9.3.6 SMTP MTMs 40
-3.2.9.3.7 Autosend 40
-3.2.10 Messaging / MMS APIs 40
-3.2.10.1 Key Internal Relationships and Dependencies 41
-3.2.10.2 API Purpose - Further Elaboration 41
-3.2.10.2.1 MMS Overview 41
-3.2.10.2.2 MMS Utilities 42
-3.2.10.2.3 MMS Watcher 43
-3.2.10.2.4 MMS Client MTM 43
-3.2.10.2.5 MMS Server MTM 44
-3.2.10.2.6 MMS Codec 45
-3.2.11 Messaging / BIO APIs 46
-3.2.11.1 Key Internal Relationships and Dependencies 46
-3.2.11.2 API Purpose - Further Elaboration 47
-3.2.11.2.1 BIO Overview 47
-3.2.11.2.2 BIO MTM 47
-3.2.11.2.3 BIO Database 48
-3.2.11.2.4 BIO Parsers 48
-3.2.11.2.5 BIF Files and Utilities 48
-3.2.11.2.6 Platform Security Compliant Messaging / BIO APIs 49
-3.2.12 Messaging / OBEX MTM APIs 50
-3.2.12.1 Key Internal Relationships and Dependencies 50
-3.2.12.2 OBEX MTM Overview 50
-3.2.12.2.1 OBEX MTM 50
-3.2.12.2.2 IR MTM 51
-3.2.12.2.3 Bluetooth MTM 51
-3.2.12.2.4 OBEX MTM Utils 52
-3.2.12.2.5 Platform Security Compliant Messaging / OBEX MTM APIs 52
-3.2.13 Messaging / GMXML APIs 52
-3.2.13.1 Key Relationships and Dependencies 52
-3.2.13.2 Overview 53
-3.2.13.2.1 GMXML DOM 53
-3.2.13.2.2 GMXML Parser and Composer 53
-3.2.13.2.3 GMXML SMIL DTD (Validator) 53
-4 SECURITY 54
-4.1 DATA CAGING 54
-4.2 BACKUP AND RESTORE 54
-4.3 CAPABILITY RANGES 54
-4.3.1 Capabilities granted to executables 54
-4.3.2 Capabilities granted to DLLs 55
-4.3.3 Capabilities required to use the subsystem 57
-5 FURTHER INFORMATION 59
-5.1 REFERENCES 59
-5.2 OPEN ISSUES 59
-5.3 GLOSSARY 60
-APPENDIX A - EXAMPLE SEQUENCE DIAGRAMS 62
-A.1 COPY TO A REMOTE SERVICE 62
-A.2 SMTP SESSION 64
-A.3 SMTP EMAIL SEND 66
-
-Table of Figures
-Figure 1 Where Messaging Lives 6
-Figure 2 MTM Relationships 11
-Figure 3 External Dependencies 12
-Figure 4 Message Store 13
-Figure 5 Series 60 Inbox List View 14
-Figure 6 Remote and Local Entries 14
-Figure 7 Email Message 15
-Figure 8 Series 60 Message Centre (Composed from 2 screen shots) 17
-Figure 9 UIQ Message Centre 18
-Figure 10 Messaging MTM Structure (light coloured components are part of messaging subsystem) 19
-Figure 11 Nokia 9210 Outbox List View 20
-Figure 12 SendAs Version 1 Dependencies 22
-Figure 13 SendAs Version 2 Dependencies 23
-Figure 14 Schedule Send Dependencies 24
-Figure 15 Watcher Dependencies 25
-Figure 16 Message URL Handler Dependencies 26
-Figure 17 SMS Internal Dependencies 27
-Figure 18 SMS External Dependencies 28
-Figure 19 CMDA SMS Internal Dependencies 31
-Figure 20 CDMA SMS External Dependencies 32
-Figure 19 Email Internal Dependencies 35
-Figure 20 Email External Dependencies 36
-Figure 21 MMS Internal Dependencies 41
-Figure 22 MMS Utilities External Dependencies 42
-Figure 23 MMS Watcher External Dependencies 43
-Figure 24 MMS Client MTM Dependencies 43
-Figure 25 MMS Server MTM Dependencies 44
-Figure 26 BIO Message Internal Dependencies 46
-Figure 27 Bio Parser External Dependencies 47
-Figure 26 BIO Message Dependencies (v9.0) 49
-Figure 28 OBEX Internal Dependencies 50
-Figure 29 OBEX External Dependencies 51
-Figure 30 IR MTM Dependencies 51
-Figure 31 Bluetooth MTM Dependencies 52
-Figure 32 GMXML Dependencies 52
-Figure 33 Sequence Diagram Showing Copying to a Remote Service 62
-Figure 34 Sequence Diagram Showing a SMTP Session 64
-Figure 35 Sequence Diagram Showing SMTP Transactions during Email Send. 66
-1 Introduction
-1.1 Purpose and Scope
-The Messaging Architectural Description details the architecture and APIs exposed by the Messaging Subsystem. This document does not attempt to list all functionality provided by the messaging subsystem. For details on the functionality provided and the specifications implemented by the messaging subsystem see the Messaging Functional Description [R1]. This document describes the general architecture of messaging subsystem. Information related to a particular release version is mentioned with relevant release number.
-2 Subsystem Overview and Background
-The Messaging Subsystem provides an application level API to handle the storage and transport of different message types. It sits between messaging applications and the lower level subsystems which messaging uses for storage and transmission of messages.
-
-Figure 1 Where Messaging Lives
-The message types that messaging currently supports are Email (POP3, IMAP4 & SMTP), SMS, MMS and OBEX. The set of supported message types is extensible at run time by the use of plug-in modules that are responsible for the transmission and storage of a particular message type. This means that the set of components shown communicating with the network cloud depend on the message types installed.
-3 Messaging Architecture and APIs
-3.1 Subsystem components
-The Messaging subsystem components can be split into two categories: those components that form the framework and those that plug into the framework to support specific message types. This section briefly describes each of the components, more detailed descriptions of the components and their dependencies can be found in later sections of this document.
-3.1.1 Framework components
-3.1.1.1 Message Server and MTM architecture
-The message server is the core component in the messaging subsystem. It provides the message store used to contain messages. The Message Type Module architecture also allows plug-ins to add support for new message types to the messaging subsystem.
-Component Description
-messaging\framework\serverexe Executable that links to the server component and starts the message server
-messaging\framework\server Contains classes that make up both the client and server side of the message server API.
-messaging\framework\mtmbase Base classes for the plug-ins that handle the various message types
-3.1.1.2 Schedule Send
-The Schedule Send component is an extension to the framework that provides support for scheduling of operations such as sending messages. Message type modules that wish to support this functionality can use these support components to implement scheduling. For example the SMS MTM uses this to allow scheduled sending of SMS messages.
-Component Description
-messaging\schedulesend\schedulesendmtm Base classes that handle functionality for message server plug-ins that wish to enable scheduling of sending messages.
-messaging\schedulesend\schedulesendexe Executable use to provide schedule send behaviour.
-3.1.1.3 SendAs Version 1
-This version of SendAs is supported in releases pre - v9.0. SendAs provides a high level API for applications that wish to include a “Send As” menu to allow users to send content via one of the message types supported by messaging. The application using the API does not have to be aware of the message type selected by the user. Note the API does not send the messages.
-Component Description
-messaging\sendas High level API to allow creation of messages.
-3.1.1.4 SendAs Version 2
-From v9.0 and onwards the SendAs has been replaced with client server architecture based SendAs server. The client server architecture enhances secured platform implementation. The SendAs server polices the client application. If it is not trusted with required capabilities the SendAs server will refuse the client access. The client MTM for the message type can send a message with user permission even if the client does not have the correct capabilities.
-Component Description
-messaging\sendAsV2 High level API to allow the creation and sending of messages
-
-3.1.1.5 Watcher Framework
-The watcher framework is a lightweight framework to allow plug-ins to wait on events. For example there is an SMS watcher that waits for incoming SMS messages and delivers them to the message store. The watcher framework will only load plug-ins from ROM.
-Component Description
-messaging\framework\watcher Executable that loads and runs watcher plug-ins.
-3.1.1.6 Message URL Handler
-Support for recognising messaging URLs (mailto:, sms:, fax:, mms:), and then launching an editor with a new message.
-Component Description
-messaging\urlhandler\urlhandler An application that parses the URLs and then creates a correctly addressed message and launches a message editor.
-messaging\urlhandler\recogniser Recognisers that map from the URL schemes to the mime types.
-3.1.1.7 Bio Message Framework
-The Bio Message Framework provides a framework that supports plug-ins to handle messages like vCards and Internet access point set-up messages.
-Component Description
-messaging\biomsg\BDB\BIODB Classes to maintain the database of bio registration files.
-messaging\biomsg\BIFU\BIFU Classes for reading and writing bio registration files
-messaging\biomsg\BIOC\BIOC Bio message client MTM, this is in the framework section as it forms part of the bio messaging framework it is also a plug-in to the messaging framework.
-messaging\biomsg\BIOS\BIOS Bio message server MTM, this is in the framework section as it forms part of the bio messaging framework it is also a plug-in to the messaging framework.
-3.1.2 Plug-ins
-3.1.2.1 SMS
-The SMS plug-ins provide application level support for the Short Message Service messages.
-Component Description
-messaging\biomsg\BioWatchers Plug-ins to the watcher framework to listen for SMS, WSP, and WDP messages and deliver them to the global inbox in the message store.
-messaging\sms\clientmtm A plug-in to the message server framework to provide a generic API for creation of SMS messages (SMS Client MTM & SMS utilities)
-messaging\sms\servermtm A plug-in to the message server framework to provide a generic API for sending of SMS messages (SMS Server MTM)
-3.1.2.2 CDMA SMS
-The CDMA SMS plug-ins provide application level support for the CDMA Short Message Service messages.
-Component Description
-messaging\biomsg\BioWatchersCdma Plug-ins to the watcher framework to listen for CDMA SMS messages and deliver them to the global inbox in the message store.
-messaging\sms\multimode\clientmtm A plug-in to the message server framework to provide a generic API for creation of CDMA SMS messages (CDMA SMS Client MTM)
-messaging\sms\multimode\servermtm A plug-in to the message server framework to provide a generic API for sending of CDMA SMS messages (CDMA SMS Server MTM)
-
-3.1.2.3 Email
-The email plug-ins provide support the POP3, IMAP4 and SMTP email protocols and support for parsing and generating plain test, MIME and M-HTML format email messages.
-Component Description
-messaging\email\clientmtms A plug-in to the message server framework to provide a generic API for creation of email messages (IMAP4 SMTP and POP3 Client MTMs & email utilities)
-messaging\email\imapservermtm A plug-in to the message server framework to provide a generic API for access to a remote IMAP4 server (IMAP4 Server MTM)
-messaging\email\smtpservermtm A plug-in to the message server framework to provide a generic API for access to a remote SMTP server (SMTP Server MTM)
-messaging\email\popservermtm A plug-in to the message server framework to provide generic API for access to remote POP3 server (POP3 Server MTM)
-messaging\email\servermtmutils Email utilities for parsing plain text and MIME email messages. It also provides an abstraction of the TCP/IP sockets for use by the SMTP POP3 and IMAP4 plug-ins.
-messaging\email\autosend An executable that requests SMTP Server MTM to send messages in the outbox. This is used to provide send on next connection functionality and is started by the POP3 and IMAP4 Client MTMs.
-3.1.2.4 OBEX
-The OBEX MTM is a set of plug-ins to the message server that provides support for IR and Bluetooth beaming.
-Component Description
-messaging\obex\btmtm\btclient\group\btcmtm Bluetooth Client MTM
-messaging\obex\btmtm\btserver\group\btsmtm Bluetooth Server MTM
-messaging\obex\irmtm\irclient\group\ircmtm IR Client MTM
-messaging\obex\irmtm\irserver\group\IRSMTM IR Server MTM
-messaging\obex\obexmtm\obexclient\group\obexClientMtm OBEX Client MTM, base classes for the Bluetooth and IR Client MTMs
-messaging\obex\obexmtm\obexserver\group\obexServerMtm OBEX Server MTM, base classes for the Bluetooth and IR Server MTMs
-messaging\obex\obexmtm\obexutil\group\obexMtmUtil OBEX MTM utilities
-3.1.2.5 MMS
-The MMS MTM is a plug-in to the message server that provides support for MMS messages. From v9.0 and onwards MMS MTM and related components are removed.
-Component Description
-messaging\mms\utils MMS Utilities
-messaging\mms\servermtm MMS Server MTM
-messaging\mms\mmswatcherplugins MMS plug-ins to WAP push framework to handle reception of MMS notifications
-messaging\mms\codec MMS utilities for handling MMS codecs
-messaging\mms\clientmtm MMS Client MTM
-3.1.2.6 GMXML
-GMXML is a parser/generator for SMIL presentations for MMS messages.
-Component Description
-messaging\GMXML\XMLParser XML parser designed for parsing of SMIL messages
-messaging\GMXML\XMLDom XML document object model designed for parsing of SMIL messages
-messaging\GMXML\SMILdtd SMIL DTD
-3.1.2.7 Bio Message Plug-ins
-These parsers plug into the bio messaging framework to handle specific types of bio message.
-Component Description
-messaging\biomsg\cbcp\CBCP Compact business card parser
-messaging\biomsg\enp\ENP Email notification parser
-messaging\biomsg\gfp\gfp General file parser
-messaging\biomsg\iacp\IACP Nokia Smart Message Internet Access Parser
-messaging\biomsg\wapp\wapp Nokia/Ericsson OTA Parser
-3.1.2.8 PCMTM
-Plug-in to the message server that provided email synchronisation with a PC. This component has been deprecated in 8.0a and will not been documented in the API section below.
-3.1.2.9 Fax
-Plug-in to the message server that provides fax support. This component has been deprecated in 8.0a and will not been documented in the API section below.
-
-3.2 General Description
-3.2.1 Messaging / Message Server and MTM Architecture APIs
-3.2.1.1 Key Internal Relationships and Dependencies
-
-Figure 2 MTM Relationships
-Figure 2 shows the relationship between the Message Server and the MTM plug-ins. The grey classes are realisations of the MTM interfaces defined by the messaging framework. The message server depends on the Server MTM interface. Messaging Clients depend on the Client, UI and UI Data MTM interfaces and the Message Server Client API.
-3.2.1.2 Key External Relationships and Dependencies
-
-Figure 3 External Dependencies
-The grey package representing the messaging client depends on the Client, UI and UI Data interfaces and the Messaging Client API. The message server then depends on:
-• Charconv – Provides character set conversion routines, used to convert encoded message body text to Unicode body text.
-• EStore – Provides API to handle a stream based store used for the messaging index file and the framework classes for the message store files. (omitted from other dependency diagrams as it is implied by the dependency on the message server)
-• F32 – Provides the file server APIs used to access the file system directories in which messaging stores files containing message data. (omitted from other dependency diagrams)
-• BAFL – Provides API to load the correct messaging resource file dependent on the current language and to register the message store index file with the backup server. (omitted from other dependency diagrams)
-• ETEXT – Rich text APIs used to store body text of messages, this rich text format is a Symbian Proprietary format. (omitted from other dependency diagrams)
-• EUSER – Core Symbian OS utilities such as descriptors, arrays, client / server framework, cleanup stack and others (omitted from this and other dependency diagrams).
-• Central Repository – Centralised and secure storage facility for application settings, the message server stores message settings data in the central repository (from v9.0 and onwards).
-Note that debug only dependencies such as the flogger have been omitted from dependency diagrams.
-3.2.1.3 API Purpose - Further Elaboration
-3.2.1.3.1 Message Store
-The message server provides persistent storage of messages and messaging account settings. It does this by providing a message store consisting of a tree of message entries. Multiple clients can access the message store simultaneously. Each entry in the tree can represent an email account, folder of messages, message part, etc.
-
-Figure 4 Message Store
-Figure 4 shows an example message store. The tree is broken down in to three levels:
-1. The Root entry. This entry is just present to tie the tree structure together
-2. Service entries. There is one local service under which local folders and messages are stored, and zero or more remote services. Remote services represent message accounts.
-3. Message & Folder entries. Messages and folders, under the local service represent messages stored on the device. Messages and folders under remote services represent a local copy of messages that are present on a remote server. For example under a POP3 email service you would have copies of all the messages present on the POP3 email server, or under an SMS service you might find SMS messages that are stored on a SIM.
-The message server controls access to the entries in the store. It enforces the three levels therefore attempts to create message or folder entries directly under the root entry will fail.
-The message server provides three types of storage for each entry in the message store:
-• Index entry - TMsvEntry - intended to provide enough information for UI to display list views as shown in Figure 5. This consists of two strings and various flags (read, complete, has attachments etc).
-• Stream based file store - CMsvStore – provides storage of streams of data associated with UIDs. A standard UID is defined for storing body text. Other UIDs are specific. For example the email MTMs define a UID for storage of MIME headers. Compared to the index entry information this is used to store larger objects and is extensible, at the cost of being slower to access. From v9.0 and onwards CMsvStore provides an Attachment API for managing attachments. The Attachment API should be used as attachments can no longer be accessed directly due to Platform Security.
-• Directory of files – normally used for attachments.
-The only storage type that is always present is the index entry. The stream store and the directory of files are optional.
-
-Figure 5 Series 60 Inbox List View
-
-Figure 6 Remote and Local Entries
-As shown in Figure 6 the message store is split into two sets of entries:
-• Remote entries - entries that are representations of entries stored on a remote store .
-• Local entries - entries not linked to a remote store.
-The message server handles changes to local entries; internally it hands off changes to remote entries to the Server MTM that owns that service. Examples of operations that are handed off to Server MTMs are operations involving copying and moving messages to and from a remote service. See section 3.2.1.3.5 or more information on Server MTMs.
-Each entry within the store has a type:
-Folder – Messages can be grouped into folders. Standard folders such as inbox / outbox and user created folders.
-Message – Storage of the content of a message. Message entries can have child entries used to represent the structure of a message.
-Attachment – These represent attachments under a message entry.
-Root & Local Service Entry – There tie the tree structure together. However the Stream store associated with the root entry is sometimes used by UIs to store preferences e.g. default folder views etc.
-Remote Service - Represents a source and / or destination for messages. They are used to store the settings associated with the source / destination.
-Message Type Specific - MTMs can create other message types for use as child entries to messages they own. For example email uses a tree structure, with a message entry as the root, to represent the MIME structure of an email message; it uses folder entries to represent MIME folders and adds new types for entries representing the html body and text body parts of a message. This is shown in Figure 7.
-
-Figure 7 Email Message
-Using the message store to represent message structure allows reuse of the tree structure and makes it very simple to represent one message embedded in another. However this representation introduces performance issues as it results in each message having multiple files associated with it. The message server also keeps all index entries in memory; therefore this representation increases the memory footprint of the message server. Therefore when designing new MTMs we should think about moving away using multiple index entries to store one message in the message store.
-A default message store is created if the message server starts and no message store is present or a corrupt message store is present. The server will initially create a store with just a root entry, and then the server will create any standard folders defined in the resource file msgs.rsc. Finally the server will check whether an executable ‘mailinit.exe’ is present on the system, if it is present the server will launch the executable to allow customisation of the message store. The behaviour of ‘mailinit.exe’ is defined by the UI family of the device. However the typical behaviour is to load each of the UI Message Type Modules and allow each to perform any message type specific initialisation. For example the SMS plug-in typically creates a default service entry.
-
-3.2.1.3.2 Data File Storage (pre - v9.0)
-This section describes the files used by the message server before release v9.0. For information on the files used for release from v9.0 and onwards see section [3.2.1.3.3.1].
-Filename Access Purpose
-?:\system\Mail\index Private Message server index file, internal to message server
-?:\system\Mail\<8 hex digits> Shared via API Message server store files for services, clients access these via a messaging API.
-?:\system\Mail\<8 hex digits>.new Shared via API Temporary file used during committing message server store files.
-?:\SYSTEM\MAIL\<8 HEX DIGITS>_F\* Shared Files associated with a messaging service. These may be accessed directly by clients.
-?:\system\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits> Shared via API Message server store files for message entries, clients access these via a messaging API.
-?:\system\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits>.new Shared via API Temporary file used whilst committing message server store files.
-?:\system\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits>_F\* Shared Files associated with a message entry. These are accessed directly by clients.
-c:\system\data\msgs.ini Private Stores the drive containing the last used message store
-c:\system\Mtm\Mtm Registry v2 Private Cache of registered MTMs, internal to message server
-C:\system\data\sms_settings.dat Shared Copy of the SMS settings.
-?:\System\Mail\StoreInit.tmp Shared Created when message server runs ‘mailinit.exe’, ‘mailinit.exe’ should delete the file when it has successfully completed.
-?:\System\Mail\storedeleted.tmp Shared Created when message server finds and deletes a corrupt message store. Allows the UI to inform the user about the fact that the message store was corrupt.
-Files that are shown as private should only be accessed by the message server or by connectivity process for backup and restore purposes. Files listed as shared are accessed directly by messaging clients. Files listed as shared via API are accessed by client process but only via messaging APIs.
-3.2.1.3.3 Platform Security Compliant Message Store
-From v9.0 and onwards the message store is stored in the message server's data cage and the settings data are placed in the Central Repository. Access to the message store is only possible via message server APIs and not directly through file access. This leads to secured data storage and secured platform.
-3.2.1.3.3.1 Data caging
-Filename Purpose
-?:\private\<SID>\Mail\index Message server index file, internal to message server
-?:\ private\<SID>\Mail\<8 hex digits> Message server store files for services, clients access these via a messaging API.
-?:\ private\<SID>\Mail\<8 hex digits>.new Temporary file used during committing message server store files.
-?:\ private\<SID>\Mail\<8 hex digits>_F\* Files associated with a messaging service. These may be accessed directly by clients.
-?:\ private\<SID>\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits> Message server store files for message entries, clients access these via a messaging API.
-?:\ private\<SID>\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits>.new Temporary file used whilst committing message server store files.
-?:\ private\<SID>\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits>_F\* Files associated with a message entry. These are accessed directly by clients.
-c:\ private\<SID>\data\msgs.ini Stores the drive containing the last used message store
-c:\ private\<SID>\Mtm\Mtm Registry v2 Cache of registered MTMs, internal to message server
-?:\ private\<SID>\Mail\StoreInit.tmp Access via IPC call
-?:\ private\<SID>\Mail\storedeleted.tmp Created when message server finds and deletes a corrupt message store. Allows the UI to inform the user about the fact that the message store was corrupt.
-?\resource\messaging\bif\*.bif Registration data field with UID used in BIO framework
-
-3.2.1.3.4 How message centres display the message store
-The UI normally provides a Message Centre application to display the structure of the message store to the user. Different UIs map the structure to different views.
-
-Figure 8 Series 60 Message Centre (Composed from 2 screen shots)
-Figure 8 shows the top level view of the message centre application on a Series 60 phone. This shows that the message centre has hidden the local service and shows the standard folders at the same level as the services. Also the SMTP, SMS and MMS services are marked as hidden entries in the message store, and so do not appear in the message application.
-
-Figure 9 UIQ Message Centre
-However Figure 9 shows that the UIQ message centre has no 1-1 mapping from the structure in the message store to the structure shown to the user. Each of the message types is displayed as if its messages were contained in separate folders. Under each of these folders the user is presented with an inbox, outbox, send and drafts folder. This filtering is done in the UI layer as this functionality is not provided by the messaging API.
-3.2.1.3.5 Message Type Module Architecture
-
-Figure 10 Messaging MTM Structure (light coloured components are part of messaging subsystem)
-The MTM architecture is the plug-in scheme provided by the messaging framework to integrate different message transports into the message server. The plug-in scheme consists of four interfaces, the UI MTM, UI Data MTM, Client MTM and Server MTM. The messaging client applications loads and uses the first three which are loaded within the client’s process space. The final one the Server MTM is loaded within the message server process. The APIs for the client facing interfaces are extensible via run time type information provided by the QueryCapability API, and the InvokeAsyncFunction and InvokeSyncFunction APIs.
-3.2.1.3.5.1 UI MTM
-Handles requests from clients to view and edit messages or service settings. The MTM handles interaction with the message centre and as such the exact meaning of the APIs is defined by the UI. However common meanings are:
-• Create – Launches the editor with a new message.
-• Edit – If entry is a message this launches the editor; if entry is a service it edits the settings.
-• View – Launches the message viewer.
-• Display progress of an operation.
-3.2.1.3.5.2 UI data MTM
-This MTM provides fast access to UI components such as menu resources and bitmaps required by message centre for list views etc. Again the exact semantics are UI specific.
-There is a resource file defining UI specific functions, for example the Series 60 Messaging UI checks if the resource file contains text to display in the “New Message” menu.
-The UI data MTM also provides mapping from the message store’s TMsvEntry structure to Icons for the messaging list views and a status string, for example in the case of Nokia 9210 it is used in the outbox view to provide strings like “Resend 01:07” as shown in Figure 11. The class also provides functions to determine what operations are possible with a given entry. Examples of this are APIs that return whether the UI should allow the user to reply to the entry or to delete a service entry. The UI then uses this information to determine which menu options / short-cut keys should be allowed when the user selects a given entry.
-
-Figure 11 Nokia 9210 Outbox List View
-3.2.1.3.5.3 Client MTM
-Provides methods to create / reply and forward messages. Functions the Client MTMs provide are:
-• Create Message.
-• Reply to a Message.
-• Forward a Message.
-• Add / remove Addressees.
-• Add / remove body text.
-• Add / remove subject.
-• Add / remove attachments (the API cannot list attachments).
-The Client MTM interface is used by SendAs to provide a way of creating messages independently of the message type.
-3.2.1.3.5.4 Server MTM
-This is the final interface that makes up an MTM plug-in; it differs from the other three plug-ins in that it is loaded into the message server’s process space. The Server MTM provides access to messages under remote services. It handles connecting to remote servers to handle updating the local cache of these messages or to send messages copied to remote services when messages are copied to a remote service. The message server loads and hands off all message store operations that involve entries under a remote entry, these are the entries on the left-hand side of Figure 6.
-Functions that a Server MTM must implement:
-• Copy/MoveToLocal – called when the message server is asked to move or copy an entry that is currently under a remote service. A Server MTM might map this to retrieving a message from a remote mailbox.
-• Copy/MoveFromLocal – called when the message server is asked to move or copy from under the local service to a destination under a remote service. A Server MTM should map this to sending a message if the MTM supports sending.
-• Create, Delete, Change – called when the message server is asked to perform these operations on entries under a remote service.
-• StartCommand – this API provides a means of extending the API the Server MTM provides. Messaging clients pass a command ID and a selection of entries via the message server to the Server MTM. Examples of commands that Server MTMs might provide are: connect and synchronise the entries under a remote service with the messages on an email server, list SMS messages present on the phones SIM. These commands are MTM specific and therefore clients have to know which MTMs support which commands.
-3.2.1.3.5.5 MTM Registration
-MTMs must be registered with the message server so that clients can query what MTMs are present and the server knows which DLL to load to create a given MTM component. MTMs are registered by providing a resource file containing the MTMs UIDs, human readable name, and for each MTM interface it lists a DLL and the ordinal at which the constructor for that interface exists. The message server will search the ROM drive for MTM registration resource files on start-up and it will automatically register any MTMs found. For registration of MTMs installed on other drives, the message server provides an API to register and de-register an MTM. Registration will persist across a reboot, so an MTM only needs to be registered when it is installed on the system.
-When MTMs are registered or unregistered the message server will send events to all messaging clients with a message server session open.
-3.2.1.3.6 Message Server Client API
-The Messaging Server Client API breaks down into two categories: APIs for manipulation of the message store and utility APIs.
-3.2.1.3.6.1 Message Store manipulation APIs
-Requests from clients to modify the message store fall into three categories:
-1. Operations performed entirely with local entries (entries on the right-hand side of Figure 6) for example requests to create entries in the inbox, delete an entry from the drafts folder etc. The message server handles these operations directly.
-2. Operations that involve a remote entry (entries on the left-hand side of Figure 6) for example requests to delete an entry under a POP3 service, or copy a message to an SMTP service. The message server hands these operations off to the Server MTM that owns the service under which the remote entry is stored. The only exception to this rule is the ChangeAttributes API call. This modifies flags on an index entry and is handled by the message server for both local and remote entries. This means that a Server MTM can not rely on being called when flags like the Unread flag are changed. Note that operations can not involve two remote entries; therefore requests to copy entries between a remote service representing one POP3 account to a remote service representing another POP3 account will fail with an error.
-3. Requests that are explicitly directed at a Server MTM via the TransferCommand API. These commands are just passed to the correct Server MTM by looking up the Service ID and MTM of the first message in the selection passed into the command.
-The message server sends events when entries in the message store are modified to messaging clients that have a session open with the server.
-Where the API provides asynchronous functions to modify the message store or transfer a command to a Server MTM, the functions will return a message server operation object. This object can be used to request progress on operation or cancel the operation. Deleting the operation object returned, or closing the session used to make the request will result in the operation being cancelled, therefore a messaging client must remain running until operations it has requested have either completed or they will be cancelled. See appendix A.1 for an example of an asynchronous copy operation. If a Server MTM operating on the same remote service is already handling an operation, the message server will queue the new operation to be handled when the Server MTM becomes free. Requests for progress of operations that are queued will fail with KErrNotReady. The fact that the queue is based on the remote service ID means that you can have two Server MTMs of the same type running at the same time as long as they are operating on different services. So for example you can have two separate POP3 MTMs running synchronising different remote services with email servers.
-3.2.1.3.6.2 Utility APIs
-1. Access to MTM registries – These allow clients to construct instances of the interfaces an MTM implements.
-2. Register / Unregister an MTM.
-3. Change Drive – The message server closes the current message store and opens one on the drive specified. If no message store is present on the drive specified a new message store is created. The message sever can have only one mail store open at a time, if the current mail store is not available because a the disk the mail store is on is not present then the message server will switch the mail store back to the C: drive if an attempt is made to create a message in the inbox.
-4. Launching Editors – This launches the correct editor for a message. It is implemented by delegating the request to the UI MTM
-3.2.2 Messaging / Send As APIs
-3.2.2.1 Key Relationships and Dependencies
-
-Figure 12 SendAs Version 1 Dependencies
-SendAs version 1 and only present in releases before v9.0. SendAs uses the Messaging Client API to access the registry of Client MTMs and construct the Client MTM interfaces. The Client MTMs are then used for composing the message. SendAs requires clients to implement the MSendAsObserver interface. This interface is responsible for checking the return value of the capability queries made to Client MTMs that require a response and also for rendering message types that require it. The only message type supplied by Symbian that requires rendering is Fax, however this MTM has been removed in 8.0a and future releases.
-3.2.2.2 API Purpose - Further Elaboration
-3.2.2.2.1 SendAs API (pre – v9.0)
-The SendAs API makes use of the Client MTM interface and the Messaging Client API to provide a generic API for creating messages. Note despite the name of this component SendAs does not provide an API to send the message.
-SendAs builds a list of registered MTMs, then queries each MTM to check whether it supports sending, removing those MTMs from the list that do not support sending. This list is then provided to the messaging client application. At this point the application can add more constraints on the list of MTMs; for example it can insist the MTM supports Attachments or more than a certain size of body text. SendAs queries each of the MTMs about the requirements and will drop any MTMs from the list that does not meet them. When the application has finished adding requirements it selects one of the MTMs left in the list and uses that to compose the message, adding addresses, a subject, body text and attachments.
-SendAs supports setting a BIO Type for the message that is composed. This tells the transport that the body text represents a BIO Message. This is used when sending business cards from the contacts application as SMS messages; the contacts application puts the vCard data in the body text of the message and the transport sends it correctly. If the MTM in question supports attachments then the vCard is attached to the message.
-A new CSendAs object must be created for each message the application wishes to create.
-3.2.3 Platform Security Compliant SendAs Server (v9.0 onwards)
-
-Figure 13 SendAs Version 2 Dependencies
-From v9.0 and onwards the CSendAs has been replaced by the SendAs server component. The new SendAs server controls the access to the message store. Some of the key SendAs Server features are listed as follows.
-• Send a message once the capability policing of the client application has been completed.
-• Allow client applications to launch an editor for a specified message type.
-• Allow client applications to query the message type.
-The main client-side API is the RSendAs class. The client applications use this to connect to the Send-As server. The session object on the server-side is an instance of CSendAsSession.
-Client applications create messages using the RSendAsMessage API. Opening an RSendAsMessage object on Send-As server session creates a CSendAsMessage object in the Send-As server. There is a one-to-one mapping between an RSendAsMessage object and a CSendAsMessage object. This allows client applications to create multiple messages concurrently.
-
-3.2.4 Messaging / Schedule Send APIs
-3.2.4.1 Key Relationships and Dependencies
-
-Figure 14 Schedule Send Dependencies
-The Schedule Send Server MTM base class depends on the task scheduler to launch the schedule send executable at the correct time. To send the message with a package of data previously passed into the task scheduler by the Server MTM. The schedule send executable then uses the Messaging Client API to actually perform the requested operation.
-3.2.4.2 API Purpose - Further Elaboration
-3.2.4.2.1 Schedule Send
-The Schedule Send functionality is delivered by four components:
-Server MTM Base Class – The base class provides support to Server MTMs that wish to support scheduled operations.
-Data Structures – These are classes used to represent the data associated with a scheduled operation.
-Executable – The executable is run by the task scheduler at the scheduled time.
-The Task Scheduler – This component is part of the system libraries subsystem. Currently the SMS and Fax Server MTMs support scheduled sending.
-Clients request the Server MTM schedules operations via additional commands passed to TransferCommand API; this is passed to the Server MTM via the message server. The Server MTM packages the operation ID, a selection of message IDs, how often to poll for progress and an MTM specific buffer. It then passes this package of data to the task scheduler requesting that it launches the schedule send executable at the correct time with the packaged information.
-When the task scheduler launches the schedule send executable, it unpacks the schedule information and uses the Messaging Client API to request the Server MTM to perform the operation.
-Schedule Send supports a retry mechanism if the operation fails. The Server MTM has a resource file containing a mapping from the error codes the operation can fail with and actions to be performed. For example the SMS resource file has a mapping such that if the operation fails with an error code indicating a bad phone number the SMS will be set to failed and left in the outbox. Whereas if it fails with a error code indicating temporary network failure the send operation will be scheduled to be resent later with a maximum of three retries.
-3.2.5 Messaging / Watchers APIs
-3.2.5.1 Key Relationships and Dependencies
-
-Figure 15 Watcher Dependencies
-The watcher executable’s dependency on the message server is the result of a performance measure. The watcher process creates a message server session before initialising each of the watcher plug-ins and closes the session when it has finished. This keeps the message server running during initialisation avoiding starting and stopping the message server if each watcher plug-in opens and closes sessions.
-3.2.5.2 API Purpose - Further Elaboration
-The watcher framework consists of an executable that is launched when the device boots. The component that is responsible for launching it depends on the UI family. When the watcher.exe is launched it will load each DLL in z:\system\libs\watchers which has a second UID as KWatcherUid and calls the first DLL entry point to construct a CActive object.
-From v9.0 and onwards watcher DLLs are found by scanning the directory \resource\messaging\watchers for registry files. These files contain the name of a watcher DLL that can be loaded from ROM i.e. z:\sys\bin.
-The framework has retry behaviour if the first entry point leaves, in this case the watcher framework will start a timer and try and construct the watcher object 10 seconds later. Five attempts are made before the watcher plug-in is assumed to have failed completely. Once the watcher framework has constructed all the watchers it starts the active scheduler which should never exit.
-Watcher plug-ins typically make a request to another subsystem such that they will be completed when an external event like a fax line ringing or an SMS being received occurs. When the watcher has completed processing the request it will wait for the next event.
-No support for starting / stopping watchers is provided. This is a limitation that makes watchers unsuitable for operations like listening for messages beamed via IR, as the watcher should only run while the IR port is active.
-3.2.6 Messaging / Message URL Handler APIs
-3.2.6.1 Key Relationships and Dependencies
-
-Figure 16 Message URL Handler Dependencies
-3.2.6.2 API Purpose - Further Elaboration
-The Message URL Handler provides support for creating messages and launching messaging editors from URLs such as mailto:infobot@example.com?subject=current-issue. Note there is no dependency between the Message URL Handler application which processes the URLs and the Message URL Handler recognisers which maps from URLs to mime types.
-3.2.6.2.1 Message URL Handler Application
-This is a Symbian OS application that registers with the application framework that it can handle the mime types: x-epoc-url/fax, x-epoc-url/mailto and x-epoc-url/sms. When launched with a URL it will parse the URL to retrieve the address and other header fields and then use the SendAs API to create a new message with the correct address, headers etc. The application then uses the APIs in the MturUtils class provide by the mtmbase component in the messaging framework to launch the correct editor for the given message type. The application is marked as hidden and therefore should not be listed by UIs in application browsers.
-3.2.6.2.2 Message URL Recognisers
-This is a plug-in to the recogniser framework it will be called when the application framework wishes to recognise a file. Recognisers are called with the file name, in this case a URL, and a buffer containing the start of the file. The message URL recogniser compares the start of the URL with the URL schemes it recognises, if it finds a URL scheme it knows about it maps it to a mime type. The recogniser ignores the buffer passed in.
-Schemes recognised:
-Scheme Mime type
-mailto: X-Epoc-Url/mailto
-fax: X-Epoc-Url/fax
-sms: X-Epoc-Url/sms
-mms: X-Epoc-Url/mms
-See the application framework architectural description for more information on recognisers [R2].
-3.2.7 Messaging / SMS APIs
-3.2.7.1 Key Internal Relationships and Dependencies
-
-Figure 17 SMS Internal Dependencies
-3.2.7.2 Key External Relationships and Dependencies
-
-Figure 18 SMS External Dependencies
-3.2.7.3 API Purpose - Further Elaboration
-3.2.7.3.1 SMS Watchers
-The SMS watchers are made up of two watchers, the nbswatcher.dll and the wapwatcher.dll, and some common base classes in biowatcher.dll. The watchers listen for incoming messages from the SMS stack, part of the nbsprotocols subsystem [R3], and the WAP stack part of the WAP-Stack subsystem [R4].
-3.2.7.3.1.1 NBS Watcher
-The NBS watcher handles reception of SMS messages. When initialised by the watcher framework (see section 3.2.4) the watcher queries the bio messaging database for bio messages that are listed as having a type of ENbs. For each of these bio messages the watcher creates an object that opens a connection to the SMS stack and waits for the particular message type. The message types are either defined by the port number the message will be received on or by a string to watch for at the start of the message. For example Internet Access Configuration Point messages are start with “//SIAP11” and vCards are received on port 226. Finally the watcher listens for all other messages received from the SMS stack.
-When the NBS Watcher receives a non-class 2 SMS message it creates a new entry under the global inbox in the message store. For class 2 messages the entry is created in the class 2 folder as defined by the SMS settings, this may also be the global inbox. The details field of the entry is used to store the phone number of the incoming message or the name of the sender if the watcher finds a match for the phone number in the contacts database. The description field is used to store the first N characters of the SMS message, where N is defined in the SMS settings, or for bio messages the description as retrieved from the bio database. Bio messages also have the BioType field set to the UID of the bio message as retrieved from the bio database. The CSmsHeader class, which is a wrapper around the CSmsMessage class provided by the nbprotocols subsystem [R3], is used to externalise the SMS message to the entry’s CMsvStore. The watcher also places a copy of the body text of the message in the rich text stream of the entry’s CMsvStore.
-The NBS Watcher is also responsible for handing special SMS types including:
-• Replace Type Messages – When the watcher receives a message of this type it will scan the folder the message would have been delivered to for messages that have a matching protocol ID and from address. For each of the messages it checks whether the time stamps from the service centre and discards the older message.
-• Message Indications – The watcher can listen for incoming message waiting indications. The CSmsSettings class defines whether the watcher will listen and whether it will deliver the messages to the inbox or discard them. If the watcher is configured to listen for messages then it will use the SMS utilities in the SMS Client MTM to decode the message to determine the notification type and number of messages, e.g. 3 Email messages waiting, the strings for these messages are in the smss.rss resource file.
-• Delivery Reports – As with Message Indications the watcher can be configured to listen for these and again the SMS utilities get a string from the smss.rss resource file to put in the description field.
-The NBS Watcher handles changes to the bio database using the observer mechanism provided by the bio message database to observe when bio message types are added or removed and starting or stopping the object watching for that bio message type.
-3.2.7.3.1.2 WAP Watcher
-The WAP watcher listens for incoming messages from the WAP stack using the WAP message API [R4]. To determine ports to use to listen for messages the watcher queries the bio message database for bio message types EWsp, EWspSecure, EWap, EWapSecure and registers as an observer of the bio database and so will listen for new bio message with these types as they are added. The watcher stores the messages in the global inbox tagged with the bio type listed in the bio message database.
-3.2.7.3.2 SMS Client MTM
-The SMS Client MTM implements the standard set of Client MTM APIs described in Client MTM. In addition it provides:
-• Access to the CSmsHeader object that is used to represent the SMS message.
-• Access to the SMS settings stored in the associated SMS service.
-• The APIs required by Send As to allow Send As to create SMS messages including setting the bio type of the message to allow clients of Send As to send bio messages such as vCards and vCals. The data of the bio message is stored in the body text of the SMS message.
-• Simple check for valid SMS addresses, and SMS address is considered valid if it contains at least one digit.
-• Reading and writing SIM parameters.
-3.2.7.3.3 SMS Utilities
-These provide:
-• Classes to represent and store SMS messages (CSmsHeader), and SMS settings (CSmsSettings, CSmsMessageSettings) and a SMS number (CSmsNumber).
-• The CSmsHeader class contains and allows clients to access the CSmsMessage class that the nbsprotocols subsystem provides. This contains the entire SMS message and not just the header.
-• Functions to generate descriptions and details fields to store with SMS messages, including decoding special messages such as message indication and status report messages, reading resource file for descriptions strings of special messages, using the contacts database to replace phone numbers with names.
-• API to validate a GSM number.
-• Find the TMsvId of the SMS service entry.
-3.2.7.3.4 SMS Server MTM
-3.2.7.3.4.1 Sending Messages
-The SMS Server MTM handles sending of SMS and WAP messages via the SMS stack and the WAP stack. To support this it implements the CopyFromLocal API inherited from the Server MTM base class. It implements this as sending SMS messages and moving successfully sent messages to the Sent folder. When sending the SMS message the Server MTM checks the bio type of the message and uses the bio database to check the transport type for the bio message. The MTM supports ENbs that is sent via the SMS stack and EWap, EWapSecure that are sent via the WAP stack. The MTM does not support EWsp or EWspSecure although the watchers do support receiving them.
-If a message fails to send, sending is retried according to the settings in the smss.rss resource file as described in the schedule send section 3.2.3.
-3.2.7.3.4.2 Scheduling Messages
-The SMS Server MTM implements scheduled sending API by sub-classing from the schedule send Server MTM (see section 3.2.3). It accepts requests from clients either via the SMS Client MTM InvokeAsync API or via the CMsvSession::TransferCommand API to schedule messages to be sent or to delete existing schedules. When it receives a request to schedule a message it packages up the command and uses the scheduled send functionality to request that the task scheduler ask it to send the messages at a future point in time.
-3.2.7.3.4.3 Phone Store
-The phone store is the name given to storage of SMS messages outside of the message store. In the case of GSM phones this is the SIM. The SMS Server MTM accepts requests from clients to copy/move messages to and from the SIM and delete messages from the SIM. For example when copying to the SIM it packages up the SMS message and passes it to the SMS stack with a request to write it to the SIM. If the class2 folder has been set in the SMS settings class then the Server MTM will copy the SMS message to the SIM and then update the SMS message in the message store with details of the slot on the SIM that has been used to store the SMS and the fact that it is stored on the SIM.
-3.2.7.3.4.4 SIM Parameters
-The Server MTM provides functions to read / write SIM parameters, again these requests are passed to the SMS stack to be processed.
-3.2.8 Messaging / CDMA SMS APIs
-3.2.8.1 Key Internal Relationships and Dependencies
-
-Figure 19 CMDA SMS Internal Dependencies
-3.2.8.2 Key External Relationships and Dependencies
-`
-Figure 20 CDMA SMS External Dependencies
-3.2.8.3 API Purpose - Further Elaboration
-3.2.8.3.1 CDMA SMS Watchers
-The CDMA SMS watchers are made up of six watchers, the cdmanbswatcher.dll, vmnwatcher.dll, wemtwatcher.dll, wmtwatcher.dll, wptwatcher.dll, and the wapwatcher.dll, and some base classes in biowatcher.dll and cdmasocketwatcher. While the WAP watcher is common for both GSM and CDMA, the other watchers: CDMA NBS watcher, VMN watcher, WEMT watcher, WMT watcher, and the WPT watcher are used for CDMA only. The watchers listen for incoming messages from the CDMA SMS stack, part of the nbsprotocols subsystem [R3], and the WAP stack part of the WAP-Stack subsystem [R4].
-3.2.8.3.1.1 CDMA NBS Watcher
-The CDMA NBS watcher is similar to the NBS watcher and it handles bio messages defined in bio database. The CSmsHeader class is extended to wrap around the CCdmaSmsMessage class provided by the nbprotocols subsystem [R3], and is used to externalise the CDMA SMS message.
-For handling special CDMA SMS type, the CDMA NBS watcher is responsible for handling Message Indications as described in section 3.2.7.3.1.1 NBS Watcher.
-3.2.8.3.1.2 WAP Watcher
-The GSM WAP watcher is used to handle CDMA WAP message as well. The WAP watcher listens for incoming messages from the WAP stack, which can listen from the CDMA SMS stack or GSM SMS stack as appropriate. See 3.2.7.3.1.2 for more info about WAP watcher.
-3.2.8.3.1.3 Other CDMA Watchers
-The VMN watcher, WEMT watcher, WMT watcher and WPT watcher are CDMA watchers that handle reception of CDMA SMS messages. All CDMA SMS messages are associated with a teleservice. Therefore, each of the CDMA watchers is responsible for handling one teleservice: VMN watcher handles VMN SMS messages, WEMT watcher handles WEMT SMS messages, WMT watcher handles WMT SMS messages, and WPT watcher handles WPT SMS messages. The CSmsHeader class is reused to externalise the CDMA SMS message.
-The CDMA watchers are also responsible for handling special SMS types including:
-• Duplicate Message – When the watcher receives a duplicate message, it will discard the duplicate message as defined by the CDMA service settings.
-• User Acknowledge – The watcher can listen for user acknowledgment message of its teleservice type.
-• Delivery Acknowledge – The watcher can listen for delivery acknowledgment message of its teleservice type.
-• Read Acknowledge – The watcher can listen for read acknowledgment message of its teleservice type.
-3.2.8.3.2 CDMA SMS Client MTM
-The CDMA SMS Client MTM implements the standard set of Client MTM APIs described in Client MTM. In addition it provides:
-• Access to the CSmsHeader object that is used to represent the SMS message.
-• Access to the SMS settings stored in the associated SMS service. These settings are store in file store pre v9.0 but stored in Central Repository from v9.0 onwards.
-• The APIs required by Send As to allow Send As to create SMS messages including setting the bio type of the message to allow clients of Send As to send bio messages such as vCards and vCals. The data of the bio message is stored in the body text of the SMS message.
-• Simple check for valid SMS addresses, and SMS address is considered valid if it contains at least one digit.
-• Reading and writing SMS messages to R-UIM.
-3.2.8.3.3 CDMA SMS Utilities
-The CDMA version of SMS utilities are binary compatible with the GSM version of SMS utilities. But the classes that store SMS Message (CSMSHeader), and SMS settings (CSmsSettings, CSmsMessageSettings) and SMS number (CSmsNumber) are extended to store CDMA information. The CSmsHeader class is extended to contain and allow clients to access the CCdmaSmsMessage in addition to the CSmsMessage. Other functions provided by the GSM SMS Utilities is also provided by the CDMA version of SMS utilities, see 3.2.7.3.3 for information about GSM SMS Utilities.
-3.2.8.3.4 CDMA SMS Server MTM
-3.2.8.3.4.1 Sending Messages
-The CDMA SMS Server MTM handles sending of CDMA SMS and WAP messages via the CDMA SMS stack and the WAP stack. To support this it implements the CopyFromLocal API inherited from the Server MTM base class. It implements this as sending SMS messages and moving successfully sent messages to the Sent folder. When sending the CDMA SMS message the Server MTM will use the appropriate teleservice type. The MTM supports ENbs that is sent via the SMS stack and EWap, EWapSecure that are sent via the WAP stack. The MTM does not support EWsp or EWspSecure although the watchers do support receiving them.
-If a message fails to send, sending is retried according to the settings in the smss.rss resource file as described in the scheduled send section 3.2.4.
-3.2.8.3.4.2 Scheduling Messages
-The CDMA SMS Server MTM implements scheduled sending API by sub-classing from the schedule send Server MTM similar to implemented in the GSM SMS Server MTM. See 3.2.7.3.4.2 for more information.
-3.2.8.3.4.3 Phone Store
-In the case of CDMA phones, phone store can be phone-based storage or R-UIM based storage. The CDMA SMS Server MTM accepts requests from clients to copy/move messages to and from the phone/R-UIM and delete messages from the phone/R-UIM. For example when copying to the R-UIM it packages up the SMS message and passes it to the CDMA SMS stack with a request to write it to the R-UIM.
-3.2.8.3.5 Configuration for using CDMA SMS MTM
-The CDMA messaging components currently only support single mode, but it is designed such that it can become multimode in the future. Currently, -Dcdma option is used to for selecting CDMA mode for using emulator and building ROM.
-
-
-3.2.9 Messaging / Email APIs
-3.2.9.1 Key Internal Relationships and Dependencies
-
-Figure 19 Email Internal Dependencies
-
-3.2.9.2 Key External Relationships and Dependencies
-
-Figure 20 Email External Dependencies
-3.2.9.3 API Purpose - Further Elaboration
-3.2.9.3.1 Email Overview
-The Email plug-ins consist of a set of utilities and MTMs for POP3, IMAP4 and SMTP. For each email account a pair of services entries is created in the message store. For a POP3 account there will be an SMTP service and a POP3 service, for an IMAP4 account there will be an SMTP service and as IMAP4 service. These entries are used to store the settings for the email transport. Each of the service entries has its related ID set to the other member of the pair. The SMTP service is created invisible so the user only sees the POP3 or IMAP4 service entry, copying a message to the SMTP service will cause the SMTP Server MTM to attempt to send the message. The POP3 and IMAP4 MTMs provide functionality to synchronise with a remote email server this is achieved by extending the Client MTM interface via the InvokeAsync API. Synchronisation of a POP3 or IMAP4 account will result in copying headers and optionally body text and attachments from the email server and creating message entries under the POP3 or IMAP4 service entry.
-Email messages are represented in a common format whether they are being sent via SMTP or downloaded via POP3 or IMAP4. The email client utilities provide the classes for creating and manipulating the entry structure used to store emails. The email server side utilities provide classes to convert between the entry structure used to store emails in the message store and RFC2822 email messages sent to SMTP servers and retrieved from POP3 servers. IMAP4 email messages are parsed by the email server and the IMAP4 Server MTM requests and stores the individual parts of the messages.
-3.2.9.3.2 Email Client Utilities
-The email client utilities are part of the imcm DLL and provide classes for:
-• Storage of email messages including mime headers, RFC2822 headers, attachments, body text and encoding information in the message store
-• Manipulating email messages, for example adding attachments, replying etc.
-• To wrap up the character converters used to convert between standard character sets and Unicode. These make use of the charconv component that is part of the system libraries subsystem.
-• Storage of Email settings in the message store.
-• Progress information for email operations.
-The utilities are used directly by clients to access parts of email messages for display. CImEmailMessage provides the functionality used by clients displaying email messages, including listing attachments, getting body text and resolving URIs in M-HTML messages.
-The Email Client MTMs use the utilities when they are asked to create, reply to and forward messages CImEmailOperation provides the functionality to perform these operations. Each email message is represented by a parent message entry and then entries to represent mime folders and mime parts, see Figure 7 for an example, so adding or deleting mime parts involves walking the tree of entries and inserting / removing entries as appropriate.
-3.2.9.3.3 Email Server MTM Utilities
-The Email Server MTM Utilities are responsible for generating and parsing of RFC2822 format email messages and providing an API to wrap up a TCP/IP connection to a remote email server.
-• Parsing of RFC2822 Email Messages – The utilities provide an API that accepts the text of an RFC2822 email message a line at a time and stores the email message in messaging’s internal format for email messages. See the Email Client Utilities for details of this format. The API handles storing of RFC2822 headers, MIME headers, decoding of Base64 encoded or uuencoded attachments and decoding of text received in character sets supported by the charconv component. This API is only accessible to Server MTMs, as it requires classes that can only be instantiated while running within the message server process. See the Messaging Functional Specification [R1] for detail on which email specifications the utilities support.
-• Generation of RFC2822 Email Messages – The utilities provide an API to convert an email in messaging’s internal format into an RFC2822 email message. The API provides access to the RFC2822 text a line at a time for streaming to an SMTP server. The exact format of the email depends on the settings passed in; the API can generate plain RFC2822 email messages with uuencoded attachments, MIME email messages with Base64 encoded attachments, or M-HTML email messages with Base64 encoded attachments. See the Messaging Functional Specification [R1] for detail on which email specifications the utilities support.
-• TCP/IP socket wrapper – The utilities provide a class that abstracts a TCP/IP socket supplied by the networking subsystem into an API that supports sending and receiving lines of text to / from a remote server. This API is used to connect to remote email servers by each of the email Server MTMs. The API can either create insecure or secure sockets enabling the SSL encryption provided by the networking subsystem. It also supports changing an insecure socket into a secure socket, this enables the email Server MTMs to implement email protocols where the initial connection to the server is insecure and then a secure socket is negotiated before sending or requesting any sensitive information.
-3.2.9.3.4 POP3 MTMs
-The POP3 MTMs implements the functionality to synchronise the local message store with a remote POP3 email server.
-3.2.9.3.4.1 Client MTM
-The POP3 Client MTM implements the standard Client MTM APIs and other extensions:
-• Reply to, forward – These are accessible via the ReplyL and ForwardL APIs of a Client MTM and are implemented as calls to the email utilities class CImEmailOperation.
-• Reply to, forward, create new messages, create receipts and forward as attachment – These are accessible as commands available via the InvokeAsyncFunction API of the Client MTM, they are implemented as calls to CImEmailOperation.
-• Connecting, disconnecting and copying email while connected – These operations are accessible as commands available via the InvokeAsyncFunction API of the Client MTM, they are implemented as calls to the POP3 Server MTM.
-• Querying connection status – This command lets clients know whether the POP3 Server MTM is connected to an email server, and is available via the InvokeAsyncFunction API of the Client MTM. The Client MTM requests the information from the Server MTM.
-• Compound operations – The Client MTM provides functionality to wrap up connecting to email servers, copying / moving new messages or a selection of messages, and then optionally disconnecting. These commands are available via the InvokeAsyncFunction API of the Client MTM. The Client MTM implements this by using the CImPOP3GetMail class which requests the correct sequence of operations from the Server MTM, waiting for each operation to complete before requesting the next one.
-• Send on next connection If the Client MTM gets a request to connect to an email server it will check whether the POP3 settings. If send on next connection is requested it will launch the autosend.exe executable (see section 3.2.7.3.7) to handle sending messages waiting in the outbox.
-• Offline operations – The POP3 Client MTM has a command to cancel offline operations, this is available via the InvokeAsyncFunction API of the Client MTM. The Client MTM passes the request to the Server MTM.
-3.2.9.3.4.2 Server MTM
-The POP3 Server MTM handles the communication with the remote POP3 server and implementation of the POP3 protocol. The MTM uses CImTextServerSession to handle the communication with the email server and CImRecvConvert to parse the email messages downloaded, both are provided by the Email Server MTM Utilities.
-• Connect – The POP3 Server MTM will open a socket to the email server using CImTextServerSession and login user the username / password in the POP3 settings. After a successful connection the Server MTM will attempt to synchronise the current state of headers stored on the email server with the set stored in the message store and then start any pending offline operations. After the connect operation has completed the Server MTM will inform the message server that it is expecting more operations via the CommandExpected API and therefore the message server will not delete and unload the Server MTM.
-• Populate Message – The POP3 Server MTM treats requests to copy a message from and to the POP3 service as a request to download the full message.
-• Offline operations – When the POP3 Server MTM receives a request to copy, move, or delete and is not connected to a POP3 email server the Server MTM will store the operation in the CMsvStore of the entry being modified and perform the operation on the next connection to the email server.
-• Disconnect – When disconnecting from a remote email server the POP3 MTM will run any pending offline operations stored. After the disconnect operation completes the Server MTM will allow the message server to delete and unload the Server MTM by setting the CommandExpected API to false.
-3.2.9.3.5 IMAP4 MTMs
-The IMAP4 Server MTM implements the functionality to synchronise the local message store with a remote IMAP4 email server.
-3.2.9.3.5.1 Client MTM
-The IMAP4 Client MTM implements the standard Client MTM APIs and other extensions:
-• Connecting, disconnecting, synchronising, un/subscribing folders – These operations are accessible as commands available via the InvokeAsyncFunction API of the Client MTM, they are implemented as calls to the IMAP4 Server MTM.
-• Send on next connection – If the Client MTM gets a request to connect to an email server it will check whether the IMAP4 settings. If send on next connection is requested it will launch the autosend.exe executable (see section 3.2.7.3.7) to handle sending messages waiting in the outbox.
-• Reply to, and forward messages – These are accessible via the ReplyL and ForwardL APIs of a Client MTM and are implemented as calls to the email utilities class CImEmailOperation.
-• Reply to, forward, create new, create receipt, forward as attachment – These are accessible as commands available via the InvokeAsyncFunction API of the Client MTM, they are implemented as calls to CImEmailOperation.
-• Querying connection status – These commands let clients know whether the IMAP4 Server MTM is connected to an email server and whether it is currently processing a request. They are available via the InvokeAsyncFunction API of the Client MTM. The Client MTM requests the information from the Server MTM.
-• Compound Connection and synchronisation – The IMAP4 Client MTM provides a compound operation that connects and synchronises with an IMAP4 server. This operation is implemented as a client side object that combines requests to the IMAP4 Server MTM. The client side operation can complete the client request either after the connection, after the connection + sync or after the connection + sync + disconnect. The client will keep requesting that the inbox be resynchronised at a configurable interval so new messages received in the inbox on the server will appear under the IMAP4 inbox. The CImapConnectAndSyncOp class handles these compound operations.
-• Compound Connect and copy / move / populate messages – The IMAP4 Client MTM provides a compound operation that connects to an IMAP4 server and copies moves or populates messages. The implementation is provided by the CImImap4GetMail class which makes calls back into the IMAP4 Client MTM.
-• Offline operations – The IMAP4 Client MTM has a command to cancel offline operations, this is available via the InvokeAsyncFunction API of the Client MTM. The Client MTM passes the request to the Server MTM.
-3.2.9.3.5.2 Server MTM
-The IMAP4 Server MTM handles the communication with the remote IMAP4 server and implementation of the IMAP4 protocol. The MTM uses CImTextServerSession to handle the communication with the email server. The IMAP4 Server MTM opens two connections to the IMAP4 server this enables users to download messages while the Server MTM is performing a background synchronisation if requested by the Client MTM.
-• Connect – The IMAP4 Server MTM will open a socket to the email server using CImTextServerSession and login using the username / password in the IMAP4 settings. After a successful connection the Server MTM will optionally attempt to synchronise the current state of headers stored on the email server with the set stored in the message store and then start any pending offline operations. After the connect operation has completed the Server MTM will inform the message server that it is expecting more operations via the CommandExpected API and therefore the message server will not delete and unload the Server MTM.
-• Copy, Move messages – The IMAP4 Server MTM supports copying and moving messages between folders on the IMAP4 server and between the IMAP4 server and local folders.
-• Delete messages – The IMAP4 Server MTM will mark the email as deleted on the server; however it will not be deleted until the IMAP4 Server MTM disconnects from the server.
-• Folders – The IMAP4 Server MTM will allow folders to be subscribed, unsubscribed, renamed, copied, moved, and created within the IMAP4 service. Subscribing to a folder means that it will be visible to the user and synchronised with the remote server. The inbox is always subscribed.
-• Offline operations – When the IMAP4 Server MTM receives a request to copy, move, or delete and is not connected to an IMAP4 email server the Server MTM will store the operation in the CMsvStore of the entry being modified and perform the operation on the next connection to the email server.
-• Disconnect – When disconnecting from a remote email server the IMAP4 MTM will run any pending offline operations stored. After the disconnect operation completes the Server MTM will allow the message server to delete and unload the Server MTM by setting the CommandExpected API to false.
-
-3.2.9.3.6 SMTP MTMs
-The SMTP MTMs provide functionality to send email messages. They are made up of the Client MTM that is part of the imcm DLL and the Server MTM.
-3.2.9.3.6.1 Client MTM
-The SMTP Client MTM implements the standard Client MTM APIs including the functions required to allow clients of Send As to create email messages.
-3.2.9.3.6.2 Server MTM
-The SMTP MTMs provide functionality to send email messages; it interprets requests to copy entries to an SMTP service as a request to send those messages. In addition it responds to two extended commands via the StartCommand Server MTM interface. These commands are KSMTPMTMIsConnected that responds with whether the Server MTM is currently connected to a remote SMTP server and KSMTPMTMSendOnNextConnection which performs the same operation as copying a selection of messages to an SMTP service. The only difference between the copy operation and the KSMTPMTMSendOnNextConnection operation is that the latter can be called without a selection of messages.
-When the Server MTM receives a request to send messages it builds a selection of messages consisting of the messages passed into the operation and any messages waiting in the outbox to be sent. To determine which messages in the outbox are waiting to be sent the SMTP server checks for messages that have the same service ID as the destination of the send operation and have a sending state of KMsvSendStateWaiting, KMsvSendStateScheduled or KMsvSendStateResend. This means that any request to send messages may result in more messages being sent than explicitly listed in the selection passed to the send operation.
-The Server MTM restores its settings from the SMTP service it has been asked to copy the messages to. Then it connects to the SMTP server using the CImTextServerSession class in the Email Server MTM Utilities, passing in the SMTP server address and TCP/IP port number from the SMTP settings. Then for each message to be sent the Server MTM uses the Email Server MTM utilities to generate an RFC2822 format message to send to the SMTP server, the RFC2822 text is generated on the fly as the data is sent to the SMTP server. If the SMTP server accepts the message to be sent then the Server MTM moves the message to the sent folder and sets its sending state to sent. If the SMTP server rejects the message then the Server MTM leaves the message in the outbox and sets the sending state to failed. Separate emails are generated for BCC recipients to ensure that the SMTP server doesn’t incorrectly include BCC recipients in emails sent to addresses in the To and CC fields of the email.
-3.2.9.3.7 Autosend
-The Autosend component is an executable that is kicked off by the POP3 and IMAP4 Client MTMs if the send on next connection setting is set. This executable will just make a request to the SMTP Server MTM to send messages associated with the SMTP service related to the POP3 or IMAP4 service, wait for the operation to finish and then exit.
-3.2.10 Messaging / MMS APIs
-The MMS module has been removed from v9.0 and onwards.
-3.2.10.1 Key Internal Relationships and Dependencies
-
-Figure 21 MMS Internal Dependencies
-3.2.10.2 API Purpose - Further Elaboration
-3.2.10.2.1 MMS Overview
-The MMS MTM provides functionality for creating, accessing, sending and receiving MMS messages. Messages are sent and received without the client application needing to open or close any kind of session. The management of the MMS session is handled entirely within the MTM.
-MMS clients are alerted when a new message is available for download via the WAP Push mechanism. A WAP push watcher is provided to handle these notifications. After the notification the message can be downloaded over WSP or HTTP. Messages are sent by posting the data over WSP or HTTP. The Symbian MMS implementation can handle sending or receiving MMS message over either protocol.
-MMS messages are based on the MIME format but are binary encoded using WSP. Note that MMS messages are encoded in this way even if they are posted over HTTP as opposed to WSP. The codec component is responsible for this encoding and decoding.
-3.2.10.2.2 MMS Utilities
-3.2.10.2.2.1 Key External Relationships and Dependencies
-
-Figure 22 MMS Utilities External Dependencies
-The MMS utilities provide the message and settings encapsulation classes. The MMS settings and messages are stored in the message store, the MMS utilities provide the interfaces to access this data.
-3.2.10.2.2.2 Settings
-The settings functionality provided by the MMS utilities allows the messaging client to persist MMS settings in the message store. Supported settings include:
- MMSC (MMS server) address
- WSP or HTTP transport
- Autofetch messages on notification
- Preferred IAP for the MMS network connection
-The settings functionality is also used by the server MTM to retrieve the settings prior to message sending or fetching.
-3.2.10.2.2.3 Message Encapsulation
-The message classes provide the message access functionality. Messages can be created, stored, restored and read using these classes. Functionality includes:
- Adding media objects to the message
- Enumerating through media objects
- Adding recipients, subject line, etc. to a message
- Adding other headers to the message, e.g. expiry date
- Finding the appropriate media object for a given URI in the SMIL part (URI resolving)
-The message data is stored in the message store using one entry per message regardless of the number of media objects added to the message. This is preferable to using multiple message entries as it is faster and uses less disk space.
-Most of the message access code is common whether it is being used on the client or server side, however some parts of it are specific. For this reason it is essential that the appropriate client or server side CMmsMessage derived class is used.
-3.2.10.2.3 MMS Watcher
-3.2.10.2.3.1 Key External Relationships and Dependencies
-
-Figure 23 MMS Watcher External Dependencies
-
-The MMS watcher plug-in is responsible for intercepting incoming MMS notifications and delivery reports then taking the appropriate action. It is implemented as a WAP Push watcher plug-in.
-When an MMS notification is received an MMS entry is created in the inbox using the MMS utilities. At this point the entry has its incomplete flag set. If the settings have the autofetch option selected then the MMS watcher initiates the fetch operation via the MMS client MTM.
-If a delivery report is received then the delivered flag is set on the appropriate sent message. If an outgoing message was sent to several recipients then there will be several delivered flags. A delivery report from each recipient will set the appropriate delivered flag.
-3.2.10.2.4 MMS Client MTM
-3.2.10.2.4.1 Key External Relationships and Dependencies
-
-Figure 24 MMS Client MTM Dependencies
-As with most other MTMs the MMS client MTM provides access to the server MTM functionality for messaging clients. It also implements the Send-As interface and reply and forward functionality.
-3.2.10.2.4.2 Send-As Implementation
-The Client MTM Send-As interface is implemented in the MMS Client MTM. The implementation differs slightly from other MTMs because additional presentation content may be generated depending on the media objects that are added. When simple combinations of images, sounds and text are added a SMIL presentation is generated to link them together. This is preferable to simple adding the objects as attachments where some clients render them as a list of files and others fail to render them at all.
-The SMIL data is constructed using templates stored in resource files, the GMXML (SMIL) composer is not used.
-3.2.10.2.4.3 Reply / Forward
-The Client MTM can be used to create replies to received messages or to create forwarded responses. The reply and forwarding operations are performed asynchronously.
-3.2.10.2.5 MMS Server MTM
-3.2.10.2.5.1 Key External Relationships and Dependencies
-
-Figure 25 MMS Server MTM Dependencies
-The Server MTM is the most complicated part the MMS implementation. It handles all of the state information required to send or fetch MMS messages. It is also responsible for managing the HTTP or WSP session and the connections to the phone network.
-3.2.10.2.5.2 Operations
-All MMS server MTM functionality is encapsulated in operations. An operation consists of the setup of a session, the sending, fetching and acknowledgements when appropriate, it then closes the session. The messaging client initiates an operation with a single call to the Client MTM, there is no need for the messaging client to explicitly establish the session or to know about the internal states. However, these internal states are available to the messaging client via the progress structure if this level of user feedback is required.
-Two types of operation are supported, background and foreground:
-A maximum of one foreground operation can be running at any one time. The messaging client can poll the server MTM for the progress of a running foreground operation, likewise it can cancel it if necessary.
-A background operation does not support progress information and can not be cancelled by the messaging client. It is possible to initiate background operations even if other background or foreground operations are pending. However, background operations are queued and a maximum of one will actually be running at any one time.
-The MMS watcher uses a background operation to perform automatic fetching. While the background autofetch is occurring it is still possible to start a foreground operation (such as sending a message) if required.
-3.2.10.2.5.3 Session and Connection Management
-The server MTM uses the HTTP Transport Framework to enable the HTTP or WSP session. HTTP or WSP can be selected at runtime by selecting the appropriate option in the settings. The server MTM is responsible for reading any HTTP proxy details from the CommDB and passing it to the HTTP framework. See the http transport framework architectural description for more information on recognisers [R5]
-The server MTM is also responsible for managing the connection to the phone network. Connections are opened when required using the RConnection mechanism, multi-homing is supported provided that the underlying HTTP framework transport plug-in also supports it.
-3.2.10.2.6 MMS Codec
-The MMS Server MTM is in charge of the state transitions, connection, session, the actual posting and fetching of the data from them, however it does not encode or decode the MMS PDUs. The encoding and decoding is performed by the MMS Codec.
-For decoding the Server MTM passes the Codec the MMS PDU data in a descriptor for processing. If the PDU contains a received MMS message then the message entry is updated with the decoded MMS data.
-For encoding the Server MTM passes a reference to the message store entry containing the un-encoded MMS data. The Codec then encodes it and returns the PDU to the Server MTM in a descriptor.
-
-
-3.2.11 Messaging / BIO APIs
-3.2.11.1 Key Internal Relationships and Dependencies
-
-Figure 26 BIO Message Internal Dependencies
-3.2.11.1.1.1 Key External Relationships and Dependencies
-
-Figure 27 Bio Parser External Dependencies
-
-3.2.11.2 API Purpose - Further Elaboration
-3.2.11.2.1 BIO Overview
-The BIO messaging components have been designed to unify and simplify the way in which system messages are processed. In this context ‘system messages’ refers to messages received on the device which are intended to update some attribute(s) on the system as opposed to being presented to the user. Examples of these types of messages include vCards which are parsed and then displayed to the user and when accepted modify the users contact database and OTA configuration messages which are again parsed before display to the user and if accepted create email accounts or internet access points.
-The BIO messaging components can be broken down into three groups:
-1) The BIO MTM - To initiate the parsing and processing of BIO messages
-2) The BIO Database - Maps port numbers, MIME types, etc. to bio types in order to identify the type of incoming BIO messages.
-3) The BIO Parsers - To parse and process the BIO message payload
-BIO messages are not receive by the bio messaging framework, they come over other message transports for example see section 3.2.6.3.1 on the SMS watchers which describes how the SMS watchers receive bio messages and use the bio framework to tag the messages with the correct bio id.
-3.2.11.2.2 BIO MTM
-The BIO client MTM is called by the messaging client to parse or process a BIO message that has been saved in the message store. It is the responsibility of a BIO watcher to save the BIO message with the BIO flag and the appropriate BIO type set.
-The BIO client MTM does very little, its primary task is to pass on the messaging client request to the server MTM. Two operations are supported, parse and process.
-The messaging client is expected to initiate the parsing of the BIO message before processing it. The parsing step involves analysing the data and storing it in a form that can be displayed to the user via the BIO message viewer.
-Once the message has been parsed the messaging client can initiate the processing of the message.
-The BIO server MTM is responsible for deferring the parsing and processing to the appropriate BIO parser. The behaviour for the parsing and processing steps varies between parsers. See the BIO Parsers section for more information.
-The bio MTM does not support sending messages and therefore does not support reply / forwarding messages. For bio messages sending / reply etc. is supported by the particular MTM that the message is sent over, for example SMS.
-3.2.11.2.3 BIO Database
-The BIO database is used to identify the type of BIO messages. It maps message attributes such as port number, MIME type or leading string to a BIO type. These are attributes are then used by clients of the bio framework to know what ports to listen for messages on. For example the SMS watchers use the leading string to wait for SMS messages that start with that string and when storing those messages in the inbox tag them with the bio id associated with that leading string. See the SMS watcher section 3.2.6.3.1 for more examples of how the BIO database can be used.
-3.2.11.2.4 BIO Parsers
-The BIO parsers are plug-ins for parsing and processing incoming BIO messages. They are invoked by the BIO Server MTM depending on the BIO type of the message being processed. Each BIO parser implements two functions, ParseL and ProcessL. The level of functionality varies between parsers. Some parsers update the final repository with the received data, e.g. WAPP updates the CommDB with the received settings. Some parsers simply save the data in an unparsed state for processing by another component, this secondary parsing is not part of the BIO framework and must be initiated by the messaging client. An example is when GFP saves vCard data as a file as opposed to updating the contacts database, the UI must then invoke the Versit parser to parse the vCard and commit it to the contacts database.
-3.2.11.2.4.1 Generic File Parser (GFP)
-The generic file parser can be used to identify and save a variety of BIO data types, e.g. vCards and vCals. The Generic File Parser does not process the data, it simply saves it in the message store for processing by another component. The file is saved as an attachment of the message entry that was parsed.
-3.2.11.2.4.2 Nokia/Ericsson OTA Parser (WAPP)
-The WAPP parser decodes Nokia/Ericsson OTA messages and updates CommDB to reflect the received settings.
-3.2.11.2.4.3 Nokia Smart Message Internet Access Parser (IACP)
-The IACP parser decodes Nokia Smart Messages and updates the CommDB and messaging settings where appropriate.
-3.2.11.2.5 BIF Files and Utilities
-The BIF files encapsulate the information required for identifying BIO messages, these details may include the expected port number, MIME type or leading string. Different BIO watcher will use different information from these files, for an example see the 3.2.6.3.1. The information can be retrieved from the BIF files by using the BIF utilities. Generally BIO aware clients will access this information via the BIO database. BIF files are resource files previous to the v6.1 release they were binary files generated by biftool.exe.
-3.2.11.2.6 Platform Security Compliant Messaging / BIO APIs
-In the platform security model the BIO parsers are run in the client space rather than in the message server space, as is done in the non-platform secure model. If the BIO parsers are run in the message server space, it allows a client process to gain the capabilities of the message server. IPC policing can protect the message server from this.
-Also, for the message server to be able to load any BIO parser it would need more capabilities than it really requires. By running the BIO parsers in the client space, both these issues are solved. The client process must be trusted with the necessary capabilities to run the specified BIO parser.
-The BIO registry files are located in the \resource\messaging\bif read-only directory. All BIO parser DLLs are located in the \sys\bin protected directory.
-
-Figure 26 BIO Message Dependencies (v9.0)
-The BIO client MTM is responsible for loading the BIO database and BIO utilities to handle parse/process requests from clients.
-The BIO registry files no longer identify the BIO parsers DLLs via their UID – the registry file must use the BIO parser DLL name to identify them.
-3.2.12 Messaging / OBEX MTM APIs
-3.2.12.1 Key Internal Relationships and Dependencies
-
-Figure 28 OBEX Internal Dependencies
-3.2.12.2 OBEX MTM Overview
-The OBEX MTM offers simple IR and Bluetooth beaming functionality. It provides an API that is consistent with other MTMs so that the underlying OBEX APIs do not need to be used directly for beaming applications. The OBEX MTM does not provide OBEX receiving functionality, in order to receive OBEX data the underlying OBEX APIs must be used directly.
-3.2.12.2.1 OBEX MTM
-The OBEX MTM is split into three parts. OBEX MTM DLLs, IR MTM DLLs and Bluetooth MTM DLLs. The OBEX MTM DLLs can not be used on their own they provide the base OBEX MTM functionality for the derived IR and Bluetooth MTMs.
-There are two APIs that can be used to create OBEX messages:
-1) The Send-As API
-2) Linked attachments by filename
-The Send-As API provides an interface consistent with other MTMs, however it requires all attachments to be copied into the message store before they can be sent, this is often undesirable for beaming applications because it is wastes disk space. For this reason a second API is provided that allows attachments to be linked to outgoing messages by filename, when this API is used there is no need to copy the attachments to the message store.
-Unlike many other MTMs after OBEX tries to send a message it is deleted from the outbox whether the sending succeeds or fails.
-3.2.12.2.1.1 OBEX MTM Key External Dependencies
-
-Figure 29 OBEX External Dependencies
-3.2.12.2.2 IR MTM
-The bulk of the OBEX MTM functionality is provided by the OBEX MTM DLLs, the IR MTM itself just sets up the parameters.
-3.2.12.2.2.1 IR MTM Key External Dependencies
-
-Figure 30 IR MTM Dependencies
-3.2.12.2.3 Bluetooth MTM
-The bulk of the OBEX MTM functionality is provided by the OBEX MTM DLLs, the Bluetooth MTM just subclasses from the OBEX MTM and sets up Bluetooth specific parameters.
-3.2.12.2.3.1 Bluetooth MTM Key External Dependencies
-
-Figure 31 Bluetooth MTM Dependencies
-3.2.12.2.4 OBEX MTM Utils
-The OBEX MTM Utils provide utility functionality used by the other OBEX MTM DLLs. The two main areas of functionality provided by this component are:
-1) Filename linking functionality
-2) Bluetooth SDP lookup
-The filename linking functionality is provided in the utilities because linked files must be added by the client side during message creation and need to be read on the server side during sending.
-
-3.2.12.2.5 Platform Security Compliant Messaging / OBEX MTM APIs
-From v9.0 and onwards the service settings of all the derived OBEX MTMs are stored in the Central Repository. The OBEX message is stored in the message store as an attachment – from v9.0 and onwards the Attachment API is used to attach the OBEX message.
-
-3.2.13 Messaging / GMXML APIs
-3.2.13.1 Key Relationships and Dependencies
-
-Figure 32 GMXML Dependencies
-3.2.13.2 Overview
-The GMXML component provides simple XML DOM parsing and validation functionality. It is intended for parsing XML that might be needed in messaging applications, specifically SMIL parsing for MMS rendering. It is not a general purpose XML parser and will not be suitable for some applications, e.g. browsing.
-3.2.13.2.1 GMXML DOM
-The DOM implementation is fit for purpose for SMIL rendering but differs from the standard DOM design in several respects, e.g. attributes are not stored as discrete nodes, for performance reasons they are stored with the element.
-The DOM tree classes are all derived from nodes. Implemented node types include elements, text and comments. The type of each element is stored as a descriptor as opposed to an enum. This is less efficient than storing it as an enum but provides maximum flexibility when dealing with unknown element types.
-Nodes are linked together in a tree structure as might be expected in a DOM implementation. The tree structure exists on the heap.
-3.2.13.2.2 GMXML Parser and Composer
-3.2.13.2.2.1 Parser
-The parser takes XML input from a buffer or file and creates the corresponding DOM structure on the heap.
-The parser is capable of performing some basic validation. In order to validate against a DTD a class that implements the GMXML DTD interface is required. The DTD interface specifies several functions that provide the required validation, e.g. one of the functions determines if a given attribute is valid for a given element. An instance of the DTD class should be passed into the parser when validation is required but can be omitted if no validation is needed.
-3.2.13.2.2.2 Composer
-The composer takes a DOM tree and generates XML output from it. The XML output is written to a file.
-3.2.13.2.3 GMXML SMIL DTD (Validator)
-The SMIL DTD validator class is an implementation of the DTD validator interface. It implements several simple functions that provide the information required to validate SMIL data. An instance of the SMIL DTD validator should be passed into the parser if SMIL validation is required.
-4 Security
-4.1 Data caging
-For data storage in the pre-platform security compliant architecture, refer to section [3.2.1.3.2]
-For the data caging in the platform security compliant architecture of v9.0 and onwards, refer to section [3.2.1.3.3]
-4.2 Backup and restore
-The message server registers the index file with the backup server. When informed about a backup/restore it releases the index file, sending events to messaging clients informing them that the message store is unavailable. When informed it can open the index file again, it checks the time stamp on the index file; if it has changed since the file was released it reloads the index file. If the newly restored index file is found to be corrupt it is deleted and a new message store is created. See the section on page 14 for details on how the message server handles corrupt stores. The client performing the restore should always wipe the existing message store before starting to copy the message store from the backup to the device.
-4.3 Capability ranges
-In the platform security compliant architecture of v9.0 and onwards, the capabilities allocated to messaging sub-systems are as listed in following table.
-4.3.1 Capabilities granted to executables
-The following table lists the executables and their capabilities and also gives a basic example for having the required capability.
-
-Executable Capability Rationale (basic example of capability requirement)
-msexe.exe ProtServ ProtServ is required to allow the msexe.exe to start a protected server. This stops processes without ProtServ from starting a server pretending to be the message server
- ReadDeviceData ReadDeviceData is needed to able to read service settings
- WriteDeviceData WriteDeviceData is needed to able to write service settings
- NetworkServices NetworkServices capability is needed to access network transports (SMS, POP3, SMTP, IMAP4).
- LocalServices LocalServices is needed to be able to access IR and Bluetooth
- ReadUserData ReadUserData is needed to be able to read user data (e.g. service settings).
-watcher.exe ReadDeviceData ReadDeviceData is needed to able to read service settings
- WriteDeviceData WriteDeviceData is needed to able to write service settings
- NetworkServices NetworkServices capability is needed to access network transports (SMS).
- LocalServices LocalServices capability is needed for the plug-ins to access IR and Bluetooth
- ReadUserData ReadUserData is needed to be able to read user data
- WriteUserData WriteUserData is needed to be able to write user data
-autosend.exe ReadUserData ReadUserData capability is needed to be able to read data from Outbox and SMTP server MTM.
- WriteUserData WriteUserData capability is needed to be able to write data in Outbox and SMTP server MTM.
- NetworkServices NetworkServices capability is needed to access network transports (SMS, POP3, SMTP, and IMAP4).
- LocalServices LocalServices capability is needed to access the IR and Bluetooth
-SchSend.exe ReadDeviceData ReadDeviceData is needed to able to read settings data
- NetworkServices NetworkServices capability is needed to access the network transports (SMS, POP3, SMTP, and IMAP4).
- LocalServices LocalServices is needed to be trusted by other MTM
- ReadUserData ReadUserData is needed to be able to read user data.
- WriteUserData WriteUserData is needed to be able to write user data.
-SendAs.exe ReadDeviceData ReadUserData is needed to be able to read data in Outbox.
- WriteDeviceData WriteUserData is needed to be able to write data in Outbox.
- NetworkServices NetworkServices capability is needed to access the network transports (SMS, POP3, SMTP, and IMAP4).
- LocalServices LocalServices is needed to be able to access IR and Bluetooth
-
-4.3.2 Capabilities granted to DLLs
-The assigned Platform Security attributes for DLLs within messaging are outlined in the following table.
-DLL Capability
-bifu.dll All –TCB
-bioc.dll All –TCB
-biodb.dll All –TCB
-bios.dll All –TCB
-biowatcher.dll same as watcher.exe
-biut.dll All –TCB
-cbcp.dll All –TCB
-enp.dll All –TCB
-gfp.dll All –TCB
-iacp.dll All –TCB
-nbswatcher.dll same as watcher.exe
-cdmanbswatcher.dll same as watcher.exe
-CdmaSocketWatcher.dll same as watcher.exe
-VMNWatcher.dll same as watcher.exe
-WEMTWatcher.dll same as watcher.exe
-WMTWatcher.dll same as watcher.exe
-WPTWatcher.dll same as watcher.exe
-wapp.dll All –TCB
-wapwatcher.dll same as watcher.exe
-smildtd.dll All –TCB
-xmldom.dll All –TCB
-xmlparser.dll All –TCB
-smiltranslator.dll All –TCB
-imcm.dll All –TCB
-imps.dll same as msexe.exe
-imut.dll All –TCB
-msgs.dll All –TCB
-msgurlrec.mdl same as AppArc.exe (once it exists; eiksrv in meantime)
-mtur.dll All –TCB
-pops.dll same as msexe.exe
-schsend.dll All –TCB
-send.dll All –TCB
-smcm.dll All –TCB
-smcm_gsm.dll Synonym for smcm.dll
-smcm_cdma.dll Synonym for smcm.dll
-smss.dll same as msexe.exe
-smss_gsm.dll Synonym for smss.dll
-smss_cdma.dll Synonym for smss.dll
-smts.dll same as msexe.exe
-btcmtm.dll All –TCB
-btsmtm.dll same as msexe.exe
-irc.dll All –TCB
-irs.dll same as msexe.exe
-obexclientmtm.dll All –TCB
-obexmtmutil.dll All –TCB
-obexservermtm.dll same as msexe.exe
-
-The reason for setting a high capability to the DLLs is to make it possible for almost anyone to link to them. Although a DLL may have capabilities ALL-TCB (All minus TCB), its real capability is limited by the process which loads the DLL.
-4.3.3 Capabilities required to use the subsystem
-The message subsystem needs to be protected against malicious clients. The following table shows the key capabilities required to do related activities in different components.
-
-Component Related Activity Required Capability and SID
-Message server Create message in local folder No capability required
- Create message in Outbox ReadUserData, WriteUserData and MTM specific capabilities
- Access client MTM ReadUserData, WriteUserData and MTM specific capabilities
-Watcher Allow plug-ins to wait on events (e.g. arrival of SMS) Watcher always polices if the client capabilities are trusted by the watcher framework, else it will not be loaded
-Plug-ins or clients using watcher need the same capabilities as watcher.exe to be able to be loaded by watcher.
-Autosend Send messages in background NetworkService or LocalService required by the message type
-SchSend Scheduling of operations (e.g. sending SMS) SchSend always polices to see if the process was started by the Task Scheduler – if not the process terminates without performing any of the scheduled tasks. Also, the SchSend verifies that only itself and the message server created the scheduled tasks. If this is not the case, SchSend does not performing the scheduled tasks.
-SendAs Create message Draft, move it to Outbox, and send message WriteDeviceData or WriteUserData and other capability required by the message type
-
-5 Further Information
-5.1 References
-No. Document Reference Version Description
-R1 messaging_functional_specification.doc 0.6 Messaging Functional description
-R2 SGL.GT0143.161_App-Framework_Architectural_Description.doc 1.0 App-Framework Architectural Description
-R3 NBProtocols_Subsystem_Architectural_Description.doc 0.2 NBProtocols Architectural Description
-R4 WAP-stack_architectural_analysis.doc 1.0 WAP stack architectural analysis
-R5 HTTP Transport Framework Architectural Description.doc 1.1 HTTP Transport Framework 1.1 Architectural Description
-5.2 Open Issues
-The following issues need to be resolved before this document is completed:
-1. Top-level architecture diagram showing the framework and plug-ins should be added to overview section.
-2. Message store section should talk about removable media.
-3. Define "Message Server Client API" and "Messaging Client API" in the glossary, and ensure it is consistently used in the diagrams
-4. Add a sequence diagram for receiving a vCard over SMS and integrating it into contacts
-5. Add a sequence diagram for sending an SMS
-6. Add a sequence diagram for synchronising a POP3 mail box
-7. Add a sequence diagram for connecting to an IMAP4 mail box and downloading a message
-8. Capability table should be updated after the implementation of server e.g. message server
-9. Sequence diagram may need to be changed to show secured platform operation
-10. In section [3.1.1.4] the server SendAsV2 to find a correct name
-11. Section 3.2.1.3.3.1 Data Caging file 'Mtm Registry v2'may need a correct name
-12. Breakdown diagram showing all DLL, exes, apps in the messaging subsystem for both the pre-v8.0 and post v9.0 in section[3.2]
-13. Needs to say more about how the capabilities are policed and the algorithms used for different operations
-14. The dependecy between the message server and the central repository need to be listed in the email, SMS and OBEX diagrams (e.g. message store)
-15. Section 3.2.1.2 - figure 3 - Central Repository also get used by the Message server, or server MTMs (e.g. POP3), to retrieve account settings the path, required DLL and description are not given
-16. Section 4.3.3 title can be Police requirement of the sub-system, add extra column for SID in the table and list the use of SID. For example SchSend checks for Task Scheduler SID
-
-
-5.3 Glossary
-The following technical terms and abbreviations are used within this document.
-Term Definition
-BIO
-Bearer Independent Object Smart messages e.g. vCards, vCals, and WAP provisioning messages. These can currently be received via the WAP stack, SMS stack, Bluetooth or Infrared.
-BIO Type UID that represents the content type of a BIO Message.
-Message Centre Application that displays list views of messages to the user, allowing the user to perform operations such as copying messages, sending messages creating new messages etc.
-Message Viewer Application for viewing a message.
-Message Editor Application for creating or editing a message
-Message Server Symbian OS Server that handles request to modify the Message Store
-Message Store Store of messages and related information kept in the file system on a Symbian OS device.
-Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
-Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
-Global Inbox A standard folder under the local service which is used to store incoming messages like SMS MMS etc. as opposed to an IMAP4 Inbox which would be under an IMAP4 service and is a representation of the Inbox on an IMAP4 email server.
-Central Repository centralised and secure storage facility for application settings
-OBEX Object exchange protocol, used to send objects such as vCards or files between devices via infrared or Bluetooth.
-GMXML XML parser / generator for use with SMIL formatted messages.
-UID Unique Identifier, a 32 bit number allocated from a registry owned by Symbian
-IPC Inter Process Communication
-MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
+MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
MTM Registry A list of currently installed MTMs maintained by the message server.
TLS Transport Layer Security, provides encryption of a TCP/IP socket.
M-HTML Standard for including HTML in MIME email messages see http://www.ietf.org/rfc/rfc2557.txt
@@ -12153,15 +8081,15 @@
Message Editor Application for creating or editing a message
Message Server Symbian OS Server that handles request to modify the Message Store
Message Store Store of messages and related information kept in the file system on a Symbian OS device.
-Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
-Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
+Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
+Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
Global Inbox A standard folder under the local service which is used to store incoming messages like SMS MMS etc. as opposed to an IMAP4 Inbox which would be under an IMAP4 service and is a representation of the Inbox on an IMAP4 email server.
Central Repository centralised and secure storage facility for application settings
OBEX Object exchange protocol, used to send objects such as vCards or files between devices via infrared or Bluetooth.
GMXML XML parser / generator for use with SMIL formatted messages.
UID Unique Identifier, a 32 bit number allocated from a registry owned by Symbian
IPC Inter Process Communication
-MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
+MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
MTM Registry A list of currently installed MTMs maintained by the message server.
TLS Transport Layer Security, provides encryption of a TCP/IP socket.
M-HTML Standard for including HTML in MIME email messages see http://www.ietf.org/rfc/rfc2557.txt
@@ -13171,15 +9099,15 @@
Message Editor Application for creating or editing a message
Message Server Symbian OS Server that handles request to modify the Message Store
Message Store Store of messages and related information kept in the file system on a Symbian OS device.
-Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
-Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
+Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
+Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
Global Inbox A standard folder under the local service which is used to store incoming messages like SMS MMS etc. as opposed to an IMAP4 Inbox which would be under an IMAP4 service and is a representation of the Inbox on an IMAP4 email server.
Central Repository centralised and secure storage facility for application settings
OBEX Object exchange protocol, used to send objects such as vCards or files between devices via infrared or Bluetooth.
GMXML XML parser / generator for use with SMIL formatted messages.
UID Unique Identifier, a 32 bit number allocated from a registry owned by Symbian
IPC Inter Process Communication
-MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
+MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
MTM Registry A list of currently installed MTMs maintained by the message server.
TLS Transport Layer Security, provides encryption of a TCP/IP socket.
M-HTML Standard for including HTML in MIME email messages see http://www.ietf.org/rfc/rfc2557.txt
@@ -14189,15 +10117,15 @@
Message Editor Application for creating or editing a message
Message Server Symbian OS Server that handles request to modify the Message Store
Message Store Store of messages and related information kept in the file system on a Symbian OS device.
-Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
-Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
+Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
+Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
Global Inbox A standard folder under the local service which is used to store incoming messages like SMS MMS etc. as opposed to an IMAP4 Inbox which would be under an IMAP4 service and is a representation of the Inbox on an IMAP4 email server.
Central Repository centralised and secure storage facility for application settings
OBEX Object exchange protocol, used to send objects such as vCards or files between devices via infrared or Bluetooth.
GMXML XML parser / generator for use with SMIL formatted messages.
UID Unique Identifier, a 32 bit number allocated from a registry owned by Symbian
IPC Inter Process Communication
-MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
+MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
MTM Registry A list of currently installed MTMs maintained by the message server.
TLS Transport Layer Security, provides encryption of a TCP/IP socket.
M-HTML Standard for including HTML in MIME email messages see http://www.ietf.org/rfc/rfc2557.txt
@@ -15207,15 +11135,15 @@
Message Editor Application for creating or editing a message
Message Server Symbian OS Server that handles request to modify the Message Store
Message Store Store of messages and related information kept in the file system on a Symbian OS device.
-Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
-Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
+Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
+Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
Global Inbox A standard folder under the local service which is used to store incoming messages like SMS MMS etc. as opposed to an IMAP4 Inbox which would be under an IMAP4 service and is a representation of the Inbox on an IMAP4 email server.
Central Repository centralised and secure storage facility for application settings
OBEX Object exchange protocol, used to send objects such as vCards or files between devices via infrared or Bluetooth.
GMXML XML parser / generator for use with SMIL formatted messages.
UID Unique Identifier, a 32 bit number allocated from a registry owned by Symbian
IPC Inter Process Communication
-MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
+MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
MTM Registry A list of currently installed MTMs maintained by the message server.
TLS Transport Layer Security, provides encryption of a TCP/IP socket.
M-HTML Standard for including HTML in MIME email messages see http://www.ietf.org/rfc/rfc2557.txt
@@ -16225,1033 +12153,15 @@
Message Editor Application for creating or editing a message
Message Server Symbian OS Server that handles request to modify the Message Store
Message Store Store of messages and related information kept in the file system on a Symbian OS device.
-Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
-Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
+Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
+Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
Global Inbox A standard folder under the local service which is used to store incoming messages like SMS MMS etc. as opposed to an IMAP4 Inbox which would be under an IMAP4 service and is a representation of the Inbox on an IMAP4 email server.
Central Repository centralised and secure storage facility for application settings
OBEX Object exchange protocol, used to send objects such as vCards or files between devices via infrared or Bluetooth.
GMXML XML parser / generator for use with SMIL formatted messages.
UID Unique Identifier, a 32 bit number allocated from a registry owned by Symbian
IPC Inter Process Communication
-MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
-MTM Registry A list of currently installed MTMs maintained by the message server.
-TLS Transport Layer Security, provides encryption of a TCP/IP socket.
-M-HTML Standard for including HTML in MIME email messages see http://www.ietf.org/rfc/rfc2557.txt
-MIME Specification for the format of email message bodies see http://www.ietf.org/rfc/rfc1341.txt
-RFC2822 The standard format for internet mail messages see http://www.ietf.org/rfc/rfc0822.txt
-SMTP Simple Mail Transport Protocol
-SID Secure Identification
-IMAP4 Internet Mail Access Protocol
-POP3 Post Office Protocol Version 3
-NBS Narrow Band Socket, in the messaging context this refers to the socket that is used to talk to the SMS stack for receiving and sending SMS messages
-SMS Short Message Service
-MMS Multimedia Message Service
-WAP Wireless Application Protocol
-WSP WAP Session Protocol
-HTTP Hypertext transfer protocol
-PDU Protocol Data Unit. This is the encoded form of SMS and MMS messages.
-Versit A consortium that defined standard formats for things like contacts (vCard) and calendar entries (vCals)
-SDP Service Discovery Protocol. A Bluetooth protocol that allows an applications to discover which services are available and to determine the characteristics of the services.
-SMIL Synchronized Multimedia Integration Language. Presentation language that is commonly used to define the contents of an MMS message.
-XML Extensible Mark-up Language
-DOM Document Object Model
-DTD Document Type Definition, a schema that defines the structure of an XML document.
-ESTORE Symbian OS component that provides stream based storage. Messaging uses the Permanent file store provided by ESTORE to store its index entries.
-Appendix A - Example Sequence Diagrams
-A.1 Copy to a Remote Service
-
-Figure 33 Sequence Diagram Showing Copying to a Remote Service
-Figure 33 shows a client copying a message to a remote service using the Messaging Client API. The message server then delegates the copy to the SMTP Server MTM. The Server MTM interprets the request as a request to send the message so it opens a connection to a remote SMTP server and sends the message. While the message is being sent the client can retrieve progress information from the CMsvOperation object that was returned by CMsvEntry::CopyL. The dark grey IPC line represents the split between the objects running in the client’s process space on the left and the message server’s process on the right.
-There are four basic steps:
-1. The client opens session with Message Server and creates a CMsvEntry set on the global outbox,
-2. The client then requests an asynchronous copy from the outbox to the SMTP service, a CMsvOperation object is returned. The message server loads the SMTP Server MTM and delegates the copy operation to it.
-3. The client requests progress from the CMsvOperation object, this request is passed through to the SMTP Server MTM. The client may repeat this step multiple times.
-4. The Server MTM finishes sending message. It moves the message to sent folder and completes the message server’s request. The message server completes the CMsvOperation object, which requests the final progress from the message server. The server returns the final progress and deletes the Server MTM. The CMsvOperation then completes the client’s original request.
-This diagram hides all of the internal working of the SMTP Server MTM, for information on this see below.
-A.2 SMTP Session
-
-Figure 34 Sequence Diagram Showing a SMTP Session
-Figure 34 shows the operation of the SMTP Server MTM after a request has come from the message server to copy a message to the SMTP service.
-1. SMTP Server MTM gets the request from the message server, it will build a selection of messages consisting of the union of the selection of messages passed in and the messages in the outbox that are associated with this SMTP service and are ready to be sent. The chain of classes are constructed, and a request is passed to networking to connect to the remote SMTP server, details of the server name and port are retrieved from the settings stored in the SMTP service entry.
-2. The component waits for the SMTP server to respond with a greeting indicating it is willing to talk, then sends EHLO to the server and waits for the response detailing the capabilities of the Server. After this step there could set steps to start using TLS and or SMTP AUTH depending on the SMTP settings.
-3. CImSmtpSession calls back into CMsgOutboxSend to retrieve the next message to be sent, then constructs a CImSmtpFile object to handle sending, for details on the sending see SMTP Email Send. When sending the email has completed the CImSmtpFile object is deleted.
-4. CImSmtpSession calls back into CMsgOutboxSend to retrieve the next message which returns saying there are no more messages. CImSmtpSession sends QUIT to the SMTP server and completes CMsgOutboxSend. CMsgOutboxSend deletes CImSmtpSession which tears down the connection to the SMTP server; it then completes the SMTP Server MTM. The Server MTM will then complete the message server and be deleted.
-A.3 SMTP Email Send
-
-Figure 35 Sequence Diagram Showing SMTP Transactions during Email Send.
-Figure 35 shows a CImSmtpFile object sending an email message to an SMTP server.
-1. Construct a CImSendMessage object, part of the imut component. Reset the SMTP Server
-2. Read address information from the CImHeader object stored in the message store, send address information to SMTP server.
-3. Use CImSendMessage object to read the message from the message store and generate RFC2822 message line by line. Send each line to the server as it is generated.
-4. Complete and send the message by sending a full stop to the SMTP server
-
-
-
-
-Messaging Symbian OS v7.0s, v8.0, v8.1, v9.0, v9.1 Architectural Description
-
-Status: Issued
-Team/Department : Messaging / Content & Messaging
-
-Contents
-1 INTRODUCTION 6
-1.1 PURPOSE AND SCOPE 6
-2 SUBSYSTEM OVERVIEW AND BACKGROUND 6
-3 MESSAGING ARCHITECTURE AND APIS 7
-3.1 SUBSYSTEM COMPONENTS 7
-3.1.1 Framework components 7
-3.1.1.1 Message Server and MTM architecture 7
-3.1.1.2 Schedule Send 7
-3.1.1.3 SendAs Version 1 7
-3.1.1.4 SendAs Version 2 7
-3.1.1.5 Watcher Framework 8
-3.1.1.6 Message URL Handler 8
-3.1.1.7 Bio Message Framework 8
-3.1.2 Plug-ins 8
-3.1.2.1 SMS 8
-3.1.2.2 CDMA SMS 8
-3.1.2.3 Email 9
-3.1.2.4 OBEX 9
-3.1.2.5 MMS 9
-3.1.2.6 GMXML 10
-3.1.2.7 Bio Message Plug-ins 10
-3.1.2.8 PCMTM 10
-3.1.2.9 Fax 10
-3.2 GENERAL DESCRIPTION 11
-3.2.1 Messaging / Message Server and MTM Architecture APIs 11
-3.2.1.1 Key Internal Relationships and Dependencies 11
-3.2.1.2 Key External Relationships and Dependencies 12
-3.2.1.3 API Purpose - Further Elaboration 13
-3.2.1.3.1 Message Store 13
-3.2.1.3.2 Data File Storage (pre - v9.0) 15
-3.2.1.3.3 Platform Security Compliant Message Store 16
-3.2.1.3.4 How message centres display the message store 17
-3.2.1.3.5 Message Type Module Architecture 19
-3.2.1.3.6 Message Server Client API 21
-3.2.2 Messaging / Send As APIs 22
-3.2.2.1 Key Relationships and Dependencies 22
-3.2.2.2 API Purpose - Further Elaboration 22
-3.2.2.2.1 SendAs API (pre – v9.0) 22
-3.2.3 Platform Security Compliant SendAs Server (v9.0 onwards) 23
-3.2.4 Messaging / Schedule Send APIs 24
-3.2.4.1 Key Relationships and Dependencies 24
-3.2.4.2 API Purpose - Further Elaboration 24
-3.2.4.2.1 Schedule Send 24
-3.2.5 Messaging / Watchers APIs 25
-3.2.5.1 Key Relationships and Dependencies 25
-3.2.5.2 API Purpose - Further Elaboration 25
-3.2.6 Messaging / Message URL Handler APIs 26
-3.2.6.1 Key Relationships and Dependencies 26
-3.2.6.2 API Purpose - Further Elaboration 26
-3.2.6.2.1 Message URL Handler Application 26
-3.2.6.2.2 Message URL Recognisers 27
-3.2.7 Messaging / SMS APIs 27
-3.2.7.1 Key Internal Relationships and Dependencies 27
-3.2.7.2 Key External Relationships and Dependencies 28
-3.2.7.3 API Purpose - Further Elaboration 28
-3.2.7.3.1 SMS Watchers 28
-3.2.7.3.2 SMS Client MTM 29
-3.2.7.3.3 SMS Utilities 29
-3.2.7.3.4 SMS Server MTM 30
-3.2.8 Messaging / CDMA SMS APIs 31
-3.2.8.1 Key Internal Relationships and Dependencies 31
-3.2.8.2 Key External Relationships and Dependencies 32
-3.2.8.3 API Purpose - Further Elaboration 32
-3.2.8.3.1 CDMA SMS Watchers 32
-3.2.8.3.2 CDMA SMS Client MTM 33
-3.2.8.3.3 CDMA SMS Utilities 33
-3.2.8.3.4 CDMA SMS Server MTM 33
-3.2.8.3.5 Configuration for using CDMA SMS MTM 34
-3.2.9 Messaging / Email APIs 35
-3.2.9.1 Key Internal Relationships and Dependencies 35
-3.2.9.2 Key External Relationships and Dependencies 36
-3.2.9.3 API Purpose - Further Elaboration 36
-3.2.9.3.1 Email Overview 36
-3.2.9.3.2 Email Client Utilities 37
-3.2.9.3.3 Email Server MTM Utilities 37
-3.2.9.3.4 POP3 MTMs 37
-3.2.9.3.5 IMAP4 MTMs 38
-3.2.9.3.6 SMTP MTMs 40
-3.2.9.3.7 Autosend 40
-3.2.10 Messaging / MMS APIs 40
-3.2.10.1 Key Internal Relationships and Dependencies 41
-3.2.10.2 API Purpose - Further Elaboration 41
-3.2.10.2.1 MMS Overview 41
-3.2.10.2.2 MMS Utilities 42
-3.2.10.2.3 MMS Watcher 43
-3.2.10.2.4 MMS Client MTM 43
-3.2.10.2.5 MMS Server MTM 44
-3.2.10.2.6 MMS Codec 45
-3.2.11 Messaging / BIO APIs 46
-3.2.11.1 Key Internal Relationships and Dependencies 46
-3.2.11.2 API Purpose - Further Elaboration 47
-3.2.11.2.1 BIO Overview 47
-3.2.11.2.2 BIO MTM 47
-3.2.11.2.3 BIO Database 48
-3.2.11.2.4 BIO Parsers 48
-3.2.11.2.5 BIF Files and Utilities 48
-3.2.11.2.6 Platform Security Compliant Messaging / BIO APIs 49
-3.2.12 Messaging / OBEX MTM APIs 50
-3.2.12.1 Key Internal Relationships and Dependencies 50
-3.2.12.2 OBEX MTM Overview 50
-3.2.12.2.1 OBEX MTM 50
-3.2.12.2.2 IR MTM 51
-3.2.12.2.3 Bluetooth MTM 51
-3.2.12.2.4 OBEX MTM Utils 52
-3.2.12.2.5 Platform Security Compliant Messaging / OBEX MTM APIs 52
-3.2.13 Messaging / GMXML APIs 52
-3.2.13.1 Key Relationships and Dependencies 52
-3.2.13.2 Overview 53
-3.2.13.2.1 GMXML DOM 53
-3.2.13.2.2 GMXML Parser and Composer 53
-3.2.13.2.3 GMXML SMIL DTD (Validator) 53
-4 SECURITY 54
-4.1 DATA CAGING 54
-4.2 BACKUP AND RESTORE 54
-4.3 CAPABILITY RANGES 54
-4.3.1 Capabilities granted to executables 54
-4.3.2 Capabilities granted to DLLs 55
-4.3.3 Capabilities required to use the subsystem 57
-5 FURTHER INFORMATION 59
-5.1 REFERENCES 59
-5.2 OPEN ISSUES 59
-5.3 GLOSSARY 60
-APPENDIX A - EXAMPLE SEQUENCE DIAGRAMS 62
-A.1 COPY TO A REMOTE SERVICE 62
-A.2 SMTP SESSION 64
-A.3 SMTP EMAIL SEND 66
-
-Table of Figures
-Figure 1 Where Messaging Lives 6
-Figure 2 MTM Relationships 11
-Figure 3 External Dependencies 12
-Figure 4 Message Store 13
-Figure 5 Series 60 Inbox List View 14
-Figure 6 Remote and Local Entries 14
-Figure 7 Email Message 15
-Figure 8 Series 60 Message Centre (Composed from 2 screen shots) 17
-Figure 9 UIQ Message Centre 18
-Figure 10 Messaging MTM Structure (light coloured components are part of messaging subsystem) 19
-Figure 11 Nokia 9210 Outbox List View 20
-Figure 12 SendAs Version 1 Dependencies 22
-Figure 13 SendAs Version 2 Dependencies 23
-Figure 14 Schedule Send Dependencies 24
-Figure 15 Watcher Dependencies 25
-Figure 16 Message URL Handler Dependencies 26
-Figure 17 SMS Internal Dependencies 27
-Figure 18 SMS External Dependencies 28
-Figure 19 CMDA SMS Internal Dependencies 31
-Figure 20 CDMA SMS External Dependencies 32
-Figure 19 Email Internal Dependencies 35
-Figure 20 Email External Dependencies 36
-Figure 21 MMS Internal Dependencies 41
-Figure 22 MMS Utilities External Dependencies 42
-Figure 23 MMS Watcher External Dependencies 43
-Figure 24 MMS Client MTM Dependencies 43
-Figure 25 MMS Server MTM Dependencies 44
-Figure 26 BIO Message Internal Dependencies 46
-Figure 27 Bio Parser External Dependencies 47
-Figure 26 BIO Message Dependencies (v9.0) 49
-Figure 28 OBEX Internal Dependencies 50
-Figure 29 OBEX External Dependencies 51
-Figure 30 IR MTM Dependencies 51
-Figure 31 Bluetooth MTM Dependencies 52
-Figure 32 GMXML Dependencies 52
-Figure 33 Sequence Diagram Showing Copying to a Remote Service 62
-Figure 34 Sequence Diagram Showing a SMTP Session 64
-Figure 35 Sequence Diagram Showing SMTP Transactions during Email Send. 66
-1 Introduction
-1.1 Purpose and Scope
-The Messaging Architectural Description details the architecture and APIs exposed by the Messaging Subsystem. This document does not attempt to list all functionality provided by the messaging subsystem. For details on the functionality provided and the specifications implemented by the messaging subsystem see the Messaging Functional Description [R1]. This document describes the general architecture of messaging subsystem. Information related to a particular release version is mentioned with relevant release number.
-2 Subsystem Overview and Background
-The Messaging Subsystem provides an application level API to handle the storage and transport of different message types. It sits between messaging applications and the lower level subsystems which messaging uses for storage and transmission of messages.
-
-Figure 1 Where Messaging Lives
-The message types that messaging currently supports are Email (POP3, IMAP4 & SMTP), SMS, MMS and OBEX. The set of supported message types is extensible at run time by the use of plug-in modules that are responsible for the transmission and storage of a particular message type. This means that the set of components shown communicating with the network cloud depend on the message types installed.
-3 Messaging Architecture and APIs
-3.1 Subsystem components
-The Messaging subsystem components can be split into two categories: those components that form the framework and those that plug into the framework to support specific message types. This section briefly describes each of the components, more detailed descriptions of the components and their dependencies can be found in later sections of this document.
-3.1.1 Framework components
-3.1.1.1 Message Server and MTM architecture
-The message server is the core component in the messaging subsystem. It provides the message store used to contain messages. The Message Type Module architecture also allows plug-ins to add support for new message types to the messaging subsystem.
-Component Description
-messaging\framework\serverexe Executable that links to the server component and starts the message server
-messaging\framework\server Contains classes that make up both the client and server side of the message server API.
-messaging\framework\mtmbase Base classes for the plug-ins that handle the various message types
-3.1.1.2 Schedule Send
-The Schedule Send component is an extension to the framework that provides support for scheduling of operations such as sending messages. Message type modules that wish to support this functionality can use these support components to implement scheduling. For example the SMS MTM uses this to allow scheduled sending of SMS messages.
-Component Description
-messaging\schedulesend\schedulesendmtm Base classes that handle functionality for message server plug-ins that wish to enable scheduling of sending messages.
-messaging\schedulesend\schedulesendexe Executable use to provide schedule send behaviour.
-3.1.1.3 SendAs Version 1
-This version of SendAs is supported in releases pre - v9.0. SendAs provides a high level API for applications that wish to include a “Send As” menu to allow users to send content via one of the message types supported by messaging. The application using the API does not have to be aware of the message type selected by the user. Note the API does not send the messages.
-Component Description
-messaging\sendas High level API to allow creation of messages.
-3.1.1.4 SendAs Version 2
-From v9.0 and onwards the SendAs has been replaced with client server architecture based SendAs server. The client server architecture enhances secured platform implementation. The SendAs server polices the client application. If it is not trusted with required capabilities the SendAs server will refuse the client access. The client MTM for the message type can send a message with user permission even if the client does not have the correct capabilities.
-Component Description
-messaging\sendAsV2 High level API to allow the creation and sending of messages
-
-3.1.1.5 Watcher Framework
-The watcher framework is a lightweight framework to allow plug-ins to wait on events. For example there is an SMS watcher that waits for incoming SMS messages and delivers them to the message store. The watcher framework will only load plug-ins from ROM.
-Component Description
-messaging\framework\watcher Executable that loads and runs watcher plug-ins.
-3.1.1.6 Message URL Handler
-Support for recognising messaging URLs (mailto:, sms:, fax:, mms:), and then launching an editor with a new message.
-Component Description
-messaging\urlhandler\urlhandler An application that parses the URLs and then creates a correctly addressed message and launches a message editor.
-messaging\urlhandler\recogniser Recognisers that map from the URL schemes to the mime types.
-3.1.1.7 Bio Message Framework
-The Bio Message Framework provides a framework that supports plug-ins to handle messages like vCards and Internet access point set-up messages.
-Component Description
-messaging\biomsg\BDB\BIODB Classes to maintain the database of bio registration files.
-messaging\biomsg\BIFU\BIFU Classes for reading and writing bio registration files
-messaging\biomsg\BIOC\BIOC Bio message client MTM, this is in the framework section as it forms part of the bio messaging framework it is also a plug-in to the messaging framework.
-messaging\biomsg\BIOS\BIOS Bio message server MTM, this is in the framework section as it forms part of the bio messaging framework it is also a plug-in to the messaging framework.
-3.1.2 Plug-ins
-3.1.2.1 SMS
-The SMS plug-ins provide application level support for the Short Message Service messages.
-Component Description
-messaging\biomsg\BioWatchers Plug-ins to the watcher framework to listen for SMS, WSP, and WDP messages and deliver them to the global inbox in the message store.
-messaging\sms\clientmtm A plug-in to the message server framework to provide a generic API for creation of SMS messages (SMS Client MTM & SMS utilities)
-messaging\sms\servermtm A plug-in to the message server framework to provide a generic API for sending of SMS messages (SMS Server MTM)
-3.1.2.2 CDMA SMS
-The CDMA SMS plug-ins provide application level support for the CDMA Short Message Service messages.
-Component Description
-messaging\biomsg\BioWatchersCdma Plug-ins to the watcher framework to listen for CDMA SMS messages and deliver them to the global inbox in the message store.
-messaging\sms\multimode\clientmtm A plug-in to the message server framework to provide a generic API for creation of CDMA SMS messages (CDMA SMS Client MTM)
-messaging\sms\multimode\servermtm A plug-in to the message server framework to provide a generic API for sending of CDMA SMS messages (CDMA SMS Server MTM)
-
-3.1.2.3 Email
-The email plug-ins provide support the POP3, IMAP4 and SMTP email protocols and support for parsing and generating plain test, MIME and M-HTML format email messages.
-Component Description
-messaging\email\clientmtms A plug-in to the message server framework to provide a generic API for creation of email messages (IMAP4 SMTP and POP3 Client MTMs & email utilities)
-messaging\email\imapservermtm A plug-in to the message server framework to provide a generic API for access to a remote IMAP4 server (IMAP4 Server MTM)
-messaging\email\smtpservermtm A plug-in to the message server framework to provide a generic API for access to a remote SMTP server (SMTP Server MTM)
-messaging\email\popservermtm A plug-in to the message server framework to provide generic API for access to remote POP3 server (POP3 Server MTM)
-messaging\email\servermtmutils Email utilities for parsing plain text and MIME email messages. It also provides an abstraction of the TCP/IP sockets for use by the SMTP POP3 and IMAP4 plug-ins.
-messaging\email\autosend An executable that requests SMTP Server MTM to send messages in the outbox. This is used to provide send on next connection functionality and is started by the POP3 and IMAP4 Client MTMs.
-3.1.2.4 OBEX
-The OBEX MTM is a set of plug-ins to the message server that provides support for IR and Bluetooth beaming.
-Component Description
-messaging\obex\btmtm\btclient\group\btcmtm Bluetooth Client MTM
-messaging\obex\btmtm\btserver\group\btsmtm Bluetooth Server MTM
-messaging\obex\irmtm\irclient\group\ircmtm IR Client MTM
-messaging\obex\irmtm\irserver\group\IRSMTM IR Server MTM
-messaging\obex\obexmtm\obexclient\group\obexClientMtm OBEX Client MTM, base classes for the Bluetooth and IR Client MTMs
-messaging\obex\obexmtm\obexserver\group\obexServerMtm OBEX Server MTM, base classes for the Bluetooth and IR Server MTMs
-messaging\obex\obexmtm\obexutil\group\obexMtmUtil OBEX MTM utilities
-3.1.2.5 MMS
-The MMS MTM is a plug-in to the message server that provides support for MMS messages. From v9.0 and onwards MMS MTM and related components are removed.
-Component Description
-messaging\mms\utils MMS Utilities
-messaging\mms\servermtm MMS Server MTM
-messaging\mms\mmswatcherplugins MMS plug-ins to WAP push framework to handle reception of MMS notifications
-messaging\mms\codec MMS utilities for handling MMS codecs
-messaging\mms\clientmtm MMS Client MTM
-3.1.2.6 GMXML
-GMXML is a parser/generator for SMIL presentations for MMS messages.
-Component Description
-messaging\GMXML\XMLParser XML parser designed for parsing of SMIL messages
-messaging\GMXML\XMLDom XML document object model designed for parsing of SMIL messages
-messaging\GMXML\SMILdtd SMIL DTD
-3.1.2.7 Bio Message Plug-ins
-These parsers plug into the bio messaging framework to handle specific types of bio message.
-Component Description
-messaging\biomsg\cbcp\CBCP Compact business card parser
-messaging\biomsg\enp\ENP Email notification parser
-messaging\biomsg\gfp\gfp General file parser
-messaging\biomsg\iacp\IACP Nokia Smart Message Internet Access Parser
-messaging\biomsg\wapp\wapp Nokia/Ericsson OTA Parser
-3.1.2.8 PCMTM
-Plug-in to the message server that provided email synchronisation with a PC. This component has been deprecated in 8.0a and will not been documented in the API section below.
-3.1.2.9 Fax
-Plug-in to the message server that provides fax support. This component has been deprecated in 8.0a and will not been documented in the API section below.
-
-3.2 General Description
-3.2.1 Messaging / Message Server and MTM Architecture APIs
-3.2.1.1 Key Internal Relationships and Dependencies
-
-Figure 2 MTM Relationships
-Figure 2 shows the relationship between the Message Server and the MTM plug-ins. The grey classes are realisations of the MTM interfaces defined by the messaging framework. The message server depends on the Server MTM interface. Messaging Clients depend on the Client, UI and UI Data MTM interfaces and the Message Server Client API.
-3.2.1.2 Key External Relationships and Dependencies
-
-Figure 3 External Dependencies
-The grey package representing the messaging client depends on the Client, UI and UI Data interfaces and the Messaging Client API. The message server then depends on:
-• Charconv – Provides character set conversion routines, used to convert encoded message body text to Unicode body text.
-• EStore – Provides API to handle a stream based store used for the messaging index file and the framework classes for the message store files. (omitted from other dependency diagrams as it is implied by the dependency on the message server)
-• F32 – Provides the file server APIs used to access the file system directories in which messaging stores files containing message data. (omitted from other dependency diagrams)
-• BAFL – Provides API to load the correct messaging resource file dependent on the current language and to register the message store index file with the backup server. (omitted from other dependency diagrams)
-• ETEXT – Rich text APIs used to store body text of messages, this rich text format is a Symbian Proprietary format. (omitted from other dependency diagrams)
-• EUSER – Core Symbian OS utilities such as descriptors, arrays, client / server framework, cleanup stack and others (omitted from this and other dependency diagrams).
-• Central Repository – Centralised and secure storage facility for application settings, the message server stores message settings data in the central repository (from v9.0 and onwards).
-Note that debug only dependencies such as the flogger have been omitted from dependency diagrams.
-3.2.1.3 API Purpose - Further Elaboration
-3.2.1.3.1 Message Store
-The message server provides persistent storage of messages and messaging account settings. It does this by providing a message store consisting of a tree of message entries. Multiple clients can access the message store simultaneously. Each entry in the tree can represent an email account, folder of messages, message part, etc.
-
-Figure 4 Message Store
-Figure 4 shows an example message store. The tree is broken down in to three levels:
-1. The Root entry. This entry is just present to tie the tree structure together
-2. Service entries. There is one local service under which local folders and messages are stored, and zero or more remote services. Remote services represent message accounts.
-3. Message & Folder entries. Messages and folders, under the local service represent messages stored on the device. Messages and folders under remote services represent a local copy of messages that are present on a remote server. For example under a POP3 email service you would have copies of all the messages present on the POP3 email server, or under an SMS service you might find SMS messages that are stored on a SIM.
-The message server controls access to the entries in the store. It enforces the three levels therefore attempts to create message or folder entries directly under the root entry will fail.
-The message server provides three types of storage for each entry in the message store:
-• Index entry - TMsvEntry - intended to provide enough information for UI to display list views as shown in Figure 5. This consists of two strings and various flags (read, complete, has attachments etc).
-• Stream based file store - CMsvStore – provides storage of streams of data associated with UIDs. A standard UID is defined for storing body text. Other UIDs are specific. For example the email MTMs define a UID for storage of MIME headers. Compared to the index entry information this is used to store larger objects and is extensible, at the cost of being slower to access. From v9.0 and onwards CMsvStore provides an Attachment API for managing attachments. The Attachment API should be used as attachments can no longer be accessed directly due to Platform Security.
-• Directory of files – normally used for attachments.
-The only storage type that is always present is the index entry. The stream store and the directory of files are optional.
-
-Figure 5 Series 60 Inbox List View
-
-Figure 6 Remote and Local Entries
-As shown in Figure 6 the message store is split into two sets of entries:
-• Remote entries - entries that are representations of entries stored on a remote store .
-• Local entries - entries not linked to a remote store.
-The message server handles changes to local entries; internally it hands off changes to remote entries to the Server MTM that owns that service. Examples of operations that are handed off to Server MTMs are operations involving copying and moving messages to and from a remote service. See section 3.2.1.3.5 or more information on Server MTMs.
-Each entry within the store has a type:
-Folder – Messages can be grouped into folders. Standard folders such as inbox / outbox and user created folders.
-Message – Storage of the content of a message. Message entries can have child entries used to represent the structure of a message.
-Attachment – These represent attachments under a message entry.
-Root & Local Service Entry – There tie the tree structure together. However the Stream store associated with the root entry is sometimes used by UIs to store preferences e.g. default folder views etc.
-Remote Service - Represents a source and / or destination for messages. They are used to store the settings associated with the source / destination.
-Message Type Specific - MTMs can create other message types for use as child entries to messages they own. For example email uses a tree structure, with a message entry as the root, to represent the MIME structure of an email message; it uses folder entries to represent MIME folders and adds new types for entries representing the html body and text body parts of a message. This is shown in Figure 7.
-
-Figure 7 Email Message
-Using the message store to represent message structure allows reuse of the tree structure and makes it very simple to represent one message embedded in another. However this representation introduces performance issues as it results in each message having multiple files associated with it. The message server also keeps all index entries in memory; therefore this representation increases the memory footprint of the message server. Therefore when designing new MTMs we should think about moving away using multiple index entries to store one message in the message store.
-A default message store is created if the message server starts and no message store is present or a corrupt message store is present. The server will initially create a store with just a root entry, and then the server will create any standard folders defined in the resource file msgs.rsc. Finally the server will check whether an executable ‘mailinit.exe’ is present on the system, if it is present the server will launch the executable to allow customisation of the message store. The behaviour of ‘mailinit.exe’ is defined by the UI family of the device. However the typical behaviour is to load each of the UI Message Type Modules and allow each to perform any message type specific initialisation. For example the SMS plug-in typically creates a default service entry.
-
-3.2.1.3.2 Data File Storage (pre - v9.0)
-This section describes the files used by the message server before release v9.0. For information on the files used for release from v9.0 and onwards see section [3.2.1.3.3.1].
-Filename Access Purpose
-?:\system\Mail\index Private Message server index file, internal to message server
-?:\system\Mail\<8 hex digits> Shared via API Message server store files for services, clients access these via a messaging API.
-?:\system\Mail\<8 hex digits>.new Shared via API Temporary file used during committing message server store files.
-?:\SYSTEM\MAIL\<8 HEX DIGITS>_F\* Shared Files associated with a messaging service. These may be accessed directly by clients.
-?:\system\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits> Shared via API Message server store files for message entries, clients access these via a messaging API.
-?:\system\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits>.new Shared via API Temporary file used whilst committing message server store files.
-?:\system\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits>_F\* Shared Files associated with a message entry. These are accessed directly by clients.
-c:\system\data\msgs.ini Private Stores the drive containing the last used message store
-c:\system\Mtm\Mtm Registry v2 Private Cache of registered MTMs, internal to message server
-C:\system\data\sms_settings.dat Shared Copy of the SMS settings.
-?:\System\Mail\StoreInit.tmp Shared Created when message server runs ‘mailinit.exe’, ‘mailinit.exe’ should delete the file when it has successfully completed.
-?:\System\Mail\storedeleted.tmp Shared Created when message server finds and deletes a corrupt message store. Allows the UI to inform the user about the fact that the message store was corrupt.
-Files that are shown as private should only be accessed by the message server or by connectivity process for backup and restore purposes. Files listed as shared are accessed directly by messaging clients. Files listed as shared via API are accessed by client process but only via messaging APIs.
-3.2.1.3.3 Platform Security Compliant Message Store
-From v9.0 and onwards the message store is stored in the message server's data cage and the settings data are placed in the Central Repository. Access to the message store is only possible via message server APIs and not directly through file access. This leads to secured data storage and secured platform.
-3.2.1.3.3.1 Data caging
-Filename Purpose
-?:\private\<SID>\Mail\index Message server index file, internal to message server
-?:\ private\<SID>\Mail\<8 hex digits> Message server store files for services, clients access these via a messaging API.
-?:\ private\<SID>\Mail\<8 hex digits>.new Temporary file used during committing message server store files.
-?:\ private\<SID>\Mail\<8 hex digits>_F\* Files associated with a messaging service. These may be accessed directly by clients.
-?:\ private\<SID>\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits> Message server store files for message entries, clients access these via a messaging API.
-?:\ private\<SID>\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits>.new Temporary file used whilst committing message server store files.
-?:\ private\<SID>\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits>_F\* Files associated with a message entry. These are accessed directly by clients.
-c:\ private\<SID>\data\msgs.ini Stores the drive containing the last used message store
-c:\ private\<SID>\Mtm\Mtm Registry v2 Cache of registered MTMs, internal to message server
-?:\ private\<SID>\Mail\StoreInit.tmp Access via IPC call
-?:\ private\<SID>\Mail\storedeleted.tmp Created when message server finds and deletes a corrupt message store. Allows the UI to inform the user about the fact that the message store was corrupt.
-?\resource\messaging\bif\*.bif Registration data field with UID used in BIO framework
-
-3.2.1.3.4 How message centres display the message store
-The UI normally provides a Message Centre application to display the structure of the message store to the user. Different UIs map the structure to different views.
-
-Figure 8 Series 60 Message Centre (Composed from 2 screen shots)
-Figure 8 shows the top level view of the message centre application on a Series 60 phone. This shows that the message centre has hidden the local service and shows the standard folders at the same level as the services. Also the SMTP, SMS and MMS services are marked as hidden entries in the message store, and so do not appear in the message application.
-
-Figure 9 UIQ Message Centre
-However Figure 9 shows that the UIQ message centre has no 1-1 mapping from the structure in the message store to the structure shown to the user. Each of the message types is displayed as if its messages were contained in separate folders. Under each of these folders the user is presented with an inbox, outbox, send and drafts folder. This filtering is done in the UI layer as this functionality is not provided by the messaging API.
-3.2.1.3.5 Message Type Module Architecture
-
-Figure 10 Messaging MTM Structure (light coloured components are part of messaging subsystem)
-The MTM architecture is the plug-in scheme provided by the messaging framework to integrate different message transports into the message server. The plug-in scheme consists of four interfaces, the UI MTM, UI Data MTM, Client MTM and Server MTM. The messaging client applications loads and uses the first three which are loaded within the client’s process space. The final one the Server MTM is loaded within the message server process. The APIs for the client facing interfaces are extensible via run time type information provided by the QueryCapability API, and the InvokeAsyncFunction and InvokeSyncFunction APIs.
-3.2.1.3.5.1 UI MTM
-Handles requests from clients to view and edit messages or service settings. The MTM handles interaction with the message centre and as such the exact meaning of the APIs is defined by the UI. However common meanings are:
-• Create – Launches the editor with a new message.
-• Edit – If entry is a message this launches the editor; if entry is a service it edits the settings.
-• View – Launches the message viewer.
-• Display progress of an operation.
-3.2.1.3.5.2 UI data MTM
-This MTM provides fast access to UI components such as menu resources and bitmaps required by message centre for list views etc. Again the exact semantics are UI specific.
-There is a resource file defining UI specific functions, for example the Series 60 Messaging UI checks if the resource file contains text to display in the “New Message” menu.
-The UI data MTM also provides mapping from the message store’s TMsvEntry structure to Icons for the messaging list views and a status string, for example in the case of Nokia 9210 it is used in the outbox view to provide strings like “Resend 01:07” as shown in Figure 11. The class also provides functions to determine what operations are possible with a given entry. Examples of this are APIs that return whether the UI should allow the user to reply to the entry or to delete a service entry. The UI then uses this information to determine which menu options / short-cut keys should be allowed when the user selects a given entry.
-
-Figure 11 Nokia 9210 Outbox List View
-3.2.1.3.5.3 Client MTM
-Provides methods to create / reply and forward messages. Functions the Client MTMs provide are:
-• Create Message.
-• Reply to a Message.
-• Forward a Message.
-• Add / remove Addressees.
-• Add / remove body text.
-• Add / remove subject.
-• Add / remove attachments (the API cannot list attachments).
-The Client MTM interface is used by SendAs to provide a way of creating messages independently of the message type.
-3.2.1.3.5.4 Server MTM
-This is the final interface that makes up an MTM plug-in; it differs from the other three plug-ins in that it is loaded into the message server’s process space. The Server MTM provides access to messages under remote services. It handles connecting to remote servers to handle updating the local cache of these messages or to send messages copied to remote services when messages are copied to a remote service. The message server loads and hands off all message store operations that involve entries under a remote entry, these are the entries on the left-hand side of Figure 6.
-Functions that a Server MTM must implement:
-• Copy/MoveToLocal – called when the message server is asked to move or copy an entry that is currently under a remote service. A Server MTM might map this to retrieving a message from a remote mailbox.
-• Copy/MoveFromLocal – called when the message server is asked to move or copy from under the local service to a destination under a remote service. A Server MTM should map this to sending a message if the MTM supports sending.
-• Create, Delete, Change – called when the message server is asked to perform these operations on entries under a remote service.
-• StartCommand – this API provides a means of extending the API the Server MTM provides. Messaging clients pass a command ID and a selection of entries via the message server to the Server MTM. Examples of commands that Server MTMs might provide are: connect and synchronise the entries under a remote service with the messages on an email server, list SMS messages present on the phones SIM. These commands are MTM specific and therefore clients have to know which MTMs support which commands.
-3.2.1.3.5.5 MTM Registration
-MTMs must be registered with the message server so that clients can query what MTMs are present and the server knows which DLL to load to create a given MTM component. MTMs are registered by providing a resource file containing the MTMs UIDs, human readable name, and for each MTM interface it lists a DLL and the ordinal at which the constructor for that interface exists. The message server will search the ROM drive for MTM registration resource files on start-up and it will automatically register any MTMs found. For registration of MTMs installed on other drives, the message server provides an API to register and de-register an MTM. Registration will persist across a reboot, so an MTM only needs to be registered when it is installed on the system.
-When MTMs are registered or unregistered the message server will send events to all messaging clients with a message server session open.
-3.2.1.3.6 Message Server Client API
-The Messaging Server Client API breaks down into two categories: APIs for manipulation of the message store and utility APIs.
-3.2.1.3.6.1 Message Store manipulation APIs
-Requests from clients to modify the message store fall into three categories:
-1. Operations performed entirely with local entries (entries on the right-hand side of Figure 6) for example requests to create entries in the inbox, delete an entry from the drafts folder etc. The message server handles these operations directly.
-2. Operations that involve a remote entry (entries on the left-hand side of Figure 6) for example requests to delete an entry under a POP3 service, or copy a message to an SMTP service. The message server hands these operations off to the Server MTM that owns the service under which the remote entry is stored. The only exception to this rule is the ChangeAttributes API call. This modifies flags on an index entry and is handled by the message server for both local and remote entries. This means that a Server MTM can not rely on being called when flags like the Unread flag are changed. Note that operations can not involve two remote entries; therefore requests to copy entries between a remote service representing one POP3 account to a remote service representing another POP3 account will fail with an error.
-3. Requests that are explicitly directed at a Server MTM via the TransferCommand API. These commands are just passed to the correct Server MTM by looking up the Service ID and MTM of the first message in the selection passed into the command.
-The message server sends events when entries in the message store are modified to messaging clients that have a session open with the server.
-Where the API provides asynchronous functions to modify the message store or transfer a command to a Server MTM, the functions will return a message server operation object. This object can be used to request progress on operation or cancel the operation. Deleting the operation object returned, or closing the session used to make the request will result in the operation being cancelled, therefore a messaging client must remain running until operations it has requested have either completed or they will be cancelled. See appendix A.1 for an example of an asynchronous copy operation. If a Server MTM operating on the same remote service is already handling an operation, the message server will queue the new operation to be handled when the Server MTM becomes free. Requests for progress of operations that are queued will fail with KErrNotReady. The fact that the queue is based on the remote service ID means that you can have two Server MTMs of the same type running at the same time as long as they are operating on different services. So for example you can have two separate POP3 MTMs running synchronising different remote services with email servers.
-3.2.1.3.6.2 Utility APIs
-1. Access to MTM registries – These allow clients to construct instances of the interfaces an MTM implements.
-2. Register / Unregister an MTM.
-3. Change Drive – The message server closes the current message store and opens one on the drive specified. If no message store is present on the drive specified a new message store is created. The message sever can have only one mail store open at a time, if the current mail store is not available because a the disk the mail store is on is not present then the message server will switch the mail store back to the C: drive if an attempt is made to create a message in the inbox.
-4. Launching Editors – This launches the correct editor for a message. It is implemented by delegating the request to the UI MTM
-3.2.2 Messaging / Send As APIs
-3.2.2.1 Key Relationships and Dependencies
-
-Figure 12 SendAs Version 1 Dependencies
-SendAs version 1 and only present in releases before v9.0. SendAs uses the Messaging Client API to access the registry of Client MTMs and construct the Client MTM interfaces. The Client MTMs are then used for composing the message. SendAs requires clients to implement the MSendAsObserver interface. This interface is responsible for checking the return value of the capability queries made to Client MTMs that require a response and also for rendering message types that require it. The only message type supplied by Symbian that requires rendering is Fax, however this MTM has been removed in 8.0a and future releases.
-3.2.2.2 API Purpose - Further Elaboration
-3.2.2.2.1 SendAs API (pre – v9.0)
-The SendAs API makes use of the Client MTM interface and the Messaging Client API to provide a generic API for creating messages. Note despite the name of this component SendAs does not provide an API to send the message.
-SendAs builds a list of registered MTMs, then queries each MTM to check whether it supports sending, removing those MTMs from the list that do not support sending. This list is then provided to the messaging client application. At this point the application can add more constraints on the list of MTMs; for example it can insist the MTM supports Attachments or more than a certain size of body text. SendAs queries each of the MTMs about the requirements and will drop any MTMs from the list that does not meet them. When the application has finished adding requirements it selects one of the MTMs left in the list and uses that to compose the message, adding addresses, a subject, body text and attachments.
-SendAs supports setting a BIO Type for the message that is composed. This tells the transport that the body text represents a BIO Message. This is used when sending business cards from the contacts application as SMS messages; the contacts application puts the vCard data in the body text of the message and the transport sends it correctly. If the MTM in question supports attachments then the vCard is attached to the message.
-A new CSendAs object must be created for each message the application wishes to create.
-3.2.3 Platform Security Compliant SendAs Server (v9.0 onwards)
-
-Figure 13 SendAs Version 2 Dependencies
-From v9.0 and onwards the CSendAs has been replaced by the SendAs server component. The new SendAs server controls the access to the message store. Some of the key SendAs Server features are listed as follows.
-• Send a message once the capability policing of the client application has been completed.
-• Allow client applications to launch an editor for a specified message type.
-• Allow client applications to query the message type.
-The main client-side API is the RSendAs class. The client applications use this to connect to the Send-As server. The session object on the server-side is an instance of CSendAsSession.
-Client applications create messages using the RSendAsMessage API. Opening an RSendAsMessage object on Send-As server session creates a CSendAsMessage object in the Send-As server. There is a one-to-one mapping between an RSendAsMessage object and a CSendAsMessage object. This allows client applications to create multiple messages concurrently.
-
-3.2.4 Messaging / Schedule Send APIs
-3.2.4.1 Key Relationships and Dependencies
-
-Figure 14 Schedule Send Dependencies
-The Schedule Send Server MTM base class depends on the task scheduler to launch the schedule send executable at the correct time. To send the message with a package of data previously passed into the task scheduler by the Server MTM. The schedule send executable then uses the Messaging Client API to actually perform the requested operation.
-3.2.4.2 API Purpose - Further Elaboration
-3.2.4.2.1 Schedule Send
-The Schedule Send functionality is delivered by four components:
-Server MTM Base Class – The base class provides support to Server MTMs that wish to support scheduled operations.
-Data Structures – These are classes used to represent the data associated with a scheduled operation.
-Executable – The executable is run by the task scheduler at the scheduled time.
-The Task Scheduler – This component is part of the system libraries subsystem. Currently the SMS and Fax Server MTMs support scheduled sending.
-Clients request the Server MTM schedules operations via additional commands passed to TransferCommand API; this is passed to the Server MTM via the message server. The Server MTM packages the operation ID, a selection of message IDs, how often to poll for progress and an MTM specific buffer. It then passes this package of data to the task scheduler requesting that it launches the schedule send executable at the correct time with the packaged information.
-When the task scheduler launches the schedule send executable, it unpacks the schedule information and uses the Messaging Client API to request the Server MTM to perform the operation.
-Schedule Send supports a retry mechanism if the operation fails. The Server MTM has a resource file containing a mapping from the error codes the operation can fail with and actions to be performed. For example the SMS resource file has a mapping such that if the operation fails with an error code indicating a bad phone number the SMS will be set to failed and left in the outbox. Whereas if it fails with a error code indicating temporary network failure the send operation will be scheduled to be resent later with a maximum of three retries.
-3.2.5 Messaging / Watchers APIs
-3.2.5.1 Key Relationships and Dependencies
-
-Figure 15 Watcher Dependencies
-The watcher executable’s dependency on the message server is the result of a performance measure. The watcher process creates a message server session before initialising each of the watcher plug-ins and closes the session when it has finished. This keeps the message server running during initialisation avoiding starting and stopping the message server if each watcher plug-in opens and closes sessions.
-3.2.5.2 API Purpose - Further Elaboration
-The watcher framework consists of an executable that is launched when the device boots. The component that is responsible for launching it depends on the UI family. When the watcher.exe is launched it will load each DLL in z:\system\libs\watchers which has a second UID as KWatcherUid and calls the first DLL entry point to construct a CActive object.
-From v9.0 and onwards watcher DLLs are found by scanning the directory \resource\messaging\watchers for registry files. These files contain the name of a watcher DLL that can be loaded from ROM i.e. z:\sys\bin.
-The framework has retry behaviour if the first entry point leaves, in this case the watcher framework will start a timer and try and construct the watcher object 10 seconds later. Five attempts are made before the watcher plug-in is assumed to have failed completely. Once the watcher framework has constructed all the watchers it starts the active scheduler which should never exit.
-Watcher plug-ins typically make a request to another subsystem such that they will be completed when an external event like a fax line ringing or an SMS being received occurs. When the watcher has completed processing the request it will wait for the next event.
-No support for starting / stopping watchers is provided. This is a limitation that makes watchers unsuitable for operations like listening for messages beamed via IR, as the watcher should only run while the IR port is active.
-3.2.6 Messaging / Message URL Handler APIs
-3.2.6.1 Key Relationships and Dependencies
-
-Figure 16 Message URL Handler Dependencies
-3.2.6.2 API Purpose - Further Elaboration
-The Message URL Handler provides support for creating messages and launching messaging editors from URLs such as mailto:infobot@example.com?subject=current-issue. Note there is no dependency between the Message URL Handler application which processes the URLs and the Message URL Handler recognisers which maps from URLs to mime types.
-3.2.6.2.1 Message URL Handler Application
-This is a Symbian OS application that registers with the application framework that it can handle the mime types: x-epoc-url/fax, x-epoc-url/mailto and x-epoc-url/sms. When launched with a URL it will parse the URL to retrieve the address and other header fields and then use the SendAs API to create a new message with the correct address, headers etc. The application then uses the APIs in the MturUtils class provide by the mtmbase component in the messaging framework to launch the correct editor for the given message type. The application is marked as hidden and therefore should not be listed by UIs in application browsers.
-3.2.6.2.2 Message URL Recognisers
-This is a plug-in to the recogniser framework it will be called when the application framework wishes to recognise a file. Recognisers are called with the file name, in this case a URL, and a buffer containing the start of the file. The message URL recogniser compares the start of the URL with the URL schemes it recognises, if it finds a URL scheme it knows about it maps it to a mime type. The recogniser ignores the buffer passed in.
-Schemes recognised:
-Scheme Mime type
-mailto: X-Epoc-Url/mailto
-fax: X-Epoc-Url/fax
-sms: X-Epoc-Url/sms
-mms: X-Epoc-Url/mms
-See the application framework architectural description for more information on recognisers [R2].
-3.2.7 Messaging / SMS APIs
-3.2.7.1 Key Internal Relationships and Dependencies
-
-Figure 17 SMS Internal Dependencies
-3.2.7.2 Key External Relationships and Dependencies
-
-Figure 18 SMS External Dependencies
-3.2.7.3 API Purpose - Further Elaboration
-3.2.7.3.1 SMS Watchers
-The SMS watchers are made up of two watchers, the nbswatcher.dll and the wapwatcher.dll, and some common base classes in biowatcher.dll. The watchers listen for incoming messages from the SMS stack, part of the nbsprotocols subsystem [R3], and the WAP stack part of the WAP-Stack subsystem [R4].
-3.2.7.3.1.1 NBS Watcher
-The NBS watcher handles reception of SMS messages. When initialised by the watcher framework (see section 3.2.4) the watcher queries the bio messaging database for bio messages that are listed as having a type of ENbs. For each of these bio messages the watcher creates an object that opens a connection to the SMS stack and waits for the particular message type. The message types are either defined by the port number the message will be received on or by a string to watch for at the start of the message. For example Internet Access Configuration Point messages are start with “//SIAP11” and vCards are received on port 226. Finally the watcher listens for all other messages received from the SMS stack.
-When the NBS Watcher receives a non-class 2 SMS message it creates a new entry under the global inbox in the message store. For class 2 messages the entry is created in the class 2 folder as defined by the SMS settings, this may also be the global inbox. The details field of the entry is used to store the phone number of the incoming message or the name of the sender if the watcher finds a match for the phone number in the contacts database. The description field is used to store the first N characters of the SMS message, where N is defined in the SMS settings, or for bio messages the description as retrieved from the bio database. Bio messages also have the BioType field set to the UID of the bio message as retrieved from the bio database. The CSmsHeader class, which is a wrapper around the CSmsMessage class provided by the nbprotocols subsystem [R3], is used to externalise the SMS message to the entry’s CMsvStore. The watcher also places a copy of the body text of the message in the rich text stream of the entry’s CMsvStore.
-The NBS Watcher is also responsible for handing special SMS types including:
-• Replace Type Messages – When the watcher receives a message of this type it will scan the folder the message would have been delivered to for messages that have a matching protocol ID and from address. For each of the messages it checks whether the time stamps from the service centre and discards the older message.
-• Message Indications – The watcher can listen for incoming message waiting indications. The CSmsSettings class defines whether the watcher will listen and whether it will deliver the messages to the inbox or discard them. If the watcher is configured to listen for messages then it will use the SMS utilities in the SMS Client MTM to decode the message to determine the notification type and number of messages, e.g. 3 Email messages waiting, the strings for these messages are in the smss.rss resource file.
-• Delivery Reports – As with Message Indications the watcher can be configured to listen for these and again the SMS utilities get a string from the smss.rss resource file to put in the description field.
-The NBS Watcher handles changes to the bio database using the observer mechanism provided by the bio message database to observe when bio message types are added or removed and starting or stopping the object watching for that bio message type.
-3.2.7.3.1.2 WAP Watcher
-The WAP watcher listens for incoming messages from the WAP stack using the WAP message API [R4]. To determine ports to use to listen for messages the watcher queries the bio message database for bio message types EWsp, EWspSecure, EWap, EWapSecure and registers as an observer of the bio database and so will listen for new bio message with these types as they are added. The watcher stores the messages in the global inbox tagged with the bio type listed in the bio message database.
-3.2.7.3.2 SMS Client MTM
-The SMS Client MTM implements the standard set of Client MTM APIs described in Client MTM. In addition it provides:
-• Access to the CSmsHeader object that is used to represent the SMS message.
-• Access to the SMS settings stored in the associated SMS service.
-• The APIs required by Send As to allow Send As to create SMS messages including setting the bio type of the message to allow clients of Send As to send bio messages such as vCards and vCals. The data of the bio message is stored in the body text of the SMS message.
-• Simple check for valid SMS addresses, and SMS address is considered valid if it contains at least one digit.
-• Reading and writing SIM parameters.
-3.2.7.3.3 SMS Utilities
-These provide:
-• Classes to represent and store SMS messages (CSmsHeader), and SMS settings (CSmsSettings, CSmsMessageSettings) and a SMS number (CSmsNumber).
-• The CSmsHeader class contains and allows clients to access the CSmsMessage class that the nbsprotocols subsystem provides. This contains the entire SMS message and not just the header.
-• Functions to generate descriptions and details fields to store with SMS messages, including decoding special messages such as message indication and status report messages, reading resource file for descriptions strings of special messages, using the contacts database to replace phone numbers with names.
-• API to validate a GSM number.
-• Find the TMsvId of the SMS service entry.
-3.2.7.3.4 SMS Server MTM
-3.2.7.3.4.1 Sending Messages
-The SMS Server MTM handles sending of SMS and WAP messages via the SMS stack and the WAP stack. To support this it implements the CopyFromLocal API inherited from the Server MTM base class. It implements this as sending SMS messages and moving successfully sent messages to the Sent folder. When sending the SMS message the Server MTM checks the bio type of the message and uses the bio database to check the transport type for the bio message. The MTM supports ENbs that is sent via the SMS stack and EWap, EWapSecure that are sent via the WAP stack. The MTM does not support EWsp or EWspSecure although the watchers do support receiving them.
-If a message fails to send, sending is retried according to the settings in the smss.rss resource file as described in the schedule send section 3.2.3.
-3.2.7.3.4.2 Scheduling Messages
-The SMS Server MTM implements scheduled sending API by sub-classing from the schedule send Server MTM (see section 3.2.3). It accepts requests from clients either via the SMS Client MTM InvokeAsync API or via the CMsvSession::TransferCommand API to schedule messages to be sent or to delete existing schedules. When it receives a request to schedule a message it packages up the command and uses the scheduled send functionality to request that the task scheduler ask it to send the messages at a future point in time.
-3.2.7.3.4.3 Phone Store
-The phone store is the name given to storage of SMS messages outside of the message store. In the case of GSM phones this is the SIM. The SMS Server MTM accepts requests from clients to copy/move messages to and from the SIM and delete messages from the SIM. For example when copying to the SIM it packages up the SMS message and passes it to the SMS stack with a request to write it to the SIM. If the class2 folder has been set in the SMS settings class then the Server MTM will copy the SMS message to the SIM and then update the SMS message in the message store with details of the slot on the SIM that has been used to store the SMS and the fact that it is stored on the SIM.
-3.2.7.3.4.4 SIM Parameters
-The Server MTM provides functions to read / write SIM parameters, again these requests are passed to the SMS stack to be processed.
-3.2.8 Messaging / CDMA SMS APIs
-3.2.8.1 Key Internal Relationships and Dependencies
-
-Figure 19 CMDA SMS Internal Dependencies
-3.2.8.2 Key External Relationships and Dependencies
-`
-Figure 20 CDMA SMS External Dependencies
-3.2.8.3 API Purpose - Further Elaboration
-3.2.8.3.1 CDMA SMS Watchers
-The CDMA SMS watchers are made up of six watchers, the cdmanbswatcher.dll, vmnwatcher.dll, wemtwatcher.dll, wmtwatcher.dll, wptwatcher.dll, and the wapwatcher.dll, and some base classes in biowatcher.dll and cdmasocketwatcher. While the WAP watcher is common for both GSM and CDMA, the other watchers: CDMA NBS watcher, VMN watcher, WEMT watcher, WMT watcher, and the WPT watcher are used for CDMA only. The watchers listen for incoming messages from the CDMA SMS stack, part of the nbsprotocols subsystem [R3], and the WAP stack part of the WAP-Stack subsystem [R4].
-3.2.8.3.1.1 CDMA NBS Watcher
-The CDMA NBS watcher is similar to the NBS watcher and it handles bio messages defined in bio database. The CSmsHeader class is extended to wrap around the CCdmaSmsMessage class provided by the nbprotocols subsystem [R3], and is used to externalise the CDMA SMS message.
-For handling special CDMA SMS type, the CDMA NBS watcher is responsible for handling Message Indications as described in section 3.2.7.3.1.1 NBS Watcher.
-3.2.8.3.1.2 WAP Watcher
-The GSM WAP watcher is used to handle CDMA WAP message as well. The WAP watcher listens for incoming messages from the WAP stack, which can listen from the CDMA SMS stack or GSM SMS stack as appropriate. See 3.2.7.3.1.2 for more info about WAP watcher.
-3.2.8.3.1.3 Other CDMA Watchers
-The VMN watcher, WEMT watcher, WMT watcher and WPT watcher are CDMA watchers that handle reception of CDMA SMS messages. All CDMA SMS messages are associated with a teleservice. Therefore, each of the CDMA watchers is responsible for handling one teleservice: VMN watcher handles VMN SMS messages, WEMT watcher handles WEMT SMS messages, WMT watcher handles WMT SMS messages, and WPT watcher handles WPT SMS messages. The CSmsHeader class is reused to externalise the CDMA SMS message.
-The CDMA watchers are also responsible for handling special SMS types including:
-• Duplicate Message – When the watcher receives a duplicate message, it will discard the duplicate message as defined by the CDMA service settings.
-• User Acknowledge – The watcher can listen for user acknowledgment message of its teleservice type.
-• Delivery Acknowledge – The watcher can listen for delivery acknowledgment message of its teleservice type.
-• Read Acknowledge – The watcher can listen for read acknowledgment message of its teleservice type.
-3.2.8.3.2 CDMA SMS Client MTM
-The CDMA SMS Client MTM implements the standard set of Client MTM APIs described in Client MTM. In addition it provides:
-• Access to the CSmsHeader object that is used to represent the SMS message.
-• Access to the SMS settings stored in the associated SMS service. These settings are store in file store pre v9.0 but stored in Central Repository from v9.0 onwards.
-• The APIs required by Send As to allow Send As to create SMS messages including setting the bio type of the message to allow clients of Send As to send bio messages such as vCards and vCals. The data of the bio message is stored in the body text of the SMS message.
-• Simple check for valid SMS addresses, and SMS address is considered valid if it contains at least one digit.
-• Reading and writing SMS messages to R-UIM.
-3.2.8.3.3 CDMA SMS Utilities
-The CDMA version of SMS utilities are binary compatible with the GSM version of SMS utilities. But the classes that store SMS Message (CSMSHeader), and SMS settings (CSmsSettings, CSmsMessageSettings) and SMS number (CSmsNumber) are extended to store CDMA information. The CSmsHeader class is extended to contain and allow clients to access the CCdmaSmsMessage in addition to the CSmsMessage. Other functions provided by the GSM SMS Utilities is also provided by the CDMA version of SMS utilities, see 3.2.7.3.3 for information about GSM SMS Utilities.
-3.2.8.3.4 CDMA SMS Server MTM
-3.2.8.3.4.1 Sending Messages
-The CDMA SMS Server MTM handles sending of CDMA SMS and WAP messages via the CDMA SMS stack and the WAP stack. To support this it implements the CopyFromLocal API inherited from the Server MTM base class. It implements this as sending SMS messages and moving successfully sent messages to the Sent folder. When sending the CDMA SMS message the Server MTM will use the appropriate teleservice type. The MTM supports ENbs that is sent via the SMS stack and EWap, EWapSecure that are sent via the WAP stack. The MTM does not support EWsp or EWspSecure although the watchers do support receiving them.
-If a message fails to send, sending is retried according to the settings in the smss.rss resource file as described in the scheduled send section 3.2.4.
-3.2.8.3.4.2 Scheduling Messages
-The CDMA SMS Server MTM implements scheduled sending API by sub-classing from the schedule send Server MTM similar to implemented in the GSM SMS Server MTM. See 3.2.7.3.4.2 for more information.
-3.2.8.3.4.3 Phone Store
-In the case of CDMA phones, phone store can be phone-based storage or R-UIM based storage. The CDMA SMS Server MTM accepts requests from clients to copy/move messages to and from the phone/R-UIM and delete messages from the phone/R-UIM. For example when copying to the R-UIM it packages up the SMS message and passes it to the CDMA SMS stack with a request to write it to the R-UIM.
-3.2.8.3.5 Configuration for using CDMA SMS MTM
-The CDMA messaging components currently only support single mode, but it is designed such that it can become multimode in the future. Currently, -Dcdma option is used to for selecting CDMA mode for using emulator and building ROM.
-
-
-3.2.9 Messaging / Email APIs
-3.2.9.1 Key Internal Relationships and Dependencies
-
-Figure 19 Email Internal Dependencies
-
-3.2.9.2 Key External Relationships and Dependencies
-
-Figure 20 Email External Dependencies
-3.2.9.3 API Purpose - Further Elaboration
-3.2.9.3.1 Email Overview
-The Email plug-ins consist of a set of utilities and MTMs for POP3, IMAP4 and SMTP. For each email account a pair of services entries is created in the message store. For a POP3 account there will be an SMTP service and a POP3 service, for an IMAP4 account there will be an SMTP service and as IMAP4 service. These entries are used to store the settings for the email transport. Each of the service entries has its related ID set to the other member of the pair. The SMTP service is created invisible so the user only sees the POP3 or IMAP4 service entry, copying a message to the SMTP service will cause the SMTP Server MTM to attempt to send the message. The POP3 and IMAP4 MTMs provide functionality to synchronise with a remote email server this is achieved by extending the Client MTM interface via the InvokeAsync API. Synchronisation of a POP3 or IMAP4 account will result in copying headers and optionally body text and attachments from the email server and creating message entries under the POP3 or IMAP4 service entry.
-Email messages are represented in a common format whether they are being sent via SMTP or downloaded via POP3 or IMAP4. The email client utilities provide the classes for creating and manipulating the entry structure used to store emails. The email server side utilities provide classes to convert between the entry structure used to store emails in the message store and RFC2822 email messages sent to SMTP servers and retrieved from POP3 servers. IMAP4 email messages are parsed by the email server and the IMAP4 Server MTM requests and stores the individual parts of the messages.
-3.2.9.3.2 Email Client Utilities
-The email client utilities are part of the imcm DLL and provide classes for:
-• Storage of email messages including mime headers, RFC2822 headers, attachments, body text and encoding information in the message store
-• Manipulating email messages, for example adding attachments, replying etc.
-• To wrap up the character converters used to convert between standard character sets and Unicode. These make use of the charconv component that is part of the system libraries subsystem.
-• Storage of Email settings in the message store.
-• Progress information for email operations.
-The utilities are used directly by clients to access parts of email messages for display. CImEmailMessage provides the functionality used by clients displaying email messages, including listing attachments, getting body text and resolving URIs in M-HTML messages.
-The Email Client MTMs use the utilities when they are asked to create, reply to and forward messages CImEmailOperation provides the functionality to perform these operations. Each email message is represented by a parent message entry and then entries to represent mime folders and mime parts, see Figure 7 for an example, so adding or deleting mime parts involves walking the tree of entries and inserting / removing entries as appropriate.
-3.2.9.3.3 Email Server MTM Utilities
-The Email Server MTM Utilities are responsible for generating and parsing of RFC2822 format email messages and providing an API to wrap up a TCP/IP connection to a remote email server.
-• Parsing of RFC2822 Email Messages – The utilities provide an API that accepts the text of an RFC2822 email message a line at a time and stores the email message in messaging’s internal format for email messages. See the Email Client Utilities for details of this format. The API handles storing of RFC2822 headers, MIME headers, decoding of Base64 encoded or uuencoded attachments and decoding of text received in character sets supported by the charconv component. This API is only accessible to Server MTMs, as it requires classes that can only be instantiated while running within the message server process. See the Messaging Functional Specification [R1] for detail on which email specifications the utilities support.
-• Generation of RFC2822 Email Messages – The utilities provide an API to convert an email in messaging’s internal format into an RFC2822 email message. The API provides access to the RFC2822 text a line at a time for streaming to an SMTP server. The exact format of the email depends on the settings passed in; the API can generate plain RFC2822 email messages with uuencoded attachments, MIME email messages with Base64 encoded attachments, or M-HTML email messages with Base64 encoded attachments. See the Messaging Functional Specification [R1] for detail on which email specifications the utilities support.
-• TCP/IP socket wrapper – The utilities provide a class that abstracts a TCP/IP socket supplied by the networking subsystem into an API that supports sending and receiving lines of text to / from a remote server. This API is used to connect to remote email servers by each of the email Server MTMs. The API can either create insecure or secure sockets enabling the SSL encryption provided by the networking subsystem. It also supports changing an insecure socket into a secure socket, this enables the email Server MTMs to implement email protocols where the initial connection to the server is insecure and then a secure socket is negotiated before sending or requesting any sensitive information.
-3.2.9.3.4 POP3 MTMs
-The POP3 MTMs implements the functionality to synchronise the local message store with a remote POP3 email server.
-3.2.9.3.4.1 Client MTM
-The POP3 Client MTM implements the standard Client MTM APIs and other extensions:
-• Reply to, forward – These are accessible via the ReplyL and ForwardL APIs of a Client MTM and are implemented as calls to the email utilities class CImEmailOperation.
-• Reply to, forward, create new messages, create receipts and forward as attachment – These are accessible as commands available via the InvokeAsyncFunction API of the Client MTM, they are implemented as calls to CImEmailOperation.
-• Connecting, disconnecting and copying email while connected – These operations are accessible as commands available via the InvokeAsyncFunction API of the Client MTM, they are implemented as calls to the POP3 Server MTM.
-• Querying connection status – This command lets clients know whether the POP3 Server MTM is connected to an email server, and is available via the InvokeAsyncFunction API of the Client MTM. The Client MTM requests the information from the Server MTM.
-• Compound operations – The Client MTM provides functionality to wrap up connecting to email servers, copying / moving new messages or a selection of messages, and then optionally disconnecting. These commands are available via the InvokeAsyncFunction API of the Client MTM. The Client MTM implements this by using the CImPOP3GetMail class which requests the correct sequence of operations from the Server MTM, waiting for each operation to complete before requesting the next one.
-• Send on next connection If the Client MTM gets a request to connect to an email server it will check whether the POP3 settings. If send on next connection is requested it will launch the autosend.exe executable (see section 3.2.7.3.7) to handle sending messages waiting in the outbox.
-• Offline operations – The POP3 Client MTM has a command to cancel offline operations, this is available via the InvokeAsyncFunction API of the Client MTM. The Client MTM passes the request to the Server MTM.
-3.2.9.3.4.2 Server MTM
-The POP3 Server MTM handles the communication with the remote POP3 server and implementation of the POP3 protocol. The MTM uses CImTextServerSession to handle the communication with the email server and CImRecvConvert to parse the email messages downloaded, both are provided by the Email Server MTM Utilities.
-• Connect – The POP3 Server MTM will open a socket to the email server using CImTextServerSession and login user the username / password in the POP3 settings. After a successful connection the Server MTM will attempt to synchronise the current state of headers stored on the email server with the set stored in the message store and then start any pending offline operations. After the connect operation has completed the Server MTM will inform the message server that it is expecting more operations via the CommandExpected API and therefore the message server will not delete and unload the Server MTM.
-• Populate Message – The POP3 Server MTM treats requests to copy a message from and to the POP3 service as a request to download the full message.
-• Offline operations – When the POP3 Server MTM receives a request to copy, move, or delete and is not connected to a POP3 email server the Server MTM will store the operation in the CMsvStore of the entry being modified and perform the operation on the next connection to the email server.
-• Disconnect – When disconnecting from a remote email server the POP3 MTM will run any pending offline operations stored. After the disconnect operation completes the Server MTM will allow the message server to delete and unload the Server MTM by setting the CommandExpected API to false.
-3.2.9.3.5 IMAP4 MTMs
-The IMAP4 Server MTM implements the functionality to synchronise the local message store with a remote IMAP4 email server.
-3.2.9.3.5.1 Client MTM
-The IMAP4 Client MTM implements the standard Client MTM APIs and other extensions:
-• Connecting, disconnecting, synchronising, un/subscribing folders – These operations are accessible as commands available via the InvokeAsyncFunction API of the Client MTM, they are implemented as calls to the IMAP4 Server MTM.
-• Send on next connection – If the Client MTM gets a request to connect to an email server it will check whether the IMAP4 settings. If send on next connection is requested it will launch the autosend.exe executable (see section 3.2.7.3.7) to handle sending messages waiting in the outbox.
-• Reply to, and forward messages – These are accessible via the ReplyL and ForwardL APIs of a Client MTM and are implemented as calls to the email utilities class CImEmailOperation.
-• Reply to, forward, create new, create receipt, forward as attachment – These are accessible as commands available via the InvokeAsyncFunction API of the Client MTM, they are implemented as calls to CImEmailOperation.
-• Querying connection status – These commands let clients know whether the IMAP4 Server MTM is connected to an email server and whether it is currently processing a request. They are available via the InvokeAsyncFunction API of the Client MTM. The Client MTM requests the information from the Server MTM.
-• Compound Connection and synchronisation – The IMAP4 Client MTM provides a compound operation that connects and synchronises with an IMAP4 server. This operation is implemented as a client side object that combines requests to the IMAP4 Server MTM. The client side operation can complete the client request either after the connection, after the connection + sync or after the connection + sync + disconnect. The client will keep requesting that the inbox be resynchronised at a configurable interval so new messages received in the inbox on the server will appear under the IMAP4 inbox. The CImapConnectAndSyncOp class handles these compound operations.
-• Compound Connect and copy / move / populate messages – The IMAP4 Client MTM provides a compound operation that connects to an IMAP4 server and copies moves or populates messages. The implementation is provided by the CImImap4GetMail class which makes calls back into the IMAP4 Client MTM.
-• Offline operations – The IMAP4 Client MTM has a command to cancel offline operations, this is available via the InvokeAsyncFunction API of the Client MTM. The Client MTM passes the request to the Server MTM.
-3.2.9.3.5.2 Server MTM
-The IMAP4 Server MTM handles the communication with the remote IMAP4 server and implementation of the IMAP4 protocol. The MTM uses CImTextServerSession to handle the communication with the email server. The IMAP4 Server MTM opens two connections to the IMAP4 server this enables users to download messages while the Server MTM is performing a background synchronisation if requested by the Client MTM.
-• Connect – The IMAP4 Server MTM will open a socket to the email server using CImTextServerSession and login using the username / password in the IMAP4 settings. After a successful connection the Server MTM will optionally attempt to synchronise the current state of headers stored on the email server with the set stored in the message store and then start any pending offline operations. After the connect operation has completed the Server MTM will inform the message server that it is expecting more operations via the CommandExpected API and therefore the message server will not delete and unload the Server MTM.
-• Copy, Move messages – The IMAP4 Server MTM supports copying and moving messages between folders on the IMAP4 server and between the IMAP4 server and local folders.
-• Delete messages – The IMAP4 Server MTM will mark the email as deleted on the server; however it will not be deleted until the IMAP4 Server MTM disconnects from the server.
-• Folders – The IMAP4 Server MTM will allow folders to be subscribed, unsubscribed, renamed, copied, moved, and created within the IMAP4 service. Subscribing to a folder means that it will be visible to the user and synchronised with the remote server. The inbox is always subscribed.
-• Offline operations – When the IMAP4 Server MTM receives a request to copy, move, or delete and is not connected to an IMAP4 email server the Server MTM will store the operation in the CMsvStore of the entry being modified and perform the operation on the next connection to the email server.
-• Disconnect – When disconnecting from a remote email server the IMAP4 MTM will run any pending offline operations stored. After the disconnect operation completes the Server MTM will allow the message server to delete and unload the Server MTM by setting the CommandExpected API to false.
-
-3.2.9.3.6 SMTP MTMs
-The SMTP MTMs provide functionality to send email messages. They are made up of the Client MTM that is part of the imcm DLL and the Server MTM.
-3.2.9.3.6.1 Client MTM
-The SMTP Client MTM implements the standard Client MTM APIs including the functions required to allow clients of Send As to create email messages.
-3.2.9.3.6.2 Server MTM
-The SMTP MTMs provide functionality to send email messages; it interprets requests to copy entries to an SMTP service as a request to send those messages. In addition it responds to two extended commands via the StartCommand Server MTM interface. These commands are KSMTPMTMIsConnected that responds with whether the Server MTM is currently connected to a remote SMTP server and KSMTPMTMSendOnNextConnection which performs the same operation as copying a selection of messages to an SMTP service. The only difference between the copy operation and the KSMTPMTMSendOnNextConnection operation is that the latter can be called without a selection of messages.
-When the Server MTM receives a request to send messages it builds a selection of messages consisting of the messages passed into the operation and any messages waiting in the outbox to be sent. To determine which messages in the outbox are waiting to be sent the SMTP server checks for messages that have the same service ID as the destination of the send operation and have a sending state of KMsvSendStateWaiting, KMsvSendStateScheduled or KMsvSendStateResend. This means that any request to send messages may result in more messages being sent than explicitly listed in the selection passed to the send operation.
-The Server MTM restores its settings from the SMTP service it has been asked to copy the messages to. Then it connects to the SMTP server using the CImTextServerSession class in the Email Server MTM Utilities, passing in the SMTP server address and TCP/IP port number from the SMTP settings. Then for each message to be sent the Server MTM uses the Email Server MTM utilities to generate an RFC2822 format message to send to the SMTP server, the RFC2822 text is generated on the fly as the data is sent to the SMTP server. If the SMTP server accepts the message to be sent then the Server MTM moves the message to the sent folder and sets its sending state to sent. If the SMTP server rejects the message then the Server MTM leaves the message in the outbox and sets the sending state to failed. Separate emails are generated for BCC recipients to ensure that the SMTP server doesn’t incorrectly include BCC recipients in emails sent to addresses in the To and CC fields of the email.
-3.2.9.3.7 Autosend
-The Autosend component is an executable that is kicked off by the POP3 and IMAP4 Client MTMs if the send on next connection setting is set. This executable will just make a request to the SMTP Server MTM to send messages associated with the SMTP service related to the POP3 or IMAP4 service, wait for the operation to finish and then exit.
-3.2.10 Messaging / MMS APIs
-The MMS module has been removed from v9.0 and onwards.
-3.2.10.1 Key Internal Relationships and Dependencies
-
-Figure 21 MMS Internal Dependencies
-3.2.10.2 API Purpose - Further Elaboration
-3.2.10.2.1 MMS Overview
-The MMS MTM provides functionality for creating, accessing, sending and receiving MMS messages. Messages are sent and received without the client application needing to open or close any kind of session. The management of the MMS session is handled entirely within the MTM.
-MMS clients are alerted when a new message is available for download via the WAP Push mechanism. A WAP push watcher is provided to handle these notifications. After the notification the message can be downloaded over WSP or HTTP. Messages are sent by posting the data over WSP or HTTP. The Symbian MMS implementation can handle sending or receiving MMS message over either protocol.
-MMS messages are based on the MIME format but are binary encoded using WSP. Note that MMS messages are encoded in this way even if they are posted over HTTP as opposed to WSP. The codec component is responsible for this encoding and decoding.
-3.2.10.2.2 MMS Utilities
-3.2.10.2.2.1 Key External Relationships and Dependencies
-
-Figure 22 MMS Utilities External Dependencies
-The MMS utilities provide the message and settings encapsulation classes. The MMS settings and messages are stored in the message store, the MMS utilities provide the interfaces to access this data.
-3.2.10.2.2.2 Settings
-The settings functionality provided by the MMS utilities allows the messaging client to persist MMS settings in the message store. Supported settings include:
- MMSC (MMS server) address
- WSP or HTTP transport
- Autofetch messages on notification
- Preferred IAP for the MMS network connection
-The settings functionality is also used by the server MTM to retrieve the settings prior to message sending or fetching.
-3.2.10.2.2.3 Message Encapsulation
-The message classes provide the message access functionality. Messages can be created, stored, restored and read using these classes. Functionality includes:
- Adding media objects to the message
- Enumerating through media objects
- Adding recipients, subject line, etc. to a message
- Adding other headers to the message, e.g. expiry date
- Finding the appropriate media object for a given URI in the SMIL part (URI resolving)
-The message data is stored in the message store using one entry per message regardless of the number of media objects added to the message. This is preferable to using multiple message entries as it is faster and uses less disk space.
-Most of the message access code is common whether it is being used on the client or server side, however some parts of it are specific. For this reason it is essential that the appropriate client or server side CMmsMessage derived class is used.
-3.2.10.2.3 MMS Watcher
-3.2.10.2.3.1 Key External Relationships and Dependencies
-
-Figure 23 MMS Watcher External Dependencies
-
-The MMS watcher plug-in is responsible for intercepting incoming MMS notifications and delivery reports then taking the appropriate action. It is implemented as a WAP Push watcher plug-in.
-When an MMS notification is received an MMS entry is created in the inbox using the MMS utilities. At this point the entry has its incomplete flag set. If the settings have the autofetch option selected then the MMS watcher initiates the fetch operation via the MMS client MTM.
-If a delivery report is received then the delivered flag is set on the appropriate sent message. If an outgoing message was sent to several recipients then there will be several delivered flags. A delivery report from each recipient will set the appropriate delivered flag.
-3.2.10.2.4 MMS Client MTM
-3.2.10.2.4.1 Key External Relationships and Dependencies
-
-Figure 24 MMS Client MTM Dependencies
-As with most other MTMs the MMS client MTM provides access to the server MTM functionality for messaging clients. It also implements the Send-As interface and reply and forward functionality.
-3.2.10.2.4.2 Send-As Implementation
-The Client MTM Send-As interface is implemented in the MMS Client MTM. The implementation differs slightly from other MTMs because additional presentation content may be generated depending on the media objects that are added. When simple combinations of images, sounds and text are added a SMIL presentation is generated to link them together. This is preferable to simple adding the objects as attachments where some clients render them as a list of files and others fail to render them at all.
-The SMIL data is constructed using templates stored in resource files, the GMXML (SMIL) composer is not used.
-3.2.10.2.4.3 Reply / Forward
-The Client MTM can be used to create replies to received messages or to create forwarded responses. The reply and forwarding operations are performed asynchronously.
-3.2.10.2.5 MMS Server MTM
-3.2.10.2.5.1 Key External Relationships and Dependencies
-
-Figure 25 MMS Server MTM Dependencies
-The Server MTM is the most complicated part the MMS implementation. It handles all of the state information required to send or fetch MMS messages. It is also responsible for managing the HTTP or WSP session and the connections to the phone network.
-3.2.10.2.5.2 Operations
-All MMS server MTM functionality is encapsulated in operations. An operation consists of the setup of a session, the sending, fetching and acknowledgements when appropriate, it then closes the session. The messaging client initiates an operation with a single call to the Client MTM, there is no need for the messaging client to explicitly establish the session or to know about the internal states. However, these internal states are available to the messaging client via the progress structure if this level of user feedback is required.
-Two types of operation are supported, background and foreground:
-A maximum of one foreground operation can be running at any one time. The messaging client can poll the server MTM for the progress of a running foreground operation, likewise it can cancel it if necessary.
-A background operation does not support progress information and can not be cancelled by the messaging client. It is possible to initiate background operations even if other background or foreground operations are pending. However, background operations are queued and a maximum of one will actually be running at any one time.
-The MMS watcher uses a background operation to perform automatic fetching. While the background autofetch is occurring it is still possible to start a foreground operation (such as sending a message) if required.
-3.2.10.2.5.3 Session and Connection Management
-The server MTM uses the HTTP Transport Framework to enable the HTTP or WSP session. HTTP or WSP can be selected at runtime by selecting the appropriate option in the settings. The server MTM is responsible for reading any HTTP proxy details from the CommDB and passing it to the HTTP framework. See the http transport framework architectural description for more information on recognisers [R5]
-The server MTM is also responsible for managing the connection to the phone network. Connections are opened when required using the RConnection mechanism, multi-homing is supported provided that the underlying HTTP framework transport plug-in also supports it.
-3.2.10.2.6 MMS Codec
-The MMS Server MTM is in charge of the state transitions, connection, session, the actual posting and fetching of the data from them, however it does not encode or decode the MMS PDUs. The encoding and decoding is performed by the MMS Codec.
-For decoding the Server MTM passes the Codec the MMS PDU data in a descriptor for processing. If the PDU contains a received MMS message then the message entry is updated with the decoded MMS data.
-For encoding the Server MTM passes a reference to the message store entry containing the un-encoded MMS data. The Codec then encodes it and returns the PDU to the Server MTM in a descriptor.
-
-
-3.2.11 Messaging / BIO APIs
-3.2.11.1 Key Internal Relationships and Dependencies
-
-Figure 26 BIO Message Internal Dependencies
-3.2.11.1.1.1 Key External Relationships and Dependencies
-
-Figure 27 Bio Parser External Dependencies
-
-3.2.11.2 API Purpose - Further Elaboration
-3.2.11.2.1 BIO Overview
-The BIO messaging components have been designed to unify and simplify the way in which system messages are processed. In this context ‘system messages’ refers to messages received on the device which are intended to update some attribute(s) on the system as opposed to being presented to the user. Examples of these types of messages include vCards which are parsed and then displayed to the user and when accepted modify the users contact database and OTA configuration messages which are again parsed before display to the user and if accepted create email accounts or internet access points.
-The BIO messaging components can be broken down into three groups:
-1) The BIO MTM - To initiate the parsing and processing of BIO messages
-2) The BIO Database - Maps port numbers, MIME types, etc. to bio types in order to identify the type of incoming BIO messages.
-3) The BIO Parsers - To parse and process the BIO message payload
-BIO messages are not receive by the bio messaging framework, they come over other message transports for example see section 3.2.6.3.1 on the SMS watchers which describes how the SMS watchers receive bio messages and use the bio framework to tag the messages with the correct bio id.
-3.2.11.2.2 BIO MTM
-The BIO client MTM is called by the messaging client to parse or process a BIO message that has been saved in the message store. It is the responsibility of a BIO watcher to save the BIO message with the BIO flag and the appropriate BIO type set.
-The BIO client MTM does very little, its primary task is to pass on the messaging client request to the server MTM. Two operations are supported, parse and process.
-The messaging client is expected to initiate the parsing of the BIO message before processing it. The parsing step involves analysing the data and storing it in a form that can be displayed to the user via the BIO message viewer.
-Once the message has been parsed the messaging client can initiate the processing of the message.
-The BIO server MTM is responsible for deferring the parsing and processing to the appropriate BIO parser. The behaviour for the parsing and processing steps varies between parsers. See the BIO Parsers section for more information.
-The bio MTM does not support sending messages and therefore does not support reply / forwarding messages. For bio messages sending / reply etc. is supported by the particular MTM that the message is sent over, for example SMS.
-3.2.11.2.3 BIO Database
-The BIO database is used to identify the type of BIO messages. It maps message attributes such as port number, MIME type or leading string to a BIO type. These are attributes are then used by clients of the bio framework to know what ports to listen for messages on. For example the SMS watchers use the leading string to wait for SMS messages that start with that string and when storing those messages in the inbox tag them with the bio id associated with that leading string. See the SMS watcher section 3.2.6.3.1 for more examples of how the BIO database can be used.
-3.2.11.2.4 BIO Parsers
-The BIO parsers are plug-ins for parsing and processing incoming BIO messages. They are invoked by the BIO Server MTM depending on the BIO type of the message being processed. Each BIO parser implements two functions, ParseL and ProcessL. The level of functionality varies between parsers. Some parsers update the final repository with the received data, e.g. WAPP updates the CommDB with the received settings. Some parsers simply save the data in an unparsed state for processing by another component, this secondary parsing is not part of the BIO framework and must be initiated by the messaging client. An example is when GFP saves vCard data as a file as opposed to updating the contacts database, the UI must then invoke the Versit parser to parse the vCard and commit it to the contacts database.
-3.2.11.2.4.1 Generic File Parser (GFP)
-The generic file parser can be used to identify and save a variety of BIO data types, e.g. vCards and vCals. The Generic File Parser does not process the data, it simply saves it in the message store for processing by another component. The file is saved as an attachment of the message entry that was parsed.
-3.2.11.2.4.2 Nokia/Ericsson OTA Parser (WAPP)
-The WAPP parser decodes Nokia/Ericsson OTA messages and updates CommDB to reflect the received settings.
-3.2.11.2.4.3 Nokia Smart Message Internet Access Parser (IACP)
-The IACP parser decodes Nokia Smart Messages and updates the CommDB and messaging settings where appropriate.
-3.2.11.2.5 BIF Files and Utilities
-The BIF files encapsulate the information required for identifying BIO messages, these details may include the expected port number, MIME type or leading string. Different BIO watcher will use different information from these files, for an example see the 3.2.6.3.1. The information can be retrieved from the BIF files by using the BIF utilities. Generally BIO aware clients will access this information via the BIO database. BIF files are resource files previous to the v6.1 release they were binary files generated by biftool.exe.
-3.2.11.2.6 Platform Security Compliant Messaging / BIO APIs
-In the platform security model the BIO parsers are run in the client space rather than in the message server space, as is done in the non-platform secure model. If the BIO parsers are run in the message server space, it allows a client process to gain the capabilities of the message server. IPC policing can protect the message server from this.
-Also, for the message server to be able to load any BIO parser it would need more capabilities than it really requires. By running the BIO parsers in the client space, both these issues are solved. The client process must be trusted with the necessary capabilities to run the specified BIO parser.
-The BIO registry files are located in the \resource\messaging\bif read-only directory. All BIO parser DLLs are located in the \sys\bin protected directory.
-
-Figure 26 BIO Message Dependencies (v9.0)
-The BIO client MTM is responsible for loading the BIO database and BIO utilities to handle parse/process requests from clients.
-The BIO registry files no longer identify the BIO parsers DLLs via their UID – the registry file must use the BIO parser DLL name to identify them.
-3.2.12 Messaging / OBEX MTM APIs
-3.2.12.1 Key Internal Relationships and Dependencies
-
-Figure 28 OBEX Internal Dependencies
-3.2.12.2 OBEX MTM Overview
-The OBEX MTM offers simple IR and Bluetooth beaming functionality. It provides an API that is consistent with other MTMs so that the underlying OBEX APIs do not need to be used directly for beaming applications. The OBEX MTM does not provide OBEX receiving functionality, in order to receive OBEX data the underlying OBEX APIs must be used directly.
-3.2.12.2.1 OBEX MTM
-The OBEX MTM is split into three parts. OBEX MTM DLLs, IR MTM DLLs and Bluetooth MTM DLLs. The OBEX MTM DLLs can not be used on their own they provide the base OBEX MTM functionality for the derived IR and Bluetooth MTMs.
-There are two APIs that can be used to create OBEX messages:
-1) The Send-As API
-2) Linked attachments by filename
-The Send-As API provides an interface consistent with other MTMs, however it requires all attachments to be copied into the message store before they can be sent, this is often undesirable for beaming applications because it is wastes disk space. For this reason a second API is provided that allows attachments to be linked to outgoing messages by filename, when this API is used there is no need to copy the attachments to the message store.
-Unlike many other MTMs after OBEX tries to send a message it is deleted from the outbox whether the sending succeeds or fails.
-3.2.12.2.1.1 OBEX MTM Key External Dependencies
-
-Figure 29 OBEX External Dependencies
-3.2.12.2.2 IR MTM
-The bulk of the OBEX MTM functionality is provided by the OBEX MTM DLLs, the IR MTM itself just sets up the parameters.
-3.2.12.2.2.1 IR MTM Key External Dependencies
-
-Figure 30 IR MTM Dependencies
-3.2.12.2.3 Bluetooth MTM
-The bulk of the OBEX MTM functionality is provided by the OBEX MTM DLLs, the Bluetooth MTM just subclasses from the OBEX MTM and sets up Bluetooth specific parameters.
-3.2.12.2.3.1 Bluetooth MTM Key External Dependencies
-
-Figure 31 Bluetooth MTM Dependencies
-3.2.12.2.4 OBEX MTM Utils
-The OBEX MTM Utils provide utility functionality used by the other OBEX MTM DLLs. The two main areas of functionality provided by this component are:
-1) Filename linking functionality
-2) Bluetooth SDP lookup
-The filename linking functionality is provided in the utilities because linked files must be added by the client side during message creation and need to be read on the server side during sending.
-
-3.2.12.2.5 Platform Security Compliant Messaging / OBEX MTM APIs
-From v9.0 and onwards the service settings of all the derived OBEX MTMs are stored in the Central Repository. The OBEX message is stored in the message store as an attachment – from v9.0 and onwards the Attachment API is used to attach the OBEX message.
-
-3.2.13 Messaging / GMXML APIs
-3.2.13.1 Key Relationships and Dependencies
-
-Figure 32 GMXML Dependencies
-3.2.13.2 Overview
-The GMXML component provides simple XML DOM parsing and validation functionality. It is intended for parsing XML that might be needed in messaging applications, specifically SMIL parsing for MMS rendering. It is not a general purpose XML parser and will not be suitable for some applications, e.g. browsing.
-3.2.13.2.1 GMXML DOM
-The DOM implementation is fit for purpose for SMIL rendering but differs from the standard DOM design in several respects, e.g. attributes are not stored as discrete nodes, for performance reasons they are stored with the element.
-The DOM tree classes are all derived from nodes. Implemented node types include elements, text and comments. The type of each element is stored as a descriptor as opposed to an enum. This is less efficient than storing it as an enum but provides maximum flexibility when dealing with unknown element types.
-Nodes are linked together in a tree structure as might be expected in a DOM implementation. The tree structure exists on the heap.
-3.2.13.2.2 GMXML Parser and Composer
-3.2.13.2.2.1 Parser
-The parser takes XML input from a buffer or file and creates the corresponding DOM structure on the heap.
-The parser is capable of performing some basic validation. In order to validate against a DTD a class that implements the GMXML DTD interface is required. The DTD interface specifies several functions that provide the required validation, e.g. one of the functions determines if a given attribute is valid for a given element. An instance of the DTD class should be passed into the parser when validation is required but can be omitted if no validation is needed.
-3.2.13.2.2.2 Composer
-The composer takes a DOM tree and generates XML output from it. The XML output is written to a file.
-3.2.13.2.3 GMXML SMIL DTD (Validator)
-The SMIL DTD validator class is an implementation of the DTD validator interface. It implements several simple functions that provide the information required to validate SMIL data. An instance of the SMIL DTD validator should be passed into the parser if SMIL validation is required.
-4 Security
-4.1 Data caging
-For data storage in the pre-platform security compliant architecture, refer to section [3.2.1.3.2]
-For the data caging in the platform security compliant architecture of v9.0 and onwards, refer to section [3.2.1.3.3]
-4.2 Backup and restore
-The message server registers the index file with the backup server. When informed about a backup/restore it releases the index file, sending events to messaging clients informing them that the message store is unavailable. When informed it can open the index file again, it checks the time stamp on the index file; if it has changed since the file was released it reloads the index file. If the newly restored index file is found to be corrupt it is deleted and a new message store is created. See the section on page 14 for details on how the message server handles corrupt stores. The client performing the restore should always wipe the existing message store before starting to copy the message store from the backup to the device.
-4.3 Capability ranges
-In the platform security compliant architecture of v9.0 and onwards, the capabilities allocated to messaging sub-systems are as listed in following table.
-4.3.1 Capabilities granted to executables
-The following table lists the executables and their capabilities and also gives a basic example for having the required capability.
-
-Executable Capability Rationale (basic example of capability requirement)
-msexe.exe ProtServ ProtServ is required to allow the msexe.exe to start a protected server. This stops processes without ProtServ from starting a server pretending to be the message server
- ReadDeviceData ReadDeviceData is needed to able to read service settings
- WriteDeviceData WriteDeviceData is needed to able to write service settings
- NetworkServices NetworkServices capability is needed to access network transports (SMS, POP3, SMTP, IMAP4).
- LocalServices LocalServices is needed to be able to access IR and Bluetooth
- ReadUserData ReadUserData is needed to be able to read user data (e.g. service settings).
-watcher.exe ReadDeviceData ReadDeviceData is needed to able to read service settings
- WriteDeviceData WriteDeviceData is needed to able to write service settings
- NetworkServices NetworkServices capability is needed to access network transports (SMS).
- LocalServices LocalServices capability is needed for the plug-ins to access IR and Bluetooth
- ReadUserData ReadUserData is needed to be able to read user data
- WriteUserData WriteUserData is needed to be able to write user data
-autosend.exe ReadUserData ReadUserData capability is needed to be able to read data from Outbox and SMTP server MTM.
- WriteUserData WriteUserData capability is needed to be able to write data in Outbox and SMTP server MTM.
- NetworkServices NetworkServices capability is needed to access network transports (SMS, POP3, SMTP, and IMAP4).
- LocalServices LocalServices capability is needed to access the IR and Bluetooth
-SchSend.exe ReadDeviceData ReadDeviceData is needed to able to read settings data
- NetworkServices NetworkServices capability is needed to access the network transports (SMS, POP3, SMTP, and IMAP4).
- LocalServices LocalServices is needed to be trusted by other MTM
- ReadUserData ReadUserData is needed to be able to read user data.
- WriteUserData WriteUserData is needed to be able to write user data.
-SendAs.exe ReadDeviceData ReadUserData is needed to be able to read data in Outbox.
- WriteDeviceData WriteUserData is needed to be able to write data in Outbox.
- NetworkServices NetworkServices capability is needed to access the network transports (SMS, POP3, SMTP, and IMAP4).
- LocalServices LocalServices is needed to be able to access IR and Bluetooth
-
-4.3.2 Capabilities granted to DLLs
-The assigned Platform Security attributes for DLLs within messaging are outlined in the following table.
-DLL Capability
-bifu.dll All –TCB
-bioc.dll All –TCB
-biodb.dll All –TCB
-bios.dll All –TCB
-biowatcher.dll same as watcher.exe
-biut.dll All –TCB
-cbcp.dll All –TCB
-enp.dll All –TCB
-gfp.dll All –TCB
-iacp.dll All –TCB
-nbswatcher.dll same as watcher.exe
-cdmanbswatcher.dll same as watcher.exe
-CdmaSocketWatcher.dll same as watcher.exe
-VMNWatcher.dll same as watcher.exe
-WEMTWatcher.dll same as watcher.exe
-WMTWatcher.dll same as watcher.exe
-WPTWatcher.dll same as watcher.exe
-wapp.dll All –TCB
-wapwatcher.dll same as watcher.exe
-smildtd.dll All –TCB
-xmldom.dll All –TCB
-xmlparser.dll All –TCB
-smiltranslator.dll All –TCB
-imcm.dll All –TCB
-imps.dll same as msexe.exe
-imut.dll All –TCB
-msgs.dll All –TCB
-msgurlrec.mdl same as AppArc.exe (once it exists; eiksrv in meantime)
-mtur.dll All –TCB
-pops.dll same as msexe.exe
-schsend.dll All –TCB
-send.dll All –TCB
-smcm.dll All –TCB
-smcm_gsm.dll Synonym for smcm.dll
-smcm_cdma.dll Synonym for smcm.dll
-smss.dll same as msexe.exe
-smss_gsm.dll Synonym for smss.dll
-smss_cdma.dll Synonym for smss.dll
-smts.dll same as msexe.exe
-btcmtm.dll All –TCB
-btsmtm.dll same as msexe.exe
-irc.dll All –TCB
-irs.dll same as msexe.exe
-obexclientmtm.dll All –TCB
-obexmtmutil.dll All –TCB
-obexservermtm.dll same as msexe.exe
-
-The reason for setting a high capability to the DLLs is to make it possible for almost anyone to link to them. Although a DLL may have capabilities ALL-TCB (All minus TCB), its real capability is limited by the process which loads the DLL.
-4.3.3 Capabilities required to use the subsystem
-The message subsystem needs to be protected against malicious clients. The following table shows the key capabilities required to do related activities in different components.
-
-Component Related Activity Required Capability and SID
-Message server Create message in local folder No capability required
- Create message in Outbox ReadUserData, WriteUserData and MTM specific capabilities
- Access client MTM ReadUserData, WriteUserData and MTM specific capabilities
-Watcher Allow plug-ins to wait on events (e.g. arrival of SMS) Watcher always polices if the client capabilities are trusted by the watcher framework, else it will not be loaded
-Plug-ins or clients using watcher need the same capabilities as watcher.exe to be able to be loaded by watcher.
-Autosend Send messages in background NetworkService or LocalService required by the message type
-SchSend Scheduling of operations (e.g. sending SMS) SchSend always polices to see if the process was started by the Task Scheduler – if not the process terminates without performing any of the scheduled tasks. Also, the SchSend verifies that only itself and the message server created the scheduled tasks. If this is not the case, SchSend does not performing the scheduled tasks.
-SendAs Create message Draft, move it to Outbox, and send message WriteDeviceData or WriteUserData and other capability required by the message type
-
-5 Further Information
-5.1 References
-No. Document Reference Version Description
-R1 messaging_functional_specification.doc 0.6 Messaging Functional description
-R2 SGL.GT0143.161_App-Framework_Architectural_Description.doc 1.0 App-Framework Architectural Description
-R3 NBProtocols_Subsystem_Architectural_Description.doc 0.2 NBProtocols Architectural Description
-R4 WAP-stack_architectural_analysis.doc 1.0 WAP stack architectural analysis
-R5 HTTP Transport Framework Architectural Description.doc 1.1 HTTP Transport Framework 1.1 Architectural Description
-5.2 Open Issues
-The following issues need to be resolved before this document is completed:
-1. Top-level architecture diagram showing the framework and plug-ins should be added to overview section.
-2. Message store section should talk about removable media.
-3. Define "Message Server Client API" and "Messaging Client API" in the glossary, and ensure it is consistently used in the diagrams
-4. Add a sequence diagram for receiving a vCard over SMS and integrating it into contacts
-5. Add a sequence diagram for sending an SMS
-6. Add a sequence diagram for synchronising a POP3 mail box
-7. Add a sequence diagram for connecting to an IMAP4 mail box and downloading a message
-8. Capability table should be updated after the implementation of server e.g. message server
-9. Sequence diagram may need to be changed to show secured platform operation
-10. In section [3.1.1.4] the server SendAsV2 to find a correct name
-11. Section 3.2.1.3.3.1 Data Caging file 'Mtm Registry v2'may need a correct name
-12. Breakdown diagram showing all DLL, exes, apps in the messaging subsystem for both the pre-v8.0 and post v9.0 in section[3.2]
-13. Needs to say more about how the capabilities are policed and the algorithms used for different operations
-14. The dependecy between the message server and the central repository need to be listed in the email, SMS and OBEX diagrams (e.g. message store)
-15. Section 3.2.1.2 - figure 3 - Central Repository also get used by the Message server, or server MTMs (e.g. POP3), to retrieve account settings the path, required DLL and description are not given
-16. Section 4.3.3 title can be Police requirement of the sub-system, add extra column for SID in the table and list the use of SID. For example SchSend checks for Task Scheduler SID
-
-
-5.3 Glossary
-The following technical terms and abbreviations are used within this document.
-Term Definition
-BIO
-Bearer Independent Object Smart messages e.g. vCards, vCals, and WAP provisioning messages. These can currently be received via the WAP stack, SMS stack, Bluetooth or Infrared.
-BIO Type UID that represents the content type of a BIO Message.
-Message Centre Application that displays list views of messages to the user, allowing the user to perform operations such as copying messages, sending messages creating new messages etc.
-Message Viewer Application for viewing a message.
-Message Editor Application for creating or editing a message
-Message Server Symbian OS Server that handles request to modify the Message Store
-Message Store Store of messages and related information kept in the file system on a Symbian OS device.
-Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
-Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
-Global Inbox A standard folder under the local service which is used to store incoming messages like SMS MMS etc. as opposed to an IMAP4 Inbox which would be under an IMAP4 service and is a representation of the Inbox on an IMAP4 email server.
-Central Repository centralised and secure storage facility for application settings
-OBEX Object exchange protocol, used to send objects such as vCards or files between devices via infrared or Bluetooth.
-GMXML XML parser / generator for use with SMIL formatted messages.
-UID Unique Identifier, a 32 bit number allocated from a registry owned by Symbian
-IPC Inter Process Communication
-MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
+MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
MTM Registry A list of currently installed MTMs maintained by the message server.
TLS Transport Layer Security, provides encryption of a TCP/IP socket.
M-HTML Standard for including HTML in MIME email messages see http://www.ietf.org/rfc/rfc2557.txt
@@ -18261,15 +13171,15 @@
Message Editor Application for creating or editing a message
Message Server Symbian OS Server that handles request to modify the Message Store
Message Store Store of messages and related information kept in the file system on a Symbian OS device.
-Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
-Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
+Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
+Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
Global Inbox A standard folder under the local service which is used to store incoming messages like SMS MMS etc. as opposed to an IMAP4 Inbox which would be under an IMAP4 service and is a representation of the Inbox on an IMAP4 email server.
Central Repository centralised and secure storage facility for application settings
OBEX Object exchange protocol, used to send objects such as vCards or files between devices via infrared or Bluetooth.
GMXML XML parser / generator for use with SMIL formatted messages.
UID Unique Identifier, a 32 bit number allocated from a registry owned by Symbian
IPC Inter Process Communication
-MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
+MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
MTM Registry A list of currently installed MTMs maintained by the message server.
TLS Transport Layer Security, provides encryption of a TCP/IP socket.
M-HTML Standard for including HTML in MIME email messages see http://www.ietf.org/rfc/rfc2557.txt
@@ -19279,15 +14189,15 @@
Message Editor Application for creating or editing a message
Message Server Symbian OS Server that handles request to modify the Message Store
Message Store Store of messages and related information kept in the file system on a Symbian OS device.
-Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
-Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
+Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
+Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
Global Inbox A standard folder under the local service which is used to store incoming messages like SMS MMS etc. as opposed to an IMAP4 Inbox which would be under an IMAP4 service and is a representation of the Inbox on an IMAP4 email server.
Central Repository centralised and secure storage facility for application settings
OBEX Object exchange protocol, used to send objects such as vCards or files between devices via infrared or Bluetooth.
GMXML XML parser / generator for use with SMIL formatted messages.
UID Unique Identifier, a 32 bit number allocated from a registry owned by Symbian
IPC Inter Process Communication
-MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
+MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
MTM Registry A list of currently installed MTMs maintained by the message server.
TLS Transport Layer Security, provides encryption of a TCP/IP socket.
M-HTML Standard for including HTML in MIME email messages see http://www.ietf.org/rfc/rfc2557.txt
@@ -20297,1033 +15207,15 @@
Message Editor Application for creating or editing a message
Message Server Symbian OS Server that handles request to modify the Message Store
Message Store Store of messages and related information kept in the file system on a Symbian OS device.
-Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
-Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
+Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
+Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
Global Inbox A standard folder under the local service which is used to store incoming messages like SMS MMS etc. as opposed to an IMAP4 Inbox which would be under an IMAP4 service and is a representation of the Inbox on an IMAP4 email server.
Central Repository centralised and secure storage facility for application settings
OBEX Object exchange protocol, used to send objects such as vCards or files between devices via infrared or Bluetooth.
GMXML XML parser / generator for use with SMIL formatted messages.
UID Unique Identifier, a 32 bit number allocated from a registry owned by Symbian
IPC Inter Process Communication
-MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
-MTM Registry A list of currently installed MTMs maintained by the message server.
-TLS Transport Layer Security, provides encryption of a TCP/IP socket.
-M-HTML Standard for including HTML in MIME email messages see http://www.ietf.org/rfc/rfc2557.txt
-MIME Specification for the format of email message bodies see http://www.ietf.org/rfc/rfc1341.txt
-RFC2822 The standard format for internet mail messages see http://www.ietf.org/rfc/rfc0822.txt
-SMTP Simple Mail Transport Protocol
-SID Secure Identification
-IMAP4 Internet Mail Access Protocol
-POP3 Post Office Protocol Version 3
-NBS Narrow Band Socket, in the messaging context this refers to the socket that is used to talk to the SMS stack for receiving and sending SMS messages
-SMS Short Message Service
-MMS Multimedia Message Service
-WAP Wireless Application Protocol
-WSP WAP Session Protocol
-HTTP Hypertext transfer protocol
-PDU Protocol Data Unit. This is the encoded form of SMS and MMS messages.
-Versit A consortium that defined standard formats for things like contacts (vCard) and calendar entries (vCals)
-SDP Service Discovery Protocol. A Bluetooth protocol that allows an applications to discover which services are available and to determine the characteristics of the services.
-SMIL Synchronized Multimedia Integration Language. Presentation language that is commonly used to define the contents of an MMS message.
-XML Extensible Mark-up Language
-DOM Document Object Model
-DTD Document Type Definition, a schema that defines the structure of an XML document.
-ESTORE Symbian OS component that provides stream based storage. Messaging uses the Permanent file store provided by ESTORE to store its index entries.
-Appendix A - Example Sequence Diagrams
-A.1 Copy to a Remote Service
-
-Figure 33 Sequence Diagram Showing Copying to a Remote Service
-Figure 33 shows a client copying a message to a remote service using the Messaging Client API. The message server then delegates the copy to the SMTP Server MTM. The Server MTM interprets the request as a request to send the message so it opens a connection to a remote SMTP server and sends the message. While the message is being sent the client can retrieve progress information from the CMsvOperation object that was returned by CMsvEntry::CopyL. The dark grey IPC line represents the split between the objects running in the client’s process space on the left and the message server’s process on the right.
-There are four basic steps:
-1. The client opens session with Message Server and creates a CMsvEntry set on the global outbox,
-2. The client then requests an asynchronous copy from the outbox to the SMTP service, a CMsvOperation object is returned. The message server loads the SMTP Server MTM and delegates the copy operation to it.
-3. The client requests progress from the CMsvOperation object, this request is passed through to the SMTP Server MTM. The client may repeat this step multiple times.
-4. The Server MTM finishes sending message. It moves the message to sent folder and completes the message server’s request. The message server completes the CMsvOperation object, which requests the final progress from the message server. The server returns the final progress and deletes the Server MTM. The CMsvOperation then completes the client’s original request.
-This diagram hides all of the internal working of the SMTP Server MTM, for information on this see below.
-A.2 SMTP Session
-
-Figure 34 Sequence Diagram Showing a SMTP Session
-Figure 34 shows the operation of the SMTP Server MTM after a request has come from the message server to copy a message to the SMTP service.
-1. SMTP Server MTM gets the request from the message server, it will build a selection of messages consisting of the union of the selection of messages passed in and the messages in the outbox that are associated with this SMTP service and are ready to be sent. The chain of classes are constructed, and a request is passed to networking to connect to the remote SMTP server, details of the server name and port are retrieved from the settings stored in the SMTP service entry.
-2. The component waits for the SMTP server to respond with a greeting indicating it is willing to talk, then sends EHLO to the server and waits for the response detailing the capabilities of the Server. After this step there could set steps to start using TLS and or SMTP AUTH depending on the SMTP settings.
-3. CImSmtpSession calls back into CMsgOutboxSend to retrieve the next message to be sent, then constructs a CImSmtpFile object to handle sending, for details on the sending see SMTP Email Send. When sending the email has completed the CImSmtpFile object is deleted.
-4. CImSmtpSession calls back into CMsgOutboxSend to retrieve the next message which returns saying there are no more messages. CImSmtpSession sends QUIT to the SMTP server and completes CMsgOutboxSend. CMsgOutboxSend deletes CImSmtpSession which tears down the connection to the SMTP server; it then completes the SMTP Server MTM. The Server MTM will then complete the message server and be deleted.
-A.3 SMTP Email Send
-
-Figure 35 Sequence Diagram Showing SMTP Transactions during Email Send.
-Figure 35 shows a CImSmtpFile object sending an email message to an SMTP server.
-1. Construct a CImSendMessage object, part of the imut component. Reset the SMTP Server
-2. Read address information from the CImHeader object stored in the message store, send address information to SMTP server.
-3. Use CImSendMessage object to read the message from the message store and generate RFC2822 message line by line. Send each line to the server as it is generated.
-4. Complete and send the message by sending a full stop to the SMTP server
-
-
-
-
-Messaging Symbian OS v7.0s, v8.0, v8.1, v9.0, v9.1 Architectural Description
-
-Status: Issued
-Team/Department : Messaging / Content & Messaging
-
-Contents
-1 INTRODUCTION 6
-1.1 PURPOSE AND SCOPE 6
-2 SUBSYSTEM OVERVIEW AND BACKGROUND 6
-3 MESSAGING ARCHITECTURE AND APIS 7
-3.1 SUBSYSTEM COMPONENTS 7
-3.1.1 Framework components 7
-3.1.1.1 Message Server and MTM architecture 7
-3.1.1.2 Schedule Send 7
-3.1.1.3 SendAs Version 1 7
-3.1.1.4 SendAs Version 2 7
-3.1.1.5 Watcher Framework 8
-3.1.1.6 Message URL Handler 8
-3.1.1.7 Bio Message Framework 8
-3.1.2 Plug-ins 8
-3.1.2.1 SMS 8
-3.1.2.2 CDMA SMS 8
-3.1.2.3 Email 9
-3.1.2.4 OBEX 9
-3.1.2.5 MMS 9
-3.1.2.6 GMXML 10
-3.1.2.7 Bio Message Plug-ins 10
-3.1.2.8 PCMTM 10
-3.1.2.9 Fax 10
-3.2 GENERAL DESCRIPTION 11
-3.2.1 Messaging / Message Server and MTM Architecture APIs 11
-3.2.1.1 Key Internal Relationships and Dependencies 11
-3.2.1.2 Key External Relationships and Dependencies 12
-3.2.1.3 API Purpose - Further Elaboration 13
-3.2.1.3.1 Message Store 13
-3.2.1.3.2 Data File Storage (pre - v9.0) 15
-3.2.1.3.3 Platform Security Compliant Message Store 16
-3.2.1.3.4 How message centres display the message store 17
-3.2.1.3.5 Message Type Module Architecture 19
-3.2.1.3.6 Message Server Client API 21
-3.2.2 Messaging / Send As APIs 22
-3.2.2.1 Key Relationships and Dependencies 22
-3.2.2.2 API Purpose - Further Elaboration 22
-3.2.2.2.1 SendAs API (pre – v9.0) 22
-3.2.3 Platform Security Compliant SendAs Server (v9.0 onwards) 23
-3.2.4 Messaging / Schedule Send APIs 24
-3.2.4.1 Key Relationships and Dependencies 24
-3.2.4.2 API Purpose - Further Elaboration 24
-3.2.4.2.1 Schedule Send 24
-3.2.5 Messaging / Watchers APIs 25
-3.2.5.1 Key Relationships and Dependencies 25
-3.2.5.2 API Purpose - Further Elaboration 25
-3.2.6 Messaging / Message URL Handler APIs 26
-3.2.6.1 Key Relationships and Dependencies 26
-3.2.6.2 API Purpose - Further Elaboration 26
-3.2.6.2.1 Message URL Handler Application 26
-3.2.6.2.2 Message URL Recognisers 27
-3.2.7 Messaging / SMS APIs 27
-3.2.7.1 Key Internal Relationships and Dependencies 27
-3.2.7.2 Key External Relationships and Dependencies 28
-3.2.7.3 API Purpose - Further Elaboration 28
-3.2.7.3.1 SMS Watchers 28
-3.2.7.3.2 SMS Client MTM 29
-3.2.7.3.3 SMS Utilities 29
-3.2.7.3.4 SMS Server MTM 30
-3.2.8 Messaging / CDMA SMS APIs 31
-3.2.8.1 Key Internal Relationships and Dependencies 31
-3.2.8.2 Key External Relationships and Dependencies 32
-3.2.8.3 API Purpose - Further Elaboration 32
-3.2.8.3.1 CDMA SMS Watchers 32
-3.2.8.3.2 CDMA SMS Client MTM 33
-3.2.8.3.3 CDMA SMS Utilities 33
-3.2.8.3.4 CDMA SMS Server MTM 33
-3.2.8.3.5 Configuration for using CDMA SMS MTM 34
-3.2.9 Messaging / Email APIs 35
-3.2.9.1 Key Internal Relationships and Dependencies 35
-3.2.9.2 Key External Relationships and Dependencies 36
-3.2.9.3 API Purpose - Further Elaboration 36
-3.2.9.3.1 Email Overview 36
-3.2.9.3.2 Email Client Utilities 37
-3.2.9.3.3 Email Server MTM Utilities 37
-3.2.9.3.4 POP3 MTMs 37
-3.2.9.3.5 IMAP4 MTMs 38
-3.2.9.3.6 SMTP MTMs 40
-3.2.9.3.7 Autosend 40
-3.2.10 Messaging / MMS APIs 40
-3.2.10.1 Key Internal Relationships and Dependencies 41
-3.2.10.2 API Purpose - Further Elaboration 41
-3.2.10.2.1 MMS Overview 41
-3.2.10.2.2 MMS Utilities 42
-3.2.10.2.3 MMS Watcher 43
-3.2.10.2.4 MMS Client MTM 43
-3.2.10.2.5 MMS Server MTM 44
-3.2.10.2.6 MMS Codec 45
-3.2.11 Messaging / BIO APIs 46
-3.2.11.1 Key Internal Relationships and Dependencies 46
-3.2.11.2 API Purpose - Further Elaboration 47
-3.2.11.2.1 BIO Overview 47
-3.2.11.2.2 BIO MTM 47
-3.2.11.2.3 BIO Database 48
-3.2.11.2.4 BIO Parsers 48
-3.2.11.2.5 BIF Files and Utilities 48
-3.2.11.2.6 Platform Security Compliant Messaging / BIO APIs 49
-3.2.12 Messaging / OBEX MTM APIs 50
-3.2.12.1 Key Internal Relationships and Dependencies 50
-3.2.12.2 OBEX MTM Overview 50
-3.2.12.2.1 OBEX MTM 50
-3.2.12.2.2 IR MTM 51
-3.2.12.2.3 Bluetooth MTM 51
-3.2.12.2.4 OBEX MTM Utils 52
-3.2.12.2.5 Platform Security Compliant Messaging / OBEX MTM APIs 52
-3.2.13 Messaging / GMXML APIs 52
-3.2.13.1 Key Relationships and Dependencies 52
-3.2.13.2 Overview 53
-3.2.13.2.1 GMXML DOM 53
-3.2.13.2.2 GMXML Parser and Composer 53
-3.2.13.2.3 GMXML SMIL DTD (Validator) 53
-4 SECURITY 54
-4.1 DATA CAGING 54
-4.2 BACKUP AND RESTORE 54
-4.3 CAPABILITY RANGES 54
-4.3.1 Capabilities granted to executables 54
-4.3.2 Capabilities granted to DLLs 55
-4.3.3 Capabilities required to use the subsystem 57
-5 FURTHER INFORMATION 59
-5.1 REFERENCES 59
-5.2 OPEN ISSUES 59
-5.3 GLOSSARY 60
-APPENDIX A - EXAMPLE SEQUENCE DIAGRAMS 62
-A.1 COPY TO A REMOTE SERVICE 62
-A.2 SMTP SESSION 64
-A.3 SMTP EMAIL SEND 66
-
-Table of Figures
-Figure 1 Where Messaging Lives 6
-Figure 2 MTM Relationships 11
-Figure 3 External Dependencies 12
-Figure 4 Message Store 13
-Figure 5 Series 60 Inbox List View 14
-Figure 6 Remote and Local Entries 14
-Figure 7 Email Message 15
-Figure 8 Series 60 Message Centre (Composed from 2 screen shots) 17
-Figure 9 UIQ Message Centre 18
-Figure 10 Messaging MTM Structure (light coloured components are part of messaging subsystem) 19
-Figure 11 Nokia 9210 Outbox List View 20
-Figure 12 SendAs Version 1 Dependencies 22
-Figure 13 SendAs Version 2 Dependencies 23
-Figure 14 Schedule Send Dependencies 24
-Figure 15 Watcher Dependencies 25
-Figure 16 Message URL Handler Dependencies 26
-Figure 17 SMS Internal Dependencies 27
-Figure 18 SMS External Dependencies 28
-Figure 19 CMDA SMS Internal Dependencies 31
-Figure 20 CDMA SMS External Dependencies 32
-Figure 19 Email Internal Dependencies 35
-Figure 20 Email External Dependencies 36
-Figure 21 MMS Internal Dependencies 41
-Figure 22 MMS Utilities External Dependencies 42
-Figure 23 MMS Watcher External Dependencies 43
-Figure 24 MMS Client MTM Dependencies 43
-Figure 25 MMS Server MTM Dependencies 44
-Figure 26 BIO Message Internal Dependencies 46
-Figure 27 Bio Parser External Dependencies 47
-Figure 26 BIO Message Dependencies (v9.0) 49
-Figure 28 OBEX Internal Dependencies 50
-Figure 29 OBEX External Dependencies 51
-Figure 30 IR MTM Dependencies 51
-Figure 31 Bluetooth MTM Dependencies 52
-Figure 32 GMXML Dependencies 52
-Figure 33 Sequence Diagram Showing Copying to a Remote Service 62
-Figure 34 Sequence Diagram Showing a SMTP Session 64
-Figure 35 Sequence Diagram Showing SMTP Transactions during Email Send. 66
-1 Introduction
-1.1 Purpose and Scope
-The Messaging Architectural Description details the architecture and APIs exposed by the Messaging Subsystem. This document does not attempt to list all functionality provided by the messaging subsystem. For details on the functionality provided and the specifications implemented by the messaging subsystem see the Messaging Functional Description [R1]. This document describes the general architecture of messaging subsystem. Information related to a particular release version is mentioned with relevant release number.
-2 Subsystem Overview and Background
-The Messaging Subsystem provides an application level API to handle the storage and transport of different message types. It sits between messaging applications and the lower level subsystems which messaging uses for storage and transmission of messages.
-
-Figure 1 Where Messaging Lives
-The message types that messaging currently supports are Email (POP3, IMAP4 & SMTP), SMS, MMS and OBEX. The set of supported message types is extensible at run time by the use of plug-in modules that are responsible for the transmission and storage of a particular message type. This means that the set of components shown communicating with the network cloud depend on the message types installed.
-3 Messaging Architecture and APIs
-3.1 Subsystem components
-The Messaging subsystem components can be split into two categories: those components that form the framework and those that plug into the framework to support specific message types. This section briefly describes each of the components, more detailed descriptions of the components and their dependencies can be found in later sections of this document.
-3.1.1 Framework components
-3.1.1.1 Message Server and MTM architecture
-The message server is the core component in the messaging subsystem. It provides the message store used to contain messages. The Message Type Module architecture also allows plug-ins to add support for new message types to the messaging subsystem.
-Component Description
-messaging\framework\serverexe Executable that links to the server component and starts the message server
-messaging\framework\server Contains classes that make up both the client and server side of the message server API.
-messaging\framework\mtmbase Base classes for the plug-ins that handle the various message types
-3.1.1.2 Schedule Send
-The Schedule Send component is an extension to the framework that provides support for scheduling of operations such as sending messages. Message type modules that wish to support this functionality can use these support components to implement scheduling. For example the SMS MTM uses this to allow scheduled sending of SMS messages.
-Component Description
-messaging\schedulesend\schedulesendmtm Base classes that handle functionality for message server plug-ins that wish to enable scheduling of sending messages.
-messaging\schedulesend\schedulesendexe Executable use to provide schedule send behaviour.
-3.1.1.3 SendAs Version 1
-This version of SendAs is supported in releases pre - v9.0. SendAs provides a high level API for applications that wish to include a “Send As” menu to allow users to send content via one of the message types supported by messaging. The application using the API does not have to be aware of the message type selected by the user. Note the API does not send the messages.
-Component Description
-messaging\sendas High level API to allow creation of messages.
-3.1.1.4 SendAs Version 2
-From v9.0 and onwards the SendAs has been replaced with client server architecture based SendAs server. The client server architecture enhances secured platform implementation. The SendAs server polices the client application. If it is not trusted with required capabilities the SendAs server will refuse the client access. The client MTM for the message type can send a message with user permission even if the client does not have the correct capabilities.
-Component Description
-messaging\sendAsV2 High level API to allow the creation and sending of messages
-
-3.1.1.5 Watcher Framework
-The watcher framework is a lightweight framework to allow plug-ins to wait on events. For example there is an SMS watcher that waits for incoming SMS messages and delivers them to the message store. The watcher framework will only load plug-ins from ROM.
-Component Description
-messaging\framework\watcher Executable that loads and runs watcher plug-ins.
-3.1.1.6 Message URL Handler
-Support for recognising messaging URLs (mailto:, sms:, fax:, mms:), and then launching an editor with a new message.
-Component Description
-messaging\urlhandler\urlhandler An application that parses the URLs and then creates a correctly addressed message and launches a message editor.
-messaging\urlhandler\recogniser Recognisers that map from the URL schemes to the mime types.
-3.1.1.7 Bio Message Framework
-The Bio Message Framework provides a framework that supports plug-ins to handle messages like vCards and Internet access point set-up messages.
-Component Description
-messaging\biomsg\BDB\BIODB Classes to maintain the database of bio registration files.
-messaging\biomsg\BIFU\BIFU Classes for reading and writing bio registration files
-messaging\biomsg\BIOC\BIOC Bio message client MTM, this is in the framework section as it forms part of the bio messaging framework it is also a plug-in to the messaging framework.
-messaging\biomsg\BIOS\BIOS Bio message server MTM, this is in the framework section as it forms part of the bio messaging framework it is also a plug-in to the messaging framework.
-3.1.2 Plug-ins
-3.1.2.1 SMS
-The SMS plug-ins provide application level support for the Short Message Service messages.
-Component Description
-messaging\biomsg\BioWatchers Plug-ins to the watcher framework to listen for SMS, WSP, and WDP messages and deliver them to the global inbox in the message store.
-messaging\sms\clientmtm A plug-in to the message server framework to provide a generic API for creation of SMS messages (SMS Client MTM & SMS utilities)
-messaging\sms\servermtm A plug-in to the message server framework to provide a generic API for sending of SMS messages (SMS Server MTM)
-3.1.2.2 CDMA SMS
-The CDMA SMS plug-ins provide application level support for the CDMA Short Message Service messages.
-Component Description
-messaging\biomsg\BioWatchersCdma Plug-ins to the watcher framework to listen for CDMA SMS messages and deliver them to the global inbox in the message store.
-messaging\sms\multimode\clientmtm A plug-in to the message server framework to provide a generic API for creation of CDMA SMS messages (CDMA SMS Client MTM)
-messaging\sms\multimode\servermtm A plug-in to the message server framework to provide a generic API for sending of CDMA SMS messages (CDMA SMS Server MTM)
-
-3.1.2.3 Email
-The email plug-ins provide support the POP3, IMAP4 and SMTP email protocols and support for parsing and generating plain test, MIME and M-HTML format email messages.
-Component Description
-messaging\email\clientmtms A plug-in to the message server framework to provide a generic API for creation of email messages (IMAP4 SMTP and POP3 Client MTMs & email utilities)
-messaging\email\imapservermtm A plug-in to the message server framework to provide a generic API for access to a remote IMAP4 server (IMAP4 Server MTM)
-messaging\email\smtpservermtm A plug-in to the message server framework to provide a generic API for access to a remote SMTP server (SMTP Server MTM)
-messaging\email\popservermtm A plug-in to the message server framework to provide generic API for access to remote POP3 server (POP3 Server MTM)
-messaging\email\servermtmutils Email utilities for parsing plain text and MIME email messages. It also provides an abstraction of the TCP/IP sockets for use by the SMTP POP3 and IMAP4 plug-ins.
-messaging\email\autosend An executable that requests SMTP Server MTM to send messages in the outbox. This is used to provide send on next connection functionality and is started by the POP3 and IMAP4 Client MTMs.
-3.1.2.4 OBEX
-The OBEX MTM is a set of plug-ins to the message server that provides support for IR and Bluetooth beaming.
-Component Description
-messaging\obex\btmtm\btclient\group\btcmtm Bluetooth Client MTM
-messaging\obex\btmtm\btserver\group\btsmtm Bluetooth Server MTM
-messaging\obex\irmtm\irclient\group\ircmtm IR Client MTM
-messaging\obex\irmtm\irserver\group\IRSMTM IR Server MTM
-messaging\obex\obexmtm\obexclient\group\obexClientMtm OBEX Client MTM, base classes for the Bluetooth and IR Client MTMs
-messaging\obex\obexmtm\obexserver\group\obexServerMtm OBEX Server MTM, base classes for the Bluetooth and IR Server MTMs
-messaging\obex\obexmtm\obexutil\group\obexMtmUtil OBEX MTM utilities
-3.1.2.5 MMS
-The MMS MTM is a plug-in to the message server that provides support for MMS messages. From v9.0 and onwards MMS MTM and related components are removed.
-Component Description
-messaging\mms\utils MMS Utilities
-messaging\mms\servermtm MMS Server MTM
-messaging\mms\mmswatcherplugins MMS plug-ins to WAP push framework to handle reception of MMS notifications
-messaging\mms\codec MMS utilities for handling MMS codecs
-messaging\mms\clientmtm MMS Client MTM
-3.1.2.6 GMXML
-GMXML is a parser/generator for SMIL presentations for MMS messages.
-Component Description
-messaging\GMXML\XMLParser XML parser designed for parsing of SMIL messages
-messaging\GMXML\XMLDom XML document object model designed for parsing of SMIL messages
-messaging\GMXML\SMILdtd SMIL DTD
-3.1.2.7 Bio Message Plug-ins
-These parsers plug into the bio messaging framework to handle specific types of bio message.
-Component Description
-messaging\biomsg\cbcp\CBCP Compact business card parser
-messaging\biomsg\enp\ENP Email notification parser
-messaging\biomsg\gfp\gfp General file parser
-messaging\biomsg\iacp\IACP Nokia Smart Message Internet Access Parser
-messaging\biomsg\wapp\wapp Nokia/Ericsson OTA Parser
-3.1.2.8 PCMTM
-Plug-in to the message server that provided email synchronisation with a PC. This component has been deprecated in 8.0a and will not been documented in the API section below.
-3.1.2.9 Fax
-Plug-in to the message server that provides fax support. This component has been deprecated in 8.0a and will not been documented in the API section below.
-
-3.2 General Description
-3.2.1 Messaging / Message Server and MTM Architecture APIs
-3.2.1.1 Key Internal Relationships and Dependencies
-
-Figure 2 MTM Relationships
-Figure 2 shows the relationship between the Message Server and the MTM plug-ins. The grey classes are realisations of the MTM interfaces defined by the messaging framework. The message server depends on the Server MTM interface. Messaging Clients depend on the Client, UI and UI Data MTM interfaces and the Message Server Client API.
-3.2.1.2 Key External Relationships and Dependencies
-
-Figure 3 External Dependencies
-The grey package representing the messaging client depends on the Client, UI and UI Data interfaces and the Messaging Client API. The message server then depends on:
-• Charconv – Provides character set conversion routines, used to convert encoded message body text to Unicode body text.
-• EStore – Provides API to handle a stream based store used for the messaging index file and the framework classes for the message store files. (omitted from other dependency diagrams as it is implied by the dependency on the message server)
-• F32 – Provides the file server APIs used to access the file system directories in which messaging stores files containing message data. (omitted from other dependency diagrams)
-• BAFL – Provides API to load the correct messaging resource file dependent on the current language and to register the message store index file with the backup server. (omitted from other dependency diagrams)
-• ETEXT – Rich text APIs used to store body text of messages, this rich text format is a Symbian Proprietary format. (omitted from other dependency diagrams)
-• EUSER – Core Symbian OS utilities such as descriptors, arrays, client / server framework, cleanup stack and others (omitted from this and other dependency diagrams).
-• Central Repository – Centralised and secure storage facility for application settings, the message server stores message settings data in the central repository (from v9.0 and onwards).
-Note that debug only dependencies such as the flogger have been omitted from dependency diagrams.
-3.2.1.3 API Purpose - Further Elaboration
-3.2.1.3.1 Message Store
-The message server provides persistent storage of messages and messaging account settings. It does this by providing a message store consisting of a tree of message entries. Multiple clients can access the message store simultaneously. Each entry in the tree can represent an email account, folder of messages, message part, etc.
-
-Figure 4 Message Store
-Figure 4 shows an example message store. The tree is broken down in to three levels:
-1. The Root entry. This entry is just present to tie the tree structure together
-2. Service entries. There is one local service under which local folders and messages are stored, and zero or more remote services. Remote services represent message accounts.
-3. Message & Folder entries. Messages and folders, under the local service represent messages stored on the device. Messages and folders under remote services represent a local copy of messages that are present on a remote server. For example under a POP3 email service you would have copies of all the messages present on the POP3 email server, or under an SMS service you might find SMS messages that are stored on a SIM.
-The message server controls access to the entries in the store. It enforces the three levels therefore attempts to create message or folder entries directly under the root entry will fail.
-The message server provides three types of storage for each entry in the message store:
-• Index entry - TMsvEntry - intended to provide enough information for UI to display list views as shown in Figure 5. This consists of two strings and various flags (read, complete, has attachments etc).
-• Stream based file store - CMsvStore – provides storage of streams of data associated with UIDs. A standard UID is defined for storing body text. Other UIDs are specific. For example the email MTMs define a UID for storage of MIME headers. Compared to the index entry information this is used to store larger objects and is extensible, at the cost of being slower to access. From v9.0 and onwards CMsvStore provides an Attachment API for managing attachments. The Attachment API should be used as attachments can no longer be accessed directly due to Platform Security.
-• Directory of files – normally used for attachments.
-The only storage type that is always present is the index entry. The stream store and the directory of files are optional.
-
-Figure 5 Series 60 Inbox List View
-
-Figure 6 Remote and Local Entries
-As shown in Figure 6 the message store is split into two sets of entries:
-• Remote entries - entries that are representations of entries stored on a remote store .
-• Local entries - entries not linked to a remote store.
-The message server handles changes to local entries; internally it hands off changes to remote entries to the Server MTM that owns that service. Examples of operations that are handed off to Server MTMs are operations involving copying and moving messages to and from a remote service. See section 3.2.1.3.5 or more information on Server MTMs.
-Each entry within the store has a type:
-Folder – Messages can be grouped into folders. Standard folders such as inbox / outbox and user created folders.
-Message – Storage of the content of a message. Message entries can have child entries used to represent the structure of a message.
-Attachment – These represent attachments under a message entry.
-Root & Local Service Entry – There tie the tree structure together. However the Stream store associated with the root entry is sometimes used by UIs to store preferences e.g. default folder views etc.
-Remote Service - Represents a source and / or destination for messages. They are used to store the settings associated with the source / destination.
-Message Type Specific - MTMs can create other message types for use as child entries to messages they own. For example email uses a tree structure, with a message entry as the root, to represent the MIME structure of an email message; it uses folder entries to represent MIME folders and adds new types for entries representing the html body and text body parts of a message. This is shown in Figure 7.
-
-Figure 7 Email Message
-Using the message store to represent message structure allows reuse of the tree structure and makes it very simple to represent one message embedded in another. However this representation introduces performance issues as it results in each message having multiple files associated with it. The message server also keeps all index entries in memory; therefore this representation increases the memory footprint of the message server. Therefore when designing new MTMs we should think about moving away using multiple index entries to store one message in the message store.
-A default message store is created if the message server starts and no message store is present or a corrupt message store is present. The server will initially create a store with just a root entry, and then the server will create any standard folders defined in the resource file msgs.rsc. Finally the server will check whether an executable ‘mailinit.exe’ is present on the system, if it is present the server will launch the executable to allow customisation of the message store. The behaviour of ‘mailinit.exe’ is defined by the UI family of the device. However the typical behaviour is to load each of the UI Message Type Modules and allow each to perform any message type specific initialisation. For example the SMS plug-in typically creates a default service entry.
-
-3.2.1.3.2 Data File Storage (pre - v9.0)
-This section describes the files used by the message server before release v9.0. For information on the files used for release from v9.0 and onwards see section [3.2.1.3.3.1].
-Filename Access Purpose
-?:\system\Mail\index Private Message server index file, internal to message server
-?:\system\Mail\<8 hex digits> Shared via API Message server store files for services, clients access these via a messaging API.
-?:\system\Mail\<8 hex digits>.new Shared via API Temporary file used during committing message server store files.
-?:\SYSTEM\MAIL\<8 HEX DIGITS>_F\* Shared Files associated with a messaging service. These may be accessed directly by clients.
-?:\system\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits> Shared via API Message server store files for message entries, clients access these via a messaging API.
-?:\system\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits>.new Shared via API Temporary file used whilst committing message server store files.
-?:\system\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits>_F\* Shared Files associated with a message entry. These are accessed directly by clients.
-c:\system\data\msgs.ini Private Stores the drive containing the last used message store
-c:\system\Mtm\Mtm Registry v2 Private Cache of registered MTMs, internal to message server
-C:\system\data\sms_settings.dat Shared Copy of the SMS settings.
-?:\System\Mail\StoreInit.tmp Shared Created when message server runs ‘mailinit.exe’, ‘mailinit.exe’ should delete the file when it has successfully completed.
-?:\System\Mail\storedeleted.tmp Shared Created when message server finds and deletes a corrupt message store. Allows the UI to inform the user about the fact that the message store was corrupt.
-Files that are shown as private should only be accessed by the message server or by connectivity process for backup and restore purposes. Files listed as shared are accessed directly by messaging clients. Files listed as shared via API are accessed by client process but only via messaging APIs.
-3.2.1.3.3 Platform Security Compliant Message Store
-From v9.0 and onwards the message store is stored in the message server's data cage and the settings data are placed in the Central Repository. Access to the message store is only possible via message server APIs and not directly through file access. This leads to secured data storage and secured platform.
-3.2.1.3.3.1 Data caging
-Filename Purpose
-?:\private\<SID>\Mail\index Message server index file, internal to message server
-?:\ private\<SID>\Mail\<8 hex digits> Message server store files for services, clients access these via a messaging API.
-?:\ private\<SID>\Mail\<8 hex digits>.new Temporary file used during committing message server store files.
-?:\ private\<SID>\Mail\<8 hex digits>_F\* Files associated with a messaging service. These may be accessed directly by clients.
-?:\ private\<SID>\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits> Message server store files for message entries, clients access these via a messaging API.
-?:\ private\<SID>\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits>.new Temporary file used whilst committing message server store files.
-?:\ private\<SID>\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits>_F\* Files associated with a message entry. These are accessed directly by clients.
-c:\ private\<SID>\data\msgs.ini Stores the drive containing the last used message store
-c:\ private\<SID>\Mtm\Mtm Registry v2 Cache of registered MTMs, internal to message server
-?:\ private\<SID>\Mail\StoreInit.tmp Access via IPC call
-?:\ private\<SID>\Mail\storedeleted.tmp Created when message server finds and deletes a corrupt message store. Allows the UI to inform the user about the fact that the message store was corrupt.
-?\resource\messaging\bif\*.bif Registration data field with UID used in BIO framework
-
-3.2.1.3.4 How message centres display the message store
-The UI normally provides a Message Centre application to display the structure of the message store to the user. Different UIs map the structure to different views.
-
-Figure 8 Series 60 Message Centre (Composed from 2 screen shots)
-Figure 8 shows the top level view of the message centre application on a Series 60 phone. This shows that the message centre has hidden the local service and shows the standard folders at the same level as the services. Also the SMTP, SMS and MMS services are marked as hidden entries in the message store, and so do not appear in the message application.
-
-Figure 9 UIQ Message Centre
-However Figure 9 shows that the UIQ message centre has no 1-1 mapping from the structure in the message store to the structure shown to the user. Each of the message types is displayed as if its messages were contained in separate folders. Under each of these folders the user is presented with an inbox, outbox, send and drafts folder. This filtering is done in the UI layer as this functionality is not provided by the messaging API.
-3.2.1.3.5 Message Type Module Architecture
-
-Figure 10 Messaging MTM Structure (light coloured components are part of messaging subsystem)
-The MTM architecture is the plug-in scheme provided by the messaging framework to integrate different message transports into the message server. The plug-in scheme consists of four interfaces, the UI MTM, UI Data MTM, Client MTM and Server MTM. The messaging client applications loads and uses the first three which are loaded within the client’s process space. The final one the Server MTM is loaded within the message server process. The APIs for the client facing interfaces are extensible via run time type information provided by the QueryCapability API, and the InvokeAsyncFunction and InvokeSyncFunction APIs.
-3.2.1.3.5.1 UI MTM
-Handles requests from clients to view and edit messages or service settings. The MTM handles interaction with the message centre and as such the exact meaning of the APIs is defined by the UI. However common meanings are:
-• Create – Launches the editor with a new message.
-• Edit – If entry is a message this launches the editor; if entry is a service it edits the settings.
-• View – Launches the message viewer.
-• Display progress of an operation.
-3.2.1.3.5.2 UI data MTM
-This MTM provides fast access to UI components such as menu resources and bitmaps required by message centre for list views etc. Again the exact semantics are UI specific.
-There is a resource file defining UI specific functions, for example the Series 60 Messaging UI checks if the resource file contains text to display in the “New Message” menu.
-The UI data MTM also provides mapping from the message store’s TMsvEntry structure to Icons for the messaging list views and a status string, for example in the case of Nokia 9210 it is used in the outbox view to provide strings like “Resend 01:07” as shown in Figure 11. The class also provides functions to determine what operations are possible with a given entry. Examples of this are APIs that return whether the UI should allow the user to reply to the entry or to delete a service entry. The UI then uses this information to determine which menu options / short-cut keys should be allowed when the user selects a given entry.
-
-Figure 11 Nokia 9210 Outbox List View
-3.2.1.3.5.3 Client MTM
-Provides methods to create / reply and forward messages. Functions the Client MTMs provide are:
-• Create Message.
-• Reply to a Message.
-• Forward a Message.
-• Add / remove Addressees.
-• Add / remove body text.
-• Add / remove subject.
-• Add / remove attachments (the API cannot list attachments).
-The Client MTM interface is used by SendAs to provide a way of creating messages independently of the message type.
-3.2.1.3.5.4 Server MTM
-This is the final interface that makes up an MTM plug-in; it differs from the other three plug-ins in that it is loaded into the message server’s process space. The Server MTM provides access to messages under remote services. It handles connecting to remote servers to handle updating the local cache of these messages or to send messages copied to remote services when messages are copied to a remote service. The message server loads and hands off all message store operations that involve entries under a remote entry, these are the entries on the left-hand side of Figure 6.
-Functions that a Server MTM must implement:
-• Copy/MoveToLocal – called when the message server is asked to move or copy an entry that is currently under a remote service. A Server MTM might map this to retrieving a message from a remote mailbox.
-• Copy/MoveFromLocal – called when the message server is asked to move or copy from under the local service to a destination under a remote service. A Server MTM should map this to sending a message if the MTM supports sending.
-• Create, Delete, Change – called when the message server is asked to perform these operations on entries under a remote service.
-• StartCommand – this API provides a means of extending the API the Server MTM provides. Messaging clients pass a command ID and a selection of entries via the message server to the Server MTM. Examples of commands that Server MTMs might provide are: connect and synchronise the entries under a remote service with the messages on an email server, list SMS messages present on the phones SIM. These commands are MTM specific and therefore clients have to know which MTMs support which commands.
-3.2.1.3.5.5 MTM Registration
-MTMs must be registered with the message server so that clients can query what MTMs are present and the server knows which DLL to load to create a given MTM component. MTMs are registered by providing a resource file containing the MTMs UIDs, human readable name, and for each MTM interface it lists a DLL and the ordinal at which the constructor for that interface exists. The message server will search the ROM drive for MTM registration resource files on start-up and it will automatically register any MTMs found. For registration of MTMs installed on other drives, the message server provides an API to register and de-register an MTM. Registration will persist across a reboot, so an MTM only needs to be registered when it is installed on the system.
-When MTMs are registered or unregistered the message server will send events to all messaging clients with a message server session open.
-3.2.1.3.6 Message Server Client API
-The Messaging Server Client API breaks down into two categories: APIs for manipulation of the message store and utility APIs.
-3.2.1.3.6.1 Message Store manipulation APIs
-Requests from clients to modify the message store fall into three categories:
-1. Operations performed entirely with local entries (entries on the right-hand side of Figure 6) for example requests to create entries in the inbox, delete an entry from the drafts folder etc. The message server handles these operations directly.
-2. Operations that involve a remote entry (entries on the left-hand side of Figure 6) for example requests to delete an entry under a POP3 service, or copy a message to an SMTP service. The message server hands these operations off to the Server MTM that owns the service under which the remote entry is stored. The only exception to this rule is the ChangeAttributes API call. This modifies flags on an index entry and is handled by the message server for both local and remote entries. This means that a Server MTM can not rely on being called when flags like the Unread flag are changed. Note that operations can not involve two remote entries; therefore requests to copy entries between a remote service representing one POP3 account to a remote service representing another POP3 account will fail with an error.
-3. Requests that are explicitly directed at a Server MTM via the TransferCommand API. These commands are just passed to the correct Server MTM by looking up the Service ID and MTM of the first message in the selection passed into the command.
-The message server sends events when entries in the message store are modified to messaging clients that have a session open with the server.
-Where the API provides asynchronous functions to modify the message store or transfer a command to a Server MTM, the functions will return a message server operation object. This object can be used to request progress on operation or cancel the operation. Deleting the operation object returned, or closing the session used to make the request will result in the operation being cancelled, therefore a messaging client must remain running until operations it has requested have either completed or they will be cancelled. See appendix A.1 for an example of an asynchronous copy operation. If a Server MTM operating on the same remote service is already handling an operation, the message server will queue the new operation to be handled when the Server MTM becomes free. Requests for progress of operations that are queued will fail with KErrNotReady. The fact that the queue is based on the remote service ID means that you can have two Server MTMs of the same type running at the same time as long as they are operating on different services. So for example you can have two separate POP3 MTMs running synchronising different remote services with email servers.
-3.2.1.3.6.2 Utility APIs
-1. Access to MTM registries – These allow clients to construct instances of the interfaces an MTM implements.
-2. Register / Unregister an MTM.
-3. Change Drive – The message server closes the current message store and opens one on the drive specified. If no message store is present on the drive specified a new message store is created. The message sever can have only one mail store open at a time, if the current mail store is not available because a the disk the mail store is on is not present then the message server will switch the mail store back to the C: drive if an attempt is made to create a message in the inbox.
-4. Launching Editors – This launches the correct editor for a message. It is implemented by delegating the request to the UI MTM
-3.2.2 Messaging / Send As APIs
-3.2.2.1 Key Relationships and Dependencies
-
-Figure 12 SendAs Version 1 Dependencies
-SendAs version 1 and only present in releases before v9.0. SendAs uses the Messaging Client API to access the registry of Client MTMs and construct the Client MTM interfaces. The Client MTMs are then used for composing the message. SendAs requires clients to implement the MSendAsObserver interface. This interface is responsible for checking the return value of the capability queries made to Client MTMs that require a response and also for rendering message types that require it. The only message type supplied by Symbian that requires rendering is Fax, however this MTM has been removed in 8.0a and future releases.
-3.2.2.2 API Purpose - Further Elaboration
-3.2.2.2.1 SendAs API (pre – v9.0)
-The SendAs API makes use of the Client MTM interface and the Messaging Client API to provide a generic API for creating messages. Note despite the name of this component SendAs does not provide an API to send the message.
-SendAs builds a list of registered MTMs, then queries each MTM to check whether it supports sending, removing those MTMs from the list that do not support sending. This list is then provided to the messaging client application. At this point the application can add more constraints on the list of MTMs; for example it can insist the MTM supports Attachments or more than a certain size of body text. SendAs queries each of the MTMs about the requirements and will drop any MTMs from the list that does not meet them. When the application has finished adding requirements it selects one of the MTMs left in the list and uses that to compose the message, adding addresses, a subject, body text and attachments.
-SendAs supports setting a BIO Type for the message that is composed. This tells the transport that the body text represents a BIO Message. This is used when sending business cards from the contacts application as SMS messages; the contacts application puts the vCard data in the body text of the message and the transport sends it correctly. If the MTM in question supports attachments then the vCard is attached to the message.
-A new CSendAs object must be created for each message the application wishes to create.
-3.2.3 Platform Security Compliant SendAs Server (v9.0 onwards)
-
-Figure 13 SendAs Version 2 Dependencies
-From v9.0 and onwards the CSendAs has been replaced by the SendAs server component. The new SendAs server controls the access to the message store. Some of the key SendAs Server features are listed as follows.
-• Send a message once the capability policing of the client application has been completed.
-• Allow client applications to launch an editor for a specified message type.
-• Allow client applications to query the message type.
-The main client-side API is the RSendAs class. The client applications use this to connect to the Send-As server. The session object on the server-side is an instance of CSendAsSession.
-Client applications create messages using the RSendAsMessage API. Opening an RSendAsMessage object on Send-As server session creates a CSendAsMessage object in the Send-As server. There is a one-to-one mapping between an RSendAsMessage object and a CSendAsMessage object. This allows client applications to create multiple messages concurrently.
-
-3.2.4 Messaging / Schedule Send APIs
-3.2.4.1 Key Relationships and Dependencies
-
-Figure 14 Schedule Send Dependencies
-The Schedule Send Server MTM base class depends on the task scheduler to launch the schedule send executable at the correct time. To send the message with a package of data previously passed into the task scheduler by the Server MTM. The schedule send executable then uses the Messaging Client API to actually perform the requested operation.
-3.2.4.2 API Purpose - Further Elaboration
-3.2.4.2.1 Schedule Send
-The Schedule Send functionality is delivered by four components:
-Server MTM Base Class – The base class provides support to Server MTMs that wish to support scheduled operations.
-Data Structures – These are classes used to represent the data associated with a scheduled operation.
-Executable – The executable is run by the task scheduler at the scheduled time.
-The Task Scheduler – This component is part of the system libraries subsystem. Currently the SMS and Fax Server MTMs support scheduled sending.
-Clients request the Server MTM schedules operations via additional commands passed to TransferCommand API; this is passed to the Server MTM via the message server. The Server MTM packages the operation ID, a selection of message IDs, how often to poll for progress and an MTM specific buffer. It then passes this package of data to the task scheduler requesting that it launches the schedule send executable at the correct time with the packaged information.
-When the task scheduler launches the schedule send executable, it unpacks the schedule information and uses the Messaging Client API to request the Server MTM to perform the operation.
-Schedule Send supports a retry mechanism if the operation fails. The Server MTM has a resource file containing a mapping from the error codes the operation can fail with and actions to be performed. For example the SMS resource file has a mapping such that if the operation fails with an error code indicating a bad phone number the SMS will be set to failed and left in the outbox. Whereas if it fails with a error code indicating temporary network failure the send operation will be scheduled to be resent later with a maximum of three retries.
-3.2.5 Messaging / Watchers APIs
-3.2.5.1 Key Relationships and Dependencies
-
-Figure 15 Watcher Dependencies
-The watcher executable’s dependency on the message server is the result of a performance measure. The watcher process creates a message server session before initialising each of the watcher plug-ins and closes the session when it has finished. This keeps the message server running during initialisation avoiding starting and stopping the message server if each watcher plug-in opens and closes sessions.
-3.2.5.2 API Purpose - Further Elaboration
-The watcher framework consists of an executable that is launched when the device boots. The component that is responsible for launching it depends on the UI family. When the watcher.exe is launched it will load each DLL in z:\system\libs\watchers which has a second UID as KWatcherUid and calls the first DLL entry point to construct a CActive object.
-From v9.0 and onwards watcher DLLs are found by scanning the directory \resource\messaging\watchers for registry files. These files contain the name of a watcher DLL that can be loaded from ROM i.e. z:\sys\bin.
-The framework has retry behaviour if the first entry point leaves, in this case the watcher framework will start a timer and try and construct the watcher object 10 seconds later. Five attempts are made before the watcher plug-in is assumed to have failed completely. Once the watcher framework has constructed all the watchers it starts the active scheduler which should never exit.
-Watcher plug-ins typically make a request to another subsystem such that they will be completed when an external event like a fax line ringing or an SMS being received occurs. When the watcher has completed processing the request it will wait for the next event.
-No support for starting / stopping watchers is provided. This is a limitation that makes watchers unsuitable for operations like listening for messages beamed via IR, as the watcher should only run while the IR port is active.
-3.2.6 Messaging / Message URL Handler APIs
-3.2.6.1 Key Relationships and Dependencies
-
-Figure 16 Message URL Handler Dependencies
-3.2.6.2 API Purpose - Further Elaboration
-The Message URL Handler provides support for creating messages and launching messaging editors from URLs such as mailto:infobot@example.com?subject=current-issue. Note there is no dependency between the Message URL Handler application which processes the URLs and the Message URL Handler recognisers which maps from URLs to mime types.
-3.2.6.2.1 Message URL Handler Application
-This is a Symbian OS application that registers with the application framework that it can handle the mime types: x-epoc-url/fax, x-epoc-url/mailto and x-epoc-url/sms. When launched with a URL it will parse the URL to retrieve the address and other header fields and then use the SendAs API to create a new message with the correct address, headers etc. The application then uses the APIs in the MturUtils class provide by the mtmbase component in the messaging framework to launch the correct editor for the given message type. The application is marked as hidden and therefore should not be listed by UIs in application browsers.
-3.2.6.2.2 Message URL Recognisers
-This is a plug-in to the recogniser framework it will be called when the application framework wishes to recognise a file. Recognisers are called with the file name, in this case a URL, and a buffer containing the start of the file. The message URL recogniser compares the start of the URL with the URL schemes it recognises, if it finds a URL scheme it knows about it maps it to a mime type. The recogniser ignores the buffer passed in.
-Schemes recognised:
-Scheme Mime type
-mailto: X-Epoc-Url/mailto
-fax: X-Epoc-Url/fax
-sms: X-Epoc-Url/sms
-mms: X-Epoc-Url/mms
-See the application framework architectural description for more information on recognisers [R2].
-3.2.7 Messaging / SMS APIs
-3.2.7.1 Key Internal Relationships and Dependencies
-
-Figure 17 SMS Internal Dependencies
-3.2.7.2 Key External Relationships and Dependencies
-
-Figure 18 SMS External Dependencies
-3.2.7.3 API Purpose - Further Elaboration
-3.2.7.3.1 SMS Watchers
-The SMS watchers are made up of two watchers, the nbswatcher.dll and the wapwatcher.dll, and some common base classes in biowatcher.dll. The watchers listen for incoming messages from the SMS stack, part of the nbsprotocols subsystem [R3], and the WAP stack part of the WAP-Stack subsystem [R4].
-3.2.7.3.1.1 NBS Watcher
-The NBS watcher handles reception of SMS messages. When initialised by the watcher framework (see section 3.2.4) the watcher queries the bio messaging database for bio messages that are listed as having a type of ENbs. For each of these bio messages the watcher creates an object that opens a connection to the SMS stack and waits for the particular message type. The message types are either defined by the port number the message will be received on or by a string to watch for at the start of the message. For example Internet Access Configuration Point messages are start with “//SIAP11” and vCards are received on port 226. Finally the watcher listens for all other messages received from the SMS stack.
-When the NBS Watcher receives a non-class 2 SMS message it creates a new entry under the global inbox in the message store. For class 2 messages the entry is created in the class 2 folder as defined by the SMS settings, this may also be the global inbox. The details field of the entry is used to store the phone number of the incoming message or the name of the sender if the watcher finds a match for the phone number in the contacts database. The description field is used to store the first N characters of the SMS message, where N is defined in the SMS settings, or for bio messages the description as retrieved from the bio database. Bio messages also have the BioType field set to the UID of the bio message as retrieved from the bio database. The CSmsHeader class, which is a wrapper around the CSmsMessage class provided by the nbprotocols subsystem [R3], is used to externalise the SMS message to the entry’s CMsvStore. The watcher also places a copy of the body text of the message in the rich text stream of the entry’s CMsvStore.
-The NBS Watcher is also responsible for handing special SMS types including:
-• Replace Type Messages – When the watcher receives a message of this type it will scan the folder the message would have been delivered to for messages that have a matching protocol ID and from address. For each of the messages it checks whether the time stamps from the service centre and discards the older message.
-• Message Indications – The watcher can listen for incoming message waiting indications. The CSmsSettings class defines whether the watcher will listen and whether it will deliver the messages to the inbox or discard them. If the watcher is configured to listen for messages then it will use the SMS utilities in the SMS Client MTM to decode the message to determine the notification type and number of messages, e.g. 3 Email messages waiting, the strings for these messages are in the smss.rss resource file.
-• Delivery Reports – As with Message Indications the watcher can be configured to listen for these and again the SMS utilities get a string from the smss.rss resource file to put in the description field.
-The NBS Watcher handles changes to the bio database using the observer mechanism provided by the bio message database to observe when bio message types are added or removed and starting or stopping the object watching for that bio message type.
-3.2.7.3.1.2 WAP Watcher
-The WAP watcher listens for incoming messages from the WAP stack using the WAP message API [R4]. To determine ports to use to listen for messages the watcher queries the bio message database for bio message types EWsp, EWspSecure, EWap, EWapSecure and registers as an observer of the bio database and so will listen for new bio message with these types as they are added. The watcher stores the messages in the global inbox tagged with the bio type listed in the bio message database.
-3.2.7.3.2 SMS Client MTM
-The SMS Client MTM implements the standard set of Client MTM APIs described in Client MTM. In addition it provides:
-• Access to the CSmsHeader object that is used to represent the SMS message.
-• Access to the SMS settings stored in the associated SMS service.
-• The APIs required by Send As to allow Send As to create SMS messages including setting the bio type of the message to allow clients of Send As to send bio messages such as vCards and vCals. The data of the bio message is stored in the body text of the SMS message.
-• Simple check for valid SMS addresses, and SMS address is considered valid if it contains at least one digit.
-• Reading and writing SIM parameters.
-3.2.7.3.3 SMS Utilities
-These provide:
-• Classes to represent and store SMS messages (CSmsHeader), and SMS settings (CSmsSettings, CSmsMessageSettings) and a SMS number (CSmsNumber).
-• The CSmsHeader class contains and allows clients to access the CSmsMessage class that the nbsprotocols subsystem provides. This contains the entire SMS message and not just the header.
-• Functions to generate descriptions and details fields to store with SMS messages, including decoding special messages such as message indication and status report messages, reading resource file for descriptions strings of special messages, using the contacts database to replace phone numbers with names.
-• API to validate a GSM number.
-• Find the TMsvId of the SMS service entry.
-3.2.7.3.4 SMS Server MTM
-3.2.7.3.4.1 Sending Messages
-The SMS Server MTM handles sending of SMS and WAP messages via the SMS stack and the WAP stack. To support this it implements the CopyFromLocal API inherited from the Server MTM base class. It implements this as sending SMS messages and moving successfully sent messages to the Sent folder. When sending the SMS message the Server MTM checks the bio type of the message and uses the bio database to check the transport type for the bio message. The MTM supports ENbs that is sent via the SMS stack and EWap, EWapSecure that are sent via the WAP stack. The MTM does not support EWsp or EWspSecure although the watchers do support receiving them.
-If a message fails to send, sending is retried according to the settings in the smss.rss resource file as described in the schedule send section 3.2.3.
-3.2.7.3.4.2 Scheduling Messages
-The SMS Server MTM implements scheduled sending API by sub-classing from the schedule send Server MTM (see section 3.2.3). It accepts requests from clients either via the SMS Client MTM InvokeAsync API or via the CMsvSession::TransferCommand API to schedule messages to be sent or to delete existing schedules. When it receives a request to schedule a message it packages up the command and uses the scheduled send functionality to request that the task scheduler ask it to send the messages at a future point in time.
-3.2.7.3.4.3 Phone Store
-The phone store is the name given to storage of SMS messages outside of the message store. In the case of GSM phones this is the SIM. The SMS Server MTM accepts requests from clients to copy/move messages to and from the SIM and delete messages from the SIM. For example when copying to the SIM it packages up the SMS message and passes it to the SMS stack with a request to write it to the SIM. If the class2 folder has been set in the SMS settings class then the Server MTM will copy the SMS message to the SIM and then update the SMS message in the message store with details of the slot on the SIM that has been used to store the SMS and the fact that it is stored on the SIM.
-3.2.7.3.4.4 SIM Parameters
-The Server MTM provides functions to read / write SIM parameters, again these requests are passed to the SMS stack to be processed.
-3.2.8 Messaging / CDMA SMS APIs
-3.2.8.1 Key Internal Relationships and Dependencies
-
-Figure 19 CMDA SMS Internal Dependencies
-3.2.8.2 Key External Relationships and Dependencies
-`
-Figure 20 CDMA SMS External Dependencies
-3.2.8.3 API Purpose - Further Elaboration
-3.2.8.3.1 CDMA SMS Watchers
-The CDMA SMS watchers are made up of six watchers, the cdmanbswatcher.dll, vmnwatcher.dll, wemtwatcher.dll, wmtwatcher.dll, wptwatcher.dll, and the wapwatcher.dll, and some base classes in biowatcher.dll and cdmasocketwatcher. While the WAP watcher is common for both GSM and CDMA, the other watchers: CDMA NBS watcher, VMN watcher, WEMT watcher, WMT watcher, and the WPT watcher are used for CDMA only. The watchers listen for incoming messages from the CDMA SMS stack, part of the nbsprotocols subsystem [R3], and the WAP stack part of the WAP-Stack subsystem [R4].
-3.2.8.3.1.1 CDMA NBS Watcher
-The CDMA NBS watcher is similar to the NBS watcher and it handles bio messages defined in bio database. The CSmsHeader class is extended to wrap around the CCdmaSmsMessage class provided by the nbprotocols subsystem [R3], and is used to externalise the CDMA SMS message.
-For handling special CDMA SMS type, the CDMA NBS watcher is responsible for handling Message Indications as described in section 3.2.7.3.1.1 NBS Watcher.
-3.2.8.3.1.2 WAP Watcher
-The GSM WAP watcher is used to handle CDMA WAP message as well. The WAP watcher listens for incoming messages from the WAP stack, which can listen from the CDMA SMS stack or GSM SMS stack as appropriate. See 3.2.7.3.1.2 for more info about WAP watcher.
-3.2.8.3.1.3 Other CDMA Watchers
-The VMN watcher, WEMT watcher, WMT watcher and WPT watcher are CDMA watchers that handle reception of CDMA SMS messages. All CDMA SMS messages are associated with a teleservice. Therefore, each of the CDMA watchers is responsible for handling one teleservice: VMN watcher handles VMN SMS messages, WEMT watcher handles WEMT SMS messages, WMT watcher handles WMT SMS messages, and WPT watcher handles WPT SMS messages. The CSmsHeader class is reused to externalise the CDMA SMS message.
-The CDMA watchers are also responsible for handling special SMS types including:
-• Duplicate Message – When the watcher receives a duplicate message, it will discard the duplicate message as defined by the CDMA service settings.
-• User Acknowledge – The watcher can listen for user acknowledgment message of its teleservice type.
-• Delivery Acknowledge – The watcher can listen for delivery acknowledgment message of its teleservice type.
-• Read Acknowledge – The watcher can listen for read acknowledgment message of its teleservice type.
-3.2.8.3.2 CDMA SMS Client MTM
-The CDMA SMS Client MTM implements the standard set of Client MTM APIs described in Client MTM. In addition it provides:
-• Access to the CSmsHeader object that is used to represent the SMS message.
-• Access to the SMS settings stored in the associated SMS service. These settings are store in file store pre v9.0 but stored in Central Repository from v9.0 onwards.
-• The APIs required by Send As to allow Send As to create SMS messages including setting the bio type of the message to allow clients of Send As to send bio messages such as vCards and vCals. The data of the bio message is stored in the body text of the SMS message.
-• Simple check for valid SMS addresses, and SMS address is considered valid if it contains at least one digit.
-• Reading and writing SMS messages to R-UIM.
-3.2.8.3.3 CDMA SMS Utilities
-The CDMA version of SMS utilities are binary compatible with the GSM version of SMS utilities. But the classes that store SMS Message (CSMSHeader), and SMS settings (CSmsSettings, CSmsMessageSettings) and SMS number (CSmsNumber) are extended to store CDMA information. The CSmsHeader class is extended to contain and allow clients to access the CCdmaSmsMessage in addition to the CSmsMessage. Other functions provided by the GSM SMS Utilities is also provided by the CDMA version of SMS utilities, see 3.2.7.3.3 for information about GSM SMS Utilities.
-3.2.8.3.4 CDMA SMS Server MTM
-3.2.8.3.4.1 Sending Messages
-The CDMA SMS Server MTM handles sending of CDMA SMS and WAP messages via the CDMA SMS stack and the WAP stack. To support this it implements the CopyFromLocal API inherited from the Server MTM base class. It implements this as sending SMS messages and moving successfully sent messages to the Sent folder. When sending the CDMA SMS message the Server MTM will use the appropriate teleservice type. The MTM supports ENbs that is sent via the SMS stack and EWap, EWapSecure that are sent via the WAP stack. The MTM does not support EWsp or EWspSecure although the watchers do support receiving them.
-If a message fails to send, sending is retried according to the settings in the smss.rss resource file as described in the scheduled send section 3.2.4.
-3.2.8.3.4.2 Scheduling Messages
-The CDMA SMS Server MTM implements scheduled sending API by sub-classing from the schedule send Server MTM similar to implemented in the GSM SMS Server MTM. See 3.2.7.3.4.2 for more information.
-3.2.8.3.4.3 Phone Store
-In the case of CDMA phones, phone store can be phone-based storage or R-UIM based storage. The CDMA SMS Server MTM accepts requests from clients to copy/move messages to and from the phone/R-UIM and delete messages from the phone/R-UIM. For example when copying to the R-UIM it packages up the SMS message and passes it to the CDMA SMS stack with a request to write it to the R-UIM.
-3.2.8.3.5 Configuration for using CDMA SMS MTM
-The CDMA messaging components currently only support single mode, but it is designed such that it can become multimode in the future. Currently, -Dcdma option is used to for selecting CDMA mode for using emulator and building ROM.
-
-
-3.2.9 Messaging / Email APIs
-3.2.9.1 Key Internal Relationships and Dependencies
-
-Figure 19 Email Internal Dependencies
-
-3.2.9.2 Key External Relationships and Dependencies
-
-Figure 20 Email External Dependencies
-3.2.9.3 API Purpose - Further Elaboration
-3.2.9.3.1 Email Overview
-The Email plug-ins consist of a set of utilities and MTMs for POP3, IMAP4 and SMTP. For each email account a pair of services entries is created in the message store. For a POP3 account there will be an SMTP service and a POP3 service, for an IMAP4 account there will be an SMTP service and as IMAP4 service. These entries are used to store the settings for the email transport. Each of the service entries has its related ID set to the other member of the pair. The SMTP service is created invisible so the user only sees the POP3 or IMAP4 service entry, copying a message to the SMTP service will cause the SMTP Server MTM to attempt to send the message. The POP3 and IMAP4 MTMs provide functionality to synchronise with a remote email server this is achieved by extending the Client MTM interface via the InvokeAsync API. Synchronisation of a POP3 or IMAP4 account will result in copying headers and optionally body text and attachments from the email server and creating message entries under the POP3 or IMAP4 service entry.
-Email messages are represented in a common format whether they are being sent via SMTP or downloaded via POP3 or IMAP4. The email client utilities provide the classes for creating and manipulating the entry structure used to store emails. The email server side utilities provide classes to convert between the entry structure used to store emails in the message store and RFC2822 email messages sent to SMTP servers and retrieved from POP3 servers. IMAP4 email messages are parsed by the email server and the IMAP4 Server MTM requests and stores the individual parts of the messages.
-3.2.9.3.2 Email Client Utilities
-The email client utilities are part of the imcm DLL and provide classes for:
-• Storage of email messages including mime headers, RFC2822 headers, attachments, body text and encoding information in the message store
-• Manipulating email messages, for example adding attachments, replying etc.
-• To wrap up the character converters used to convert between standard character sets and Unicode. These make use of the charconv component that is part of the system libraries subsystem.
-• Storage of Email settings in the message store.
-• Progress information for email operations.
-The utilities are used directly by clients to access parts of email messages for display. CImEmailMessage provides the functionality used by clients displaying email messages, including listing attachments, getting body text and resolving URIs in M-HTML messages.
-The Email Client MTMs use the utilities when they are asked to create, reply to and forward messages CImEmailOperation provides the functionality to perform these operations. Each email message is represented by a parent message entry and then entries to represent mime folders and mime parts, see Figure 7 for an example, so adding or deleting mime parts involves walking the tree of entries and inserting / removing entries as appropriate.
-3.2.9.3.3 Email Server MTM Utilities
-The Email Server MTM Utilities are responsible for generating and parsing of RFC2822 format email messages and providing an API to wrap up a TCP/IP connection to a remote email server.
-• Parsing of RFC2822 Email Messages – The utilities provide an API that accepts the text of an RFC2822 email message a line at a time and stores the email message in messaging’s internal format for email messages. See the Email Client Utilities for details of this format. The API handles storing of RFC2822 headers, MIME headers, decoding of Base64 encoded or uuencoded attachments and decoding of text received in character sets supported by the charconv component. This API is only accessible to Server MTMs, as it requires classes that can only be instantiated while running within the message server process. See the Messaging Functional Specification [R1] for detail on which email specifications the utilities support.
-• Generation of RFC2822 Email Messages – The utilities provide an API to convert an email in messaging’s internal format into an RFC2822 email message. The API provides access to the RFC2822 text a line at a time for streaming to an SMTP server. The exact format of the email depends on the settings passed in; the API can generate plain RFC2822 email messages with uuencoded attachments, MIME email messages with Base64 encoded attachments, or M-HTML email messages with Base64 encoded attachments. See the Messaging Functional Specification [R1] for detail on which email specifications the utilities support.
-• TCP/IP socket wrapper – The utilities provide a class that abstracts a TCP/IP socket supplied by the networking subsystem into an API that supports sending and receiving lines of text to / from a remote server. This API is used to connect to remote email servers by each of the email Server MTMs. The API can either create insecure or secure sockets enabling the SSL encryption provided by the networking subsystem. It also supports changing an insecure socket into a secure socket, this enables the email Server MTMs to implement email protocols where the initial connection to the server is insecure and then a secure socket is negotiated before sending or requesting any sensitive information.
-3.2.9.3.4 POP3 MTMs
-The POP3 MTMs implements the functionality to synchronise the local message store with a remote POP3 email server.
-3.2.9.3.4.1 Client MTM
-The POP3 Client MTM implements the standard Client MTM APIs and other extensions:
-• Reply to, forward – These are accessible via the ReplyL and ForwardL APIs of a Client MTM and are implemented as calls to the email utilities class CImEmailOperation.
-• Reply to, forward, create new messages, create receipts and forward as attachment – These are accessible as commands available via the InvokeAsyncFunction API of the Client MTM, they are implemented as calls to CImEmailOperation.
-• Connecting, disconnecting and copying email while connected – These operations are accessible as commands available via the InvokeAsyncFunction API of the Client MTM, they are implemented as calls to the POP3 Server MTM.
-• Querying connection status – This command lets clients know whether the POP3 Server MTM is connected to an email server, and is available via the InvokeAsyncFunction API of the Client MTM. The Client MTM requests the information from the Server MTM.
-• Compound operations – The Client MTM provides functionality to wrap up connecting to email servers, copying / moving new messages or a selection of messages, and then optionally disconnecting. These commands are available via the InvokeAsyncFunction API of the Client MTM. The Client MTM implements this by using the CImPOP3GetMail class which requests the correct sequence of operations from the Server MTM, waiting for each operation to complete before requesting the next one.
-• Send on next connection If the Client MTM gets a request to connect to an email server it will check whether the POP3 settings. If send on next connection is requested it will launch the autosend.exe executable (see section 3.2.7.3.7) to handle sending messages waiting in the outbox.
-• Offline operations – The POP3 Client MTM has a command to cancel offline operations, this is available via the InvokeAsyncFunction API of the Client MTM. The Client MTM passes the request to the Server MTM.
-3.2.9.3.4.2 Server MTM
-The POP3 Server MTM handles the communication with the remote POP3 server and implementation of the POP3 protocol. The MTM uses CImTextServerSession to handle the communication with the email server and CImRecvConvert to parse the email messages downloaded, both are provided by the Email Server MTM Utilities.
-• Connect – The POP3 Server MTM will open a socket to the email server using CImTextServerSession and login user the username / password in the POP3 settings. After a successful connection the Server MTM will attempt to synchronise the current state of headers stored on the email server with the set stored in the message store and then start any pending offline operations. After the connect operation has completed the Server MTM will inform the message server that it is expecting more operations via the CommandExpected API and therefore the message server will not delete and unload the Server MTM.
-• Populate Message – The POP3 Server MTM treats requests to copy a message from and to the POP3 service as a request to download the full message.
-• Offline operations – When the POP3 Server MTM receives a request to copy, move, or delete and is not connected to a POP3 email server the Server MTM will store the operation in the CMsvStore of the entry being modified and perform the operation on the next connection to the email server.
-• Disconnect – When disconnecting from a remote email server the POP3 MTM will run any pending offline operations stored. After the disconnect operation completes the Server MTM will allow the message server to delete and unload the Server MTM by setting the CommandExpected API to false.
-3.2.9.3.5 IMAP4 MTMs
-The IMAP4 Server MTM implements the functionality to synchronise the local message store with a remote IMAP4 email server.
-3.2.9.3.5.1 Client MTM
-The IMAP4 Client MTM implements the standard Client MTM APIs and other extensions:
-• Connecting, disconnecting, synchronising, un/subscribing folders – These operations are accessible as commands available via the InvokeAsyncFunction API of the Client MTM, they are implemented as calls to the IMAP4 Server MTM.
-• Send on next connection – If the Client MTM gets a request to connect to an email server it will check whether the IMAP4 settings. If send on next connection is requested it will launch the autosend.exe executable (see section 3.2.7.3.7) to handle sending messages waiting in the outbox.
-• Reply to, and forward messages – These are accessible via the ReplyL and ForwardL APIs of a Client MTM and are implemented as calls to the email utilities class CImEmailOperation.
-• Reply to, forward, create new, create receipt, forward as attachment – These are accessible as commands available via the InvokeAsyncFunction API of the Client MTM, they are implemented as calls to CImEmailOperation.
-• Querying connection status – These commands let clients know whether the IMAP4 Server MTM is connected to an email server and whether it is currently processing a request. They are available via the InvokeAsyncFunction API of the Client MTM. The Client MTM requests the information from the Server MTM.
-• Compound Connection and synchronisation – The IMAP4 Client MTM provides a compound operation that connects and synchronises with an IMAP4 server. This operation is implemented as a client side object that combines requests to the IMAP4 Server MTM. The client side operation can complete the client request either after the connection, after the connection + sync or after the connection + sync + disconnect. The client will keep requesting that the inbox be resynchronised at a configurable interval so new messages received in the inbox on the server will appear under the IMAP4 inbox. The CImapConnectAndSyncOp class handles these compound operations.
-• Compound Connect and copy / move / populate messages – The IMAP4 Client MTM provides a compound operation that connects to an IMAP4 server and copies moves or populates messages. The implementation is provided by the CImImap4GetMail class which makes calls back into the IMAP4 Client MTM.
-• Offline operations – The IMAP4 Client MTM has a command to cancel offline operations, this is available via the InvokeAsyncFunction API of the Client MTM. The Client MTM passes the request to the Server MTM.
-3.2.9.3.5.2 Server MTM
-The IMAP4 Server MTM handles the communication with the remote IMAP4 server and implementation of the IMAP4 protocol. The MTM uses CImTextServerSession to handle the communication with the email server. The IMAP4 Server MTM opens two connections to the IMAP4 server this enables users to download messages while the Server MTM is performing a background synchronisation if requested by the Client MTM.
-• Connect – The IMAP4 Server MTM will open a socket to the email server using CImTextServerSession and login using the username / password in the IMAP4 settings. After a successful connection the Server MTM will optionally attempt to synchronise the current state of headers stored on the email server with the set stored in the message store and then start any pending offline operations. After the connect operation has completed the Server MTM will inform the message server that it is expecting more operations via the CommandExpected API and therefore the message server will not delete and unload the Server MTM.
-• Copy, Move messages – The IMAP4 Server MTM supports copying and moving messages between folders on the IMAP4 server and between the IMAP4 server and local folders.
-• Delete messages – The IMAP4 Server MTM will mark the email as deleted on the server; however it will not be deleted until the IMAP4 Server MTM disconnects from the server.
-• Folders – The IMAP4 Server MTM will allow folders to be subscribed, unsubscribed, renamed, copied, moved, and created within the IMAP4 service. Subscribing to a folder means that it will be visible to the user and synchronised with the remote server. The inbox is always subscribed.
-• Offline operations – When the IMAP4 Server MTM receives a request to copy, move, or delete and is not connected to an IMAP4 email server the Server MTM will store the operation in the CMsvStore of the entry being modified and perform the operation on the next connection to the email server.
-• Disconnect – When disconnecting from a remote email server the IMAP4 MTM will run any pending offline operations stored. After the disconnect operation completes the Server MTM will allow the message server to delete and unload the Server MTM by setting the CommandExpected API to false.
-
-3.2.9.3.6 SMTP MTMs
-The SMTP MTMs provide functionality to send email messages. They are made up of the Client MTM that is part of the imcm DLL and the Server MTM.
-3.2.9.3.6.1 Client MTM
-The SMTP Client MTM implements the standard Client MTM APIs including the functions required to allow clients of Send As to create email messages.
-3.2.9.3.6.2 Server MTM
-The SMTP MTMs provide functionality to send email messages; it interprets requests to copy entries to an SMTP service as a request to send those messages. In addition it responds to two extended commands via the StartCommand Server MTM interface. These commands are KSMTPMTMIsConnected that responds with whether the Server MTM is currently connected to a remote SMTP server and KSMTPMTMSendOnNextConnection which performs the same operation as copying a selection of messages to an SMTP service. The only difference between the copy operation and the KSMTPMTMSendOnNextConnection operation is that the latter can be called without a selection of messages.
-When the Server MTM receives a request to send messages it builds a selection of messages consisting of the messages passed into the operation and any messages waiting in the outbox to be sent. To determine which messages in the outbox are waiting to be sent the SMTP server checks for messages that have the same service ID as the destination of the send operation and have a sending state of KMsvSendStateWaiting, KMsvSendStateScheduled or KMsvSendStateResend. This means that any request to send messages may result in more messages being sent than explicitly listed in the selection passed to the send operation.
-The Server MTM restores its settings from the SMTP service it has been asked to copy the messages to. Then it connects to the SMTP server using the CImTextServerSession class in the Email Server MTM Utilities, passing in the SMTP server address and TCP/IP port number from the SMTP settings. Then for each message to be sent the Server MTM uses the Email Server MTM utilities to generate an RFC2822 format message to send to the SMTP server, the RFC2822 text is generated on the fly as the data is sent to the SMTP server. If the SMTP server accepts the message to be sent then the Server MTM moves the message to the sent folder and sets its sending state to sent. If the SMTP server rejects the message then the Server MTM leaves the message in the outbox and sets the sending state to failed. Separate emails are generated for BCC recipients to ensure that the SMTP server doesn’t incorrectly include BCC recipients in emails sent to addresses in the To and CC fields of the email.
-3.2.9.3.7 Autosend
-The Autosend component is an executable that is kicked off by the POP3 and IMAP4 Client MTMs if the send on next connection setting is set. This executable will just make a request to the SMTP Server MTM to send messages associated with the SMTP service related to the POP3 or IMAP4 service, wait for the operation to finish and then exit.
-3.2.10 Messaging / MMS APIs
-The MMS module has been removed from v9.0 and onwards.
-3.2.10.1 Key Internal Relationships and Dependencies
-
-Figure 21 MMS Internal Dependencies
-3.2.10.2 API Purpose - Further Elaboration
-3.2.10.2.1 MMS Overview
-The MMS MTM provides functionality for creating, accessing, sending and receiving MMS messages. Messages are sent and received without the client application needing to open or close any kind of session. The management of the MMS session is handled entirely within the MTM.
-MMS clients are alerted when a new message is available for download via the WAP Push mechanism. A WAP push watcher is provided to handle these notifications. After the notification the message can be downloaded over WSP or HTTP. Messages are sent by posting the data over WSP or HTTP. The Symbian MMS implementation can handle sending or receiving MMS message over either protocol.
-MMS messages are based on the MIME format but are binary encoded using WSP. Note that MMS messages are encoded in this way even if they are posted over HTTP as opposed to WSP. The codec component is responsible for this encoding and decoding.
-3.2.10.2.2 MMS Utilities
-3.2.10.2.2.1 Key External Relationships and Dependencies
-
-Figure 22 MMS Utilities External Dependencies
-The MMS utilities provide the message and settings encapsulation classes. The MMS settings and messages are stored in the message store, the MMS utilities provide the interfaces to access this data.
-3.2.10.2.2.2 Settings
-The settings functionality provided by the MMS utilities allows the messaging client to persist MMS settings in the message store. Supported settings include:
- MMSC (MMS server) address
- WSP or HTTP transport
- Autofetch messages on notification
- Preferred IAP for the MMS network connection
-The settings functionality is also used by the server MTM to retrieve the settings prior to message sending or fetching.
-3.2.10.2.2.3 Message Encapsulation
-The message classes provide the message access functionality. Messages can be created, stored, restored and read using these classes. Functionality includes:
- Adding media objects to the message
- Enumerating through media objects
- Adding recipients, subject line, etc. to a message
- Adding other headers to the message, e.g. expiry date
- Finding the appropriate media object for a given URI in the SMIL part (URI resolving)
-The message data is stored in the message store using one entry per message regardless of the number of media objects added to the message. This is preferable to using multiple message entries as it is faster and uses less disk space.
-Most of the message access code is common whether it is being used on the client or server side, however some parts of it are specific. For this reason it is essential that the appropriate client or server side CMmsMessage derived class is used.
-3.2.10.2.3 MMS Watcher
-3.2.10.2.3.1 Key External Relationships and Dependencies
-
-Figure 23 MMS Watcher External Dependencies
-
-The MMS watcher plug-in is responsible for intercepting incoming MMS notifications and delivery reports then taking the appropriate action. It is implemented as a WAP Push watcher plug-in.
-When an MMS notification is received an MMS entry is created in the inbox using the MMS utilities. At this point the entry has its incomplete flag set. If the settings have the autofetch option selected then the MMS watcher initiates the fetch operation via the MMS client MTM.
-If a delivery report is received then the delivered flag is set on the appropriate sent message. If an outgoing message was sent to several recipients then there will be several delivered flags. A delivery report from each recipient will set the appropriate delivered flag.
-3.2.10.2.4 MMS Client MTM
-3.2.10.2.4.1 Key External Relationships and Dependencies
-
-Figure 24 MMS Client MTM Dependencies
-As with most other MTMs the MMS client MTM provides access to the server MTM functionality for messaging clients. It also implements the Send-As interface and reply and forward functionality.
-3.2.10.2.4.2 Send-As Implementation
-The Client MTM Send-As interface is implemented in the MMS Client MTM. The implementation differs slightly from other MTMs because additional presentation content may be generated depending on the media objects that are added. When simple combinations of images, sounds and text are added a SMIL presentation is generated to link them together. This is preferable to simple adding the objects as attachments where some clients render them as a list of files and others fail to render them at all.
-The SMIL data is constructed using templates stored in resource files, the GMXML (SMIL) composer is not used.
-3.2.10.2.4.3 Reply / Forward
-The Client MTM can be used to create replies to received messages or to create forwarded responses. The reply and forwarding operations are performed asynchronously.
-3.2.10.2.5 MMS Server MTM
-3.2.10.2.5.1 Key External Relationships and Dependencies
-
-Figure 25 MMS Server MTM Dependencies
-The Server MTM is the most complicated part the MMS implementation. It handles all of the state information required to send or fetch MMS messages. It is also responsible for managing the HTTP or WSP session and the connections to the phone network.
-3.2.10.2.5.2 Operations
-All MMS server MTM functionality is encapsulated in operations. An operation consists of the setup of a session, the sending, fetching and acknowledgements when appropriate, it then closes the session. The messaging client initiates an operation with a single call to the Client MTM, there is no need for the messaging client to explicitly establish the session or to know about the internal states. However, these internal states are available to the messaging client via the progress structure if this level of user feedback is required.
-Two types of operation are supported, background and foreground:
-A maximum of one foreground operation can be running at any one time. The messaging client can poll the server MTM for the progress of a running foreground operation, likewise it can cancel it if necessary.
-A background operation does not support progress information and can not be cancelled by the messaging client. It is possible to initiate background operations even if other background or foreground operations are pending. However, background operations are queued and a maximum of one will actually be running at any one time.
-The MMS watcher uses a background operation to perform automatic fetching. While the background autofetch is occurring it is still possible to start a foreground operation (such as sending a message) if required.
-3.2.10.2.5.3 Session and Connection Management
-The server MTM uses the HTTP Transport Framework to enable the HTTP or WSP session. HTTP or WSP can be selected at runtime by selecting the appropriate option in the settings. The server MTM is responsible for reading any HTTP proxy details from the CommDB and passing it to the HTTP framework. See the http transport framework architectural description for more information on recognisers [R5]
-The server MTM is also responsible for managing the connection to the phone network. Connections are opened when required using the RConnection mechanism, multi-homing is supported provided that the underlying HTTP framework transport plug-in also supports it.
-3.2.10.2.6 MMS Codec
-The MMS Server MTM is in charge of the state transitions, connection, session, the actual posting and fetching of the data from them, however it does not encode or decode the MMS PDUs. The encoding and decoding is performed by the MMS Codec.
-For decoding the Server MTM passes the Codec the MMS PDU data in a descriptor for processing. If the PDU contains a received MMS message then the message entry is updated with the decoded MMS data.
-For encoding the Server MTM passes a reference to the message store entry containing the un-encoded MMS data. The Codec then encodes it and returns the PDU to the Server MTM in a descriptor.
-
-
-3.2.11 Messaging / BIO APIs
-3.2.11.1 Key Internal Relationships and Dependencies
-
-Figure 26 BIO Message Internal Dependencies
-3.2.11.1.1.1 Key External Relationships and Dependencies
-
-Figure 27 Bio Parser External Dependencies
-
-3.2.11.2 API Purpose - Further Elaboration
-3.2.11.2.1 BIO Overview
-The BIO messaging components have been designed to unify and simplify the way in which system messages are processed. In this context ‘system messages’ refers to messages received on the device which are intended to update some attribute(s) on the system as opposed to being presented to the user. Examples of these types of messages include vCards which are parsed and then displayed to the user and when accepted modify the users contact database and OTA configuration messages which are again parsed before display to the user and if accepted create email accounts or internet access points.
-The BIO messaging components can be broken down into three groups:
-1) The BIO MTM - To initiate the parsing and processing of BIO messages
-2) The BIO Database - Maps port numbers, MIME types, etc. to bio types in order to identify the type of incoming BIO messages.
-3) The BIO Parsers - To parse and process the BIO message payload
-BIO messages are not receive by the bio messaging framework, they come over other message transports for example see section 3.2.6.3.1 on the SMS watchers which describes how the SMS watchers receive bio messages and use the bio framework to tag the messages with the correct bio id.
-3.2.11.2.2 BIO MTM
-The BIO client MTM is called by the messaging client to parse or process a BIO message that has been saved in the message store. It is the responsibility of a BIO watcher to save the BIO message with the BIO flag and the appropriate BIO type set.
-The BIO client MTM does very little, its primary task is to pass on the messaging client request to the server MTM. Two operations are supported, parse and process.
-The messaging client is expected to initiate the parsing of the BIO message before processing it. The parsing step involves analysing the data and storing it in a form that can be displayed to the user via the BIO message viewer.
-Once the message has been parsed the messaging client can initiate the processing of the message.
-The BIO server MTM is responsible for deferring the parsing and processing to the appropriate BIO parser. The behaviour for the parsing and processing steps varies between parsers. See the BIO Parsers section for more information.
-The bio MTM does not support sending messages and therefore does not support reply / forwarding messages. For bio messages sending / reply etc. is supported by the particular MTM that the message is sent over, for example SMS.
-3.2.11.2.3 BIO Database
-The BIO database is used to identify the type of BIO messages. It maps message attributes such as port number, MIME type or leading string to a BIO type. These are attributes are then used by clients of the bio framework to know what ports to listen for messages on. For example the SMS watchers use the leading string to wait for SMS messages that start with that string and when storing those messages in the inbox tag them with the bio id associated with that leading string. See the SMS watcher section 3.2.6.3.1 for more examples of how the BIO database can be used.
-3.2.11.2.4 BIO Parsers
-The BIO parsers are plug-ins for parsing and processing incoming BIO messages. They are invoked by the BIO Server MTM depending on the BIO type of the message being processed. Each BIO parser implements two functions, ParseL and ProcessL. The level of functionality varies between parsers. Some parsers update the final repository with the received data, e.g. WAPP updates the CommDB with the received settings. Some parsers simply save the data in an unparsed state for processing by another component, this secondary parsing is not part of the BIO framework and must be initiated by the messaging client. An example is when GFP saves vCard data as a file as opposed to updating the contacts database, the UI must then invoke the Versit parser to parse the vCard and commit it to the contacts database.
-3.2.11.2.4.1 Generic File Parser (GFP)
-The generic file parser can be used to identify and save a variety of BIO data types, e.g. vCards and vCals. The Generic File Parser does not process the data, it simply saves it in the message store for processing by another component. The file is saved as an attachment of the message entry that was parsed.
-3.2.11.2.4.2 Nokia/Ericsson OTA Parser (WAPP)
-The WAPP parser decodes Nokia/Ericsson OTA messages and updates CommDB to reflect the received settings.
-3.2.11.2.4.3 Nokia Smart Message Internet Access Parser (IACP)
-The IACP parser decodes Nokia Smart Messages and updates the CommDB and messaging settings where appropriate.
-3.2.11.2.5 BIF Files and Utilities
-The BIF files encapsulate the information required for identifying BIO messages, these details may include the expected port number, MIME type or leading string. Different BIO watcher will use different information from these files, for an example see the 3.2.6.3.1. The information can be retrieved from the BIF files by using the BIF utilities. Generally BIO aware clients will access this information via the BIO database. BIF files are resource files previous to the v6.1 release they were binary files generated by biftool.exe.
-3.2.11.2.6 Platform Security Compliant Messaging / BIO APIs
-In the platform security model the BIO parsers are run in the client space rather than in the message server space, as is done in the non-platform secure model. If the BIO parsers are run in the message server space, it allows a client process to gain the capabilities of the message server. IPC policing can protect the message server from this.
-Also, for the message server to be able to load any BIO parser it would need more capabilities than it really requires. By running the BIO parsers in the client space, both these issues are solved. The client process must be trusted with the necessary capabilities to run the specified BIO parser.
-The BIO registry files are located in the \resource\messaging\bif read-only directory. All BIO parser DLLs are located in the \sys\bin protected directory.
-
-Figure 26 BIO Message Dependencies (v9.0)
-The BIO client MTM is responsible for loading the BIO database and BIO utilities to handle parse/process requests from clients.
-The BIO registry files no longer identify the BIO parsers DLLs via their UID – the registry file must use the BIO parser DLL name to identify them.
-3.2.12 Messaging / OBEX MTM APIs
-3.2.12.1 Key Internal Relationships and Dependencies
-
-Figure 28 OBEX Internal Dependencies
-3.2.12.2 OBEX MTM Overview
-The OBEX MTM offers simple IR and Bluetooth beaming functionality. It provides an API that is consistent with other MTMs so that the underlying OBEX APIs do not need to be used directly for beaming applications. The OBEX MTM does not provide OBEX receiving functionality, in order to receive OBEX data the underlying OBEX APIs must be used directly.
-3.2.12.2.1 OBEX MTM
-The OBEX MTM is split into three parts. OBEX MTM DLLs, IR MTM DLLs and Bluetooth MTM DLLs. The OBEX MTM DLLs can not be used on their own they provide the base OBEX MTM functionality for the derived IR and Bluetooth MTMs.
-There are two APIs that can be used to create OBEX messages:
-1) The Send-As API
-2) Linked attachments by filename
-The Send-As API provides an interface consistent with other MTMs, however it requires all attachments to be copied into the message store before they can be sent, this is often undesirable for beaming applications because it is wastes disk space. For this reason a second API is provided that allows attachments to be linked to outgoing messages by filename, when this API is used there is no need to copy the attachments to the message store.
-Unlike many other MTMs after OBEX tries to send a message it is deleted from the outbox whether the sending succeeds or fails.
-3.2.12.2.1.1 OBEX MTM Key External Dependencies
-
-Figure 29 OBEX External Dependencies
-3.2.12.2.2 IR MTM
-The bulk of the OBEX MTM functionality is provided by the OBEX MTM DLLs, the IR MTM itself just sets up the parameters.
-3.2.12.2.2.1 IR MTM Key External Dependencies
-
-Figure 30 IR MTM Dependencies
-3.2.12.2.3 Bluetooth MTM
-The bulk of the OBEX MTM functionality is provided by the OBEX MTM DLLs, the Bluetooth MTM just subclasses from the OBEX MTM and sets up Bluetooth specific parameters.
-3.2.12.2.3.1 Bluetooth MTM Key External Dependencies
-
-Figure 31 Bluetooth MTM Dependencies
-3.2.12.2.4 OBEX MTM Utils
-The OBEX MTM Utils provide utility functionality used by the other OBEX MTM DLLs. The two main areas of functionality provided by this component are:
-1) Filename linking functionality
-2) Bluetooth SDP lookup
-The filename linking functionality is provided in the utilities because linked files must be added by the client side during message creation and need to be read on the server side during sending.
-
-3.2.12.2.5 Platform Security Compliant Messaging / OBEX MTM APIs
-From v9.0 and onwards the service settings of all the derived OBEX MTMs are stored in the Central Repository. The OBEX message is stored in the message store as an attachment – from v9.0 and onwards the Attachment API is used to attach the OBEX message.
-
-3.2.13 Messaging / GMXML APIs
-3.2.13.1 Key Relationships and Dependencies
-
-Figure 32 GMXML Dependencies
-3.2.13.2 Overview
-The GMXML component provides simple XML DOM parsing and validation functionality. It is intended for parsing XML that might be needed in messaging applications, specifically SMIL parsing for MMS rendering. It is not a general purpose XML parser and will not be suitable for some applications, e.g. browsing.
-3.2.13.2.1 GMXML DOM
-The DOM implementation is fit for purpose for SMIL rendering but differs from the standard DOM design in several respects, e.g. attributes are not stored as discrete nodes, for performance reasons they are stored with the element.
-The DOM tree classes are all derived from nodes. Implemented node types include elements, text and comments. The type of each element is stored as a descriptor as opposed to an enum. This is less efficient than storing it as an enum but provides maximum flexibility when dealing with unknown element types.
-Nodes are linked together in a tree structure as might be expected in a DOM implementation. The tree structure exists on the heap.
-3.2.13.2.2 GMXML Parser and Composer
-3.2.13.2.2.1 Parser
-The parser takes XML input from a buffer or file and creates the corresponding DOM structure on the heap.
-The parser is capable of performing some basic validation. In order to validate against a DTD a class that implements the GMXML DTD interface is required. The DTD interface specifies several functions that provide the required validation, e.g. one of the functions determines if a given attribute is valid for a given element. An instance of the DTD class should be passed into the parser when validation is required but can be omitted if no validation is needed.
-3.2.13.2.2.2 Composer
-The composer takes a DOM tree and generates XML output from it. The XML output is written to a file.
-3.2.13.2.3 GMXML SMIL DTD (Validator)
-The SMIL DTD validator class is an implementation of the DTD validator interface. It implements several simple functions that provide the information required to validate SMIL data. An instance of the SMIL DTD validator should be passed into the parser if SMIL validation is required.
-4 Security
-4.1 Data caging
-For data storage in the pre-platform security compliant architecture, refer to section [3.2.1.3.2]
-For the data caging in the platform security compliant architecture of v9.0 and onwards, refer to section [3.2.1.3.3]
-4.2 Backup and restore
-The message server registers the index file with the backup server. When informed about a backup/restore it releases the index file, sending events to messaging clients informing them that the message store is unavailable. When informed it can open the index file again, it checks the time stamp on the index file; if it has changed since the file was released it reloads the index file. If the newly restored index file is found to be corrupt it is deleted and a new message store is created. See the section on page 14 for details on how the message server handles corrupt stores. The client performing the restore should always wipe the existing message store before starting to copy the message store from the backup to the device.
-4.3 Capability ranges
-In the platform security compliant architecture of v9.0 and onwards, the capabilities allocated to messaging sub-systems are as listed in following table.
-4.3.1 Capabilities granted to executables
-The following table lists the executables and their capabilities and also gives a basic example for having the required capability.
-
-Executable Capability Rationale (basic example of capability requirement)
-msexe.exe ProtServ ProtServ is required to allow the msexe.exe to start a protected server. This stops processes without ProtServ from starting a server pretending to be the message server
- ReadDeviceData ReadDeviceData is needed to able to read service settings
- WriteDeviceData WriteDeviceData is needed to able to write service settings
- NetworkServices NetworkServices capability is needed to access network transports (SMS, POP3, SMTP, IMAP4).
- LocalServices LocalServices is needed to be able to access IR and Bluetooth
- ReadUserData ReadUserData is needed to be able to read user data (e.g. service settings).
-watcher.exe ReadDeviceData ReadDeviceData is needed to able to read service settings
- WriteDeviceData WriteDeviceData is needed to able to write service settings
- NetworkServices NetworkServices capability is needed to access network transports (SMS).
- LocalServices LocalServices capability is needed for the plug-ins to access IR and Bluetooth
- ReadUserData ReadUserData is needed to be able to read user data
- WriteUserData WriteUserData is needed to be able to write user data
-autosend.exe ReadUserData ReadUserData capability is needed to be able to read data from Outbox and SMTP server MTM.
- WriteUserData WriteUserData capability is needed to be able to write data in Outbox and SMTP server MTM.
- NetworkServices NetworkServices capability is needed to access network transports (SMS, POP3, SMTP, and IMAP4).
- LocalServices LocalServices capability is needed to access the IR and Bluetooth
-SchSend.exe ReadDeviceData ReadDeviceData is needed to able to read settings data
- NetworkServices NetworkServices capability is needed to access the network transports (SMS, POP3, SMTP, and IMAP4).
- LocalServices LocalServices is needed to be trusted by other MTM
- ReadUserData ReadUserData is needed to be able to read user data.
- WriteUserData WriteUserData is needed to be able to write user data.
-SendAs.exe ReadDeviceData ReadUserData is needed to be able to read data in Outbox.
- WriteDeviceData WriteUserData is needed to be able to write data in Outbox.
- NetworkServices NetworkServices capability is needed to access the network transports (SMS, POP3, SMTP, and IMAP4).
- LocalServices LocalServices is needed to be able to access IR and Bluetooth
-
-4.3.2 Capabilities granted to DLLs
-The assigned Platform Security attributes for DLLs within messaging are outlined in the following table.
-DLL Capability
-bifu.dll All –TCB
-bioc.dll All –TCB
-biodb.dll All –TCB
-bios.dll All –TCB
-biowatcher.dll same as watcher.exe
-biut.dll All –TCB
-cbcp.dll All –TCB
-enp.dll All –TCB
-gfp.dll All –TCB
-iacp.dll All –TCB
-nbswatcher.dll same as watcher.exe
-cdmanbswatcher.dll same as watcher.exe
-CdmaSocketWatcher.dll same as watcher.exe
-VMNWatcher.dll same as watcher.exe
-WEMTWatcher.dll same as watcher.exe
-WMTWatcher.dll same as watcher.exe
-WPTWatcher.dll same as watcher.exe
-wapp.dll All –TCB
-wapwatcher.dll same as watcher.exe
-smildtd.dll All –TCB
-xmldom.dll All –TCB
-xmlparser.dll All –TCB
-smiltranslator.dll All –TCB
-imcm.dll All –TCB
-imps.dll same as msexe.exe
-imut.dll All –TCB
-msgs.dll All –TCB
-msgurlrec.mdl same as AppArc.exe (once it exists; eiksrv in meantime)
-mtur.dll All –TCB
-pops.dll same as msexe.exe
-schsend.dll All –TCB
-send.dll All –TCB
-smcm.dll All –TCB
-smcm_gsm.dll Synonym for smcm.dll
-smcm_cdma.dll Synonym for smcm.dll
-smss.dll same as msexe.exe
-smss_gsm.dll Synonym for smss.dll
-smss_cdma.dll Synonym for smss.dll
-smts.dll same as msexe.exe
-btcmtm.dll All –TCB
-btsmtm.dll same as msexe.exe
-irc.dll All –TCB
-irs.dll same as msexe.exe
-obexclientmtm.dll All –TCB
-obexmtmutil.dll All –TCB
-obexservermtm.dll same as msexe.exe
-
-The reason for setting a high capability to the DLLs is to make it possible for almost anyone to link to them. Although a DLL may have capabilities ALL-TCB (All minus TCB), its real capability is limited by the process which loads the DLL.
-4.3.3 Capabilities required to use the subsystem
-The message subsystem needs to be protected against malicious clients. The following table shows the key capabilities required to do related activities in different components.
-
-Component Related Activity Required Capability and SID
-Message server Create message in local folder No capability required
- Create message in Outbox ReadUserData, WriteUserData and MTM specific capabilities
- Access client MTM ReadUserData, WriteUserData and MTM specific capabilities
-Watcher Allow plug-ins to wait on events (e.g. arrival of SMS) Watcher always polices if the client capabilities are trusted by the watcher framework, else it will not be loaded
-Plug-ins or clients using watcher need the same capabilities as watcher.exe to be able to be loaded by watcher.
-Autosend Send messages in background NetworkService or LocalService required by the message type
-SchSend Scheduling of operations (e.g. sending SMS) SchSend always polices to see if the process was started by the Task Scheduler – if not the process terminates without performing any of the scheduled tasks. Also, the SchSend verifies that only itself and the message server created the scheduled tasks. If this is not the case, SchSend does not performing the scheduled tasks.
-SendAs Create message Draft, move it to Outbox, and send message WriteDeviceData or WriteUserData and other capability required by the message type
-
-5 Further Information
-5.1 References
-No. Document Reference Version Description
-R1 messaging_functional_specification.doc 0.6 Messaging Functional description
-R2 SGL.GT0143.161_App-Framework_Architectural_Description.doc 1.0 App-Framework Architectural Description
-R3 NBProtocols_Subsystem_Architectural_Description.doc 0.2 NBProtocols Architectural Description
-R4 WAP-stack_architectural_analysis.doc 1.0 WAP stack architectural analysis
-R5 HTTP Transport Framework Architectural Description.doc 1.1 HTTP Transport Framework 1.1 Architectural Description
-5.2 Open Issues
-The following issues need to be resolved before this document is completed:
-1. Top-level architecture diagram showing the framework and plug-ins should be added to overview section.
-2. Message store section should talk about removable media.
-3. Define "Message Server Client API" and "Messaging Client API" in the glossary, and ensure it is consistently used in the diagrams
-4. Add a sequence diagram for receiving a vCard over SMS and integrating it into contacts
-5. Add a sequence diagram for sending an SMS
-6. Add a sequence diagram for synchronising a POP3 mail box
-7. Add a sequence diagram for connecting to an IMAP4 mail box and downloading a message
-8. Capability table should be updated after the implementation of server e.g. message server
-9. Sequence diagram may need to be changed to show secured platform operation
-10. In section [3.1.1.4] the server SendAsV2 to find a correct name
-11. Section 3.2.1.3.3.1 Data Caging file 'Mtm Registry v2'may need a correct name
-12. Breakdown diagram showing all DLL, exes, apps in the messaging subsystem for both the pre-v8.0 and post v9.0 in section[3.2]
-13. Needs to say more about how the capabilities are policed and the algorithms used for different operations
-14. The dependecy between the message server and the central repository need to be listed in the email, SMS and OBEX diagrams (e.g. message store)
-15. Section 3.2.1.2 - figure 3 - Central Repository also get used by the Message server, or server MTMs (e.g. POP3), to retrieve account settings the path, required DLL and description are not given
-16. Section 4.3.3 title can be Police requirement of the sub-system, add extra column for SID in the table and list the use of SID. For example SchSend checks for Task Scheduler SID
-
-
-5.3 Glossary
-The following technical terms and abbreviations are used within this document.
-Term Definition
-BIO
-Bearer Independent Object Smart messages e.g. vCards, vCals, and WAP provisioning messages. These can currently be received via the WAP stack, SMS stack, Bluetooth or Infrared.
-BIO Type UID that represents the content type of a BIO Message.
-Message Centre Application that displays list views of messages to the user, allowing the user to perform operations such as copying messages, sending messages creating new messages etc.
-Message Viewer Application for viewing a message.
-Message Editor Application for creating or editing a message
-Message Server Symbian OS Server that handles request to modify the Message Store
-Message Store Store of messages and related information kept in the file system on a Symbian OS device.
-Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
-Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
-Global Inbox A standard folder under the local service which is used to store incoming messages like SMS MMS etc. as opposed to an IMAP4 Inbox which would be under an IMAP4 service and is a representation of the Inbox on an IMAP4 email server.
-Central Repository centralised and secure storage facility for application settings
-OBEX Object exchange protocol, used to send objects such as vCards or files between devices via infrared or Bluetooth.
-GMXML XML parser / generator for use with SMIL formatted messages.
-UID Unique Identifier, a 32 bit number allocated from a registry owned by Symbian
-IPC Inter Process Communication
-MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
+MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
MTM Registry A list of currently installed MTMs maintained by the message server.
TLS Transport Layer Security, provides encryption of a TCP/IP socket.
M-HTML Standard for including HTML in MIME email messages see http://www.ietf.org/rfc/rfc2557.txt
@@ -22333,15 +16225,15 @@
Message Editor Application for creating or editing a message
Message Server Symbian OS Server that handles request to modify the Message Store
Message Store Store of messages and related information kept in the file system on a Symbian OS device.
-Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
-Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
+Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
+Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
Global Inbox A standard folder under the local service which is used to store incoming messages like SMS MMS etc. as opposed to an IMAP4 Inbox which would be under an IMAP4 service and is a representation of the Inbox on an IMAP4 email server.
Central Repository centralised and secure storage facility for application settings
OBEX Object exchange protocol, used to send objects such as vCards or files between devices via infrared or Bluetooth.
GMXML XML parser / generator for use with SMIL formatted messages.
UID Unique Identifier, a 32 bit number allocated from a registry owned by Symbian
IPC Inter Process Communication
-MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
+MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
MTM Registry A list of currently installed MTMs maintained by the message server.
TLS Transport Layer Security, provides encryption of a TCP/IP socket.
M-HTML Standard for including HTML in MIME email messages see http://www.ietf.org/rfc/rfc2557.txt
@@ -23351,15 +17243,15 @@
Message Editor Application for creating or editing a message
Message Server Symbian OS Server that handles request to modify the Message Store
Message Store Store of messages and related information kept in the file system on a Symbian OS device.
-Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
-Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
+Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
+Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
Global Inbox A standard folder under the local service which is used to store incoming messages like SMS MMS etc. as opposed to an IMAP4 Inbox which would be under an IMAP4 service and is a representation of the Inbox on an IMAP4 email server.
Central Repository centralised and secure storage facility for application settings
OBEX Object exchange protocol, used to send objects such as vCards or files between devices via infrared or Bluetooth.
GMXML XML parser / generator for use with SMIL formatted messages.
UID Unique Identifier, a 32 bit number allocated from a registry owned by Symbian
IPC Inter Process Communication
-MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
+MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
MTM Registry A list of currently installed MTMs maintained by the message server.
TLS Transport Layer Security, provides encryption of a TCP/IP socket.
M-HTML Standard for including HTML in MIME email messages see http://www.ietf.org/rfc/rfc2557.txt
@@ -24369,1033 +18261,15 @@
Message Editor Application for creating or editing a message
Message Server Symbian OS Server that handles request to modify the Message Store
Message Store Store of messages and related information kept in the file system on a Symbian OS device.
-Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
-Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
+Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
+Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
Global Inbox A standard folder under the local service which is used to store incoming messages like SMS MMS etc. as opposed to an IMAP4 Inbox which would be under an IMAP4 service and is a representation of the Inbox on an IMAP4 email server.
Central Repository centralised and secure storage facility for application settings
OBEX Object exchange protocol, used to send objects such as vCards or files between devices via infrared or Bluetooth.
GMXML XML parser / generator for use with SMIL formatted messages.
UID Unique Identifier, a 32 bit number allocated from a registry owned by Symbian
IPC Inter Process Communication
-MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
-MTM Registry A list of currently installed MTMs maintained by the message server.
-TLS Transport Layer Security, provides encryption of a TCP/IP socket.
-M-HTML Standard for including HTML in MIME email messages see http://www.ietf.org/rfc/rfc2557.txt
-MIME Specification for the format of email message bodies see http://www.ietf.org/rfc/rfc1341.txt
-RFC2822 The standard format for internet mail messages see http://www.ietf.org/rfc/rfc0822.txt
-SMTP Simple Mail Transport Protocol
-SID Secure Identification
-IMAP4 Internet Mail Access Protocol
-POP3 Post Office Protocol Version 3
-NBS Narrow Band Socket, in the messaging context this refers to the socket that is used to talk to the SMS stack for receiving and sending SMS messages
-SMS Short Message Service
-MMS Multimedia Message Service
-WAP Wireless Application Protocol
-WSP WAP Session Protocol
-HTTP Hypertext transfer protocol
-PDU Protocol Data Unit. This is the encoded form of SMS and MMS messages.
-Versit A consortium that defined standard formats for things like contacts (vCard) and calendar entries (vCals)
-SDP Service Discovery Protocol. A Bluetooth protocol that allows an applications to discover which services are available and to determine the characteristics of the services.
-SMIL Synchronized Multimedia Integration Language. Presentation language that is commonly used to define the contents of an MMS message.
-XML Extensible Mark-up Language
-DOM Document Object Model
-DTD Document Type Definition, a schema that defines the structure of an XML document.
-ESTORE Symbian OS component that provides stream based storage. Messaging uses the Permanent file store provided by ESTORE to store its index entries.
-Appendix A - Example Sequence Diagrams
-A.1 Copy to a Remote Service
-
-Figure 33 Sequence Diagram Showing Copying to a Remote Service
-Figure 33 shows a client copying a message to a remote service using the Messaging Client API. The message server then delegates the copy to the SMTP Server MTM. The Server MTM interprets the request as a request to send the message so it opens a connection to a remote SMTP server and sends the message. While the message is being sent the client can retrieve progress information from the CMsvOperation object that was returned by CMsvEntry::CopyL. The dark grey IPC line represents the split between the objects running in the client’s process space on the left and the message server’s process on the right.
-There are four basic steps:
-1. The client opens session with Message Server and creates a CMsvEntry set on the global outbox,
-2. The client then requests an asynchronous copy from the outbox to the SMTP service, a CMsvOperation object is returned. The message server loads the SMTP Server MTM and delegates the copy operation to it.
-3. The client requests progress from the CMsvOperation object, this request is passed through to the SMTP Server MTM. The client may repeat this step multiple times.
-4. The Server MTM finishes sending message. It moves the message to sent folder and completes the message server’s request. The message server completes the CMsvOperation object, which requests the final progress from the message server. The server returns the final progress and deletes the Server MTM. The CMsvOperation then completes the client’s original request.
-This diagram hides all of the internal working of the SMTP Server MTM, for information on this see below.
-A.2 SMTP Session
-
-Figure 34 Sequence Diagram Showing a SMTP Session
-Figure 34 shows the operation of the SMTP Server MTM after a request has come from the message server to copy a message to the SMTP service.
-1. SMTP Server MTM gets the request from the message server, it will build a selection of messages consisting of the union of the selection of messages passed in and the messages in the outbox that are associated with this SMTP service and are ready to be sent. The chain of classes are constructed, and a request is passed to networking to connect to the remote SMTP server, details of the server name and port are retrieved from the settings stored in the SMTP service entry.
-2. The component waits for the SMTP server to respond with a greeting indicating it is willing to talk, then sends EHLO to the server and waits for the response detailing the capabilities of the Server. After this step there could set steps to start using TLS and or SMTP AUTH depending on the SMTP settings.
-3. CImSmtpSession calls back into CMsgOutboxSend to retrieve the next message to be sent, then constructs a CImSmtpFile object to handle sending, for details on the sending see SMTP Email Send. When sending the email has completed the CImSmtpFile object is deleted.
-4. CImSmtpSession calls back into CMsgOutboxSend to retrieve the next message which returns saying there are no more messages. CImSmtpSession sends QUIT to the SMTP server and completes CMsgOutboxSend. CMsgOutboxSend deletes CImSmtpSession which tears down the connection to the SMTP server; it then completes the SMTP Server MTM. The Server MTM will then complete the message server and be deleted.
-A.3 SMTP Email Send
-
-Figure 35 Sequence Diagram Showing SMTP Transactions during Email Send.
-Figure 35 shows a CImSmtpFile object sending an email message to an SMTP server.
-1. Construct a CImSendMessage object, part of the imut component. Reset the SMTP Server
-2. Read address information from the CImHeader object stored in the message store, send address information to SMTP server.
-3. Use CImSendMessage object to read the message from the message store and generate RFC2822 message line by line. Send each line to the server as it is generated.
-4. Complete and send the message by sending a full stop to the SMTP server
-
-
-
-
-Messaging Symbian OS v7.0s, v8.0, v8.1, v9.0, v9.1 Architectural Description
-
-Status: Issued
-Team/Department : Messaging / Content & Messaging
-
-Contents
-1 INTRODUCTION 6
-1.1 PURPOSE AND SCOPE 6
-2 SUBSYSTEM OVERVIEW AND BACKGROUND 6
-3 MESSAGING ARCHITECTURE AND APIS 7
-3.1 SUBSYSTEM COMPONENTS 7
-3.1.1 Framework components 7
-3.1.1.1 Message Server and MTM architecture 7
-3.1.1.2 Schedule Send 7
-3.1.1.3 SendAs Version 1 7
-3.1.1.4 SendAs Version 2 7
-3.1.1.5 Watcher Framework 8
-3.1.1.6 Message URL Handler 8
-3.1.1.7 Bio Message Framework 8
-3.1.2 Plug-ins 8
-3.1.2.1 SMS 8
-3.1.2.2 CDMA SMS 8
-3.1.2.3 Email 9
-3.1.2.4 OBEX 9
-3.1.2.5 MMS 9
-3.1.2.6 GMXML 10
-3.1.2.7 Bio Message Plug-ins 10
-3.1.2.8 PCMTM 10
-3.1.2.9 Fax 10
-3.2 GENERAL DESCRIPTION 11
-3.2.1 Messaging / Message Server and MTM Architecture APIs 11
-3.2.1.1 Key Internal Relationships and Dependencies 11
-3.2.1.2 Key External Relationships and Dependencies 12
-3.2.1.3 API Purpose - Further Elaboration 13
-3.2.1.3.1 Message Store 13
-3.2.1.3.2 Data File Storage (pre - v9.0) 15
-3.2.1.3.3 Platform Security Compliant Message Store 16
-3.2.1.3.4 How message centres display the message store 17
-3.2.1.3.5 Message Type Module Architecture 19
-3.2.1.3.6 Message Server Client API 21
-3.2.2 Messaging / Send As APIs 22
-3.2.2.1 Key Relationships and Dependencies 22
-3.2.2.2 API Purpose - Further Elaboration 22
-3.2.2.2.1 SendAs API (pre – v9.0) 22
-3.2.3 Platform Security Compliant SendAs Server (v9.0 onwards) 23
-3.2.4 Messaging / Schedule Send APIs 24
-3.2.4.1 Key Relationships and Dependencies 24
-3.2.4.2 API Purpose - Further Elaboration 24
-3.2.4.2.1 Schedule Send 24
-3.2.5 Messaging / Watchers APIs 25
-3.2.5.1 Key Relationships and Dependencies 25
-3.2.5.2 API Purpose - Further Elaboration 25
-3.2.6 Messaging / Message URL Handler APIs 26
-3.2.6.1 Key Relationships and Dependencies 26
-3.2.6.2 API Purpose - Further Elaboration 26
-3.2.6.2.1 Message URL Handler Application 26
-3.2.6.2.2 Message URL Recognisers 27
-3.2.7 Messaging / SMS APIs 27
-3.2.7.1 Key Internal Relationships and Dependencies 27
-3.2.7.2 Key External Relationships and Dependencies 28
-3.2.7.3 API Purpose - Further Elaboration 28
-3.2.7.3.1 SMS Watchers 28
-3.2.7.3.2 SMS Client MTM 29
-3.2.7.3.3 SMS Utilities 29
-3.2.7.3.4 SMS Server MTM 30
-3.2.8 Messaging / CDMA SMS APIs 31
-3.2.8.1 Key Internal Relationships and Dependencies 31
-3.2.8.2 Key External Relationships and Dependencies 32
-3.2.8.3 API Purpose - Further Elaboration 32
-3.2.8.3.1 CDMA SMS Watchers 32
-3.2.8.3.2 CDMA SMS Client MTM 33
-3.2.8.3.3 CDMA SMS Utilities 33
-3.2.8.3.4 CDMA SMS Server MTM 33
-3.2.8.3.5 Configuration for using CDMA SMS MTM 34
-3.2.9 Messaging / Email APIs 35
-3.2.9.1 Key Internal Relationships and Dependencies 35
-3.2.9.2 Key External Relationships and Dependencies 36
-3.2.9.3 API Purpose - Further Elaboration 36
-3.2.9.3.1 Email Overview 36
-3.2.9.3.2 Email Client Utilities 37
-3.2.9.3.3 Email Server MTM Utilities 37
-3.2.9.3.4 POP3 MTMs 37
-3.2.9.3.5 IMAP4 MTMs 38
-3.2.9.3.6 SMTP MTMs 40
-3.2.9.3.7 Autosend 40
-3.2.10 Messaging / MMS APIs 40
-3.2.10.1 Key Internal Relationships and Dependencies 41
-3.2.10.2 API Purpose - Further Elaboration 41
-3.2.10.2.1 MMS Overview 41
-3.2.10.2.2 MMS Utilities 42
-3.2.10.2.3 MMS Watcher 43
-3.2.10.2.4 MMS Client MTM 43
-3.2.10.2.5 MMS Server MTM 44
-3.2.10.2.6 MMS Codec 45
-3.2.11 Messaging / BIO APIs 46
-3.2.11.1 Key Internal Relationships and Dependencies 46
-3.2.11.2 API Purpose - Further Elaboration 47
-3.2.11.2.1 BIO Overview 47
-3.2.11.2.2 BIO MTM 47
-3.2.11.2.3 BIO Database 48
-3.2.11.2.4 BIO Parsers 48
-3.2.11.2.5 BIF Files and Utilities 48
-3.2.11.2.6 Platform Security Compliant Messaging / BIO APIs 49
-3.2.12 Messaging / OBEX MTM APIs 50
-3.2.12.1 Key Internal Relationships and Dependencies 50
-3.2.12.2 OBEX MTM Overview 50
-3.2.12.2.1 OBEX MTM 50
-3.2.12.2.2 IR MTM 51
-3.2.12.2.3 Bluetooth MTM 51
-3.2.12.2.4 OBEX MTM Utils 52
-3.2.12.2.5 Platform Security Compliant Messaging / OBEX MTM APIs 52
-3.2.13 Messaging / GMXML APIs 52
-3.2.13.1 Key Relationships and Dependencies 52
-3.2.13.2 Overview 53
-3.2.13.2.1 GMXML DOM 53
-3.2.13.2.2 GMXML Parser and Composer 53
-3.2.13.2.3 GMXML SMIL DTD (Validator) 53
-4 SECURITY 54
-4.1 DATA CAGING 54
-4.2 BACKUP AND RESTORE 54
-4.3 CAPABILITY RANGES 54
-4.3.1 Capabilities granted to executables 54
-4.3.2 Capabilities granted to DLLs 55
-4.3.3 Capabilities required to use the subsystem 57
-5 FURTHER INFORMATION 59
-5.1 REFERENCES 59
-5.2 OPEN ISSUES 59
-5.3 GLOSSARY 60
-APPENDIX A - EXAMPLE SEQUENCE DIAGRAMS 62
-A.1 COPY TO A REMOTE SERVICE 62
-A.2 SMTP SESSION 64
-A.3 SMTP EMAIL SEND 66
-
-Table of Figures
-Figure 1 Where Messaging Lives 6
-Figure 2 MTM Relationships 11
-Figure 3 External Dependencies 12
-Figure 4 Message Store 13
-Figure 5 Series 60 Inbox List View 14
-Figure 6 Remote and Local Entries 14
-Figure 7 Email Message 15
-Figure 8 Series 60 Message Centre (Composed from 2 screen shots) 17
-Figure 9 UIQ Message Centre 18
-Figure 10 Messaging MTM Structure (light coloured components are part of messaging subsystem) 19
-Figure 11 Nokia 9210 Outbox List View 20
-Figure 12 SendAs Version 1 Dependencies 22
-Figure 13 SendAs Version 2 Dependencies 23
-Figure 14 Schedule Send Dependencies 24
-Figure 15 Watcher Dependencies 25
-Figure 16 Message URL Handler Dependencies 26
-Figure 17 SMS Internal Dependencies 27
-Figure 18 SMS External Dependencies 28
-Figure 19 CMDA SMS Internal Dependencies 31
-Figure 20 CDMA SMS External Dependencies 32
-Figure 19 Email Internal Dependencies 35
-Figure 20 Email External Dependencies 36
-Figure 21 MMS Internal Dependencies 41
-Figure 22 MMS Utilities External Dependencies 42
-Figure 23 MMS Watcher External Dependencies 43
-Figure 24 MMS Client MTM Dependencies 43
-Figure 25 MMS Server MTM Dependencies 44
-Figure 26 BIO Message Internal Dependencies 46
-Figure 27 Bio Parser External Dependencies 47
-Figure 26 BIO Message Dependencies (v9.0) 49
-Figure 28 OBEX Internal Dependencies 50
-Figure 29 OBEX External Dependencies 51
-Figure 30 IR MTM Dependencies 51
-Figure 31 Bluetooth MTM Dependencies 52
-Figure 32 GMXML Dependencies 52
-Figure 33 Sequence Diagram Showing Copying to a Remote Service 62
-Figure 34 Sequence Diagram Showing a SMTP Session 64
-Figure 35 Sequence Diagram Showing SMTP Transactions during Email Send. 66
-1 Introduction
-1.1 Purpose and Scope
-The Messaging Architectural Description details the architecture and APIs exposed by the Messaging Subsystem. This document does not attempt to list all functionality provided by the messaging subsystem. For details on the functionality provided and the specifications implemented by the messaging subsystem see the Messaging Functional Description [R1]. This document describes the general architecture of messaging subsystem. Information related to a particular release version is mentioned with relevant release number.
-2 Subsystem Overview and Background
-The Messaging Subsystem provides an application level API to handle the storage and transport of different message types. It sits between messaging applications and the lower level subsystems which messaging uses for storage and transmission of messages.
-
-Figure 1 Where Messaging Lives
-The message types that messaging currently supports are Email (POP3, IMAP4 & SMTP), SMS, MMS and OBEX. The set of supported message types is extensible at run time by the use of plug-in modules that are responsible for the transmission and storage of a particular message type. This means that the set of components shown communicating with the network cloud depend on the message types installed.
-3 Messaging Architecture and APIs
-3.1 Subsystem components
-The Messaging subsystem components can be split into two categories: those components that form the framework and those that plug into the framework to support specific message types. This section briefly describes each of the components, more detailed descriptions of the components and their dependencies can be found in later sections of this document.
-3.1.1 Framework components
-3.1.1.1 Message Server and MTM architecture
-The message server is the core component in the messaging subsystem. It provides the message store used to contain messages. The Message Type Module architecture also allows plug-ins to add support for new message types to the messaging subsystem.
-Component Description
-messaging\framework\serverexe Executable that links to the server component and starts the message server
-messaging\framework\server Contains classes that make up both the client and server side of the message server API.
-messaging\framework\mtmbase Base classes for the plug-ins that handle the various message types
-3.1.1.2 Schedule Send
-The Schedule Send component is an extension to the framework that provides support for scheduling of operations such as sending messages. Message type modules that wish to support this functionality can use these support components to implement scheduling. For example the SMS MTM uses this to allow scheduled sending of SMS messages.
-Component Description
-messaging\schedulesend\schedulesendmtm Base classes that handle functionality for message server plug-ins that wish to enable scheduling of sending messages.
-messaging\schedulesend\schedulesendexe Executable use to provide schedule send behaviour.
-3.1.1.3 SendAs Version 1
-This version of SendAs is supported in releases pre - v9.0. SendAs provides a high level API for applications that wish to include a “Send As” menu to allow users to send content via one of the message types supported by messaging. The application using the API does not have to be aware of the message type selected by the user. Note the API does not send the messages.
-Component Description
-messaging\sendas High level API to allow creation of messages.
-3.1.1.4 SendAs Version 2
-From v9.0 and onwards the SendAs has been replaced with client server architecture based SendAs server. The client server architecture enhances secured platform implementation. The SendAs server polices the client application. If it is not trusted with required capabilities the SendAs server will refuse the client access. The client MTM for the message type can send a message with user permission even if the client does not have the correct capabilities.
-Component Description
-messaging\sendAsV2 High level API to allow the creation and sending of messages
-
-3.1.1.5 Watcher Framework
-The watcher framework is a lightweight framework to allow plug-ins to wait on events. For example there is an SMS watcher that waits for incoming SMS messages and delivers them to the message store. The watcher framework will only load plug-ins from ROM.
-Component Description
-messaging\framework\watcher Executable that loads and runs watcher plug-ins.
-3.1.1.6 Message URL Handler
-Support for recognising messaging URLs (mailto:, sms:, fax:, mms:), and then launching an editor with a new message.
-Component Description
-messaging\urlhandler\urlhandler An application that parses the URLs and then creates a correctly addressed message and launches a message editor.
-messaging\urlhandler\recogniser Recognisers that map from the URL schemes to the mime types.
-3.1.1.7 Bio Message Framework
-The Bio Message Framework provides a framework that supports plug-ins to handle messages like vCards and Internet access point set-up messages.
-Component Description
-messaging\biomsg\BDB\BIODB Classes to maintain the database of bio registration files.
-messaging\biomsg\BIFU\BIFU Classes for reading and writing bio registration files
-messaging\biomsg\BIOC\BIOC Bio message client MTM, this is in the framework section as it forms part of the bio messaging framework it is also a plug-in to the messaging framework.
-messaging\biomsg\BIOS\BIOS Bio message server MTM, this is in the framework section as it forms part of the bio messaging framework it is also a plug-in to the messaging framework.
-3.1.2 Plug-ins
-3.1.2.1 SMS
-The SMS plug-ins provide application level support for the Short Message Service messages.
-Component Description
-messaging\biomsg\BioWatchers Plug-ins to the watcher framework to listen for SMS, WSP, and WDP messages and deliver them to the global inbox in the message store.
-messaging\sms\clientmtm A plug-in to the message server framework to provide a generic API for creation of SMS messages (SMS Client MTM & SMS utilities)
-messaging\sms\servermtm A plug-in to the message server framework to provide a generic API for sending of SMS messages (SMS Server MTM)
-3.1.2.2 CDMA SMS
-The CDMA SMS plug-ins provide application level support for the CDMA Short Message Service messages.
-Component Description
-messaging\biomsg\BioWatchersCdma Plug-ins to the watcher framework to listen for CDMA SMS messages and deliver them to the global inbox in the message store.
-messaging\sms\multimode\clientmtm A plug-in to the message server framework to provide a generic API for creation of CDMA SMS messages (CDMA SMS Client MTM)
-messaging\sms\multimode\servermtm A plug-in to the message server framework to provide a generic API for sending of CDMA SMS messages (CDMA SMS Server MTM)
-
-3.1.2.3 Email
-The email plug-ins provide support the POP3, IMAP4 and SMTP email protocols and support for parsing and generating plain test, MIME and M-HTML format email messages.
-Component Description
-messaging\email\clientmtms A plug-in to the message server framework to provide a generic API for creation of email messages (IMAP4 SMTP and POP3 Client MTMs & email utilities)
-messaging\email\imapservermtm A plug-in to the message server framework to provide a generic API for access to a remote IMAP4 server (IMAP4 Server MTM)
-messaging\email\smtpservermtm A plug-in to the message server framework to provide a generic API for access to a remote SMTP server (SMTP Server MTM)
-messaging\email\popservermtm A plug-in to the message server framework to provide generic API for access to remote POP3 server (POP3 Server MTM)
-messaging\email\servermtmutils Email utilities for parsing plain text and MIME email messages. It also provides an abstraction of the TCP/IP sockets for use by the SMTP POP3 and IMAP4 plug-ins.
-messaging\email\autosend An executable that requests SMTP Server MTM to send messages in the outbox. This is used to provide send on next connection functionality and is started by the POP3 and IMAP4 Client MTMs.
-3.1.2.4 OBEX
-The OBEX MTM is a set of plug-ins to the message server that provides support for IR and Bluetooth beaming.
-Component Description
-messaging\obex\btmtm\btclient\group\btcmtm Bluetooth Client MTM
-messaging\obex\btmtm\btserver\group\btsmtm Bluetooth Server MTM
-messaging\obex\irmtm\irclient\group\ircmtm IR Client MTM
-messaging\obex\irmtm\irserver\group\IRSMTM IR Server MTM
-messaging\obex\obexmtm\obexclient\group\obexClientMtm OBEX Client MTM, base classes for the Bluetooth and IR Client MTMs
-messaging\obex\obexmtm\obexserver\group\obexServerMtm OBEX Server MTM, base classes for the Bluetooth and IR Server MTMs
-messaging\obex\obexmtm\obexutil\group\obexMtmUtil OBEX MTM utilities
-3.1.2.5 MMS
-The MMS MTM is a plug-in to the message server that provides support for MMS messages. From v9.0 and onwards MMS MTM and related components are removed.
-Component Description
-messaging\mms\utils MMS Utilities
-messaging\mms\servermtm MMS Server MTM
-messaging\mms\mmswatcherplugins MMS plug-ins to WAP push framework to handle reception of MMS notifications
-messaging\mms\codec MMS utilities for handling MMS codecs
-messaging\mms\clientmtm MMS Client MTM
-3.1.2.6 GMXML
-GMXML is a parser/generator for SMIL presentations for MMS messages.
-Component Description
-messaging\GMXML\XMLParser XML parser designed for parsing of SMIL messages
-messaging\GMXML\XMLDom XML document object model designed for parsing of SMIL messages
-messaging\GMXML\SMILdtd SMIL DTD
-3.1.2.7 Bio Message Plug-ins
-These parsers plug into the bio messaging framework to handle specific types of bio message.
-Component Description
-messaging\biomsg\cbcp\CBCP Compact business card parser
-messaging\biomsg\enp\ENP Email notification parser
-messaging\biomsg\gfp\gfp General file parser
-messaging\biomsg\iacp\IACP Nokia Smart Message Internet Access Parser
-messaging\biomsg\wapp\wapp Nokia/Ericsson OTA Parser
-3.1.2.8 PCMTM
-Plug-in to the message server that provided email synchronisation with a PC. This component has been deprecated in 8.0a and will not been documented in the API section below.
-3.1.2.9 Fax
-Plug-in to the message server that provides fax support. This component has been deprecated in 8.0a and will not been documented in the API section below.
-
-3.2 General Description
-3.2.1 Messaging / Message Server and MTM Architecture APIs
-3.2.1.1 Key Internal Relationships and Dependencies
-
-Figure 2 MTM Relationships
-Figure 2 shows the relationship between the Message Server and the MTM plug-ins. The grey classes are realisations of the MTM interfaces defined by the messaging framework. The message server depends on the Server MTM interface. Messaging Clients depend on the Client, UI and UI Data MTM interfaces and the Message Server Client API.
-3.2.1.2 Key External Relationships and Dependencies
-
-Figure 3 External Dependencies
-The grey package representing the messaging client depends on the Client, UI and UI Data interfaces and the Messaging Client API. The message server then depends on:
-• Charconv – Provides character set conversion routines, used to convert encoded message body text to Unicode body text.
-• EStore – Provides API to handle a stream based store used for the messaging index file and the framework classes for the message store files. (omitted from other dependency diagrams as it is implied by the dependency on the message server)
-• F32 – Provides the file server APIs used to access the file system directories in which messaging stores files containing message data. (omitted from other dependency diagrams)
-• BAFL – Provides API to load the correct messaging resource file dependent on the current language and to register the message store index file with the backup server. (omitted from other dependency diagrams)
-• ETEXT – Rich text APIs used to store body text of messages, this rich text format is a Symbian Proprietary format. (omitted from other dependency diagrams)
-• EUSER – Core Symbian OS utilities such as descriptors, arrays, client / server framework, cleanup stack and others (omitted from this and other dependency diagrams).
-• Central Repository – Centralised and secure storage facility for application settings, the message server stores message settings data in the central repository (from v9.0 and onwards).
-Note that debug only dependencies such as the flogger have been omitted from dependency diagrams.
-3.2.1.3 API Purpose - Further Elaboration
-3.2.1.3.1 Message Store
-The message server provides persistent storage of messages and messaging account settings. It does this by providing a message store consisting of a tree of message entries. Multiple clients can access the message store simultaneously. Each entry in the tree can represent an email account, folder of messages, message part, etc.
-
-Figure 4 Message Store
-Figure 4 shows an example message store. The tree is broken down in to three levels:
-1. The Root entry. This entry is just present to tie the tree structure together
-2. Service entries. There is one local service under which local folders and messages are stored, and zero or more remote services. Remote services represent message accounts.
-3. Message & Folder entries. Messages and folders, under the local service represent messages stored on the device. Messages and folders under remote services represent a local copy of messages that are present on a remote server. For example under a POP3 email service you would have copies of all the messages present on the POP3 email server, or under an SMS service you might find SMS messages that are stored on a SIM.
-The message server controls access to the entries in the store. It enforces the three levels therefore attempts to create message or folder entries directly under the root entry will fail.
-The message server provides three types of storage for each entry in the message store:
-• Index entry - TMsvEntry - intended to provide enough information for UI to display list views as shown in Figure 5. This consists of two strings and various flags (read, complete, has attachments etc).
-• Stream based file store - CMsvStore – provides storage of streams of data associated with UIDs. A standard UID is defined for storing body text. Other UIDs are specific. For example the email MTMs define a UID for storage of MIME headers. Compared to the index entry information this is used to store larger objects and is extensible, at the cost of being slower to access. From v9.0 and onwards CMsvStore provides an Attachment API for managing attachments. The Attachment API should be used as attachments can no longer be accessed directly due to Platform Security.
-• Directory of files – normally used for attachments.
-The only storage type that is always present is the index entry. The stream store and the directory of files are optional.
-
-Figure 5 Series 60 Inbox List View
-
-Figure 6 Remote and Local Entries
-As shown in Figure 6 the message store is split into two sets of entries:
-• Remote entries - entries that are representations of entries stored on a remote store .
-• Local entries - entries not linked to a remote store.
-The message server handles changes to local entries; internally it hands off changes to remote entries to the Server MTM that owns that service. Examples of operations that are handed off to Server MTMs are operations involving copying and moving messages to and from a remote service. See section 3.2.1.3.5 or more information on Server MTMs.
-Each entry within the store has a type:
-Folder – Messages can be grouped into folders. Standard folders such as inbox / outbox and user created folders.
-Message – Storage of the content of a message. Message entries can have child entries used to represent the structure of a message.
-Attachment – These represent attachments under a message entry.
-Root & Local Service Entry – There tie the tree structure together. However the Stream store associated with the root entry is sometimes used by UIs to store preferences e.g. default folder views etc.
-Remote Service - Represents a source and / or destination for messages. They are used to store the settings associated with the source / destination.
-Message Type Specific - MTMs can create other message types for use as child entries to messages they own. For example email uses a tree structure, with a message entry as the root, to represent the MIME structure of an email message; it uses folder entries to represent MIME folders and adds new types for entries representing the html body and text body parts of a message. This is shown in Figure 7.
-
-Figure 7 Email Message
-Using the message store to represent message structure allows reuse of the tree structure and makes it very simple to represent one message embedded in another. However this representation introduces performance issues as it results in each message having multiple files associated with it. The message server also keeps all index entries in memory; therefore this representation increases the memory footprint of the message server. Therefore when designing new MTMs we should think about moving away using multiple index entries to store one message in the message store.
-A default message store is created if the message server starts and no message store is present or a corrupt message store is present. The server will initially create a store with just a root entry, and then the server will create any standard folders defined in the resource file msgs.rsc. Finally the server will check whether an executable ‘mailinit.exe’ is present on the system, if it is present the server will launch the executable to allow customisation of the message store. The behaviour of ‘mailinit.exe’ is defined by the UI family of the device. However the typical behaviour is to load each of the UI Message Type Modules and allow each to perform any message type specific initialisation. For example the SMS plug-in typically creates a default service entry.
-
-3.2.1.3.2 Data File Storage (pre - v9.0)
-This section describes the files used by the message server before release v9.0. For information on the files used for release from v9.0 and onwards see section [3.2.1.3.3.1].
-Filename Access Purpose
-?:\system\Mail\index Private Message server index file, internal to message server
-?:\system\Mail\<8 hex digits> Shared via API Message server store files for services, clients access these via a messaging API.
-?:\system\Mail\<8 hex digits>.new Shared via API Temporary file used during committing message server store files.
-?:\SYSTEM\MAIL\<8 HEX DIGITS>_F\* Shared Files associated with a messaging service. These may be accessed directly by clients.
-?:\system\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits> Shared via API Message server store files for message entries, clients access these via a messaging API.
-?:\system\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits>.new Shared via API Temporary file used whilst committing message server store files.
-?:\system\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits>_F\* Shared Files associated with a message entry. These are accessed directly by clients.
-c:\system\data\msgs.ini Private Stores the drive containing the last used message store
-c:\system\Mtm\Mtm Registry v2 Private Cache of registered MTMs, internal to message server
-C:\system\data\sms_settings.dat Shared Copy of the SMS settings.
-?:\System\Mail\StoreInit.tmp Shared Created when message server runs ‘mailinit.exe’, ‘mailinit.exe’ should delete the file when it has successfully completed.
-?:\System\Mail\storedeleted.tmp Shared Created when message server finds and deletes a corrupt message store. Allows the UI to inform the user about the fact that the message store was corrupt.
-Files that are shown as private should only be accessed by the message server or by connectivity process for backup and restore purposes. Files listed as shared are accessed directly by messaging clients. Files listed as shared via API are accessed by client process but only via messaging APIs.
-3.2.1.3.3 Platform Security Compliant Message Store
-From v9.0 and onwards the message store is stored in the message server's data cage and the settings data are placed in the Central Repository. Access to the message store is only possible via message server APIs and not directly through file access. This leads to secured data storage and secured platform.
-3.2.1.3.3.1 Data caging
-Filename Purpose
-?:\private\<SID>\Mail\index Message server index file, internal to message server
-?:\ private\<SID>\Mail\<8 hex digits> Message server store files for services, clients access these via a messaging API.
-?:\ private\<SID>\Mail\<8 hex digits>.new Temporary file used during committing message server store files.
-?:\ private\<SID>\Mail\<8 hex digits>_F\* Files associated with a messaging service. These may be accessed directly by clients.
-?:\ private\<SID>\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits> Message server store files for message entries, clients access these via a messaging API.
-?:\ private\<SID>\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits>.new Temporary file used whilst committing message server store files.
-?:\ private\<SID>\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits>_F\* Files associated with a message entry. These are accessed directly by clients.
-c:\ private\<SID>\data\msgs.ini Stores the drive containing the last used message store
-c:\ private\<SID>\Mtm\Mtm Registry v2 Cache of registered MTMs, internal to message server
-?:\ private\<SID>\Mail\StoreInit.tmp Access via IPC call
-?:\ private\<SID>\Mail\storedeleted.tmp Created when message server finds and deletes a corrupt message store. Allows the UI to inform the user about the fact that the message store was corrupt.
-?\resource\messaging\bif\*.bif Registration data field with UID used in BIO framework
-
-3.2.1.3.4 How message centres display the message store
-The UI normally provides a Message Centre application to display the structure of the message store to the user. Different UIs map the structure to different views.
-
-Figure 8 Series 60 Message Centre (Composed from 2 screen shots)
-Figure 8 shows the top level view of the message centre application on a Series 60 phone. This shows that the message centre has hidden the local service and shows the standard folders at the same level as the services. Also the SMTP, SMS and MMS services are marked as hidden entries in the message store, and so do not appear in the message application.
-
-Figure 9 UIQ Message Centre
-However Figure 9 shows that the UIQ message centre has no 1-1 mapping from the structure in the message store to the structure shown to the user. Each of the message types is displayed as if its messages were contained in separate folders. Under each of these folders the user is presented with an inbox, outbox, send and drafts folder. This filtering is done in the UI layer as this functionality is not provided by the messaging API.
-3.2.1.3.5 Message Type Module Architecture
-
-Figure 10 Messaging MTM Structure (light coloured components are part of messaging subsystem)
-The MTM architecture is the plug-in scheme provided by the messaging framework to integrate different message transports into the message server. The plug-in scheme consists of four interfaces, the UI MTM, UI Data MTM, Client MTM and Server MTM. The messaging client applications loads and uses the first three which are loaded within the client’s process space. The final one the Server MTM is loaded within the message server process. The APIs for the client facing interfaces are extensible via run time type information provided by the QueryCapability API, and the InvokeAsyncFunction and InvokeSyncFunction APIs.
-3.2.1.3.5.1 UI MTM
-Handles requests from clients to view and edit messages or service settings. The MTM handles interaction with the message centre and as such the exact meaning of the APIs is defined by the UI. However common meanings are:
-• Create – Launches the editor with a new message.
-• Edit – If entry is a message this launches the editor; if entry is a service it edits the settings.
-• View – Launches the message viewer.
-• Display progress of an operation.
-3.2.1.3.5.2 UI data MTM
-This MTM provides fast access to UI components such as menu resources and bitmaps required by message centre for list views etc. Again the exact semantics are UI specific.
-There is a resource file defining UI specific functions, for example the Series 60 Messaging UI checks if the resource file contains text to display in the “New Message” menu.
-The UI data MTM also provides mapping from the message store’s TMsvEntry structure to Icons for the messaging list views and a status string, for example in the case of Nokia 9210 it is used in the outbox view to provide strings like “Resend 01:07” as shown in Figure 11. The class also provides functions to determine what operations are possible with a given entry. Examples of this are APIs that return whether the UI should allow the user to reply to the entry or to delete a service entry. The UI then uses this information to determine which menu options / short-cut keys should be allowed when the user selects a given entry.
-
-Figure 11 Nokia 9210 Outbox List View
-3.2.1.3.5.3 Client MTM
-Provides methods to create / reply and forward messages. Functions the Client MTMs provide are:
-• Create Message.
-• Reply to a Message.
-• Forward a Message.
-• Add / remove Addressees.
-• Add / remove body text.
-• Add / remove subject.
-• Add / remove attachments (the API cannot list attachments).
-The Client MTM interface is used by SendAs to provide a way of creating messages independently of the message type.
-3.2.1.3.5.4 Server MTM
-This is the final interface that makes up an MTM plug-in; it differs from the other three plug-ins in that it is loaded into the message server’s process space. The Server MTM provides access to messages under remote services. It handles connecting to remote servers to handle updating the local cache of these messages or to send messages copied to remote services when messages are copied to a remote service. The message server loads and hands off all message store operations that involve entries under a remote entry, these are the entries on the left-hand side of Figure 6.
-Functions that a Server MTM must implement:
-• Copy/MoveToLocal – called when the message server is asked to move or copy an entry that is currently under a remote service. A Server MTM might map this to retrieving a message from a remote mailbox.
-• Copy/MoveFromLocal – called when the message server is asked to move or copy from under the local service to a destination under a remote service. A Server MTM should map this to sending a message if the MTM supports sending.
-• Create, Delete, Change – called when the message server is asked to perform these operations on entries under a remote service.
-• StartCommand – this API provides a means of extending the API the Server MTM provides. Messaging clients pass a command ID and a selection of entries via the message server to the Server MTM. Examples of commands that Server MTMs might provide are: connect and synchronise the entries under a remote service with the messages on an email server, list SMS messages present on the phones SIM. These commands are MTM specific and therefore clients have to know which MTMs support which commands.
-3.2.1.3.5.5 MTM Registration
-MTMs must be registered with the message server so that clients can query what MTMs are present and the server knows which DLL to load to create a given MTM component. MTMs are registered by providing a resource file containing the MTMs UIDs, human readable name, and for each MTM interface it lists a DLL and the ordinal at which the constructor for that interface exists. The message server will search the ROM drive for MTM registration resource files on start-up and it will automatically register any MTMs found. For registration of MTMs installed on other drives, the message server provides an API to register and de-register an MTM. Registration will persist across a reboot, so an MTM only needs to be registered when it is installed on the system.
-When MTMs are registered or unregistered the message server will send events to all messaging clients with a message server session open.
-3.2.1.3.6 Message Server Client API
-The Messaging Server Client API breaks down into two categories: APIs for manipulation of the message store and utility APIs.
-3.2.1.3.6.1 Message Store manipulation APIs
-Requests from clients to modify the message store fall into three categories:
-1. Operations performed entirely with local entries (entries on the right-hand side of Figure 6) for example requests to create entries in the inbox, delete an entry from the drafts folder etc. The message server handles these operations directly.
-2. Operations that involve a remote entry (entries on the left-hand side of Figure 6) for example requests to delete an entry under a POP3 service, or copy a message to an SMTP service. The message server hands these operations off to the Server MTM that owns the service under which the remote entry is stored. The only exception to this rule is the ChangeAttributes API call. This modifies flags on an index entry and is handled by the message server for both local and remote entries. This means that a Server MTM can not rely on being called when flags like the Unread flag are changed. Note that operations can not involve two remote entries; therefore requests to copy entries between a remote service representing one POP3 account to a remote service representing another POP3 account will fail with an error.
-3. Requests that are explicitly directed at a Server MTM via the TransferCommand API. These commands are just passed to the correct Server MTM by looking up the Service ID and MTM of the first message in the selection passed into the command.
-The message server sends events when entries in the message store are modified to messaging clients that have a session open with the server.
-Where the API provides asynchronous functions to modify the message store or transfer a command to a Server MTM, the functions will return a message server operation object. This object can be used to request progress on operation or cancel the operation. Deleting the operation object returned, or closing the session used to make the request will result in the operation being cancelled, therefore a messaging client must remain running until operations it has requested have either completed or they will be cancelled. See appendix A.1 for an example of an asynchronous copy operation. If a Server MTM operating on the same remote service is already handling an operation, the message server will queue the new operation to be handled when the Server MTM becomes free. Requests for progress of operations that are queued will fail with KErrNotReady. The fact that the queue is based on the remote service ID means that you can have two Server MTMs of the same type running at the same time as long as they are operating on different services. So for example you can have two separate POP3 MTMs running synchronising different remote services with email servers.
-3.2.1.3.6.2 Utility APIs
-1. Access to MTM registries – These allow clients to construct instances of the interfaces an MTM implements.
-2. Register / Unregister an MTM.
-3. Change Drive – The message server closes the current message store and opens one on the drive specified. If no message store is present on the drive specified a new message store is created. The message sever can have only one mail store open at a time, if the current mail store is not available because a the disk the mail store is on is not present then the message server will switch the mail store back to the C: drive if an attempt is made to create a message in the inbox.
-4. Launching Editors – This launches the correct editor for a message. It is implemented by delegating the request to the UI MTM
-3.2.2 Messaging / Send As APIs
-3.2.2.1 Key Relationships and Dependencies
-
-Figure 12 SendAs Version 1 Dependencies
-SendAs version 1 and only present in releases before v9.0. SendAs uses the Messaging Client API to access the registry of Client MTMs and construct the Client MTM interfaces. The Client MTMs are then used for composing the message. SendAs requires clients to implement the MSendAsObserver interface. This interface is responsible for checking the return value of the capability queries made to Client MTMs that require a response and also for rendering message types that require it. The only message type supplied by Symbian that requires rendering is Fax, however this MTM has been removed in 8.0a and future releases.
-3.2.2.2 API Purpose - Further Elaboration
-3.2.2.2.1 SendAs API (pre – v9.0)
-The SendAs API makes use of the Client MTM interface and the Messaging Client API to provide a generic API for creating messages. Note despite the name of this component SendAs does not provide an API to send the message.
-SendAs builds a list of registered MTMs, then queries each MTM to check whether it supports sending, removing those MTMs from the list that do not support sending. This list is then provided to the messaging client application. At this point the application can add more constraints on the list of MTMs; for example it can insist the MTM supports Attachments or more than a certain size of body text. SendAs queries each of the MTMs about the requirements and will drop any MTMs from the list that does not meet them. When the application has finished adding requirements it selects one of the MTMs left in the list and uses that to compose the message, adding addresses, a subject, body text and attachments.
-SendAs supports setting a BIO Type for the message that is composed. This tells the transport that the body text represents a BIO Message. This is used when sending business cards from the contacts application as SMS messages; the contacts application puts the vCard data in the body text of the message and the transport sends it correctly. If the MTM in question supports attachments then the vCard is attached to the message.
-A new CSendAs object must be created for each message the application wishes to create.
-3.2.3 Platform Security Compliant SendAs Server (v9.0 onwards)
-
-Figure 13 SendAs Version 2 Dependencies
-From v9.0 and onwards the CSendAs has been replaced by the SendAs server component. The new SendAs server controls the access to the message store. Some of the key SendAs Server features are listed as follows.
-• Send a message once the capability policing of the client application has been completed.
-• Allow client applications to launch an editor for a specified message type.
-• Allow client applications to query the message type.
-The main client-side API is the RSendAs class. The client applications use this to connect to the Send-As server. The session object on the server-side is an instance of CSendAsSession.
-Client applications create messages using the RSendAsMessage API. Opening an RSendAsMessage object on Send-As server session creates a CSendAsMessage object in the Send-As server. There is a one-to-one mapping between an RSendAsMessage object and a CSendAsMessage object. This allows client applications to create multiple messages concurrently.
-
-3.2.4 Messaging / Schedule Send APIs
-3.2.4.1 Key Relationships and Dependencies
-
-Figure 14 Schedule Send Dependencies
-The Schedule Send Server MTM base class depends on the task scheduler to launch the schedule send executable at the correct time. To send the message with a package of data previously passed into the task scheduler by the Server MTM. The schedule send executable then uses the Messaging Client API to actually perform the requested operation.
-3.2.4.2 API Purpose - Further Elaboration
-3.2.4.2.1 Schedule Send
-The Schedule Send functionality is delivered by four components:
-Server MTM Base Class – The base class provides support to Server MTMs that wish to support scheduled operations.
-Data Structures – These are classes used to represent the data associated with a scheduled operation.
-Executable – The executable is run by the task scheduler at the scheduled time.
-The Task Scheduler – This component is part of the system libraries subsystem. Currently the SMS and Fax Server MTMs support scheduled sending.
-Clients request the Server MTM schedules operations via additional commands passed to TransferCommand API; this is passed to the Server MTM via the message server. The Server MTM packages the operation ID, a selection of message IDs, how often to poll for progress and an MTM specific buffer. It then passes this package of data to the task scheduler requesting that it launches the schedule send executable at the correct time with the packaged information.
-When the task scheduler launches the schedule send executable, it unpacks the schedule information and uses the Messaging Client API to request the Server MTM to perform the operation.
-Schedule Send supports a retry mechanism if the operation fails. The Server MTM has a resource file containing a mapping from the error codes the operation can fail with and actions to be performed. For example the SMS resource file has a mapping such that if the operation fails with an error code indicating a bad phone number the SMS will be set to failed and left in the outbox. Whereas if it fails with a error code indicating temporary network failure the send operation will be scheduled to be resent later with a maximum of three retries.
-3.2.5 Messaging / Watchers APIs
-3.2.5.1 Key Relationships and Dependencies
-
-Figure 15 Watcher Dependencies
-The watcher executable’s dependency on the message server is the result of a performance measure. The watcher process creates a message server session before initialising each of the watcher plug-ins and closes the session when it has finished. This keeps the message server running during initialisation avoiding starting and stopping the message server if each watcher plug-in opens and closes sessions.
-3.2.5.2 API Purpose - Further Elaboration
-The watcher framework consists of an executable that is launched when the device boots. The component that is responsible for launching it depends on the UI family. When the watcher.exe is launched it will load each DLL in z:\system\libs\watchers which has a second UID as KWatcherUid and calls the first DLL entry point to construct a CActive object.
-From v9.0 and onwards watcher DLLs are found by scanning the directory \resource\messaging\watchers for registry files. These files contain the name of a watcher DLL that can be loaded from ROM i.e. z:\sys\bin.
-The framework has retry behaviour if the first entry point leaves, in this case the watcher framework will start a timer and try and construct the watcher object 10 seconds later. Five attempts are made before the watcher plug-in is assumed to have failed completely. Once the watcher framework has constructed all the watchers it starts the active scheduler which should never exit.
-Watcher plug-ins typically make a request to another subsystem such that they will be completed when an external event like a fax line ringing or an SMS being received occurs. When the watcher has completed processing the request it will wait for the next event.
-No support for starting / stopping watchers is provided. This is a limitation that makes watchers unsuitable for operations like listening for messages beamed via IR, as the watcher should only run while the IR port is active.
-3.2.6 Messaging / Message URL Handler APIs
-3.2.6.1 Key Relationships and Dependencies
-
-Figure 16 Message URL Handler Dependencies
-3.2.6.2 API Purpose - Further Elaboration
-The Message URL Handler provides support for creating messages and launching messaging editors from URLs such as mailto:infobot@example.com?subject=current-issue. Note there is no dependency between the Message URL Handler application which processes the URLs and the Message URL Handler recognisers which maps from URLs to mime types.
-3.2.6.2.1 Message URL Handler Application
-This is a Symbian OS application that registers with the application framework that it can handle the mime types: x-epoc-url/fax, x-epoc-url/mailto and x-epoc-url/sms. When launched with a URL it will parse the URL to retrieve the address and other header fields and then use the SendAs API to create a new message with the correct address, headers etc. The application then uses the APIs in the MturUtils class provide by the mtmbase component in the messaging framework to launch the correct editor for the given message type. The application is marked as hidden and therefore should not be listed by UIs in application browsers.
-3.2.6.2.2 Message URL Recognisers
-This is a plug-in to the recogniser framework it will be called when the application framework wishes to recognise a file. Recognisers are called with the file name, in this case a URL, and a buffer containing the start of the file. The message URL recogniser compares the start of the URL with the URL schemes it recognises, if it finds a URL scheme it knows about it maps it to a mime type. The recogniser ignores the buffer passed in.
-Schemes recognised:
-Scheme Mime type
-mailto: X-Epoc-Url/mailto
-fax: X-Epoc-Url/fax
-sms: X-Epoc-Url/sms
-mms: X-Epoc-Url/mms
-See the application framework architectural description for more information on recognisers [R2].
-3.2.7 Messaging / SMS APIs
-3.2.7.1 Key Internal Relationships and Dependencies
-
-Figure 17 SMS Internal Dependencies
-3.2.7.2 Key External Relationships and Dependencies
-
-Figure 18 SMS External Dependencies
-3.2.7.3 API Purpose - Further Elaboration
-3.2.7.3.1 SMS Watchers
-The SMS watchers are made up of two watchers, the nbswatcher.dll and the wapwatcher.dll, and some common base classes in biowatcher.dll. The watchers listen for incoming messages from the SMS stack, part of the nbsprotocols subsystem [R3], and the WAP stack part of the WAP-Stack subsystem [R4].
-3.2.7.3.1.1 NBS Watcher
-The NBS watcher handles reception of SMS messages. When initialised by the watcher framework (see section 3.2.4) the watcher queries the bio messaging database for bio messages that are listed as having a type of ENbs. For each of these bio messages the watcher creates an object that opens a connection to the SMS stack and waits for the particular message type. The message types are either defined by the port number the message will be received on or by a string to watch for at the start of the message. For example Internet Access Configuration Point messages are start with “//SIAP11” and vCards are received on port 226. Finally the watcher listens for all other messages received from the SMS stack.
-When the NBS Watcher receives a non-class 2 SMS message it creates a new entry under the global inbox in the message store. For class 2 messages the entry is created in the class 2 folder as defined by the SMS settings, this may also be the global inbox. The details field of the entry is used to store the phone number of the incoming message or the name of the sender if the watcher finds a match for the phone number in the contacts database. The description field is used to store the first N characters of the SMS message, where N is defined in the SMS settings, or for bio messages the description as retrieved from the bio database. Bio messages also have the BioType field set to the UID of the bio message as retrieved from the bio database. The CSmsHeader class, which is a wrapper around the CSmsMessage class provided by the nbprotocols subsystem [R3], is used to externalise the SMS message to the entry’s CMsvStore. The watcher also places a copy of the body text of the message in the rich text stream of the entry’s CMsvStore.
-The NBS Watcher is also responsible for handing special SMS types including:
-• Replace Type Messages – When the watcher receives a message of this type it will scan the folder the message would have been delivered to for messages that have a matching protocol ID and from address. For each of the messages it checks whether the time stamps from the service centre and discards the older message.
-• Message Indications – The watcher can listen for incoming message waiting indications. The CSmsSettings class defines whether the watcher will listen and whether it will deliver the messages to the inbox or discard them. If the watcher is configured to listen for messages then it will use the SMS utilities in the SMS Client MTM to decode the message to determine the notification type and number of messages, e.g. 3 Email messages waiting, the strings for these messages are in the smss.rss resource file.
-• Delivery Reports – As with Message Indications the watcher can be configured to listen for these and again the SMS utilities get a string from the smss.rss resource file to put in the description field.
-The NBS Watcher handles changes to the bio database using the observer mechanism provided by the bio message database to observe when bio message types are added or removed and starting or stopping the object watching for that bio message type.
-3.2.7.3.1.2 WAP Watcher
-The WAP watcher listens for incoming messages from the WAP stack using the WAP message API [R4]. To determine ports to use to listen for messages the watcher queries the bio message database for bio message types EWsp, EWspSecure, EWap, EWapSecure and registers as an observer of the bio database and so will listen for new bio message with these types as they are added. The watcher stores the messages in the global inbox tagged with the bio type listed in the bio message database.
-3.2.7.3.2 SMS Client MTM
-The SMS Client MTM implements the standard set of Client MTM APIs described in Client MTM. In addition it provides:
-• Access to the CSmsHeader object that is used to represent the SMS message.
-• Access to the SMS settings stored in the associated SMS service.
-• The APIs required by Send As to allow Send As to create SMS messages including setting the bio type of the message to allow clients of Send As to send bio messages such as vCards and vCals. The data of the bio message is stored in the body text of the SMS message.
-• Simple check for valid SMS addresses, and SMS address is considered valid if it contains at least one digit.
-• Reading and writing SIM parameters.
-3.2.7.3.3 SMS Utilities
-These provide:
-• Classes to represent and store SMS messages (CSmsHeader), and SMS settings (CSmsSettings, CSmsMessageSettings) and a SMS number (CSmsNumber).
-• The CSmsHeader class contains and allows clients to access the CSmsMessage class that the nbsprotocols subsystem provides. This contains the entire SMS message and not just the header.
-• Functions to generate descriptions and details fields to store with SMS messages, including decoding special messages such as message indication and status report messages, reading resource file for descriptions strings of special messages, using the contacts database to replace phone numbers with names.
-• API to validate a GSM number.
-• Find the TMsvId of the SMS service entry.
-3.2.7.3.4 SMS Server MTM
-3.2.7.3.4.1 Sending Messages
-The SMS Server MTM handles sending of SMS and WAP messages via the SMS stack and the WAP stack. To support this it implements the CopyFromLocal API inherited from the Server MTM base class. It implements this as sending SMS messages and moving successfully sent messages to the Sent folder. When sending the SMS message the Server MTM checks the bio type of the message and uses the bio database to check the transport type for the bio message. The MTM supports ENbs that is sent via the SMS stack and EWap, EWapSecure that are sent via the WAP stack. The MTM does not support EWsp or EWspSecure although the watchers do support receiving them.
-If a message fails to send, sending is retried according to the settings in the smss.rss resource file as described in the schedule send section 3.2.3.
-3.2.7.3.4.2 Scheduling Messages
-The SMS Server MTM implements scheduled sending API by sub-classing from the schedule send Server MTM (see section 3.2.3). It accepts requests from clients either via the SMS Client MTM InvokeAsync API or via the CMsvSession::TransferCommand API to schedule messages to be sent or to delete existing schedules. When it receives a request to schedule a message it packages up the command and uses the scheduled send functionality to request that the task scheduler ask it to send the messages at a future point in time.
-3.2.7.3.4.3 Phone Store
-The phone store is the name given to storage of SMS messages outside of the message store. In the case of GSM phones this is the SIM. The SMS Server MTM accepts requests from clients to copy/move messages to and from the SIM and delete messages from the SIM. For example when copying to the SIM it packages up the SMS message and passes it to the SMS stack with a request to write it to the SIM. If the class2 folder has been set in the SMS settings class then the Server MTM will copy the SMS message to the SIM and then update the SMS message in the message store with details of the slot on the SIM that has been used to store the SMS and the fact that it is stored on the SIM.
-3.2.7.3.4.4 SIM Parameters
-The Server MTM provides functions to read / write SIM parameters, again these requests are passed to the SMS stack to be processed.
-3.2.8 Messaging / CDMA SMS APIs
-3.2.8.1 Key Internal Relationships and Dependencies
-
-Figure 19 CMDA SMS Internal Dependencies
-3.2.8.2 Key External Relationships and Dependencies
-`
-Figure 20 CDMA SMS External Dependencies
-3.2.8.3 API Purpose - Further Elaboration
-3.2.8.3.1 CDMA SMS Watchers
-The CDMA SMS watchers are made up of six watchers, the cdmanbswatcher.dll, vmnwatcher.dll, wemtwatcher.dll, wmtwatcher.dll, wptwatcher.dll, and the wapwatcher.dll, and some base classes in biowatcher.dll and cdmasocketwatcher. While the WAP watcher is common for both GSM and CDMA, the other watchers: CDMA NBS watcher, VMN watcher, WEMT watcher, WMT watcher, and the WPT watcher are used for CDMA only. The watchers listen for incoming messages from the CDMA SMS stack, part of the nbsprotocols subsystem [R3], and the WAP stack part of the WAP-Stack subsystem [R4].
-3.2.8.3.1.1 CDMA NBS Watcher
-The CDMA NBS watcher is similar to the NBS watcher and it handles bio messages defined in bio database. The CSmsHeader class is extended to wrap around the CCdmaSmsMessage class provided by the nbprotocols subsystem [R3], and is used to externalise the CDMA SMS message.
-For handling special CDMA SMS type, the CDMA NBS watcher is responsible for handling Message Indications as described in section 3.2.7.3.1.1 NBS Watcher.
-3.2.8.3.1.2 WAP Watcher
-The GSM WAP watcher is used to handle CDMA WAP message as well. The WAP watcher listens for incoming messages from the WAP stack, which can listen from the CDMA SMS stack or GSM SMS stack as appropriate. See 3.2.7.3.1.2 for more info about WAP watcher.
-3.2.8.3.1.3 Other CDMA Watchers
-The VMN watcher, WEMT watcher, WMT watcher and WPT watcher are CDMA watchers that handle reception of CDMA SMS messages. All CDMA SMS messages are associated with a teleservice. Therefore, each of the CDMA watchers is responsible for handling one teleservice: VMN watcher handles VMN SMS messages, WEMT watcher handles WEMT SMS messages, WMT watcher handles WMT SMS messages, and WPT watcher handles WPT SMS messages. The CSmsHeader class is reused to externalise the CDMA SMS message.
-The CDMA watchers are also responsible for handling special SMS types including:
-• Duplicate Message – When the watcher receives a duplicate message, it will discard the duplicate message as defined by the CDMA service settings.
-• User Acknowledge – The watcher can listen for user acknowledgment message of its teleservice type.
-• Delivery Acknowledge – The watcher can listen for delivery acknowledgment message of its teleservice type.
-• Read Acknowledge – The watcher can listen for read acknowledgment message of its teleservice type.
-3.2.8.3.2 CDMA SMS Client MTM
-The CDMA SMS Client MTM implements the standard set of Client MTM APIs described in Client MTM. In addition it provides:
-• Access to the CSmsHeader object that is used to represent the SMS message.
-• Access to the SMS settings stored in the associated SMS service. These settings are store in file store pre v9.0 but stored in Central Repository from v9.0 onwards.
-• The APIs required by Send As to allow Send As to create SMS messages including setting the bio type of the message to allow clients of Send As to send bio messages such as vCards and vCals. The data of the bio message is stored in the body text of the SMS message.
-• Simple check for valid SMS addresses, and SMS address is considered valid if it contains at least one digit.
-• Reading and writing SMS messages to R-UIM.
-3.2.8.3.3 CDMA SMS Utilities
-The CDMA version of SMS utilities are binary compatible with the GSM version of SMS utilities. But the classes that store SMS Message (CSMSHeader), and SMS settings (CSmsSettings, CSmsMessageSettings) and SMS number (CSmsNumber) are extended to store CDMA information. The CSmsHeader class is extended to contain and allow clients to access the CCdmaSmsMessage in addition to the CSmsMessage. Other functions provided by the GSM SMS Utilities is also provided by the CDMA version of SMS utilities, see 3.2.7.3.3 for information about GSM SMS Utilities.
-3.2.8.3.4 CDMA SMS Server MTM
-3.2.8.3.4.1 Sending Messages
-The CDMA SMS Server MTM handles sending of CDMA SMS and WAP messages via the CDMA SMS stack and the WAP stack. To support this it implements the CopyFromLocal API inherited from the Server MTM base class. It implements this as sending SMS messages and moving successfully sent messages to the Sent folder. When sending the CDMA SMS message the Server MTM will use the appropriate teleservice type. The MTM supports ENbs that is sent via the SMS stack and EWap, EWapSecure that are sent via the WAP stack. The MTM does not support EWsp or EWspSecure although the watchers do support receiving them.
-If a message fails to send, sending is retried according to the settings in the smss.rss resource file as described in the scheduled send section 3.2.4.
-3.2.8.3.4.2 Scheduling Messages
-The CDMA SMS Server MTM implements scheduled sending API by sub-classing from the schedule send Server MTM similar to implemented in the GSM SMS Server MTM. See 3.2.7.3.4.2 for more information.
-3.2.8.3.4.3 Phone Store
-In the case of CDMA phones, phone store can be phone-based storage or R-UIM based storage. The CDMA SMS Server MTM accepts requests from clients to copy/move messages to and from the phone/R-UIM and delete messages from the phone/R-UIM. For example when copying to the R-UIM it packages up the SMS message and passes it to the CDMA SMS stack with a request to write it to the R-UIM.
-3.2.8.3.5 Configuration for using CDMA SMS MTM
-The CDMA messaging components currently only support single mode, but it is designed such that it can become multimode in the future. Currently, -Dcdma option is used to for selecting CDMA mode for using emulator and building ROM.
-
-
-3.2.9 Messaging / Email APIs
-3.2.9.1 Key Internal Relationships and Dependencies
-
-Figure 19 Email Internal Dependencies
-
-3.2.9.2 Key External Relationships and Dependencies
-
-Figure 20 Email External Dependencies
-3.2.9.3 API Purpose - Further Elaboration
-3.2.9.3.1 Email Overview
-The Email plug-ins consist of a set of utilities and MTMs for POP3, IMAP4 and SMTP. For each email account a pair of services entries is created in the message store. For a POP3 account there will be an SMTP service and a POP3 service, for an IMAP4 account there will be an SMTP service and as IMAP4 service. These entries are used to store the settings for the email transport. Each of the service entries has its related ID set to the other member of the pair. The SMTP service is created invisible so the user only sees the POP3 or IMAP4 service entry, copying a message to the SMTP service will cause the SMTP Server MTM to attempt to send the message. The POP3 and IMAP4 MTMs provide functionality to synchronise with a remote email server this is achieved by extending the Client MTM interface via the InvokeAsync API. Synchronisation of a POP3 or IMAP4 account will result in copying headers and optionally body text and attachments from the email server and creating message entries under the POP3 or IMAP4 service entry.
-Email messages are represented in a common format whether they are being sent via SMTP or downloaded via POP3 or IMAP4. The email client utilities provide the classes for creating and manipulating the entry structure used to store emails. The email server side utilities provide classes to convert between the entry structure used to store emails in the message store and RFC2822 email messages sent to SMTP servers and retrieved from POP3 servers. IMAP4 email messages are parsed by the email server and the IMAP4 Server MTM requests and stores the individual parts of the messages.
-3.2.9.3.2 Email Client Utilities
-The email client utilities are part of the imcm DLL and provide classes for:
-• Storage of email messages including mime headers, RFC2822 headers, attachments, body text and encoding information in the message store
-• Manipulating email messages, for example adding attachments, replying etc.
-• To wrap up the character converters used to convert between standard character sets and Unicode. These make use of the charconv component that is part of the system libraries subsystem.
-• Storage of Email settings in the message store.
-• Progress information for email operations.
-The utilities are used directly by clients to access parts of email messages for display. CImEmailMessage provides the functionality used by clients displaying email messages, including listing attachments, getting body text and resolving URIs in M-HTML messages.
-The Email Client MTMs use the utilities when they are asked to create, reply to and forward messages CImEmailOperation provides the functionality to perform these operations. Each email message is represented by a parent message entry and then entries to represent mime folders and mime parts, see Figure 7 for an example, so adding or deleting mime parts involves walking the tree of entries and inserting / removing entries as appropriate.
-3.2.9.3.3 Email Server MTM Utilities
-The Email Server MTM Utilities are responsible for generating and parsing of RFC2822 format email messages and providing an API to wrap up a TCP/IP connection to a remote email server.
-• Parsing of RFC2822 Email Messages – The utilities provide an API that accepts the text of an RFC2822 email message a line at a time and stores the email message in messaging’s internal format for email messages. See the Email Client Utilities for details of this format. The API handles storing of RFC2822 headers, MIME headers, decoding of Base64 encoded or uuencoded attachments and decoding of text received in character sets supported by the charconv component. This API is only accessible to Server MTMs, as it requires classes that can only be instantiated while running within the message server process. See the Messaging Functional Specification [R1] for detail on which email specifications the utilities support.
-• Generation of RFC2822 Email Messages – The utilities provide an API to convert an email in messaging’s internal format into an RFC2822 email message. The API provides access to the RFC2822 text a line at a time for streaming to an SMTP server. The exact format of the email depends on the settings passed in; the API can generate plain RFC2822 email messages with uuencoded attachments, MIME email messages with Base64 encoded attachments, or M-HTML email messages with Base64 encoded attachments. See the Messaging Functional Specification [R1] for detail on which email specifications the utilities support.
-• TCP/IP socket wrapper – The utilities provide a class that abstracts a TCP/IP socket supplied by the networking subsystem into an API that supports sending and receiving lines of text to / from a remote server. This API is used to connect to remote email servers by each of the email Server MTMs. The API can either create insecure or secure sockets enabling the SSL encryption provided by the networking subsystem. It also supports changing an insecure socket into a secure socket, this enables the email Server MTMs to implement email protocols where the initial connection to the server is insecure and then a secure socket is negotiated before sending or requesting any sensitive information.
-3.2.9.3.4 POP3 MTMs
-The POP3 MTMs implements the functionality to synchronise the local message store with a remote POP3 email server.
-3.2.9.3.4.1 Client MTM
-The POP3 Client MTM implements the standard Client MTM APIs and other extensions:
-• Reply to, forward – These are accessible via the ReplyL and ForwardL APIs of a Client MTM and are implemented as calls to the email utilities class CImEmailOperation.
-• Reply to, forward, create new messages, create receipts and forward as attachment – These are accessible as commands available via the InvokeAsyncFunction API of the Client MTM, they are implemented as calls to CImEmailOperation.
-• Connecting, disconnecting and copying email while connected – These operations are accessible as commands available via the InvokeAsyncFunction API of the Client MTM, they are implemented as calls to the POP3 Server MTM.
-• Querying connection status – This command lets clients know whether the POP3 Server MTM is connected to an email server, and is available via the InvokeAsyncFunction API of the Client MTM. The Client MTM requests the information from the Server MTM.
-• Compound operations – The Client MTM provides functionality to wrap up connecting to email servers, copying / moving new messages or a selection of messages, and then optionally disconnecting. These commands are available via the InvokeAsyncFunction API of the Client MTM. The Client MTM implements this by using the CImPOP3GetMail class which requests the correct sequence of operations from the Server MTM, waiting for each operation to complete before requesting the next one.
-• Send on next connection If the Client MTM gets a request to connect to an email server it will check whether the POP3 settings. If send on next connection is requested it will launch the autosend.exe executable (see section 3.2.7.3.7) to handle sending messages waiting in the outbox.
-• Offline operations – The POP3 Client MTM has a command to cancel offline operations, this is available via the InvokeAsyncFunction API of the Client MTM. The Client MTM passes the request to the Server MTM.
-3.2.9.3.4.2 Server MTM
-The POP3 Server MTM handles the communication with the remote POP3 server and implementation of the POP3 protocol. The MTM uses CImTextServerSession to handle the communication with the email server and CImRecvConvert to parse the email messages downloaded, both are provided by the Email Server MTM Utilities.
-• Connect – The POP3 Server MTM will open a socket to the email server using CImTextServerSession and login user the username / password in the POP3 settings. After a successful connection the Server MTM will attempt to synchronise the current state of headers stored on the email server with the set stored in the message store and then start any pending offline operations. After the connect operation has completed the Server MTM will inform the message server that it is expecting more operations via the CommandExpected API and therefore the message server will not delete and unload the Server MTM.
-• Populate Message – The POP3 Server MTM treats requests to copy a message from and to the POP3 service as a request to download the full message.
-• Offline operations – When the POP3 Server MTM receives a request to copy, move, or delete and is not connected to a POP3 email server the Server MTM will store the operation in the CMsvStore of the entry being modified and perform the operation on the next connection to the email server.
-• Disconnect – When disconnecting from a remote email server the POP3 MTM will run any pending offline operations stored. After the disconnect operation completes the Server MTM will allow the message server to delete and unload the Server MTM by setting the CommandExpected API to false.
-3.2.9.3.5 IMAP4 MTMs
-The IMAP4 Server MTM implements the functionality to synchronise the local message store with a remote IMAP4 email server.
-3.2.9.3.5.1 Client MTM
-The IMAP4 Client MTM implements the standard Client MTM APIs and other extensions:
-• Connecting, disconnecting, synchronising, un/subscribing folders – These operations are accessible as commands available via the InvokeAsyncFunction API of the Client MTM, they are implemented as calls to the IMAP4 Server MTM.
-• Send on next connection – If the Client MTM gets a request to connect to an email server it will check whether the IMAP4 settings. If send on next connection is requested it will launch the autosend.exe executable (see section 3.2.7.3.7) to handle sending messages waiting in the outbox.
-• Reply to, and forward messages – These are accessible via the ReplyL and ForwardL APIs of a Client MTM and are implemented as calls to the email utilities class CImEmailOperation.
-• Reply to, forward, create new, create receipt, forward as attachment – These are accessible as commands available via the InvokeAsyncFunction API of the Client MTM, they are implemented as calls to CImEmailOperation.
-• Querying connection status – These commands let clients know whether the IMAP4 Server MTM is connected to an email server and whether it is currently processing a request. They are available via the InvokeAsyncFunction API of the Client MTM. The Client MTM requests the information from the Server MTM.
-• Compound Connection and synchronisation – The IMAP4 Client MTM provides a compound operation that connects and synchronises with an IMAP4 server. This operation is implemented as a client side object that combines requests to the IMAP4 Server MTM. The client side operation can complete the client request either after the connection, after the connection + sync or after the connection + sync + disconnect. The client will keep requesting that the inbox be resynchronised at a configurable interval so new messages received in the inbox on the server will appear under the IMAP4 inbox. The CImapConnectAndSyncOp class handles these compound operations.
-• Compound Connect and copy / move / populate messages – The IMAP4 Client MTM provides a compound operation that connects to an IMAP4 server and copies moves or populates messages. The implementation is provided by the CImImap4GetMail class which makes calls back into the IMAP4 Client MTM.
-• Offline operations – The IMAP4 Client MTM has a command to cancel offline operations, this is available via the InvokeAsyncFunction API of the Client MTM. The Client MTM passes the request to the Server MTM.
-3.2.9.3.5.2 Server MTM
-The IMAP4 Server MTM handles the communication with the remote IMAP4 server and implementation of the IMAP4 protocol. The MTM uses CImTextServerSession to handle the communication with the email server. The IMAP4 Server MTM opens two connections to the IMAP4 server this enables users to download messages while the Server MTM is performing a background synchronisation if requested by the Client MTM.
-• Connect – The IMAP4 Server MTM will open a socket to the email server using CImTextServerSession and login using the username / password in the IMAP4 settings. After a successful connection the Server MTM will optionally attempt to synchronise the current state of headers stored on the email server with the set stored in the message store and then start any pending offline operations. After the connect operation has completed the Server MTM will inform the message server that it is expecting more operations via the CommandExpected API and therefore the message server will not delete and unload the Server MTM.
-• Copy, Move messages – The IMAP4 Server MTM supports copying and moving messages between folders on the IMAP4 server and between the IMAP4 server and local folders.
-• Delete messages – The IMAP4 Server MTM will mark the email as deleted on the server; however it will not be deleted until the IMAP4 Server MTM disconnects from the server.
-• Folders – The IMAP4 Server MTM will allow folders to be subscribed, unsubscribed, renamed, copied, moved, and created within the IMAP4 service. Subscribing to a folder means that it will be visible to the user and synchronised with the remote server. The inbox is always subscribed.
-• Offline operations – When the IMAP4 Server MTM receives a request to copy, move, or delete and is not connected to an IMAP4 email server the Server MTM will store the operation in the CMsvStore of the entry being modified and perform the operation on the next connection to the email server.
-• Disconnect – When disconnecting from a remote email server the IMAP4 MTM will run any pending offline operations stored. After the disconnect operation completes the Server MTM will allow the message server to delete and unload the Server MTM by setting the CommandExpected API to false.
-
-3.2.9.3.6 SMTP MTMs
-The SMTP MTMs provide functionality to send email messages. They are made up of the Client MTM that is part of the imcm DLL and the Server MTM.
-3.2.9.3.6.1 Client MTM
-The SMTP Client MTM implements the standard Client MTM APIs including the functions required to allow clients of Send As to create email messages.
-3.2.9.3.6.2 Server MTM
-The SMTP MTMs provide functionality to send email messages; it interprets requests to copy entries to an SMTP service as a request to send those messages. In addition it responds to two extended commands via the StartCommand Server MTM interface. These commands are KSMTPMTMIsConnected that responds with whether the Server MTM is currently connected to a remote SMTP server and KSMTPMTMSendOnNextConnection which performs the same operation as copying a selection of messages to an SMTP service. The only difference between the copy operation and the KSMTPMTMSendOnNextConnection operation is that the latter can be called without a selection of messages.
-When the Server MTM receives a request to send messages it builds a selection of messages consisting of the messages passed into the operation and any messages waiting in the outbox to be sent. To determine which messages in the outbox are waiting to be sent the SMTP server checks for messages that have the same service ID as the destination of the send operation and have a sending state of KMsvSendStateWaiting, KMsvSendStateScheduled or KMsvSendStateResend. This means that any request to send messages may result in more messages being sent than explicitly listed in the selection passed to the send operation.
-The Server MTM restores its settings from the SMTP service it has been asked to copy the messages to. Then it connects to the SMTP server using the CImTextServerSession class in the Email Server MTM Utilities, passing in the SMTP server address and TCP/IP port number from the SMTP settings. Then for each message to be sent the Server MTM uses the Email Server MTM utilities to generate an RFC2822 format message to send to the SMTP server, the RFC2822 text is generated on the fly as the data is sent to the SMTP server. If the SMTP server accepts the message to be sent then the Server MTM moves the message to the sent folder and sets its sending state to sent. If the SMTP server rejects the message then the Server MTM leaves the message in the outbox and sets the sending state to failed. Separate emails are generated for BCC recipients to ensure that the SMTP server doesn’t incorrectly include BCC recipients in emails sent to addresses in the To and CC fields of the email.
-3.2.9.3.7 Autosend
-The Autosend component is an executable that is kicked off by the POP3 and IMAP4 Client MTMs if the send on next connection setting is set. This executable will just make a request to the SMTP Server MTM to send messages associated with the SMTP service related to the POP3 or IMAP4 service, wait for the operation to finish and then exit.
-3.2.10 Messaging / MMS APIs
-The MMS module has been removed from v9.0 and onwards.
-3.2.10.1 Key Internal Relationships and Dependencies
-
-Figure 21 MMS Internal Dependencies
-3.2.10.2 API Purpose - Further Elaboration
-3.2.10.2.1 MMS Overview
-The MMS MTM provides functionality for creating, accessing, sending and receiving MMS messages. Messages are sent and received without the client application needing to open or close any kind of session. The management of the MMS session is handled entirely within the MTM.
-MMS clients are alerted when a new message is available for download via the WAP Push mechanism. A WAP push watcher is provided to handle these notifications. After the notification the message can be downloaded over WSP or HTTP. Messages are sent by posting the data over WSP or HTTP. The Symbian MMS implementation can handle sending or receiving MMS message over either protocol.
-MMS messages are based on the MIME format but are binary encoded using WSP. Note that MMS messages are encoded in this way even if they are posted over HTTP as opposed to WSP. The codec component is responsible for this encoding and decoding.
-3.2.10.2.2 MMS Utilities
-3.2.10.2.2.1 Key External Relationships and Dependencies
-
-Figure 22 MMS Utilities External Dependencies
-The MMS utilities provide the message and settings encapsulation classes. The MMS settings and messages are stored in the message store, the MMS utilities provide the interfaces to access this data.
-3.2.10.2.2.2 Settings
-The settings functionality provided by the MMS utilities allows the messaging client to persist MMS settings in the message store. Supported settings include:
- MMSC (MMS server) address
- WSP or HTTP transport
- Autofetch messages on notification
- Preferred IAP for the MMS network connection
-The settings functionality is also used by the server MTM to retrieve the settings prior to message sending or fetching.
-3.2.10.2.2.3 Message Encapsulation
-The message classes provide the message access functionality. Messages can be created, stored, restored and read using these classes. Functionality includes:
- Adding media objects to the message
- Enumerating through media objects
- Adding recipients, subject line, etc. to a message
- Adding other headers to the message, e.g. expiry date
- Finding the appropriate media object for a given URI in the SMIL part (URI resolving)
-The message data is stored in the message store using one entry per message regardless of the number of media objects added to the message. This is preferable to using multiple message entries as it is faster and uses less disk space.
-Most of the message access code is common whether it is being used on the client or server side, however some parts of it are specific. For this reason it is essential that the appropriate client or server side CMmsMessage derived class is used.
-3.2.10.2.3 MMS Watcher
-3.2.10.2.3.1 Key External Relationships and Dependencies
-
-Figure 23 MMS Watcher External Dependencies
-
-The MMS watcher plug-in is responsible for intercepting incoming MMS notifications and delivery reports then taking the appropriate action. It is implemented as a WAP Push watcher plug-in.
-When an MMS notification is received an MMS entry is created in the inbox using the MMS utilities. At this point the entry has its incomplete flag set. If the settings have the autofetch option selected then the MMS watcher initiates the fetch operation via the MMS client MTM.
-If a delivery report is received then the delivered flag is set on the appropriate sent message. If an outgoing message was sent to several recipients then there will be several delivered flags. A delivery report from each recipient will set the appropriate delivered flag.
-3.2.10.2.4 MMS Client MTM
-3.2.10.2.4.1 Key External Relationships and Dependencies
-
-Figure 24 MMS Client MTM Dependencies
-As with most other MTMs the MMS client MTM provides access to the server MTM functionality for messaging clients. It also implements the Send-As interface and reply and forward functionality.
-3.2.10.2.4.2 Send-As Implementation
-The Client MTM Send-As interface is implemented in the MMS Client MTM. The implementation differs slightly from other MTMs because additional presentation content may be generated depending on the media objects that are added. When simple combinations of images, sounds and text are added a SMIL presentation is generated to link them together. This is preferable to simple adding the objects as attachments where some clients render them as a list of files and others fail to render them at all.
-The SMIL data is constructed using templates stored in resource files, the GMXML (SMIL) composer is not used.
-3.2.10.2.4.3 Reply / Forward
-The Client MTM can be used to create replies to received messages or to create forwarded responses. The reply and forwarding operations are performed asynchronously.
-3.2.10.2.5 MMS Server MTM
-3.2.10.2.5.1 Key External Relationships and Dependencies
-
-Figure 25 MMS Server MTM Dependencies
-The Server MTM is the most complicated part the MMS implementation. It handles all of the state information required to send or fetch MMS messages. It is also responsible for managing the HTTP or WSP session and the connections to the phone network.
-3.2.10.2.5.2 Operations
-All MMS server MTM functionality is encapsulated in operations. An operation consists of the setup of a session, the sending, fetching and acknowledgements when appropriate, it then closes the session. The messaging client initiates an operation with a single call to the Client MTM, there is no need for the messaging client to explicitly establish the session or to know about the internal states. However, these internal states are available to the messaging client via the progress structure if this level of user feedback is required.
-Two types of operation are supported, background and foreground:
-A maximum of one foreground operation can be running at any one time. The messaging client can poll the server MTM for the progress of a running foreground operation, likewise it can cancel it if necessary.
-A background operation does not support progress information and can not be cancelled by the messaging client. It is possible to initiate background operations even if other background or foreground operations are pending. However, background operations are queued and a maximum of one will actually be running at any one time.
-The MMS watcher uses a background operation to perform automatic fetching. While the background autofetch is occurring it is still possible to start a foreground operation (such as sending a message) if required.
-3.2.10.2.5.3 Session and Connection Management
-The server MTM uses the HTTP Transport Framework to enable the HTTP or WSP session. HTTP or WSP can be selected at runtime by selecting the appropriate option in the settings. The server MTM is responsible for reading any HTTP proxy details from the CommDB and passing it to the HTTP framework. See the http transport framework architectural description for more information on recognisers [R5]
-The server MTM is also responsible for managing the connection to the phone network. Connections are opened when required using the RConnection mechanism, multi-homing is supported provided that the underlying HTTP framework transport plug-in also supports it.
-3.2.10.2.6 MMS Codec
-The MMS Server MTM is in charge of the state transitions, connection, session, the actual posting and fetching of the data from them, however it does not encode or decode the MMS PDUs. The encoding and decoding is performed by the MMS Codec.
-For decoding the Server MTM passes the Codec the MMS PDU data in a descriptor for processing. If the PDU contains a received MMS message then the message entry is updated with the decoded MMS data.
-For encoding the Server MTM passes a reference to the message store entry containing the un-encoded MMS data. The Codec then encodes it and returns the PDU to the Server MTM in a descriptor.
-
-
-3.2.11 Messaging / BIO APIs
-3.2.11.1 Key Internal Relationships and Dependencies
-
-Figure 26 BIO Message Internal Dependencies
-3.2.11.1.1.1 Key External Relationships and Dependencies
-
-Figure 27 Bio Parser External Dependencies
-
-3.2.11.2 API Purpose - Further Elaboration
-3.2.11.2.1 BIO Overview
-The BIO messaging components have been designed to unify and simplify the way in which system messages are processed. In this context ‘system messages’ refers to messages received on the device which are intended to update some attribute(s) on the system as opposed to being presented to the user. Examples of these types of messages include vCards which are parsed and then displayed to the user and when accepted modify the users contact database and OTA configuration messages which are again parsed before display to the user and if accepted create email accounts or internet access points.
-The BIO messaging components can be broken down into three groups:
-1) The BIO MTM - To initiate the parsing and processing of BIO messages
-2) The BIO Database - Maps port numbers, MIME types, etc. to bio types in order to identify the type of incoming BIO messages.
-3) The BIO Parsers - To parse and process the BIO message payload
-BIO messages are not receive by the bio messaging framework, they come over other message transports for example see section 3.2.6.3.1 on the SMS watchers which describes how the SMS watchers receive bio messages and use the bio framework to tag the messages with the correct bio id.
-3.2.11.2.2 BIO MTM
-The BIO client MTM is called by the messaging client to parse or process a BIO message that has been saved in the message store. It is the responsibility of a BIO watcher to save the BIO message with the BIO flag and the appropriate BIO type set.
-The BIO client MTM does very little, its primary task is to pass on the messaging client request to the server MTM. Two operations are supported, parse and process.
-The messaging client is expected to initiate the parsing of the BIO message before processing it. The parsing step involves analysing the data and storing it in a form that can be displayed to the user via the BIO message viewer.
-Once the message has been parsed the messaging client can initiate the processing of the message.
-The BIO server MTM is responsible for deferring the parsing and processing to the appropriate BIO parser. The behaviour for the parsing and processing steps varies between parsers. See the BIO Parsers section for more information.
-The bio MTM does not support sending messages and therefore does not support reply / forwarding messages. For bio messages sending / reply etc. is supported by the particular MTM that the message is sent over, for example SMS.
-3.2.11.2.3 BIO Database
-The BIO database is used to identify the type of BIO messages. It maps message attributes such as port number, MIME type or leading string to a BIO type. These are attributes are then used by clients of the bio framework to know what ports to listen for messages on. For example the SMS watchers use the leading string to wait for SMS messages that start with that string and when storing those messages in the inbox tag them with the bio id associated with that leading string. See the SMS watcher section 3.2.6.3.1 for more examples of how the BIO database can be used.
-3.2.11.2.4 BIO Parsers
-The BIO parsers are plug-ins for parsing and processing incoming BIO messages. They are invoked by the BIO Server MTM depending on the BIO type of the message being processed. Each BIO parser implements two functions, ParseL and ProcessL. The level of functionality varies between parsers. Some parsers update the final repository with the received data, e.g. WAPP updates the CommDB with the received settings. Some parsers simply save the data in an unparsed state for processing by another component, this secondary parsing is not part of the BIO framework and must be initiated by the messaging client. An example is when GFP saves vCard data as a file as opposed to updating the contacts database, the UI must then invoke the Versit parser to parse the vCard and commit it to the contacts database.
-3.2.11.2.4.1 Generic File Parser (GFP)
-The generic file parser can be used to identify and save a variety of BIO data types, e.g. vCards and vCals. The Generic File Parser does not process the data, it simply saves it in the message store for processing by another component. The file is saved as an attachment of the message entry that was parsed.
-3.2.11.2.4.2 Nokia/Ericsson OTA Parser (WAPP)
-The WAPP parser decodes Nokia/Ericsson OTA messages and updates CommDB to reflect the received settings.
-3.2.11.2.4.3 Nokia Smart Message Internet Access Parser (IACP)
-The IACP parser decodes Nokia Smart Messages and updates the CommDB and messaging settings where appropriate.
-3.2.11.2.5 BIF Files and Utilities
-The BIF files encapsulate the information required for identifying BIO messages, these details may include the expected port number, MIME type or leading string. Different BIO watcher will use different information from these files, for an example see the 3.2.6.3.1. The information can be retrieved from the BIF files by using the BIF utilities. Generally BIO aware clients will access this information via the BIO database. BIF files are resource files previous to the v6.1 release they were binary files generated by biftool.exe.
-3.2.11.2.6 Platform Security Compliant Messaging / BIO APIs
-In the platform security model the BIO parsers are run in the client space rather than in the message server space, as is done in the non-platform secure model. If the BIO parsers are run in the message server space, it allows a client process to gain the capabilities of the message server. IPC policing can protect the message server from this.
-Also, for the message server to be able to load any BIO parser it would need more capabilities than it really requires. By running the BIO parsers in the client space, both these issues are solved. The client process must be trusted with the necessary capabilities to run the specified BIO parser.
-The BIO registry files are located in the \resource\messaging\bif read-only directory. All BIO parser DLLs are located in the \sys\bin protected directory.
-
-Figure 26 BIO Message Dependencies (v9.0)
-The BIO client MTM is responsible for loading the BIO database and BIO utilities to handle parse/process requests from clients.
-The BIO registry files no longer identify the BIO parsers DLLs via their UID – the registry file must use the BIO parser DLL name to identify them.
-3.2.12 Messaging / OBEX MTM APIs
-3.2.12.1 Key Internal Relationships and Dependencies
-
-Figure 28 OBEX Internal Dependencies
-3.2.12.2 OBEX MTM Overview
-The OBEX MTM offers simple IR and Bluetooth beaming functionality. It provides an API that is consistent with other MTMs so that the underlying OBEX APIs do not need to be used directly for beaming applications. The OBEX MTM does not provide OBEX receiving functionality, in order to receive OBEX data the underlying OBEX APIs must be used directly.
-3.2.12.2.1 OBEX MTM
-The OBEX MTM is split into three parts. OBEX MTM DLLs, IR MTM DLLs and Bluetooth MTM DLLs. The OBEX MTM DLLs can not be used on their own they provide the base OBEX MTM functionality for the derived IR and Bluetooth MTMs.
-There are two APIs that can be used to create OBEX messages:
-1) The Send-As API
-2) Linked attachments by filename
-The Send-As API provides an interface consistent with other MTMs, however it requires all attachments to be copied into the message store before they can be sent, this is often undesirable for beaming applications because it is wastes disk space. For this reason a second API is provided that allows attachments to be linked to outgoing messages by filename, when this API is used there is no need to copy the attachments to the message store.
-Unlike many other MTMs after OBEX tries to send a message it is deleted from the outbox whether the sending succeeds or fails.
-3.2.12.2.1.1 OBEX MTM Key External Dependencies
-
-Figure 29 OBEX External Dependencies
-3.2.12.2.2 IR MTM
-The bulk of the OBEX MTM functionality is provided by the OBEX MTM DLLs, the IR MTM itself just sets up the parameters.
-3.2.12.2.2.1 IR MTM Key External Dependencies
-
-Figure 30 IR MTM Dependencies
-3.2.12.2.3 Bluetooth MTM
-The bulk of the OBEX MTM functionality is provided by the OBEX MTM DLLs, the Bluetooth MTM just subclasses from the OBEX MTM and sets up Bluetooth specific parameters.
-3.2.12.2.3.1 Bluetooth MTM Key External Dependencies
-
-Figure 31 Bluetooth MTM Dependencies
-3.2.12.2.4 OBEX MTM Utils
-The OBEX MTM Utils provide utility functionality used by the other OBEX MTM DLLs. The two main areas of functionality provided by this component are:
-1) Filename linking functionality
-2) Bluetooth SDP lookup
-The filename linking functionality is provided in the utilities because linked files must be added by the client side during message creation and need to be read on the server side during sending.
-
-3.2.12.2.5 Platform Security Compliant Messaging / OBEX MTM APIs
-From v9.0 and onwards the service settings of all the derived OBEX MTMs are stored in the Central Repository. The OBEX message is stored in the message store as an attachment – from v9.0 and onwards the Attachment API is used to attach the OBEX message.
-
-3.2.13 Messaging / GMXML APIs
-3.2.13.1 Key Relationships and Dependencies
-
-Figure 32 GMXML Dependencies
-3.2.13.2 Overview
-The GMXML component provides simple XML DOM parsing and validation functionality. It is intended for parsing XML that might be needed in messaging applications, specifically SMIL parsing for MMS rendering. It is not a general purpose XML parser and will not be suitable for some applications, e.g. browsing.
-3.2.13.2.1 GMXML DOM
-The DOM implementation is fit for purpose for SMIL rendering but differs from the standard DOM design in several respects, e.g. attributes are not stored as discrete nodes, for performance reasons they are stored with the element.
-The DOM tree classes are all derived from nodes. Implemented node types include elements, text and comments. The type of each element is stored as a descriptor as opposed to an enum. This is less efficient than storing it as an enum but provides maximum flexibility when dealing with unknown element types.
-Nodes are linked together in a tree structure as might be expected in a DOM implementation. The tree structure exists on the heap.
-3.2.13.2.2 GMXML Parser and Composer
-3.2.13.2.2.1 Parser
-The parser takes XML input from a buffer or file and creates the corresponding DOM structure on the heap.
-The parser is capable of performing some basic validation. In order to validate against a DTD a class that implements the GMXML DTD interface is required. The DTD interface specifies several functions that provide the required validation, e.g. one of the functions determines if a given attribute is valid for a given element. An instance of the DTD class should be passed into the parser when validation is required but can be omitted if no validation is needed.
-3.2.13.2.2.2 Composer
-The composer takes a DOM tree and generates XML output from it. The XML output is written to a file.
-3.2.13.2.3 GMXML SMIL DTD (Validator)
-The SMIL DTD validator class is an implementation of the DTD validator interface. It implements several simple functions that provide the information required to validate SMIL data. An instance of the SMIL DTD validator should be passed into the parser if SMIL validation is required.
-4 Security
-4.1 Data caging
-For data storage in the pre-platform security compliant architecture, refer to section [3.2.1.3.2]
-For the data caging in the platform security compliant architecture of v9.0 and onwards, refer to section [3.2.1.3.3]
-4.2 Backup and restore
-The message server registers the index file with the backup server. When informed about a backup/restore it releases the index file, sending events to messaging clients informing them that the message store is unavailable. When informed it can open the index file again, it checks the time stamp on the index file; if it has changed since the file was released it reloads the index file. If the newly restored index file is found to be corrupt it is deleted and a new message store is created. See the section on page 14 for details on how the message server handles corrupt stores. The client performing the restore should always wipe the existing message store before starting to copy the message store from the backup to the device.
-4.3 Capability ranges
-In the platform security compliant architecture of v9.0 and onwards, the capabilities allocated to messaging sub-systems are as listed in following table.
-4.3.1 Capabilities granted to executables
-The following table lists the executables and their capabilities and also gives a basic example for having the required capability.
-
-Executable Capability Rationale (basic example of capability requirement)
-msexe.exe ProtServ ProtServ is required to allow the msexe.exe to start a protected server. This stops processes without ProtServ from starting a server pretending to be the message server
- ReadDeviceData ReadDeviceData is needed to able to read service settings
- WriteDeviceData WriteDeviceData is needed to able to write service settings
- NetworkServices NetworkServices capability is needed to access network transports (SMS, POP3, SMTP, IMAP4).
- LocalServices LocalServices is needed to be able to access IR and Bluetooth
- ReadUserData ReadUserData is needed to be able to read user data (e.g. service settings).
-watcher.exe ReadDeviceData ReadDeviceData is needed to able to read service settings
- WriteDeviceData WriteDeviceData is needed to able to write service settings
- NetworkServices NetworkServices capability is needed to access network transports (SMS).
- LocalServices LocalServices capability is needed for the plug-ins to access IR and Bluetooth
- ReadUserData ReadUserData is needed to be able to read user data
- WriteUserData WriteUserData is needed to be able to write user data
-autosend.exe ReadUserData ReadUserData capability is needed to be able to read data from Outbox and SMTP server MTM.
- WriteUserData WriteUserData capability is needed to be able to write data in Outbox and SMTP server MTM.
- NetworkServices NetworkServices capability is needed to access network transports (SMS, POP3, SMTP, and IMAP4).
- LocalServices LocalServices capability is needed to access the IR and Bluetooth
-SchSend.exe ReadDeviceData ReadDeviceData is needed to able to read settings data
- NetworkServices NetworkServices capability is needed to access the network transports (SMS, POP3, SMTP, and IMAP4).
- LocalServices LocalServices is needed to be trusted by other MTM
- ReadUserData ReadUserData is needed to be able to read user data.
- WriteUserData WriteUserData is needed to be able to write user data.
-SendAs.exe ReadDeviceData ReadUserData is needed to be able to read data in Outbox.
- WriteDeviceData WriteUserData is needed to be able to write data in Outbox.
- NetworkServices NetworkServices capability is needed to access the network transports (SMS, POP3, SMTP, and IMAP4).
- LocalServices LocalServices is needed to be able to access IR and Bluetooth
-
-4.3.2 Capabilities granted to DLLs
-The assigned Platform Security attributes for DLLs within messaging are outlined in the following table.
-DLL Capability
-bifu.dll All –TCB
-bioc.dll All –TCB
-biodb.dll All –TCB
-bios.dll All –TCB
-biowatcher.dll same as watcher.exe
-biut.dll All –TCB
-cbcp.dll All –TCB
-enp.dll All –TCB
-gfp.dll All –TCB
-iacp.dll All –TCB
-nbswatcher.dll same as watcher.exe
-cdmanbswatcher.dll same as watcher.exe
-CdmaSocketWatcher.dll same as watcher.exe
-VMNWatcher.dll same as watcher.exe
-WEMTWatcher.dll same as watcher.exe
-WMTWatcher.dll same as watcher.exe
-WPTWatcher.dll same as watcher.exe
-wapp.dll All –TCB
-wapwatcher.dll same as watcher.exe
-smildtd.dll All –TCB
-xmldom.dll All –TCB
-xmlparser.dll All –TCB
-smiltranslator.dll All –TCB
-imcm.dll All –TCB
-imps.dll same as msexe.exe
-imut.dll All –TCB
-msgs.dll All –TCB
-msgurlrec.mdl same as AppArc.exe (once it exists; eiksrv in meantime)
-mtur.dll All –TCB
-pops.dll same as msexe.exe
-schsend.dll All –TCB
-send.dll All –TCB
-smcm.dll All –TCB
-smcm_gsm.dll Synonym for smcm.dll
-smcm_cdma.dll Synonym for smcm.dll
-smss.dll same as msexe.exe
-smss_gsm.dll Synonym for smss.dll
-smss_cdma.dll Synonym for smss.dll
-smts.dll same as msexe.exe
-btcmtm.dll All –TCB
-btsmtm.dll same as msexe.exe
-irc.dll All –TCB
-irs.dll same as msexe.exe
-obexclientmtm.dll All –TCB
-obexmtmutil.dll All –TCB
-obexservermtm.dll same as msexe.exe
-
-The reason for setting a high capability to the DLLs is to make it possible for almost anyone to link to them. Although a DLL may have capabilities ALL-TCB (All minus TCB), its real capability is limited by the process which loads the DLL.
-4.3.3 Capabilities required to use the subsystem
-The message subsystem needs to be protected against malicious clients. The following table shows the key capabilities required to do related activities in different components.
-
-Component Related Activity Required Capability and SID
-Message server Create message in local folder No capability required
- Create message in Outbox ReadUserData, WriteUserData and MTM specific capabilities
- Access client MTM ReadUserData, WriteUserData and MTM specific capabilities
-Watcher Allow plug-ins to wait on events (e.g. arrival of SMS) Watcher always polices if the client capabilities are trusted by the watcher framework, else it will not be loaded
-Plug-ins or clients using watcher need the same capabilities as watcher.exe to be able to be loaded by watcher.
-Autosend Send messages in background NetworkService or LocalService required by the message type
-SchSend Scheduling of operations (e.g. sending SMS) SchSend always polices to see if the process was started by the Task Scheduler – if not the process terminates without performing any of the scheduled tasks. Also, the SchSend verifies that only itself and the message server created the scheduled tasks. If this is not the case, SchSend does not performing the scheduled tasks.
-SendAs Create message Draft, move it to Outbox, and send message WriteDeviceData or WriteUserData and other capability required by the message type
-
-5 Further Information
-5.1 References
-No. Document Reference Version Description
-R1 messaging_functional_specification.doc 0.6 Messaging Functional description
-R2 SGL.GT0143.161_App-Framework_Architectural_Description.doc 1.0 App-Framework Architectural Description
-R3 NBProtocols_Subsystem_Architectural_Description.doc 0.2 NBProtocols Architectural Description
-R4 WAP-stack_architectural_analysis.doc 1.0 WAP stack architectural analysis
-R5 HTTP Transport Framework Architectural Description.doc 1.1 HTTP Transport Framework 1.1 Architectural Description
-5.2 Open Issues
-The following issues need to be resolved before this document is completed:
-1. Top-level architecture diagram showing the framework and plug-ins should be added to overview section.
-2. Message store section should talk about removable media.
-3. Define "Message Server Client API" and "Messaging Client API" in the glossary, and ensure it is consistently used in the diagrams
-4. Add a sequence diagram for receiving a vCard over SMS and integrating it into contacts
-5. Add a sequence diagram for sending an SMS
-6. Add a sequence diagram for synchronising a POP3 mail box
-7. Add a sequence diagram for connecting to an IMAP4 mail box and downloading a message
-8. Capability table should be updated after the implementation of server e.g. message server
-9. Sequence diagram may need to be changed to show secured platform operation
-10. In section [3.1.1.4] the server SendAsV2 to find a correct name
-11. Section 3.2.1.3.3.1 Data Caging file 'Mtm Registry v2'may need a correct name
-12. Breakdown diagram showing all DLL, exes, apps in the messaging subsystem for both the pre-v8.0 and post v9.0 in section[3.2]
-13. Needs to say more about how the capabilities are policed and the algorithms used for different operations
-14. The dependecy between the message server and the central repository need to be listed in the email, SMS and OBEX diagrams (e.g. message store)
-15. Section 3.2.1.2 - figure 3 - Central Repository also get used by the Message server, or server MTMs (e.g. POP3), to retrieve account settings the path, required DLL and description are not given
-16. Section 4.3.3 title can be Police requirement of the sub-system, add extra column for SID in the table and list the use of SID. For example SchSend checks for Task Scheduler SID
-
-
-5.3 Glossary
-The following technical terms and abbreviations are used within this document.
-Term Definition
-BIO
-Bearer Independent Object Smart messages e.g. vCards, vCals, and WAP provisioning messages. These can currently be received via the WAP stack, SMS stack, Bluetooth or Infrared.
-BIO Type UID that represents the content type of a BIO Message.
-Message Centre Application that displays list views of messages to the user, allowing the user to perform operations such as copying messages, sending messages creating new messages etc.
-Message Viewer Application for viewing a message.
-Message Editor Application for creating or editing a message
-Message Server Symbian OS Server that handles request to modify the Message Store
-Message Store Store of messages and related information kept in the file system on a Symbian OS device.
-Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
-Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
-Global Inbox A standard folder under the local service which is used to store incoming messages like SMS MMS etc. as opposed to an IMAP4 Inbox which would be under an IMAP4 service and is a representation of the Inbox on an IMAP4 email server.
-Central Repository centralised and secure storage facility for application settings
-OBEX Object exchange protocol, used to send objects such as vCards or files between devices via infrared or Bluetooth.
-GMXML XML parser / generator for use with SMIL formatted messages.
-UID Unique Identifier, a 32 bit number allocated from a registry owned by Symbian
-IPC Inter Process Communication
-MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
+MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
MTM Registry A list of currently installed MTMs maintained by the message server.
TLS Transport Layer Security, provides encryption of a TCP/IP socket.
M-HTML Standard for including HTML in MIME email messages see http://www.ietf.org/rfc/rfc2557.txt
@@ -26405,1033 +19279,15 @@
Message Editor Application for creating or editing a message
Message Server Symbian OS Server that handles request to modify the Message Store
Message Store Store of messages and related information kept in the file system on a Symbian OS device.
-Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
-Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
+Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
+Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
Global Inbox A standard folder under the local service which is used to store incoming messages like SMS MMS etc. as opposed to an IMAP4 Inbox which would be under an IMAP4 service and is a representation of the Inbox on an IMAP4 email server.
Central Repository centralised and secure storage facility for application settings
OBEX Object exchange protocol, used to send objects such as vCards or files between devices via infrared or Bluetooth.
GMXML XML parser / generator for use with SMIL formatted messages.
UID Unique Identifier, a 32 bit number allocated from a registry owned by Symbian
IPC Inter Process Communication
-MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
-MTM Registry A list of currently installed MTMs maintained by the message server.
-TLS Transport Layer Security, provides encryption of a TCP/IP socket.
-M-HTML Standard for including HTML in MIME email messages see http://www.ietf.org/rfc/rfc2557.txt
-MIME Specification for the format of email message bodies see http://www.ietf.org/rfc/rfc1341.txt
-RFC2822 The standard format for internet mail messages see http://www.ietf.org/rfc/rfc0822.txt
-SMTP Simple Mail Transport Protocol
-SID Secure Identification
-IMAP4 Internet Mail Access Protocol
-POP3 Post Office Protocol Version 3
-NBS Narrow Band Socket, in the messaging context this refers to the socket that is used to talk to the SMS stack for receiving and sending SMS messages
-SMS Short Message Service
-MMS Multimedia Message Service
-WAP Wireless Application Protocol
-WSP WAP Session Protocol
-HTTP Hypertext transfer protocol
-PDU Protocol Data Unit. This is the encoded form of SMS and MMS messages.
-Versit A consortium that defined standard formats for things like contacts (vCard) and calendar entries (vCals)
-SDP Service Discovery Protocol. A Bluetooth protocol that allows an applications to discover which services are available and to determine the characteristics of the services.
-SMIL Synchronized Multimedia Integration Language. Presentation language that is commonly used to define the contents of an MMS message.
-XML Extensible Mark-up Language
-DOM Document Object Model
-DTD Document Type Definition, a schema that defines the structure of an XML document.
-ESTORE Symbian OS component that provides stream based storage. Messaging uses the Permanent file store provided by ESTORE to store its index entries.
-Appendix A - Example Sequence Diagrams
-A.1 Copy to a Remote Service
-
-Figure 33 Sequence Diagram Showing Copying to a Remote Service
-Figure 33 shows a client copying a message to a remote service using the Messaging Client API. The message server then delegates the copy to the SMTP Server MTM. The Server MTM interprets the request as a request to send the message so it opens a connection to a remote SMTP server and sends the message. While the message is being sent the client can retrieve progress information from the CMsvOperation object that was returned by CMsvEntry::CopyL. The dark grey IPC line represents the split between the objects running in the client’s process space on the left and the message server’s process on the right.
-There are four basic steps:
-1. The client opens session with Message Server and creates a CMsvEntry set on the global outbox,
-2. The client then requests an asynchronous copy from the outbox to the SMTP service, a CMsvOperation object is returned. The message server loads the SMTP Server MTM and delegates the copy operation to it.
-3. The client requests progress from the CMsvOperation object, this request is passed through to the SMTP Server MTM. The client may repeat this step multiple times.
-4. The Server MTM finishes sending message. It moves the message to sent folder and completes the message server’s request. The message server completes the CMsvOperation object, which requests the final progress from the message server. The server returns the final progress and deletes the Server MTM. The CMsvOperation then completes the client’s original request.
-This diagram hides all of the internal working of the SMTP Server MTM, for information on this see below.
-A.2 SMTP Session
-
-Figure 34 Sequence Diagram Showing a SMTP Session
-Figure 34 shows the operation of the SMTP Server MTM after a request has come from the message server to copy a message to the SMTP service.
-1. SMTP Server MTM gets the request from the message server, it will build a selection of messages consisting of the union of the selection of messages passed in and the messages in the outbox that are associated with this SMTP service and are ready to be sent. The chain of classes are constructed, and a request is passed to networking to connect to the remote SMTP server, details of the server name and port are retrieved from the settings stored in the SMTP service entry.
-2. The component waits for the SMTP server to respond with a greeting indicating it is willing to talk, then sends EHLO to the server and waits for the response detailing the capabilities of the Server. After this step there could set steps to start using TLS and or SMTP AUTH depending on the SMTP settings.
-3. CImSmtpSession calls back into CMsgOutboxSend to retrieve the next message to be sent, then constructs a CImSmtpFile object to handle sending, for details on the sending see SMTP Email Send. When sending the email has completed the CImSmtpFile object is deleted.
-4. CImSmtpSession calls back into CMsgOutboxSend to retrieve the next message which returns saying there are no more messages. CImSmtpSession sends QUIT to the SMTP server and completes CMsgOutboxSend. CMsgOutboxSend deletes CImSmtpSession which tears down the connection to the SMTP server; it then completes the SMTP Server MTM. The Server MTM will then complete the message server and be deleted.
-A.3 SMTP Email Send
-
-Figure 35 Sequence Diagram Showing SMTP Transactions during Email Send.
-Figure 35 shows a CImSmtpFile object sending an email message to an SMTP server.
-1. Construct a CImSendMessage object, part of the imut component. Reset the SMTP Server
-2. Read address information from the CImHeader object stored in the message store, send address information to SMTP server.
-3. Use CImSendMessage object to read the message from the message store and generate RFC2822 message line by line. Send each line to the server as it is generated.
-4. Complete and send the message by sending a full stop to the SMTP server
-
-
-
-
-Messaging Symbian OS v7.0s, v8.0, v8.1, v9.0, v9.1 Architectural Description
-
-Status: Issued
-Team/Department : Messaging / Content & Messaging
-
-Contents
-1 INTRODUCTION 6
-1.1 PURPOSE AND SCOPE 6
-2 SUBSYSTEM OVERVIEW AND BACKGROUND 6
-3 MESSAGING ARCHITECTURE AND APIS 7
-3.1 SUBSYSTEM COMPONENTS 7
-3.1.1 Framework components 7
-3.1.1.1 Message Server and MTM architecture 7
-3.1.1.2 Schedule Send 7
-3.1.1.3 SendAs Version 1 7
-3.1.1.4 SendAs Version 2 7
-3.1.1.5 Watcher Framework 8
-3.1.1.6 Message URL Handler 8
-3.1.1.7 Bio Message Framework 8
-3.1.2 Plug-ins 8
-3.1.2.1 SMS 8
-3.1.2.2 CDMA SMS 8
-3.1.2.3 Email 9
-3.1.2.4 OBEX 9
-3.1.2.5 MMS 9
-3.1.2.6 GMXML 10
-3.1.2.7 Bio Message Plug-ins 10
-3.1.2.8 PCMTM 10
-3.1.2.9 Fax 10
-3.2 GENERAL DESCRIPTION 11
-3.2.1 Messaging / Message Server and MTM Architecture APIs 11
-3.2.1.1 Key Internal Relationships and Dependencies 11
-3.2.1.2 Key External Relationships and Dependencies 12
-3.2.1.3 API Purpose - Further Elaboration 13
-3.2.1.3.1 Message Store 13
-3.2.1.3.2 Data File Storage (pre - v9.0) 15
-3.2.1.3.3 Platform Security Compliant Message Store 16
-3.2.1.3.4 How message centres display the message store 17
-3.2.1.3.5 Message Type Module Architecture 19
-3.2.1.3.6 Message Server Client API 21
-3.2.2 Messaging / Send As APIs 22
-3.2.2.1 Key Relationships and Dependencies 22
-3.2.2.2 API Purpose - Further Elaboration 22
-3.2.2.2.1 SendAs API (pre – v9.0) 22
-3.2.3 Platform Security Compliant SendAs Server (v9.0 onwards) 23
-3.2.4 Messaging / Schedule Send APIs 24
-3.2.4.1 Key Relationships and Dependencies 24
-3.2.4.2 API Purpose - Further Elaboration 24
-3.2.4.2.1 Schedule Send 24
-3.2.5 Messaging / Watchers APIs 25
-3.2.5.1 Key Relationships and Dependencies 25
-3.2.5.2 API Purpose - Further Elaboration 25
-3.2.6 Messaging / Message URL Handler APIs 26
-3.2.6.1 Key Relationships and Dependencies 26
-3.2.6.2 API Purpose - Further Elaboration 26
-3.2.6.2.1 Message URL Handler Application 26
-3.2.6.2.2 Message URL Recognisers 27
-3.2.7 Messaging / SMS APIs 27
-3.2.7.1 Key Internal Relationships and Dependencies 27
-3.2.7.2 Key External Relationships and Dependencies 28
-3.2.7.3 API Purpose - Further Elaboration 28
-3.2.7.3.1 SMS Watchers 28
-3.2.7.3.2 SMS Client MTM 29
-3.2.7.3.3 SMS Utilities 29
-3.2.7.3.4 SMS Server MTM 30
-3.2.8 Messaging / CDMA SMS APIs 31
-3.2.8.1 Key Internal Relationships and Dependencies 31
-3.2.8.2 Key External Relationships and Dependencies 32
-3.2.8.3 API Purpose - Further Elaboration 32
-3.2.8.3.1 CDMA SMS Watchers 32
-3.2.8.3.2 CDMA SMS Client MTM 33
-3.2.8.3.3 CDMA SMS Utilities 33
-3.2.8.3.4 CDMA SMS Server MTM 33
-3.2.8.3.5 Configuration for using CDMA SMS MTM 34
-3.2.9 Messaging / Email APIs 35
-3.2.9.1 Key Internal Relationships and Dependencies 35
-3.2.9.2 Key External Relationships and Dependencies 36
-3.2.9.3 API Purpose - Further Elaboration 36
-3.2.9.3.1 Email Overview 36
-3.2.9.3.2 Email Client Utilities 37
-3.2.9.3.3 Email Server MTM Utilities 37
-3.2.9.3.4 POP3 MTMs 37
-3.2.9.3.5 IMAP4 MTMs 38
-3.2.9.3.6 SMTP MTMs 40
-3.2.9.3.7 Autosend 40
-3.2.10 Messaging / MMS APIs 40
-3.2.10.1 Key Internal Relationships and Dependencies 41
-3.2.10.2 API Purpose - Further Elaboration 41
-3.2.10.2.1 MMS Overview 41
-3.2.10.2.2 MMS Utilities 42
-3.2.10.2.3 MMS Watcher 43
-3.2.10.2.4 MMS Client MTM 43
-3.2.10.2.5 MMS Server MTM 44
-3.2.10.2.6 MMS Codec 45
-3.2.11 Messaging / BIO APIs 46
-3.2.11.1 Key Internal Relationships and Dependencies 46
-3.2.11.2 API Purpose - Further Elaboration 47
-3.2.11.2.1 BIO Overview 47
-3.2.11.2.2 BIO MTM 47
-3.2.11.2.3 BIO Database 48
-3.2.11.2.4 BIO Parsers 48
-3.2.11.2.5 BIF Files and Utilities 48
-3.2.11.2.6 Platform Security Compliant Messaging / BIO APIs 49
-3.2.12 Messaging / OBEX MTM APIs 50
-3.2.12.1 Key Internal Relationships and Dependencies 50
-3.2.12.2 OBEX MTM Overview 50
-3.2.12.2.1 OBEX MTM 50
-3.2.12.2.2 IR MTM 51
-3.2.12.2.3 Bluetooth MTM 51
-3.2.12.2.4 OBEX MTM Utils 52
-3.2.12.2.5 Platform Security Compliant Messaging / OBEX MTM APIs 52
-3.2.13 Messaging / GMXML APIs 52
-3.2.13.1 Key Relationships and Dependencies 52
-3.2.13.2 Overview 53
-3.2.13.2.1 GMXML DOM 53
-3.2.13.2.2 GMXML Parser and Composer 53
-3.2.13.2.3 GMXML SMIL DTD (Validator) 53
-4 SECURITY 54
-4.1 DATA CAGING 54
-4.2 BACKUP AND RESTORE 54
-4.3 CAPABILITY RANGES 54
-4.3.1 Capabilities granted to executables 54
-4.3.2 Capabilities granted to DLLs 55
-4.3.3 Capabilities required to use the subsystem 57
-5 FURTHER INFORMATION 59
-5.1 REFERENCES 59
-5.2 OPEN ISSUES 59
-5.3 GLOSSARY 60
-APPENDIX A - EXAMPLE SEQUENCE DIAGRAMS 62
-A.1 COPY TO A REMOTE SERVICE 62
-A.2 SMTP SESSION 64
-A.3 SMTP EMAIL SEND 66
-
-Table of Figures
-Figure 1 Where Messaging Lives 6
-Figure 2 MTM Relationships 11
-Figure 3 External Dependencies 12
-Figure 4 Message Store 13
-Figure 5 Series 60 Inbox List View 14
-Figure 6 Remote and Local Entries 14
-Figure 7 Email Message 15
-Figure 8 Series 60 Message Centre (Composed from 2 screen shots) 17
-Figure 9 UIQ Message Centre 18
-Figure 10 Messaging MTM Structure (light coloured components are part of messaging subsystem) 19
-Figure 11 Nokia 9210 Outbox List View 20
-Figure 12 SendAs Version 1 Dependencies 22
-Figure 13 SendAs Version 2 Dependencies 23
-Figure 14 Schedule Send Dependencies 24
-Figure 15 Watcher Dependencies 25
-Figure 16 Message URL Handler Dependencies 26
-Figure 17 SMS Internal Dependencies 27
-Figure 18 SMS External Dependencies 28
-Figure 19 CMDA SMS Internal Dependencies 31
-Figure 20 CDMA SMS External Dependencies 32
-Figure 19 Email Internal Dependencies 35
-Figure 20 Email External Dependencies 36
-Figure 21 MMS Internal Dependencies 41
-Figure 22 MMS Utilities External Dependencies 42
-Figure 23 MMS Watcher External Dependencies 43
-Figure 24 MMS Client MTM Dependencies 43
-Figure 25 MMS Server MTM Dependencies 44
-Figure 26 BIO Message Internal Dependencies 46
-Figure 27 Bio Parser External Dependencies 47
-Figure 26 BIO Message Dependencies (v9.0) 49
-Figure 28 OBEX Internal Dependencies 50
-Figure 29 OBEX External Dependencies 51
-Figure 30 IR MTM Dependencies 51
-Figure 31 Bluetooth MTM Dependencies 52
-Figure 32 GMXML Dependencies 52
-Figure 33 Sequence Diagram Showing Copying to a Remote Service 62
-Figure 34 Sequence Diagram Showing a SMTP Session 64
-Figure 35 Sequence Diagram Showing SMTP Transactions during Email Send. 66
-1 Introduction
-1.1 Purpose and Scope
-The Messaging Architectural Description details the architecture and APIs exposed by the Messaging Subsystem. This document does not attempt to list all functionality provided by the messaging subsystem. For details on the functionality provided and the specifications implemented by the messaging subsystem see the Messaging Functional Description [R1]. This document describes the general architecture of messaging subsystem. Information related to a particular release version is mentioned with relevant release number.
-2 Subsystem Overview and Background
-The Messaging Subsystem provides an application level API to handle the storage and transport of different message types. It sits between messaging applications and the lower level subsystems which messaging uses for storage and transmission of messages.
-
-Figure 1 Where Messaging Lives
-The message types that messaging currently supports are Email (POP3, IMAP4 & SMTP), SMS, MMS and OBEX. The set of supported message types is extensible at run time by the use of plug-in modules that are responsible for the transmission and storage of a particular message type. This means that the set of components shown communicating with the network cloud depend on the message types installed.
-3 Messaging Architecture and APIs
-3.1 Subsystem components
-The Messaging subsystem components can be split into two categories: those components that form the framework and those that plug into the framework to support specific message types. This section briefly describes each of the components, more detailed descriptions of the components and their dependencies can be found in later sections of this document.
-3.1.1 Framework components
-3.1.1.1 Message Server and MTM architecture
-The message server is the core component in the messaging subsystem. It provides the message store used to contain messages. The Message Type Module architecture also allows plug-ins to add support for new message types to the messaging subsystem.
-Component Description
-messaging\framework\serverexe Executable that links to the server component and starts the message server
-messaging\framework\server Contains classes that make up both the client and server side of the message server API.
-messaging\framework\mtmbase Base classes for the plug-ins that handle the various message types
-3.1.1.2 Schedule Send
-The Schedule Send component is an extension to the framework that provides support for scheduling of operations such as sending messages. Message type modules that wish to support this functionality can use these support components to implement scheduling. For example the SMS MTM uses this to allow scheduled sending of SMS messages.
-Component Description
-messaging\schedulesend\schedulesendmtm Base classes that handle functionality for message server plug-ins that wish to enable scheduling of sending messages.
-messaging\schedulesend\schedulesendexe Executable use to provide schedule send behaviour.
-3.1.1.3 SendAs Version 1
-This version of SendAs is supported in releases pre - v9.0. SendAs provides a high level API for applications that wish to include a “Send As” menu to allow users to send content via one of the message types supported by messaging. The application using the API does not have to be aware of the message type selected by the user. Note the API does not send the messages.
-Component Description
-messaging\sendas High level API to allow creation of messages.
-3.1.1.4 SendAs Version 2
-From v9.0 and onwards the SendAs has been replaced with client server architecture based SendAs server. The client server architecture enhances secured platform implementation. The SendAs server polices the client application. If it is not trusted with required capabilities the SendAs server will refuse the client access. The client MTM for the message type can send a message with user permission even if the client does not have the correct capabilities.
-Component Description
-messaging\sendAsV2 High level API to allow the creation and sending of messages
-
-3.1.1.5 Watcher Framework
-The watcher framework is a lightweight framework to allow plug-ins to wait on events. For example there is an SMS watcher that waits for incoming SMS messages and delivers them to the message store. The watcher framework will only load plug-ins from ROM.
-Component Description
-messaging\framework\watcher Executable that loads and runs watcher plug-ins.
-3.1.1.6 Message URL Handler
-Support for recognising messaging URLs (mailto:, sms:, fax:, mms:), and then launching an editor with a new message.
-Component Description
-messaging\urlhandler\urlhandler An application that parses the URLs and then creates a correctly addressed message and launches a message editor.
-messaging\urlhandler\recogniser Recognisers that map from the URL schemes to the mime types.
-3.1.1.7 Bio Message Framework
-The Bio Message Framework provides a framework that supports plug-ins to handle messages like vCards and Internet access point set-up messages.
-Component Description
-messaging\biomsg\BDB\BIODB Classes to maintain the database of bio registration files.
-messaging\biomsg\BIFU\BIFU Classes for reading and writing bio registration files
-messaging\biomsg\BIOC\BIOC Bio message client MTM, this is in the framework section as it forms part of the bio messaging framework it is also a plug-in to the messaging framework.
-messaging\biomsg\BIOS\BIOS Bio message server MTM, this is in the framework section as it forms part of the bio messaging framework it is also a plug-in to the messaging framework.
-3.1.2 Plug-ins
-3.1.2.1 SMS
-The SMS plug-ins provide application level support for the Short Message Service messages.
-Component Description
-messaging\biomsg\BioWatchers Plug-ins to the watcher framework to listen for SMS, WSP, and WDP messages and deliver them to the global inbox in the message store.
-messaging\sms\clientmtm A plug-in to the message server framework to provide a generic API for creation of SMS messages (SMS Client MTM & SMS utilities)
-messaging\sms\servermtm A plug-in to the message server framework to provide a generic API for sending of SMS messages (SMS Server MTM)
-3.1.2.2 CDMA SMS
-The CDMA SMS plug-ins provide application level support for the CDMA Short Message Service messages.
-Component Description
-messaging\biomsg\BioWatchersCdma Plug-ins to the watcher framework to listen for CDMA SMS messages and deliver them to the global inbox in the message store.
-messaging\sms\multimode\clientmtm A plug-in to the message server framework to provide a generic API for creation of CDMA SMS messages (CDMA SMS Client MTM)
-messaging\sms\multimode\servermtm A plug-in to the message server framework to provide a generic API for sending of CDMA SMS messages (CDMA SMS Server MTM)
-
-3.1.2.3 Email
-The email plug-ins provide support the POP3, IMAP4 and SMTP email protocols and support for parsing and generating plain test, MIME and M-HTML format email messages.
-Component Description
-messaging\email\clientmtms A plug-in to the message server framework to provide a generic API for creation of email messages (IMAP4 SMTP and POP3 Client MTMs & email utilities)
-messaging\email\imapservermtm A plug-in to the message server framework to provide a generic API for access to a remote IMAP4 server (IMAP4 Server MTM)
-messaging\email\smtpservermtm A plug-in to the message server framework to provide a generic API for access to a remote SMTP server (SMTP Server MTM)
-messaging\email\popservermtm A plug-in to the message server framework to provide generic API for access to remote POP3 server (POP3 Server MTM)
-messaging\email\servermtmutils Email utilities for parsing plain text and MIME email messages. It also provides an abstraction of the TCP/IP sockets for use by the SMTP POP3 and IMAP4 plug-ins.
-messaging\email\autosend An executable that requests SMTP Server MTM to send messages in the outbox. This is used to provide send on next connection functionality and is started by the POP3 and IMAP4 Client MTMs.
-3.1.2.4 OBEX
-The OBEX MTM is a set of plug-ins to the message server that provides support for IR and Bluetooth beaming.
-Component Description
-messaging\obex\btmtm\btclient\group\btcmtm Bluetooth Client MTM
-messaging\obex\btmtm\btserver\group\btsmtm Bluetooth Server MTM
-messaging\obex\irmtm\irclient\group\ircmtm IR Client MTM
-messaging\obex\irmtm\irserver\group\IRSMTM IR Server MTM
-messaging\obex\obexmtm\obexclient\group\obexClientMtm OBEX Client MTM, base classes for the Bluetooth and IR Client MTMs
-messaging\obex\obexmtm\obexserver\group\obexServerMtm OBEX Server MTM, base classes for the Bluetooth and IR Server MTMs
-messaging\obex\obexmtm\obexutil\group\obexMtmUtil OBEX MTM utilities
-3.1.2.5 MMS
-The MMS MTM is a plug-in to the message server that provides support for MMS messages. From v9.0 and onwards MMS MTM and related components are removed.
-Component Description
-messaging\mms\utils MMS Utilities
-messaging\mms\servermtm MMS Server MTM
-messaging\mms\mmswatcherplugins MMS plug-ins to WAP push framework to handle reception of MMS notifications
-messaging\mms\codec MMS utilities for handling MMS codecs
-messaging\mms\clientmtm MMS Client MTM
-3.1.2.6 GMXML
-GMXML is a parser/generator for SMIL presentations for MMS messages.
-Component Description
-messaging\GMXML\XMLParser XML parser designed for parsing of SMIL messages
-messaging\GMXML\XMLDom XML document object model designed for parsing of SMIL messages
-messaging\GMXML\SMILdtd SMIL DTD
-3.1.2.7 Bio Message Plug-ins
-These parsers plug into the bio messaging framework to handle specific types of bio message.
-Component Description
-messaging\biomsg\cbcp\CBCP Compact business card parser
-messaging\biomsg\enp\ENP Email notification parser
-messaging\biomsg\gfp\gfp General file parser
-messaging\biomsg\iacp\IACP Nokia Smart Message Internet Access Parser
-messaging\biomsg\wapp\wapp Nokia/Ericsson OTA Parser
-3.1.2.8 PCMTM
-Plug-in to the message server that provided email synchronisation with a PC. This component has been deprecated in 8.0a and will not been documented in the API section below.
-3.1.2.9 Fax
-Plug-in to the message server that provides fax support. This component has been deprecated in 8.0a and will not been documented in the API section below.
-
-3.2 General Description
-3.2.1 Messaging / Message Server and MTM Architecture APIs
-3.2.1.1 Key Internal Relationships and Dependencies
-
-Figure 2 MTM Relationships
-Figure 2 shows the relationship between the Message Server and the MTM plug-ins. The grey classes are realisations of the MTM interfaces defined by the messaging framework. The message server depends on the Server MTM interface. Messaging Clients depend on the Client, UI and UI Data MTM interfaces and the Message Server Client API.
-3.2.1.2 Key External Relationships and Dependencies
-
-Figure 3 External Dependencies
-The grey package representing the messaging client depends on the Client, UI and UI Data interfaces and the Messaging Client API. The message server then depends on:
-• Charconv – Provides character set conversion routines, used to convert encoded message body text to Unicode body text.
-• EStore – Provides API to handle a stream based store used for the messaging index file and the framework classes for the message store files. (omitted from other dependency diagrams as it is implied by the dependency on the message server)
-• F32 – Provides the file server APIs used to access the file system directories in which messaging stores files containing message data. (omitted from other dependency diagrams)
-• BAFL – Provides API to load the correct messaging resource file dependent on the current language and to register the message store index file with the backup server. (omitted from other dependency diagrams)
-• ETEXT – Rich text APIs used to store body text of messages, this rich text format is a Symbian Proprietary format. (omitted from other dependency diagrams)
-• EUSER – Core Symbian OS utilities such as descriptors, arrays, client / server framework, cleanup stack and others (omitted from this and other dependency diagrams).
-• Central Repository – Centralised and secure storage facility for application settings, the message server stores message settings data in the central repository (from v9.0 and onwards).
-Note that debug only dependencies such as the flogger have been omitted from dependency diagrams.
-3.2.1.3 API Purpose - Further Elaboration
-3.2.1.3.1 Message Store
-The message server provides persistent storage of messages and messaging account settings. It does this by providing a message store consisting of a tree of message entries. Multiple clients can access the message store simultaneously. Each entry in the tree can represent an email account, folder of messages, message part, etc.
-
-Figure 4 Message Store
-Figure 4 shows an example message store. The tree is broken down in to three levels:
-1. The Root entry. This entry is just present to tie the tree structure together
-2. Service entries. There is one local service under which local folders and messages are stored, and zero or more remote services. Remote services represent message accounts.
-3. Message & Folder entries. Messages and folders, under the local service represent messages stored on the device. Messages and folders under remote services represent a local copy of messages that are present on a remote server. For example under a POP3 email service you would have copies of all the messages present on the POP3 email server, or under an SMS service you might find SMS messages that are stored on a SIM.
-The message server controls access to the entries in the store. It enforces the three levels therefore attempts to create message or folder entries directly under the root entry will fail.
-The message server provides three types of storage for each entry in the message store:
-• Index entry - TMsvEntry - intended to provide enough information for UI to display list views as shown in Figure 5. This consists of two strings and various flags (read, complete, has attachments etc).
-• Stream based file store - CMsvStore – provides storage of streams of data associated with UIDs. A standard UID is defined for storing body text. Other UIDs are specific. For example the email MTMs define a UID for storage of MIME headers. Compared to the index entry information this is used to store larger objects and is extensible, at the cost of being slower to access. From v9.0 and onwards CMsvStore provides an Attachment API for managing attachments. The Attachment API should be used as attachments can no longer be accessed directly due to Platform Security.
-• Directory of files – normally used for attachments.
-The only storage type that is always present is the index entry. The stream store and the directory of files are optional.
-
-Figure 5 Series 60 Inbox List View
-
-Figure 6 Remote and Local Entries
-As shown in Figure 6 the message store is split into two sets of entries:
-• Remote entries - entries that are representations of entries stored on a remote store .
-• Local entries - entries not linked to a remote store.
-The message server handles changes to local entries; internally it hands off changes to remote entries to the Server MTM that owns that service. Examples of operations that are handed off to Server MTMs are operations involving copying and moving messages to and from a remote service. See section 3.2.1.3.5 or more information on Server MTMs.
-Each entry within the store has a type:
-Folder – Messages can be grouped into folders. Standard folders such as inbox / outbox and user created folders.
-Message – Storage of the content of a message. Message entries can have child entries used to represent the structure of a message.
-Attachment – These represent attachments under a message entry.
-Root & Local Service Entry – There tie the tree structure together. However the Stream store associated with the root entry is sometimes used by UIs to store preferences e.g. default folder views etc.
-Remote Service - Represents a source and / or destination for messages. They are used to store the settings associated with the source / destination.
-Message Type Specific - MTMs can create other message types for use as child entries to messages they own. For example email uses a tree structure, with a message entry as the root, to represent the MIME structure of an email message; it uses folder entries to represent MIME folders and adds new types for entries representing the html body and text body parts of a message. This is shown in Figure 7.
-
-Figure 7 Email Message
-Using the message store to represent message structure allows reuse of the tree structure and makes it very simple to represent one message embedded in another. However this representation introduces performance issues as it results in each message having multiple files associated with it. The message server also keeps all index entries in memory; therefore this representation increases the memory footprint of the message server. Therefore when designing new MTMs we should think about moving away using multiple index entries to store one message in the message store.
-A default message store is created if the message server starts and no message store is present or a corrupt message store is present. The server will initially create a store with just a root entry, and then the server will create any standard folders defined in the resource file msgs.rsc. Finally the server will check whether an executable ‘mailinit.exe’ is present on the system, if it is present the server will launch the executable to allow customisation of the message store. The behaviour of ‘mailinit.exe’ is defined by the UI family of the device. However the typical behaviour is to load each of the UI Message Type Modules and allow each to perform any message type specific initialisation. For example the SMS plug-in typically creates a default service entry.
-
-3.2.1.3.2 Data File Storage (pre - v9.0)
-This section describes the files used by the message server before release v9.0. For information on the files used for release from v9.0 and onwards see section [3.2.1.3.3.1].
-Filename Access Purpose
-?:\system\Mail\index Private Message server index file, internal to message server
-?:\system\Mail\<8 hex digits> Shared via API Message server store files for services, clients access these via a messaging API.
-?:\system\Mail\<8 hex digits>.new Shared via API Temporary file used during committing message server store files.
-?:\SYSTEM\MAIL\<8 HEX DIGITS>_F\* Shared Files associated with a messaging service. These may be accessed directly by clients.
-?:\system\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits> Shared via API Message server store files for message entries, clients access these via a messaging API.
-?:\system\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits>.new Shared via API Temporary file used whilst committing message server store files.
-?:\system\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits>_F\* Shared Files associated with a message entry. These are accessed directly by clients.
-c:\system\data\msgs.ini Private Stores the drive containing the last used message store
-c:\system\Mtm\Mtm Registry v2 Private Cache of registered MTMs, internal to message server
-C:\system\data\sms_settings.dat Shared Copy of the SMS settings.
-?:\System\Mail\StoreInit.tmp Shared Created when message server runs ‘mailinit.exe’, ‘mailinit.exe’ should delete the file when it has successfully completed.
-?:\System\Mail\storedeleted.tmp Shared Created when message server finds and deletes a corrupt message store. Allows the UI to inform the user about the fact that the message store was corrupt.
-Files that are shown as private should only be accessed by the message server or by connectivity process for backup and restore purposes. Files listed as shared are accessed directly by messaging clients. Files listed as shared via API are accessed by client process but only via messaging APIs.
-3.2.1.3.3 Platform Security Compliant Message Store
-From v9.0 and onwards the message store is stored in the message server's data cage and the settings data are placed in the Central Repository. Access to the message store is only possible via message server APIs and not directly through file access. This leads to secured data storage and secured platform.
-3.2.1.3.3.1 Data caging
-Filename Purpose
-?:\private\<SID>\Mail\index Message server index file, internal to message server
-?:\ private\<SID>\Mail\<8 hex digits> Message server store files for services, clients access these via a messaging API.
-?:\ private\<SID>\Mail\<8 hex digits>.new Temporary file used during committing message server store files.
-?:\ private\<SID>\Mail\<8 hex digits>_F\* Files associated with a messaging service. These may be accessed directly by clients.
-?:\ private\<SID>\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits> Message server store files for message entries, clients access these via a messaging API.
-?:\ private\<SID>\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits>.new Temporary file used whilst committing message server store files.
-?:\ private\<SID>\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits>_F\* Files associated with a message entry. These are accessed directly by clients.
-c:\ private\<SID>\data\msgs.ini Stores the drive containing the last used message store
-c:\ private\<SID>\Mtm\Mtm Registry v2 Cache of registered MTMs, internal to message server
-?:\ private\<SID>\Mail\StoreInit.tmp Access via IPC call
-?:\ private\<SID>\Mail\storedeleted.tmp Created when message server finds and deletes a corrupt message store. Allows the UI to inform the user about the fact that the message store was corrupt.
-?\resource\messaging\bif\*.bif Registration data field with UID used in BIO framework
-
-3.2.1.3.4 How message centres display the message store
-The UI normally provides a Message Centre application to display the structure of the message store to the user. Different UIs map the structure to different views.
-
-Figure 8 Series 60 Message Centre (Composed from 2 screen shots)
-Figure 8 shows the top level view of the message centre application on a Series 60 phone. This shows that the message centre has hidden the local service and shows the standard folders at the same level as the services. Also the SMTP, SMS and MMS services are marked as hidden entries in the message store, and so do not appear in the message application.
-
-Figure 9 UIQ Message Centre
-However Figure 9 shows that the UIQ message centre has no 1-1 mapping from the structure in the message store to the structure shown to the user. Each of the message types is displayed as if its messages were contained in separate folders. Under each of these folders the user is presented with an inbox, outbox, send and drafts folder. This filtering is done in the UI layer as this functionality is not provided by the messaging API.
-3.2.1.3.5 Message Type Module Architecture
-
-Figure 10 Messaging MTM Structure (light coloured components are part of messaging subsystem)
-The MTM architecture is the plug-in scheme provided by the messaging framework to integrate different message transports into the message server. The plug-in scheme consists of four interfaces, the UI MTM, UI Data MTM, Client MTM and Server MTM. The messaging client applications loads and uses the first three which are loaded within the client’s process space. The final one the Server MTM is loaded within the message server process. The APIs for the client facing interfaces are extensible via run time type information provided by the QueryCapability API, and the InvokeAsyncFunction and InvokeSyncFunction APIs.
-3.2.1.3.5.1 UI MTM
-Handles requests from clients to view and edit messages or service settings. The MTM handles interaction with the message centre and as such the exact meaning of the APIs is defined by the UI. However common meanings are:
-• Create – Launches the editor with a new message.
-• Edit – If entry is a message this launches the editor; if entry is a service it edits the settings.
-• View – Launches the message viewer.
-• Display progress of an operation.
-3.2.1.3.5.2 UI data MTM
-This MTM provides fast access to UI components such as menu resources and bitmaps required by message centre for list views etc. Again the exact semantics are UI specific.
-There is a resource file defining UI specific functions, for example the Series 60 Messaging UI checks if the resource file contains text to display in the “New Message” menu.
-The UI data MTM also provides mapping from the message store’s TMsvEntry structure to Icons for the messaging list views and a status string, for example in the case of Nokia 9210 it is used in the outbox view to provide strings like “Resend 01:07” as shown in Figure 11. The class also provides functions to determine what operations are possible with a given entry. Examples of this are APIs that return whether the UI should allow the user to reply to the entry or to delete a service entry. The UI then uses this information to determine which menu options / short-cut keys should be allowed when the user selects a given entry.
-
-Figure 11 Nokia 9210 Outbox List View
-3.2.1.3.5.3 Client MTM
-Provides methods to create / reply and forward messages. Functions the Client MTMs provide are:
-• Create Message.
-• Reply to a Message.
-• Forward a Message.
-• Add / remove Addressees.
-• Add / remove body text.
-• Add / remove subject.
-• Add / remove attachments (the API cannot list attachments).
-The Client MTM interface is used by SendAs to provide a way of creating messages independently of the message type.
-3.2.1.3.5.4 Server MTM
-This is the final interface that makes up an MTM plug-in; it differs from the other three plug-ins in that it is loaded into the message server’s process space. The Server MTM provides access to messages under remote services. It handles connecting to remote servers to handle updating the local cache of these messages or to send messages copied to remote services when messages are copied to a remote service. The message server loads and hands off all message store operations that involve entries under a remote entry, these are the entries on the left-hand side of Figure 6.
-Functions that a Server MTM must implement:
-• Copy/MoveToLocal – called when the message server is asked to move or copy an entry that is currently under a remote service. A Server MTM might map this to retrieving a message from a remote mailbox.
-• Copy/MoveFromLocal – called when the message server is asked to move or copy from under the local service to a destination under a remote service. A Server MTM should map this to sending a message if the MTM supports sending.
-• Create, Delete, Change – called when the message server is asked to perform these operations on entries under a remote service.
-• StartCommand – this API provides a means of extending the API the Server MTM provides. Messaging clients pass a command ID and a selection of entries via the message server to the Server MTM. Examples of commands that Server MTMs might provide are: connect and synchronise the entries under a remote service with the messages on an email server, list SMS messages present on the phones SIM. These commands are MTM specific and therefore clients have to know which MTMs support which commands.
-3.2.1.3.5.5 MTM Registration
-MTMs must be registered with the message server so that clients can query what MTMs are present and the server knows which DLL to load to create a given MTM component. MTMs are registered by providing a resource file containing the MTMs UIDs, human readable name, and for each MTM interface it lists a DLL and the ordinal at which the constructor for that interface exists. The message server will search the ROM drive for MTM registration resource files on start-up and it will automatically register any MTMs found. For registration of MTMs installed on other drives, the message server provides an API to register and de-register an MTM. Registration will persist across a reboot, so an MTM only needs to be registered when it is installed on the system.
-When MTMs are registered or unregistered the message server will send events to all messaging clients with a message server session open.
-3.2.1.3.6 Message Server Client API
-The Messaging Server Client API breaks down into two categories: APIs for manipulation of the message store and utility APIs.
-3.2.1.3.6.1 Message Store manipulation APIs
-Requests from clients to modify the message store fall into three categories:
-1. Operations performed entirely with local entries (entries on the right-hand side of Figure 6) for example requests to create entries in the inbox, delete an entry from the drafts folder etc. The message server handles these operations directly.
-2. Operations that involve a remote entry (entries on the left-hand side of Figure 6) for example requests to delete an entry under a POP3 service, or copy a message to an SMTP service. The message server hands these operations off to the Server MTM that owns the service under which the remote entry is stored. The only exception to this rule is the ChangeAttributes API call. This modifies flags on an index entry and is handled by the message server for both local and remote entries. This means that a Server MTM can not rely on being called when flags like the Unread flag are changed. Note that operations can not involve two remote entries; therefore requests to copy entries between a remote service representing one POP3 account to a remote service representing another POP3 account will fail with an error.
-3. Requests that are explicitly directed at a Server MTM via the TransferCommand API. These commands are just passed to the correct Server MTM by looking up the Service ID and MTM of the first message in the selection passed into the command.
-The message server sends events when entries in the message store are modified to messaging clients that have a session open with the server.
-Where the API provides asynchronous functions to modify the message store or transfer a command to a Server MTM, the functions will return a message server operation object. This object can be used to request progress on operation or cancel the operation. Deleting the operation object returned, or closing the session used to make the request will result in the operation being cancelled, therefore a messaging client must remain running until operations it has requested have either completed or they will be cancelled. See appendix A.1 for an example of an asynchronous copy operation. If a Server MTM operating on the same remote service is already handling an operation, the message server will queue the new operation to be handled when the Server MTM becomes free. Requests for progress of operations that are queued will fail with KErrNotReady. The fact that the queue is based on the remote service ID means that you can have two Server MTMs of the same type running at the same time as long as they are operating on different services. So for example you can have two separate POP3 MTMs running synchronising different remote services with email servers.
-3.2.1.3.6.2 Utility APIs
-1. Access to MTM registries – These allow clients to construct instances of the interfaces an MTM implements.
-2. Register / Unregister an MTM.
-3. Change Drive – The message server closes the current message store and opens one on the drive specified. If no message store is present on the drive specified a new message store is created. The message sever can have only one mail store open at a time, if the current mail store is not available because a the disk the mail store is on is not present then the message server will switch the mail store back to the C: drive if an attempt is made to create a message in the inbox.
-4. Launching Editors – This launches the correct editor for a message. It is implemented by delegating the request to the UI MTM
-3.2.2 Messaging / Send As APIs
-3.2.2.1 Key Relationships and Dependencies
-
-Figure 12 SendAs Version 1 Dependencies
-SendAs version 1 and only present in releases before v9.0. SendAs uses the Messaging Client API to access the registry of Client MTMs and construct the Client MTM interfaces. The Client MTMs are then used for composing the message. SendAs requires clients to implement the MSendAsObserver interface. This interface is responsible for checking the return value of the capability queries made to Client MTMs that require a response and also for rendering message types that require it. The only message type supplied by Symbian that requires rendering is Fax, however this MTM has been removed in 8.0a and future releases.
-3.2.2.2 API Purpose - Further Elaboration
-3.2.2.2.1 SendAs API (pre – v9.0)
-The SendAs API makes use of the Client MTM interface and the Messaging Client API to provide a generic API for creating messages. Note despite the name of this component SendAs does not provide an API to send the message.
-SendAs builds a list of registered MTMs, then queries each MTM to check whether it supports sending, removing those MTMs from the list that do not support sending. This list is then provided to the messaging client application. At this point the application can add more constraints on the list of MTMs; for example it can insist the MTM supports Attachments or more than a certain size of body text. SendAs queries each of the MTMs about the requirements and will drop any MTMs from the list that does not meet them. When the application has finished adding requirements it selects one of the MTMs left in the list and uses that to compose the message, adding addresses, a subject, body text and attachments.
-SendAs supports setting a BIO Type for the message that is composed. This tells the transport that the body text represents a BIO Message. This is used when sending business cards from the contacts application as SMS messages; the contacts application puts the vCard data in the body text of the message and the transport sends it correctly. If the MTM in question supports attachments then the vCard is attached to the message.
-A new CSendAs object must be created for each message the application wishes to create.
-3.2.3 Platform Security Compliant SendAs Server (v9.0 onwards)
-
-Figure 13 SendAs Version 2 Dependencies
-From v9.0 and onwards the CSendAs has been replaced by the SendAs server component. The new SendAs server controls the access to the message store. Some of the key SendAs Server features are listed as follows.
-• Send a message once the capability policing of the client application has been completed.
-• Allow client applications to launch an editor for a specified message type.
-• Allow client applications to query the message type.
-The main client-side API is the RSendAs class. The client applications use this to connect to the Send-As server. The session object on the server-side is an instance of CSendAsSession.
-Client applications create messages using the RSendAsMessage API. Opening an RSendAsMessage object on Send-As server session creates a CSendAsMessage object in the Send-As server. There is a one-to-one mapping between an RSendAsMessage object and a CSendAsMessage object. This allows client applications to create multiple messages concurrently.
-
-3.2.4 Messaging / Schedule Send APIs
-3.2.4.1 Key Relationships and Dependencies
-
-Figure 14 Schedule Send Dependencies
-The Schedule Send Server MTM base class depends on the task scheduler to launch the schedule send executable at the correct time. To send the message with a package of data previously passed into the task scheduler by the Server MTM. The schedule send executable then uses the Messaging Client API to actually perform the requested operation.
-3.2.4.2 API Purpose - Further Elaboration
-3.2.4.2.1 Schedule Send
-The Schedule Send functionality is delivered by four components:
-Server MTM Base Class – The base class provides support to Server MTMs that wish to support scheduled operations.
-Data Structures – These are classes used to represent the data associated with a scheduled operation.
-Executable – The executable is run by the task scheduler at the scheduled time.
-The Task Scheduler – This component is part of the system libraries subsystem. Currently the SMS and Fax Server MTMs support scheduled sending.
-Clients request the Server MTM schedules operations via additional commands passed to TransferCommand API; this is passed to the Server MTM via the message server. The Server MTM packages the operation ID, a selection of message IDs, how often to poll for progress and an MTM specific buffer. It then passes this package of data to the task scheduler requesting that it launches the schedule send executable at the correct time with the packaged information.
-When the task scheduler launches the schedule send executable, it unpacks the schedule information and uses the Messaging Client API to request the Server MTM to perform the operation.
-Schedule Send supports a retry mechanism if the operation fails. The Server MTM has a resource file containing a mapping from the error codes the operation can fail with and actions to be performed. For example the SMS resource file has a mapping such that if the operation fails with an error code indicating a bad phone number the SMS will be set to failed and left in the outbox. Whereas if it fails with a error code indicating temporary network failure the send operation will be scheduled to be resent later with a maximum of three retries.
-3.2.5 Messaging / Watchers APIs
-3.2.5.1 Key Relationships and Dependencies
-
-Figure 15 Watcher Dependencies
-The watcher executable’s dependency on the message server is the result of a performance measure. The watcher process creates a message server session before initialising each of the watcher plug-ins and closes the session when it has finished. This keeps the message server running during initialisation avoiding starting and stopping the message server if each watcher plug-in opens and closes sessions.
-3.2.5.2 API Purpose - Further Elaboration
-The watcher framework consists of an executable that is launched when the device boots. The component that is responsible for launching it depends on the UI family. When the watcher.exe is launched it will load each DLL in z:\system\libs\watchers which has a second UID as KWatcherUid and calls the first DLL entry point to construct a CActive object.
-From v9.0 and onwards watcher DLLs are found by scanning the directory \resource\messaging\watchers for registry files. These files contain the name of a watcher DLL that can be loaded from ROM i.e. z:\sys\bin.
-The framework has retry behaviour if the first entry point leaves, in this case the watcher framework will start a timer and try and construct the watcher object 10 seconds later. Five attempts are made before the watcher plug-in is assumed to have failed completely. Once the watcher framework has constructed all the watchers it starts the active scheduler which should never exit.
-Watcher plug-ins typically make a request to another subsystem such that they will be completed when an external event like a fax line ringing or an SMS being received occurs. When the watcher has completed processing the request it will wait for the next event.
-No support for starting / stopping watchers is provided. This is a limitation that makes watchers unsuitable for operations like listening for messages beamed via IR, as the watcher should only run while the IR port is active.
-3.2.6 Messaging / Message URL Handler APIs
-3.2.6.1 Key Relationships and Dependencies
-
-Figure 16 Message URL Handler Dependencies
-3.2.6.2 API Purpose - Further Elaboration
-The Message URL Handler provides support for creating messages and launching messaging editors from URLs such as mailto:infobot@example.com?subject=current-issue. Note there is no dependency between the Message URL Handler application which processes the URLs and the Message URL Handler recognisers which maps from URLs to mime types.
-3.2.6.2.1 Message URL Handler Application
-This is a Symbian OS application that registers with the application framework that it can handle the mime types: x-epoc-url/fax, x-epoc-url/mailto and x-epoc-url/sms. When launched with a URL it will parse the URL to retrieve the address and other header fields and then use the SendAs API to create a new message with the correct address, headers etc. The application then uses the APIs in the MturUtils class provide by the mtmbase component in the messaging framework to launch the correct editor for the given message type. The application is marked as hidden and therefore should not be listed by UIs in application browsers.
-3.2.6.2.2 Message URL Recognisers
-This is a plug-in to the recogniser framework it will be called when the application framework wishes to recognise a file. Recognisers are called with the file name, in this case a URL, and a buffer containing the start of the file. The message URL recogniser compares the start of the URL with the URL schemes it recognises, if it finds a URL scheme it knows about it maps it to a mime type. The recogniser ignores the buffer passed in.
-Schemes recognised:
-Scheme Mime type
-mailto: X-Epoc-Url/mailto
-fax: X-Epoc-Url/fax
-sms: X-Epoc-Url/sms
-mms: X-Epoc-Url/mms
-See the application framework architectural description for more information on recognisers [R2].
-3.2.7 Messaging / SMS APIs
-3.2.7.1 Key Internal Relationships and Dependencies
-
-Figure 17 SMS Internal Dependencies
-3.2.7.2 Key External Relationships and Dependencies
-
-Figure 18 SMS External Dependencies
-3.2.7.3 API Purpose - Further Elaboration
-3.2.7.3.1 SMS Watchers
-The SMS watchers are made up of two watchers, the nbswatcher.dll and the wapwatcher.dll, and some common base classes in biowatcher.dll. The watchers listen for incoming messages from the SMS stack, part of the nbsprotocols subsystem [R3], and the WAP stack part of the WAP-Stack subsystem [R4].
-3.2.7.3.1.1 NBS Watcher
-The NBS watcher handles reception of SMS messages. When initialised by the watcher framework (see section 3.2.4) the watcher queries the bio messaging database for bio messages that are listed as having a type of ENbs. For each of these bio messages the watcher creates an object that opens a connection to the SMS stack and waits for the particular message type. The message types are either defined by the port number the message will be received on or by a string to watch for at the start of the message. For example Internet Access Configuration Point messages are start with “//SIAP11” and vCards are received on port 226. Finally the watcher listens for all other messages received from the SMS stack.
-When the NBS Watcher receives a non-class 2 SMS message it creates a new entry under the global inbox in the message store. For class 2 messages the entry is created in the class 2 folder as defined by the SMS settings, this may also be the global inbox. The details field of the entry is used to store the phone number of the incoming message or the name of the sender if the watcher finds a match for the phone number in the contacts database. The description field is used to store the first N characters of the SMS message, where N is defined in the SMS settings, or for bio messages the description as retrieved from the bio database. Bio messages also have the BioType field set to the UID of the bio message as retrieved from the bio database. The CSmsHeader class, which is a wrapper around the CSmsMessage class provided by the nbprotocols subsystem [R3], is used to externalise the SMS message to the entry’s CMsvStore. The watcher also places a copy of the body text of the message in the rich text stream of the entry’s CMsvStore.
-The NBS Watcher is also responsible for handing special SMS types including:
-• Replace Type Messages – When the watcher receives a message of this type it will scan the folder the message would have been delivered to for messages that have a matching protocol ID and from address. For each of the messages it checks whether the time stamps from the service centre and discards the older message.
-• Message Indications – The watcher can listen for incoming message waiting indications. The CSmsSettings class defines whether the watcher will listen and whether it will deliver the messages to the inbox or discard them. If the watcher is configured to listen for messages then it will use the SMS utilities in the SMS Client MTM to decode the message to determine the notification type and number of messages, e.g. 3 Email messages waiting, the strings for these messages are in the smss.rss resource file.
-• Delivery Reports – As with Message Indications the watcher can be configured to listen for these and again the SMS utilities get a string from the smss.rss resource file to put in the description field.
-The NBS Watcher handles changes to the bio database using the observer mechanism provided by the bio message database to observe when bio message types are added or removed and starting or stopping the object watching for that bio message type.
-3.2.7.3.1.2 WAP Watcher
-The WAP watcher listens for incoming messages from the WAP stack using the WAP message API [R4]. To determine ports to use to listen for messages the watcher queries the bio message database for bio message types EWsp, EWspSecure, EWap, EWapSecure and registers as an observer of the bio database and so will listen for new bio message with these types as they are added. The watcher stores the messages in the global inbox tagged with the bio type listed in the bio message database.
-3.2.7.3.2 SMS Client MTM
-The SMS Client MTM implements the standard set of Client MTM APIs described in Client MTM. In addition it provides:
-• Access to the CSmsHeader object that is used to represent the SMS message.
-• Access to the SMS settings stored in the associated SMS service.
-• The APIs required by Send As to allow Send As to create SMS messages including setting the bio type of the message to allow clients of Send As to send bio messages such as vCards and vCals. The data of the bio message is stored in the body text of the SMS message.
-• Simple check for valid SMS addresses, and SMS address is considered valid if it contains at least one digit.
-• Reading and writing SIM parameters.
-3.2.7.3.3 SMS Utilities
-These provide:
-• Classes to represent and store SMS messages (CSmsHeader), and SMS settings (CSmsSettings, CSmsMessageSettings) and a SMS number (CSmsNumber).
-• The CSmsHeader class contains and allows clients to access the CSmsMessage class that the nbsprotocols subsystem provides. This contains the entire SMS message and not just the header.
-• Functions to generate descriptions and details fields to store with SMS messages, including decoding special messages such as message indication and status report messages, reading resource file for descriptions strings of special messages, using the contacts database to replace phone numbers with names.
-• API to validate a GSM number.
-• Find the TMsvId of the SMS service entry.
-3.2.7.3.4 SMS Server MTM
-3.2.7.3.4.1 Sending Messages
-The SMS Server MTM handles sending of SMS and WAP messages via the SMS stack and the WAP stack. To support this it implements the CopyFromLocal API inherited from the Server MTM base class. It implements this as sending SMS messages and moving successfully sent messages to the Sent folder. When sending the SMS message the Server MTM checks the bio type of the message and uses the bio database to check the transport type for the bio message. The MTM supports ENbs that is sent via the SMS stack and EWap, EWapSecure that are sent via the WAP stack. The MTM does not support EWsp or EWspSecure although the watchers do support receiving them.
-If a message fails to send, sending is retried according to the settings in the smss.rss resource file as described in the schedule send section 3.2.3.
-3.2.7.3.4.2 Scheduling Messages
-The SMS Server MTM implements scheduled sending API by sub-classing from the schedule send Server MTM (see section 3.2.3). It accepts requests from clients either via the SMS Client MTM InvokeAsync API or via the CMsvSession::TransferCommand API to schedule messages to be sent or to delete existing schedules. When it receives a request to schedule a message it packages up the command and uses the scheduled send functionality to request that the task scheduler ask it to send the messages at a future point in time.
-3.2.7.3.4.3 Phone Store
-The phone store is the name given to storage of SMS messages outside of the message store. In the case of GSM phones this is the SIM. The SMS Server MTM accepts requests from clients to copy/move messages to and from the SIM and delete messages from the SIM. For example when copying to the SIM it packages up the SMS message and passes it to the SMS stack with a request to write it to the SIM. If the class2 folder has been set in the SMS settings class then the Server MTM will copy the SMS message to the SIM and then update the SMS message in the message store with details of the slot on the SIM that has been used to store the SMS and the fact that it is stored on the SIM.
-3.2.7.3.4.4 SIM Parameters
-The Server MTM provides functions to read / write SIM parameters, again these requests are passed to the SMS stack to be processed.
-3.2.8 Messaging / CDMA SMS APIs
-3.2.8.1 Key Internal Relationships and Dependencies
-
-Figure 19 CMDA SMS Internal Dependencies
-3.2.8.2 Key External Relationships and Dependencies
-`
-Figure 20 CDMA SMS External Dependencies
-3.2.8.3 API Purpose - Further Elaboration
-3.2.8.3.1 CDMA SMS Watchers
-The CDMA SMS watchers are made up of six watchers, the cdmanbswatcher.dll, vmnwatcher.dll, wemtwatcher.dll, wmtwatcher.dll, wptwatcher.dll, and the wapwatcher.dll, and some base classes in biowatcher.dll and cdmasocketwatcher. While the WAP watcher is common for both GSM and CDMA, the other watchers: CDMA NBS watcher, VMN watcher, WEMT watcher, WMT watcher, and the WPT watcher are used for CDMA only. The watchers listen for incoming messages from the CDMA SMS stack, part of the nbsprotocols subsystem [R3], and the WAP stack part of the WAP-Stack subsystem [R4].
-3.2.8.3.1.1 CDMA NBS Watcher
-The CDMA NBS watcher is similar to the NBS watcher and it handles bio messages defined in bio database. The CSmsHeader class is extended to wrap around the CCdmaSmsMessage class provided by the nbprotocols subsystem [R3], and is used to externalise the CDMA SMS message.
-For handling special CDMA SMS type, the CDMA NBS watcher is responsible for handling Message Indications as described in section 3.2.7.3.1.1 NBS Watcher.
-3.2.8.3.1.2 WAP Watcher
-The GSM WAP watcher is used to handle CDMA WAP message as well. The WAP watcher listens for incoming messages from the WAP stack, which can listen from the CDMA SMS stack or GSM SMS stack as appropriate. See 3.2.7.3.1.2 for more info about WAP watcher.
-3.2.8.3.1.3 Other CDMA Watchers
-The VMN watcher, WEMT watcher, WMT watcher and WPT watcher are CDMA watchers that handle reception of CDMA SMS messages. All CDMA SMS messages are associated with a teleservice. Therefore, each of the CDMA watchers is responsible for handling one teleservice: VMN watcher handles VMN SMS messages, WEMT watcher handles WEMT SMS messages, WMT watcher handles WMT SMS messages, and WPT watcher handles WPT SMS messages. The CSmsHeader class is reused to externalise the CDMA SMS message.
-The CDMA watchers are also responsible for handling special SMS types including:
-• Duplicate Message – When the watcher receives a duplicate message, it will discard the duplicate message as defined by the CDMA service settings.
-• User Acknowledge – The watcher can listen for user acknowledgment message of its teleservice type.
-• Delivery Acknowledge – The watcher can listen for delivery acknowledgment message of its teleservice type.
-• Read Acknowledge – The watcher can listen for read acknowledgment message of its teleservice type.
-3.2.8.3.2 CDMA SMS Client MTM
-The CDMA SMS Client MTM implements the standard set of Client MTM APIs described in Client MTM. In addition it provides:
-• Access to the CSmsHeader object that is used to represent the SMS message.
-• Access to the SMS settings stored in the associated SMS service. These settings are store in file store pre v9.0 but stored in Central Repository from v9.0 onwards.
-• The APIs required by Send As to allow Send As to create SMS messages including setting the bio type of the message to allow clients of Send As to send bio messages such as vCards and vCals. The data of the bio message is stored in the body text of the SMS message.
-• Simple check for valid SMS addresses, and SMS address is considered valid if it contains at least one digit.
-• Reading and writing SMS messages to R-UIM.
-3.2.8.3.3 CDMA SMS Utilities
-The CDMA version of SMS utilities are binary compatible with the GSM version of SMS utilities. But the classes that store SMS Message (CSMSHeader), and SMS settings (CSmsSettings, CSmsMessageSettings) and SMS number (CSmsNumber) are extended to store CDMA information. The CSmsHeader class is extended to contain and allow clients to access the CCdmaSmsMessage in addition to the CSmsMessage. Other functions provided by the GSM SMS Utilities is also provided by the CDMA version of SMS utilities, see 3.2.7.3.3 for information about GSM SMS Utilities.
-3.2.8.3.4 CDMA SMS Server MTM
-3.2.8.3.4.1 Sending Messages
-The CDMA SMS Server MTM handles sending of CDMA SMS and WAP messages via the CDMA SMS stack and the WAP stack. To support this it implements the CopyFromLocal API inherited from the Server MTM base class. It implements this as sending SMS messages and moving successfully sent messages to the Sent folder. When sending the CDMA SMS message the Server MTM will use the appropriate teleservice type. The MTM supports ENbs that is sent via the SMS stack and EWap, EWapSecure that are sent via the WAP stack. The MTM does not support EWsp or EWspSecure although the watchers do support receiving them.
-If a message fails to send, sending is retried according to the settings in the smss.rss resource file as described in the scheduled send section 3.2.4.
-3.2.8.3.4.2 Scheduling Messages
-The CDMA SMS Server MTM implements scheduled sending API by sub-classing from the schedule send Server MTM similar to implemented in the GSM SMS Server MTM. See 3.2.7.3.4.2 for more information.
-3.2.8.3.4.3 Phone Store
-In the case of CDMA phones, phone store can be phone-based storage or R-UIM based storage. The CDMA SMS Server MTM accepts requests from clients to copy/move messages to and from the phone/R-UIM and delete messages from the phone/R-UIM. For example when copying to the R-UIM it packages up the SMS message and passes it to the CDMA SMS stack with a request to write it to the R-UIM.
-3.2.8.3.5 Configuration for using CDMA SMS MTM
-The CDMA messaging components currently only support single mode, but it is designed such that it can become multimode in the future. Currently, -Dcdma option is used to for selecting CDMA mode for using emulator and building ROM.
-
-
-3.2.9 Messaging / Email APIs
-3.2.9.1 Key Internal Relationships and Dependencies
-
-Figure 19 Email Internal Dependencies
-
-3.2.9.2 Key External Relationships and Dependencies
-
-Figure 20 Email External Dependencies
-3.2.9.3 API Purpose - Further Elaboration
-3.2.9.3.1 Email Overview
-The Email plug-ins consist of a set of utilities and MTMs for POP3, IMAP4 and SMTP. For each email account a pair of services entries is created in the message store. For a POP3 account there will be an SMTP service and a POP3 service, for an IMAP4 account there will be an SMTP service and as IMAP4 service. These entries are used to store the settings for the email transport. Each of the service entries has its related ID set to the other member of the pair. The SMTP service is created invisible so the user only sees the POP3 or IMAP4 service entry, copying a message to the SMTP service will cause the SMTP Server MTM to attempt to send the message. The POP3 and IMAP4 MTMs provide functionality to synchronise with a remote email server this is achieved by extending the Client MTM interface via the InvokeAsync API. Synchronisation of a POP3 or IMAP4 account will result in copying headers and optionally body text and attachments from the email server and creating message entries under the POP3 or IMAP4 service entry.
-Email messages are represented in a common format whether they are being sent via SMTP or downloaded via POP3 or IMAP4. The email client utilities provide the classes for creating and manipulating the entry structure used to store emails. The email server side utilities provide classes to convert between the entry structure used to store emails in the message store and RFC2822 email messages sent to SMTP servers and retrieved from POP3 servers. IMAP4 email messages are parsed by the email server and the IMAP4 Server MTM requests and stores the individual parts of the messages.
-3.2.9.3.2 Email Client Utilities
-The email client utilities are part of the imcm DLL and provide classes for:
-• Storage of email messages including mime headers, RFC2822 headers, attachments, body text and encoding information in the message store
-• Manipulating email messages, for example adding attachments, replying etc.
-• To wrap up the character converters used to convert between standard character sets and Unicode. These make use of the charconv component that is part of the system libraries subsystem.
-• Storage of Email settings in the message store.
-• Progress information for email operations.
-The utilities are used directly by clients to access parts of email messages for display. CImEmailMessage provides the functionality used by clients displaying email messages, including listing attachments, getting body text and resolving URIs in M-HTML messages.
-The Email Client MTMs use the utilities when they are asked to create, reply to and forward messages CImEmailOperation provides the functionality to perform these operations. Each email message is represented by a parent message entry and then entries to represent mime folders and mime parts, see Figure 7 for an example, so adding or deleting mime parts involves walking the tree of entries and inserting / removing entries as appropriate.
-3.2.9.3.3 Email Server MTM Utilities
-The Email Server MTM Utilities are responsible for generating and parsing of RFC2822 format email messages and providing an API to wrap up a TCP/IP connection to a remote email server.
-• Parsing of RFC2822 Email Messages – The utilities provide an API that accepts the text of an RFC2822 email message a line at a time and stores the email message in messaging’s internal format for email messages. See the Email Client Utilities for details of this format. The API handles storing of RFC2822 headers, MIME headers, decoding of Base64 encoded or uuencoded attachments and decoding of text received in character sets supported by the charconv component. This API is only accessible to Server MTMs, as it requires classes that can only be instantiated while running within the message server process. See the Messaging Functional Specification [R1] for detail on which email specifications the utilities support.
-• Generation of RFC2822 Email Messages – The utilities provide an API to convert an email in messaging’s internal format into an RFC2822 email message. The API provides access to the RFC2822 text a line at a time for streaming to an SMTP server. The exact format of the email depends on the settings passed in; the API can generate plain RFC2822 email messages with uuencoded attachments, MIME email messages with Base64 encoded attachments, or M-HTML email messages with Base64 encoded attachments. See the Messaging Functional Specification [R1] for detail on which email specifications the utilities support.
-• TCP/IP socket wrapper – The utilities provide a class that abstracts a TCP/IP socket supplied by the networking subsystem into an API that supports sending and receiving lines of text to / from a remote server. This API is used to connect to remote email servers by each of the email Server MTMs. The API can either create insecure or secure sockets enabling the SSL encryption provided by the networking subsystem. It also supports changing an insecure socket into a secure socket, this enables the email Server MTMs to implement email protocols where the initial connection to the server is insecure and then a secure socket is negotiated before sending or requesting any sensitive information.
-3.2.9.3.4 POP3 MTMs
-The POP3 MTMs implements the functionality to synchronise the local message store with a remote POP3 email server.
-3.2.9.3.4.1 Client MTM
-The POP3 Client MTM implements the standard Client MTM APIs and other extensions:
-• Reply to, forward – These are accessible via the ReplyL and ForwardL APIs of a Client MTM and are implemented as calls to the email utilities class CImEmailOperation.
-• Reply to, forward, create new messages, create receipts and forward as attachment – These are accessible as commands available via the InvokeAsyncFunction API of the Client MTM, they are implemented as calls to CImEmailOperation.
-• Connecting, disconnecting and copying email while connected – These operations are accessible as commands available via the InvokeAsyncFunction API of the Client MTM, they are implemented as calls to the POP3 Server MTM.
-• Querying connection status – This command lets clients know whether the POP3 Server MTM is connected to an email server, and is available via the InvokeAsyncFunction API of the Client MTM. The Client MTM requests the information from the Server MTM.
-• Compound operations – The Client MTM provides functionality to wrap up connecting to email servers, copying / moving new messages or a selection of messages, and then optionally disconnecting. These commands are available via the InvokeAsyncFunction API of the Client MTM. The Client MTM implements this by using the CImPOP3GetMail class which requests the correct sequence of operations from the Server MTM, waiting for each operation to complete before requesting the next one.
-• Send on next connection If the Client MTM gets a request to connect to an email server it will check whether the POP3 settings. If send on next connection is requested it will launch the autosend.exe executable (see section 3.2.7.3.7) to handle sending messages waiting in the outbox.
-• Offline operations – The POP3 Client MTM has a command to cancel offline operations, this is available via the InvokeAsyncFunction API of the Client MTM. The Client MTM passes the request to the Server MTM.
-3.2.9.3.4.2 Server MTM
-The POP3 Server MTM handles the communication with the remote POP3 server and implementation of the POP3 protocol. The MTM uses CImTextServerSession to handle the communication with the email server and CImRecvConvert to parse the email messages downloaded, both are provided by the Email Server MTM Utilities.
-• Connect – The POP3 Server MTM will open a socket to the email server using CImTextServerSession and login user the username / password in the POP3 settings. After a successful connection the Server MTM will attempt to synchronise the current state of headers stored on the email server with the set stored in the message store and then start any pending offline operations. After the connect operation has completed the Server MTM will inform the message server that it is expecting more operations via the CommandExpected API and therefore the message server will not delete and unload the Server MTM.
-• Populate Message – The POP3 Server MTM treats requests to copy a message from and to the POP3 service as a request to download the full message.
-• Offline operations – When the POP3 Server MTM receives a request to copy, move, or delete and is not connected to a POP3 email server the Server MTM will store the operation in the CMsvStore of the entry being modified and perform the operation on the next connection to the email server.
-• Disconnect – When disconnecting from a remote email server the POP3 MTM will run any pending offline operations stored. After the disconnect operation completes the Server MTM will allow the message server to delete and unload the Server MTM by setting the CommandExpected API to false.
-3.2.9.3.5 IMAP4 MTMs
-The IMAP4 Server MTM implements the functionality to synchronise the local message store with a remote IMAP4 email server.
-3.2.9.3.5.1 Client MTM
-The IMAP4 Client MTM implements the standard Client MTM APIs and other extensions:
-• Connecting, disconnecting, synchronising, un/subscribing folders – These operations are accessible as commands available via the InvokeAsyncFunction API of the Client MTM, they are implemented as calls to the IMAP4 Server MTM.
-• Send on next connection – If the Client MTM gets a request to connect to an email server it will check whether the IMAP4 settings. If send on next connection is requested it will launch the autosend.exe executable (see section 3.2.7.3.7) to handle sending messages waiting in the outbox.
-• Reply to, and forward messages – These are accessible via the ReplyL and ForwardL APIs of a Client MTM and are implemented as calls to the email utilities class CImEmailOperation.
-• Reply to, forward, create new, create receipt, forward as attachment – These are accessible as commands available via the InvokeAsyncFunction API of the Client MTM, they are implemented as calls to CImEmailOperation.
-• Querying connection status – These commands let clients know whether the IMAP4 Server MTM is connected to an email server and whether it is currently processing a request. They are available via the InvokeAsyncFunction API of the Client MTM. The Client MTM requests the information from the Server MTM.
-• Compound Connection and synchronisation – The IMAP4 Client MTM provides a compound operation that connects and synchronises with an IMAP4 server. This operation is implemented as a client side object that combines requests to the IMAP4 Server MTM. The client side operation can complete the client request either after the connection, after the connection + sync or after the connection + sync + disconnect. The client will keep requesting that the inbox be resynchronised at a configurable interval so new messages received in the inbox on the server will appear under the IMAP4 inbox. The CImapConnectAndSyncOp class handles these compound operations.
-• Compound Connect and copy / move / populate messages – The IMAP4 Client MTM provides a compound operation that connects to an IMAP4 server and copies moves or populates messages. The implementation is provided by the CImImap4GetMail class which makes calls back into the IMAP4 Client MTM.
-• Offline operations – The IMAP4 Client MTM has a command to cancel offline operations, this is available via the InvokeAsyncFunction API of the Client MTM. The Client MTM passes the request to the Server MTM.
-3.2.9.3.5.2 Server MTM
-The IMAP4 Server MTM handles the communication with the remote IMAP4 server and implementation of the IMAP4 protocol. The MTM uses CImTextServerSession to handle the communication with the email server. The IMAP4 Server MTM opens two connections to the IMAP4 server this enables users to download messages while the Server MTM is performing a background synchronisation if requested by the Client MTM.
-• Connect – The IMAP4 Server MTM will open a socket to the email server using CImTextServerSession and login using the username / password in the IMAP4 settings. After a successful connection the Server MTM will optionally attempt to synchronise the current state of headers stored on the email server with the set stored in the message store and then start any pending offline operations. After the connect operation has completed the Server MTM will inform the message server that it is expecting more operations via the CommandExpected API and therefore the message server will not delete and unload the Server MTM.
-• Copy, Move messages – The IMAP4 Server MTM supports copying and moving messages between folders on the IMAP4 server and between the IMAP4 server and local folders.
-• Delete messages – The IMAP4 Server MTM will mark the email as deleted on the server; however it will not be deleted until the IMAP4 Server MTM disconnects from the server.
-• Folders – The IMAP4 Server MTM will allow folders to be subscribed, unsubscribed, renamed, copied, moved, and created within the IMAP4 service. Subscribing to a folder means that it will be visible to the user and synchronised with the remote server. The inbox is always subscribed.
-• Offline operations – When the IMAP4 Server MTM receives a request to copy, move, or delete and is not connected to an IMAP4 email server the Server MTM will store the operation in the CMsvStore of the entry being modified and perform the operation on the next connection to the email server.
-• Disconnect – When disconnecting from a remote email server the IMAP4 MTM will run any pending offline operations stored. After the disconnect operation completes the Server MTM will allow the message server to delete and unload the Server MTM by setting the CommandExpected API to false.
-
-3.2.9.3.6 SMTP MTMs
-The SMTP MTMs provide functionality to send email messages. They are made up of the Client MTM that is part of the imcm DLL and the Server MTM.
-3.2.9.3.6.1 Client MTM
-The SMTP Client MTM implements the standard Client MTM APIs including the functions required to allow clients of Send As to create email messages.
-3.2.9.3.6.2 Server MTM
-The SMTP MTMs provide functionality to send email messages; it interprets requests to copy entries to an SMTP service as a request to send those messages. In addition it responds to two extended commands via the StartCommand Server MTM interface. These commands are KSMTPMTMIsConnected that responds with whether the Server MTM is currently connected to a remote SMTP server and KSMTPMTMSendOnNextConnection which performs the same operation as copying a selection of messages to an SMTP service. The only difference between the copy operation and the KSMTPMTMSendOnNextConnection operation is that the latter can be called without a selection of messages.
-When the Server MTM receives a request to send messages it builds a selection of messages consisting of the messages passed into the operation and any messages waiting in the outbox to be sent. To determine which messages in the outbox are waiting to be sent the SMTP server checks for messages that have the same service ID as the destination of the send operation and have a sending state of KMsvSendStateWaiting, KMsvSendStateScheduled or KMsvSendStateResend. This means that any request to send messages may result in more messages being sent than explicitly listed in the selection passed to the send operation.
-The Server MTM restores its settings from the SMTP service it has been asked to copy the messages to. Then it connects to the SMTP server using the CImTextServerSession class in the Email Server MTM Utilities, passing in the SMTP server address and TCP/IP port number from the SMTP settings. Then for each message to be sent the Server MTM uses the Email Server MTM utilities to generate an RFC2822 format message to send to the SMTP server, the RFC2822 text is generated on the fly as the data is sent to the SMTP server. If the SMTP server accepts the message to be sent then the Server MTM moves the message to the sent folder and sets its sending state to sent. If the SMTP server rejects the message then the Server MTM leaves the message in the outbox and sets the sending state to failed. Separate emails are generated for BCC recipients to ensure that the SMTP server doesn’t incorrectly include BCC recipients in emails sent to addresses in the To and CC fields of the email.
-3.2.9.3.7 Autosend
-The Autosend component is an executable that is kicked off by the POP3 and IMAP4 Client MTMs if the send on next connection setting is set. This executable will just make a request to the SMTP Server MTM to send messages associated with the SMTP service related to the POP3 or IMAP4 service, wait for the operation to finish and then exit.
-3.2.10 Messaging / MMS APIs
-The MMS module has been removed from v9.0 and onwards.
-3.2.10.1 Key Internal Relationships and Dependencies
-
-Figure 21 MMS Internal Dependencies
-3.2.10.2 API Purpose - Further Elaboration
-3.2.10.2.1 MMS Overview
-The MMS MTM provides functionality for creating, accessing, sending and receiving MMS messages. Messages are sent and received without the client application needing to open or close any kind of session. The management of the MMS session is handled entirely within the MTM.
-MMS clients are alerted when a new message is available for download via the WAP Push mechanism. A WAP push watcher is provided to handle these notifications. After the notification the message can be downloaded over WSP or HTTP. Messages are sent by posting the data over WSP or HTTP. The Symbian MMS implementation can handle sending or receiving MMS message over either protocol.
-MMS messages are based on the MIME format but are binary encoded using WSP. Note that MMS messages are encoded in this way even if they are posted over HTTP as opposed to WSP. The codec component is responsible for this encoding and decoding.
-3.2.10.2.2 MMS Utilities
-3.2.10.2.2.1 Key External Relationships and Dependencies
-
-Figure 22 MMS Utilities External Dependencies
-The MMS utilities provide the message and settings encapsulation classes. The MMS settings and messages are stored in the message store, the MMS utilities provide the interfaces to access this data.
-3.2.10.2.2.2 Settings
-The settings functionality provided by the MMS utilities allows the messaging client to persist MMS settings in the message store. Supported settings include:
- MMSC (MMS server) address
- WSP or HTTP transport
- Autofetch messages on notification
- Preferred IAP for the MMS network connection
-The settings functionality is also used by the server MTM to retrieve the settings prior to message sending or fetching.
-3.2.10.2.2.3 Message Encapsulation
-The message classes provide the message access functionality. Messages can be created, stored, restored and read using these classes. Functionality includes:
- Adding media objects to the message
- Enumerating through media objects
- Adding recipients, subject line, etc. to a message
- Adding other headers to the message, e.g. expiry date
- Finding the appropriate media object for a given URI in the SMIL part (URI resolving)
-The message data is stored in the message store using one entry per message regardless of the number of media objects added to the message. This is preferable to using multiple message entries as it is faster and uses less disk space.
-Most of the message access code is common whether it is being used on the client or server side, however some parts of it are specific. For this reason it is essential that the appropriate client or server side CMmsMessage derived class is used.
-3.2.10.2.3 MMS Watcher
-3.2.10.2.3.1 Key External Relationships and Dependencies
-
-Figure 23 MMS Watcher External Dependencies
-
-The MMS watcher plug-in is responsible for intercepting incoming MMS notifications and delivery reports then taking the appropriate action. It is implemented as a WAP Push watcher plug-in.
-When an MMS notification is received an MMS entry is created in the inbox using the MMS utilities. At this point the entry has its incomplete flag set. If the settings have the autofetch option selected then the MMS watcher initiates the fetch operation via the MMS client MTM.
-If a delivery report is received then the delivered flag is set on the appropriate sent message. If an outgoing message was sent to several recipients then there will be several delivered flags. A delivery report from each recipient will set the appropriate delivered flag.
-3.2.10.2.4 MMS Client MTM
-3.2.10.2.4.1 Key External Relationships and Dependencies
-
-Figure 24 MMS Client MTM Dependencies
-As with most other MTMs the MMS client MTM provides access to the server MTM functionality for messaging clients. It also implements the Send-As interface and reply and forward functionality.
-3.2.10.2.4.2 Send-As Implementation
-The Client MTM Send-As interface is implemented in the MMS Client MTM. The implementation differs slightly from other MTMs because additional presentation content may be generated depending on the media objects that are added. When simple combinations of images, sounds and text are added a SMIL presentation is generated to link them together. This is preferable to simple adding the objects as attachments where some clients render them as a list of files and others fail to render them at all.
-The SMIL data is constructed using templates stored in resource files, the GMXML (SMIL) composer is not used.
-3.2.10.2.4.3 Reply / Forward
-The Client MTM can be used to create replies to received messages or to create forwarded responses. The reply and forwarding operations are performed asynchronously.
-3.2.10.2.5 MMS Server MTM
-3.2.10.2.5.1 Key External Relationships and Dependencies
-
-Figure 25 MMS Server MTM Dependencies
-The Server MTM is the most complicated part the MMS implementation. It handles all of the state information required to send or fetch MMS messages. It is also responsible for managing the HTTP or WSP session and the connections to the phone network.
-3.2.10.2.5.2 Operations
-All MMS server MTM functionality is encapsulated in operations. An operation consists of the setup of a session, the sending, fetching and acknowledgements when appropriate, it then closes the session. The messaging client initiates an operation with a single call to the Client MTM, there is no need for the messaging client to explicitly establish the session or to know about the internal states. However, these internal states are available to the messaging client via the progress structure if this level of user feedback is required.
-Two types of operation are supported, background and foreground:
-A maximum of one foreground operation can be running at any one time. The messaging client can poll the server MTM for the progress of a running foreground operation, likewise it can cancel it if necessary.
-A background operation does not support progress information and can not be cancelled by the messaging client. It is possible to initiate background operations even if other background or foreground operations are pending. However, background operations are queued and a maximum of one will actually be running at any one time.
-The MMS watcher uses a background operation to perform automatic fetching. While the background autofetch is occurring it is still possible to start a foreground operation (such as sending a message) if required.
-3.2.10.2.5.3 Session and Connection Management
-The server MTM uses the HTTP Transport Framework to enable the HTTP or WSP session. HTTP or WSP can be selected at runtime by selecting the appropriate option in the settings. The server MTM is responsible for reading any HTTP proxy details from the CommDB and passing it to the HTTP framework. See the http transport framework architectural description for more information on recognisers [R5]
-The server MTM is also responsible for managing the connection to the phone network. Connections are opened when required using the RConnection mechanism, multi-homing is supported provided that the underlying HTTP framework transport plug-in also supports it.
-3.2.10.2.6 MMS Codec
-The MMS Server MTM is in charge of the state transitions, connection, session, the actual posting and fetching of the data from them, however it does not encode or decode the MMS PDUs. The encoding and decoding is performed by the MMS Codec.
-For decoding the Server MTM passes the Codec the MMS PDU data in a descriptor for processing. If the PDU contains a received MMS message then the message entry is updated with the decoded MMS data.
-For encoding the Server MTM passes a reference to the message store entry containing the un-encoded MMS data. The Codec then encodes it and returns the PDU to the Server MTM in a descriptor.
-
-
-3.2.11 Messaging / BIO APIs
-3.2.11.1 Key Internal Relationships and Dependencies
-
-Figure 26 BIO Message Internal Dependencies
-3.2.11.1.1.1 Key External Relationships and Dependencies
-
-Figure 27 Bio Parser External Dependencies
-
-3.2.11.2 API Purpose - Further Elaboration
-3.2.11.2.1 BIO Overview
-The BIO messaging components have been designed to unify and simplify the way in which system messages are processed. In this context ‘system messages’ refers to messages received on the device which are intended to update some attribute(s) on the system as opposed to being presented to the user. Examples of these types of messages include vCards which are parsed and then displayed to the user and when accepted modify the users contact database and OTA configuration messages which are again parsed before display to the user and if accepted create email accounts or internet access points.
-The BIO messaging components can be broken down into three groups:
-1) The BIO MTM - To initiate the parsing and processing of BIO messages
-2) The BIO Database - Maps port numbers, MIME types, etc. to bio types in order to identify the type of incoming BIO messages.
-3) The BIO Parsers - To parse and process the BIO message payload
-BIO messages are not receive by the bio messaging framework, they come over other message transports for example see section 3.2.6.3.1 on the SMS watchers which describes how the SMS watchers receive bio messages and use the bio framework to tag the messages with the correct bio id.
-3.2.11.2.2 BIO MTM
-The BIO client MTM is called by the messaging client to parse or process a BIO message that has been saved in the message store. It is the responsibility of a BIO watcher to save the BIO message with the BIO flag and the appropriate BIO type set.
-The BIO client MTM does very little, its primary task is to pass on the messaging client request to the server MTM. Two operations are supported, parse and process.
-The messaging client is expected to initiate the parsing of the BIO message before processing it. The parsing step involves analysing the data and storing it in a form that can be displayed to the user via the BIO message viewer.
-Once the message has been parsed the messaging client can initiate the processing of the message.
-The BIO server MTM is responsible for deferring the parsing and processing to the appropriate BIO parser. The behaviour for the parsing and processing steps varies between parsers. See the BIO Parsers section for more information.
-The bio MTM does not support sending messages and therefore does not support reply / forwarding messages. For bio messages sending / reply etc. is supported by the particular MTM that the message is sent over, for example SMS.
-3.2.11.2.3 BIO Database
-The BIO database is used to identify the type of BIO messages. It maps message attributes such as port number, MIME type or leading string to a BIO type. These are attributes are then used by clients of the bio framework to know what ports to listen for messages on. For example the SMS watchers use the leading string to wait for SMS messages that start with that string and when storing those messages in the inbox tag them with the bio id associated with that leading string. See the SMS watcher section 3.2.6.3.1 for more examples of how the BIO database can be used.
-3.2.11.2.4 BIO Parsers
-The BIO parsers are plug-ins for parsing and processing incoming BIO messages. They are invoked by the BIO Server MTM depending on the BIO type of the message being processed. Each BIO parser implements two functions, ParseL and ProcessL. The level of functionality varies between parsers. Some parsers update the final repository with the received data, e.g. WAPP updates the CommDB with the received settings. Some parsers simply save the data in an unparsed state for processing by another component, this secondary parsing is not part of the BIO framework and must be initiated by the messaging client. An example is when GFP saves vCard data as a file as opposed to updating the contacts database, the UI must then invoke the Versit parser to parse the vCard and commit it to the contacts database.
-3.2.11.2.4.1 Generic File Parser (GFP)
-The generic file parser can be used to identify and save a variety of BIO data types, e.g. vCards and vCals. The Generic File Parser does not process the data, it simply saves it in the message store for processing by another component. The file is saved as an attachment of the message entry that was parsed.
-3.2.11.2.4.2 Nokia/Ericsson OTA Parser (WAPP)
-The WAPP parser decodes Nokia/Ericsson OTA messages and updates CommDB to reflect the received settings.
-3.2.11.2.4.3 Nokia Smart Message Internet Access Parser (IACP)
-The IACP parser decodes Nokia Smart Messages and updates the CommDB and messaging settings where appropriate.
-3.2.11.2.5 BIF Files and Utilities
-The BIF files encapsulate the information required for identifying BIO messages, these details may include the expected port number, MIME type or leading string. Different BIO watcher will use different information from these files, for an example see the 3.2.6.3.1. The information can be retrieved from the BIF files by using the BIF utilities. Generally BIO aware clients will access this information via the BIO database. BIF files are resource files previous to the v6.1 release they were binary files generated by biftool.exe.
-3.2.11.2.6 Platform Security Compliant Messaging / BIO APIs
-In the platform security model the BIO parsers are run in the client space rather than in the message server space, as is done in the non-platform secure model. If the BIO parsers are run in the message server space, it allows a client process to gain the capabilities of the message server. IPC policing can protect the message server from this.
-Also, for the message server to be able to load any BIO parser it would need more capabilities than it really requires. By running the BIO parsers in the client space, both these issues are solved. The client process must be trusted with the necessary capabilities to run the specified BIO parser.
-The BIO registry files are located in the \resource\messaging\bif read-only directory. All BIO parser DLLs are located in the \sys\bin protected directory.
-
-Figure 26 BIO Message Dependencies (v9.0)
-The BIO client MTM is responsible for loading the BIO database and BIO utilities to handle parse/process requests from clients.
-The BIO registry files no longer identify the BIO parsers DLLs via their UID – the registry file must use the BIO parser DLL name to identify them.
-3.2.12 Messaging / OBEX MTM APIs
-3.2.12.1 Key Internal Relationships and Dependencies
-
-Figure 28 OBEX Internal Dependencies
-3.2.12.2 OBEX MTM Overview
-The OBEX MTM offers simple IR and Bluetooth beaming functionality. It provides an API that is consistent with other MTMs so that the underlying OBEX APIs do not need to be used directly for beaming applications. The OBEX MTM does not provide OBEX receiving functionality, in order to receive OBEX data the underlying OBEX APIs must be used directly.
-3.2.12.2.1 OBEX MTM
-The OBEX MTM is split into three parts. OBEX MTM DLLs, IR MTM DLLs and Bluetooth MTM DLLs. The OBEX MTM DLLs can not be used on their own they provide the base OBEX MTM functionality for the derived IR and Bluetooth MTMs.
-There are two APIs that can be used to create OBEX messages:
-1) The Send-As API
-2) Linked attachments by filename
-The Send-As API provides an interface consistent with other MTMs, however it requires all attachments to be copied into the message store before they can be sent, this is often undesirable for beaming applications because it is wastes disk space. For this reason a second API is provided that allows attachments to be linked to outgoing messages by filename, when this API is used there is no need to copy the attachments to the message store.
-Unlike many other MTMs after OBEX tries to send a message it is deleted from the outbox whether the sending succeeds or fails.
-3.2.12.2.1.1 OBEX MTM Key External Dependencies
-
-Figure 29 OBEX External Dependencies
-3.2.12.2.2 IR MTM
-The bulk of the OBEX MTM functionality is provided by the OBEX MTM DLLs, the IR MTM itself just sets up the parameters.
-3.2.12.2.2.1 IR MTM Key External Dependencies
-
-Figure 30 IR MTM Dependencies
-3.2.12.2.3 Bluetooth MTM
-The bulk of the OBEX MTM functionality is provided by the OBEX MTM DLLs, the Bluetooth MTM just subclasses from the OBEX MTM and sets up Bluetooth specific parameters.
-3.2.12.2.3.1 Bluetooth MTM Key External Dependencies
-
-Figure 31 Bluetooth MTM Dependencies
-3.2.12.2.4 OBEX MTM Utils
-The OBEX MTM Utils provide utility functionality used by the other OBEX MTM DLLs. The two main areas of functionality provided by this component are:
-1) Filename linking functionality
-2) Bluetooth SDP lookup
-The filename linking functionality is provided in the utilities because linked files must be added by the client side during message creation and need to be read on the server side during sending.
-
-3.2.12.2.5 Platform Security Compliant Messaging / OBEX MTM APIs
-From v9.0 and onwards the service settings of all the derived OBEX MTMs are stored in the Central Repository. The OBEX message is stored in the message store as an attachment – from v9.0 and onwards the Attachment API is used to attach the OBEX message.
-
-3.2.13 Messaging / GMXML APIs
-3.2.13.1 Key Relationships and Dependencies
-
-Figure 32 GMXML Dependencies
-3.2.13.2 Overview
-The GMXML component provides simple XML DOM parsing and validation functionality. It is intended for parsing XML that might be needed in messaging applications, specifically SMIL parsing for MMS rendering. It is not a general purpose XML parser and will not be suitable for some applications, e.g. browsing.
-3.2.13.2.1 GMXML DOM
-The DOM implementation is fit for purpose for SMIL rendering but differs from the standard DOM design in several respects, e.g. attributes are not stored as discrete nodes, for performance reasons they are stored with the element.
-The DOM tree classes are all derived from nodes. Implemented node types include elements, text and comments. The type of each element is stored as a descriptor as opposed to an enum. This is less efficient than storing it as an enum but provides maximum flexibility when dealing with unknown element types.
-Nodes are linked together in a tree structure as might be expected in a DOM implementation. The tree structure exists on the heap.
-3.2.13.2.2 GMXML Parser and Composer
-3.2.13.2.2.1 Parser
-The parser takes XML input from a buffer or file and creates the corresponding DOM structure on the heap.
-The parser is capable of performing some basic validation. In order to validate against a DTD a class that implements the GMXML DTD interface is required. The DTD interface specifies several functions that provide the required validation, e.g. one of the functions determines if a given attribute is valid for a given element. An instance of the DTD class should be passed into the parser when validation is required but can be omitted if no validation is needed.
-3.2.13.2.2.2 Composer
-The composer takes a DOM tree and generates XML output from it. The XML output is written to a file.
-3.2.13.2.3 GMXML SMIL DTD (Validator)
-The SMIL DTD validator class is an implementation of the DTD validator interface. It implements several simple functions that provide the information required to validate SMIL data. An instance of the SMIL DTD validator should be passed into the parser if SMIL validation is required.
-4 Security
-4.1 Data caging
-For data storage in the pre-platform security compliant architecture, refer to section [3.2.1.3.2]
-For the data caging in the platform security compliant architecture of v9.0 and onwards, refer to section [3.2.1.3.3]
-4.2 Backup and restore
-The message server registers the index file with the backup server. When informed about a backup/restore it releases the index file, sending events to messaging clients informing them that the message store is unavailable. When informed it can open the index file again, it checks the time stamp on the index file; if it has changed since the file was released it reloads the index file. If the newly restored index file is found to be corrupt it is deleted and a new message store is created. See the section on page 14 for details on how the message server handles corrupt stores. The client performing the restore should always wipe the existing message store before starting to copy the message store from the backup to the device.
-4.3 Capability ranges
-In the platform security compliant architecture of v9.0 and onwards, the capabilities allocated to messaging sub-systems are as listed in following table.
-4.3.1 Capabilities granted to executables
-The following table lists the executables and their capabilities and also gives a basic example for having the required capability.
-
-Executable Capability Rationale (basic example of capability requirement)
-msexe.exe ProtServ ProtServ is required to allow the msexe.exe to start a protected server. This stops processes without ProtServ from starting a server pretending to be the message server
- ReadDeviceData ReadDeviceData is needed to able to read service settings
- WriteDeviceData WriteDeviceData is needed to able to write service settings
- NetworkServices NetworkServices capability is needed to access network transports (SMS, POP3, SMTP, IMAP4).
- LocalServices LocalServices is needed to be able to access IR and Bluetooth
- ReadUserData ReadUserData is needed to be able to read user data (e.g. service settings).
-watcher.exe ReadDeviceData ReadDeviceData is needed to able to read service settings
- WriteDeviceData WriteDeviceData is needed to able to write service settings
- NetworkServices NetworkServices capability is needed to access network transports (SMS).
- LocalServices LocalServices capability is needed for the plug-ins to access IR and Bluetooth
- ReadUserData ReadUserData is needed to be able to read user data
- WriteUserData WriteUserData is needed to be able to write user data
-autosend.exe ReadUserData ReadUserData capability is needed to be able to read data from Outbox and SMTP server MTM.
- WriteUserData WriteUserData capability is needed to be able to write data in Outbox and SMTP server MTM.
- NetworkServices NetworkServices capability is needed to access network transports (SMS, POP3, SMTP, and IMAP4).
- LocalServices LocalServices capability is needed to access the IR and Bluetooth
-SchSend.exe ReadDeviceData ReadDeviceData is needed to able to read settings data
- NetworkServices NetworkServices capability is needed to access the network transports (SMS, POP3, SMTP, and IMAP4).
- LocalServices LocalServices is needed to be trusted by other MTM
- ReadUserData ReadUserData is needed to be able to read user data.
- WriteUserData WriteUserData is needed to be able to write user data.
-SendAs.exe ReadDeviceData ReadUserData is needed to be able to read data in Outbox.
- WriteDeviceData WriteUserData is needed to be able to write data in Outbox.
- NetworkServices NetworkServices capability is needed to access the network transports (SMS, POP3, SMTP, and IMAP4).
- LocalServices LocalServices is needed to be able to access IR and Bluetooth
-
-4.3.2 Capabilities granted to DLLs
-The assigned Platform Security attributes for DLLs within messaging are outlined in the following table.
-DLL Capability
-bifu.dll All –TCB
-bioc.dll All –TCB
-biodb.dll All –TCB
-bios.dll All –TCB
-biowatcher.dll same as watcher.exe
-biut.dll All –TCB
-cbcp.dll All –TCB
-enp.dll All –TCB
-gfp.dll All –TCB
-iacp.dll All –TCB
-nbswatcher.dll same as watcher.exe
-cdmanbswatcher.dll same as watcher.exe
-CdmaSocketWatcher.dll same as watcher.exe
-VMNWatcher.dll same as watcher.exe
-WEMTWatcher.dll same as watcher.exe
-WMTWatcher.dll same as watcher.exe
-WPTWatcher.dll same as watcher.exe
-wapp.dll All –TCB
-wapwatcher.dll same as watcher.exe
-smildtd.dll All –TCB
-xmldom.dll All –TCB
-xmlparser.dll All –TCB
-smiltranslator.dll All –TCB
-imcm.dll All –TCB
-imps.dll same as msexe.exe
-imut.dll All –TCB
-msgs.dll All –TCB
-msgurlrec.mdl same as AppArc.exe (once it exists; eiksrv in meantime)
-mtur.dll All –TCB
-pops.dll same as msexe.exe
-schsend.dll All –TCB
-send.dll All –TCB
-smcm.dll All –TCB
-smcm_gsm.dll Synonym for smcm.dll
-smcm_cdma.dll Synonym for smcm.dll
-smss.dll same as msexe.exe
-smss_gsm.dll Synonym for smss.dll
-smss_cdma.dll Synonym for smss.dll
-smts.dll same as msexe.exe
-btcmtm.dll All –TCB
-btsmtm.dll same as msexe.exe
-irc.dll All –TCB
-irs.dll same as msexe.exe
-obexclientmtm.dll All –TCB
-obexmtmutil.dll All –TCB
-obexservermtm.dll same as msexe.exe
-
-The reason for setting a high capability to the DLLs is to make it possible for almost anyone to link to them. Although a DLL may have capabilities ALL-TCB (All minus TCB), its real capability is limited by the process which loads the DLL.
-4.3.3 Capabilities required to use the subsystem
-The message subsystem needs to be protected against malicious clients. The following table shows the key capabilities required to do related activities in different components.
-
-Component Related Activity Required Capability and SID
-Message server Create message in local folder No capability required
- Create message in Outbox ReadUserData, WriteUserData and MTM specific capabilities
- Access client MTM ReadUserData, WriteUserData and MTM specific capabilities
-Watcher Allow plug-ins to wait on events (e.g. arrival of SMS) Watcher always polices if the client capabilities are trusted by the watcher framework, else it will not be loaded
-Plug-ins or clients using watcher need the same capabilities as watcher.exe to be able to be loaded by watcher.
-Autosend Send messages in background NetworkService or LocalService required by the message type
-SchSend Scheduling of operations (e.g. sending SMS) SchSend always polices to see if the process was started by the Task Scheduler – if not the process terminates without performing any of the scheduled tasks. Also, the SchSend verifies that only itself and the message server created the scheduled tasks. If this is not the case, SchSend does not performing the scheduled tasks.
-SendAs Create message Draft, move it to Outbox, and send message WriteDeviceData or WriteUserData and other capability required by the message type
-
-5 Further Information
-5.1 References
-No. Document Reference Version Description
-R1 messaging_functional_specification.doc 0.6 Messaging Functional description
-R2 SGL.GT0143.161_App-Framework_Architectural_Description.doc 1.0 App-Framework Architectural Description
-R3 NBProtocols_Subsystem_Architectural_Description.doc 0.2 NBProtocols Architectural Description
-R4 WAP-stack_architectural_analysis.doc 1.0 WAP stack architectural analysis
-R5 HTTP Transport Framework Architectural Description.doc 1.1 HTTP Transport Framework 1.1 Architectural Description
-5.2 Open Issues
-The following issues need to be resolved before this document is completed:
-1. Top-level architecture diagram showing the framework and plug-ins should be added to overview section.
-2. Message store section should talk about removable media.
-3. Define "Message Server Client API" and "Messaging Client API" in the glossary, and ensure it is consistently used in the diagrams
-4. Add a sequence diagram for receiving a vCard over SMS and integrating it into contacts
-5. Add a sequence diagram for sending an SMS
-6. Add a sequence diagram for synchronising a POP3 mail box
-7. Add a sequence diagram for connecting to an IMAP4 mail box and downloading a message
-8. Capability table should be updated after the implementation of server e.g. message server
-9. Sequence diagram may need to be changed to show secured platform operation
-10. In section [3.1.1.4] the server SendAsV2 to find a correct name
-11. Section 3.2.1.3.3.1 Data Caging file 'Mtm Registry v2'may need a correct name
-12. Breakdown diagram showing all DLL, exes, apps in the messaging subsystem for both the pre-v8.0 and post v9.0 in section[3.2]
-13. Needs to say more about how the capabilities are policed and the algorithms used for different operations
-14. The dependecy between the message server and the central repository need to be listed in the email, SMS and OBEX diagrams (e.g. message store)
-15. Section 3.2.1.2 - figure 3 - Central Repository also get used by the Message server, or server MTMs (e.g. POP3), to retrieve account settings the path, required DLL and description are not given
-16. Section 4.3.3 title can be Police requirement of the sub-system, add extra column for SID in the table and list the use of SID. For example SchSend checks for Task Scheduler SID
-
-
-5.3 Glossary
-The following technical terms and abbreviations are used within this document.
-Term Definition
-BIO
-Bearer Independent Object Smart messages e.g. vCards, vCals, and WAP provisioning messages. These can currently be received via the WAP stack, SMS stack, Bluetooth or Infrared.
-BIO Type UID that represents the content type of a BIO Message.
-Message Centre Application that displays list views of messages to the user, allowing the user to perform operations such as copying messages, sending messages creating new messages etc.
-Message Viewer Application for viewing a message.
-Message Editor Application for creating or editing a message
-Message Server Symbian OS Server that handles request to modify the Message Store
-Message Store Store of messages and related information kept in the file system on a Symbian OS device.
-Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
-Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
-Global Inbox A standard folder under the local service which is used to store incoming messages like SMS MMS etc. as opposed to an IMAP4 Inbox which would be under an IMAP4 service and is a representation of the Inbox on an IMAP4 email server.
-Central Repository centralised and secure storage facility for application settings
-OBEX Object exchange protocol, used to send objects such as vCards or files between devices via infrared or Bluetooth.
-GMXML XML parser / generator for use with SMIL formatted messages.
-UID Unique Identifier, a 32 bit number allocated from a registry owned by Symbian
-IPC Inter Process Communication
-MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
+MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
MTM Registry A list of currently installed MTMs maintained by the message server.
TLS Transport Layer Security, provides encryption of a TCP/IP socket.
M-HTML Standard for including HTML in MIME email messages see http://www.ietf.org/rfc/rfc2557.txt
@@ -28441,15 +20297,15 @@
Message Editor Application for creating or editing a message
Message Server Symbian OS Server that handles request to modify the Message Store
Message Store Store of messages and related information kept in the file system on a Symbian OS device.
-Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
-Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
+Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
+Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
Global Inbox A standard folder under the local service which is used to store incoming messages like SMS MMS etc. as opposed to an IMAP4 Inbox which would be under an IMAP4 service and is a representation of the Inbox on an IMAP4 email server.
Central Repository centralised and secure storage facility for application settings
OBEX Object exchange protocol, used to send objects such as vCards or files between devices via infrared or Bluetooth.
GMXML XML parser / generator for use with SMIL formatted messages.
UID Unique Identifier, a 32 bit number allocated from a registry owned by Symbian
IPC Inter Process Communication
-MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
+MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
MTM Registry A list of currently installed MTMs maintained by the message server.
TLS Transport Layer Security, provides encryption of a TCP/IP socket.
M-HTML Standard for including HTML in MIME email messages see http://www.ietf.org/rfc/rfc2557.txt
@@ -29459,15 +21315,15 @@
Message Editor Application for creating or editing a message
Message Server Symbian OS Server that handles request to modify the Message Store
Message Store Store of messages and related information kept in the file system on a Symbian OS device.
-Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
-Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
+Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
+Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
Global Inbox A standard folder under the local service which is used to store incoming messages like SMS MMS etc. as opposed to an IMAP4 Inbox which would be under an IMAP4 service and is a representation of the Inbox on an IMAP4 email server.
Central Repository centralised and secure storage facility for application settings
OBEX Object exchange protocol, used to send objects such as vCards or files between devices via infrared or Bluetooth.
GMXML XML parser / generator for use with SMIL formatted messages.
UID Unique Identifier, a 32 bit number allocated from a registry owned by Symbian
IPC Inter Process Communication
-MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
+MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
MTM Registry A list of currently installed MTMs maintained by the message server.
TLS Transport Layer Security, provides encryption of a TCP/IP socket.
M-HTML Standard for including HTML in MIME email messages see http://www.ietf.org/rfc/rfc2557.txt
@@ -30477,15 +22333,15 @@
Message Editor Application for creating or editing a message
Message Server Symbian OS Server that handles request to modify the Message Store
Message Store Store of messages and related information kept in the file system on a Symbian OS device.
-Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
-Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
+Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
+Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
Global Inbox A standard folder under the local service which is used to store incoming messages like SMS MMS etc. as opposed to an IMAP4 Inbox which would be under an IMAP4 service and is a representation of the Inbox on an IMAP4 email server.
Central Repository centralised and secure storage facility for application settings
OBEX Object exchange protocol, used to send objects such as vCards or files between devices via infrared or Bluetooth.
GMXML XML parser / generator for use with SMIL formatted messages.
UID Unique Identifier, a 32 bit number allocated from a registry owned by Symbian
IPC Inter Process Communication
-MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
+MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
MTM Registry A list of currently installed MTMs maintained by the message server.
TLS Transport Layer Security, provides encryption of a TCP/IP socket.
M-HTML Standard for including HTML in MIME email messages see http://www.ietf.org/rfc/rfc2557.txt
@@ -31495,15 +23351,1033 @@
Message Editor Application for creating or editing a message
Message Server Symbian OS Server that handles request to modify the Message Store
Message Store Store of messages and related information kept in the file system on a Symbian OS device.
-Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
-Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
+Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
+Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
Global Inbox A standard folder under the local service which is used to store incoming messages like SMS MMS etc. as opposed to an IMAP4 Inbox which would be under an IMAP4 service and is a representation of the Inbox on an IMAP4 email server.
Central Repository centralised and secure storage facility for application settings
OBEX Object exchange protocol, used to send objects such as vCards or files between devices via infrared or Bluetooth.
GMXML XML parser / generator for use with SMIL formatted messages.
UID Unique Identifier, a 32 bit number allocated from a registry owned by Symbian
IPC Inter Process Communication
-MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
+MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
+MTM Registry A list of currently installed MTMs maintained by the message server.
+TLS Transport Layer Security, provides encryption of a TCP/IP socket.
+M-HTML Standard for including HTML in MIME email messages see http://www.ietf.org/rfc/rfc2557.txt
+MIME Specification for the format of email message bodies see http://www.ietf.org/rfc/rfc1341.txt
+RFC2822 The standard format for internet mail messages see http://www.ietf.org/rfc/rfc0822.txt
+SMTP Simple Mail Transport Protocol
+SID Secure Identification
+IMAP4 Internet Mail Access Protocol
+POP3 Post Office Protocol Version 3
+NBS Narrow Band Socket, in the messaging context this refers to the socket that is used to talk to the SMS stack for receiving and sending SMS messages
+SMS Short Message Service
+MMS Multimedia Message Service
+WAP Wireless Application Protocol
+WSP WAP Session Protocol
+HTTP Hypertext transfer protocol
+PDU Protocol Data Unit. This is the encoded form of SMS and MMS messages.
+Versit A consortium that defined standard formats for things like contacts (vCard) and calendar entries (vCals)
+SDP Service Discovery Protocol. A Bluetooth protocol that allows an applications to discover which services are available and to determine the characteristics of the services.
+SMIL Synchronized Multimedia Integration Language. Presentation language that is commonly used to define the contents of an MMS message.
+XML Extensible Mark-up Language
+DOM Document Object Model
+DTD Document Type Definition, a schema that defines the structure of an XML document.
+ESTORE Symbian OS component that provides stream based storage. Messaging uses the Permanent file store provided by ESTORE to store its index entries.
+Appendix A - Example Sequence Diagrams
+A.1 Copy to a Remote Service
+
+Figure 33 Sequence Diagram Showing Copying to a Remote Service
+Figure 33 shows a client copying a message to a remote service using the Messaging Client API. The message server then delegates the copy to the SMTP Server MTM. The Server MTM interprets the request as a request to send the message so it opens a connection to a remote SMTP server and sends the message. While the message is being sent the client can retrieve progress information from the CMsvOperation object that was returned by CMsvEntry::CopyL. The dark grey IPC line represents the split between the objects running in the client’s process space on the left and the message server’s process on the right.
+There are four basic steps:
+1. The client opens session with Message Server and creates a CMsvEntry set on the global outbox,
+2. The client then requests an asynchronous copy from the outbox to the SMTP service, a CMsvOperation object is returned. The message server loads the SMTP Server MTM and delegates the copy operation to it.
+3. The client requests progress from the CMsvOperation object, this request is passed through to the SMTP Server MTM. The client may repeat this step multiple times.
+4. The Server MTM finishes sending message. It moves the message to sent folder and completes the message server’s request. The message server completes the CMsvOperation object, which requests the final progress from the message server. The server returns the final progress and deletes the Server MTM. The CMsvOperation then completes the client’s original request.
+This diagram hides all of the internal working of the SMTP Server MTM, for information on this see below.
+A.2 SMTP Session
+
+Figure 34 Sequence Diagram Showing a SMTP Session
+Figure 34 shows the operation of the SMTP Server MTM after a request has come from the message server to copy a message to the SMTP service.
+1. SMTP Server MTM gets the request from the message server, it will build a selection of messages consisting of the union of the selection of messages passed in and the messages in the outbox that are associated with this SMTP service and are ready to be sent. The chain of classes are constructed, and a request is passed to networking to connect to the remote SMTP server, details of the server name and port are retrieved from the settings stored in the SMTP service entry.
+2. The component waits for the SMTP server to respond with a greeting indicating it is willing to talk, then sends EHLO to the server and waits for the response detailing the capabilities of the Server. After this step there could set steps to start using TLS and or SMTP AUTH depending on the SMTP settings.
+3. CImSmtpSession calls back into CMsgOutboxSend to retrieve the next message to be sent, then constructs a CImSmtpFile object to handle sending, for details on the sending see SMTP Email Send. When sending the email has completed the CImSmtpFile object is deleted.
+4. CImSmtpSession calls back into CMsgOutboxSend to retrieve the next message which returns saying there are no more messages. CImSmtpSession sends QUIT to the SMTP server and completes CMsgOutboxSend. CMsgOutboxSend deletes CImSmtpSession which tears down the connection to the SMTP server; it then completes the SMTP Server MTM. The Server MTM will then complete the message server and be deleted.
+A.3 SMTP Email Send
+
+Figure 35 Sequence Diagram Showing SMTP Transactions during Email Send.
+Figure 35 shows a CImSmtpFile object sending an email message to an SMTP server.
+1. Construct a CImSendMessage object, part of the imut component. Reset the SMTP Server
+2. Read address information from the CImHeader object stored in the message store, send address information to SMTP server.
+3. Use CImSendMessage object to read the message from the message store and generate RFC2822 message line by line. Send each line to the server as it is generated.
+4. Complete and send the message by sending a full stop to the SMTP server
+
+
+
+
+Messaging Symbian OS v7.0s, v8.0, v8.1, v9.0, v9.1 Architectural Description
+
+Status: Issued
+Team/Department : Messaging / Content & Messaging
+
+Contents
+1 INTRODUCTION 6
+1.1 PURPOSE AND SCOPE 6
+2 SUBSYSTEM OVERVIEW AND BACKGROUND 6
+3 MESSAGING ARCHITECTURE AND APIS 7
+3.1 SUBSYSTEM COMPONENTS 7
+3.1.1 Framework components 7
+3.1.1.1 Message Server and MTM architecture 7
+3.1.1.2 Schedule Send 7
+3.1.1.3 SendAs Version 1 7
+3.1.1.4 SendAs Version 2 7
+3.1.1.5 Watcher Framework 8
+3.1.1.6 Message URL Handler 8
+3.1.1.7 Bio Message Framework 8
+3.1.2 Plug-ins 8
+3.1.2.1 SMS 8
+3.1.2.2 CDMA SMS 8
+3.1.2.3 Email 9
+3.1.2.4 OBEX 9
+3.1.2.5 MMS 9
+3.1.2.6 GMXML 10
+3.1.2.7 Bio Message Plug-ins 10
+3.1.2.8 PCMTM 10
+3.1.2.9 Fax 10
+3.2 GENERAL DESCRIPTION 11
+3.2.1 Messaging / Message Server and MTM Architecture APIs 11
+3.2.1.1 Key Internal Relationships and Dependencies 11
+3.2.1.2 Key External Relationships and Dependencies 12
+3.2.1.3 API Purpose - Further Elaboration 13
+3.2.1.3.1 Message Store 13
+3.2.1.3.2 Data File Storage (pre - v9.0) 15
+3.2.1.3.3 Platform Security Compliant Message Store 16
+3.2.1.3.4 How message centres display the message store 17
+3.2.1.3.5 Message Type Module Architecture 19
+3.2.1.3.6 Message Server Client API 21
+3.2.2 Messaging / Send As APIs 22
+3.2.2.1 Key Relationships and Dependencies 22
+3.2.2.2 API Purpose - Further Elaboration 22
+3.2.2.2.1 SendAs API (pre – v9.0) 22
+3.2.3 Platform Security Compliant SendAs Server (v9.0 onwards) 23
+3.2.4 Messaging / Schedule Send APIs 24
+3.2.4.1 Key Relationships and Dependencies 24
+3.2.4.2 API Purpose - Further Elaboration 24
+3.2.4.2.1 Schedule Send 24
+3.2.5 Messaging / Watchers APIs 25
+3.2.5.1 Key Relationships and Dependencies 25
+3.2.5.2 API Purpose - Further Elaboration 25
+3.2.6 Messaging / Message URL Handler APIs 26
+3.2.6.1 Key Relationships and Dependencies 26
+3.2.6.2 API Purpose - Further Elaboration 26
+3.2.6.2.1 Message URL Handler Application 26
+3.2.6.2.2 Message URL Recognisers 27
+3.2.7 Messaging / SMS APIs 27
+3.2.7.1 Key Internal Relationships and Dependencies 27
+3.2.7.2 Key External Relationships and Dependencies 28
+3.2.7.3 API Purpose - Further Elaboration 28
+3.2.7.3.1 SMS Watchers 28
+3.2.7.3.2 SMS Client MTM 29
+3.2.7.3.3 SMS Utilities 29
+3.2.7.3.4 SMS Server MTM 30
+3.2.8 Messaging / CDMA SMS APIs 31
+3.2.8.1 Key Internal Relationships and Dependencies 31
+3.2.8.2 Key External Relationships and Dependencies 32
+3.2.8.3 API Purpose - Further Elaboration 32
+3.2.8.3.1 CDMA SMS Watchers 32
+3.2.8.3.2 CDMA SMS Client MTM 33
+3.2.8.3.3 CDMA SMS Utilities 33
+3.2.8.3.4 CDMA SMS Server MTM 33
+3.2.8.3.5 Configuration for using CDMA SMS MTM 34
+3.2.9 Messaging / Email APIs 35
+3.2.9.1 Key Internal Relationships and Dependencies 35
+3.2.9.2 Key External Relationships and Dependencies 36
+3.2.9.3 API Purpose - Further Elaboration 36
+3.2.9.3.1 Email Overview 36
+3.2.9.3.2 Email Client Utilities 37
+3.2.9.3.3 Email Server MTM Utilities 37
+3.2.9.3.4 POP3 MTMs 37
+3.2.9.3.5 IMAP4 MTMs 38
+3.2.9.3.6 SMTP MTMs 40
+3.2.9.3.7 Autosend 40
+3.2.10 Messaging / MMS APIs 40
+3.2.10.1 Key Internal Relationships and Dependencies 41
+3.2.10.2 API Purpose - Further Elaboration 41
+3.2.10.2.1 MMS Overview 41
+3.2.10.2.2 MMS Utilities 42
+3.2.10.2.3 MMS Watcher 43
+3.2.10.2.4 MMS Client MTM 43
+3.2.10.2.5 MMS Server MTM 44
+3.2.10.2.6 MMS Codec 45
+3.2.11 Messaging / BIO APIs 46
+3.2.11.1 Key Internal Relationships and Dependencies 46
+3.2.11.2 API Purpose - Further Elaboration 47
+3.2.11.2.1 BIO Overview 47
+3.2.11.2.2 BIO MTM 47
+3.2.11.2.3 BIO Database 48
+3.2.11.2.4 BIO Parsers 48
+3.2.11.2.5 BIF Files and Utilities 48
+3.2.11.2.6 Platform Security Compliant Messaging / BIO APIs 49
+3.2.12 Messaging / OBEX MTM APIs 50
+3.2.12.1 Key Internal Relationships and Dependencies 50
+3.2.12.2 OBEX MTM Overview 50
+3.2.12.2.1 OBEX MTM 50
+3.2.12.2.2 IR MTM 51
+3.2.12.2.3 Bluetooth MTM 51
+3.2.12.2.4 OBEX MTM Utils 52
+3.2.12.2.5 Platform Security Compliant Messaging / OBEX MTM APIs 52
+3.2.13 Messaging / GMXML APIs 52
+3.2.13.1 Key Relationships and Dependencies 52
+3.2.13.2 Overview 53
+3.2.13.2.1 GMXML DOM 53
+3.2.13.2.2 GMXML Parser and Composer 53
+3.2.13.2.3 GMXML SMIL DTD (Validator) 53
+4 SECURITY 54
+4.1 DATA CAGING 54
+4.2 BACKUP AND RESTORE 54
+4.3 CAPABILITY RANGES 54
+4.3.1 Capabilities granted to executables 54
+4.3.2 Capabilities granted to DLLs 55
+4.3.3 Capabilities required to use the subsystem 57
+5 FURTHER INFORMATION 59
+5.1 REFERENCES 59
+5.2 OPEN ISSUES 59
+5.3 GLOSSARY 60
+APPENDIX A - EXAMPLE SEQUENCE DIAGRAMS 62
+A.1 COPY TO A REMOTE SERVICE 62
+A.2 SMTP SESSION 64
+A.3 SMTP EMAIL SEND 66
+
+Table of Figures
+Figure 1 Where Messaging Lives 6
+Figure 2 MTM Relationships 11
+Figure 3 External Dependencies 12
+Figure 4 Message Store 13
+Figure 5 Series 60 Inbox List View 14
+Figure 6 Remote and Local Entries 14
+Figure 7 Email Message 15
+Figure 8 Series 60 Message Centre (Composed from 2 screen shots) 17
+Figure 9 UIQ Message Centre 18
+Figure 10 Messaging MTM Structure (light coloured components are part of messaging subsystem) 19
+Figure 11 Nokia 9210 Outbox List View 20
+Figure 12 SendAs Version 1 Dependencies 22
+Figure 13 SendAs Version 2 Dependencies 23
+Figure 14 Schedule Send Dependencies 24
+Figure 15 Watcher Dependencies 25
+Figure 16 Message URL Handler Dependencies 26
+Figure 17 SMS Internal Dependencies 27
+Figure 18 SMS External Dependencies 28
+Figure 19 CMDA SMS Internal Dependencies 31
+Figure 20 CDMA SMS External Dependencies 32
+Figure 19 Email Internal Dependencies 35
+Figure 20 Email External Dependencies 36
+Figure 21 MMS Internal Dependencies 41
+Figure 22 MMS Utilities External Dependencies 42
+Figure 23 MMS Watcher External Dependencies 43
+Figure 24 MMS Client MTM Dependencies 43
+Figure 25 MMS Server MTM Dependencies 44
+Figure 26 BIO Message Internal Dependencies 46
+Figure 27 Bio Parser External Dependencies 47
+Figure 26 BIO Message Dependencies (v9.0) 49
+Figure 28 OBEX Internal Dependencies 50
+Figure 29 OBEX External Dependencies 51
+Figure 30 IR MTM Dependencies 51
+Figure 31 Bluetooth MTM Dependencies 52
+Figure 32 GMXML Dependencies 52
+Figure 33 Sequence Diagram Showing Copying to a Remote Service 62
+Figure 34 Sequence Diagram Showing a SMTP Session 64
+Figure 35 Sequence Diagram Showing SMTP Transactions during Email Send. 66
+1 Introduction
+1.1 Purpose and Scope
+The Messaging Architectural Description details the architecture and APIs exposed by the Messaging Subsystem. This document does not attempt to list all functionality provided by the messaging subsystem. For details on the functionality provided and the specifications implemented by the messaging subsystem see the Messaging Functional Description [R1]. This document describes the general architecture of messaging subsystem. Information related to a particular release version is mentioned with relevant release number.
+2 Subsystem Overview and Background
+The Messaging Subsystem provides an application level API to handle the storage and transport of different message types. It sits between messaging applications and the lower level subsystems which messaging uses for storage and transmission of messages.
+
+Figure 1 Where Messaging Lives
+The message types that messaging currently supports are Email (POP3, IMAP4 & SMTP), SMS, MMS and OBEX. The set of supported message types is extensible at run time by the use of plug-in modules that are responsible for the transmission and storage of a particular message type. This means that the set of components shown communicating with the network cloud depend on the message types installed.
+3 Messaging Architecture and APIs
+3.1 Subsystem components
+The Messaging subsystem components can be split into two categories: those components that form the framework and those that plug into the framework to support specific message types. This section briefly describes each of the components, more detailed descriptions of the components and their dependencies can be found in later sections of this document.
+3.1.1 Framework components
+3.1.1.1 Message Server and MTM architecture
+The message server is the core component in the messaging subsystem. It provides the message store used to contain messages. The Message Type Module architecture also allows plug-ins to add support for new message types to the messaging subsystem.
+Component Description
+messaging\framework\serverexe Executable that links to the server component and starts the message server
+messaging\framework\server Contains classes that make up both the client and server side of the message server API.
+messaging\framework\mtmbase Base classes for the plug-ins that handle the various message types
+3.1.1.2 Schedule Send
+The Schedule Send component is an extension to the framework that provides support for scheduling of operations such as sending messages. Message type modules that wish to support this functionality can use these support components to implement scheduling. For example the SMS MTM uses this to allow scheduled sending of SMS messages.
+Component Description
+messaging\schedulesend\schedulesendmtm Base classes that handle functionality for message server plug-ins that wish to enable scheduling of sending messages.
+messaging\schedulesend\schedulesendexe Executable use to provide schedule send behaviour.
+3.1.1.3 SendAs Version 1
+This version of SendAs is supported in releases pre - v9.0. SendAs provides a high level API for applications that wish to include a “Send As” menu to allow users to send content via one of the message types supported by messaging. The application using the API does not have to be aware of the message type selected by the user. Note the API does not send the messages.
+Component Description
+messaging\sendas High level API to allow creation of messages.
+3.1.1.4 SendAs Version 2
+From v9.0 and onwards the SendAs has been replaced with client server architecture based SendAs server. The client server architecture enhances secured platform implementation. The SendAs server polices the client application. If it is not trusted with required capabilities the SendAs server will refuse the client access. The client MTM for the message type can send a message with user permission even if the client does not have the correct capabilities.
+Component Description
+messaging\sendAsV2 High level API to allow the creation and sending of messages
+
+3.1.1.5 Watcher Framework
+The watcher framework is a lightweight framework to allow plug-ins to wait on events. For example there is an SMS watcher that waits for incoming SMS messages and delivers them to the message store. The watcher framework will only load plug-ins from ROM.
+Component Description
+messaging\framework\watcher Executable that loads and runs watcher plug-ins.
+3.1.1.6 Message URL Handler
+Support for recognising messaging URLs (mailto:, sms:, fax:, mms:), and then launching an editor with a new message.
+Component Description
+messaging\urlhandler\urlhandler An application that parses the URLs and then creates a correctly addressed message and launches a message editor.
+messaging\urlhandler\recogniser Recognisers that map from the URL schemes to the mime types.
+3.1.1.7 Bio Message Framework
+The Bio Message Framework provides a framework that supports plug-ins to handle messages like vCards and Internet access point set-up messages.
+Component Description
+messaging\biomsg\BDB\BIODB Classes to maintain the database of bio registration files.
+messaging\biomsg\BIFU\BIFU Classes for reading and writing bio registration files
+messaging\biomsg\BIOC\BIOC Bio message client MTM, this is in the framework section as it forms part of the bio messaging framework it is also a plug-in to the messaging framework.
+messaging\biomsg\BIOS\BIOS Bio message server MTM, this is in the framework section as it forms part of the bio messaging framework it is also a plug-in to the messaging framework.
+3.1.2 Plug-ins
+3.1.2.1 SMS
+The SMS plug-ins provide application level support for the Short Message Service messages.
+Component Description
+messaging\biomsg\BioWatchers Plug-ins to the watcher framework to listen for SMS, WSP, and WDP messages and deliver them to the global inbox in the message store.
+messaging\sms\clientmtm A plug-in to the message server framework to provide a generic API for creation of SMS messages (SMS Client MTM & SMS utilities)
+messaging\sms\servermtm A plug-in to the message server framework to provide a generic API for sending of SMS messages (SMS Server MTM)
+3.1.2.2 CDMA SMS
+The CDMA SMS plug-ins provide application level support for the CDMA Short Message Service messages.
+Component Description
+messaging\biomsg\BioWatchersCdma Plug-ins to the watcher framework to listen for CDMA SMS messages and deliver them to the global inbox in the message store.
+messaging\sms\multimode\clientmtm A plug-in to the message server framework to provide a generic API for creation of CDMA SMS messages (CDMA SMS Client MTM)
+messaging\sms\multimode\servermtm A plug-in to the message server framework to provide a generic API for sending of CDMA SMS messages (CDMA SMS Server MTM)
+
+3.1.2.3 Email
+The email plug-ins provide support the POP3, IMAP4 and SMTP email protocols and support for parsing and generating plain test, MIME and M-HTML format email messages.
+Component Description
+messaging\email\clientmtms A plug-in to the message server framework to provide a generic API for creation of email messages (IMAP4 SMTP and POP3 Client MTMs & email utilities)
+messaging\email\imapservermtm A plug-in to the message server framework to provide a generic API for access to a remote IMAP4 server (IMAP4 Server MTM)
+messaging\email\smtpservermtm A plug-in to the message server framework to provide a generic API for access to a remote SMTP server (SMTP Server MTM)
+messaging\email\popservermtm A plug-in to the message server framework to provide generic API for access to remote POP3 server (POP3 Server MTM)
+messaging\email\servermtmutils Email utilities for parsing plain text and MIME email messages. It also provides an abstraction of the TCP/IP sockets for use by the SMTP POP3 and IMAP4 plug-ins.
+messaging\email\autosend An executable that requests SMTP Server MTM to send messages in the outbox. This is used to provide send on next connection functionality and is started by the POP3 and IMAP4 Client MTMs.
+3.1.2.4 OBEX
+The OBEX MTM is a set of plug-ins to the message server that provides support for IR and Bluetooth beaming.
+Component Description
+messaging\obex\btmtm\btclient\group\btcmtm Bluetooth Client MTM
+messaging\obex\btmtm\btserver\group\btsmtm Bluetooth Server MTM
+messaging\obex\irmtm\irclient\group\ircmtm IR Client MTM
+messaging\obex\irmtm\irserver\group\IRSMTM IR Server MTM
+messaging\obex\obexmtm\obexclient\group\obexClientMtm OBEX Client MTM, base classes for the Bluetooth and IR Client MTMs
+messaging\obex\obexmtm\obexserver\group\obexServerMtm OBEX Server MTM, base classes for the Bluetooth and IR Server MTMs
+messaging\obex\obexmtm\obexutil\group\obexMtmUtil OBEX MTM utilities
+3.1.2.5 MMS
+The MMS MTM is a plug-in to the message server that provides support for MMS messages. From v9.0 and onwards MMS MTM and related components are removed.
+Component Description
+messaging\mms\utils MMS Utilities
+messaging\mms\servermtm MMS Server MTM
+messaging\mms\mmswatcherplugins MMS plug-ins to WAP push framework to handle reception of MMS notifications
+messaging\mms\codec MMS utilities for handling MMS codecs
+messaging\mms\clientmtm MMS Client MTM
+3.1.2.6 GMXML
+GMXML is a parser/generator for SMIL presentations for MMS messages.
+Component Description
+messaging\GMXML\XMLParser XML parser designed for parsing of SMIL messages
+messaging\GMXML\XMLDom XML document object model designed for parsing of SMIL messages
+messaging\GMXML\SMILdtd SMIL DTD
+3.1.2.7 Bio Message Plug-ins
+These parsers plug into the bio messaging framework to handle specific types of bio message.
+Component Description
+messaging\biomsg\cbcp\CBCP Compact business card parser
+messaging\biomsg\enp\ENP Email notification parser
+messaging\biomsg\gfp\gfp General file parser
+messaging\biomsg\iacp\IACP Nokia Smart Message Internet Access Parser
+messaging\biomsg\wapp\wapp Nokia/Ericsson OTA Parser
+3.1.2.8 PCMTM
+Plug-in to the message server that provided email synchronisation with a PC. This component has been deprecated in 8.0a and will not been documented in the API section below.
+3.1.2.9 Fax
+Plug-in to the message server that provides fax support. This component has been deprecated in 8.0a and will not been documented in the API section below.
+
+3.2 General Description
+3.2.1 Messaging / Message Server and MTM Architecture APIs
+3.2.1.1 Key Internal Relationships and Dependencies
+
+Figure 2 MTM Relationships
+Figure 2 shows the relationship between the Message Server and the MTM plug-ins. The grey classes are realisations of the MTM interfaces defined by the messaging framework. The message server depends on the Server MTM interface. Messaging Clients depend on the Client, UI and UI Data MTM interfaces and the Message Server Client API.
+3.2.1.2 Key External Relationships and Dependencies
+
+Figure 3 External Dependencies
+The grey package representing the messaging client depends on the Client, UI and UI Data interfaces and the Messaging Client API. The message server then depends on:
+• Charconv – Provides character set conversion routines, used to convert encoded message body text to Unicode body text.
+• EStore – Provides API to handle a stream based store used for the messaging index file and the framework classes for the message store files. (omitted from other dependency diagrams as it is implied by the dependency on the message server)
+• F32 – Provides the file server APIs used to access the file system directories in which messaging stores files containing message data. (omitted from other dependency diagrams)
+• BAFL – Provides API to load the correct messaging resource file dependent on the current language and to register the message store index file with the backup server. (omitted from other dependency diagrams)
+• ETEXT – Rich text APIs used to store body text of messages, this rich text format is a Symbian Proprietary format. (omitted from other dependency diagrams)
+• EUSER – Core Symbian OS utilities such as descriptors, arrays, client / server framework, cleanup stack and others (omitted from this and other dependency diagrams).
+• Central Repository – Centralised and secure storage facility for application settings, the message server stores message settings data in the central repository (from v9.0 and onwards).
+Note that debug only dependencies such as the flogger have been omitted from dependency diagrams.
+3.2.1.3 API Purpose - Further Elaboration
+3.2.1.3.1 Message Store
+The message server provides persistent storage of messages and messaging account settings. It does this by providing a message store consisting of a tree of message entries. Multiple clients can access the message store simultaneously. Each entry in the tree can represent an email account, folder of messages, message part, etc.
+
+Figure 4 Message Store
+Figure 4 shows an example message store. The tree is broken down in to three levels:
+1. The Root entry. This entry is just present to tie the tree structure together
+2. Service entries. There is one local service under which local folders and messages are stored, and zero or more remote services. Remote services represent message accounts.
+3. Message & Folder entries. Messages and folders, under the local service represent messages stored on the device. Messages and folders under remote services represent a local copy of messages that are present on a remote server. For example under a POP3 email service you would have copies of all the messages present on the POP3 email server, or under an SMS service you might find SMS messages that are stored on a SIM.
+The message server controls access to the entries in the store. It enforces the three levels therefore attempts to create message or folder entries directly under the root entry will fail.
+The message server provides three types of storage for each entry in the message store:
+• Index entry - TMsvEntry - intended to provide enough information for UI to display list views as shown in Figure 5. This consists of two strings and various flags (read, complete, has attachments etc).
+• Stream based file store - CMsvStore – provides storage of streams of data associated with UIDs. A standard UID is defined for storing body text. Other UIDs are specific. For example the email MTMs define a UID for storage of MIME headers. Compared to the index entry information this is used to store larger objects and is extensible, at the cost of being slower to access. From v9.0 and onwards CMsvStore provides an Attachment API for managing attachments. The Attachment API should be used as attachments can no longer be accessed directly due to Platform Security.
+• Directory of files – normally used for attachments.
+The only storage type that is always present is the index entry. The stream store and the directory of files are optional.
+
+Figure 5 Series 60 Inbox List View
+
+Figure 6 Remote and Local Entries
+As shown in Figure 6 the message store is split into two sets of entries:
+• Remote entries - entries that are representations of entries stored on a remote store .
+• Local entries - entries not linked to a remote store.
+The message server handles changes to local entries; internally it hands off changes to remote entries to the Server MTM that owns that service. Examples of operations that are handed off to Server MTMs are operations involving copying and moving messages to and from a remote service. See section 3.2.1.3.5 or more information on Server MTMs.
+Each entry within the store has a type:
+Folder – Messages can be grouped into folders. Standard folders such as inbox / outbox and user created folders.
+Message – Storage of the content of a message. Message entries can have child entries used to represent the structure of a message.
+Attachment – These represent attachments under a message entry.
+Root & Local Service Entry – There tie the tree structure together. However the Stream store associated with the root entry is sometimes used by UIs to store preferences e.g. default folder views etc.
+Remote Service - Represents a source and / or destination for messages. They are used to store the settings associated with the source / destination.
+Message Type Specific - MTMs can create other message types for use as child entries to messages they own. For example email uses a tree structure, with a message entry as the root, to represent the MIME structure of an email message; it uses folder entries to represent MIME folders and adds new types for entries representing the html body and text body parts of a message. This is shown in Figure 7.
+
+Figure 7 Email Message
+Using the message store to represent message structure allows reuse of the tree structure and makes it very simple to represent one message embedded in another. However this representation introduces performance issues as it results in each message having multiple files associated with it. The message server also keeps all index entries in memory; therefore this representation increases the memory footprint of the message server. Therefore when designing new MTMs we should think about moving away using multiple index entries to store one message in the message store.
+A default message store is created if the message server starts and no message store is present or a corrupt message store is present. The server will initially create a store with just a root entry, and then the server will create any standard folders defined in the resource file msgs.rsc. Finally the server will check whether an executable ‘mailinit.exe’ is present on the system, if it is present the server will launch the executable to allow customisation of the message store. The behaviour of ‘mailinit.exe’ is defined by the UI family of the device. However the typical behaviour is to load each of the UI Message Type Modules and allow each to perform any message type specific initialisation. For example the SMS plug-in typically creates a default service entry.
+
+3.2.1.3.2 Data File Storage (pre - v9.0)
+This section describes the files used by the message server before release v9.0. For information on the files used for release from v9.0 and onwards see section [3.2.1.3.3.1].
+Filename Access Purpose
+?:\system\Mail\index Private Message server index file, internal to message server
+?:\system\Mail\<8 hex digits> Shared via API Message server store files for services, clients access these via a messaging API.
+?:\system\Mail\<8 hex digits>.new Shared via API Temporary file used during committing message server store files.
+?:\SYSTEM\MAIL\<8 HEX DIGITS>_F\* Shared Files associated with a messaging service. These may be accessed directly by clients.
+?:\system\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits> Shared via API Message server store files for message entries, clients access these via a messaging API.
+?:\system\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits>.new Shared via API Temporary file used whilst committing message server store files.
+?:\system\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits>_F\* Shared Files associated with a message entry. These are accessed directly by clients.
+c:\system\data\msgs.ini Private Stores the drive containing the last used message store
+c:\system\Mtm\Mtm Registry v2 Private Cache of registered MTMs, internal to message server
+C:\system\data\sms_settings.dat Shared Copy of the SMS settings.
+?:\System\Mail\StoreInit.tmp Shared Created when message server runs ‘mailinit.exe’, ‘mailinit.exe’ should delete the file when it has successfully completed.
+?:\System\Mail\storedeleted.tmp Shared Created when message server finds and deletes a corrupt message store. Allows the UI to inform the user about the fact that the message store was corrupt.
+Files that are shown as private should only be accessed by the message server or by connectivity process for backup and restore purposes. Files listed as shared are accessed directly by messaging clients. Files listed as shared via API are accessed by client process but only via messaging APIs.
+3.2.1.3.3 Platform Security Compliant Message Store
+From v9.0 and onwards the message store is stored in the message server's data cage and the settings data are placed in the Central Repository. Access to the message store is only possible via message server APIs and not directly through file access. This leads to secured data storage and secured platform.
+3.2.1.3.3.1 Data caging
+Filename Purpose
+?:\private\<SID>\Mail\index Message server index file, internal to message server
+?:\ private\<SID>\Mail\<8 hex digits> Message server store files for services, clients access these via a messaging API.
+?:\ private\<SID>\Mail\<8 hex digits>.new Temporary file used during committing message server store files.
+?:\ private\<SID>\Mail\<8 hex digits>_F\* Files associated with a messaging service. These may be accessed directly by clients.
+?:\ private\<SID>\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits> Message server store files for message entries, clients access these via a messaging API.
+?:\ private\<SID>\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits>.new Temporary file used whilst committing message server store files.
+?:\ private\<SID>\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits>_F\* Files associated with a message entry. These are accessed directly by clients.
+c:\ private\<SID>\data\msgs.ini Stores the drive containing the last used message store
+c:\ private\<SID>\Mtm\Mtm Registry v2 Cache of registered MTMs, internal to message server
+?:\ private\<SID>\Mail\StoreInit.tmp Access via IPC call
+?:\ private\<SID>\Mail\storedeleted.tmp Created when message server finds and deletes a corrupt message store. Allows the UI to inform the user about the fact that the message store was corrupt.
+?\resource\messaging\bif\*.bif Registration data field with UID used in BIO framework
+
+3.2.1.3.4 How message centres display the message store
+The UI normally provides a Message Centre application to display the structure of the message store to the user. Different UIs map the structure to different views.
+
+Figure 8 Series 60 Message Centre (Composed from 2 screen shots)
+Figure 8 shows the top level view of the message centre application on a Series 60 phone. This shows that the message centre has hidden the local service and shows the standard folders at the same level as the services. Also the SMTP, SMS and MMS services are marked as hidden entries in the message store, and so do not appear in the message application.
+
+Figure 9 UIQ Message Centre
+However Figure 9 shows that the UIQ message centre has no 1-1 mapping from the structure in the message store to the structure shown to the user. Each of the message types is displayed as if its messages were contained in separate folders. Under each of these folders the user is presented with an inbox, outbox, send and drafts folder. This filtering is done in the UI layer as this functionality is not provided by the messaging API.
+3.2.1.3.5 Message Type Module Architecture
+
+Figure 10 Messaging MTM Structure (light coloured components are part of messaging subsystem)
+The MTM architecture is the plug-in scheme provided by the messaging framework to integrate different message transports into the message server. The plug-in scheme consists of four interfaces, the UI MTM, UI Data MTM, Client MTM and Server MTM. The messaging client applications loads and uses the first three which are loaded within the client’s process space. The final one the Server MTM is loaded within the message server process. The APIs for the client facing interfaces are extensible via run time type information provided by the QueryCapability API, and the InvokeAsyncFunction and InvokeSyncFunction APIs.
+3.2.1.3.5.1 UI MTM
+Handles requests from clients to view and edit messages or service settings. The MTM handles interaction with the message centre and as such the exact meaning of the APIs is defined by the UI. However common meanings are:
+• Create – Launches the editor with a new message.
+• Edit – If entry is a message this launches the editor; if entry is a service it edits the settings.
+• View – Launches the message viewer.
+• Display progress of an operation.
+3.2.1.3.5.2 UI data MTM
+This MTM provides fast access to UI components such as menu resources and bitmaps required by message centre for list views etc. Again the exact semantics are UI specific.
+There is a resource file defining UI specific functions, for example the Series 60 Messaging UI checks if the resource file contains text to display in the “New Message” menu.
+The UI data MTM also provides mapping from the message store’s TMsvEntry structure to Icons for the messaging list views and a status string, for example in the case of Nokia 9210 it is used in the outbox view to provide strings like “Resend 01:07” as shown in Figure 11. The class also provides functions to determine what operations are possible with a given entry. Examples of this are APIs that return whether the UI should allow the user to reply to the entry or to delete a service entry. The UI then uses this information to determine which menu options / short-cut keys should be allowed when the user selects a given entry.
+
+Figure 11 Nokia 9210 Outbox List View
+3.2.1.3.5.3 Client MTM
+Provides methods to create / reply and forward messages. Functions the Client MTMs provide are:
+• Create Message.
+• Reply to a Message.
+• Forward a Message.
+• Add / remove Addressees.
+• Add / remove body text.
+• Add / remove subject.
+• Add / remove attachments (the API cannot list attachments).
+The Client MTM interface is used by SendAs to provide a way of creating messages independently of the message type.
+3.2.1.3.5.4 Server MTM
+This is the final interface that makes up an MTM plug-in; it differs from the other three plug-ins in that it is loaded into the message server’s process space. The Server MTM provides access to messages under remote services. It handles connecting to remote servers to handle updating the local cache of these messages or to send messages copied to remote services when messages are copied to a remote service. The message server loads and hands off all message store operations that involve entries under a remote entry, these are the entries on the left-hand side of Figure 6.
+Functions that a Server MTM must implement:
+• Copy/MoveToLocal – called when the message server is asked to move or copy an entry that is currently under a remote service. A Server MTM might map this to retrieving a message from a remote mailbox.
+• Copy/MoveFromLocal – called when the message server is asked to move or copy from under the local service to a destination under a remote service. A Server MTM should map this to sending a message if the MTM supports sending.
+• Create, Delete, Change – called when the message server is asked to perform these operations on entries under a remote service.
+• StartCommand – this API provides a means of extending the API the Server MTM provides. Messaging clients pass a command ID and a selection of entries via the message server to the Server MTM. Examples of commands that Server MTMs might provide are: connect and synchronise the entries under a remote service with the messages on an email server, list SMS messages present on the phones SIM. These commands are MTM specific and therefore clients have to know which MTMs support which commands.
+3.2.1.3.5.5 MTM Registration
+MTMs must be registered with the message server so that clients can query what MTMs are present and the server knows which DLL to load to create a given MTM component. MTMs are registered by providing a resource file containing the MTMs UIDs, human readable name, and for each MTM interface it lists a DLL and the ordinal at which the constructor for that interface exists. The message server will search the ROM drive for MTM registration resource files on start-up and it will automatically register any MTMs found. For registration of MTMs installed on other drives, the message server provides an API to register and de-register an MTM. Registration will persist across a reboot, so an MTM only needs to be registered when it is installed on the system.
+When MTMs are registered or unregistered the message server will send events to all messaging clients with a message server session open.
+3.2.1.3.6 Message Server Client API
+The Messaging Server Client API breaks down into two categories: APIs for manipulation of the message store and utility APIs.
+3.2.1.3.6.1 Message Store manipulation APIs
+Requests from clients to modify the message store fall into three categories:
+1. Operations performed entirely with local entries (entries on the right-hand side of Figure 6) for example requests to create entries in the inbox, delete an entry from the drafts folder etc. The message server handles these operations directly.
+2. Operations that involve a remote entry (entries on the left-hand side of Figure 6) for example requests to delete an entry under a POP3 service, or copy a message to an SMTP service. The message server hands these operations off to the Server MTM that owns the service under which the remote entry is stored. The only exception to this rule is the ChangeAttributes API call. This modifies flags on an index entry and is handled by the message server for both local and remote entries. This means that a Server MTM can not rely on being called when flags like the Unread flag are changed. Note that operations can not involve two remote entries; therefore requests to copy entries between a remote service representing one POP3 account to a remote service representing another POP3 account will fail with an error.
+3. Requests that are explicitly directed at a Server MTM via the TransferCommand API. These commands are just passed to the correct Server MTM by looking up the Service ID and MTM of the first message in the selection passed into the command.
+The message server sends events when entries in the message store are modified to messaging clients that have a session open with the server.
+Where the API provides asynchronous functions to modify the message store or transfer a command to a Server MTM, the functions will return a message server operation object. This object can be used to request progress on operation or cancel the operation. Deleting the operation object returned, or closing the session used to make the request will result in the operation being cancelled, therefore a messaging client must remain running until operations it has requested have either completed or they will be cancelled. See appendix A.1 for an example of an asynchronous copy operation. If a Server MTM operating on the same remote service is already handling an operation, the message server will queue the new operation to be handled when the Server MTM becomes free. Requests for progress of operations that are queued will fail with KErrNotReady. The fact that the queue is based on the remote service ID means that you can have two Server MTMs of the same type running at the same time as long as they are operating on different services. So for example you can have two separate POP3 MTMs running synchronising different remote services with email servers.
+3.2.1.3.6.2 Utility APIs
+1. Access to MTM registries – These allow clients to construct instances of the interfaces an MTM implements.
+2. Register / Unregister an MTM.
+3. Change Drive – The message server closes the current message store and opens one on the drive specified. If no message store is present on the drive specified a new message store is created. The message sever can have only one mail store open at a time, if the current mail store is not available because a the disk the mail store is on is not present then the message server will switch the mail store back to the C: drive if an attempt is made to create a message in the inbox.
+4. Launching Editors – This launches the correct editor for a message. It is implemented by delegating the request to the UI MTM
+3.2.2 Messaging / Send As APIs
+3.2.2.1 Key Relationships and Dependencies
+
+Figure 12 SendAs Version 1 Dependencies
+SendAs version 1 and only present in releases before v9.0. SendAs uses the Messaging Client API to access the registry of Client MTMs and construct the Client MTM interfaces. The Client MTMs are then used for composing the message. SendAs requires clients to implement the MSendAsObserver interface. This interface is responsible for checking the return value of the capability queries made to Client MTMs that require a response and also for rendering message types that require it. The only message type supplied by Symbian that requires rendering is Fax, however this MTM has been removed in 8.0a and future releases.
+3.2.2.2 API Purpose - Further Elaboration
+3.2.2.2.1 SendAs API (pre – v9.0)
+The SendAs API makes use of the Client MTM interface and the Messaging Client API to provide a generic API for creating messages. Note despite the name of this component SendAs does not provide an API to send the message.
+SendAs builds a list of registered MTMs, then queries each MTM to check whether it supports sending, removing those MTMs from the list that do not support sending. This list is then provided to the messaging client application. At this point the application can add more constraints on the list of MTMs; for example it can insist the MTM supports Attachments or more than a certain size of body text. SendAs queries each of the MTMs about the requirements and will drop any MTMs from the list that does not meet them. When the application has finished adding requirements it selects one of the MTMs left in the list and uses that to compose the message, adding addresses, a subject, body text and attachments.
+SendAs supports setting a BIO Type for the message that is composed. This tells the transport that the body text represents a BIO Message. This is used when sending business cards from the contacts application as SMS messages; the contacts application puts the vCard data in the body text of the message and the transport sends it correctly. If the MTM in question supports attachments then the vCard is attached to the message.
+A new CSendAs object must be created for each message the application wishes to create.
+3.2.3 Platform Security Compliant SendAs Server (v9.0 onwards)
+
+Figure 13 SendAs Version 2 Dependencies
+From v9.0 and onwards the CSendAs has been replaced by the SendAs server component. The new SendAs server controls the access to the message store. Some of the key SendAs Server features are listed as follows.
+• Send a message once the capability policing of the client application has been completed.
+• Allow client applications to launch an editor for a specified message type.
+• Allow client applications to query the message type.
+The main client-side API is the RSendAs class. The client applications use this to connect to the Send-As server. The session object on the server-side is an instance of CSendAsSession.
+Client applications create messages using the RSendAsMessage API. Opening an RSendAsMessage object on Send-As server session creates a CSendAsMessage object in the Send-As server. There is a one-to-one mapping between an RSendAsMessage object and a CSendAsMessage object. This allows client applications to create multiple messages concurrently.
+
+3.2.4 Messaging / Schedule Send APIs
+3.2.4.1 Key Relationships and Dependencies
+
+Figure 14 Schedule Send Dependencies
+The Schedule Send Server MTM base class depends on the task scheduler to launch the schedule send executable at the correct time. To send the message with a package of data previously passed into the task scheduler by the Server MTM. The schedule send executable then uses the Messaging Client API to actually perform the requested operation.
+3.2.4.2 API Purpose - Further Elaboration
+3.2.4.2.1 Schedule Send
+The Schedule Send functionality is delivered by four components:
+Server MTM Base Class – The base class provides support to Server MTMs that wish to support scheduled operations.
+Data Structures – These are classes used to represent the data associated with a scheduled operation.
+Executable – The executable is run by the task scheduler at the scheduled time.
+The Task Scheduler – This component is part of the system libraries subsystem. Currently the SMS and Fax Server MTMs support scheduled sending.
+Clients request the Server MTM schedules operations via additional commands passed to TransferCommand API; this is passed to the Server MTM via the message server. The Server MTM packages the operation ID, a selection of message IDs, how often to poll for progress and an MTM specific buffer. It then passes this package of data to the task scheduler requesting that it launches the schedule send executable at the correct time with the packaged information.
+When the task scheduler launches the schedule send executable, it unpacks the schedule information and uses the Messaging Client API to request the Server MTM to perform the operation.
+Schedule Send supports a retry mechanism if the operation fails. The Server MTM has a resource file containing a mapping from the error codes the operation can fail with and actions to be performed. For example the SMS resource file has a mapping such that if the operation fails with an error code indicating a bad phone number the SMS will be set to failed and left in the outbox. Whereas if it fails with a error code indicating temporary network failure the send operation will be scheduled to be resent later with a maximum of three retries.
+3.2.5 Messaging / Watchers APIs
+3.2.5.1 Key Relationships and Dependencies
+
+Figure 15 Watcher Dependencies
+The watcher executable’s dependency on the message server is the result of a performance measure. The watcher process creates a message server session before initialising each of the watcher plug-ins and closes the session when it has finished. This keeps the message server running during initialisation avoiding starting and stopping the message server if each watcher plug-in opens and closes sessions.
+3.2.5.2 API Purpose - Further Elaboration
+The watcher framework consists of an executable that is launched when the device boots. The component that is responsible for launching it depends on the UI family. When the watcher.exe is launched it will load each DLL in z:\system\libs\watchers which has a second UID as KWatcherUid and calls the first DLL entry point to construct a CActive object.
+From v9.0 and onwards watcher DLLs are found by scanning the directory \resource\messaging\watchers for registry files. These files contain the name of a watcher DLL that can be loaded from ROM i.e. z:\sys\bin.
+The framework has retry behaviour if the first entry point leaves, in this case the watcher framework will start a timer and try and construct the watcher object 10 seconds later. Five attempts are made before the watcher plug-in is assumed to have failed completely. Once the watcher framework has constructed all the watchers it starts the active scheduler which should never exit.
+Watcher plug-ins typically make a request to another subsystem such that they will be completed when an external event like a fax line ringing or an SMS being received occurs. When the watcher has completed processing the request it will wait for the next event.
+No support for starting / stopping watchers is provided. This is a limitation that makes watchers unsuitable for operations like listening for messages beamed via IR, as the watcher should only run while the IR port is active.
+3.2.6 Messaging / Message URL Handler APIs
+3.2.6.1 Key Relationships and Dependencies
+
+Figure 16 Message URL Handler Dependencies
+3.2.6.2 API Purpose - Further Elaboration
+The Message URL Handler provides support for creating messages and launching messaging editors from URLs such as mailto:infobot@example.com?subject=current-issue. Note there is no dependency between the Message URL Handler application which processes the URLs and the Message URL Handler recognisers which maps from URLs to mime types.
+3.2.6.2.1 Message URL Handler Application
+This is a Symbian OS application that registers with the application framework that it can handle the mime types: x-epoc-url/fax, x-epoc-url/mailto and x-epoc-url/sms. When launched with a URL it will parse the URL to retrieve the address and other header fields and then use the SendAs API to create a new message with the correct address, headers etc. The application then uses the APIs in the MturUtils class provide by the mtmbase component in the messaging framework to launch the correct editor for the given message type. The application is marked as hidden and therefore should not be listed by UIs in application browsers.
+3.2.6.2.2 Message URL Recognisers
+This is a plug-in to the recogniser framework it will be called when the application framework wishes to recognise a file. Recognisers are called with the file name, in this case a URL, and a buffer containing the start of the file. The message URL recogniser compares the start of the URL with the URL schemes it recognises, if it finds a URL scheme it knows about it maps it to a mime type. The recogniser ignores the buffer passed in.
+Schemes recognised:
+Scheme Mime type
+mailto: X-Epoc-Url/mailto
+fax: X-Epoc-Url/fax
+sms: X-Epoc-Url/sms
+mms: X-Epoc-Url/mms
+See the application framework architectural description for more information on recognisers [R2].
+3.2.7 Messaging / SMS APIs
+3.2.7.1 Key Internal Relationships and Dependencies
+
+Figure 17 SMS Internal Dependencies
+3.2.7.2 Key External Relationships and Dependencies
+
+Figure 18 SMS External Dependencies
+3.2.7.3 API Purpose - Further Elaboration
+3.2.7.3.1 SMS Watchers
+The SMS watchers are made up of two watchers, the nbswatcher.dll and the wapwatcher.dll, and some common base classes in biowatcher.dll. The watchers listen for incoming messages from the SMS stack, part of the nbsprotocols subsystem [R3], and the WAP stack part of the WAP-Stack subsystem [R4].
+3.2.7.3.1.1 NBS Watcher
+The NBS watcher handles reception of SMS messages. When initialised by the watcher framework (see section 3.2.4) the watcher queries the bio messaging database for bio messages that are listed as having a type of ENbs. For each of these bio messages the watcher creates an object that opens a connection to the SMS stack and waits for the particular message type. The message types are either defined by the port number the message will be received on or by a string to watch for at the start of the message. For example Internet Access Configuration Point messages are start with “//SIAP11” and vCards are received on port 226. Finally the watcher listens for all other messages received from the SMS stack.
+When the NBS Watcher receives a non-class 2 SMS message it creates a new entry under the global inbox in the message store. For class 2 messages the entry is created in the class 2 folder as defined by the SMS settings, this may also be the global inbox. The details field of the entry is used to store the phone number of the incoming message or the name of the sender if the watcher finds a match for the phone number in the contacts database. The description field is used to store the first N characters of the SMS message, where N is defined in the SMS settings, or for bio messages the description as retrieved from the bio database. Bio messages also have the BioType field set to the UID of the bio message as retrieved from the bio database. The CSmsHeader class, which is a wrapper around the CSmsMessage class provided by the nbprotocols subsystem [R3], is used to externalise the SMS message to the entry’s CMsvStore. The watcher also places a copy of the body text of the message in the rich text stream of the entry’s CMsvStore.
+The NBS Watcher is also responsible for handing special SMS types including:
+• Replace Type Messages – When the watcher receives a message of this type it will scan the folder the message would have been delivered to for messages that have a matching protocol ID and from address. For each of the messages it checks whether the time stamps from the service centre and discards the older message.
+• Message Indications – The watcher can listen for incoming message waiting indications. The CSmsSettings class defines whether the watcher will listen and whether it will deliver the messages to the inbox or discard them. If the watcher is configured to listen for messages then it will use the SMS utilities in the SMS Client MTM to decode the message to determine the notification type and number of messages, e.g. 3 Email messages waiting, the strings for these messages are in the smss.rss resource file.
+• Delivery Reports – As with Message Indications the watcher can be configured to listen for these and again the SMS utilities get a string from the smss.rss resource file to put in the description field.
+The NBS Watcher handles changes to the bio database using the observer mechanism provided by the bio message database to observe when bio message types are added or removed and starting or stopping the object watching for that bio message type.
+3.2.7.3.1.2 WAP Watcher
+The WAP watcher listens for incoming messages from the WAP stack using the WAP message API [R4]. To determine ports to use to listen for messages the watcher queries the bio message database for bio message types EWsp, EWspSecure, EWap, EWapSecure and registers as an observer of the bio database and so will listen for new bio message with these types as they are added. The watcher stores the messages in the global inbox tagged with the bio type listed in the bio message database.
+3.2.7.3.2 SMS Client MTM
+The SMS Client MTM implements the standard set of Client MTM APIs described in Client MTM. In addition it provides:
+• Access to the CSmsHeader object that is used to represent the SMS message.
+• Access to the SMS settings stored in the associated SMS service.
+• The APIs required by Send As to allow Send As to create SMS messages including setting the bio type of the message to allow clients of Send As to send bio messages such as vCards and vCals. The data of the bio message is stored in the body text of the SMS message.
+• Simple check for valid SMS addresses, and SMS address is considered valid if it contains at least one digit.
+• Reading and writing SIM parameters.
+3.2.7.3.3 SMS Utilities
+These provide:
+• Classes to represent and store SMS messages (CSmsHeader), and SMS settings (CSmsSettings, CSmsMessageSettings) and a SMS number (CSmsNumber).
+• The CSmsHeader class contains and allows clients to access the CSmsMessage class that the nbsprotocols subsystem provides. This contains the entire SMS message and not just the header.
+• Functions to generate descriptions and details fields to store with SMS messages, including decoding special messages such as message indication and status report messages, reading resource file for descriptions strings of special messages, using the contacts database to replace phone numbers with names.
+• API to validate a GSM number.
+• Find the TMsvId of the SMS service entry.
+3.2.7.3.4 SMS Server MTM
+3.2.7.3.4.1 Sending Messages
+The SMS Server MTM handles sending of SMS and WAP messages via the SMS stack and the WAP stack. To support this it implements the CopyFromLocal API inherited from the Server MTM base class. It implements this as sending SMS messages and moving successfully sent messages to the Sent folder. When sending the SMS message the Server MTM checks the bio type of the message and uses the bio database to check the transport type for the bio message. The MTM supports ENbs that is sent via the SMS stack and EWap, EWapSecure that are sent via the WAP stack. The MTM does not support EWsp or EWspSecure although the watchers do support receiving them.
+If a message fails to send, sending is retried according to the settings in the smss.rss resource file as described in the schedule send section 3.2.3.
+3.2.7.3.4.2 Scheduling Messages
+The SMS Server MTM implements scheduled sending API by sub-classing from the schedule send Server MTM (see section 3.2.3). It accepts requests from clients either via the SMS Client MTM InvokeAsync API or via the CMsvSession::TransferCommand API to schedule messages to be sent or to delete existing schedules. When it receives a request to schedule a message it packages up the command and uses the scheduled send functionality to request that the task scheduler ask it to send the messages at a future point in time.
+3.2.7.3.4.3 Phone Store
+The phone store is the name given to storage of SMS messages outside of the message store. In the case of GSM phones this is the SIM. The SMS Server MTM accepts requests from clients to copy/move messages to and from the SIM and delete messages from the SIM. For example when copying to the SIM it packages up the SMS message and passes it to the SMS stack with a request to write it to the SIM. If the class2 folder has been set in the SMS settings class then the Server MTM will copy the SMS message to the SIM and then update the SMS message in the message store with details of the slot on the SIM that has been used to store the SMS and the fact that it is stored on the SIM.
+3.2.7.3.4.4 SIM Parameters
+The Server MTM provides functions to read / write SIM parameters, again these requests are passed to the SMS stack to be processed.
+3.2.8 Messaging / CDMA SMS APIs
+3.2.8.1 Key Internal Relationships and Dependencies
+
+Figure 19 CMDA SMS Internal Dependencies
+3.2.8.2 Key External Relationships and Dependencies
+`
+Figure 20 CDMA SMS External Dependencies
+3.2.8.3 API Purpose - Further Elaboration
+3.2.8.3.1 CDMA SMS Watchers
+The CDMA SMS watchers are made up of six watchers, the cdmanbswatcher.dll, vmnwatcher.dll, wemtwatcher.dll, wmtwatcher.dll, wptwatcher.dll, and the wapwatcher.dll, and some base classes in biowatcher.dll and cdmasocketwatcher. While the WAP watcher is common for both GSM and CDMA, the other watchers: CDMA NBS watcher, VMN watcher, WEMT watcher, WMT watcher, and the WPT watcher are used for CDMA only. The watchers listen for incoming messages from the CDMA SMS stack, part of the nbsprotocols subsystem [R3], and the WAP stack part of the WAP-Stack subsystem [R4].
+3.2.8.3.1.1 CDMA NBS Watcher
+The CDMA NBS watcher is similar to the NBS watcher and it handles bio messages defined in bio database. The CSmsHeader class is extended to wrap around the CCdmaSmsMessage class provided by the nbprotocols subsystem [R3], and is used to externalise the CDMA SMS message.
+For handling special CDMA SMS type, the CDMA NBS watcher is responsible for handling Message Indications as described in section 3.2.7.3.1.1 NBS Watcher.
+3.2.8.3.1.2 WAP Watcher
+The GSM WAP watcher is used to handle CDMA WAP message as well. The WAP watcher listens for incoming messages from the WAP stack, which can listen from the CDMA SMS stack or GSM SMS stack as appropriate. See 3.2.7.3.1.2 for more info about WAP watcher.
+3.2.8.3.1.3 Other CDMA Watchers
+The VMN watcher, WEMT watcher, WMT watcher and WPT watcher are CDMA watchers that handle reception of CDMA SMS messages. All CDMA SMS messages are associated with a teleservice. Therefore, each of the CDMA watchers is responsible for handling one teleservice: VMN watcher handles VMN SMS messages, WEMT watcher handles WEMT SMS messages, WMT watcher handles WMT SMS messages, and WPT watcher handles WPT SMS messages. The CSmsHeader class is reused to externalise the CDMA SMS message.
+The CDMA watchers are also responsible for handling special SMS types including:
+• Duplicate Message – When the watcher receives a duplicate message, it will discard the duplicate message as defined by the CDMA service settings.
+• User Acknowledge – The watcher can listen for user acknowledgment message of its teleservice type.
+• Delivery Acknowledge – The watcher can listen for delivery acknowledgment message of its teleservice type.
+• Read Acknowledge – The watcher can listen for read acknowledgment message of its teleservice type.
+3.2.8.3.2 CDMA SMS Client MTM
+The CDMA SMS Client MTM implements the standard set of Client MTM APIs described in Client MTM. In addition it provides:
+• Access to the CSmsHeader object that is used to represent the SMS message.
+• Access to the SMS settings stored in the associated SMS service. These settings are store in file store pre v9.0 but stored in Central Repository from v9.0 onwards.
+• The APIs required by Send As to allow Send As to create SMS messages including setting the bio type of the message to allow clients of Send As to send bio messages such as vCards and vCals. The data of the bio message is stored in the body text of the SMS message.
+• Simple check for valid SMS addresses, and SMS address is considered valid if it contains at least one digit.
+• Reading and writing SMS messages to R-UIM.
+3.2.8.3.3 CDMA SMS Utilities
+The CDMA version of SMS utilities are binary compatible with the GSM version of SMS utilities. But the classes that store SMS Message (CSMSHeader), and SMS settings (CSmsSettings, CSmsMessageSettings) and SMS number (CSmsNumber) are extended to store CDMA information. The CSmsHeader class is extended to contain and allow clients to access the CCdmaSmsMessage in addition to the CSmsMessage. Other functions provided by the GSM SMS Utilities is also provided by the CDMA version of SMS utilities, see 3.2.7.3.3 for information about GSM SMS Utilities.
+3.2.8.3.4 CDMA SMS Server MTM
+3.2.8.3.4.1 Sending Messages
+The CDMA SMS Server MTM handles sending of CDMA SMS and WAP messages via the CDMA SMS stack and the WAP stack. To support this it implements the CopyFromLocal API inherited from the Server MTM base class. It implements this as sending SMS messages and moving successfully sent messages to the Sent folder. When sending the CDMA SMS message the Server MTM will use the appropriate teleservice type. The MTM supports ENbs that is sent via the SMS stack and EWap, EWapSecure that are sent via the WAP stack. The MTM does not support EWsp or EWspSecure although the watchers do support receiving them.
+If a message fails to send, sending is retried according to the settings in the smss.rss resource file as described in the scheduled send section 3.2.4.
+3.2.8.3.4.2 Scheduling Messages
+The CDMA SMS Server MTM implements scheduled sending API by sub-classing from the schedule send Server MTM similar to implemented in the GSM SMS Server MTM. See 3.2.7.3.4.2 for more information.
+3.2.8.3.4.3 Phone Store
+In the case of CDMA phones, phone store can be phone-based storage or R-UIM based storage. The CDMA SMS Server MTM accepts requests from clients to copy/move messages to and from the phone/R-UIM and delete messages from the phone/R-UIM. For example when copying to the R-UIM it packages up the SMS message and passes it to the CDMA SMS stack with a request to write it to the R-UIM.
+3.2.8.3.5 Configuration for using CDMA SMS MTM
+The CDMA messaging components currently only support single mode, but it is designed such that it can become multimode in the future. Currently, -Dcdma option is used to for selecting CDMA mode for using emulator and building ROM.
+
+
+3.2.9 Messaging / Email APIs
+3.2.9.1 Key Internal Relationships and Dependencies
+
+Figure 19 Email Internal Dependencies
+
+3.2.9.2 Key External Relationships and Dependencies
+
+Figure 20 Email External Dependencies
+3.2.9.3 API Purpose - Further Elaboration
+3.2.9.3.1 Email Overview
+The Email plug-ins consist of a set of utilities and MTMs for POP3, IMAP4 and SMTP. For each email account a pair of services entries is created in the message store. For a POP3 account there will be an SMTP service and a POP3 service, for an IMAP4 account there will be an SMTP service and as IMAP4 service. These entries are used to store the settings for the email transport. Each of the service entries has its related ID set to the other member of the pair. The SMTP service is created invisible so the user only sees the POP3 or IMAP4 service entry, copying a message to the SMTP service will cause the SMTP Server MTM to attempt to send the message. The POP3 and IMAP4 MTMs provide functionality to synchronise with a remote email server this is achieved by extending the Client MTM interface via the InvokeAsync API. Synchronisation of a POP3 or IMAP4 account will result in copying headers and optionally body text and attachments from the email server and creating message entries under the POP3 or IMAP4 service entry.
+Email messages are represented in a common format whether they are being sent via SMTP or downloaded via POP3 or IMAP4. The email client utilities provide the classes for creating and manipulating the entry structure used to store emails. The email server side utilities provide classes to convert between the entry structure used to store emails in the message store and RFC2822 email messages sent to SMTP servers and retrieved from POP3 servers. IMAP4 email messages are parsed by the email server and the IMAP4 Server MTM requests and stores the individual parts of the messages.
+3.2.9.3.2 Email Client Utilities
+The email client utilities are part of the imcm DLL and provide classes for:
+• Storage of email messages including mime headers, RFC2822 headers, attachments, body text and encoding information in the message store
+• Manipulating email messages, for example adding attachments, replying etc.
+• To wrap up the character converters used to convert between standard character sets and Unicode. These make use of the charconv component that is part of the system libraries subsystem.
+• Storage of Email settings in the message store.
+• Progress information for email operations.
+The utilities are used directly by clients to access parts of email messages for display. CImEmailMessage provides the functionality used by clients displaying email messages, including listing attachments, getting body text and resolving URIs in M-HTML messages.
+The Email Client MTMs use the utilities when they are asked to create, reply to and forward messages CImEmailOperation provides the functionality to perform these operations. Each email message is represented by a parent message entry and then entries to represent mime folders and mime parts, see Figure 7 for an example, so adding or deleting mime parts involves walking the tree of entries and inserting / removing entries as appropriate.
+3.2.9.3.3 Email Server MTM Utilities
+The Email Server MTM Utilities are responsible for generating and parsing of RFC2822 format email messages and providing an API to wrap up a TCP/IP connection to a remote email server.
+• Parsing of RFC2822 Email Messages – The utilities provide an API that accepts the text of an RFC2822 email message a line at a time and stores the email message in messaging’s internal format for email messages. See the Email Client Utilities for details of this format. The API handles storing of RFC2822 headers, MIME headers, decoding of Base64 encoded or uuencoded attachments and decoding of text received in character sets supported by the charconv component. This API is only accessible to Server MTMs, as it requires classes that can only be instantiated while running within the message server process. See the Messaging Functional Specification [R1] for detail on which email specifications the utilities support.
+• Generation of RFC2822 Email Messages – The utilities provide an API to convert an email in messaging’s internal format into an RFC2822 email message. The API provides access to the RFC2822 text a line at a time for streaming to an SMTP server. The exact format of the email depends on the settings passed in; the API can generate plain RFC2822 email messages with uuencoded attachments, MIME email messages with Base64 encoded attachments, or M-HTML email messages with Base64 encoded attachments. See the Messaging Functional Specification [R1] for detail on which email specifications the utilities support.
+• TCP/IP socket wrapper – The utilities provide a class that abstracts a TCP/IP socket supplied by the networking subsystem into an API that supports sending and receiving lines of text to / from a remote server. This API is used to connect to remote email servers by each of the email Server MTMs. The API can either create insecure or secure sockets enabling the SSL encryption provided by the networking subsystem. It also supports changing an insecure socket into a secure socket, this enables the email Server MTMs to implement email protocols where the initial connection to the server is insecure and then a secure socket is negotiated before sending or requesting any sensitive information.
+3.2.9.3.4 POP3 MTMs
+The POP3 MTMs implements the functionality to synchronise the local message store with a remote POP3 email server.
+3.2.9.3.4.1 Client MTM
+The POP3 Client MTM implements the standard Client MTM APIs and other extensions:
+• Reply to, forward – These are accessible via the ReplyL and ForwardL APIs of a Client MTM and are implemented as calls to the email utilities class CImEmailOperation.
+• Reply to, forward, create new messages, create receipts and forward as attachment – These are accessible as commands available via the InvokeAsyncFunction API of the Client MTM, they are implemented as calls to CImEmailOperation.
+• Connecting, disconnecting and copying email while connected – These operations are accessible as commands available via the InvokeAsyncFunction API of the Client MTM, they are implemented as calls to the POP3 Server MTM.
+• Querying connection status – This command lets clients know whether the POP3 Server MTM is connected to an email server, and is available via the InvokeAsyncFunction API of the Client MTM. The Client MTM requests the information from the Server MTM.
+• Compound operations – The Client MTM provides functionality to wrap up connecting to email servers, copying / moving new messages or a selection of messages, and then optionally disconnecting. These commands are available via the InvokeAsyncFunction API of the Client MTM. The Client MTM implements this by using the CImPOP3GetMail class which requests the correct sequence of operations from the Server MTM, waiting for each operation to complete before requesting the next one.
+• Send on next connection If the Client MTM gets a request to connect to an email server it will check whether the POP3 settings. If send on next connection is requested it will launch the autosend.exe executable (see section 3.2.7.3.7) to handle sending messages waiting in the outbox.
+• Offline operations – The POP3 Client MTM has a command to cancel offline operations, this is available via the InvokeAsyncFunction API of the Client MTM. The Client MTM passes the request to the Server MTM.
+3.2.9.3.4.2 Server MTM
+The POP3 Server MTM handles the communication with the remote POP3 server and implementation of the POP3 protocol. The MTM uses CImTextServerSession to handle the communication with the email server and CImRecvConvert to parse the email messages downloaded, both are provided by the Email Server MTM Utilities.
+• Connect – The POP3 Server MTM will open a socket to the email server using CImTextServerSession and login user the username / password in the POP3 settings. After a successful connection the Server MTM will attempt to synchronise the current state of headers stored on the email server with the set stored in the message store and then start any pending offline operations. After the connect operation has completed the Server MTM will inform the message server that it is expecting more operations via the CommandExpected API and therefore the message server will not delete and unload the Server MTM.
+• Populate Message – The POP3 Server MTM treats requests to copy a message from and to the POP3 service as a request to download the full message.
+• Offline operations – When the POP3 Server MTM receives a request to copy, move, or delete and is not connected to a POP3 email server the Server MTM will store the operation in the CMsvStore of the entry being modified and perform the operation on the next connection to the email server.
+• Disconnect – When disconnecting from a remote email server the POP3 MTM will run any pending offline operations stored. After the disconnect operation completes the Server MTM will allow the message server to delete and unload the Server MTM by setting the CommandExpected API to false.
+3.2.9.3.5 IMAP4 MTMs
+The IMAP4 Server MTM implements the functionality to synchronise the local message store with a remote IMAP4 email server.
+3.2.9.3.5.1 Client MTM
+The IMAP4 Client MTM implements the standard Client MTM APIs and other extensions:
+• Connecting, disconnecting, synchronising, un/subscribing folders – These operations are accessible as commands available via the InvokeAsyncFunction API of the Client MTM, they are implemented as calls to the IMAP4 Server MTM.
+• Send on next connection – If the Client MTM gets a request to connect to an email server it will check whether the IMAP4 settings. If send on next connection is requested it will launch the autosend.exe executable (see section 3.2.7.3.7) to handle sending messages waiting in the outbox.
+• Reply to, and forward messages – These are accessible via the ReplyL and ForwardL APIs of a Client MTM and are implemented as calls to the email utilities class CImEmailOperation.
+• Reply to, forward, create new, create receipt, forward as attachment – These are accessible as commands available via the InvokeAsyncFunction API of the Client MTM, they are implemented as calls to CImEmailOperation.
+• Querying connection status – These commands let clients know whether the IMAP4 Server MTM is connected to an email server and whether it is currently processing a request. They are available via the InvokeAsyncFunction API of the Client MTM. The Client MTM requests the information from the Server MTM.
+• Compound Connection and synchronisation – The IMAP4 Client MTM provides a compound operation that connects and synchronises with an IMAP4 server. This operation is implemented as a client side object that combines requests to the IMAP4 Server MTM. The client side operation can complete the client request either after the connection, after the connection + sync or after the connection + sync + disconnect. The client will keep requesting that the inbox be resynchronised at a configurable interval so new messages received in the inbox on the server will appear under the IMAP4 inbox. The CImapConnectAndSyncOp class handles these compound operations.
+• Compound Connect and copy / move / populate messages – The IMAP4 Client MTM provides a compound operation that connects to an IMAP4 server and copies moves or populates messages. The implementation is provided by the CImImap4GetMail class which makes calls back into the IMAP4 Client MTM.
+• Offline operations – The IMAP4 Client MTM has a command to cancel offline operations, this is available via the InvokeAsyncFunction API of the Client MTM. The Client MTM passes the request to the Server MTM.
+3.2.9.3.5.2 Server MTM
+The IMAP4 Server MTM handles the communication with the remote IMAP4 server and implementation of the IMAP4 protocol. The MTM uses CImTextServerSession to handle the communication with the email server. The IMAP4 Server MTM opens two connections to the IMAP4 server this enables users to download messages while the Server MTM is performing a background synchronisation if requested by the Client MTM.
+• Connect – The IMAP4 Server MTM will open a socket to the email server using CImTextServerSession and login using the username / password in the IMAP4 settings. After a successful connection the Server MTM will optionally attempt to synchronise the current state of headers stored on the email server with the set stored in the message store and then start any pending offline operations. After the connect operation has completed the Server MTM will inform the message server that it is expecting more operations via the CommandExpected API and therefore the message server will not delete and unload the Server MTM.
+• Copy, Move messages – The IMAP4 Server MTM supports copying and moving messages between folders on the IMAP4 server and between the IMAP4 server and local folders.
+• Delete messages – The IMAP4 Server MTM will mark the email as deleted on the server; however it will not be deleted until the IMAP4 Server MTM disconnects from the server.
+• Folders – The IMAP4 Server MTM will allow folders to be subscribed, unsubscribed, renamed, copied, moved, and created within the IMAP4 service. Subscribing to a folder means that it will be visible to the user and synchronised with the remote server. The inbox is always subscribed.
+• Offline operations – When the IMAP4 Server MTM receives a request to copy, move, or delete and is not connected to an IMAP4 email server the Server MTM will store the operation in the CMsvStore of the entry being modified and perform the operation on the next connection to the email server.
+• Disconnect – When disconnecting from a remote email server the IMAP4 MTM will run any pending offline operations stored. After the disconnect operation completes the Server MTM will allow the message server to delete and unload the Server MTM by setting the CommandExpected API to false.
+
+3.2.9.3.6 SMTP MTMs
+The SMTP MTMs provide functionality to send email messages. They are made up of the Client MTM that is part of the imcm DLL and the Server MTM.
+3.2.9.3.6.1 Client MTM
+The SMTP Client MTM implements the standard Client MTM APIs including the functions required to allow clients of Send As to create email messages.
+3.2.9.3.6.2 Server MTM
+The SMTP MTMs provide functionality to send email messages; it interprets requests to copy entries to an SMTP service as a request to send those messages. In addition it responds to two extended commands via the StartCommand Server MTM interface. These commands are KSMTPMTMIsConnected that responds with whether the Server MTM is currently connected to a remote SMTP server and KSMTPMTMSendOnNextConnection which performs the same operation as copying a selection of messages to an SMTP service. The only difference between the copy operation and the KSMTPMTMSendOnNextConnection operation is that the latter can be called without a selection of messages.
+When the Server MTM receives a request to send messages it builds a selection of messages consisting of the messages passed into the operation and any messages waiting in the outbox to be sent. To determine which messages in the outbox are waiting to be sent the SMTP server checks for messages that have the same service ID as the destination of the send operation and have a sending state of KMsvSendStateWaiting, KMsvSendStateScheduled or KMsvSendStateResend. This means that any request to send messages may result in more messages being sent than explicitly listed in the selection passed to the send operation.
+The Server MTM restores its settings from the SMTP service it has been asked to copy the messages to. Then it connects to the SMTP server using the CImTextServerSession class in the Email Server MTM Utilities, passing in the SMTP server address and TCP/IP port number from the SMTP settings. Then for each message to be sent the Server MTM uses the Email Server MTM utilities to generate an RFC2822 format message to send to the SMTP server, the RFC2822 text is generated on the fly as the data is sent to the SMTP server. If the SMTP server accepts the message to be sent then the Server MTM moves the message to the sent folder and sets its sending state to sent. If the SMTP server rejects the message then the Server MTM leaves the message in the outbox and sets the sending state to failed. Separate emails are generated for BCC recipients to ensure that the SMTP server doesn’t incorrectly include BCC recipients in emails sent to addresses in the To and CC fields of the email.
+3.2.9.3.7 Autosend
+The Autosend component is an executable that is kicked off by the POP3 and IMAP4 Client MTMs if the send on next connection setting is set. This executable will just make a request to the SMTP Server MTM to send messages associated with the SMTP service related to the POP3 or IMAP4 service, wait for the operation to finish and then exit.
+3.2.10 Messaging / MMS APIs
+The MMS module has been removed from v9.0 and onwards.
+3.2.10.1 Key Internal Relationships and Dependencies
+
+Figure 21 MMS Internal Dependencies
+3.2.10.2 API Purpose - Further Elaboration
+3.2.10.2.1 MMS Overview
+The MMS MTM provides functionality for creating, accessing, sending and receiving MMS messages. Messages are sent and received without the client application needing to open or close any kind of session. The management of the MMS session is handled entirely within the MTM.
+MMS clients are alerted when a new message is available for download via the WAP Push mechanism. A WAP push watcher is provided to handle these notifications. After the notification the message can be downloaded over WSP or HTTP. Messages are sent by posting the data over WSP or HTTP. The Symbian MMS implementation can handle sending or receiving MMS message over either protocol.
+MMS messages are based on the MIME format but are binary encoded using WSP. Note that MMS messages are encoded in this way even if they are posted over HTTP as opposed to WSP. The codec component is responsible for this encoding and decoding.
+3.2.10.2.2 MMS Utilities
+3.2.10.2.2.1 Key External Relationships and Dependencies
+
+Figure 22 MMS Utilities External Dependencies
+The MMS utilities provide the message and settings encapsulation classes. The MMS settings and messages are stored in the message store, the MMS utilities provide the interfaces to access this data.
+3.2.10.2.2.2 Settings
+The settings functionality provided by the MMS utilities allows the messaging client to persist MMS settings in the message store. Supported settings include:
+ MMSC (MMS server) address
+ WSP or HTTP transport
+ Autofetch messages on notification
+ Preferred IAP for the MMS network connection
+The settings functionality is also used by the server MTM to retrieve the settings prior to message sending or fetching.
+3.2.10.2.2.3 Message Encapsulation
+The message classes provide the message access functionality. Messages can be created, stored, restored and read using these classes. Functionality includes:
+ Adding media objects to the message
+ Enumerating through media objects
+ Adding recipients, subject line, etc. to a message
+ Adding other headers to the message, e.g. expiry date
+ Finding the appropriate media object for a given URI in the SMIL part (URI resolving)
+The message data is stored in the message store using one entry per message regardless of the number of media objects added to the message. This is preferable to using multiple message entries as it is faster and uses less disk space.
+Most of the message access code is common whether it is being used on the client or server side, however some parts of it are specific. For this reason it is essential that the appropriate client or server side CMmsMessage derived class is used.
+3.2.10.2.3 MMS Watcher
+3.2.10.2.3.1 Key External Relationships and Dependencies
+
+Figure 23 MMS Watcher External Dependencies
+
+The MMS watcher plug-in is responsible for intercepting incoming MMS notifications and delivery reports then taking the appropriate action. It is implemented as a WAP Push watcher plug-in.
+When an MMS notification is received an MMS entry is created in the inbox using the MMS utilities. At this point the entry has its incomplete flag set. If the settings have the autofetch option selected then the MMS watcher initiates the fetch operation via the MMS client MTM.
+If a delivery report is received then the delivered flag is set on the appropriate sent message. If an outgoing message was sent to several recipients then there will be several delivered flags. A delivery report from each recipient will set the appropriate delivered flag.
+3.2.10.2.4 MMS Client MTM
+3.2.10.2.4.1 Key External Relationships and Dependencies
+
+Figure 24 MMS Client MTM Dependencies
+As with most other MTMs the MMS client MTM provides access to the server MTM functionality for messaging clients. It also implements the Send-As interface and reply and forward functionality.
+3.2.10.2.4.2 Send-As Implementation
+The Client MTM Send-As interface is implemented in the MMS Client MTM. The implementation differs slightly from other MTMs because additional presentation content may be generated depending on the media objects that are added. When simple combinations of images, sounds and text are added a SMIL presentation is generated to link them together. This is preferable to simple adding the objects as attachments where some clients render them as a list of files and others fail to render them at all.
+The SMIL data is constructed using templates stored in resource files, the GMXML (SMIL) composer is not used.
+3.2.10.2.4.3 Reply / Forward
+The Client MTM can be used to create replies to received messages or to create forwarded responses. The reply and forwarding operations are performed asynchronously.
+3.2.10.2.5 MMS Server MTM
+3.2.10.2.5.1 Key External Relationships and Dependencies
+
+Figure 25 MMS Server MTM Dependencies
+The Server MTM is the most complicated part the MMS implementation. It handles all of the state information required to send or fetch MMS messages. It is also responsible for managing the HTTP or WSP session and the connections to the phone network.
+3.2.10.2.5.2 Operations
+All MMS server MTM functionality is encapsulated in operations. An operation consists of the setup of a session, the sending, fetching and acknowledgements when appropriate, it then closes the session. The messaging client initiates an operation with a single call to the Client MTM, there is no need for the messaging client to explicitly establish the session or to know about the internal states. However, these internal states are available to the messaging client via the progress structure if this level of user feedback is required.
+Two types of operation are supported, background and foreground:
+A maximum of one foreground operation can be running at any one time. The messaging client can poll the server MTM for the progress of a running foreground operation, likewise it can cancel it if necessary.
+A background operation does not support progress information and can not be cancelled by the messaging client. It is possible to initiate background operations even if other background or foreground operations are pending. However, background operations are queued and a maximum of one will actually be running at any one time.
+The MMS watcher uses a background operation to perform automatic fetching. While the background autofetch is occurring it is still possible to start a foreground operation (such as sending a message) if required.
+3.2.10.2.5.3 Session and Connection Management
+The server MTM uses the HTTP Transport Framework to enable the HTTP or WSP session. HTTP or WSP can be selected at runtime by selecting the appropriate option in the settings. The server MTM is responsible for reading any HTTP proxy details from the CommDB and passing it to the HTTP framework. See the http transport framework architectural description for more information on recognisers [R5]
+The server MTM is also responsible for managing the connection to the phone network. Connections are opened when required using the RConnection mechanism, multi-homing is supported provided that the underlying HTTP framework transport plug-in also supports it.
+3.2.10.2.6 MMS Codec
+The MMS Server MTM is in charge of the state transitions, connection, session, the actual posting and fetching of the data from them, however it does not encode or decode the MMS PDUs. The encoding and decoding is performed by the MMS Codec.
+For decoding the Server MTM passes the Codec the MMS PDU data in a descriptor for processing. If the PDU contains a received MMS message then the message entry is updated with the decoded MMS data.
+For encoding the Server MTM passes a reference to the message store entry containing the un-encoded MMS data. The Codec then encodes it and returns the PDU to the Server MTM in a descriptor.
+
+
+3.2.11 Messaging / BIO APIs
+3.2.11.1 Key Internal Relationships and Dependencies
+
+Figure 26 BIO Message Internal Dependencies
+3.2.11.1.1.1 Key External Relationships and Dependencies
+
+Figure 27 Bio Parser External Dependencies
+
+3.2.11.2 API Purpose - Further Elaboration
+3.2.11.2.1 BIO Overview
+The BIO messaging components have been designed to unify and simplify the way in which system messages are processed. In this context ‘system messages’ refers to messages received on the device which are intended to update some attribute(s) on the system as opposed to being presented to the user. Examples of these types of messages include vCards which are parsed and then displayed to the user and when accepted modify the users contact database and OTA configuration messages which are again parsed before display to the user and if accepted create email accounts or internet access points.
+The BIO messaging components can be broken down into three groups:
+1) The BIO MTM - To initiate the parsing and processing of BIO messages
+2) The BIO Database - Maps port numbers, MIME types, etc. to bio types in order to identify the type of incoming BIO messages.
+3) The BIO Parsers - To parse and process the BIO message payload
+BIO messages are not receive by the bio messaging framework, they come over other message transports for example see section 3.2.6.3.1 on the SMS watchers which describes how the SMS watchers receive bio messages and use the bio framework to tag the messages with the correct bio id.
+3.2.11.2.2 BIO MTM
+The BIO client MTM is called by the messaging client to parse or process a BIO message that has been saved in the message store. It is the responsibility of a BIO watcher to save the BIO message with the BIO flag and the appropriate BIO type set.
+The BIO client MTM does very little, its primary task is to pass on the messaging client request to the server MTM. Two operations are supported, parse and process.
+The messaging client is expected to initiate the parsing of the BIO message before processing it. The parsing step involves analysing the data and storing it in a form that can be displayed to the user via the BIO message viewer.
+Once the message has been parsed the messaging client can initiate the processing of the message.
+The BIO server MTM is responsible for deferring the parsing and processing to the appropriate BIO parser. The behaviour for the parsing and processing steps varies between parsers. See the BIO Parsers section for more information.
+The bio MTM does not support sending messages and therefore does not support reply / forwarding messages. For bio messages sending / reply etc. is supported by the particular MTM that the message is sent over, for example SMS.
+3.2.11.2.3 BIO Database
+The BIO database is used to identify the type of BIO messages. It maps message attributes such as port number, MIME type or leading string to a BIO type. These are attributes are then used by clients of the bio framework to know what ports to listen for messages on. For example the SMS watchers use the leading string to wait for SMS messages that start with that string and when storing those messages in the inbox tag them with the bio id associated with that leading string. See the SMS watcher section 3.2.6.3.1 for more examples of how the BIO database can be used.
+3.2.11.2.4 BIO Parsers
+The BIO parsers are plug-ins for parsing and processing incoming BIO messages. They are invoked by the BIO Server MTM depending on the BIO type of the message being processed. Each BIO parser implements two functions, ParseL and ProcessL. The level of functionality varies between parsers. Some parsers update the final repository with the received data, e.g. WAPP updates the CommDB with the received settings. Some parsers simply save the data in an unparsed state for processing by another component, this secondary parsing is not part of the BIO framework and must be initiated by the messaging client. An example is when GFP saves vCard data as a file as opposed to updating the contacts database, the UI must then invoke the Versit parser to parse the vCard and commit it to the contacts database.
+3.2.11.2.4.1 Generic File Parser (GFP)
+The generic file parser can be used to identify and save a variety of BIO data types, e.g. vCards and vCals. The Generic File Parser does not process the data, it simply saves it in the message store for processing by another component. The file is saved as an attachment of the message entry that was parsed.
+3.2.11.2.4.2 Nokia/Ericsson OTA Parser (WAPP)
+The WAPP parser decodes Nokia/Ericsson OTA messages and updates CommDB to reflect the received settings.
+3.2.11.2.4.3 Nokia Smart Message Internet Access Parser (IACP)
+The IACP parser decodes Nokia Smart Messages and updates the CommDB and messaging settings where appropriate.
+3.2.11.2.5 BIF Files and Utilities
+The BIF files encapsulate the information required for identifying BIO messages, these details may include the expected port number, MIME type or leading string. Different BIO watcher will use different information from these files, for an example see the 3.2.6.3.1. The information can be retrieved from the BIF files by using the BIF utilities. Generally BIO aware clients will access this information via the BIO database. BIF files are resource files previous to the v6.1 release they were binary files generated by biftool.exe.
+3.2.11.2.6 Platform Security Compliant Messaging / BIO APIs
+In the platform security model the BIO parsers are run in the client space rather than in the message server space, as is done in the non-platform secure model. If the BIO parsers are run in the message server space, it allows a client process to gain the capabilities of the message server. IPC policing can protect the message server from this.
+Also, for the message server to be able to load any BIO parser it would need more capabilities than it really requires. By running the BIO parsers in the client space, both these issues are solved. The client process must be trusted with the necessary capabilities to run the specified BIO parser.
+The BIO registry files are located in the \resource\messaging\bif read-only directory. All BIO parser DLLs are located in the \sys\bin protected directory.
+
+Figure 26 BIO Message Dependencies (v9.0)
+The BIO client MTM is responsible for loading the BIO database and BIO utilities to handle parse/process requests from clients.
+The BIO registry files no longer identify the BIO parsers DLLs via their UID – the registry file must use the BIO parser DLL name to identify them.
+3.2.12 Messaging / OBEX MTM APIs
+3.2.12.1 Key Internal Relationships and Dependencies
+
+Figure 28 OBEX Internal Dependencies
+3.2.12.2 OBEX MTM Overview
+The OBEX MTM offers simple IR and Bluetooth beaming functionality. It provides an API that is consistent with other MTMs so that the underlying OBEX APIs do not need to be used directly for beaming applications. The OBEX MTM does not provide OBEX receiving functionality, in order to receive OBEX data the underlying OBEX APIs must be used directly.
+3.2.12.2.1 OBEX MTM
+The OBEX MTM is split into three parts. OBEX MTM DLLs, IR MTM DLLs and Bluetooth MTM DLLs. The OBEX MTM DLLs can not be used on their own they provide the base OBEX MTM functionality for the derived IR and Bluetooth MTMs.
+There are two APIs that can be used to create OBEX messages:
+1) The Send-As API
+2) Linked attachments by filename
+The Send-As API provides an interface consistent with other MTMs, however it requires all attachments to be copied into the message store before they can be sent, this is often undesirable for beaming applications because it is wastes disk space. For this reason a second API is provided that allows attachments to be linked to outgoing messages by filename, when this API is used there is no need to copy the attachments to the message store.
+Unlike many other MTMs after OBEX tries to send a message it is deleted from the outbox whether the sending succeeds or fails.
+3.2.12.2.1.1 OBEX MTM Key External Dependencies
+
+Figure 29 OBEX External Dependencies
+3.2.12.2.2 IR MTM
+The bulk of the OBEX MTM functionality is provided by the OBEX MTM DLLs, the IR MTM itself just sets up the parameters.
+3.2.12.2.2.1 IR MTM Key External Dependencies
+
+Figure 30 IR MTM Dependencies
+3.2.12.2.3 Bluetooth MTM
+The bulk of the OBEX MTM functionality is provided by the OBEX MTM DLLs, the Bluetooth MTM just subclasses from the OBEX MTM and sets up Bluetooth specific parameters.
+3.2.12.2.3.1 Bluetooth MTM Key External Dependencies
+
+Figure 31 Bluetooth MTM Dependencies
+3.2.12.2.4 OBEX MTM Utils
+The OBEX MTM Utils provide utility functionality used by the other OBEX MTM DLLs. The two main areas of functionality provided by this component are:
+1) Filename linking functionality
+2) Bluetooth SDP lookup
+The filename linking functionality is provided in the utilities because linked files must be added by the client side during message creation and need to be read on the server side during sending.
+
+3.2.12.2.5 Platform Security Compliant Messaging / OBEX MTM APIs
+From v9.0 and onwards the service settings of all the derived OBEX MTMs are stored in the Central Repository. The OBEX message is stored in the message store as an attachment – from v9.0 and onwards the Attachment API is used to attach the OBEX message.
+
+3.2.13 Messaging / GMXML APIs
+3.2.13.1 Key Relationships and Dependencies
+
+Figure 32 GMXML Dependencies
+3.2.13.2 Overview
+The GMXML component provides simple XML DOM parsing and validation functionality. It is intended for parsing XML that might be needed in messaging applications, specifically SMIL parsing for MMS rendering. It is not a general purpose XML parser and will not be suitable for some applications, e.g. browsing.
+3.2.13.2.1 GMXML DOM
+The DOM implementation is fit for purpose for SMIL rendering but differs from the standard DOM design in several respects, e.g. attributes are not stored as discrete nodes, for performance reasons they are stored with the element.
+The DOM tree classes are all derived from nodes. Implemented node types include elements, text and comments. The type of each element is stored as a descriptor as opposed to an enum. This is less efficient than storing it as an enum but provides maximum flexibility when dealing with unknown element types.
+Nodes are linked together in a tree structure as might be expected in a DOM implementation. The tree structure exists on the heap.
+3.2.13.2.2 GMXML Parser and Composer
+3.2.13.2.2.1 Parser
+The parser takes XML input from a buffer or file and creates the corresponding DOM structure on the heap.
+The parser is capable of performing some basic validation. In order to validate against a DTD a class that implements the GMXML DTD interface is required. The DTD interface specifies several functions that provide the required validation, e.g. one of the functions determines if a given attribute is valid for a given element. An instance of the DTD class should be passed into the parser when validation is required but can be omitted if no validation is needed.
+3.2.13.2.2.2 Composer
+The composer takes a DOM tree and generates XML output from it. The XML output is written to a file.
+3.2.13.2.3 GMXML SMIL DTD (Validator)
+The SMIL DTD validator class is an implementation of the DTD validator interface. It implements several simple functions that provide the information required to validate SMIL data. An instance of the SMIL DTD validator should be passed into the parser if SMIL validation is required.
+4 Security
+4.1 Data caging
+For data storage in the pre-platform security compliant architecture, refer to section [3.2.1.3.2]
+For the data caging in the platform security compliant architecture of v9.0 and onwards, refer to section [3.2.1.3.3]
+4.2 Backup and restore
+The message server registers the index file with the backup server. When informed about a backup/restore it releases the index file, sending events to messaging clients informing them that the message store is unavailable. When informed it can open the index file again, it checks the time stamp on the index file; if it has changed since the file was released it reloads the index file. If the newly restored index file is found to be corrupt it is deleted and a new message store is created. See the section on page 14 for details on how the message server handles corrupt stores. The client performing the restore should always wipe the existing message store before starting to copy the message store from the backup to the device.
+4.3 Capability ranges
+In the platform security compliant architecture of v9.0 and onwards, the capabilities allocated to messaging sub-systems are as listed in following table.
+4.3.1 Capabilities granted to executables
+The following table lists the executables and their capabilities and also gives a basic example for having the required capability.
+
+Executable Capability Rationale (basic example of capability requirement)
+msexe.exe ProtServ ProtServ is required to allow the msexe.exe to start a protected server. This stops processes without ProtServ from starting a server pretending to be the message server
+ ReadDeviceData ReadDeviceData is needed to able to read service settings
+ WriteDeviceData WriteDeviceData is needed to able to write service settings
+ NetworkServices NetworkServices capability is needed to access network transports (SMS, POP3, SMTP, IMAP4).
+ LocalServices LocalServices is needed to be able to access IR and Bluetooth
+ ReadUserData ReadUserData is needed to be able to read user data (e.g. service settings).
+watcher.exe ReadDeviceData ReadDeviceData is needed to able to read service settings
+ WriteDeviceData WriteDeviceData is needed to able to write service settings
+ NetworkServices NetworkServices capability is needed to access network transports (SMS).
+ LocalServices LocalServices capability is needed for the plug-ins to access IR and Bluetooth
+ ReadUserData ReadUserData is needed to be able to read user data
+ WriteUserData WriteUserData is needed to be able to write user data
+autosend.exe ReadUserData ReadUserData capability is needed to be able to read data from Outbox and SMTP server MTM.
+ WriteUserData WriteUserData capability is needed to be able to write data in Outbox and SMTP server MTM.
+ NetworkServices NetworkServices capability is needed to access network transports (SMS, POP3, SMTP, and IMAP4).
+ LocalServices LocalServices capability is needed to access the IR and Bluetooth
+SchSend.exe ReadDeviceData ReadDeviceData is needed to able to read settings data
+ NetworkServices NetworkServices capability is needed to access the network transports (SMS, POP3, SMTP, and IMAP4).
+ LocalServices LocalServices is needed to be trusted by other MTM
+ ReadUserData ReadUserData is needed to be able to read user data.
+ WriteUserData WriteUserData is needed to be able to write user data.
+SendAs.exe ReadDeviceData ReadUserData is needed to be able to read data in Outbox.
+ WriteDeviceData WriteUserData is needed to be able to write data in Outbox.
+ NetworkServices NetworkServices capability is needed to access the network transports (SMS, POP3, SMTP, and IMAP4).
+ LocalServices LocalServices is needed to be able to access IR and Bluetooth
+
+4.3.2 Capabilities granted to DLLs
+The assigned Platform Security attributes for DLLs within messaging are outlined in the following table.
+DLL Capability
+bifu.dll All –TCB
+bioc.dll All –TCB
+biodb.dll All –TCB
+bios.dll All –TCB
+biowatcher.dll same as watcher.exe
+biut.dll All –TCB
+cbcp.dll All –TCB
+enp.dll All –TCB
+gfp.dll All –TCB
+iacp.dll All –TCB
+nbswatcher.dll same as watcher.exe
+cdmanbswatcher.dll same as watcher.exe
+CdmaSocketWatcher.dll same as watcher.exe
+VMNWatcher.dll same as watcher.exe
+WEMTWatcher.dll same as watcher.exe
+WMTWatcher.dll same as watcher.exe
+WPTWatcher.dll same as watcher.exe
+wapp.dll All –TCB
+wapwatcher.dll same as watcher.exe
+smildtd.dll All –TCB
+xmldom.dll All –TCB
+xmlparser.dll All –TCB
+smiltranslator.dll All –TCB
+imcm.dll All –TCB
+imps.dll same as msexe.exe
+imut.dll All –TCB
+msgs.dll All –TCB
+msgurlrec.mdl same as AppArc.exe (once it exists; eiksrv in meantime)
+mtur.dll All –TCB
+pops.dll same as msexe.exe
+schsend.dll All –TCB
+send.dll All –TCB
+smcm.dll All –TCB
+smcm_gsm.dll Synonym for smcm.dll
+smcm_cdma.dll Synonym for smcm.dll
+smss.dll same as msexe.exe
+smss_gsm.dll Synonym for smss.dll
+smss_cdma.dll Synonym for smss.dll
+smts.dll same as msexe.exe
+btcmtm.dll All –TCB
+btsmtm.dll same as msexe.exe
+irc.dll All –TCB
+irs.dll same as msexe.exe
+obexclientmtm.dll All –TCB
+obexmtmutil.dll All –TCB
+obexservermtm.dll same as msexe.exe
+
+The reason for setting a high capability to the DLLs is to make it possible for almost anyone to link to them. Although a DLL may have capabilities ALL-TCB (All minus TCB), its real capability is limited by the process which loads the DLL.
+4.3.3 Capabilities required to use the subsystem
+The message subsystem needs to be protected against malicious clients. The following table shows the key capabilities required to do related activities in different components.
+
+Component Related Activity Required Capability and SID
+Message server Create message in local folder No capability required
+ Create message in Outbox ReadUserData, WriteUserData and MTM specific capabilities
+ Access client MTM ReadUserData, WriteUserData and MTM specific capabilities
+Watcher Allow plug-ins to wait on events (e.g. arrival of SMS) Watcher always polices if the client capabilities are trusted by the watcher framework, else it will not be loaded
+Plug-ins or clients using watcher need the same capabilities as watcher.exe to be able to be loaded by watcher.
+Autosend Send messages in background NetworkService or LocalService required by the message type
+SchSend Scheduling of operations (e.g. sending SMS) SchSend always polices to see if the process was started by the Task Scheduler – if not the process terminates without performing any of the scheduled tasks. Also, the SchSend verifies that only itself and the message server created the scheduled tasks. If this is not the case, SchSend does not performing the scheduled tasks.
+SendAs Create message Draft, move it to Outbox, and send message WriteDeviceData or WriteUserData and other capability required by the message type
+
+5 Further Information
+5.1 References
+No. Document Reference Version Description
+R1 messaging_functional_specification.doc 0.6 Messaging Functional description
+R2 SGL.GT0143.161_App-Framework_Architectural_Description.doc 1.0 App-Framework Architectural Description
+R3 NBProtocols_Subsystem_Architectural_Description.doc 0.2 NBProtocols Architectural Description
+R4 WAP-stack_architectural_analysis.doc 1.0 WAP stack architectural analysis
+R5 HTTP Transport Framework Architectural Description.doc 1.1 HTTP Transport Framework 1.1 Architectural Description
+5.2 Open Issues
+The following issues need to be resolved before this document is completed:
+1. Top-level architecture diagram showing the framework and plug-ins should be added to overview section.
+2. Message store section should talk about removable media.
+3. Define "Message Server Client API" and "Messaging Client API" in the glossary, and ensure it is consistently used in the diagrams
+4. Add a sequence diagram for receiving a vCard over SMS and integrating it into contacts
+5. Add a sequence diagram for sending an SMS
+6. Add a sequence diagram for synchronising a POP3 mail box
+7. Add a sequence diagram for connecting to an IMAP4 mail box and downloading a message
+8. Capability table should be updated after the implementation of server e.g. message server
+9. Sequence diagram may need to be changed to show secured platform operation
+10. In section [3.1.1.4] the server SendAsV2 to find a correct name
+11. Section 3.2.1.3.3.1 Data Caging file 'Mtm Registry v2'may need a correct name
+12. Breakdown diagram showing all DLL, exes, apps in the messaging subsystem for both the pre-v8.0 and post v9.0 in section[3.2]
+13. Needs to say more about how the capabilities are policed and the algorithms used for different operations
+14. The dependecy between the message server and the central repository need to be listed in the email, SMS and OBEX diagrams (e.g. message store)
+15. Section 3.2.1.2 - figure 3 - Central Repository also get used by the Message server, or server MTMs (e.g. POP3), to retrieve account settings the path, required DLL and description are not given
+16. Section 4.3.3 title can be Police requirement of the sub-system, add extra column for SID in the table and list the use of SID. For example SchSend checks for Task Scheduler SID
+
+
+5.3 Glossary
+The following technical terms and abbreviations are used within this document.
+Term Definition
+BIO
+Bearer Independent Object Smart messages e.g. vCards, vCals, and WAP provisioning messages. These can currently be received via the WAP stack, SMS stack, Bluetooth or Infrared.
+BIO Type UID that represents the content type of a BIO Message.
+Message Centre Application that displays list views of messages to the user, allowing the user to perform operations such as copying messages, sending messages creating new messages etc.
+Message Viewer Application for viewing a message.
+Message Editor Application for creating or editing a message
+Message Server Symbian OS Server that handles request to modify the Message Store
+Message Store Store of messages and related information kept in the file system on a Symbian OS device.
+Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
+Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
+Global Inbox A standard folder under the local service which is used to store incoming messages like SMS MMS etc. as opposed to an IMAP4 Inbox which would be under an IMAP4 service and is a representation of the Inbox on an IMAP4 email server.
+Central Repository centralised and secure storage facility for application settings
+OBEX Object exchange protocol, used to send objects such as vCards or files between devices via infrared or Bluetooth.
+GMXML XML parser / generator for use with SMIL formatted messages.
+UID Unique Identifier, a 32 bit number allocated from a registry owned by Symbian
+IPC Inter Process Communication
+MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
MTM Registry A list of currently installed MTMs maintained by the message server.
TLS Transport Layer Security, provides encryption of a TCP/IP socket.
M-HTML Standard for including HTML in MIME email messages see http://www.ietf.org/rfc/rfc2557.txt
@@ -32513,15 +25387,15 @@
Message Editor Application for creating or editing a message
Message Server Symbian OS Server that handles request to modify the Message Store
Message Store Store of messages and related information kept in the file system on a Symbian OS device.
-Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
-Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
+Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
+Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
Global Inbox A standard folder under the local service which is used to store incoming messages like SMS MMS etc. as opposed to an IMAP4 Inbox which would be under an IMAP4 service and is a representation of the Inbox on an IMAP4 email server.
Central Repository centralised and secure storage facility for application settings
OBEX Object exchange protocol, used to send objects such as vCards or files between devices via infrared or Bluetooth.
GMXML XML parser / generator for use with SMIL formatted messages.
UID Unique Identifier, a 32 bit number allocated from a registry owned by Symbian
IPC Inter Process Communication
-MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
+MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
MTM Registry A list of currently installed MTMs maintained by the message server.
TLS Transport Layer Security, provides encryption of a TCP/IP socket.
M-HTML Standard for including HTML in MIME email messages see http://www.ietf.org/rfc/rfc2557.txt
@@ -33531,15 +26405,1033 @@
Message Editor Application for creating or editing a message
Message Server Symbian OS Server that handles request to modify the Message Store
Message Store Store of messages and related information kept in the file system on a Symbian OS device.
-Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
-Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
+Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
+Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
Global Inbox A standard folder under the local service which is used to store incoming messages like SMS MMS etc. as opposed to an IMAP4 Inbox which would be under an IMAP4 service and is a representation of the Inbox on an IMAP4 email server.
Central Repository centralised and secure storage facility for application settings
OBEX Object exchange protocol, used to send objects such as vCards or files between devices via infrared or Bluetooth.
GMXML XML parser / generator for use with SMIL formatted messages.
UID Unique Identifier, a 32 bit number allocated from a registry owned by Symbian
IPC Inter Process Communication
-MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
+MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
+MTM Registry A list of currently installed MTMs maintained by the message server.
+TLS Transport Layer Security, provides encryption of a TCP/IP socket.
+M-HTML Standard for including HTML in MIME email messages see http://www.ietf.org/rfc/rfc2557.txt
+MIME Specification for the format of email message bodies see http://www.ietf.org/rfc/rfc1341.txt
+RFC2822 The standard format for internet mail messages see http://www.ietf.org/rfc/rfc0822.txt
+SMTP Simple Mail Transport Protocol
+SID Secure Identification
+IMAP4 Internet Mail Access Protocol
+POP3 Post Office Protocol Version 3
+NBS Narrow Band Socket, in the messaging context this refers to the socket that is used to talk to the SMS stack for receiving and sending SMS messages
+SMS Short Message Service
+MMS Multimedia Message Service
+WAP Wireless Application Protocol
+WSP WAP Session Protocol
+HTTP Hypertext transfer protocol
+PDU Protocol Data Unit. This is the encoded form of SMS and MMS messages.
+Versit A consortium that defined standard formats for things like contacts (vCard) and calendar entries (vCals)
+SDP Service Discovery Protocol. A Bluetooth protocol that allows an applications to discover which services are available and to determine the characteristics of the services.
+SMIL Synchronized Multimedia Integration Language. Presentation language that is commonly used to define the contents of an MMS message.
+XML Extensible Mark-up Language
+DOM Document Object Model
+DTD Document Type Definition, a schema that defines the structure of an XML document.
+ESTORE Symbian OS component that provides stream based storage. Messaging uses the Permanent file store provided by ESTORE to store its index entries.
+Appendix A - Example Sequence Diagrams
+A.1 Copy to a Remote Service
+
+Figure 33 Sequence Diagram Showing Copying to a Remote Service
+Figure 33 shows a client copying a message to a remote service using the Messaging Client API. The message server then delegates the copy to the SMTP Server MTM. The Server MTM interprets the request as a request to send the message so it opens a connection to a remote SMTP server and sends the message. While the message is being sent the client can retrieve progress information from the CMsvOperation object that was returned by CMsvEntry::CopyL. The dark grey IPC line represents the split between the objects running in the client’s process space on the left and the message server’s process on the right.
+There are four basic steps:
+1. The client opens session with Message Server and creates a CMsvEntry set on the global outbox,
+2. The client then requests an asynchronous copy from the outbox to the SMTP service, a CMsvOperation object is returned. The message server loads the SMTP Server MTM and delegates the copy operation to it.
+3. The client requests progress from the CMsvOperation object, this request is passed through to the SMTP Server MTM. The client may repeat this step multiple times.
+4. The Server MTM finishes sending message. It moves the message to sent folder and completes the message server’s request. The message server completes the CMsvOperation object, which requests the final progress from the message server. The server returns the final progress and deletes the Server MTM. The CMsvOperation then completes the client’s original request.
+This diagram hides all of the internal working of the SMTP Server MTM, for information on this see below.
+A.2 SMTP Session
+
+Figure 34 Sequence Diagram Showing a SMTP Session
+Figure 34 shows the operation of the SMTP Server MTM after a request has come from the message server to copy a message to the SMTP service.
+1. SMTP Server MTM gets the request from the message server, it will build a selection of messages consisting of the union of the selection of messages passed in and the messages in the outbox that are associated with this SMTP service and are ready to be sent. The chain of classes are constructed, and a request is passed to networking to connect to the remote SMTP server, details of the server name and port are retrieved from the settings stored in the SMTP service entry.
+2. The component waits for the SMTP server to respond with a greeting indicating it is willing to talk, then sends EHLO to the server and waits for the response detailing the capabilities of the Server. After this step there could set steps to start using TLS and or SMTP AUTH depending on the SMTP settings.
+3. CImSmtpSession calls back into CMsgOutboxSend to retrieve the next message to be sent, then constructs a CImSmtpFile object to handle sending, for details on the sending see SMTP Email Send. When sending the email has completed the CImSmtpFile object is deleted.
+4. CImSmtpSession calls back into CMsgOutboxSend to retrieve the next message which returns saying there are no more messages. CImSmtpSession sends QUIT to the SMTP server and completes CMsgOutboxSend. CMsgOutboxSend deletes CImSmtpSession which tears down the connection to the SMTP server; it then completes the SMTP Server MTM. The Server MTM will then complete the message server and be deleted.
+A.3 SMTP Email Send
+
+Figure 35 Sequence Diagram Showing SMTP Transactions during Email Send.
+Figure 35 shows a CImSmtpFile object sending an email message to an SMTP server.
+1. Construct a CImSendMessage object, part of the imut component. Reset the SMTP Server
+2. Read address information from the CImHeader object stored in the message store, send address information to SMTP server.
+3. Use CImSendMessage object to read the message from the message store and generate RFC2822 message line by line. Send each line to the server as it is generated.
+4. Complete and send the message by sending a full stop to the SMTP server
+
+
+
+
+Messaging Symbian OS v7.0s, v8.0, v8.1, v9.0, v9.1 Architectural Description
+
+Status: Issued
+Team/Department : Messaging / Content & Messaging
+
+Contents
+1 INTRODUCTION 6
+1.1 PURPOSE AND SCOPE 6
+2 SUBSYSTEM OVERVIEW AND BACKGROUND 6
+3 MESSAGING ARCHITECTURE AND APIS 7
+3.1 SUBSYSTEM COMPONENTS 7
+3.1.1 Framework components 7
+3.1.1.1 Message Server and MTM architecture 7
+3.1.1.2 Schedule Send 7
+3.1.1.3 SendAs Version 1 7
+3.1.1.4 SendAs Version 2 7
+3.1.1.5 Watcher Framework 8
+3.1.1.6 Message URL Handler 8
+3.1.1.7 Bio Message Framework 8
+3.1.2 Plug-ins 8
+3.1.2.1 SMS 8
+3.1.2.2 CDMA SMS 8
+3.1.2.3 Email 9
+3.1.2.4 OBEX 9
+3.1.2.5 MMS 9
+3.1.2.6 GMXML 10
+3.1.2.7 Bio Message Plug-ins 10
+3.1.2.8 PCMTM 10
+3.1.2.9 Fax 10
+3.2 GENERAL DESCRIPTION 11
+3.2.1 Messaging / Message Server and MTM Architecture APIs 11
+3.2.1.1 Key Internal Relationships and Dependencies 11
+3.2.1.2 Key External Relationships and Dependencies 12
+3.2.1.3 API Purpose - Further Elaboration 13
+3.2.1.3.1 Message Store 13
+3.2.1.3.2 Data File Storage (pre - v9.0) 15
+3.2.1.3.3 Platform Security Compliant Message Store 16
+3.2.1.3.4 How message centres display the message store 17
+3.2.1.3.5 Message Type Module Architecture 19
+3.2.1.3.6 Message Server Client API 21
+3.2.2 Messaging / Send As APIs 22
+3.2.2.1 Key Relationships and Dependencies 22
+3.2.2.2 API Purpose - Further Elaboration 22
+3.2.2.2.1 SendAs API (pre – v9.0) 22
+3.2.3 Platform Security Compliant SendAs Server (v9.0 onwards) 23
+3.2.4 Messaging / Schedule Send APIs 24
+3.2.4.1 Key Relationships and Dependencies 24
+3.2.4.2 API Purpose - Further Elaboration 24
+3.2.4.2.1 Schedule Send 24
+3.2.5 Messaging / Watchers APIs 25
+3.2.5.1 Key Relationships and Dependencies 25
+3.2.5.2 API Purpose - Further Elaboration 25
+3.2.6 Messaging / Message URL Handler APIs 26
+3.2.6.1 Key Relationships and Dependencies 26
+3.2.6.2 API Purpose - Further Elaboration 26
+3.2.6.2.1 Message URL Handler Application 26
+3.2.6.2.2 Message URL Recognisers 27
+3.2.7 Messaging / SMS APIs 27
+3.2.7.1 Key Internal Relationships and Dependencies 27
+3.2.7.2 Key External Relationships and Dependencies 28
+3.2.7.3 API Purpose - Further Elaboration 28
+3.2.7.3.1 SMS Watchers 28
+3.2.7.3.2 SMS Client MTM 29
+3.2.7.3.3 SMS Utilities 29
+3.2.7.3.4 SMS Server MTM 30
+3.2.8 Messaging / CDMA SMS APIs 31
+3.2.8.1 Key Internal Relationships and Dependencies 31
+3.2.8.2 Key External Relationships and Dependencies 32
+3.2.8.3 API Purpose - Further Elaboration 32
+3.2.8.3.1 CDMA SMS Watchers 32
+3.2.8.3.2 CDMA SMS Client MTM 33
+3.2.8.3.3 CDMA SMS Utilities 33
+3.2.8.3.4 CDMA SMS Server MTM 33
+3.2.8.3.5 Configuration for using CDMA SMS MTM 34
+3.2.9 Messaging / Email APIs 35
+3.2.9.1 Key Internal Relationships and Dependencies 35
+3.2.9.2 Key External Relationships and Dependencies 36
+3.2.9.3 API Purpose - Further Elaboration 36
+3.2.9.3.1 Email Overview 36
+3.2.9.3.2 Email Client Utilities 37
+3.2.9.3.3 Email Server MTM Utilities 37
+3.2.9.3.4 POP3 MTMs 37
+3.2.9.3.5 IMAP4 MTMs 38
+3.2.9.3.6 SMTP MTMs 40
+3.2.9.3.7 Autosend 40
+3.2.10 Messaging / MMS APIs 40
+3.2.10.1 Key Internal Relationships and Dependencies 41
+3.2.10.2 API Purpose - Further Elaboration 41
+3.2.10.2.1 MMS Overview 41
+3.2.10.2.2 MMS Utilities 42
+3.2.10.2.3 MMS Watcher 43
+3.2.10.2.4 MMS Client MTM 43
+3.2.10.2.5 MMS Server MTM 44
+3.2.10.2.6 MMS Codec 45
+3.2.11 Messaging / BIO APIs 46
+3.2.11.1 Key Internal Relationships and Dependencies 46
+3.2.11.2 API Purpose - Further Elaboration 47
+3.2.11.2.1 BIO Overview 47
+3.2.11.2.2 BIO MTM 47
+3.2.11.2.3 BIO Database 48
+3.2.11.2.4 BIO Parsers 48
+3.2.11.2.5 BIF Files and Utilities 48
+3.2.11.2.6 Platform Security Compliant Messaging / BIO APIs 49
+3.2.12 Messaging / OBEX MTM APIs 50
+3.2.12.1 Key Internal Relationships and Dependencies 50
+3.2.12.2 OBEX MTM Overview 50
+3.2.12.2.1 OBEX MTM 50
+3.2.12.2.2 IR MTM 51
+3.2.12.2.3 Bluetooth MTM 51
+3.2.12.2.4 OBEX MTM Utils 52
+3.2.12.2.5 Platform Security Compliant Messaging / OBEX MTM APIs 52
+3.2.13 Messaging / GMXML APIs 52
+3.2.13.1 Key Relationships and Dependencies 52
+3.2.13.2 Overview 53
+3.2.13.2.1 GMXML DOM 53
+3.2.13.2.2 GMXML Parser and Composer 53
+3.2.13.2.3 GMXML SMIL DTD (Validator) 53
+4 SECURITY 54
+4.1 DATA CAGING 54
+4.2 BACKUP AND RESTORE 54
+4.3 CAPABILITY RANGES 54
+4.3.1 Capabilities granted to executables 54
+4.3.2 Capabilities granted to DLLs 55
+4.3.3 Capabilities required to use the subsystem 57
+5 FURTHER INFORMATION 59
+5.1 REFERENCES 59
+5.2 OPEN ISSUES 59
+5.3 GLOSSARY 60
+APPENDIX A - EXAMPLE SEQUENCE DIAGRAMS 62
+A.1 COPY TO A REMOTE SERVICE 62
+A.2 SMTP SESSION 64
+A.3 SMTP EMAIL SEND 66
+
+Table of Figures
+Figure 1 Where Messaging Lives 6
+Figure 2 MTM Relationships 11
+Figure 3 External Dependencies 12
+Figure 4 Message Store 13
+Figure 5 Series 60 Inbox List View 14
+Figure 6 Remote and Local Entries 14
+Figure 7 Email Message 15
+Figure 8 Series 60 Message Centre (Composed from 2 screen shots) 17
+Figure 9 UIQ Message Centre 18
+Figure 10 Messaging MTM Structure (light coloured components are part of messaging subsystem) 19
+Figure 11 Nokia 9210 Outbox List View 20
+Figure 12 SendAs Version 1 Dependencies 22
+Figure 13 SendAs Version 2 Dependencies 23
+Figure 14 Schedule Send Dependencies 24
+Figure 15 Watcher Dependencies 25
+Figure 16 Message URL Handler Dependencies 26
+Figure 17 SMS Internal Dependencies 27
+Figure 18 SMS External Dependencies 28
+Figure 19 CMDA SMS Internal Dependencies 31
+Figure 20 CDMA SMS External Dependencies 32
+Figure 19 Email Internal Dependencies 35
+Figure 20 Email External Dependencies 36
+Figure 21 MMS Internal Dependencies 41
+Figure 22 MMS Utilities External Dependencies 42
+Figure 23 MMS Watcher External Dependencies 43
+Figure 24 MMS Client MTM Dependencies 43
+Figure 25 MMS Server MTM Dependencies 44
+Figure 26 BIO Message Internal Dependencies 46
+Figure 27 Bio Parser External Dependencies 47
+Figure 26 BIO Message Dependencies (v9.0) 49
+Figure 28 OBEX Internal Dependencies 50
+Figure 29 OBEX External Dependencies 51
+Figure 30 IR MTM Dependencies 51
+Figure 31 Bluetooth MTM Dependencies 52
+Figure 32 GMXML Dependencies 52
+Figure 33 Sequence Diagram Showing Copying to a Remote Service 62
+Figure 34 Sequence Diagram Showing a SMTP Session 64
+Figure 35 Sequence Diagram Showing SMTP Transactions during Email Send. 66
+1 Introduction
+1.1 Purpose and Scope
+The Messaging Architectural Description details the architecture and APIs exposed by the Messaging Subsystem. This document does not attempt to list all functionality provided by the messaging subsystem. For details on the functionality provided and the specifications implemented by the messaging subsystem see the Messaging Functional Description [R1]. This document describes the general architecture of messaging subsystem. Information related to a particular release version is mentioned with relevant release number.
+2 Subsystem Overview and Background
+The Messaging Subsystem provides an application level API to handle the storage and transport of different message types. It sits between messaging applications and the lower level subsystems which messaging uses for storage and transmission of messages.
+
+Figure 1 Where Messaging Lives
+The message types that messaging currently supports are Email (POP3, IMAP4 & SMTP), SMS, MMS and OBEX. The set of supported message types is extensible at run time by the use of plug-in modules that are responsible for the transmission and storage of a particular message type. This means that the set of components shown communicating with the network cloud depend on the message types installed.
+3 Messaging Architecture and APIs
+3.1 Subsystem components
+The Messaging subsystem components can be split into two categories: those components that form the framework and those that plug into the framework to support specific message types. This section briefly describes each of the components, more detailed descriptions of the components and their dependencies can be found in later sections of this document.
+3.1.1 Framework components
+3.1.1.1 Message Server and MTM architecture
+The message server is the core component in the messaging subsystem. It provides the message store used to contain messages. The Message Type Module architecture also allows plug-ins to add support for new message types to the messaging subsystem.
+Component Description
+messaging\framework\serverexe Executable that links to the server component and starts the message server
+messaging\framework\server Contains classes that make up both the client and server side of the message server API.
+messaging\framework\mtmbase Base classes for the plug-ins that handle the various message types
+3.1.1.2 Schedule Send
+The Schedule Send component is an extension to the framework that provides support for scheduling of operations such as sending messages. Message type modules that wish to support this functionality can use these support components to implement scheduling. For example the SMS MTM uses this to allow scheduled sending of SMS messages.
+Component Description
+messaging\schedulesend\schedulesendmtm Base classes that handle functionality for message server plug-ins that wish to enable scheduling of sending messages.
+messaging\schedulesend\schedulesendexe Executable use to provide schedule send behaviour.
+3.1.1.3 SendAs Version 1
+This version of SendAs is supported in releases pre - v9.0. SendAs provides a high level API for applications that wish to include a “Send As” menu to allow users to send content via one of the message types supported by messaging. The application using the API does not have to be aware of the message type selected by the user. Note the API does not send the messages.
+Component Description
+messaging\sendas High level API to allow creation of messages.
+3.1.1.4 SendAs Version 2
+From v9.0 and onwards the SendAs has been replaced with client server architecture based SendAs server. The client server architecture enhances secured platform implementation. The SendAs server polices the client application. If it is not trusted with required capabilities the SendAs server will refuse the client access. The client MTM for the message type can send a message with user permission even if the client does not have the correct capabilities.
+Component Description
+messaging\sendAsV2 High level API to allow the creation and sending of messages
+
+3.1.1.5 Watcher Framework
+The watcher framework is a lightweight framework to allow plug-ins to wait on events. For example there is an SMS watcher that waits for incoming SMS messages and delivers them to the message store. The watcher framework will only load plug-ins from ROM.
+Component Description
+messaging\framework\watcher Executable that loads and runs watcher plug-ins.
+3.1.1.6 Message URL Handler
+Support for recognising messaging URLs (mailto:, sms:, fax:, mms:), and then launching an editor with a new message.
+Component Description
+messaging\urlhandler\urlhandler An application that parses the URLs and then creates a correctly addressed message and launches a message editor.
+messaging\urlhandler\recogniser Recognisers that map from the URL schemes to the mime types.
+3.1.1.7 Bio Message Framework
+The Bio Message Framework provides a framework that supports plug-ins to handle messages like vCards and Internet access point set-up messages.
+Component Description
+messaging\biomsg\BDB\BIODB Classes to maintain the database of bio registration files.
+messaging\biomsg\BIFU\BIFU Classes for reading and writing bio registration files
+messaging\biomsg\BIOC\BIOC Bio message client MTM, this is in the framework section as it forms part of the bio messaging framework it is also a plug-in to the messaging framework.
+messaging\biomsg\BIOS\BIOS Bio message server MTM, this is in the framework section as it forms part of the bio messaging framework it is also a plug-in to the messaging framework.
+3.1.2 Plug-ins
+3.1.2.1 SMS
+The SMS plug-ins provide application level support for the Short Message Service messages.
+Component Description
+messaging\biomsg\BioWatchers Plug-ins to the watcher framework to listen for SMS, WSP, and WDP messages and deliver them to the global inbox in the message store.
+messaging\sms\clientmtm A plug-in to the message server framework to provide a generic API for creation of SMS messages (SMS Client MTM & SMS utilities)
+messaging\sms\servermtm A plug-in to the message server framework to provide a generic API for sending of SMS messages (SMS Server MTM)
+3.1.2.2 CDMA SMS
+The CDMA SMS plug-ins provide application level support for the CDMA Short Message Service messages.
+Component Description
+messaging\biomsg\BioWatchersCdma Plug-ins to the watcher framework to listen for CDMA SMS messages and deliver them to the global inbox in the message store.
+messaging\sms\multimode\clientmtm A plug-in to the message server framework to provide a generic API for creation of CDMA SMS messages (CDMA SMS Client MTM)
+messaging\sms\multimode\servermtm A plug-in to the message server framework to provide a generic API for sending of CDMA SMS messages (CDMA SMS Server MTM)
+
+3.1.2.3 Email
+The email plug-ins provide support the POP3, IMAP4 and SMTP email protocols and support for parsing and generating plain test, MIME and M-HTML format email messages.
+Component Description
+messaging\email\clientmtms A plug-in to the message server framework to provide a generic API for creation of email messages (IMAP4 SMTP and POP3 Client MTMs & email utilities)
+messaging\email\imapservermtm A plug-in to the message server framework to provide a generic API for access to a remote IMAP4 server (IMAP4 Server MTM)
+messaging\email\smtpservermtm A plug-in to the message server framework to provide a generic API for access to a remote SMTP server (SMTP Server MTM)
+messaging\email\popservermtm A plug-in to the message server framework to provide generic API for access to remote POP3 server (POP3 Server MTM)
+messaging\email\servermtmutils Email utilities for parsing plain text and MIME email messages. It also provides an abstraction of the TCP/IP sockets for use by the SMTP POP3 and IMAP4 plug-ins.
+messaging\email\autosend An executable that requests SMTP Server MTM to send messages in the outbox. This is used to provide send on next connection functionality and is started by the POP3 and IMAP4 Client MTMs.
+3.1.2.4 OBEX
+The OBEX MTM is a set of plug-ins to the message server that provides support for IR and Bluetooth beaming.
+Component Description
+messaging\obex\btmtm\btclient\group\btcmtm Bluetooth Client MTM
+messaging\obex\btmtm\btserver\group\btsmtm Bluetooth Server MTM
+messaging\obex\irmtm\irclient\group\ircmtm IR Client MTM
+messaging\obex\irmtm\irserver\group\IRSMTM IR Server MTM
+messaging\obex\obexmtm\obexclient\group\obexClientMtm OBEX Client MTM, base classes for the Bluetooth and IR Client MTMs
+messaging\obex\obexmtm\obexserver\group\obexServerMtm OBEX Server MTM, base classes for the Bluetooth and IR Server MTMs
+messaging\obex\obexmtm\obexutil\group\obexMtmUtil OBEX MTM utilities
+3.1.2.5 MMS
+The MMS MTM is a plug-in to the message server that provides support for MMS messages. From v9.0 and onwards MMS MTM and related components are removed.
+Component Description
+messaging\mms\utils MMS Utilities
+messaging\mms\servermtm MMS Server MTM
+messaging\mms\mmswatcherplugins MMS plug-ins to WAP push framework to handle reception of MMS notifications
+messaging\mms\codec MMS utilities for handling MMS codecs
+messaging\mms\clientmtm MMS Client MTM
+3.1.2.6 GMXML
+GMXML is a parser/generator for SMIL presentations for MMS messages.
+Component Description
+messaging\GMXML\XMLParser XML parser designed for parsing of SMIL messages
+messaging\GMXML\XMLDom XML document object model designed for parsing of SMIL messages
+messaging\GMXML\SMILdtd SMIL DTD
+3.1.2.7 Bio Message Plug-ins
+These parsers plug into the bio messaging framework to handle specific types of bio message.
+Component Description
+messaging\biomsg\cbcp\CBCP Compact business card parser
+messaging\biomsg\enp\ENP Email notification parser
+messaging\biomsg\gfp\gfp General file parser
+messaging\biomsg\iacp\IACP Nokia Smart Message Internet Access Parser
+messaging\biomsg\wapp\wapp Nokia/Ericsson OTA Parser
+3.1.2.8 PCMTM
+Plug-in to the message server that provided email synchronisation with a PC. This component has been deprecated in 8.0a and will not been documented in the API section below.
+3.1.2.9 Fax
+Plug-in to the message server that provides fax support. This component has been deprecated in 8.0a and will not been documented in the API section below.
+
+3.2 General Description
+3.2.1 Messaging / Message Server and MTM Architecture APIs
+3.2.1.1 Key Internal Relationships and Dependencies
+
+Figure 2 MTM Relationships
+Figure 2 shows the relationship between the Message Server and the MTM plug-ins. The grey classes are realisations of the MTM interfaces defined by the messaging framework. The message server depends on the Server MTM interface. Messaging Clients depend on the Client, UI and UI Data MTM interfaces and the Message Server Client API.
+3.2.1.2 Key External Relationships and Dependencies
+
+Figure 3 External Dependencies
+The grey package representing the messaging client depends on the Client, UI and UI Data interfaces and the Messaging Client API. The message server then depends on:
+• Charconv – Provides character set conversion routines, used to convert encoded message body text to Unicode body text.
+• EStore – Provides API to handle a stream based store used for the messaging index file and the framework classes for the message store files. (omitted from other dependency diagrams as it is implied by the dependency on the message server)
+• F32 – Provides the file server APIs used to access the file system directories in which messaging stores files containing message data. (omitted from other dependency diagrams)
+• BAFL – Provides API to load the correct messaging resource file dependent on the current language and to register the message store index file with the backup server. (omitted from other dependency diagrams)
+• ETEXT – Rich text APIs used to store body text of messages, this rich text format is a Symbian Proprietary format. (omitted from other dependency diagrams)
+• EUSER – Core Symbian OS utilities such as descriptors, arrays, client / server framework, cleanup stack and others (omitted from this and other dependency diagrams).
+• Central Repository – Centralised and secure storage facility for application settings, the message server stores message settings data in the central repository (from v9.0 and onwards).
+Note that debug only dependencies such as the flogger have been omitted from dependency diagrams.
+3.2.1.3 API Purpose - Further Elaboration
+3.2.1.3.1 Message Store
+The message server provides persistent storage of messages and messaging account settings. It does this by providing a message store consisting of a tree of message entries. Multiple clients can access the message store simultaneously. Each entry in the tree can represent an email account, folder of messages, message part, etc.
+
+Figure 4 Message Store
+Figure 4 shows an example message store. The tree is broken down in to three levels:
+1. The Root entry. This entry is just present to tie the tree structure together
+2. Service entries. There is one local service under which local folders and messages are stored, and zero or more remote services. Remote services represent message accounts.
+3. Message & Folder entries. Messages and folders, under the local service represent messages stored on the device. Messages and folders under remote services represent a local copy of messages that are present on a remote server. For example under a POP3 email service you would have copies of all the messages present on the POP3 email server, or under an SMS service you might find SMS messages that are stored on a SIM.
+The message server controls access to the entries in the store. It enforces the three levels therefore attempts to create message or folder entries directly under the root entry will fail.
+The message server provides three types of storage for each entry in the message store:
+• Index entry - TMsvEntry - intended to provide enough information for UI to display list views as shown in Figure 5. This consists of two strings and various flags (read, complete, has attachments etc).
+• Stream based file store - CMsvStore – provides storage of streams of data associated with UIDs. A standard UID is defined for storing body text. Other UIDs are specific. For example the email MTMs define a UID for storage of MIME headers. Compared to the index entry information this is used to store larger objects and is extensible, at the cost of being slower to access. From v9.0 and onwards CMsvStore provides an Attachment API for managing attachments. The Attachment API should be used as attachments can no longer be accessed directly due to Platform Security.
+• Directory of files – normally used for attachments.
+The only storage type that is always present is the index entry. The stream store and the directory of files are optional.
+
+Figure 5 Series 60 Inbox List View
+
+Figure 6 Remote and Local Entries
+As shown in Figure 6 the message store is split into two sets of entries:
+• Remote entries - entries that are representations of entries stored on a remote store .
+• Local entries - entries not linked to a remote store.
+The message server handles changes to local entries; internally it hands off changes to remote entries to the Server MTM that owns that service. Examples of operations that are handed off to Server MTMs are operations involving copying and moving messages to and from a remote service. See section 3.2.1.3.5 or more information on Server MTMs.
+Each entry within the store has a type:
+Folder – Messages can be grouped into folders. Standard folders such as inbox / outbox and user created folders.
+Message – Storage of the content of a message. Message entries can have child entries used to represent the structure of a message.
+Attachment – These represent attachments under a message entry.
+Root & Local Service Entry – There tie the tree structure together. However the Stream store associated with the root entry is sometimes used by UIs to store preferences e.g. default folder views etc.
+Remote Service - Represents a source and / or destination for messages. They are used to store the settings associated with the source / destination.
+Message Type Specific - MTMs can create other message types for use as child entries to messages they own. For example email uses a tree structure, with a message entry as the root, to represent the MIME structure of an email message; it uses folder entries to represent MIME folders and adds new types for entries representing the html body and text body parts of a message. This is shown in Figure 7.
+
+Figure 7 Email Message
+Using the message store to represent message structure allows reuse of the tree structure and makes it very simple to represent one message embedded in another. However this representation introduces performance issues as it results in each message having multiple files associated with it. The message server also keeps all index entries in memory; therefore this representation increases the memory footprint of the message server. Therefore when designing new MTMs we should think about moving away using multiple index entries to store one message in the message store.
+A default message store is created if the message server starts and no message store is present or a corrupt message store is present. The server will initially create a store with just a root entry, and then the server will create any standard folders defined in the resource file msgs.rsc. Finally the server will check whether an executable ‘mailinit.exe’ is present on the system, if it is present the server will launch the executable to allow customisation of the message store. The behaviour of ‘mailinit.exe’ is defined by the UI family of the device. However the typical behaviour is to load each of the UI Message Type Modules and allow each to perform any message type specific initialisation. For example the SMS plug-in typically creates a default service entry.
+
+3.2.1.3.2 Data File Storage (pre - v9.0)
+This section describes the files used by the message server before release v9.0. For information on the files used for release from v9.0 and onwards see section [3.2.1.3.3.1].
+Filename Access Purpose
+?:\system\Mail\index Private Message server index file, internal to message server
+?:\system\Mail\<8 hex digits> Shared via API Message server store files for services, clients access these via a messaging API.
+?:\system\Mail\<8 hex digits>.new Shared via API Temporary file used during committing message server store files.
+?:\SYSTEM\MAIL\<8 HEX DIGITS>_F\* Shared Files associated with a messaging service. These may be accessed directly by clients.
+?:\system\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits> Shared via API Message server store files for message entries, clients access these via a messaging API.
+?:\system\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits>.new Shared via API Temporary file used whilst committing message server store files.
+?:\system\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits>_F\* Shared Files associated with a message entry. These are accessed directly by clients.
+c:\system\data\msgs.ini Private Stores the drive containing the last used message store
+c:\system\Mtm\Mtm Registry v2 Private Cache of registered MTMs, internal to message server
+C:\system\data\sms_settings.dat Shared Copy of the SMS settings.
+?:\System\Mail\StoreInit.tmp Shared Created when message server runs ‘mailinit.exe’, ‘mailinit.exe’ should delete the file when it has successfully completed.
+?:\System\Mail\storedeleted.tmp Shared Created when message server finds and deletes a corrupt message store. Allows the UI to inform the user about the fact that the message store was corrupt.
+Files that are shown as private should only be accessed by the message server or by connectivity process for backup and restore purposes. Files listed as shared are accessed directly by messaging clients. Files listed as shared via API are accessed by client process but only via messaging APIs.
+3.2.1.3.3 Platform Security Compliant Message Store
+From v9.0 and onwards the message store is stored in the message server's data cage and the settings data are placed in the Central Repository. Access to the message store is only possible via message server APIs and not directly through file access. This leads to secured data storage and secured platform.
+3.2.1.3.3.1 Data caging
+Filename Purpose
+?:\private\<SID>\Mail\index Message server index file, internal to message server
+?:\ private\<SID>\Mail\<8 hex digits> Message server store files for services, clients access these via a messaging API.
+?:\ private\<SID>\Mail\<8 hex digits>.new Temporary file used during committing message server store files.
+?:\ private\<SID>\Mail\<8 hex digits>_F\* Files associated with a messaging service. These may be accessed directly by clients.
+?:\ private\<SID>\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits> Message server store files for message entries, clients access these via a messaging API.
+?:\ private\<SID>\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits>.new Temporary file used whilst committing message server store files.
+?:\ private\<SID>\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits>_F\* Files associated with a message entry. These are accessed directly by clients.
+c:\ private\<SID>\data\msgs.ini Stores the drive containing the last used message store
+c:\ private\<SID>\Mtm\Mtm Registry v2 Cache of registered MTMs, internal to message server
+?:\ private\<SID>\Mail\StoreInit.tmp Access via IPC call
+?:\ private\<SID>\Mail\storedeleted.tmp Created when message server finds and deletes a corrupt message store. Allows the UI to inform the user about the fact that the message store was corrupt.
+?\resource\messaging\bif\*.bif Registration data field with UID used in BIO framework
+
+3.2.1.3.4 How message centres display the message store
+The UI normally provides a Message Centre application to display the structure of the message store to the user. Different UIs map the structure to different views.
+
+Figure 8 Series 60 Message Centre (Composed from 2 screen shots)
+Figure 8 shows the top level view of the message centre application on a Series 60 phone. This shows that the message centre has hidden the local service and shows the standard folders at the same level as the services. Also the SMTP, SMS and MMS services are marked as hidden entries in the message store, and so do not appear in the message application.
+
+Figure 9 UIQ Message Centre
+However Figure 9 shows that the UIQ message centre has no 1-1 mapping from the structure in the message store to the structure shown to the user. Each of the message types is displayed as if its messages were contained in separate folders. Under each of these folders the user is presented with an inbox, outbox, send and drafts folder. This filtering is done in the UI layer as this functionality is not provided by the messaging API.
+3.2.1.3.5 Message Type Module Architecture
+
+Figure 10 Messaging MTM Structure (light coloured components are part of messaging subsystem)
+The MTM architecture is the plug-in scheme provided by the messaging framework to integrate different message transports into the message server. The plug-in scheme consists of four interfaces, the UI MTM, UI Data MTM, Client MTM and Server MTM. The messaging client applications loads and uses the first three which are loaded within the client’s process space. The final one the Server MTM is loaded within the message server process. The APIs for the client facing interfaces are extensible via run time type information provided by the QueryCapability API, and the InvokeAsyncFunction and InvokeSyncFunction APIs.
+3.2.1.3.5.1 UI MTM
+Handles requests from clients to view and edit messages or service settings. The MTM handles interaction with the message centre and as such the exact meaning of the APIs is defined by the UI. However common meanings are:
+• Create – Launches the editor with a new message.
+• Edit – If entry is a message this launches the editor; if entry is a service it edits the settings.
+• View – Launches the message viewer.
+• Display progress of an operation.
+3.2.1.3.5.2 UI data MTM
+This MTM provides fast access to UI components such as menu resources and bitmaps required by message centre for list views etc. Again the exact semantics are UI specific.
+There is a resource file defining UI specific functions, for example the Series 60 Messaging UI checks if the resource file contains text to display in the “New Message” menu.
+The UI data MTM also provides mapping from the message store’s TMsvEntry structure to Icons for the messaging list views and a status string, for example in the case of Nokia 9210 it is used in the outbox view to provide strings like “Resend 01:07” as shown in Figure 11. The class also provides functions to determine what operations are possible with a given entry. Examples of this are APIs that return whether the UI should allow the user to reply to the entry or to delete a service entry. The UI then uses this information to determine which menu options / short-cut keys should be allowed when the user selects a given entry.
+
+Figure 11 Nokia 9210 Outbox List View
+3.2.1.3.5.3 Client MTM
+Provides methods to create / reply and forward messages. Functions the Client MTMs provide are:
+• Create Message.
+• Reply to a Message.
+• Forward a Message.
+• Add / remove Addressees.
+• Add / remove body text.
+• Add / remove subject.
+• Add / remove attachments (the API cannot list attachments).
+The Client MTM interface is used by SendAs to provide a way of creating messages independently of the message type.
+3.2.1.3.5.4 Server MTM
+This is the final interface that makes up an MTM plug-in; it differs from the other three plug-ins in that it is loaded into the message server’s process space. The Server MTM provides access to messages under remote services. It handles connecting to remote servers to handle updating the local cache of these messages or to send messages copied to remote services when messages are copied to a remote service. The message server loads and hands off all message store operations that involve entries under a remote entry, these are the entries on the left-hand side of Figure 6.
+Functions that a Server MTM must implement:
+• Copy/MoveToLocal – called when the message server is asked to move or copy an entry that is currently under a remote service. A Server MTM might map this to retrieving a message from a remote mailbox.
+• Copy/MoveFromLocal – called when the message server is asked to move or copy from under the local service to a destination under a remote service. A Server MTM should map this to sending a message if the MTM supports sending.
+• Create, Delete, Change – called when the message server is asked to perform these operations on entries under a remote service.
+• StartCommand – this API provides a means of extending the API the Server MTM provides. Messaging clients pass a command ID and a selection of entries via the message server to the Server MTM. Examples of commands that Server MTMs might provide are: connect and synchronise the entries under a remote service with the messages on an email server, list SMS messages present on the phones SIM. These commands are MTM specific and therefore clients have to know which MTMs support which commands.
+3.2.1.3.5.5 MTM Registration
+MTMs must be registered with the message server so that clients can query what MTMs are present and the server knows which DLL to load to create a given MTM component. MTMs are registered by providing a resource file containing the MTMs UIDs, human readable name, and for each MTM interface it lists a DLL and the ordinal at which the constructor for that interface exists. The message server will search the ROM drive for MTM registration resource files on start-up and it will automatically register any MTMs found. For registration of MTMs installed on other drives, the message server provides an API to register and de-register an MTM. Registration will persist across a reboot, so an MTM only needs to be registered when it is installed on the system.
+When MTMs are registered or unregistered the message server will send events to all messaging clients with a message server session open.
+3.2.1.3.6 Message Server Client API
+The Messaging Server Client API breaks down into two categories: APIs for manipulation of the message store and utility APIs.
+3.2.1.3.6.1 Message Store manipulation APIs
+Requests from clients to modify the message store fall into three categories:
+1. Operations performed entirely with local entries (entries on the right-hand side of Figure 6) for example requests to create entries in the inbox, delete an entry from the drafts folder etc. The message server handles these operations directly.
+2. Operations that involve a remote entry (entries on the left-hand side of Figure 6) for example requests to delete an entry under a POP3 service, or copy a message to an SMTP service. The message server hands these operations off to the Server MTM that owns the service under which the remote entry is stored. The only exception to this rule is the ChangeAttributes API call. This modifies flags on an index entry and is handled by the message server for both local and remote entries. This means that a Server MTM can not rely on being called when flags like the Unread flag are changed. Note that operations can not involve two remote entries; therefore requests to copy entries between a remote service representing one POP3 account to a remote service representing another POP3 account will fail with an error.
+3. Requests that are explicitly directed at a Server MTM via the TransferCommand API. These commands are just passed to the correct Server MTM by looking up the Service ID and MTM of the first message in the selection passed into the command.
+The message server sends events when entries in the message store are modified to messaging clients that have a session open with the server.
+Where the API provides asynchronous functions to modify the message store or transfer a command to a Server MTM, the functions will return a message server operation object. This object can be used to request progress on operation or cancel the operation. Deleting the operation object returned, or closing the session used to make the request will result in the operation being cancelled, therefore a messaging client must remain running until operations it has requested have either completed or they will be cancelled. See appendix A.1 for an example of an asynchronous copy operation. If a Server MTM operating on the same remote service is already handling an operation, the message server will queue the new operation to be handled when the Server MTM becomes free. Requests for progress of operations that are queued will fail with KErrNotReady. The fact that the queue is based on the remote service ID means that you can have two Server MTMs of the same type running at the same time as long as they are operating on different services. So for example you can have two separate POP3 MTMs running synchronising different remote services with email servers.
+3.2.1.3.6.2 Utility APIs
+1. Access to MTM registries – These allow clients to construct instances of the interfaces an MTM implements.
+2. Register / Unregister an MTM.
+3. Change Drive – The message server closes the current message store and opens one on the drive specified. If no message store is present on the drive specified a new message store is created. The message sever can have only one mail store open at a time, if the current mail store is not available because a the disk the mail store is on is not present then the message server will switch the mail store back to the C: drive if an attempt is made to create a message in the inbox.
+4. Launching Editors – This launches the correct editor for a message. It is implemented by delegating the request to the UI MTM
+3.2.2 Messaging / Send As APIs
+3.2.2.1 Key Relationships and Dependencies
+
+Figure 12 SendAs Version 1 Dependencies
+SendAs version 1 and only present in releases before v9.0. SendAs uses the Messaging Client API to access the registry of Client MTMs and construct the Client MTM interfaces. The Client MTMs are then used for composing the message. SendAs requires clients to implement the MSendAsObserver interface. This interface is responsible for checking the return value of the capability queries made to Client MTMs that require a response and also for rendering message types that require it. The only message type supplied by Symbian that requires rendering is Fax, however this MTM has been removed in 8.0a and future releases.
+3.2.2.2 API Purpose - Further Elaboration
+3.2.2.2.1 SendAs API (pre – v9.0)
+The SendAs API makes use of the Client MTM interface and the Messaging Client API to provide a generic API for creating messages. Note despite the name of this component SendAs does not provide an API to send the message.
+SendAs builds a list of registered MTMs, then queries each MTM to check whether it supports sending, removing those MTMs from the list that do not support sending. This list is then provided to the messaging client application. At this point the application can add more constraints on the list of MTMs; for example it can insist the MTM supports Attachments or more than a certain size of body text. SendAs queries each of the MTMs about the requirements and will drop any MTMs from the list that does not meet them. When the application has finished adding requirements it selects one of the MTMs left in the list and uses that to compose the message, adding addresses, a subject, body text and attachments.
+SendAs supports setting a BIO Type for the message that is composed. This tells the transport that the body text represents a BIO Message. This is used when sending business cards from the contacts application as SMS messages; the contacts application puts the vCard data in the body text of the message and the transport sends it correctly. If the MTM in question supports attachments then the vCard is attached to the message.
+A new CSendAs object must be created for each message the application wishes to create.
+3.2.3 Platform Security Compliant SendAs Server (v9.0 onwards)
+
+Figure 13 SendAs Version 2 Dependencies
+From v9.0 and onwards the CSendAs has been replaced by the SendAs server component. The new SendAs server controls the access to the message store. Some of the key SendAs Server features are listed as follows.
+• Send a message once the capability policing of the client application has been completed.
+• Allow client applications to launch an editor for a specified message type.
+• Allow client applications to query the message type.
+The main client-side API is the RSendAs class. The client applications use this to connect to the Send-As server. The session object on the server-side is an instance of CSendAsSession.
+Client applications create messages using the RSendAsMessage API. Opening an RSendAsMessage object on Send-As server session creates a CSendAsMessage object in the Send-As server. There is a one-to-one mapping between an RSendAsMessage object and a CSendAsMessage object. This allows client applications to create multiple messages concurrently.
+
+3.2.4 Messaging / Schedule Send APIs
+3.2.4.1 Key Relationships and Dependencies
+
+Figure 14 Schedule Send Dependencies
+The Schedule Send Server MTM base class depends on the task scheduler to launch the schedule send executable at the correct time. To send the message with a package of data previously passed into the task scheduler by the Server MTM. The schedule send executable then uses the Messaging Client API to actually perform the requested operation.
+3.2.4.2 API Purpose - Further Elaboration
+3.2.4.2.1 Schedule Send
+The Schedule Send functionality is delivered by four components:
+Server MTM Base Class – The base class provides support to Server MTMs that wish to support scheduled operations.
+Data Structures – These are classes used to represent the data associated with a scheduled operation.
+Executable – The executable is run by the task scheduler at the scheduled time.
+The Task Scheduler – This component is part of the system libraries subsystem. Currently the SMS and Fax Server MTMs support scheduled sending.
+Clients request the Server MTM schedules operations via additional commands passed to TransferCommand API; this is passed to the Server MTM via the message server. The Server MTM packages the operation ID, a selection of message IDs, how often to poll for progress and an MTM specific buffer. It then passes this package of data to the task scheduler requesting that it launches the schedule send executable at the correct time with the packaged information.
+When the task scheduler launches the schedule send executable, it unpacks the schedule information and uses the Messaging Client API to request the Server MTM to perform the operation.
+Schedule Send supports a retry mechanism if the operation fails. The Server MTM has a resource file containing a mapping from the error codes the operation can fail with and actions to be performed. For example the SMS resource file has a mapping such that if the operation fails with an error code indicating a bad phone number the SMS will be set to failed and left in the outbox. Whereas if it fails with a error code indicating temporary network failure the send operation will be scheduled to be resent later with a maximum of three retries.
+3.2.5 Messaging / Watchers APIs
+3.2.5.1 Key Relationships and Dependencies
+
+Figure 15 Watcher Dependencies
+The watcher executable’s dependency on the message server is the result of a performance measure. The watcher process creates a message server session before initialising each of the watcher plug-ins and closes the session when it has finished. This keeps the message server running during initialisation avoiding starting and stopping the message server if each watcher plug-in opens and closes sessions.
+3.2.5.2 API Purpose - Further Elaboration
+The watcher framework consists of an executable that is launched when the device boots. The component that is responsible for launching it depends on the UI family. When the watcher.exe is launched it will load each DLL in z:\system\libs\watchers which has a second UID as KWatcherUid and calls the first DLL entry point to construct a CActive object.
+From v9.0 and onwards watcher DLLs are found by scanning the directory \resource\messaging\watchers for registry files. These files contain the name of a watcher DLL that can be loaded from ROM i.e. z:\sys\bin.
+The framework has retry behaviour if the first entry point leaves, in this case the watcher framework will start a timer and try and construct the watcher object 10 seconds later. Five attempts are made before the watcher plug-in is assumed to have failed completely. Once the watcher framework has constructed all the watchers it starts the active scheduler which should never exit.
+Watcher plug-ins typically make a request to another subsystem such that they will be completed when an external event like a fax line ringing or an SMS being received occurs. When the watcher has completed processing the request it will wait for the next event.
+No support for starting / stopping watchers is provided. This is a limitation that makes watchers unsuitable for operations like listening for messages beamed via IR, as the watcher should only run while the IR port is active.
+3.2.6 Messaging / Message URL Handler APIs
+3.2.6.1 Key Relationships and Dependencies
+
+Figure 16 Message URL Handler Dependencies
+3.2.6.2 API Purpose - Further Elaboration
+The Message URL Handler provides support for creating messages and launching messaging editors from URLs such as mailto:infobot@example.com?subject=current-issue. Note there is no dependency between the Message URL Handler application which processes the URLs and the Message URL Handler recognisers which maps from URLs to mime types.
+3.2.6.2.1 Message URL Handler Application
+This is a Symbian OS application that registers with the application framework that it can handle the mime types: x-epoc-url/fax, x-epoc-url/mailto and x-epoc-url/sms. When launched with a URL it will parse the URL to retrieve the address and other header fields and then use the SendAs API to create a new message with the correct address, headers etc. The application then uses the APIs in the MturUtils class provide by the mtmbase component in the messaging framework to launch the correct editor for the given message type. The application is marked as hidden and therefore should not be listed by UIs in application browsers.
+3.2.6.2.2 Message URL Recognisers
+This is a plug-in to the recogniser framework it will be called when the application framework wishes to recognise a file. Recognisers are called with the file name, in this case a URL, and a buffer containing the start of the file. The message URL recogniser compares the start of the URL with the URL schemes it recognises, if it finds a URL scheme it knows about it maps it to a mime type. The recogniser ignores the buffer passed in.
+Schemes recognised:
+Scheme Mime type
+mailto: X-Epoc-Url/mailto
+fax: X-Epoc-Url/fax
+sms: X-Epoc-Url/sms
+mms: X-Epoc-Url/mms
+See the application framework architectural description for more information on recognisers [R2].
+3.2.7 Messaging / SMS APIs
+3.2.7.1 Key Internal Relationships and Dependencies
+
+Figure 17 SMS Internal Dependencies
+3.2.7.2 Key External Relationships and Dependencies
+
+Figure 18 SMS External Dependencies
+3.2.7.3 API Purpose - Further Elaboration
+3.2.7.3.1 SMS Watchers
+The SMS watchers are made up of two watchers, the nbswatcher.dll and the wapwatcher.dll, and some common base classes in biowatcher.dll. The watchers listen for incoming messages from the SMS stack, part of the nbsprotocols subsystem [R3], and the WAP stack part of the WAP-Stack subsystem [R4].
+3.2.7.3.1.1 NBS Watcher
+The NBS watcher handles reception of SMS messages. When initialised by the watcher framework (see section 3.2.4) the watcher queries the bio messaging database for bio messages that are listed as having a type of ENbs. For each of these bio messages the watcher creates an object that opens a connection to the SMS stack and waits for the particular message type. The message types are either defined by the port number the message will be received on or by a string to watch for at the start of the message. For example Internet Access Configuration Point messages are start with “//SIAP11” and vCards are received on port 226. Finally the watcher listens for all other messages received from the SMS stack.
+When the NBS Watcher receives a non-class 2 SMS message it creates a new entry under the global inbox in the message store. For class 2 messages the entry is created in the class 2 folder as defined by the SMS settings, this may also be the global inbox. The details field of the entry is used to store the phone number of the incoming message or the name of the sender if the watcher finds a match for the phone number in the contacts database. The description field is used to store the first N characters of the SMS message, where N is defined in the SMS settings, or for bio messages the description as retrieved from the bio database. Bio messages also have the BioType field set to the UID of the bio message as retrieved from the bio database. The CSmsHeader class, which is a wrapper around the CSmsMessage class provided by the nbprotocols subsystem [R3], is used to externalise the SMS message to the entry’s CMsvStore. The watcher also places a copy of the body text of the message in the rich text stream of the entry’s CMsvStore.
+The NBS Watcher is also responsible for handing special SMS types including:
+• Replace Type Messages – When the watcher receives a message of this type it will scan the folder the message would have been delivered to for messages that have a matching protocol ID and from address. For each of the messages it checks whether the time stamps from the service centre and discards the older message.
+• Message Indications – The watcher can listen for incoming message waiting indications. The CSmsSettings class defines whether the watcher will listen and whether it will deliver the messages to the inbox or discard them. If the watcher is configured to listen for messages then it will use the SMS utilities in the SMS Client MTM to decode the message to determine the notification type and number of messages, e.g. 3 Email messages waiting, the strings for these messages are in the smss.rss resource file.
+• Delivery Reports – As with Message Indications the watcher can be configured to listen for these and again the SMS utilities get a string from the smss.rss resource file to put in the description field.
+The NBS Watcher handles changes to the bio database using the observer mechanism provided by the bio message database to observe when bio message types are added or removed and starting or stopping the object watching for that bio message type.
+3.2.7.3.1.2 WAP Watcher
+The WAP watcher listens for incoming messages from the WAP stack using the WAP message API [R4]. To determine ports to use to listen for messages the watcher queries the bio message database for bio message types EWsp, EWspSecure, EWap, EWapSecure and registers as an observer of the bio database and so will listen for new bio message with these types as they are added. The watcher stores the messages in the global inbox tagged with the bio type listed in the bio message database.
+3.2.7.3.2 SMS Client MTM
+The SMS Client MTM implements the standard set of Client MTM APIs described in Client MTM. In addition it provides:
+• Access to the CSmsHeader object that is used to represent the SMS message.
+• Access to the SMS settings stored in the associated SMS service.
+• The APIs required by Send As to allow Send As to create SMS messages including setting the bio type of the message to allow clients of Send As to send bio messages such as vCards and vCals. The data of the bio message is stored in the body text of the SMS message.
+• Simple check for valid SMS addresses, and SMS address is considered valid if it contains at least one digit.
+• Reading and writing SIM parameters.
+3.2.7.3.3 SMS Utilities
+These provide:
+• Classes to represent and store SMS messages (CSmsHeader), and SMS settings (CSmsSettings, CSmsMessageSettings) and a SMS number (CSmsNumber).
+• The CSmsHeader class contains and allows clients to access the CSmsMessage class that the nbsprotocols subsystem provides. This contains the entire SMS message and not just the header.
+• Functions to generate descriptions and details fields to store with SMS messages, including decoding special messages such as message indication and status report messages, reading resource file for descriptions strings of special messages, using the contacts database to replace phone numbers with names.
+• API to validate a GSM number.
+• Find the TMsvId of the SMS service entry.
+3.2.7.3.4 SMS Server MTM
+3.2.7.3.4.1 Sending Messages
+The SMS Server MTM handles sending of SMS and WAP messages via the SMS stack and the WAP stack. To support this it implements the CopyFromLocal API inherited from the Server MTM base class. It implements this as sending SMS messages and moving successfully sent messages to the Sent folder. When sending the SMS message the Server MTM checks the bio type of the message and uses the bio database to check the transport type for the bio message. The MTM supports ENbs that is sent via the SMS stack and EWap, EWapSecure that are sent via the WAP stack. The MTM does not support EWsp or EWspSecure although the watchers do support receiving them.
+If a message fails to send, sending is retried according to the settings in the smss.rss resource file as described in the schedule send section 3.2.3.
+3.2.7.3.4.2 Scheduling Messages
+The SMS Server MTM implements scheduled sending API by sub-classing from the schedule send Server MTM (see section 3.2.3). It accepts requests from clients either via the SMS Client MTM InvokeAsync API or via the CMsvSession::TransferCommand API to schedule messages to be sent or to delete existing schedules. When it receives a request to schedule a message it packages up the command and uses the scheduled send functionality to request that the task scheduler ask it to send the messages at a future point in time.
+3.2.7.3.4.3 Phone Store
+The phone store is the name given to storage of SMS messages outside of the message store. In the case of GSM phones this is the SIM. The SMS Server MTM accepts requests from clients to copy/move messages to and from the SIM and delete messages from the SIM. For example when copying to the SIM it packages up the SMS message and passes it to the SMS stack with a request to write it to the SIM. If the class2 folder has been set in the SMS settings class then the Server MTM will copy the SMS message to the SIM and then update the SMS message in the message store with details of the slot on the SIM that has been used to store the SMS and the fact that it is stored on the SIM.
+3.2.7.3.4.4 SIM Parameters
+The Server MTM provides functions to read / write SIM parameters, again these requests are passed to the SMS stack to be processed.
+3.2.8 Messaging / CDMA SMS APIs
+3.2.8.1 Key Internal Relationships and Dependencies
+
+Figure 19 CMDA SMS Internal Dependencies
+3.2.8.2 Key External Relationships and Dependencies
+`
+Figure 20 CDMA SMS External Dependencies
+3.2.8.3 API Purpose - Further Elaboration
+3.2.8.3.1 CDMA SMS Watchers
+The CDMA SMS watchers are made up of six watchers, the cdmanbswatcher.dll, vmnwatcher.dll, wemtwatcher.dll, wmtwatcher.dll, wptwatcher.dll, and the wapwatcher.dll, and some base classes in biowatcher.dll and cdmasocketwatcher. While the WAP watcher is common for both GSM and CDMA, the other watchers: CDMA NBS watcher, VMN watcher, WEMT watcher, WMT watcher, and the WPT watcher are used for CDMA only. The watchers listen for incoming messages from the CDMA SMS stack, part of the nbsprotocols subsystem [R3], and the WAP stack part of the WAP-Stack subsystem [R4].
+3.2.8.3.1.1 CDMA NBS Watcher
+The CDMA NBS watcher is similar to the NBS watcher and it handles bio messages defined in bio database. The CSmsHeader class is extended to wrap around the CCdmaSmsMessage class provided by the nbprotocols subsystem [R3], and is used to externalise the CDMA SMS message.
+For handling special CDMA SMS type, the CDMA NBS watcher is responsible for handling Message Indications as described in section 3.2.7.3.1.1 NBS Watcher.
+3.2.8.3.1.2 WAP Watcher
+The GSM WAP watcher is used to handle CDMA WAP message as well. The WAP watcher listens for incoming messages from the WAP stack, which can listen from the CDMA SMS stack or GSM SMS stack as appropriate. See 3.2.7.3.1.2 for more info about WAP watcher.
+3.2.8.3.1.3 Other CDMA Watchers
+The VMN watcher, WEMT watcher, WMT watcher and WPT watcher are CDMA watchers that handle reception of CDMA SMS messages. All CDMA SMS messages are associated with a teleservice. Therefore, each of the CDMA watchers is responsible for handling one teleservice: VMN watcher handles VMN SMS messages, WEMT watcher handles WEMT SMS messages, WMT watcher handles WMT SMS messages, and WPT watcher handles WPT SMS messages. The CSmsHeader class is reused to externalise the CDMA SMS message.
+The CDMA watchers are also responsible for handling special SMS types including:
+• Duplicate Message – When the watcher receives a duplicate message, it will discard the duplicate message as defined by the CDMA service settings.
+• User Acknowledge – The watcher can listen for user acknowledgment message of its teleservice type.
+• Delivery Acknowledge – The watcher can listen for delivery acknowledgment message of its teleservice type.
+• Read Acknowledge – The watcher can listen for read acknowledgment message of its teleservice type.
+3.2.8.3.2 CDMA SMS Client MTM
+The CDMA SMS Client MTM implements the standard set of Client MTM APIs described in Client MTM. In addition it provides:
+• Access to the CSmsHeader object that is used to represent the SMS message.
+• Access to the SMS settings stored in the associated SMS service. These settings are store in file store pre v9.0 but stored in Central Repository from v9.0 onwards.
+• The APIs required by Send As to allow Send As to create SMS messages including setting the bio type of the message to allow clients of Send As to send bio messages such as vCards and vCals. The data of the bio message is stored in the body text of the SMS message.
+• Simple check for valid SMS addresses, and SMS address is considered valid if it contains at least one digit.
+• Reading and writing SMS messages to R-UIM.
+3.2.8.3.3 CDMA SMS Utilities
+The CDMA version of SMS utilities are binary compatible with the GSM version of SMS utilities. But the classes that store SMS Message (CSMSHeader), and SMS settings (CSmsSettings, CSmsMessageSettings) and SMS number (CSmsNumber) are extended to store CDMA information. The CSmsHeader class is extended to contain and allow clients to access the CCdmaSmsMessage in addition to the CSmsMessage. Other functions provided by the GSM SMS Utilities is also provided by the CDMA version of SMS utilities, see 3.2.7.3.3 for information about GSM SMS Utilities.
+3.2.8.3.4 CDMA SMS Server MTM
+3.2.8.3.4.1 Sending Messages
+The CDMA SMS Server MTM handles sending of CDMA SMS and WAP messages via the CDMA SMS stack and the WAP stack. To support this it implements the CopyFromLocal API inherited from the Server MTM base class. It implements this as sending SMS messages and moving successfully sent messages to the Sent folder. When sending the CDMA SMS message the Server MTM will use the appropriate teleservice type. The MTM supports ENbs that is sent via the SMS stack and EWap, EWapSecure that are sent via the WAP stack. The MTM does not support EWsp or EWspSecure although the watchers do support receiving them.
+If a message fails to send, sending is retried according to the settings in the smss.rss resource file as described in the scheduled send section 3.2.4.
+3.2.8.3.4.2 Scheduling Messages
+The CDMA SMS Server MTM implements scheduled sending API by sub-classing from the schedule send Server MTM similar to implemented in the GSM SMS Server MTM. See 3.2.7.3.4.2 for more information.
+3.2.8.3.4.3 Phone Store
+In the case of CDMA phones, phone store can be phone-based storage or R-UIM based storage. The CDMA SMS Server MTM accepts requests from clients to copy/move messages to and from the phone/R-UIM and delete messages from the phone/R-UIM. For example when copying to the R-UIM it packages up the SMS message and passes it to the CDMA SMS stack with a request to write it to the R-UIM.
+3.2.8.3.5 Configuration for using CDMA SMS MTM
+The CDMA messaging components currently only support single mode, but it is designed such that it can become multimode in the future. Currently, -Dcdma option is used to for selecting CDMA mode for using emulator and building ROM.
+
+
+3.2.9 Messaging / Email APIs
+3.2.9.1 Key Internal Relationships and Dependencies
+
+Figure 19 Email Internal Dependencies
+
+3.2.9.2 Key External Relationships and Dependencies
+
+Figure 20 Email External Dependencies
+3.2.9.3 API Purpose - Further Elaboration
+3.2.9.3.1 Email Overview
+The Email plug-ins consist of a set of utilities and MTMs for POP3, IMAP4 and SMTP. For each email account a pair of services entries is created in the message store. For a POP3 account there will be an SMTP service and a POP3 service, for an IMAP4 account there will be an SMTP service and as IMAP4 service. These entries are used to store the settings for the email transport. Each of the service entries has its related ID set to the other member of the pair. The SMTP service is created invisible so the user only sees the POP3 or IMAP4 service entry, copying a message to the SMTP service will cause the SMTP Server MTM to attempt to send the message. The POP3 and IMAP4 MTMs provide functionality to synchronise with a remote email server this is achieved by extending the Client MTM interface via the InvokeAsync API. Synchronisation of a POP3 or IMAP4 account will result in copying headers and optionally body text and attachments from the email server and creating message entries under the POP3 or IMAP4 service entry.
+Email messages are represented in a common format whether they are being sent via SMTP or downloaded via POP3 or IMAP4. The email client utilities provide the classes for creating and manipulating the entry structure used to store emails. The email server side utilities provide classes to convert between the entry structure used to store emails in the message store and RFC2822 email messages sent to SMTP servers and retrieved from POP3 servers. IMAP4 email messages are parsed by the email server and the IMAP4 Server MTM requests and stores the individual parts of the messages.
+3.2.9.3.2 Email Client Utilities
+The email client utilities are part of the imcm DLL and provide classes for:
+• Storage of email messages including mime headers, RFC2822 headers, attachments, body text and encoding information in the message store
+• Manipulating email messages, for example adding attachments, replying etc.
+• To wrap up the character converters used to convert between standard character sets and Unicode. These make use of the charconv component that is part of the system libraries subsystem.
+• Storage of Email settings in the message store.
+• Progress information for email operations.
+The utilities are used directly by clients to access parts of email messages for display. CImEmailMessage provides the functionality used by clients displaying email messages, including listing attachments, getting body text and resolving URIs in M-HTML messages.
+The Email Client MTMs use the utilities when they are asked to create, reply to and forward messages CImEmailOperation provides the functionality to perform these operations. Each email message is represented by a parent message entry and then entries to represent mime folders and mime parts, see Figure 7 for an example, so adding or deleting mime parts involves walking the tree of entries and inserting / removing entries as appropriate.
+3.2.9.3.3 Email Server MTM Utilities
+The Email Server MTM Utilities are responsible for generating and parsing of RFC2822 format email messages and providing an API to wrap up a TCP/IP connection to a remote email server.
+• Parsing of RFC2822 Email Messages – The utilities provide an API that accepts the text of an RFC2822 email message a line at a time and stores the email message in messaging’s internal format for email messages. See the Email Client Utilities for details of this format. The API handles storing of RFC2822 headers, MIME headers, decoding of Base64 encoded or uuencoded attachments and decoding of text received in character sets supported by the charconv component. This API is only accessible to Server MTMs, as it requires classes that can only be instantiated while running within the message server process. See the Messaging Functional Specification [R1] for detail on which email specifications the utilities support.
+• Generation of RFC2822 Email Messages – The utilities provide an API to convert an email in messaging’s internal format into an RFC2822 email message. The API provides access to the RFC2822 text a line at a time for streaming to an SMTP server. The exact format of the email depends on the settings passed in; the API can generate plain RFC2822 email messages with uuencoded attachments, MIME email messages with Base64 encoded attachments, or M-HTML email messages with Base64 encoded attachments. See the Messaging Functional Specification [R1] for detail on which email specifications the utilities support.
+• TCP/IP socket wrapper – The utilities provide a class that abstracts a TCP/IP socket supplied by the networking subsystem into an API that supports sending and receiving lines of text to / from a remote server. This API is used to connect to remote email servers by each of the email Server MTMs. The API can either create insecure or secure sockets enabling the SSL encryption provided by the networking subsystem. It also supports changing an insecure socket into a secure socket, this enables the email Server MTMs to implement email protocols where the initial connection to the server is insecure and then a secure socket is negotiated before sending or requesting any sensitive information.
+3.2.9.3.4 POP3 MTMs
+The POP3 MTMs implements the functionality to synchronise the local message store with a remote POP3 email server.
+3.2.9.3.4.1 Client MTM
+The POP3 Client MTM implements the standard Client MTM APIs and other extensions:
+• Reply to, forward – These are accessible via the ReplyL and ForwardL APIs of a Client MTM and are implemented as calls to the email utilities class CImEmailOperation.
+• Reply to, forward, create new messages, create receipts and forward as attachment – These are accessible as commands available via the InvokeAsyncFunction API of the Client MTM, they are implemented as calls to CImEmailOperation.
+• Connecting, disconnecting and copying email while connected – These operations are accessible as commands available via the InvokeAsyncFunction API of the Client MTM, they are implemented as calls to the POP3 Server MTM.
+• Querying connection status – This command lets clients know whether the POP3 Server MTM is connected to an email server, and is available via the InvokeAsyncFunction API of the Client MTM. The Client MTM requests the information from the Server MTM.
+• Compound operations – The Client MTM provides functionality to wrap up connecting to email servers, copying / moving new messages or a selection of messages, and then optionally disconnecting. These commands are available via the InvokeAsyncFunction API of the Client MTM. The Client MTM implements this by using the CImPOP3GetMail class which requests the correct sequence of operations from the Server MTM, waiting for each operation to complete before requesting the next one.
+• Send on next connection If the Client MTM gets a request to connect to an email server it will check whether the POP3 settings. If send on next connection is requested it will launch the autosend.exe executable (see section 3.2.7.3.7) to handle sending messages waiting in the outbox.
+• Offline operations – The POP3 Client MTM has a command to cancel offline operations, this is available via the InvokeAsyncFunction API of the Client MTM. The Client MTM passes the request to the Server MTM.
+3.2.9.3.4.2 Server MTM
+The POP3 Server MTM handles the communication with the remote POP3 server and implementation of the POP3 protocol. The MTM uses CImTextServerSession to handle the communication with the email server and CImRecvConvert to parse the email messages downloaded, both are provided by the Email Server MTM Utilities.
+• Connect – The POP3 Server MTM will open a socket to the email server using CImTextServerSession and login user the username / password in the POP3 settings. After a successful connection the Server MTM will attempt to synchronise the current state of headers stored on the email server with the set stored in the message store and then start any pending offline operations. After the connect operation has completed the Server MTM will inform the message server that it is expecting more operations via the CommandExpected API and therefore the message server will not delete and unload the Server MTM.
+• Populate Message – The POP3 Server MTM treats requests to copy a message from and to the POP3 service as a request to download the full message.
+• Offline operations – When the POP3 Server MTM receives a request to copy, move, or delete and is not connected to a POP3 email server the Server MTM will store the operation in the CMsvStore of the entry being modified and perform the operation on the next connection to the email server.
+• Disconnect – When disconnecting from a remote email server the POP3 MTM will run any pending offline operations stored. After the disconnect operation completes the Server MTM will allow the message server to delete and unload the Server MTM by setting the CommandExpected API to false.
+3.2.9.3.5 IMAP4 MTMs
+The IMAP4 Server MTM implements the functionality to synchronise the local message store with a remote IMAP4 email server.
+3.2.9.3.5.1 Client MTM
+The IMAP4 Client MTM implements the standard Client MTM APIs and other extensions:
+• Connecting, disconnecting, synchronising, un/subscribing folders – These operations are accessible as commands available via the InvokeAsyncFunction API of the Client MTM, they are implemented as calls to the IMAP4 Server MTM.
+• Send on next connection – If the Client MTM gets a request to connect to an email server it will check whether the IMAP4 settings. If send on next connection is requested it will launch the autosend.exe executable (see section 3.2.7.3.7) to handle sending messages waiting in the outbox.
+• Reply to, and forward messages – These are accessible via the ReplyL and ForwardL APIs of a Client MTM and are implemented as calls to the email utilities class CImEmailOperation.
+• Reply to, forward, create new, create receipt, forward as attachment – These are accessible as commands available via the InvokeAsyncFunction API of the Client MTM, they are implemented as calls to CImEmailOperation.
+• Querying connection status – These commands let clients know whether the IMAP4 Server MTM is connected to an email server and whether it is currently processing a request. They are available via the InvokeAsyncFunction API of the Client MTM. The Client MTM requests the information from the Server MTM.
+• Compound Connection and synchronisation – The IMAP4 Client MTM provides a compound operation that connects and synchronises with an IMAP4 server. This operation is implemented as a client side object that combines requests to the IMAP4 Server MTM. The client side operation can complete the client request either after the connection, after the connection + sync or after the connection + sync + disconnect. The client will keep requesting that the inbox be resynchronised at a configurable interval so new messages received in the inbox on the server will appear under the IMAP4 inbox. The CImapConnectAndSyncOp class handles these compound operations.
+• Compound Connect and copy / move / populate messages – The IMAP4 Client MTM provides a compound operation that connects to an IMAP4 server and copies moves or populates messages. The implementation is provided by the CImImap4GetMail class which makes calls back into the IMAP4 Client MTM.
+• Offline operations – The IMAP4 Client MTM has a command to cancel offline operations, this is available via the InvokeAsyncFunction API of the Client MTM. The Client MTM passes the request to the Server MTM.
+3.2.9.3.5.2 Server MTM
+The IMAP4 Server MTM handles the communication with the remote IMAP4 server and implementation of the IMAP4 protocol. The MTM uses CImTextServerSession to handle the communication with the email server. The IMAP4 Server MTM opens two connections to the IMAP4 server this enables users to download messages while the Server MTM is performing a background synchronisation if requested by the Client MTM.
+• Connect – The IMAP4 Server MTM will open a socket to the email server using CImTextServerSession and login using the username / password in the IMAP4 settings. After a successful connection the Server MTM will optionally attempt to synchronise the current state of headers stored on the email server with the set stored in the message store and then start any pending offline operations. After the connect operation has completed the Server MTM will inform the message server that it is expecting more operations via the CommandExpected API and therefore the message server will not delete and unload the Server MTM.
+• Copy, Move messages – The IMAP4 Server MTM supports copying and moving messages between folders on the IMAP4 server and between the IMAP4 server and local folders.
+• Delete messages – The IMAP4 Server MTM will mark the email as deleted on the server; however it will not be deleted until the IMAP4 Server MTM disconnects from the server.
+• Folders – The IMAP4 Server MTM will allow folders to be subscribed, unsubscribed, renamed, copied, moved, and created within the IMAP4 service. Subscribing to a folder means that it will be visible to the user and synchronised with the remote server. The inbox is always subscribed.
+• Offline operations – When the IMAP4 Server MTM receives a request to copy, move, or delete and is not connected to an IMAP4 email server the Server MTM will store the operation in the CMsvStore of the entry being modified and perform the operation on the next connection to the email server.
+• Disconnect – When disconnecting from a remote email server the IMAP4 MTM will run any pending offline operations stored. After the disconnect operation completes the Server MTM will allow the message server to delete and unload the Server MTM by setting the CommandExpected API to false.
+
+3.2.9.3.6 SMTP MTMs
+The SMTP MTMs provide functionality to send email messages. They are made up of the Client MTM that is part of the imcm DLL and the Server MTM.
+3.2.9.3.6.1 Client MTM
+The SMTP Client MTM implements the standard Client MTM APIs including the functions required to allow clients of Send As to create email messages.
+3.2.9.3.6.2 Server MTM
+The SMTP MTMs provide functionality to send email messages; it interprets requests to copy entries to an SMTP service as a request to send those messages. In addition it responds to two extended commands via the StartCommand Server MTM interface. These commands are KSMTPMTMIsConnected that responds with whether the Server MTM is currently connected to a remote SMTP server and KSMTPMTMSendOnNextConnection which performs the same operation as copying a selection of messages to an SMTP service. The only difference between the copy operation and the KSMTPMTMSendOnNextConnection operation is that the latter can be called without a selection of messages.
+When the Server MTM receives a request to send messages it builds a selection of messages consisting of the messages passed into the operation and any messages waiting in the outbox to be sent. To determine which messages in the outbox are waiting to be sent the SMTP server checks for messages that have the same service ID as the destination of the send operation and have a sending state of KMsvSendStateWaiting, KMsvSendStateScheduled or KMsvSendStateResend. This means that any request to send messages may result in more messages being sent than explicitly listed in the selection passed to the send operation.
+The Server MTM restores its settings from the SMTP service it has been asked to copy the messages to. Then it connects to the SMTP server using the CImTextServerSession class in the Email Server MTM Utilities, passing in the SMTP server address and TCP/IP port number from the SMTP settings. Then for each message to be sent the Server MTM uses the Email Server MTM utilities to generate an RFC2822 format message to send to the SMTP server, the RFC2822 text is generated on the fly as the data is sent to the SMTP server. If the SMTP server accepts the message to be sent then the Server MTM moves the message to the sent folder and sets its sending state to sent. If the SMTP server rejects the message then the Server MTM leaves the message in the outbox and sets the sending state to failed. Separate emails are generated for BCC recipients to ensure that the SMTP server doesn’t incorrectly include BCC recipients in emails sent to addresses in the To and CC fields of the email.
+3.2.9.3.7 Autosend
+The Autosend component is an executable that is kicked off by the POP3 and IMAP4 Client MTMs if the send on next connection setting is set. This executable will just make a request to the SMTP Server MTM to send messages associated with the SMTP service related to the POP3 or IMAP4 service, wait for the operation to finish and then exit.
+3.2.10 Messaging / MMS APIs
+The MMS module has been removed from v9.0 and onwards.
+3.2.10.1 Key Internal Relationships and Dependencies
+
+Figure 21 MMS Internal Dependencies
+3.2.10.2 API Purpose - Further Elaboration
+3.2.10.2.1 MMS Overview
+The MMS MTM provides functionality for creating, accessing, sending and receiving MMS messages. Messages are sent and received without the client application needing to open or close any kind of session. The management of the MMS session is handled entirely within the MTM.
+MMS clients are alerted when a new message is available for download via the WAP Push mechanism. A WAP push watcher is provided to handle these notifications. After the notification the message can be downloaded over WSP or HTTP. Messages are sent by posting the data over WSP or HTTP. The Symbian MMS implementation can handle sending or receiving MMS message over either protocol.
+MMS messages are based on the MIME format but are binary encoded using WSP. Note that MMS messages are encoded in this way even if they are posted over HTTP as opposed to WSP. The codec component is responsible for this encoding and decoding.
+3.2.10.2.2 MMS Utilities
+3.2.10.2.2.1 Key External Relationships and Dependencies
+
+Figure 22 MMS Utilities External Dependencies
+The MMS utilities provide the message and settings encapsulation classes. The MMS settings and messages are stored in the message store, the MMS utilities provide the interfaces to access this data.
+3.2.10.2.2.2 Settings
+The settings functionality provided by the MMS utilities allows the messaging client to persist MMS settings in the message store. Supported settings include:
+ MMSC (MMS server) address
+ WSP or HTTP transport
+ Autofetch messages on notification
+ Preferred IAP for the MMS network connection
+The settings functionality is also used by the server MTM to retrieve the settings prior to message sending or fetching.
+3.2.10.2.2.3 Message Encapsulation
+The message classes provide the message access functionality. Messages can be created, stored, restored and read using these classes. Functionality includes:
+ Adding media objects to the message
+ Enumerating through media objects
+ Adding recipients, subject line, etc. to a message
+ Adding other headers to the message, e.g. expiry date
+ Finding the appropriate media object for a given URI in the SMIL part (URI resolving)
+The message data is stored in the message store using one entry per message regardless of the number of media objects added to the message. This is preferable to using multiple message entries as it is faster and uses less disk space.
+Most of the message access code is common whether it is being used on the client or server side, however some parts of it are specific. For this reason it is essential that the appropriate client or server side CMmsMessage derived class is used.
+3.2.10.2.3 MMS Watcher
+3.2.10.2.3.1 Key External Relationships and Dependencies
+
+Figure 23 MMS Watcher External Dependencies
+
+The MMS watcher plug-in is responsible for intercepting incoming MMS notifications and delivery reports then taking the appropriate action. It is implemented as a WAP Push watcher plug-in.
+When an MMS notification is received an MMS entry is created in the inbox using the MMS utilities. At this point the entry has its incomplete flag set. If the settings have the autofetch option selected then the MMS watcher initiates the fetch operation via the MMS client MTM.
+If a delivery report is received then the delivered flag is set on the appropriate sent message. If an outgoing message was sent to several recipients then there will be several delivered flags. A delivery report from each recipient will set the appropriate delivered flag.
+3.2.10.2.4 MMS Client MTM
+3.2.10.2.4.1 Key External Relationships and Dependencies
+
+Figure 24 MMS Client MTM Dependencies
+As with most other MTMs the MMS client MTM provides access to the server MTM functionality for messaging clients. It also implements the Send-As interface and reply and forward functionality.
+3.2.10.2.4.2 Send-As Implementation
+The Client MTM Send-As interface is implemented in the MMS Client MTM. The implementation differs slightly from other MTMs because additional presentation content may be generated depending on the media objects that are added. When simple combinations of images, sounds and text are added a SMIL presentation is generated to link them together. This is preferable to simple adding the objects as attachments where some clients render them as a list of files and others fail to render them at all.
+The SMIL data is constructed using templates stored in resource files, the GMXML (SMIL) composer is not used.
+3.2.10.2.4.3 Reply / Forward
+The Client MTM can be used to create replies to received messages or to create forwarded responses. The reply and forwarding operations are performed asynchronously.
+3.2.10.2.5 MMS Server MTM
+3.2.10.2.5.1 Key External Relationships and Dependencies
+
+Figure 25 MMS Server MTM Dependencies
+The Server MTM is the most complicated part the MMS implementation. It handles all of the state information required to send or fetch MMS messages. It is also responsible for managing the HTTP or WSP session and the connections to the phone network.
+3.2.10.2.5.2 Operations
+All MMS server MTM functionality is encapsulated in operations. An operation consists of the setup of a session, the sending, fetching and acknowledgements when appropriate, it then closes the session. The messaging client initiates an operation with a single call to the Client MTM, there is no need for the messaging client to explicitly establish the session or to know about the internal states. However, these internal states are available to the messaging client via the progress structure if this level of user feedback is required.
+Two types of operation are supported, background and foreground:
+A maximum of one foreground operation can be running at any one time. The messaging client can poll the server MTM for the progress of a running foreground operation, likewise it can cancel it if necessary.
+A background operation does not support progress information and can not be cancelled by the messaging client. It is possible to initiate background operations even if other background or foreground operations are pending. However, background operations are queued and a maximum of one will actually be running at any one time.
+The MMS watcher uses a background operation to perform automatic fetching. While the background autofetch is occurring it is still possible to start a foreground operation (such as sending a message) if required.
+3.2.10.2.5.3 Session and Connection Management
+The server MTM uses the HTTP Transport Framework to enable the HTTP or WSP session. HTTP or WSP can be selected at runtime by selecting the appropriate option in the settings. The server MTM is responsible for reading any HTTP proxy details from the CommDB and passing it to the HTTP framework. See the http transport framework architectural description for more information on recognisers [R5]
+The server MTM is also responsible for managing the connection to the phone network. Connections are opened when required using the RConnection mechanism, multi-homing is supported provided that the underlying HTTP framework transport plug-in also supports it.
+3.2.10.2.6 MMS Codec
+The MMS Server MTM is in charge of the state transitions, connection, session, the actual posting and fetching of the data from them, however it does not encode or decode the MMS PDUs. The encoding and decoding is performed by the MMS Codec.
+For decoding the Server MTM passes the Codec the MMS PDU data in a descriptor for processing. If the PDU contains a received MMS message then the message entry is updated with the decoded MMS data.
+For encoding the Server MTM passes a reference to the message store entry containing the un-encoded MMS data. The Codec then encodes it and returns the PDU to the Server MTM in a descriptor.
+
+
+3.2.11 Messaging / BIO APIs
+3.2.11.1 Key Internal Relationships and Dependencies
+
+Figure 26 BIO Message Internal Dependencies
+3.2.11.1.1.1 Key External Relationships and Dependencies
+
+Figure 27 Bio Parser External Dependencies
+
+3.2.11.2 API Purpose - Further Elaboration
+3.2.11.2.1 BIO Overview
+The BIO messaging components have been designed to unify and simplify the way in which system messages are processed. In this context ‘system messages’ refers to messages received on the device which are intended to update some attribute(s) on the system as opposed to being presented to the user. Examples of these types of messages include vCards which are parsed and then displayed to the user and when accepted modify the users contact database and OTA configuration messages which are again parsed before display to the user and if accepted create email accounts or internet access points.
+The BIO messaging components can be broken down into three groups:
+1) The BIO MTM - To initiate the parsing and processing of BIO messages
+2) The BIO Database - Maps port numbers, MIME types, etc. to bio types in order to identify the type of incoming BIO messages.
+3) The BIO Parsers - To parse and process the BIO message payload
+BIO messages are not receive by the bio messaging framework, they come over other message transports for example see section 3.2.6.3.1 on the SMS watchers which describes how the SMS watchers receive bio messages and use the bio framework to tag the messages with the correct bio id.
+3.2.11.2.2 BIO MTM
+The BIO client MTM is called by the messaging client to parse or process a BIO message that has been saved in the message store. It is the responsibility of a BIO watcher to save the BIO message with the BIO flag and the appropriate BIO type set.
+The BIO client MTM does very little, its primary task is to pass on the messaging client request to the server MTM. Two operations are supported, parse and process.
+The messaging client is expected to initiate the parsing of the BIO message before processing it. The parsing step involves analysing the data and storing it in a form that can be displayed to the user via the BIO message viewer.
+Once the message has been parsed the messaging client can initiate the processing of the message.
+The BIO server MTM is responsible for deferring the parsing and processing to the appropriate BIO parser. The behaviour for the parsing and processing steps varies between parsers. See the BIO Parsers section for more information.
+The bio MTM does not support sending messages and therefore does not support reply / forwarding messages. For bio messages sending / reply etc. is supported by the particular MTM that the message is sent over, for example SMS.
+3.2.11.2.3 BIO Database
+The BIO database is used to identify the type of BIO messages. It maps message attributes such as port number, MIME type or leading string to a BIO type. These are attributes are then used by clients of the bio framework to know what ports to listen for messages on. For example the SMS watchers use the leading string to wait for SMS messages that start with that string and when storing those messages in the inbox tag them with the bio id associated with that leading string. See the SMS watcher section 3.2.6.3.1 for more examples of how the BIO database can be used.
+3.2.11.2.4 BIO Parsers
+The BIO parsers are plug-ins for parsing and processing incoming BIO messages. They are invoked by the BIO Server MTM depending on the BIO type of the message being processed. Each BIO parser implements two functions, ParseL and ProcessL. The level of functionality varies between parsers. Some parsers update the final repository with the received data, e.g. WAPP updates the CommDB with the received settings. Some parsers simply save the data in an unparsed state for processing by another component, this secondary parsing is not part of the BIO framework and must be initiated by the messaging client. An example is when GFP saves vCard data as a file as opposed to updating the contacts database, the UI must then invoke the Versit parser to parse the vCard and commit it to the contacts database.
+3.2.11.2.4.1 Generic File Parser (GFP)
+The generic file parser can be used to identify and save a variety of BIO data types, e.g. vCards and vCals. The Generic File Parser does not process the data, it simply saves it in the message store for processing by another component. The file is saved as an attachment of the message entry that was parsed.
+3.2.11.2.4.2 Nokia/Ericsson OTA Parser (WAPP)
+The WAPP parser decodes Nokia/Ericsson OTA messages and updates CommDB to reflect the received settings.
+3.2.11.2.4.3 Nokia Smart Message Internet Access Parser (IACP)
+The IACP parser decodes Nokia Smart Messages and updates the CommDB and messaging settings where appropriate.
+3.2.11.2.5 BIF Files and Utilities
+The BIF files encapsulate the information required for identifying BIO messages, these details may include the expected port number, MIME type or leading string. Different BIO watcher will use different information from these files, for an example see the 3.2.6.3.1. The information can be retrieved from the BIF files by using the BIF utilities. Generally BIO aware clients will access this information via the BIO database. BIF files are resource files previous to the v6.1 release they were binary files generated by biftool.exe.
+3.2.11.2.6 Platform Security Compliant Messaging / BIO APIs
+In the platform security model the BIO parsers are run in the client space rather than in the message server space, as is done in the non-platform secure model. If the BIO parsers are run in the message server space, it allows a client process to gain the capabilities of the message server. IPC policing can protect the message server from this.
+Also, for the message server to be able to load any BIO parser it would need more capabilities than it really requires. By running the BIO parsers in the client space, both these issues are solved. The client process must be trusted with the necessary capabilities to run the specified BIO parser.
+The BIO registry files are located in the \resource\messaging\bif read-only directory. All BIO parser DLLs are located in the \sys\bin protected directory.
+
+Figure 26 BIO Message Dependencies (v9.0)
+The BIO client MTM is responsible for loading the BIO database and BIO utilities to handle parse/process requests from clients.
+The BIO registry files no longer identify the BIO parsers DLLs via their UID – the registry file must use the BIO parser DLL name to identify them.
+3.2.12 Messaging / OBEX MTM APIs
+3.2.12.1 Key Internal Relationships and Dependencies
+
+Figure 28 OBEX Internal Dependencies
+3.2.12.2 OBEX MTM Overview
+The OBEX MTM offers simple IR and Bluetooth beaming functionality. It provides an API that is consistent with other MTMs so that the underlying OBEX APIs do not need to be used directly for beaming applications. The OBEX MTM does not provide OBEX receiving functionality, in order to receive OBEX data the underlying OBEX APIs must be used directly.
+3.2.12.2.1 OBEX MTM
+The OBEX MTM is split into three parts. OBEX MTM DLLs, IR MTM DLLs and Bluetooth MTM DLLs. The OBEX MTM DLLs can not be used on their own they provide the base OBEX MTM functionality for the derived IR and Bluetooth MTMs.
+There are two APIs that can be used to create OBEX messages:
+1) The Send-As API
+2) Linked attachments by filename
+The Send-As API provides an interface consistent with other MTMs, however it requires all attachments to be copied into the message store before they can be sent, this is often undesirable for beaming applications because it is wastes disk space. For this reason a second API is provided that allows attachments to be linked to outgoing messages by filename, when this API is used there is no need to copy the attachments to the message store.
+Unlike many other MTMs after OBEX tries to send a message it is deleted from the outbox whether the sending succeeds or fails.
+3.2.12.2.1.1 OBEX MTM Key External Dependencies
+
+Figure 29 OBEX External Dependencies
+3.2.12.2.2 IR MTM
+The bulk of the OBEX MTM functionality is provided by the OBEX MTM DLLs, the IR MTM itself just sets up the parameters.
+3.2.12.2.2.1 IR MTM Key External Dependencies
+
+Figure 30 IR MTM Dependencies
+3.2.12.2.3 Bluetooth MTM
+The bulk of the OBEX MTM functionality is provided by the OBEX MTM DLLs, the Bluetooth MTM just subclasses from the OBEX MTM and sets up Bluetooth specific parameters.
+3.2.12.2.3.1 Bluetooth MTM Key External Dependencies
+
+Figure 31 Bluetooth MTM Dependencies
+3.2.12.2.4 OBEX MTM Utils
+The OBEX MTM Utils provide utility functionality used by the other OBEX MTM DLLs. The two main areas of functionality provided by this component are:
+1) Filename linking functionality
+2) Bluetooth SDP lookup
+The filename linking functionality is provided in the utilities because linked files must be added by the client side during message creation and need to be read on the server side during sending.
+
+3.2.12.2.5 Platform Security Compliant Messaging / OBEX MTM APIs
+From v9.0 and onwards the service settings of all the derived OBEX MTMs are stored in the Central Repository. The OBEX message is stored in the message store as an attachment – from v9.0 and onwards the Attachment API is used to attach the OBEX message.
+
+3.2.13 Messaging / GMXML APIs
+3.2.13.1 Key Relationships and Dependencies
+
+Figure 32 GMXML Dependencies
+3.2.13.2 Overview
+The GMXML component provides simple XML DOM parsing and validation functionality. It is intended for parsing XML that might be needed in messaging applications, specifically SMIL parsing for MMS rendering. It is not a general purpose XML parser and will not be suitable for some applications, e.g. browsing.
+3.2.13.2.1 GMXML DOM
+The DOM implementation is fit for purpose for SMIL rendering but differs from the standard DOM design in several respects, e.g. attributes are not stored as discrete nodes, for performance reasons they are stored with the element.
+The DOM tree classes are all derived from nodes. Implemented node types include elements, text and comments. The type of each element is stored as a descriptor as opposed to an enum. This is less efficient than storing it as an enum but provides maximum flexibility when dealing with unknown element types.
+Nodes are linked together in a tree structure as might be expected in a DOM implementation. The tree structure exists on the heap.
+3.2.13.2.2 GMXML Parser and Composer
+3.2.13.2.2.1 Parser
+The parser takes XML input from a buffer or file and creates the corresponding DOM structure on the heap.
+The parser is capable of performing some basic validation. In order to validate against a DTD a class that implements the GMXML DTD interface is required. The DTD interface specifies several functions that provide the required validation, e.g. one of the functions determines if a given attribute is valid for a given element. An instance of the DTD class should be passed into the parser when validation is required but can be omitted if no validation is needed.
+3.2.13.2.2.2 Composer
+The composer takes a DOM tree and generates XML output from it. The XML output is written to a file.
+3.2.13.2.3 GMXML SMIL DTD (Validator)
+The SMIL DTD validator class is an implementation of the DTD validator interface. It implements several simple functions that provide the information required to validate SMIL data. An instance of the SMIL DTD validator should be passed into the parser if SMIL validation is required.
+4 Security
+4.1 Data caging
+For data storage in the pre-platform security compliant architecture, refer to section [3.2.1.3.2]
+For the data caging in the platform security compliant architecture of v9.0 and onwards, refer to section [3.2.1.3.3]
+4.2 Backup and restore
+The message server registers the index file with the backup server. When informed about a backup/restore it releases the index file, sending events to messaging clients informing them that the message store is unavailable. When informed it can open the index file again, it checks the time stamp on the index file; if it has changed since the file was released it reloads the index file. If the newly restored index file is found to be corrupt it is deleted and a new message store is created. See the section on page 14 for details on how the message server handles corrupt stores. The client performing the restore should always wipe the existing message store before starting to copy the message store from the backup to the device.
+4.3 Capability ranges
+In the platform security compliant architecture of v9.0 and onwards, the capabilities allocated to messaging sub-systems are as listed in following table.
+4.3.1 Capabilities granted to executables
+The following table lists the executables and their capabilities and also gives a basic example for having the required capability.
+
+Executable Capability Rationale (basic example of capability requirement)
+msexe.exe ProtServ ProtServ is required to allow the msexe.exe to start a protected server. This stops processes without ProtServ from starting a server pretending to be the message server
+ ReadDeviceData ReadDeviceData is needed to able to read service settings
+ WriteDeviceData WriteDeviceData is needed to able to write service settings
+ NetworkServices NetworkServices capability is needed to access network transports (SMS, POP3, SMTP, IMAP4).
+ LocalServices LocalServices is needed to be able to access IR and Bluetooth
+ ReadUserData ReadUserData is needed to be able to read user data (e.g. service settings).
+watcher.exe ReadDeviceData ReadDeviceData is needed to able to read service settings
+ WriteDeviceData WriteDeviceData is needed to able to write service settings
+ NetworkServices NetworkServices capability is needed to access network transports (SMS).
+ LocalServices LocalServices capability is needed for the plug-ins to access IR and Bluetooth
+ ReadUserData ReadUserData is needed to be able to read user data
+ WriteUserData WriteUserData is needed to be able to write user data
+autosend.exe ReadUserData ReadUserData capability is needed to be able to read data from Outbox and SMTP server MTM.
+ WriteUserData WriteUserData capability is needed to be able to write data in Outbox and SMTP server MTM.
+ NetworkServices NetworkServices capability is needed to access network transports (SMS, POP3, SMTP, and IMAP4).
+ LocalServices LocalServices capability is needed to access the IR and Bluetooth
+SchSend.exe ReadDeviceData ReadDeviceData is needed to able to read settings data
+ NetworkServices NetworkServices capability is needed to access the network transports (SMS, POP3, SMTP, and IMAP4).
+ LocalServices LocalServices is needed to be trusted by other MTM
+ ReadUserData ReadUserData is needed to be able to read user data.
+ WriteUserData WriteUserData is needed to be able to write user data.
+SendAs.exe ReadDeviceData ReadUserData is needed to be able to read data in Outbox.
+ WriteDeviceData WriteUserData is needed to be able to write data in Outbox.
+ NetworkServices NetworkServices capability is needed to access the network transports (SMS, POP3, SMTP, and IMAP4).
+ LocalServices LocalServices is needed to be able to access IR and Bluetooth
+
+4.3.2 Capabilities granted to DLLs
+The assigned Platform Security attributes for DLLs within messaging are outlined in the following table.
+DLL Capability
+bifu.dll All –TCB
+bioc.dll All –TCB
+biodb.dll All –TCB
+bios.dll All –TCB
+biowatcher.dll same as watcher.exe
+biut.dll All –TCB
+cbcp.dll All –TCB
+enp.dll All –TCB
+gfp.dll All –TCB
+iacp.dll All –TCB
+nbswatcher.dll same as watcher.exe
+cdmanbswatcher.dll same as watcher.exe
+CdmaSocketWatcher.dll same as watcher.exe
+VMNWatcher.dll same as watcher.exe
+WEMTWatcher.dll same as watcher.exe
+WMTWatcher.dll same as watcher.exe
+WPTWatcher.dll same as watcher.exe
+wapp.dll All –TCB
+wapwatcher.dll same as watcher.exe
+smildtd.dll All –TCB
+xmldom.dll All –TCB
+xmlparser.dll All –TCB
+smiltranslator.dll All –TCB
+imcm.dll All –TCB
+imps.dll same as msexe.exe
+imut.dll All –TCB
+msgs.dll All –TCB
+msgurlrec.mdl same as AppArc.exe (once it exists; eiksrv in meantime)
+mtur.dll All –TCB
+pops.dll same as msexe.exe
+schsend.dll All –TCB
+send.dll All –TCB
+smcm.dll All –TCB
+smcm_gsm.dll Synonym for smcm.dll
+smcm_cdma.dll Synonym for smcm.dll
+smss.dll same as msexe.exe
+smss_gsm.dll Synonym for smss.dll
+smss_cdma.dll Synonym for smss.dll
+smts.dll same as msexe.exe
+btcmtm.dll All –TCB
+btsmtm.dll same as msexe.exe
+irc.dll All –TCB
+irs.dll same as msexe.exe
+obexclientmtm.dll All –TCB
+obexmtmutil.dll All –TCB
+obexservermtm.dll same as msexe.exe
+
+The reason for setting a high capability to the DLLs is to make it possible for almost anyone to link to them. Although a DLL may have capabilities ALL-TCB (All minus TCB), its real capability is limited by the process which loads the DLL.
+4.3.3 Capabilities required to use the subsystem
+The message subsystem needs to be protected against malicious clients. The following table shows the key capabilities required to do related activities in different components.
+
+Component Related Activity Required Capability and SID
+Message server Create message in local folder No capability required
+ Create message in Outbox ReadUserData, WriteUserData and MTM specific capabilities
+ Access client MTM ReadUserData, WriteUserData and MTM specific capabilities
+Watcher Allow plug-ins to wait on events (e.g. arrival of SMS) Watcher always polices if the client capabilities are trusted by the watcher framework, else it will not be loaded
+Plug-ins or clients using watcher need the same capabilities as watcher.exe to be able to be loaded by watcher.
+Autosend Send messages in background NetworkService or LocalService required by the message type
+SchSend Scheduling of operations (e.g. sending SMS) SchSend always polices to see if the process was started by the Task Scheduler – if not the process terminates without performing any of the scheduled tasks. Also, the SchSend verifies that only itself and the message server created the scheduled tasks. If this is not the case, SchSend does not performing the scheduled tasks.
+SendAs Create message Draft, move it to Outbox, and send message WriteDeviceData or WriteUserData and other capability required by the message type
+
+5 Further Information
+5.1 References
+No. Document Reference Version Description
+R1 messaging_functional_specification.doc 0.6 Messaging Functional description
+R2 SGL.GT0143.161_App-Framework_Architectural_Description.doc 1.0 App-Framework Architectural Description
+R3 NBProtocols_Subsystem_Architectural_Description.doc 0.2 NBProtocols Architectural Description
+R4 WAP-stack_architectural_analysis.doc 1.0 WAP stack architectural analysis
+R5 HTTP Transport Framework Architectural Description.doc 1.1 HTTP Transport Framework 1.1 Architectural Description
+5.2 Open Issues
+The following issues need to be resolved before this document is completed:
+1. Top-level architecture diagram showing the framework and plug-ins should be added to overview section.
+2. Message store section should talk about removable media.
+3. Define "Message Server Client API" and "Messaging Client API" in the glossary, and ensure it is consistently used in the diagrams
+4. Add a sequence diagram for receiving a vCard over SMS and integrating it into contacts
+5. Add a sequence diagram for sending an SMS
+6. Add a sequence diagram for synchronising a POP3 mail box
+7. Add a sequence diagram for connecting to an IMAP4 mail box and downloading a message
+8. Capability table should be updated after the implementation of server e.g. message server
+9. Sequence diagram may need to be changed to show secured platform operation
+10. In section [3.1.1.4] the server SendAsV2 to find a correct name
+11. Section 3.2.1.3.3.1 Data Caging file 'Mtm Registry v2'may need a correct name
+12. Breakdown diagram showing all DLL, exes, apps in the messaging subsystem for both the pre-v8.0 and post v9.0 in section[3.2]
+13. Needs to say more about how the capabilities are policed and the algorithms used for different operations
+14. The dependecy between the message server and the central repository need to be listed in the email, SMS and OBEX diagrams (e.g. message store)
+15. Section 3.2.1.2 - figure 3 - Central Repository also get used by the Message server, or server MTMs (e.g. POP3), to retrieve account settings the path, required DLL and description are not given
+16. Section 4.3.3 title can be Police requirement of the sub-system, add extra column for SID in the table and list the use of SID. For example SchSend checks for Task Scheduler SID
+
+
+5.3 Glossary
+The following technical terms and abbreviations are used within this document.
+Term Definition
+BIO
+Bearer Independent Object Smart messages e.g. vCards, vCals, and WAP provisioning messages. These can currently be received via the WAP stack, SMS stack, Bluetooth or Infrared.
+BIO Type UID that represents the content type of a BIO Message.
+Message Centre Application that displays list views of messages to the user, allowing the user to perform operations such as copying messages, sending messages creating new messages etc.
+Message Viewer Application for viewing a message.
+Message Editor Application for creating or editing a message
+Message Server Symbian OS Server that handles request to modify the Message Store
+Message Store Store of messages and related information kept in the file system on a Symbian OS device.
+Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
+Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
+Global Inbox A standard folder under the local service which is used to store incoming messages like SMS MMS etc. as opposed to an IMAP4 Inbox which would be under an IMAP4 service and is a representation of the Inbox on an IMAP4 email server.
+Central Repository centralised and secure storage facility for application settings
+OBEX Object exchange protocol, used to send objects such as vCards or files between devices via infrared or Bluetooth.
+GMXML XML parser / generator for use with SMIL formatted messages.
+UID Unique Identifier, a 32 bit number allocated from a registry owned by Symbian
+IPC Inter Process Communication
+MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
MTM Registry A list of currently installed MTMs maintained by the message server.
TLS Transport Layer Security, provides encryption of a TCP/IP socket.
M-HTML Standard for including HTML in MIME email messages see http://www.ietf.org/rfc/rfc2557.txt
@@ -34549,15 +28441,1033 @@
Message Editor Application for creating or editing a message
Message Server Symbian OS Server that handles request to modify the Message Store
Message Store Store of messages and related information kept in the file system on a Symbian OS device.
-Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
-Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
+Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
+Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
Global Inbox A standard folder under the local service which is used to store incoming messages like SMS MMS etc. as opposed to an IMAP4 Inbox which would be under an IMAP4 service and is a representation of the Inbox on an IMAP4 email server.
Central Repository centralised and secure storage facility for application settings
OBEX Object exchange protocol, used to send objects such as vCards or files between devices via infrared or Bluetooth.
GMXML XML parser / generator for use with SMIL formatted messages.
UID Unique Identifier, a 32 bit number allocated from a registry owned by Symbian
IPC Inter Process Communication
-MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
+MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
+MTM Registry A list of currently installed MTMs maintained by the message server.
+TLS Transport Layer Security, provides encryption of a TCP/IP socket.
+M-HTML Standard for including HTML in MIME email messages see http://www.ietf.org/rfc/rfc2557.txt
+MIME Specification for the format of email message bodies see http://www.ietf.org/rfc/rfc1341.txt
+RFC2822 The standard format for internet mail messages see http://www.ietf.org/rfc/rfc0822.txt
+SMTP Simple Mail Transport Protocol
+SID Secure Identification
+IMAP4 Internet Mail Access Protocol
+POP3 Post Office Protocol Version 3
+NBS Narrow Band Socket, in the messaging context this refers to the socket that is used to talk to the SMS stack for receiving and sending SMS messages
+SMS Short Message Service
+MMS Multimedia Message Service
+WAP Wireless Application Protocol
+WSP WAP Session Protocol
+HTTP Hypertext transfer protocol
+PDU Protocol Data Unit. This is the encoded form of SMS and MMS messages.
+Versit A consortium that defined standard formats for things like contacts (vCard) and calendar entries (vCals)
+SDP Service Discovery Protocol. A Bluetooth protocol that allows an applications to discover which services are available and to determine the characteristics of the services.
+SMIL Synchronized Multimedia Integration Language. Presentation language that is commonly used to define the contents of an MMS message.
+XML Extensible Mark-up Language
+DOM Document Object Model
+DTD Document Type Definition, a schema that defines the structure of an XML document.
+ESTORE Symbian OS component that provides stream based storage. Messaging uses the Permanent file store provided by ESTORE to store its index entries.
+Appendix A - Example Sequence Diagrams
+A.1 Copy to a Remote Service
+
+Figure 33 Sequence Diagram Showing Copying to a Remote Service
+Figure 33 shows a client copying a message to a remote service using the Messaging Client API. The message server then delegates the copy to the SMTP Server MTM. The Server MTM interprets the request as a request to send the message so it opens a connection to a remote SMTP server and sends the message. While the message is being sent the client can retrieve progress information from the CMsvOperation object that was returned by CMsvEntry::CopyL. The dark grey IPC line represents the split between the objects running in the client’s process space on the left and the message server’s process on the right.
+There are four basic steps:
+1. The client opens session with Message Server and creates a CMsvEntry set on the global outbox,
+2. The client then requests an asynchronous copy from the outbox to the SMTP service, a CMsvOperation object is returned. The message server loads the SMTP Server MTM and delegates the copy operation to it.
+3. The client requests progress from the CMsvOperation object, this request is passed through to the SMTP Server MTM. The client may repeat this step multiple times.
+4. The Server MTM finishes sending message. It moves the message to sent folder and completes the message server’s request. The message server completes the CMsvOperation object, which requests the final progress from the message server. The server returns the final progress and deletes the Server MTM. The CMsvOperation then completes the client’s original request.
+This diagram hides all of the internal working of the SMTP Server MTM, for information on this see below.
+A.2 SMTP Session
+
+Figure 34 Sequence Diagram Showing a SMTP Session
+Figure 34 shows the operation of the SMTP Server MTM after a request has come from the message server to copy a message to the SMTP service.
+1. SMTP Server MTM gets the request from the message server, it will build a selection of messages consisting of the union of the selection of messages passed in and the messages in the outbox that are associated with this SMTP service and are ready to be sent. The chain of classes are constructed, and a request is passed to networking to connect to the remote SMTP server, details of the server name and port are retrieved from the settings stored in the SMTP service entry.
+2. The component waits for the SMTP server to respond with a greeting indicating it is willing to talk, then sends EHLO to the server and waits for the response detailing the capabilities of the Server. After this step there could set steps to start using TLS and or SMTP AUTH depending on the SMTP settings.
+3. CImSmtpSession calls back into CMsgOutboxSend to retrieve the next message to be sent, then constructs a CImSmtpFile object to handle sending, for details on the sending see SMTP Email Send. When sending the email has completed the CImSmtpFile object is deleted.
+4. CImSmtpSession calls back into CMsgOutboxSend to retrieve the next message which returns saying there are no more messages. CImSmtpSession sends QUIT to the SMTP server and completes CMsgOutboxSend. CMsgOutboxSend deletes CImSmtpSession which tears down the connection to the SMTP server; it then completes the SMTP Server MTM. The Server MTM will then complete the message server and be deleted.
+A.3 SMTP Email Send
+
+Figure 35 Sequence Diagram Showing SMTP Transactions during Email Send.
+Figure 35 shows a CImSmtpFile object sending an email message to an SMTP server.
+1. Construct a CImSendMessage object, part of the imut component. Reset the SMTP Server
+2. Read address information from the CImHeader object stored in the message store, send address information to SMTP server.
+3. Use CImSendMessage object to read the message from the message store and generate RFC2822 message line by line. Send each line to the server as it is generated.
+4. Complete and send the message by sending a full stop to the SMTP server
+
+
+
+
+Messaging Symbian OS v7.0s, v8.0, v8.1, v9.0, v9.1 Architectural Description
+
+Status: Issued
+Team/Department : Messaging / Content & Messaging
+
+Contents
+1 INTRODUCTION 6
+1.1 PURPOSE AND SCOPE 6
+2 SUBSYSTEM OVERVIEW AND BACKGROUND 6
+3 MESSAGING ARCHITECTURE AND APIS 7
+3.1 SUBSYSTEM COMPONENTS 7
+3.1.1 Framework components 7
+3.1.1.1 Message Server and MTM architecture 7
+3.1.1.2 Schedule Send 7
+3.1.1.3 SendAs Version 1 7
+3.1.1.4 SendAs Version 2 7
+3.1.1.5 Watcher Framework 8
+3.1.1.6 Message URL Handler 8
+3.1.1.7 Bio Message Framework 8
+3.1.2 Plug-ins 8
+3.1.2.1 SMS 8
+3.1.2.2 CDMA SMS 8
+3.1.2.3 Email 9
+3.1.2.4 OBEX 9
+3.1.2.5 MMS 9
+3.1.2.6 GMXML 10
+3.1.2.7 Bio Message Plug-ins 10
+3.1.2.8 PCMTM 10
+3.1.2.9 Fax 10
+3.2 GENERAL DESCRIPTION 11
+3.2.1 Messaging / Message Server and MTM Architecture APIs 11
+3.2.1.1 Key Internal Relationships and Dependencies 11
+3.2.1.2 Key External Relationships and Dependencies 12
+3.2.1.3 API Purpose - Further Elaboration 13
+3.2.1.3.1 Message Store 13
+3.2.1.3.2 Data File Storage (pre - v9.0) 15
+3.2.1.3.3 Platform Security Compliant Message Store 16
+3.2.1.3.4 How message centres display the message store 17
+3.2.1.3.5 Message Type Module Architecture 19
+3.2.1.3.6 Message Server Client API 21
+3.2.2 Messaging / Send As APIs 22
+3.2.2.1 Key Relationships and Dependencies 22
+3.2.2.2 API Purpose - Further Elaboration 22
+3.2.2.2.1 SendAs API (pre – v9.0) 22
+3.2.3 Platform Security Compliant SendAs Server (v9.0 onwards) 23
+3.2.4 Messaging / Schedule Send APIs 24
+3.2.4.1 Key Relationships and Dependencies 24
+3.2.4.2 API Purpose - Further Elaboration 24
+3.2.4.2.1 Schedule Send 24
+3.2.5 Messaging / Watchers APIs 25
+3.2.5.1 Key Relationships and Dependencies 25
+3.2.5.2 API Purpose - Further Elaboration 25
+3.2.6 Messaging / Message URL Handler APIs 26
+3.2.6.1 Key Relationships and Dependencies 26
+3.2.6.2 API Purpose - Further Elaboration 26
+3.2.6.2.1 Message URL Handler Application 26
+3.2.6.2.2 Message URL Recognisers 27
+3.2.7 Messaging / SMS APIs 27
+3.2.7.1 Key Internal Relationships and Dependencies 27
+3.2.7.2 Key External Relationships and Dependencies 28
+3.2.7.3 API Purpose - Further Elaboration 28
+3.2.7.3.1 SMS Watchers 28
+3.2.7.3.2 SMS Client MTM 29
+3.2.7.3.3 SMS Utilities 29
+3.2.7.3.4 SMS Server MTM 30
+3.2.8 Messaging / CDMA SMS APIs 31
+3.2.8.1 Key Internal Relationships and Dependencies 31
+3.2.8.2 Key External Relationships and Dependencies 32
+3.2.8.3 API Purpose - Further Elaboration 32
+3.2.8.3.1 CDMA SMS Watchers 32
+3.2.8.3.2 CDMA SMS Client MTM 33
+3.2.8.3.3 CDMA SMS Utilities 33
+3.2.8.3.4 CDMA SMS Server MTM 33
+3.2.8.3.5 Configuration for using CDMA SMS MTM 34
+3.2.9 Messaging / Email APIs 35
+3.2.9.1 Key Internal Relationships and Dependencies 35
+3.2.9.2 Key External Relationships and Dependencies 36
+3.2.9.3 API Purpose - Further Elaboration 36
+3.2.9.3.1 Email Overview 36
+3.2.9.3.2 Email Client Utilities 37
+3.2.9.3.3 Email Server MTM Utilities 37
+3.2.9.3.4 POP3 MTMs 37
+3.2.9.3.5 IMAP4 MTMs 38
+3.2.9.3.6 SMTP MTMs 40
+3.2.9.3.7 Autosend 40
+3.2.10 Messaging / MMS APIs 40
+3.2.10.1 Key Internal Relationships and Dependencies 41
+3.2.10.2 API Purpose - Further Elaboration 41
+3.2.10.2.1 MMS Overview 41
+3.2.10.2.2 MMS Utilities 42
+3.2.10.2.3 MMS Watcher 43
+3.2.10.2.4 MMS Client MTM 43
+3.2.10.2.5 MMS Server MTM 44
+3.2.10.2.6 MMS Codec 45
+3.2.11 Messaging / BIO APIs 46
+3.2.11.1 Key Internal Relationships and Dependencies 46
+3.2.11.2 API Purpose - Further Elaboration 47
+3.2.11.2.1 BIO Overview 47
+3.2.11.2.2 BIO MTM 47
+3.2.11.2.3 BIO Database 48
+3.2.11.2.4 BIO Parsers 48
+3.2.11.2.5 BIF Files and Utilities 48
+3.2.11.2.6 Platform Security Compliant Messaging / BIO APIs 49
+3.2.12 Messaging / OBEX MTM APIs 50
+3.2.12.1 Key Internal Relationships and Dependencies 50
+3.2.12.2 OBEX MTM Overview 50
+3.2.12.2.1 OBEX MTM 50
+3.2.12.2.2 IR MTM 51
+3.2.12.2.3 Bluetooth MTM 51
+3.2.12.2.4 OBEX MTM Utils 52
+3.2.12.2.5 Platform Security Compliant Messaging / OBEX MTM APIs 52
+3.2.13 Messaging / GMXML APIs 52
+3.2.13.1 Key Relationships and Dependencies 52
+3.2.13.2 Overview 53
+3.2.13.2.1 GMXML DOM 53
+3.2.13.2.2 GMXML Parser and Composer 53
+3.2.13.2.3 GMXML SMIL DTD (Validator) 53
+4 SECURITY 54
+4.1 DATA CAGING 54
+4.2 BACKUP AND RESTORE 54
+4.3 CAPABILITY RANGES 54
+4.3.1 Capabilities granted to executables 54
+4.3.2 Capabilities granted to DLLs 55
+4.3.3 Capabilities required to use the subsystem 57
+5 FURTHER INFORMATION 59
+5.1 REFERENCES 59
+5.2 OPEN ISSUES 59
+5.3 GLOSSARY 60
+APPENDIX A - EXAMPLE SEQUENCE DIAGRAMS 62
+A.1 COPY TO A REMOTE SERVICE 62
+A.2 SMTP SESSION 64
+A.3 SMTP EMAIL SEND 66
+
+Table of Figures
+Figure 1 Where Messaging Lives 6
+Figure 2 MTM Relationships 11
+Figure 3 External Dependencies 12
+Figure 4 Message Store 13
+Figure 5 Series 60 Inbox List View 14
+Figure 6 Remote and Local Entries 14
+Figure 7 Email Message 15
+Figure 8 Series 60 Message Centre (Composed from 2 screen shots) 17
+Figure 9 UIQ Message Centre 18
+Figure 10 Messaging MTM Structure (light coloured components are part of messaging subsystem) 19
+Figure 11 Nokia 9210 Outbox List View 20
+Figure 12 SendAs Version 1 Dependencies 22
+Figure 13 SendAs Version 2 Dependencies 23
+Figure 14 Schedule Send Dependencies 24
+Figure 15 Watcher Dependencies 25
+Figure 16 Message URL Handler Dependencies 26
+Figure 17 SMS Internal Dependencies 27
+Figure 18 SMS External Dependencies 28
+Figure 19 CMDA SMS Internal Dependencies 31
+Figure 20 CDMA SMS External Dependencies 32
+Figure 19 Email Internal Dependencies 35
+Figure 20 Email External Dependencies 36
+Figure 21 MMS Internal Dependencies 41
+Figure 22 MMS Utilities External Dependencies 42
+Figure 23 MMS Watcher External Dependencies 43
+Figure 24 MMS Client MTM Dependencies 43
+Figure 25 MMS Server MTM Dependencies 44
+Figure 26 BIO Message Internal Dependencies 46
+Figure 27 Bio Parser External Dependencies 47
+Figure 26 BIO Message Dependencies (v9.0) 49
+Figure 28 OBEX Internal Dependencies 50
+Figure 29 OBEX External Dependencies 51
+Figure 30 IR MTM Dependencies 51
+Figure 31 Bluetooth MTM Dependencies 52
+Figure 32 GMXML Dependencies 52
+Figure 33 Sequence Diagram Showing Copying to a Remote Service 62
+Figure 34 Sequence Diagram Showing a SMTP Session 64
+Figure 35 Sequence Diagram Showing SMTP Transactions during Email Send. 66
+1 Introduction
+1.1 Purpose and Scope
+The Messaging Architectural Description details the architecture and APIs exposed by the Messaging Subsystem. This document does not attempt to list all functionality provided by the messaging subsystem. For details on the functionality provided and the specifications implemented by the messaging subsystem see the Messaging Functional Description [R1]. This document describes the general architecture of messaging subsystem. Information related to a particular release version is mentioned with relevant release number.
+2 Subsystem Overview and Background
+The Messaging Subsystem provides an application level API to handle the storage and transport of different message types. It sits between messaging applications and the lower level subsystems which messaging uses for storage and transmission of messages.
+
+Figure 1 Where Messaging Lives
+The message types that messaging currently supports are Email (POP3, IMAP4 & SMTP), SMS, MMS and OBEX. The set of supported message types is extensible at run time by the use of plug-in modules that are responsible for the transmission and storage of a particular message type. This means that the set of components shown communicating with the network cloud depend on the message types installed.
+3 Messaging Architecture and APIs
+3.1 Subsystem components
+The Messaging subsystem components can be split into two categories: those components that form the framework and those that plug into the framework to support specific message types. This section briefly describes each of the components, more detailed descriptions of the components and their dependencies can be found in later sections of this document.
+3.1.1 Framework components
+3.1.1.1 Message Server and MTM architecture
+The message server is the core component in the messaging subsystem. It provides the message store used to contain messages. The Message Type Module architecture also allows plug-ins to add support for new message types to the messaging subsystem.
+Component Description
+messaging\framework\serverexe Executable that links to the server component and starts the message server
+messaging\framework\server Contains classes that make up both the client and server side of the message server API.
+messaging\framework\mtmbase Base classes for the plug-ins that handle the various message types
+3.1.1.2 Schedule Send
+The Schedule Send component is an extension to the framework that provides support for scheduling of operations such as sending messages. Message type modules that wish to support this functionality can use these support components to implement scheduling. For example the SMS MTM uses this to allow scheduled sending of SMS messages.
+Component Description
+messaging\schedulesend\schedulesendmtm Base classes that handle functionality for message server plug-ins that wish to enable scheduling of sending messages.
+messaging\schedulesend\schedulesendexe Executable use to provide schedule send behaviour.
+3.1.1.3 SendAs Version 1
+This version of SendAs is supported in releases pre - v9.0. SendAs provides a high level API for applications that wish to include a “Send As” menu to allow users to send content via one of the message types supported by messaging. The application using the API does not have to be aware of the message type selected by the user. Note the API does not send the messages.
+Component Description
+messaging\sendas High level API to allow creation of messages.
+3.1.1.4 SendAs Version 2
+From v9.0 and onwards the SendAs has been replaced with client server architecture based SendAs server. The client server architecture enhances secured platform implementation. The SendAs server polices the client application. If it is not trusted with required capabilities the SendAs server will refuse the client access. The client MTM for the message type can send a message with user permission even if the client does not have the correct capabilities.
+Component Description
+messaging\sendAsV2 High level API to allow the creation and sending of messages
+
+3.1.1.5 Watcher Framework
+The watcher framework is a lightweight framework to allow plug-ins to wait on events. For example there is an SMS watcher that waits for incoming SMS messages and delivers them to the message store. The watcher framework will only load plug-ins from ROM.
+Component Description
+messaging\framework\watcher Executable that loads and runs watcher plug-ins.
+3.1.1.6 Message URL Handler
+Support for recognising messaging URLs (mailto:, sms:, fax:, mms:), and then launching an editor with a new message.
+Component Description
+messaging\urlhandler\urlhandler An application that parses the URLs and then creates a correctly addressed message and launches a message editor.
+messaging\urlhandler\recogniser Recognisers that map from the URL schemes to the mime types.
+3.1.1.7 Bio Message Framework
+The Bio Message Framework provides a framework that supports plug-ins to handle messages like vCards and Internet access point set-up messages.
+Component Description
+messaging\biomsg\BDB\BIODB Classes to maintain the database of bio registration files.
+messaging\biomsg\BIFU\BIFU Classes for reading and writing bio registration files
+messaging\biomsg\BIOC\BIOC Bio message client MTM, this is in the framework section as it forms part of the bio messaging framework it is also a plug-in to the messaging framework.
+messaging\biomsg\BIOS\BIOS Bio message server MTM, this is in the framework section as it forms part of the bio messaging framework it is also a plug-in to the messaging framework.
+3.1.2 Plug-ins
+3.1.2.1 SMS
+The SMS plug-ins provide application level support for the Short Message Service messages.
+Component Description
+messaging\biomsg\BioWatchers Plug-ins to the watcher framework to listen for SMS, WSP, and WDP messages and deliver them to the global inbox in the message store.
+messaging\sms\clientmtm A plug-in to the message server framework to provide a generic API for creation of SMS messages (SMS Client MTM & SMS utilities)
+messaging\sms\servermtm A plug-in to the message server framework to provide a generic API for sending of SMS messages (SMS Server MTM)
+3.1.2.2 CDMA SMS
+The CDMA SMS plug-ins provide application level support for the CDMA Short Message Service messages.
+Component Description
+messaging\biomsg\BioWatchersCdma Plug-ins to the watcher framework to listen for CDMA SMS messages and deliver them to the global inbox in the message store.
+messaging\sms\multimode\clientmtm A plug-in to the message server framework to provide a generic API for creation of CDMA SMS messages (CDMA SMS Client MTM)
+messaging\sms\multimode\servermtm A plug-in to the message server framework to provide a generic API for sending of CDMA SMS messages (CDMA SMS Server MTM)
+
+3.1.2.3 Email
+The email plug-ins provide support the POP3, IMAP4 and SMTP email protocols and support for parsing and generating plain test, MIME and M-HTML format email messages.
+Component Description
+messaging\email\clientmtms A plug-in to the message server framework to provide a generic API for creation of email messages (IMAP4 SMTP and POP3 Client MTMs & email utilities)
+messaging\email\imapservermtm A plug-in to the message server framework to provide a generic API for access to a remote IMAP4 server (IMAP4 Server MTM)
+messaging\email\smtpservermtm A plug-in to the message server framework to provide a generic API for access to a remote SMTP server (SMTP Server MTM)
+messaging\email\popservermtm A plug-in to the message server framework to provide generic API for access to remote POP3 server (POP3 Server MTM)
+messaging\email\servermtmutils Email utilities for parsing plain text and MIME email messages. It also provides an abstraction of the TCP/IP sockets for use by the SMTP POP3 and IMAP4 plug-ins.
+messaging\email\autosend An executable that requests SMTP Server MTM to send messages in the outbox. This is used to provide send on next connection functionality and is started by the POP3 and IMAP4 Client MTMs.
+3.1.2.4 OBEX
+The OBEX MTM is a set of plug-ins to the message server that provides support for IR and Bluetooth beaming.
+Component Description
+messaging\obex\btmtm\btclient\group\btcmtm Bluetooth Client MTM
+messaging\obex\btmtm\btserver\group\btsmtm Bluetooth Server MTM
+messaging\obex\irmtm\irclient\group\ircmtm IR Client MTM
+messaging\obex\irmtm\irserver\group\IRSMTM IR Server MTM
+messaging\obex\obexmtm\obexclient\group\obexClientMtm OBEX Client MTM, base classes for the Bluetooth and IR Client MTMs
+messaging\obex\obexmtm\obexserver\group\obexServerMtm OBEX Server MTM, base classes for the Bluetooth and IR Server MTMs
+messaging\obex\obexmtm\obexutil\group\obexMtmUtil OBEX MTM utilities
+3.1.2.5 MMS
+The MMS MTM is a plug-in to the message server that provides support for MMS messages. From v9.0 and onwards MMS MTM and related components are removed.
+Component Description
+messaging\mms\utils MMS Utilities
+messaging\mms\servermtm MMS Server MTM
+messaging\mms\mmswatcherplugins MMS plug-ins to WAP push framework to handle reception of MMS notifications
+messaging\mms\codec MMS utilities for handling MMS codecs
+messaging\mms\clientmtm MMS Client MTM
+3.1.2.6 GMXML
+GMXML is a parser/generator for SMIL presentations for MMS messages.
+Component Description
+messaging\GMXML\XMLParser XML parser designed for parsing of SMIL messages
+messaging\GMXML\XMLDom XML document object model designed for parsing of SMIL messages
+messaging\GMXML\SMILdtd SMIL DTD
+3.1.2.7 Bio Message Plug-ins
+These parsers plug into the bio messaging framework to handle specific types of bio message.
+Component Description
+messaging\biomsg\cbcp\CBCP Compact business card parser
+messaging\biomsg\enp\ENP Email notification parser
+messaging\biomsg\gfp\gfp General file parser
+messaging\biomsg\iacp\IACP Nokia Smart Message Internet Access Parser
+messaging\biomsg\wapp\wapp Nokia/Ericsson OTA Parser
+3.1.2.8 PCMTM
+Plug-in to the message server that provided email synchronisation with a PC. This component has been deprecated in 8.0a and will not been documented in the API section below.
+3.1.2.9 Fax
+Plug-in to the message server that provides fax support. This component has been deprecated in 8.0a and will not been documented in the API section below.
+
+3.2 General Description
+3.2.1 Messaging / Message Server and MTM Architecture APIs
+3.2.1.1 Key Internal Relationships and Dependencies
+
+Figure 2 MTM Relationships
+Figure 2 shows the relationship between the Message Server and the MTM plug-ins. The grey classes are realisations of the MTM interfaces defined by the messaging framework. The message server depends on the Server MTM interface. Messaging Clients depend on the Client, UI and UI Data MTM interfaces and the Message Server Client API.
+3.2.1.2 Key External Relationships and Dependencies
+
+Figure 3 External Dependencies
+The grey package representing the messaging client depends on the Client, UI and UI Data interfaces and the Messaging Client API. The message server then depends on:
+• Charconv – Provides character set conversion routines, used to convert encoded message body text to Unicode body text.
+• EStore – Provides API to handle a stream based store used for the messaging index file and the framework classes for the message store files. (omitted from other dependency diagrams as it is implied by the dependency on the message server)
+• F32 – Provides the file server APIs used to access the file system directories in which messaging stores files containing message data. (omitted from other dependency diagrams)
+• BAFL – Provides API to load the correct messaging resource file dependent on the current language and to register the message store index file with the backup server. (omitted from other dependency diagrams)
+• ETEXT – Rich text APIs used to store body text of messages, this rich text format is a Symbian Proprietary format. (omitted from other dependency diagrams)
+• EUSER – Core Symbian OS utilities such as descriptors, arrays, client / server framework, cleanup stack and others (omitted from this and other dependency diagrams).
+• Central Repository – Centralised and secure storage facility for application settings, the message server stores message settings data in the central repository (from v9.0 and onwards).
+Note that debug only dependencies such as the flogger have been omitted from dependency diagrams.
+3.2.1.3 API Purpose - Further Elaboration
+3.2.1.3.1 Message Store
+The message server provides persistent storage of messages and messaging account settings. It does this by providing a message store consisting of a tree of message entries. Multiple clients can access the message store simultaneously. Each entry in the tree can represent an email account, folder of messages, message part, etc.
+
+Figure 4 Message Store
+Figure 4 shows an example message store. The tree is broken down in to three levels:
+1. The Root entry. This entry is just present to tie the tree structure together
+2. Service entries. There is one local service under which local folders and messages are stored, and zero or more remote services. Remote services represent message accounts.
+3. Message & Folder entries. Messages and folders, under the local service represent messages stored on the device. Messages and folders under remote services represent a local copy of messages that are present on a remote server. For example under a POP3 email service you would have copies of all the messages present on the POP3 email server, or under an SMS service you might find SMS messages that are stored on a SIM.
+The message server controls access to the entries in the store. It enforces the three levels therefore attempts to create message or folder entries directly under the root entry will fail.
+The message server provides three types of storage for each entry in the message store:
+• Index entry - TMsvEntry - intended to provide enough information for UI to display list views as shown in Figure 5. This consists of two strings and various flags (read, complete, has attachments etc).
+• Stream based file store - CMsvStore – provides storage of streams of data associated with UIDs. A standard UID is defined for storing body text. Other UIDs are specific. For example the email MTMs define a UID for storage of MIME headers. Compared to the index entry information this is used to store larger objects and is extensible, at the cost of being slower to access. From v9.0 and onwards CMsvStore provides an Attachment API for managing attachments. The Attachment API should be used as attachments can no longer be accessed directly due to Platform Security.
+• Directory of files – normally used for attachments.
+The only storage type that is always present is the index entry. The stream store and the directory of files are optional.
+
+Figure 5 Series 60 Inbox List View
+
+Figure 6 Remote and Local Entries
+As shown in Figure 6 the message store is split into two sets of entries:
+• Remote entries - entries that are representations of entries stored on a remote store .
+• Local entries - entries not linked to a remote store.
+The message server handles changes to local entries; internally it hands off changes to remote entries to the Server MTM that owns that service. Examples of operations that are handed off to Server MTMs are operations involving copying and moving messages to and from a remote service. See section 3.2.1.3.5 or more information on Server MTMs.
+Each entry within the store has a type:
+Folder – Messages can be grouped into folders. Standard folders such as inbox / outbox and user created folders.
+Message – Storage of the content of a message. Message entries can have child entries used to represent the structure of a message.
+Attachment – These represent attachments under a message entry.
+Root & Local Service Entry – There tie the tree structure together. However the Stream store associated with the root entry is sometimes used by UIs to store preferences e.g. default folder views etc.
+Remote Service - Represents a source and / or destination for messages. They are used to store the settings associated with the source / destination.
+Message Type Specific - MTMs can create other message types for use as child entries to messages they own. For example email uses a tree structure, with a message entry as the root, to represent the MIME structure of an email message; it uses folder entries to represent MIME folders and adds new types for entries representing the html body and text body parts of a message. This is shown in Figure 7.
+
+Figure 7 Email Message
+Using the message store to represent message structure allows reuse of the tree structure and makes it very simple to represent one message embedded in another. However this representation introduces performance issues as it results in each message having multiple files associated with it. The message server also keeps all index entries in memory; therefore this representation increases the memory footprint of the message server. Therefore when designing new MTMs we should think about moving away using multiple index entries to store one message in the message store.
+A default message store is created if the message server starts and no message store is present or a corrupt message store is present. The server will initially create a store with just a root entry, and then the server will create any standard folders defined in the resource file msgs.rsc. Finally the server will check whether an executable ‘mailinit.exe’ is present on the system, if it is present the server will launch the executable to allow customisation of the message store. The behaviour of ‘mailinit.exe’ is defined by the UI family of the device. However the typical behaviour is to load each of the UI Message Type Modules and allow each to perform any message type specific initialisation. For example the SMS plug-in typically creates a default service entry.
+
+3.2.1.3.2 Data File Storage (pre - v9.0)
+This section describes the files used by the message server before release v9.0. For information on the files used for release from v9.0 and onwards see section [3.2.1.3.3.1].
+Filename Access Purpose
+?:\system\Mail\index Private Message server index file, internal to message server
+?:\system\Mail\<8 hex digits> Shared via API Message server store files for services, clients access these via a messaging API.
+?:\system\Mail\<8 hex digits>.new Shared via API Temporary file used during committing message server store files.
+?:\SYSTEM\MAIL\<8 HEX DIGITS>_F\* Shared Files associated with a messaging service. These may be accessed directly by clients.
+?:\system\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits> Shared via API Message server store files for message entries, clients access these via a messaging API.
+?:\system\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits>.new Shared via API Temporary file used whilst committing message server store files.
+?:\system\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits>_F\* Shared Files associated with a message entry. These are accessed directly by clients.
+c:\system\data\msgs.ini Private Stores the drive containing the last used message store
+c:\system\Mtm\Mtm Registry v2 Private Cache of registered MTMs, internal to message server
+C:\system\data\sms_settings.dat Shared Copy of the SMS settings.
+?:\System\Mail\StoreInit.tmp Shared Created when message server runs ‘mailinit.exe’, ‘mailinit.exe’ should delete the file when it has successfully completed.
+?:\System\Mail\storedeleted.tmp Shared Created when message server finds and deletes a corrupt message store. Allows the UI to inform the user about the fact that the message store was corrupt.
+Files that are shown as private should only be accessed by the message server or by connectivity process for backup and restore purposes. Files listed as shared are accessed directly by messaging clients. Files listed as shared via API are accessed by client process but only via messaging APIs.
+3.2.1.3.3 Platform Security Compliant Message Store
+From v9.0 and onwards the message store is stored in the message server's data cage and the settings data are placed in the Central Repository. Access to the message store is only possible via message server APIs and not directly through file access. This leads to secured data storage and secured platform.
+3.2.1.3.3.1 Data caging
+Filename Purpose
+?:\private\<SID>\Mail\index Message server index file, internal to message server
+?:\ private\<SID>\Mail\<8 hex digits> Message server store files for services, clients access these via a messaging API.
+?:\ private\<SID>\Mail\<8 hex digits>.new Temporary file used during committing message server store files.
+?:\ private\<SID>\Mail\<8 hex digits>_F\* Files associated with a messaging service. These may be accessed directly by clients.
+?:\ private\<SID>\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits> Message server store files for message entries, clients access these via a messaging API.
+?:\ private\<SID>\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits>.new Temporary file used whilst committing message server store files.
+?:\ private\<SID>\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits>_F\* Files associated with a message entry. These are accessed directly by clients.
+c:\ private\<SID>\data\msgs.ini Stores the drive containing the last used message store
+c:\ private\<SID>\Mtm\Mtm Registry v2 Cache of registered MTMs, internal to message server
+?:\ private\<SID>\Mail\StoreInit.tmp Access via IPC call
+?:\ private\<SID>\Mail\storedeleted.tmp Created when message server finds and deletes a corrupt message store. Allows the UI to inform the user about the fact that the message store was corrupt.
+?\resource\messaging\bif\*.bif Registration data field with UID used in BIO framework
+
+3.2.1.3.4 How message centres display the message store
+The UI normally provides a Message Centre application to display the structure of the message store to the user. Different UIs map the structure to different views.
+
+Figure 8 Series 60 Message Centre (Composed from 2 screen shots)
+Figure 8 shows the top level view of the message centre application on a Series 60 phone. This shows that the message centre has hidden the local service and shows the standard folders at the same level as the services. Also the SMTP, SMS and MMS services are marked as hidden entries in the message store, and so do not appear in the message application.
+
+Figure 9 UIQ Message Centre
+However Figure 9 shows that the UIQ message centre has no 1-1 mapping from the structure in the message store to the structure shown to the user. Each of the message types is displayed as if its messages were contained in separate folders. Under each of these folders the user is presented with an inbox, outbox, send and drafts folder. This filtering is done in the UI layer as this functionality is not provided by the messaging API.
+3.2.1.3.5 Message Type Module Architecture
+
+Figure 10 Messaging MTM Structure (light coloured components are part of messaging subsystem)
+The MTM architecture is the plug-in scheme provided by the messaging framework to integrate different message transports into the message server. The plug-in scheme consists of four interfaces, the UI MTM, UI Data MTM, Client MTM and Server MTM. The messaging client applications loads and uses the first three which are loaded within the client’s process space. The final one the Server MTM is loaded within the message server process. The APIs for the client facing interfaces are extensible via run time type information provided by the QueryCapability API, and the InvokeAsyncFunction and InvokeSyncFunction APIs.
+3.2.1.3.5.1 UI MTM
+Handles requests from clients to view and edit messages or service settings. The MTM handles interaction with the message centre and as such the exact meaning of the APIs is defined by the UI. However common meanings are:
+• Create – Launches the editor with a new message.
+• Edit – If entry is a message this launches the editor; if entry is a service it edits the settings.
+• View – Launches the message viewer.
+• Display progress of an operation.
+3.2.1.3.5.2 UI data MTM
+This MTM provides fast access to UI components such as menu resources and bitmaps required by message centre for list views etc. Again the exact semantics are UI specific.
+There is a resource file defining UI specific functions, for example the Series 60 Messaging UI checks if the resource file contains text to display in the “New Message” menu.
+The UI data MTM also provides mapping from the message store’s TMsvEntry structure to Icons for the messaging list views and a status string, for example in the case of Nokia 9210 it is used in the outbox view to provide strings like “Resend 01:07” as shown in Figure 11. The class also provides functions to determine what operations are possible with a given entry. Examples of this are APIs that return whether the UI should allow the user to reply to the entry or to delete a service entry. The UI then uses this information to determine which menu options / short-cut keys should be allowed when the user selects a given entry.
+
+Figure 11 Nokia 9210 Outbox List View
+3.2.1.3.5.3 Client MTM
+Provides methods to create / reply and forward messages. Functions the Client MTMs provide are:
+• Create Message.
+• Reply to a Message.
+• Forward a Message.
+• Add / remove Addressees.
+• Add / remove body text.
+• Add / remove subject.
+• Add / remove attachments (the API cannot list attachments).
+The Client MTM interface is used by SendAs to provide a way of creating messages independently of the message type.
+3.2.1.3.5.4 Server MTM
+This is the final interface that makes up an MTM plug-in; it differs from the other three plug-ins in that it is loaded into the message server’s process space. The Server MTM provides access to messages under remote services. It handles connecting to remote servers to handle updating the local cache of these messages or to send messages copied to remote services when messages are copied to a remote service. The message server loads and hands off all message store operations that involve entries under a remote entry, these are the entries on the left-hand side of Figure 6.
+Functions that a Server MTM must implement:
+• Copy/MoveToLocal – called when the message server is asked to move or copy an entry that is currently under a remote service. A Server MTM might map this to retrieving a message from a remote mailbox.
+• Copy/MoveFromLocal – called when the message server is asked to move or copy from under the local service to a destination under a remote service. A Server MTM should map this to sending a message if the MTM supports sending.
+• Create, Delete, Change – called when the message server is asked to perform these operations on entries under a remote service.
+• StartCommand – this API provides a means of extending the API the Server MTM provides. Messaging clients pass a command ID and a selection of entries via the message server to the Server MTM. Examples of commands that Server MTMs might provide are: connect and synchronise the entries under a remote service with the messages on an email server, list SMS messages present on the phones SIM. These commands are MTM specific and therefore clients have to know which MTMs support which commands.
+3.2.1.3.5.5 MTM Registration
+MTMs must be registered with the message server so that clients can query what MTMs are present and the server knows which DLL to load to create a given MTM component. MTMs are registered by providing a resource file containing the MTMs UIDs, human readable name, and for each MTM interface it lists a DLL and the ordinal at which the constructor for that interface exists. The message server will search the ROM drive for MTM registration resource files on start-up and it will automatically register any MTMs found. For registration of MTMs installed on other drives, the message server provides an API to register and de-register an MTM. Registration will persist across a reboot, so an MTM only needs to be registered when it is installed on the system.
+When MTMs are registered or unregistered the message server will send events to all messaging clients with a message server session open.
+3.2.1.3.6 Message Server Client API
+The Messaging Server Client API breaks down into two categories: APIs for manipulation of the message store and utility APIs.
+3.2.1.3.6.1 Message Store manipulation APIs
+Requests from clients to modify the message store fall into three categories:
+1. Operations performed entirely with local entries (entries on the right-hand side of Figure 6) for example requests to create entries in the inbox, delete an entry from the drafts folder etc. The message server handles these operations directly.
+2. Operations that involve a remote entry (entries on the left-hand side of Figure 6) for example requests to delete an entry under a POP3 service, or copy a message to an SMTP service. The message server hands these operations off to the Server MTM that owns the service under which the remote entry is stored. The only exception to this rule is the ChangeAttributes API call. This modifies flags on an index entry and is handled by the message server for both local and remote entries. This means that a Server MTM can not rely on being called when flags like the Unread flag are changed. Note that operations can not involve two remote entries; therefore requests to copy entries between a remote service representing one POP3 account to a remote service representing another POP3 account will fail with an error.
+3. Requests that are explicitly directed at a Server MTM via the TransferCommand API. These commands are just passed to the correct Server MTM by looking up the Service ID and MTM of the first message in the selection passed into the command.
+The message server sends events when entries in the message store are modified to messaging clients that have a session open with the server.
+Where the API provides asynchronous functions to modify the message store or transfer a command to a Server MTM, the functions will return a message server operation object. This object can be used to request progress on operation or cancel the operation. Deleting the operation object returned, or closing the session used to make the request will result in the operation being cancelled, therefore a messaging client must remain running until operations it has requested have either completed or they will be cancelled. See appendix A.1 for an example of an asynchronous copy operation. If a Server MTM operating on the same remote service is already handling an operation, the message server will queue the new operation to be handled when the Server MTM becomes free. Requests for progress of operations that are queued will fail with KErrNotReady. The fact that the queue is based on the remote service ID means that you can have two Server MTMs of the same type running at the same time as long as they are operating on different services. So for example you can have two separate POP3 MTMs running synchronising different remote services with email servers.
+3.2.1.3.6.2 Utility APIs
+1. Access to MTM registries – These allow clients to construct instances of the interfaces an MTM implements.
+2. Register / Unregister an MTM.
+3. Change Drive – The message server closes the current message store and opens one on the drive specified. If no message store is present on the drive specified a new message store is created. The message sever can have only one mail store open at a time, if the current mail store is not available because a the disk the mail store is on is not present then the message server will switch the mail store back to the C: drive if an attempt is made to create a message in the inbox.
+4. Launching Editors – This launches the correct editor for a message. It is implemented by delegating the request to the UI MTM
+3.2.2 Messaging / Send As APIs
+3.2.2.1 Key Relationships and Dependencies
+
+Figure 12 SendAs Version 1 Dependencies
+SendAs version 1 and only present in releases before v9.0. SendAs uses the Messaging Client API to access the registry of Client MTMs and construct the Client MTM interfaces. The Client MTMs are then used for composing the message. SendAs requires clients to implement the MSendAsObserver interface. This interface is responsible for checking the return value of the capability queries made to Client MTMs that require a response and also for rendering message types that require it. The only message type supplied by Symbian that requires rendering is Fax, however this MTM has been removed in 8.0a and future releases.
+3.2.2.2 API Purpose - Further Elaboration
+3.2.2.2.1 SendAs API (pre – v9.0)
+The SendAs API makes use of the Client MTM interface and the Messaging Client API to provide a generic API for creating messages. Note despite the name of this component SendAs does not provide an API to send the message.
+SendAs builds a list of registered MTMs, then queries each MTM to check whether it supports sending, removing those MTMs from the list that do not support sending. This list is then provided to the messaging client application. At this point the application can add more constraints on the list of MTMs; for example it can insist the MTM supports Attachments or more than a certain size of body text. SendAs queries each of the MTMs about the requirements and will drop any MTMs from the list that does not meet them. When the application has finished adding requirements it selects one of the MTMs left in the list and uses that to compose the message, adding addresses, a subject, body text and attachments.
+SendAs supports setting a BIO Type for the message that is composed. This tells the transport that the body text represents a BIO Message. This is used when sending business cards from the contacts application as SMS messages; the contacts application puts the vCard data in the body text of the message and the transport sends it correctly. If the MTM in question supports attachments then the vCard is attached to the message.
+A new CSendAs object must be created for each message the application wishes to create.
+3.2.3 Platform Security Compliant SendAs Server (v9.0 onwards)
+
+Figure 13 SendAs Version 2 Dependencies
+From v9.0 and onwards the CSendAs has been replaced by the SendAs server component. The new SendAs server controls the access to the message store. Some of the key SendAs Server features are listed as follows.
+• Send a message once the capability policing of the client application has been completed.
+• Allow client applications to launch an editor for a specified message type.
+• Allow client applications to query the message type.
+The main client-side API is the RSendAs class. The client applications use this to connect to the Send-As server. The session object on the server-side is an instance of CSendAsSession.
+Client applications create messages using the RSendAsMessage API. Opening an RSendAsMessage object on Send-As server session creates a CSendAsMessage object in the Send-As server. There is a one-to-one mapping between an RSendAsMessage object and a CSendAsMessage object. This allows client applications to create multiple messages concurrently.
+
+3.2.4 Messaging / Schedule Send APIs
+3.2.4.1 Key Relationships and Dependencies
+
+Figure 14 Schedule Send Dependencies
+The Schedule Send Server MTM base class depends on the task scheduler to launch the schedule send executable at the correct time. To send the message with a package of data previously passed into the task scheduler by the Server MTM. The schedule send executable then uses the Messaging Client API to actually perform the requested operation.
+3.2.4.2 API Purpose - Further Elaboration
+3.2.4.2.1 Schedule Send
+The Schedule Send functionality is delivered by four components:
+Server MTM Base Class – The base class provides support to Server MTMs that wish to support scheduled operations.
+Data Structures – These are classes used to represent the data associated with a scheduled operation.
+Executable – The executable is run by the task scheduler at the scheduled time.
+The Task Scheduler – This component is part of the system libraries subsystem. Currently the SMS and Fax Server MTMs support scheduled sending.
+Clients request the Server MTM schedules operations via additional commands passed to TransferCommand API; this is passed to the Server MTM via the message server. The Server MTM packages the operation ID, a selection of message IDs, how often to poll for progress and an MTM specific buffer. It then passes this package of data to the task scheduler requesting that it launches the schedule send executable at the correct time with the packaged information.
+When the task scheduler launches the schedule send executable, it unpacks the schedule information and uses the Messaging Client API to request the Server MTM to perform the operation.
+Schedule Send supports a retry mechanism if the operation fails. The Server MTM has a resource file containing a mapping from the error codes the operation can fail with and actions to be performed. For example the SMS resource file has a mapping such that if the operation fails with an error code indicating a bad phone number the SMS will be set to failed and left in the outbox. Whereas if it fails with a error code indicating temporary network failure the send operation will be scheduled to be resent later with a maximum of three retries.
+3.2.5 Messaging / Watchers APIs
+3.2.5.1 Key Relationships and Dependencies
+
+Figure 15 Watcher Dependencies
+The watcher executable’s dependency on the message server is the result of a performance measure. The watcher process creates a message server session before initialising each of the watcher plug-ins and closes the session when it has finished. This keeps the message server running during initialisation avoiding starting and stopping the message server if each watcher plug-in opens and closes sessions.
+3.2.5.2 API Purpose - Further Elaboration
+The watcher framework consists of an executable that is launched when the device boots. The component that is responsible for launching it depends on the UI family. When the watcher.exe is launched it will load each DLL in z:\system\libs\watchers which has a second UID as KWatcherUid and calls the first DLL entry point to construct a CActive object.
+From v9.0 and onwards watcher DLLs are found by scanning the directory \resource\messaging\watchers for registry files. These files contain the name of a watcher DLL that can be loaded from ROM i.e. z:\sys\bin.
+The framework has retry behaviour if the first entry point leaves, in this case the watcher framework will start a timer and try and construct the watcher object 10 seconds later. Five attempts are made before the watcher plug-in is assumed to have failed completely. Once the watcher framework has constructed all the watchers it starts the active scheduler which should never exit.
+Watcher plug-ins typically make a request to another subsystem such that they will be completed when an external event like a fax line ringing or an SMS being received occurs. When the watcher has completed processing the request it will wait for the next event.
+No support for starting / stopping watchers is provided. This is a limitation that makes watchers unsuitable for operations like listening for messages beamed via IR, as the watcher should only run while the IR port is active.
+3.2.6 Messaging / Message URL Handler APIs
+3.2.6.1 Key Relationships and Dependencies
+
+Figure 16 Message URL Handler Dependencies
+3.2.6.2 API Purpose - Further Elaboration
+The Message URL Handler provides support for creating messages and launching messaging editors from URLs such as mailto:infobot@example.com?subject=current-issue. Note there is no dependency between the Message URL Handler application which processes the URLs and the Message URL Handler recognisers which maps from URLs to mime types.
+3.2.6.2.1 Message URL Handler Application
+This is a Symbian OS application that registers with the application framework that it can handle the mime types: x-epoc-url/fax, x-epoc-url/mailto and x-epoc-url/sms. When launched with a URL it will parse the URL to retrieve the address and other header fields and then use the SendAs API to create a new message with the correct address, headers etc. The application then uses the APIs in the MturUtils class provide by the mtmbase component in the messaging framework to launch the correct editor for the given message type. The application is marked as hidden and therefore should not be listed by UIs in application browsers.
+3.2.6.2.2 Message URL Recognisers
+This is a plug-in to the recogniser framework it will be called when the application framework wishes to recognise a file. Recognisers are called with the file name, in this case a URL, and a buffer containing the start of the file. The message URL recogniser compares the start of the URL with the URL schemes it recognises, if it finds a URL scheme it knows about it maps it to a mime type. The recogniser ignores the buffer passed in.
+Schemes recognised:
+Scheme Mime type
+mailto: X-Epoc-Url/mailto
+fax: X-Epoc-Url/fax
+sms: X-Epoc-Url/sms
+mms: X-Epoc-Url/mms
+See the application framework architectural description for more information on recognisers [R2].
+3.2.7 Messaging / SMS APIs
+3.2.7.1 Key Internal Relationships and Dependencies
+
+Figure 17 SMS Internal Dependencies
+3.2.7.2 Key External Relationships and Dependencies
+
+Figure 18 SMS External Dependencies
+3.2.7.3 API Purpose - Further Elaboration
+3.2.7.3.1 SMS Watchers
+The SMS watchers are made up of two watchers, the nbswatcher.dll and the wapwatcher.dll, and some common base classes in biowatcher.dll. The watchers listen for incoming messages from the SMS stack, part of the nbsprotocols subsystem [R3], and the WAP stack part of the WAP-Stack subsystem [R4].
+3.2.7.3.1.1 NBS Watcher
+The NBS watcher handles reception of SMS messages. When initialised by the watcher framework (see section 3.2.4) the watcher queries the bio messaging database for bio messages that are listed as having a type of ENbs. For each of these bio messages the watcher creates an object that opens a connection to the SMS stack and waits for the particular message type. The message types are either defined by the port number the message will be received on or by a string to watch for at the start of the message. For example Internet Access Configuration Point messages are start with “//SIAP11” and vCards are received on port 226. Finally the watcher listens for all other messages received from the SMS stack.
+When the NBS Watcher receives a non-class 2 SMS message it creates a new entry under the global inbox in the message store. For class 2 messages the entry is created in the class 2 folder as defined by the SMS settings, this may also be the global inbox. The details field of the entry is used to store the phone number of the incoming message or the name of the sender if the watcher finds a match for the phone number in the contacts database. The description field is used to store the first N characters of the SMS message, where N is defined in the SMS settings, or for bio messages the description as retrieved from the bio database. Bio messages also have the BioType field set to the UID of the bio message as retrieved from the bio database. The CSmsHeader class, which is a wrapper around the CSmsMessage class provided by the nbprotocols subsystem [R3], is used to externalise the SMS message to the entry’s CMsvStore. The watcher also places a copy of the body text of the message in the rich text stream of the entry’s CMsvStore.
+The NBS Watcher is also responsible for handing special SMS types including:
+• Replace Type Messages – When the watcher receives a message of this type it will scan the folder the message would have been delivered to for messages that have a matching protocol ID and from address. For each of the messages it checks whether the time stamps from the service centre and discards the older message.
+• Message Indications – The watcher can listen for incoming message waiting indications. The CSmsSettings class defines whether the watcher will listen and whether it will deliver the messages to the inbox or discard them. If the watcher is configured to listen for messages then it will use the SMS utilities in the SMS Client MTM to decode the message to determine the notification type and number of messages, e.g. 3 Email messages waiting, the strings for these messages are in the smss.rss resource file.
+• Delivery Reports – As with Message Indications the watcher can be configured to listen for these and again the SMS utilities get a string from the smss.rss resource file to put in the description field.
+The NBS Watcher handles changes to the bio database using the observer mechanism provided by the bio message database to observe when bio message types are added or removed and starting or stopping the object watching for that bio message type.
+3.2.7.3.1.2 WAP Watcher
+The WAP watcher listens for incoming messages from the WAP stack using the WAP message API [R4]. To determine ports to use to listen for messages the watcher queries the bio message database for bio message types EWsp, EWspSecure, EWap, EWapSecure and registers as an observer of the bio database and so will listen for new bio message with these types as they are added. The watcher stores the messages in the global inbox tagged with the bio type listed in the bio message database.
+3.2.7.3.2 SMS Client MTM
+The SMS Client MTM implements the standard set of Client MTM APIs described in Client MTM. In addition it provides:
+• Access to the CSmsHeader object that is used to represent the SMS message.
+• Access to the SMS settings stored in the associated SMS service.
+• The APIs required by Send As to allow Send As to create SMS messages including setting the bio type of the message to allow clients of Send As to send bio messages such as vCards and vCals. The data of the bio message is stored in the body text of the SMS message.
+• Simple check for valid SMS addresses, and SMS address is considered valid if it contains at least one digit.
+• Reading and writing SIM parameters.
+3.2.7.3.3 SMS Utilities
+These provide:
+• Classes to represent and store SMS messages (CSmsHeader), and SMS settings (CSmsSettings, CSmsMessageSettings) and a SMS number (CSmsNumber).
+• The CSmsHeader class contains and allows clients to access the CSmsMessage class that the nbsprotocols subsystem provides. This contains the entire SMS message and not just the header.
+• Functions to generate descriptions and details fields to store with SMS messages, including decoding special messages such as message indication and status report messages, reading resource file for descriptions strings of special messages, using the contacts database to replace phone numbers with names.
+• API to validate a GSM number.
+• Find the TMsvId of the SMS service entry.
+3.2.7.3.4 SMS Server MTM
+3.2.7.3.4.1 Sending Messages
+The SMS Server MTM handles sending of SMS and WAP messages via the SMS stack and the WAP stack. To support this it implements the CopyFromLocal API inherited from the Server MTM base class. It implements this as sending SMS messages and moving successfully sent messages to the Sent folder. When sending the SMS message the Server MTM checks the bio type of the message and uses the bio database to check the transport type for the bio message. The MTM supports ENbs that is sent via the SMS stack and EWap, EWapSecure that are sent via the WAP stack. The MTM does not support EWsp or EWspSecure although the watchers do support receiving them.
+If a message fails to send, sending is retried according to the settings in the smss.rss resource file as described in the schedule send section 3.2.3.
+3.2.7.3.4.2 Scheduling Messages
+The SMS Server MTM implements scheduled sending API by sub-classing from the schedule send Server MTM (see section 3.2.3). It accepts requests from clients either via the SMS Client MTM InvokeAsync API or via the CMsvSession::TransferCommand API to schedule messages to be sent or to delete existing schedules. When it receives a request to schedule a message it packages up the command and uses the scheduled send functionality to request that the task scheduler ask it to send the messages at a future point in time.
+3.2.7.3.4.3 Phone Store
+The phone store is the name given to storage of SMS messages outside of the message store. In the case of GSM phones this is the SIM. The SMS Server MTM accepts requests from clients to copy/move messages to and from the SIM and delete messages from the SIM. For example when copying to the SIM it packages up the SMS message and passes it to the SMS stack with a request to write it to the SIM. If the class2 folder has been set in the SMS settings class then the Server MTM will copy the SMS message to the SIM and then update the SMS message in the message store with details of the slot on the SIM that has been used to store the SMS and the fact that it is stored on the SIM.
+3.2.7.3.4.4 SIM Parameters
+The Server MTM provides functions to read / write SIM parameters, again these requests are passed to the SMS stack to be processed.
+3.2.8 Messaging / CDMA SMS APIs
+3.2.8.1 Key Internal Relationships and Dependencies
+
+Figure 19 CMDA SMS Internal Dependencies
+3.2.8.2 Key External Relationships and Dependencies
+`
+Figure 20 CDMA SMS External Dependencies
+3.2.8.3 API Purpose - Further Elaboration
+3.2.8.3.1 CDMA SMS Watchers
+The CDMA SMS watchers are made up of six watchers, the cdmanbswatcher.dll, vmnwatcher.dll, wemtwatcher.dll, wmtwatcher.dll, wptwatcher.dll, and the wapwatcher.dll, and some base classes in biowatcher.dll and cdmasocketwatcher. While the WAP watcher is common for both GSM and CDMA, the other watchers: CDMA NBS watcher, VMN watcher, WEMT watcher, WMT watcher, and the WPT watcher are used for CDMA only. The watchers listen for incoming messages from the CDMA SMS stack, part of the nbsprotocols subsystem [R3], and the WAP stack part of the WAP-Stack subsystem [R4].
+3.2.8.3.1.1 CDMA NBS Watcher
+The CDMA NBS watcher is similar to the NBS watcher and it handles bio messages defined in bio database. The CSmsHeader class is extended to wrap around the CCdmaSmsMessage class provided by the nbprotocols subsystem [R3], and is used to externalise the CDMA SMS message.
+For handling special CDMA SMS type, the CDMA NBS watcher is responsible for handling Message Indications as described in section 3.2.7.3.1.1 NBS Watcher.
+3.2.8.3.1.2 WAP Watcher
+The GSM WAP watcher is used to handle CDMA WAP message as well. The WAP watcher listens for incoming messages from the WAP stack, which can listen from the CDMA SMS stack or GSM SMS stack as appropriate. See 3.2.7.3.1.2 for more info about WAP watcher.
+3.2.8.3.1.3 Other CDMA Watchers
+The VMN watcher, WEMT watcher, WMT watcher and WPT watcher are CDMA watchers that handle reception of CDMA SMS messages. All CDMA SMS messages are associated with a teleservice. Therefore, each of the CDMA watchers is responsible for handling one teleservice: VMN watcher handles VMN SMS messages, WEMT watcher handles WEMT SMS messages, WMT watcher handles WMT SMS messages, and WPT watcher handles WPT SMS messages. The CSmsHeader class is reused to externalise the CDMA SMS message.
+The CDMA watchers are also responsible for handling special SMS types including:
+• Duplicate Message – When the watcher receives a duplicate message, it will discard the duplicate message as defined by the CDMA service settings.
+• User Acknowledge – The watcher can listen for user acknowledgment message of its teleservice type.
+• Delivery Acknowledge – The watcher can listen for delivery acknowledgment message of its teleservice type.
+• Read Acknowledge – The watcher can listen for read acknowledgment message of its teleservice type.
+3.2.8.3.2 CDMA SMS Client MTM
+The CDMA SMS Client MTM implements the standard set of Client MTM APIs described in Client MTM. In addition it provides:
+• Access to the CSmsHeader object that is used to represent the SMS message.
+• Access to the SMS settings stored in the associated SMS service. These settings are store in file store pre v9.0 but stored in Central Repository from v9.0 onwards.
+• The APIs required by Send As to allow Send As to create SMS messages including setting the bio type of the message to allow clients of Send As to send bio messages such as vCards and vCals. The data of the bio message is stored in the body text of the SMS message.
+• Simple check for valid SMS addresses, and SMS address is considered valid if it contains at least one digit.
+• Reading and writing SMS messages to R-UIM.
+3.2.8.3.3 CDMA SMS Utilities
+The CDMA version of SMS utilities are binary compatible with the GSM version of SMS utilities. But the classes that store SMS Message (CSMSHeader), and SMS settings (CSmsSettings, CSmsMessageSettings) and SMS number (CSmsNumber) are extended to store CDMA information. The CSmsHeader class is extended to contain and allow clients to access the CCdmaSmsMessage in addition to the CSmsMessage. Other functions provided by the GSM SMS Utilities is also provided by the CDMA version of SMS utilities, see 3.2.7.3.3 for information about GSM SMS Utilities.
+3.2.8.3.4 CDMA SMS Server MTM
+3.2.8.3.4.1 Sending Messages
+The CDMA SMS Server MTM handles sending of CDMA SMS and WAP messages via the CDMA SMS stack and the WAP stack. To support this it implements the CopyFromLocal API inherited from the Server MTM base class. It implements this as sending SMS messages and moving successfully sent messages to the Sent folder. When sending the CDMA SMS message the Server MTM will use the appropriate teleservice type. The MTM supports ENbs that is sent via the SMS stack and EWap, EWapSecure that are sent via the WAP stack. The MTM does not support EWsp or EWspSecure although the watchers do support receiving them.
+If a message fails to send, sending is retried according to the settings in the smss.rss resource file as described in the scheduled send section 3.2.4.
+3.2.8.3.4.2 Scheduling Messages
+The CDMA SMS Server MTM implements scheduled sending API by sub-classing from the schedule send Server MTM similar to implemented in the GSM SMS Server MTM. See 3.2.7.3.4.2 for more information.
+3.2.8.3.4.3 Phone Store
+In the case of CDMA phones, phone store can be phone-based storage or R-UIM based storage. The CDMA SMS Server MTM accepts requests from clients to copy/move messages to and from the phone/R-UIM and delete messages from the phone/R-UIM. For example when copying to the R-UIM it packages up the SMS message and passes it to the CDMA SMS stack with a request to write it to the R-UIM.
+3.2.8.3.5 Configuration for using CDMA SMS MTM
+The CDMA messaging components currently only support single mode, but it is designed such that it can become multimode in the future. Currently, -Dcdma option is used to for selecting CDMA mode for using emulator and building ROM.
+
+
+3.2.9 Messaging / Email APIs
+3.2.9.1 Key Internal Relationships and Dependencies
+
+Figure 19 Email Internal Dependencies
+
+3.2.9.2 Key External Relationships and Dependencies
+
+Figure 20 Email External Dependencies
+3.2.9.3 API Purpose - Further Elaboration
+3.2.9.3.1 Email Overview
+The Email plug-ins consist of a set of utilities and MTMs for POP3, IMAP4 and SMTP. For each email account a pair of services entries is created in the message store. For a POP3 account there will be an SMTP service and a POP3 service, for an IMAP4 account there will be an SMTP service and as IMAP4 service. These entries are used to store the settings for the email transport. Each of the service entries has its related ID set to the other member of the pair. The SMTP service is created invisible so the user only sees the POP3 or IMAP4 service entry, copying a message to the SMTP service will cause the SMTP Server MTM to attempt to send the message. The POP3 and IMAP4 MTMs provide functionality to synchronise with a remote email server this is achieved by extending the Client MTM interface via the InvokeAsync API. Synchronisation of a POP3 or IMAP4 account will result in copying headers and optionally body text and attachments from the email server and creating message entries under the POP3 or IMAP4 service entry.
+Email messages are represented in a common format whether they are being sent via SMTP or downloaded via POP3 or IMAP4. The email client utilities provide the classes for creating and manipulating the entry structure used to store emails. The email server side utilities provide classes to convert between the entry structure used to store emails in the message store and RFC2822 email messages sent to SMTP servers and retrieved from POP3 servers. IMAP4 email messages are parsed by the email server and the IMAP4 Server MTM requests and stores the individual parts of the messages.
+3.2.9.3.2 Email Client Utilities
+The email client utilities are part of the imcm DLL and provide classes for:
+• Storage of email messages including mime headers, RFC2822 headers, attachments, body text and encoding information in the message store
+• Manipulating email messages, for example adding attachments, replying etc.
+• To wrap up the character converters used to convert between standard character sets and Unicode. These make use of the charconv component that is part of the system libraries subsystem.
+• Storage of Email settings in the message store.
+• Progress information for email operations.
+The utilities are used directly by clients to access parts of email messages for display. CImEmailMessage provides the functionality used by clients displaying email messages, including listing attachments, getting body text and resolving URIs in M-HTML messages.
+The Email Client MTMs use the utilities when they are asked to create, reply to and forward messages CImEmailOperation provides the functionality to perform these operations. Each email message is represented by a parent message entry and then entries to represent mime folders and mime parts, see Figure 7 for an example, so adding or deleting mime parts involves walking the tree of entries and inserting / removing entries as appropriate.
+3.2.9.3.3 Email Server MTM Utilities
+The Email Server MTM Utilities are responsible for generating and parsing of RFC2822 format email messages and providing an API to wrap up a TCP/IP connection to a remote email server.
+• Parsing of RFC2822 Email Messages – The utilities provide an API that accepts the text of an RFC2822 email message a line at a time and stores the email message in messaging’s internal format for email messages. See the Email Client Utilities for details of this format. The API handles storing of RFC2822 headers, MIME headers, decoding of Base64 encoded or uuencoded attachments and decoding of text received in character sets supported by the charconv component. This API is only accessible to Server MTMs, as it requires classes that can only be instantiated while running within the message server process. See the Messaging Functional Specification [R1] for detail on which email specifications the utilities support.
+• Generation of RFC2822 Email Messages – The utilities provide an API to convert an email in messaging’s internal format into an RFC2822 email message. The API provides access to the RFC2822 text a line at a time for streaming to an SMTP server. The exact format of the email depends on the settings passed in; the API can generate plain RFC2822 email messages with uuencoded attachments, MIME email messages with Base64 encoded attachments, or M-HTML email messages with Base64 encoded attachments. See the Messaging Functional Specification [R1] for detail on which email specifications the utilities support.
+• TCP/IP socket wrapper – The utilities provide a class that abstracts a TCP/IP socket supplied by the networking subsystem into an API that supports sending and receiving lines of text to / from a remote server. This API is used to connect to remote email servers by each of the email Server MTMs. The API can either create insecure or secure sockets enabling the SSL encryption provided by the networking subsystem. It also supports changing an insecure socket into a secure socket, this enables the email Server MTMs to implement email protocols where the initial connection to the server is insecure and then a secure socket is negotiated before sending or requesting any sensitive information.
+3.2.9.3.4 POP3 MTMs
+The POP3 MTMs implements the functionality to synchronise the local message store with a remote POP3 email server.
+3.2.9.3.4.1 Client MTM
+The POP3 Client MTM implements the standard Client MTM APIs and other extensions:
+• Reply to, forward – These are accessible via the ReplyL and ForwardL APIs of a Client MTM and are implemented as calls to the email utilities class CImEmailOperation.
+• Reply to, forward, create new messages, create receipts and forward as attachment – These are accessible as commands available via the InvokeAsyncFunction API of the Client MTM, they are implemented as calls to CImEmailOperation.
+• Connecting, disconnecting and copying email while connected – These operations are accessible as commands available via the InvokeAsyncFunction API of the Client MTM, they are implemented as calls to the POP3 Server MTM.
+• Querying connection status – This command lets clients know whether the POP3 Server MTM is connected to an email server, and is available via the InvokeAsyncFunction API of the Client MTM. The Client MTM requests the information from the Server MTM.
+• Compound operations – The Client MTM provides functionality to wrap up connecting to email servers, copying / moving new messages or a selection of messages, and then optionally disconnecting. These commands are available via the InvokeAsyncFunction API of the Client MTM. The Client MTM implements this by using the CImPOP3GetMail class which requests the correct sequence of operations from the Server MTM, waiting for each operation to complete before requesting the next one.
+• Send on next connection If the Client MTM gets a request to connect to an email server it will check whether the POP3 settings. If send on next connection is requested it will launch the autosend.exe executable (see section 3.2.7.3.7) to handle sending messages waiting in the outbox.
+• Offline operations – The POP3 Client MTM has a command to cancel offline operations, this is available via the InvokeAsyncFunction API of the Client MTM. The Client MTM passes the request to the Server MTM.
+3.2.9.3.4.2 Server MTM
+The POP3 Server MTM handles the communication with the remote POP3 server and implementation of the POP3 protocol. The MTM uses CImTextServerSession to handle the communication with the email server and CImRecvConvert to parse the email messages downloaded, both are provided by the Email Server MTM Utilities.
+• Connect – The POP3 Server MTM will open a socket to the email server using CImTextServerSession and login user the username / password in the POP3 settings. After a successful connection the Server MTM will attempt to synchronise the current state of headers stored on the email server with the set stored in the message store and then start any pending offline operations. After the connect operation has completed the Server MTM will inform the message server that it is expecting more operations via the CommandExpected API and therefore the message server will not delete and unload the Server MTM.
+• Populate Message – The POP3 Server MTM treats requests to copy a message from and to the POP3 service as a request to download the full message.
+• Offline operations – When the POP3 Server MTM receives a request to copy, move, or delete and is not connected to a POP3 email server the Server MTM will store the operation in the CMsvStore of the entry being modified and perform the operation on the next connection to the email server.
+• Disconnect – When disconnecting from a remote email server the POP3 MTM will run any pending offline operations stored. After the disconnect operation completes the Server MTM will allow the message server to delete and unload the Server MTM by setting the CommandExpected API to false.
+3.2.9.3.5 IMAP4 MTMs
+The IMAP4 Server MTM implements the functionality to synchronise the local message store with a remote IMAP4 email server.
+3.2.9.3.5.1 Client MTM
+The IMAP4 Client MTM implements the standard Client MTM APIs and other extensions:
+• Connecting, disconnecting, synchronising, un/subscribing folders – These operations are accessible as commands available via the InvokeAsyncFunction API of the Client MTM, they are implemented as calls to the IMAP4 Server MTM.
+• Send on next connection – If the Client MTM gets a request to connect to an email server it will check whether the IMAP4 settings. If send on next connection is requested it will launch the autosend.exe executable (see section 3.2.7.3.7) to handle sending messages waiting in the outbox.
+• Reply to, and forward messages – These are accessible via the ReplyL and ForwardL APIs of a Client MTM and are implemented as calls to the email utilities class CImEmailOperation.
+• Reply to, forward, create new, create receipt, forward as attachment – These are accessible as commands available via the InvokeAsyncFunction API of the Client MTM, they are implemented as calls to CImEmailOperation.
+• Querying connection status – These commands let clients know whether the IMAP4 Server MTM is connected to an email server and whether it is currently processing a request. They are available via the InvokeAsyncFunction API of the Client MTM. The Client MTM requests the information from the Server MTM.
+• Compound Connection and synchronisation – The IMAP4 Client MTM provides a compound operation that connects and synchronises with an IMAP4 server. This operation is implemented as a client side object that combines requests to the IMAP4 Server MTM. The client side operation can complete the client request either after the connection, after the connection + sync or after the connection + sync + disconnect. The client will keep requesting that the inbox be resynchronised at a configurable interval so new messages received in the inbox on the server will appear under the IMAP4 inbox. The CImapConnectAndSyncOp class handles these compound operations.
+• Compound Connect and copy / move / populate messages – The IMAP4 Client MTM provides a compound operation that connects to an IMAP4 server and copies moves or populates messages. The implementation is provided by the CImImap4GetMail class which makes calls back into the IMAP4 Client MTM.
+• Offline operations – The IMAP4 Client MTM has a command to cancel offline operations, this is available via the InvokeAsyncFunction API of the Client MTM. The Client MTM passes the request to the Server MTM.
+3.2.9.3.5.2 Server MTM
+The IMAP4 Server MTM handles the communication with the remote IMAP4 server and implementation of the IMAP4 protocol. The MTM uses CImTextServerSession to handle the communication with the email server. The IMAP4 Server MTM opens two connections to the IMAP4 server this enables users to download messages while the Server MTM is performing a background synchronisation if requested by the Client MTM.
+• Connect – The IMAP4 Server MTM will open a socket to the email server using CImTextServerSession and login using the username / password in the IMAP4 settings. After a successful connection the Server MTM will optionally attempt to synchronise the current state of headers stored on the email server with the set stored in the message store and then start any pending offline operations. After the connect operation has completed the Server MTM will inform the message server that it is expecting more operations via the CommandExpected API and therefore the message server will not delete and unload the Server MTM.
+• Copy, Move messages – The IMAP4 Server MTM supports copying and moving messages between folders on the IMAP4 server and between the IMAP4 server and local folders.
+• Delete messages – The IMAP4 Server MTM will mark the email as deleted on the server; however it will not be deleted until the IMAP4 Server MTM disconnects from the server.
+• Folders – The IMAP4 Server MTM will allow folders to be subscribed, unsubscribed, renamed, copied, moved, and created within the IMAP4 service. Subscribing to a folder means that it will be visible to the user and synchronised with the remote server. The inbox is always subscribed.
+• Offline operations – When the IMAP4 Server MTM receives a request to copy, move, or delete and is not connected to an IMAP4 email server the Server MTM will store the operation in the CMsvStore of the entry being modified and perform the operation on the next connection to the email server.
+• Disconnect – When disconnecting from a remote email server the IMAP4 MTM will run any pending offline operations stored. After the disconnect operation completes the Server MTM will allow the message server to delete and unload the Server MTM by setting the CommandExpected API to false.
+
+3.2.9.3.6 SMTP MTMs
+The SMTP MTMs provide functionality to send email messages. They are made up of the Client MTM that is part of the imcm DLL and the Server MTM.
+3.2.9.3.6.1 Client MTM
+The SMTP Client MTM implements the standard Client MTM APIs including the functions required to allow clients of Send As to create email messages.
+3.2.9.3.6.2 Server MTM
+The SMTP MTMs provide functionality to send email messages; it interprets requests to copy entries to an SMTP service as a request to send those messages. In addition it responds to two extended commands via the StartCommand Server MTM interface. These commands are KSMTPMTMIsConnected that responds with whether the Server MTM is currently connected to a remote SMTP server and KSMTPMTMSendOnNextConnection which performs the same operation as copying a selection of messages to an SMTP service. The only difference between the copy operation and the KSMTPMTMSendOnNextConnection operation is that the latter can be called without a selection of messages.
+When the Server MTM receives a request to send messages it builds a selection of messages consisting of the messages passed into the operation and any messages waiting in the outbox to be sent. To determine which messages in the outbox are waiting to be sent the SMTP server checks for messages that have the same service ID as the destination of the send operation and have a sending state of KMsvSendStateWaiting, KMsvSendStateScheduled or KMsvSendStateResend. This means that any request to send messages may result in more messages being sent than explicitly listed in the selection passed to the send operation.
+The Server MTM restores its settings from the SMTP service it has been asked to copy the messages to. Then it connects to the SMTP server using the CImTextServerSession class in the Email Server MTM Utilities, passing in the SMTP server address and TCP/IP port number from the SMTP settings. Then for each message to be sent the Server MTM uses the Email Server MTM utilities to generate an RFC2822 format message to send to the SMTP server, the RFC2822 text is generated on the fly as the data is sent to the SMTP server. If the SMTP server accepts the message to be sent then the Server MTM moves the message to the sent folder and sets its sending state to sent. If the SMTP server rejects the message then the Server MTM leaves the message in the outbox and sets the sending state to failed. Separate emails are generated for BCC recipients to ensure that the SMTP server doesn’t incorrectly include BCC recipients in emails sent to addresses in the To and CC fields of the email.
+3.2.9.3.7 Autosend
+The Autosend component is an executable that is kicked off by the POP3 and IMAP4 Client MTMs if the send on next connection setting is set. This executable will just make a request to the SMTP Server MTM to send messages associated with the SMTP service related to the POP3 or IMAP4 service, wait for the operation to finish and then exit.
+3.2.10 Messaging / MMS APIs
+The MMS module has been removed from v9.0 and onwards.
+3.2.10.1 Key Internal Relationships and Dependencies
+
+Figure 21 MMS Internal Dependencies
+3.2.10.2 API Purpose - Further Elaboration
+3.2.10.2.1 MMS Overview
+The MMS MTM provides functionality for creating, accessing, sending and receiving MMS messages. Messages are sent and received without the client application needing to open or close any kind of session. The management of the MMS session is handled entirely within the MTM.
+MMS clients are alerted when a new message is available for download via the WAP Push mechanism. A WAP push watcher is provided to handle these notifications. After the notification the message can be downloaded over WSP or HTTP. Messages are sent by posting the data over WSP or HTTP. The Symbian MMS implementation can handle sending or receiving MMS message over either protocol.
+MMS messages are based on the MIME format but are binary encoded using WSP. Note that MMS messages are encoded in this way even if they are posted over HTTP as opposed to WSP. The codec component is responsible for this encoding and decoding.
+3.2.10.2.2 MMS Utilities
+3.2.10.2.2.1 Key External Relationships and Dependencies
+
+Figure 22 MMS Utilities External Dependencies
+The MMS utilities provide the message and settings encapsulation classes. The MMS settings and messages are stored in the message store, the MMS utilities provide the interfaces to access this data.
+3.2.10.2.2.2 Settings
+The settings functionality provided by the MMS utilities allows the messaging client to persist MMS settings in the message store. Supported settings include:
+ MMSC (MMS server) address
+ WSP or HTTP transport
+ Autofetch messages on notification
+ Preferred IAP for the MMS network connection
+The settings functionality is also used by the server MTM to retrieve the settings prior to message sending or fetching.
+3.2.10.2.2.3 Message Encapsulation
+The message classes provide the message access functionality. Messages can be created, stored, restored and read using these classes. Functionality includes:
+ Adding media objects to the message
+ Enumerating through media objects
+ Adding recipients, subject line, etc. to a message
+ Adding other headers to the message, e.g. expiry date
+ Finding the appropriate media object for a given URI in the SMIL part (URI resolving)
+The message data is stored in the message store using one entry per message regardless of the number of media objects added to the message. This is preferable to using multiple message entries as it is faster and uses less disk space.
+Most of the message access code is common whether it is being used on the client or server side, however some parts of it are specific. For this reason it is essential that the appropriate client or server side CMmsMessage derived class is used.
+3.2.10.2.3 MMS Watcher
+3.2.10.2.3.1 Key External Relationships and Dependencies
+
+Figure 23 MMS Watcher External Dependencies
+
+The MMS watcher plug-in is responsible for intercepting incoming MMS notifications and delivery reports then taking the appropriate action. It is implemented as a WAP Push watcher plug-in.
+When an MMS notification is received an MMS entry is created in the inbox using the MMS utilities. At this point the entry has its incomplete flag set. If the settings have the autofetch option selected then the MMS watcher initiates the fetch operation via the MMS client MTM.
+If a delivery report is received then the delivered flag is set on the appropriate sent message. If an outgoing message was sent to several recipients then there will be several delivered flags. A delivery report from each recipient will set the appropriate delivered flag.
+3.2.10.2.4 MMS Client MTM
+3.2.10.2.4.1 Key External Relationships and Dependencies
+
+Figure 24 MMS Client MTM Dependencies
+As with most other MTMs the MMS client MTM provides access to the server MTM functionality for messaging clients. It also implements the Send-As interface and reply and forward functionality.
+3.2.10.2.4.2 Send-As Implementation
+The Client MTM Send-As interface is implemented in the MMS Client MTM. The implementation differs slightly from other MTMs because additional presentation content may be generated depending on the media objects that are added. When simple combinations of images, sounds and text are added a SMIL presentation is generated to link them together. This is preferable to simple adding the objects as attachments where some clients render them as a list of files and others fail to render them at all.
+The SMIL data is constructed using templates stored in resource files, the GMXML (SMIL) composer is not used.
+3.2.10.2.4.3 Reply / Forward
+The Client MTM can be used to create replies to received messages or to create forwarded responses. The reply and forwarding operations are performed asynchronously.
+3.2.10.2.5 MMS Server MTM
+3.2.10.2.5.1 Key External Relationships and Dependencies
+
+Figure 25 MMS Server MTM Dependencies
+The Server MTM is the most complicated part the MMS implementation. It handles all of the state information required to send or fetch MMS messages. It is also responsible for managing the HTTP or WSP session and the connections to the phone network.
+3.2.10.2.5.2 Operations
+All MMS server MTM functionality is encapsulated in operations. An operation consists of the setup of a session, the sending, fetching and acknowledgements when appropriate, it then closes the session. The messaging client initiates an operation with a single call to the Client MTM, there is no need for the messaging client to explicitly establish the session or to know about the internal states. However, these internal states are available to the messaging client via the progress structure if this level of user feedback is required.
+Two types of operation are supported, background and foreground:
+A maximum of one foreground operation can be running at any one time. The messaging client can poll the server MTM for the progress of a running foreground operation, likewise it can cancel it if necessary.
+A background operation does not support progress information and can not be cancelled by the messaging client. It is possible to initiate background operations even if other background or foreground operations are pending. However, background operations are queued and a maximum of one will actually be running at any one time.
+The MMS watcher uses a background operation to perform automatic fetching. While the background autofetch is occurring it is still possible to start a foreground operation (such as sending a message) if required.
+3.2.10.2.5.3 Session and Connection Management
+The server MTM uses the HTTP Transport Framework to enable the HTTP or WSP session. HTTP or WSP can be selected at runtime by selecting the appropriate option in the settings. The server MTM is responsible for reading any HTTP proxy details from the CommDB and passing it to the HTTP framework. See the http transport framework architectural description for more information on recognisers [R5]
+The server MTM is also responsible for managing the connection to the phone network. Connections are opened when required using the RConnection mechanism, multi-homing is supported provided that the underlying HTTP framework transport plug-in also supports it.
+3.2.10.2.6 MMS Codec
+The MMS Server MTM is in charge of the state transitions, connection, session, the actual posting and fetching of the data from them, however it does not encode or decode the MMS PDUs. The encoding and decoding is performed by the MMS Codec.
+For decoding the Server MTM passes the Codec the MMS PDU data in a descriptor for processing. If the PDU contains a received MMS message then the message entry is updated with the decoded MMS data.
+For encoding the Server MTM passes a reference to the message store entry containing the un-encoded MMS data. The Codec then encodes it and returns the PDU to the Server MTM in a descriptor.
+
+
+3.2.11 Messaging / BIO APIs
+3.2.11.1 Key Internal Relationships and Dependencies
+
+Figure 26 BIO Message Internal Dependencies
+3.2.11.1.1.1 Key External Relationships and Dependencies
+
+Figure 27 Bio Parser External Dependencies
+
+3.2.11.2 API Purpose - Further Elaboration
+3.2.11.2.1 BIO Overview
+The BIO messaging components have been designed to unify and simplify the way in which system messages are processed. In this context ‘system messages’ refers to messages received on the device which are intended to update some attribute(s) on the system as opposed to being presented to the user. Examples of these types of messages include vCards which are parsed and then displayed to the user and when accepted modify the users contact database and OTA configuration messages which are again parsed before display to the user and if accepted create email accounts or internet access points.
+The BIO messaging components can be broken down into three groups:
+1) The BIO MTM - To initiate the parsing and processing of BIO messages
+2) The BIO Database - Maps port numbers, MIME types, etc. to bio types in order to identify the type of incoming BIO messages.
+3) The BIO Parsers - To parse and process the BIO message payload
+BIO messages are not receive by the bio messaging framework, they come over other message transports for example see section 3.2.6.3.1 on the SMS watchers which describes how the SMS watchers receive bio messages and use the bio framework to tag the messages with the correct bio id.
+3.2.11.2.2 BIO MTM
+The BIO client MTM is called by the messaging client to parse or process a BIO message that has been saved in the message store. It is the responsibility of a BIO watcher to save the BIO message with the BIO flag and the appropriate BIO type set.
+The BIO client MTM does very little, its primary task is to pass on the messaging client request to the server MTM. Two operations are supported, parse and process.
+The messaging client is expected to initiate the parsing of the BIO message before processing it. The parsing step involves analysing the data and storing it in a form that can be displayed to the user via the BIO message viewer.
+Once the message has been parsed the messaging client can initiate the processing of the message.
+The BIO server MTM is responsible for deferring the parsing and processing to the appropriate BIO parser. The behaviour for the parsing and processing steps varies between parsers. See the BIO Parsers section for more information.
+The bio MTM does not support sending messages and therefore does not support reply / forwarding messages. For bio messages sending / reply etc. is supported by the particular MTM that the message is sent over, for example SMS.
+3.2.11.2.3 BIO Database
+The BIO database is used to identify the type of BIO messages. It maps message attributes such as port number, MIME type or leading string to a BIO type. These are attributes are then used by clients of the bio framework to know what ports to listen for messages on. For example the SMS watchers use the leading string to wait for SMS messages that start with that string and when storing those messages in the inbox tag them with the bio id associated with that leading string. See the SMS watcher section 3.2.6.3.1 for more examples of how the BIO database can be used.
+3.2.11.2.4 BIO Parsers
+The BIO parsers are plug-ins for parsing and processing incoming BIO messages. They are invoked by the BIO Server MTM depending on the BIO type of the message being processed. Each BIO parser implements two functions, ParseL and ProcessL. The level of functionality varies between parsers. Some parsers update the final repository with the received data, e.g. WAPP updates the CommDB with the received settings. Some parsers simply save the data in an unparsed state for processing by another component, this secondary parsing is not part of the BIO framework and must be initiated by the messaging client. An example is when GFP saves vCard data as a file as opposed to updating the contacts database, the UI must then invoke the Versit parser to parse the vCard and commit it to the contacts database.
+3.2.11.2.4.1 Generic File Parser (GFP)
+The generic file parser can be used to identify and save a variety of BIO data types, e.g. vCards and vCals. The Generic File Parser does not process the data, it simply saves it in the message store for processing by another component. The file is saved as an attachment of the message entry that was parsed.
+3.2.11.2.4.2 Nokia/Ericsson OTA Parser (WAPP)
+The WAPP parser decodes Nokia/Ericsson OTA messages and updates CommDB to reflect the received settings.
+3.2.11.2.4.3 Nokia Smart Message Internet Access Parser (IACP)
+The IACP parser decodes Nokia Smart Messages and updates the CommDB and messaging settings where appropriate.
+3.2.11.2.5 BIF Files and Utilities
+The BIF files encapsulate the information required for identifying BIO messages, these details may include the expected port number, MIME type or leading string. Different BIO watcher will use different information from these files, for an example see the 3.2.6.3.1. The information can be retrieved from the BIF files by using the BIF utilities. Generally BIO aware clients will access this information via the BIO database. BIF files are resource files previous to the v6.1 release they were binary files generated by biftool.exe.
+3.2.11.2.6 Platform Security Compliant Messaging / BIO APIs
+In the platform security model the BIO parsers are run in the client space rather than in the message server space, as is done in the non-platform secure model. If the BIO parsers are run in the message server space, it allows a client process to gain the capabilities of the message server. IPC policing can protect the message server from this.
+Also, for the message server to be able to load any BIO parser it would need more capabilities than it really requires. By running the BIO parsers in the client space, both these issues are solved. The client process must be trusted with the necessary capabilities to run the specified BIO parser.
+The BIO registry files are located in the \resource\messaging\bif read-only directory. All BIO parser DLLs are located in the \sys\bin protected directory.
+
+Figure 26 BIO Message Dependencies (v9.0)
+The BIO client MTM is responsible for loading the BIO database and BIO utilities to handle parse/process requests from clients.
+The BIO registry files no longer identify the BIO parsers DLLs via their UID – the registry file must use the BIO parser DLL name to identify them.
+3.2.12 Messaging / OBEX MTM APIs
+3.2.12.1 Key Internal Relationships and Dependencies
+
+Figure 28 OBEX Internal Dependencies
+3.2.12.2 OBEX MTM Overview
+The OBEX MTM offers simple IR and Bluetooth beaming functionality. It provides an API that is consistent with other MTMs so that the underlying OBEX APIs do not need to be used directly for beaming applications. The OBEX MTM does not provide OBEX receiving functionality, in order to receive OBEX data the underlying OBEX APIs must be used directly.
+3.2.12.2.1 OBEX MTM
+The OBEX MTM is split into three parts. OBEX MTM DLLs, IR MTM DLLs and Bluetooth MTM DLLs. The OBEX MTM DLLs can not be used on their own they provide the base OBEX MTM functionality for the derived IR and Bluetooth MTMs.
+There are two APIs that can be used to create OBEX messages:
+1) The Send-As API
+2) Linked attachments by filename
+The Send-As API provides an interface consistent with other MTMs, however it requires all attachments to be copied into the message store before they can be sent, this is often undesirable for beaming applications because it is wastes disk space. For this reason a second API is provided that allows attachments to be linked to outgoing messages by filename, when this API is used there is no need to copy the attachments to the message store.
+Unlike many other MTMs after OBEX tries to send a message it is deleted from the outbox whether the sending succeeds or fails.
+3.2.12.2.1.1 OBEX MTM Key External Dependencies
+
+Figure 29 OBEX External Dependencies
+3.2.12.2.2 IR MTM
+The bulk of the OBEX MTM functionality is provided by the OBEX MTM DLLs, the IR MTM itself just sets up the parameters.
+3.2.12.2.2.1 IR MTM Key External Dependencies
+
+Figure 30 IR MTM Dependencies
+3.2.12.2.3 Bluetooth MTM
+The bulk of the OBEX MTM functionality is provided by the OBEX MTM DLLs, the Bluetooth MTM just subclasses from the OBEX MTM and sets up Bluetooth specific parameters.
+3.2.12.2.3.1 Bluetooth MTM Key External Dependencies
+
+Figure 31 Bluetooth MTM Dependencies
+3.2.12.2.4 OBEX MTM Utils
+The OBEX MTM Utils provide utility functionality used by the other OBEX MTM DLLs. The two main areas of functionality provided by this component are:
+1) Filename linking functionality
+2) Bluetooth SDP lookup
+The filename linking functionality is provided in the utilities because linked files must be added by the client side during message creation and need to be read on the server side during sending.
+
+3.2.12.2.5 Platform Security Compliant Messaging / OBEX MTM APIs
+From v9.0 and onwards the service settings of all the derived OBEX MTMs are stored in the Central Repository. The OBEX message is stored in the message store as an attachment – from v9.0 and onwards the Attachment API is used to attach the OBEX message.
+
+3.2.13 Messaging / GMXML APIs
+3.2.13.1 Key Relationships and Dependencies
+
+Figure 32 GMXML Dependencies
+3.2.13.2 Overview
+The GMXML component provides simple XML DOM parsing and validation functionality. It is intended for parsing XML that might be needed in messaging applications, specifically SMIL parsing for MMS rendering. It is not a general purpose XML parser and will not be suitable for some applications, e.g. browsing.
+3.2.13.2.1 GMXML DOM
+The DOM implementation is fit for purpose for SMIL rendering but differs from the standard DOM design in several respects, e.g. attributes are not stored as discrete nodes, for performance reasons they are stored with the element.
+The DOM tree classes are all derived from nodes. Implemented node types include elements, text and comments. The type of each element is stored as a descriptor as opposed to an enum. This is less efficient than storing it as an enum but provides maximum flexibility when dealing with unknown element types.
+Nodes are linked together in a tree structure as might be expected in a DOM implementation. The tree structure exists on the heap.
+3.2.13.2.2 GMXML Parser and Composer
+3.2.13.2.2.1 Parser
+The parser takes XML input from a buffer or file and creates the corresponding DOM structure on the heap.
+The parser is capable of performing some basic validation. In order to validate against a DTD a class that implements the GMXML DTD interface is required. The DTD interface specifies several functions that provide the required validation, e.g. one of the functions determines if a given attribute is valid for a given element. An instance of the DTD class should be passed into the parser when validation is required but can be omitted if no validation is needed.
+3.2.13.2.2.2 Composer
+The composer takes a DOM tree and generates XML output from it. The XML output is written to a file.
+3.2.13.2.3 GMXML SMIL DTD (Validator)
+The SMIL DTD validator class is an implementation of the DTD validator interface. It implements several simple functions that provide the information required to validate SMIL data. An instance of the SMIL DTD validator should be passed into the parser if SMIL validation is required.
+4 Security
+4.1 Data caging
+For data storage in the pre-platform security compliant architecture, refer to section [3.2.1.3.2]
+For the data caging in the platform security compliant architecture of v9.0 and onwards, refer to section [3.2.1.3.3]
+4.2 Backup and restore
+The message server registers the index file with the backup server. When informed about a backup/restore it releases the index file, sending events to messaging clients informing them that the message store is unavailable. When informed it can open the index file again, it checks the time stamp on the index file; if it has changed since the file was released it reloads the index file. If the newly restored index file is found to be corrupt it is deleted and a new message store is created. See the section on page 14 for details on how the message server handles corrupt stores. The client performing the restore should always wipe the existing message store before starting to copy the message store from the backup to the device.
+4.3 Capability ranges
+In the platform security compliant architecture of v9.0 and onwards, the capabilities allocated to messaging sub-systems are as listed in following table.
+4.3.1 Capabilities granted to executables
+The following table lists the executables and their capabilities and also gives a basic example for having the required capability.
+
+Executable Capability Rationale (basic example of capability requirement)
+msexe.exe ProtServ ProtServ is required to allow the msexe.exe to start a protected server. This stops processes without ProtServ from starting a server pretending to be the message server
+ ReadDeviceData ReadDeviceData is needed to able to read service settings
+ WriteDeviceData WriteDeviceData is needed to able to write service settings
+ NetworkServices NetworkServices capability is needed to access network transports (SMS, POP3, SMTP, IMAP4).
+ LocalServices LocalServices is needed to be able to access IR and Bluetooth
+ ReadUserData ReadUserData is needed to be able to read user data (e.g. service settings).
+watcher.exe ReadDeviceData ReadDeviceData is needed to able to read service settings
+ WriteDeviceData WriteDeviceData is needed to able to write service settings
+ NetworkServices NetworkServices capability is needed to access network transports (SMS).
+ LocalServices LocalServices capability is needed for the plug-ins to access IR and Bluetooth
+ ReadUserData ReadUserData is needed to be able to read user data
+ WriteUserData WriteUserData is needed to be able to write user data
+autosend.exe ReadUserData ReadUserData capability is needed to be able to read data from Outbox and SMTP server MTM.
+ WriteUserData WriteUserData capability is needed to be able to write data in Outbox and SMTP server MTM.
+ NetworkServices NetworkServices capability is needed to access network transports (SMS, POP3, SMTP, and IMAP4).
+ LocalServices LocalServices capability is needed to access the IR and Bluetooth
+SchSend.exe ReadDeviceData ReadDeviceData is needed to able to read settings data
+ NetworkServices NetworkServices capability is needed to access the network transports (SMS, POP3, SMTP, and IMAP4).
+ LocalServices LocalServices is needed to be trusted by other MTM
+ ReadUserData ReadUserData is needed to be able to read user data.
+ WriteUserData WriteUserData is needed to be able to write user data.
+SendAs.exe ReadDeviceData ReadUserData is needed to be able to read data in Outbox.
+ WriteDeviceData WriteUserData is needed to be able to write data in Outbox.
+ NetworkServices NetworkServices capability is needed to access the network transports (SMS, POP3, SMTP, and IMAP4).
+ LocalServices LocalServices is needed to be able to access IR and Bluetooth
+
+4.3.2 Capabilities granted to DLLs
+The assigned Platform Security attributes for DLLs within messaging are outlined in the following table.
+DLL Capability
+bifu.dll All –TCB
+bioc.dll All –TCB
+biodb.dll All –TCB
+bios.dll All –TCB
+biowatcher.dll same as watcher.exe
+biut.dll All –TCB
+cbcp.dll All –TCB
+enp.dll All –TCB
+gfp.dll All –TCB
+iacp.dll All –TCB
+nbswatcher.dll same as watcher.exe
+cdmanbswatcher.dll same as watcher.exe
+CdmaSocketWatcher.dll same as watcher.exe
+VMNWatcher.dll same as watcher.exe
+WEMTWatcher.dll same as watcher.exe
+WMTWatcher.dll same as watcher.exe
+WPTWatcher.dll same as watcher.exe
+wapp.dll All –TCB
+wapwatcher.dll same as watcher.exe
+smildtd.dll All –TCB
+xmldom.dll All –TCB
+xmlparser.dll All –TCB
+smiltranslator.dll All –TCB
+imcm.dll All –TCB
+imps.dll same as msexe.exe
+imut.dll All –TCB
+msgs.dll All –TCB
+msgurlrec.mdl same as AppArc.exe (once it exists; eiksrv in meantime)
+mtur.dll All –TCB
+pops.dll same as msexe.exe
+schsend.dll All –TCB
+send.dll All –TCB
+smcm.dll All –TCB
+smcm_gsm.dll Synonym for smcm.dll
+smcm_cdma.dll Synonym for smcm.dll
+smss.dll same as msexe.exe
+smss_gsm.dll Synonym for smss.dll
+smss_cdma.dll Synonym for smss.dll
+smts.dll same as msexe.exe
+btcmtm.dll All –TCB
+btsmtm.dll same as msexe.exe
+irc.dll All –TCB
+irs.dll same as msexe.exe
+obexclientmtm.dll All –TCB
+obexmtmutil.dll All –TCB
+obexservermtm.dll same as msexe.exe
+
+The reason for setting a high capability to the DLLs is to make it possible for almost anyone to link to them. Although a DLL may have capabilities ALL-TCB (All minus TCB), its real capability is limited by the process which loads the DLL.
+4.3.3 Capabilities required to use the subsystem
+The message subsystem needs to be protected against malicious clients. The following table shows the key capabilities required to do related activities in different components.
+
+Component Related Activity Required Capability and SID
+Message server Create message in local folder No capability required
+ Create message in Outbox ReadUserData, WriteUserData and MTM specific capabilities
+ Access client MTM ReadUserData, WriteUserData and MTM specific capabilities
+Watcher Allow plug-ins to wait on events (e.g. arrival of SMS) Watcher always polices if the client capabilities are trusted by the watcher framework, else it will not be loaded
+Plug-ins or clients using watcher need the same capabilities as watcher.exe to be able to be loaded by watcher.
+Autosend Send messages in background NetworkService or LocalService required by the message type
+SchSend Scheduling of operations (e.g. sending SMS) SchSend always polices to see if the process was started by the Task Scheduler – if not the process terminates without performing any of the scheduled tasks. Also, the SchSend verifies that only itself and the message server created the scheduled tasks. If this is not the case, SchSend does not performing the scheduled tasks.
+SendAs Create message Draft, move it to Outbox, and send message WriteDeviceData or WriteUserData and other capability required by the message type
+
+5 Further Information
+5.1 References
+No. Document Reference Version Description
+R1 messaging_functional_specification.doc 0.6 Messaging Functional description
+R2 SGL.GT0143.161_App-Framework_Architectural_Description.doc 1.0 App-Framework Architectural Description
+R3 NBProtocols_Subsystem_Architectural_Description.doc 0.2 NBProtocols Architectural Description
+R4 WAP-stack_architectural_analysis.doc 1.0 WAP stack architectural analysis
+R5 HTTP Transport Framework Architectural Description.doc 1.1 HTTP Transport Framework 1.1 Architectural Description
+5.2 Open Issues
+The following issues need to be resolved before this document is completed:
+1. Top-level architecture diagram showing the framework and plug-ins should be added to overview section.
+2. Message store section should talk about removable media.
+3. Define "Message Server Client API" and "Messaging Client API" in the glossary, and ensure it is consistently used in the diagrams
+4. Add a sequence diagram for receiving a vCard over SMS and integrating it into contacts
+5. Add a sequence diagram for sending an SMS
+6. Add a sequence diagram for synchronising a POP3 mail box
+7. Add a sequence diagram for connecting to an IMAP4 mail box and downloading a message
+8. Capability table should be updated after the implementation of server e.g. message server
+9. Sequence diagram may need to be changed to show secured platform operation
+10. In section [3.1.1.4] the server SendAsV2 to find a correct name
+11. Section 3.2.1.3.3.1 Data Caging file 'Mtm Registry v2'may need a correct name
+12. Breakdown diagram showing all DLL, exes, apps in the messaging subsystem for both the pre-v8.0 and post v9.0 in section[3.2]
+13. Needs to say more about how the capabilities are policed and the algorithms used for different operations
+14. The dependecy between the message server and the central repository need to be listed in the email, SMS and OBEX diagrams (e.g. message store)
+15. Section 3.2.1.2 - figure 3 - Central Repository also get used by the Message server, or server MTMs (e.g. POP3), to retrieve account settings the path, required DLL and description are not given
+16. Section 4.3.3 title can be Police requirement of the sub-system, add extra column for SID in the table and list the use of SID. For example SchSend checks for Task Scheduler SID
+
+
+5.3 Glossary
+The following technical terms and abbreviations are used within this document.
+Term Definition
+BIO
+Bearer Independent Object Smart messages e.g. vCards, vCals, and WAP provisioning messages. These can currently be received via the WAP stack, SMS stack, Bluetooth or Infrared.
+BIO Type UID that represents the content type of a BIO Message.
+Message Centre Application that displays list views of messages to the user, allowing the user to perform operations such as copying messages, sending messages creating new messages etc.
+Message Viewer Application for viewing a message.
+Message Editor Application for creating or editing a message
+Message Server Symbian OS Server that handles request to modify the Message Store
+Message Store Store of messages and related information kept in the file system on a Symbian OS device.
+Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
+Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
+Global Inbox A standard folder under the local service which is used to store incoming messages like SMS MMS etc. as opposed to an IMAP4 Inbox which would be under an IMAP4 service and is a representation of the Inbox on an IMAP4 email server.
+Central Repository centralised and secure storage facility for application settings
+OBEX Object exchange protocol, used to send objects such as vCards or files between devices via infrared or Bluetooth.
+GMXML XML parser / generator for use with SMIL formatted messages.
+UID Unique Identifier, a 32 bit number allocated from a registry owned by Symbian
+IPC Inter Process Communication
+MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
MTM Registry A list of currently installed MTMs maintained by the message server.
TLS Transport Layer Security, provides encryption of a TCP/IP socket.
M-HTML Standard for including HTML in MIME email messages see http://www.ietf.org/rfc/rfc2557.txt
@@ -35567,15 +30477,15 @@
Message Editor Application for creating or editing a message
Message Server Symbian OS Server that handles request to modify the Message Store
Message Store Store of messages and related information kept in the file system on a Symbian OS device.
-Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
-Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
+Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
+Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
Global Inbox A standard folder under the local service which is used to store incoming messages like SMS MMS etc. as opposed to an IMAP4 Inbox which would be under an IMAP4 service and is a representation of the Inbox on an IMAP4 email server.
Central Repository centralised and secure storage facility for application settings
OBEX Object exchange protocol, used to send objects such as vCards or files between devices via infrared or Bluetooth.
GMXML XML parser / generator for use with SMIL formatted messages.
UID Unique Identifier, a 32 bit number allocated from a registry owned by Symbian
IPC Inter Process Communication
-MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
+MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
MTM Registry A list of currently installed MTMs maintained by the message server.
TLS Transport Layer Security, provides encryption of a TCP/IP socket.
M-HTML Standard for including HTML in MIME email messages see http://www.ietf.org/rfc/rfc2557.txt
@@ -36585,15 +31495,15 @@
Message Editor Application for creating or editing a message
Message Server Symbian OS Server that handles request to modify the Message Store
Message Store Store of messages and related information kept in the file system on a Symbian OS device.
-Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
-Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
+Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
+Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
Global Inbox A standard folder under the local service which is used to store incoming messages like SMS MMS etc. as opposed to an IMAP4 Inbox which would be under an IMAP4 service and is a representation of the Inbox on an IMAP4 email server.
Central Repository centralised and secure storage facility for application settings
OBEX Object exchange protocol, used to send objects such as vCards or files between devices via infrared or Bluetooth.
GMXML XML parser / generator for use with SMIL formatted messages.
UID Unique Identifier, a 32 bit number allocated from a registry owned by Symbian
IPC Inter Process Communication
-MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
+MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
MTM Registry A list of currently installed MTMs maintained by the message server.
TLS Transport Layer Security, provides encryption of a TCP/IP socket.
M-HTML Standard for including HTML in MIME email messages see http://www.ietf.org/rfc/rfc2557.txt
@@ -37603,15 +32513,1033 @@
Message Editor Application for creating or editing a message
Message Server Symbian OS Server that handles request to modify the Message Store
Message Store Store of messages and related information kept in the file system on a Symbian OS device.
-Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
-Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
+Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
+Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
Global Inbox A standard folder under the local service which is used to store incoming messages like SMS MMS etc. as opposed to an IMAP4 Inbox which would be under an IMAP4 service and is a representation of the Inbox on an IMAP4 email server.
Central Repository centralised and secure storage facility for application settings
OBEX Object exchange protocol, used to send objects such as vCards or files between devices via infrared or Bluetooth.
GMXML XML parser / generator for use with SMIL formatted messages.
UID Unique Identifier, a 32 bit number allocated from a registry owned by Symbian
IPC Inter Process Communication
-MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
+MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
+MTM Registry A list of currently installed MTMs maintained by the message server.
+TLS Transport Layer Security, provides encryption of a TCP/IP socket.
+M-HTML Standard for including HTML in MIME email messages see http://www.ietf.org/rfc/rfc2557.txt
+MIME Specification for the format of email message bodies see http://www.ietf.org/rfc/rfc1341.txt
+RFC2822 The standard format for internet mail messages see http://www.ietf.org/rfc/rfc0822.txt
+SMTP Simple Mail Transport Protocol
+SID Secure Identification
+IMAP4 Internet Mail Access Protocol
+POP3 Post Office Protocol Version 3
+NBS Narrow Band Socket, in the messaging context this refers to the socket that is used to talk to the SMS stack for receiving and sending SMS messages
+SMS Short Message Service
+MMS Multimedia Message Service
+WAP Wireless Application Protocol
+WSP WAP Session Protocol
+HTTP Hypertext transfer protocol
+PDU Protocol Data Unit. This is the encoded form of SMS and MMS messages.
+Versit A consortium that defined standard formats for things like contacts (vCard) and calendar entries (vCals)
+SDP Service Discovery Protocol. A Bluetooth protocol that allows an applications to discover which services are available and to determine the characteristics of the services.
+SMIL Synchronized Multimedia Integration Language. Presentation language that is commonly used to define the contents of an MMS message.
+XML Extensible Mark-up Language
+DOM Document Object Model
+DTD Document Type Definition, a schema that defines the structure of an XML document.
+ESTORE Symbian OS component that provides stream based storage. Messaging uses the Permanent file store provided by ESTORE to store its index entries.
+Appendix A - Example Sequence Diagrams
+A.1 Copy to a Remote Service
+
+Figure 33 Sequence Diagram Showing Copying to a Remote Service
+Figure 33 shows a client copying a message to a remote service using the Messaging Client API. The message server then delegates the copy to the SMTP Server MTM. The Server MTM interprets the request as a request to send the message so it opens a connection to a remote SMTP server and sends the message. While the message is being sent the client can retrieve progress information from the CMsvOperation object that was returned by CMsvEntry::CopyL. The dark grey IPC line represents the split between the objects running in the client’s process space on the left and the message server’s process on the right.
+There are four basic steps:
+1. The client opens session with Message Server and creates a CMsvEntry set on the global outbox,
+2. The client then requests an asynchronous copy from the outbox to the SMTP service, a CMsvOperation object is returned. The message server loads the SMTP Server MTM and delegates the copy operation to it.
+3. The client requests progress from the CMsvOperation object, this request is passed through to the SMTP Server MTM. The client may repeat this step multiple times.
+4. The Server MTM finishes sending message. It moves the message to sent folder and completes the message server’s request. The message server completes the CMsvOperation object, which requests the final progress from the message server. The server returns the final progress and deletes the Server MTM. The CMsvOperation then completes the client’s original request.
+This diagram hides all of the internal working of the SMTP Server MTM, for information on this see below.
+A.2 SMTP Session
+
+Figure 34 Sequence Diagram Showing a SMTP Session
+Figure 34 shows the operation of the SMTP Server MTM after a request has come from the message server to copy a message to the SMTP service.
+1. SMTP Server MTM gets the request from the message server, it will build a selection of messages consisting of the union of the selection of messages passed in and the messages in the outbox that are associated with this SMTP service and are ready to be sent. The chain of classes are constructed, and a request is passed to networking to connect to the remote SMTP server, details of the server name and port are retrieved from the settings stored in the SMTP service entry.
+2. The component waits for the SMTP server to respond with a greeting indicating it is willing to talk, then sends EHLO to the server and waits for the response detailing the capabilities of the Server. After this step there could set steps to start using TLS and or SMTP AUTH depending on the SMTP settings.
+3. CImSmtpSession calls back into CMsgOutboxSend to retrieve the next message to be sent, then constructs a CImSmtpFile object to handle sending, for details on the sending see SMTP Email Send. When sending the email has completed the CImSmtpFile object is deleted.
+4. CImSmtpSession calls back into CMsgOutboxSend to retrieve the next message which returns saying there are no more messages. CImSmtpSession sends QUIT to the SMTP server and completes CMsgOutboxSend. CMsgOutboxSend deletes CImSmtpSession which tears down the connection to the SMTP server; it then completes the SMTP Server MTM. The Server MTM will then complete the message server and be deleted.
+A.3 SMTP Email Send
+
+Figure 35 Sequence Diagram Showing SMTP Transactions during Email Send.
+Figure 35 shows a CImSmtpFile object sending an email message to an SMTP server.
+1. Construct a CImSendMessage object, part of the imut component. Reset the SMTP Server
+2. Read address information from the CImHeader object stored in the message store, send address information to SMTP server.
+3. Use CImSendMessage object to read the message from the message store and generate RFC2822 message line by line. Send each line to the server as it is generated.
+4. Complete and send the message by sending a full stop to the SMTP server
+
+
+
+
+Messaging Symbian OS v7.0s, v8.0, v8.1, v9.0, v9.1 Architectural Description
+
+Status: Issued
+Team/Department : Messaging / Content & Messaging
+
+Contents
+1 INTRODUCTION 6
+1.1 PURPOSE AND SCOPE 6
+2 SUBSYSTEM OVERVIEW AND BACKGROUND 6
+3 MESSAGING ARCHITECTURE AND APIS 7
+3.1 SUBSYSTEM COMPONENTS 7
+3.1.1 Framework components 7
+3.1.1.1 Message Server and MTM architecture 7
+3.1.1.2 Schedule Send 7
+3.1.1.3 SendAs Version 1 7
+3.1.1.4 SendAs Version 2 7
+3.1.1.5 Watcher Framework 8
+3.1.1.6 Message URL Handler 8
+3.1.1.7 Bio Message Framework 8
+3.1.2 Plug-ins 8
+3.1.2.1 SMS 8
+3.1.2.2 CDMA SMS 8
+3.1.2.3 Email 9
+3.1.2.4 OBEX 9
+3.1.2.5 MMS 9
+3.1.2.6 GMXML 10
+3.1.2.7 Bio Message Plug-ins 10
+3.1.2.8 PCMTM 10
+3.1.2.9 Fax 10
+3.2 GENERAL DESCRIPTION 11
+3.2.1 Messaging / Message Server and MTM Architecture APIs 11
+3.2.1.1 Key Internal Relationships and Dependencies 11
+3.2.1.2 Key External Relationships and Dependencies 12
+3.2.1.3 API Purpose - Further Elaboration 13
+3.2.1.3.1 Message Store 13
+3.2.1.3.2 Data File Storage (pre - v9.0) 15
+3.2.1.3.3 Platform Security Compliant Message Store 16
+3.2.1.3.4 How message centres display the message store 17
+3.2.1.3.5 Message Type Module Architecture 19
+3.2.1.3.6 Message Server Client API 21
+3.2.2 Messaging / Send As APIs 22
+3.2.2.1 Key Relationships and Dependencies 22
+3.2.2.2 API Purpose - Further Elaboration 22
+3.2.2.2.1 SendAs API (pre – v9.0) 22
+3.2.3 Platform Security Compliant SendAs Server (v9.0 onwards) 23
+3.2.4 Messaging / Schedule Send APIs 24
+3.2.4.1 Key Relationships and Dependencies 24
+3.2.4.2 API Purpose - Further Elaboration 24
+3.2.4.2.1 Schedule Send 24
+3.2.5 Messaging / Watchers APIs 25
+3.2.5.1 Key Relationships and Dependencies 25
+3.2.5.2 API Purpose - Further Elaboration 25
+3.2.6 Messaging / Message URL Handler APIs 26
+3.2.6.1 Key Relationships and Dependencies 26
+3.2.6.2 API Purpose - Further Elaboration 26
+3.2.6.2.1 Message URL Handler Application 26
+3.2.6.2.2 Message URL Recognisers 27
+3.2.7 Messaging / SMS APIs 27
+3.2.7.1 Key Internal Relationships and Dependencies 27
+3.2.7.2 Key External Relationships and Dependencies 28
+3.2.7.3 API Purpose - Further Elaboration 28
+3.2.7.3.1 SMS Watchers 28
+3.2.7.3.2 SMS Client MTM 29
+3.2.7.3.3 SMS Utilities 29
+3.2.7.3.4 SMS Server MTM 30
+3.2.8 Messaging / CDMA SMS APIs 31
+3.2.8.1 Key Internal Relationships and Dependencies 31
+3.2.8.2 Key External Relationships and Dependencies 32
+3.2.8.3 API Purpose - Further Elaboration 32
+3.2.8.3.1 CDMA SMS Watchers 32
+3.2.8.3.2 CDMA SMS Client MTM 33
+3.2.8.3.3 CDMA SMS Utilities 33
+3.2.8.3.4 CDMA SMS Server MTM 33
+3.2.8.3.5 Configuration for using CDMA SMS MTM 34
+3.2.9 Messaging / Email APIs 35
+3.2.9.1 Key Internal Relationships and Dependencies 35
+3.2.9.2 Key External Relationships and Dependencies 36
+3.2.9.3 API Purpose - Further Elaboration 36
+3.2.9.3.1 Email Overview 36
+3.2.9.3.2 Email Client Utilities 37
+3.2.9.3.3 Email Server MTM Utilities 37
+3.2.9.3.4 POP3 MTMs 37
+3.2.9.3.5 IMAP4 MTMs 38
+3.2.9.3.6 SMTP MTMs 40
+3.2.9.3.7 Autosend 40
+3.2.10 Messaging / MMS APIs 40
+3.2.10.1 Key Internal Relationships and Dependencies 41
+3.2.10.2 API Purpose - Further Elaboration 41
+3.2.10.2.1 MMS Overview 41
+3.2.10.2.2 MMS Utilities 42
+3.2.10.2.3 MMS Watcher 43
+3.2.10.2.4 MMS Client MTM 43
+3.2.10.2.5 MMS Server MTM 44
+3.2.10.2.6 MMS Codec 45
+3.2.11 Messaging / BIO APIs 46
+3.2.11.1 Key Internal Relationships and Dependencies 46
+3.2.11.2 API Purpose - Further Elaboration 47
+3.2.11.2.1 BIO Overview 47
+3.2.11.2.2 BIO MTM 47
+3.2.11.2.3 BIO Database 48
+3.2.11.2.4 BIO Parsers 48
+3.2.11.2.5 BIF Files and Utilities 48
+3.2.11.2.6 Platform Security Compliant Messaging / BIO APIs 49
+3.2.12 Messaging / OBEX MTM APIs 50
+3.2.12.1 Key Internal Relationships and Dependencies 50
+3.2.12.2 OBEX MTM Overview 50
+3.2.12.2.1 OBEX MTM 50
+3.2.12.2.2 IR MTM 51
+3.2.12.2.3 Bluetooth MTM 51
+3.2.12.2.4 OBEX MTM Utils 52
+3.2.12.2.5 Platform Security Compliant Messaging / OBEX MTM APIs 52
+3.2.13 Messaging / GMXML APIs 52
+3.2.13.1 Key Relationships and Dependencies 52
+3.2.13.2 Overview 53
+3.2.13.2.1 GMXML DOM 53
+3.2.13.2.2 GMXML Parser and Composer 53
+3.2.13.2.3 GMXML SMIL DTD (Validator) 53
+4 SECURITY 54
+4.1 DATA CAGING 54
+4.2 BACKUP AND RESTORE 54
+4.3 CAPABILITY RANGES 54
+4.3.1 Capabilities granted to executables 54
+4.3.2 Capabilities granted to DLLs 55
+4.3.3 Capabilities required to use the subsystem 57
+5 FURTHER INFORMATION 59
+5.1 REFERENCES 59
+5.2 OPEN ISSUES 59
+5.3 GLOSSARY 60
+APPENDIX A - EXAMPLE SEQUENCE DIAGRAMS 62
+A.1 COPY TO A REMOTE SERVICE 62
+A.2 SMTP SESSION 64
+A.3 SMTP EMAIL SEND 66
+
+Table of Figures
+Figure 1 Where Messaging Lives 6
+Figure 2 MTM Relationships 11
+Figure 3 External Dependencies 12
+Figure 4 Message Store 13
+Figure 5 Series 60 Inbox List View 14
+Figure 6 Remote and Local Entries 14
+Figure 7 Email Message 15
+Figure 8 Series 60 Message Centre (Composed from 2 screen shots) 17
+Figure 9 UIQ Message Centre 18
+Figure 10 Messaging MTM Structure (light coloured components are part of messaging subsystem) 19
+Figure 11 Nokia 9210 Outbox List View 20
+Figure 12 SendAs Version 1 Dependencies 22
+Figure 13 SendAs Version 2 Dependencies 23
+Figure 14 Schedule Send Dependencies 24
+Figure 15 Watcher Dependencies 25
+Figure 16 Message URL Handler Dependencies 26
+Figure 17 SMS Internal Dependencies 27
+Figure 18 SMS External Dependencies 28
+Figure 19 CMDA SMS Internal Dependencies 31
+Figure 20 CDMA SMS External Dependencies 32
+Figure 19 Email Internal Dependencies 35
+Figure 20 Email External Dependencies 36
+Figure 21 MMS Internal Dependencies 41
+Figure 22 MMS Utilities External Dependencies 42
+Figure 23 MMS Watcher External Dependencies 43
+Figure 24 MMS Client MTM Dependencies 43
+Figure 25 MMS Server MTM Dependencies 44
+Figure 26 BIO Message Internal Dependencies 46
+Figure 27 Bio Parser External Dependencies 47
+Figure 26 BIO Message Dependencies (v9.0) 49
+Figure 28 OBEX Internal Dependencies 50
+Figure 29 OBEX External Dependencies 51
+Figure 30 IR MTM Dependencies 51
+Figure 31 Bluetooth MTM Dependencies 52
+Figure 32 GMXML Dependencies 52
+Figure 33 Sequence Diagram Showing Copying to a Remote Service 62
+Figure 34 Sequence Diagram Showing a SMTP Session 64
+Figure 35 Sequence Diagram Showing SMTP Transactions during Email Send. 66
+1 Introduction
+1.1 Purpose and Scope
+The Messaging Architectural Description details the architecture and APIs exposed by the Messaging Subsystem. This document does not attempt to list all functionality provided by the messaging subsystem. For details on the functionality provided and the specifications implemented by the messaging subsystem see the Messaging Functional Description [R1]. This document describes the general architecture of messaging subsystem. Information related to a particular release version is mentioned with relevant release number.
+2 Subsystem Overview and Background
+The Messaging Subsystem provides an application level API to handle the storage and transport of different message types. It sits between messaging applications and the lower level subsystems which messaging uses for storage and transmission of messages.
+
+Figure 1 Where Messaging Lives
+The message types that messaging currently supports are Email (POP3, IMAP4 & SMTP), SMS, MMS and OBEX. The set of supported message types is extensible at run time by the use of plug-in modules that are responsible for the transmission and storage of a particular message type. This means that the set of components shown communicating with the network cloud depend on the message types installed.
+3 Messaging Architecture and APIs
+3.1 Subsystem components
+The Messaging subsystem components can be split into two categories: those components that form the framework and those that plug into the framework to support specific message types. This section briefly describes each of the components, more detailed descriptions of the components and their dependencies can be found in later sections of this document.
+3.1.1 Framework components
+3.1.1.1 Message Server and MTM architecture
+The message server is the core component in the messaging subsystem. It provides the message store used to contain messages. The Message Type Module architecture also allows plug-ins to add support for new message types to the messaging subsystem.
+Component Description
+messaging\framework\serverexe Executable that links to the server component and starts the message server
+messaging\framework\server Contains classes that make up both the client and server side of the message server API.
+messaging\framework\mtmbase Base classes for the plug-ins that handle the various message types
+3.1.1.2 Schedule Send
+The Schedule Send component is an extension to the framework that provides support for scheduling of operations such as sending messages. Message type modules that wish to support this functionality can use these support components to implement scheduling. For example the SMS MTM uses this to allow scheduled sending of SMS messages.
+Component Description
+messaging\schedulesend\schedulesendmtm Base classes that handle functionality for message server plug-ins that wish to enable scheduling of sending messages.
+messaging\schedulesend\schedulesendexe Executable use to provide schedule send behaviour.
+3.1.1.3 SendAs Version 1
+This version of SendAs is supported in releases pre - v9.0. SendAs provides a high level API for applications that wish to include a “Send As” menu to allow users to send content via one of the message types supported by messaging. The application using the API does not have to be aware of the message type selected by the user. Note the API does not send the messages.
+Component Description
+messaging\sendas High level API to allow creation of messages.
+3.1.1.4 SendAs Version 2
+From v9.0 and onwards the SendAs has been replaced with client server architecture based SendAs server. The client server architecture enhances secured platform implementation. The SendAs server polices the client application. If it is not trusted with required capabilities the SendAs server will refuse the client access. The client MTM for the message type can send a message with user permission even if the client does not have the correct capabilities.
+Component Description
+messaging\sendAsV2 High level API to allow the creation and sending of messages
+
+3.1.1.5 Watcher Framework
+The watcher framework is a lightweight framework to allow plug-ins to wait on events. For example there is an SMS watcher that waits for incoming SMS messages and delivers them to the message store. The watcher framework will only load plug-ins from ROM.
+Component Description
+messaging\framework\watcher Executable that loads and runs watcher plug-ins.
+3.1.1.6 Message URL Handler
+Support for recognising messaging URLs (mailto:, sms:, fax:, mms:), and then launching an editor with a new message.
+Component Description
+messaging\urlhandler\urlhandler An application that parses the URLs and then creates a correctly addressed message and launches a message editor.
+messaging\urlhandler\recogniser Recognisers that map from the URL schemes to the mime types.
+3.1.1.7 Bio Message Framework
+The Bio Message Framework provides a framework that supports plug-ins to handle messages like vCards and Internet access point set-up messages.
+Component Description
+messaging\biomsg\BDB\BIODB Classes to maintain the database of bio registration files.
+messaging\biomsg\BIFU\BIFU Classes for reading and writing bio registration files
+messaging\biomsg\BIOC\BIOC Bio message client MTM, this is in the framework section as it forms part of the bio messaging framework it is also a plug-in to the messaging framework.
+messaging\biomsg\BIOS\BIOS Bio message server MTM, this is in the framework section as it forms part of the bio messaging framework it is also a plug-in to the messaging framework.
+3.1.2 Plug-ins
+3.1.2.1 SMS
+The SMS plug-ins provide application level support for the Short Message Service messages.
+Component Description
+messaging\biomsg\BioWatchers Plug-ins to the watcher framework to listen for SMS, WSP, and WDP messages and deliver them to the global inbox in the message store.
+messaging\sms\clientmtm A plug-in to the message server framework to provide a generic API for creation of SMS messages (SMS Client MTM & SMS utilities)
+messaging\sms\servermtm A plug-in to the message server framework to provide a generic API for sending of SMS messages (SMS Server MTM)
+3.1.2.2 CDMA SMS
+The CDMA SMS plug-ins provide application level support for the CDMA Short Message Service messages.
+Component Description
+messaging\biomsg\BioWatchersCdma Plug-ins to the watcher framework to listen for CDMA SMS messages and deliver them to the global inbox in the message store.
+messaging\sms\multimode\clientmtm A plug-in to the message server framework to provide a generic API for creation of CDMA SMS messages (CDMA SMS Client MTM)
+messaging\sms\multimode\servermtm A plug-in to the message server framework to provide a generic API for sending of CDMA SMS messages (CDMA SMS Server MTM)
+
+3.1.2.3 Email
+The email plug-ins provide support the POP3, IMAP4 and SMTP email protocols and support for parsing and generating plain test, MIME and M-HTML format email messages.
+Component Description
+messaging\email\clientmtms A plug-in to the message server framework to provide a generic API for creation of email messages (IMAP4 SMTP and POP3 Client MTMs & email utilities)
+messaging\email\imapservermtm A plug-in to the message server framework to provide a generic API for access to a remote IMAP4 server (IMAP4 Server MTM)
+messaging\email\smtpservermtm A plug-in to the message server framework to provide a generic API for access to a remote SMTP server (SMTP Server MTM)
+messaging\email\popservermtm A plug-in to the message server framework to provide generic API for access to remote POP3 server (POP3 Server MTM)
+messaging\email\servermtmutils Email utilities for parsing plain text and MIME email messages. It also provides an abstraction of the TCP/IP sockets for use by the SMTP POP3 and IMAP4 plug-ins.
+messaging\email\autosend An executable that requests SMTP Server MTM to send messages in the outbox. This is used to provide send on next connection functionality and is started by the POP3 and IMAP4 Client MTMs.
+3.1.2.4 OBEX
+The OBEX MTM is a set of plug-ins to the message server that provides support for IR and Bluetooth beaming.
+Component Description
+messaging\obex\btmtm\btclient\group\btcmtm Bluetooth Client MTM
+messaging\obex\btmtm\btserver\group\btsmtm Bluetooth Server MTM
+messaging\obex\irmtm\irclient\group\ircmtm IR Client MTM
+messaging\obex\irmtm\irserver\group\IRSMTM IR Server MTM
+messaging\obex\obexmtm\obexclient\group\obexClientMtm OBEX Client MTM, base classes for the Bluetooth and IR Client MTMs
+messaging\obex\obexmtm\obexserver\group\obexServerMtm OBEX Server MTM, base classes for the Bluetooth and IR Server MTMs
+messaging\obex\obexmtm\obexutil\group\obexMtmUtil OBEX MTM utilities
+3.1.2.5 MMS
+The MMS MTM is a plug-in to the message server that provides support for MMS messages. From v9.0 and onwards MMS MTM and related components are removed.
+Component Description
+messaging\mms\utils MMS Utilities
+messaging\mms\servermtm MMS Server MTM
+messaging\mms\mmswatcherplugins MMS plug-ins to WAP push framework to handle reception of MMS notifications
+messaging\mms\codec MMS utilities for handling MMS codecs
+messaging\mms\clientmtm MMS Client MTM
+3.1.2.6 GMXML
+GMXML is a parser/generator for SMIL presentations for MMS messages.
+Component Description
+messaging\GMXML\XMLParser XML parser designed for parsing of SMIL messages
+messaging\GMXML\XMLDom XML document object model designed for parsing of SMIL messages
+messaging\GMXML\SMILdtd SMIL DTD
+3.1.2.7 Bio Message Plug-ins
+These parsers plug into the bio messaging framework to handle specific types of bio message.
+Component Description
+messaging\biomsg\cbcp\CBCP Compact business card parser
+messaging\biomsg\enp\ENP Email notification parser
+messaging\biomsg\gfp\gfp General file parser
+messaging\biomsg\iacp\IACP Nokia Smart Message Internet Access Parser
+messaging\biomsg\wapp\wapp Nokia/Ericsson OTA Parser
+3.1.2.8 PCMTM
+Plug-in to the message server that provided email synchronisation with a PC. This component has been deprecated in 8.0a and will not been documented in the API section below.
+3.1.2.9 Fax
+Plug-in to the message server that provides fax support. This component has been deprecated in 8.0a and will not been documented in the API section below.
+
+3.2 General Description
+3.2.1 Messaging / Message Server and MTM Architecture APIs
+3.2.1.1 Key Internal Relationships and Dependencies
+
+Figure 2 MTM Relationships
+Figure 2 shows the relationship between the Message Server and the MTM plug-ins. The grey classes are realisations of the MTM interfaces defined by the messaging framework. The message server depends on the Server MTM interface. Messaging Clients depend on the Client, UI and UI Data MTM interfaces and the Message Server Client API.
+3.2.1.2 Key External Relationships and Dependencies
+
+Figure 3 External Dependencies
+The grey package representing the messaging client depends on the Client, UI and UI Data interfaces and the Messaging Client API. The message server then depends on:
+• Charconv – Provides character set conversion routines, used to convert encoded message body text to Unicode body text.
+• EStore – Provides API to handle a stream based store used for the messaging index file and the framework classes for the message store files. (omitted from other dependency diagrams as it is implied by the dependency on the message server)
+• F32 – Provides the file server APIs used to access the file system directories in which messaging stores files containing message data. (omitted from other dependency diagrams)
+• BAFL – Provides API to load the correct messaging resource file dependent on the current language and to register the message store index file with the backup server. (omitted from other dependency diagrams)
+• ETEXT – Rich text APIs used to store body text of messages, this rich text format is a Symbian Proprietary format. (omitted from other dependency diagrams)
+• EUSER – Core Symbian OS utilities such as descriptors, arrays, client / server framework, cleanup stack and others (omitted from this and other dependency diagrams).
+• Central Repository – Centralised and secure storage facility for application settings, the message server stores message settings data in the central repository (from v9.0 and onwards).
+Note that debug only dependencies such as the flogger have been omitted from dependency diagrams.
+3.2.1.3 API Purpose - Further Elaboration
+3.2.1.3.1 Message Store
+The message server provides persistent storage of messages and messaging account settings. It does this by providing a message store consisting of a tree of message entries. Multiple clients can access the message store simultaneously. Each entry in the tree can represent an email account, folder of messages, message part, etc.
+
+Figure 4 Message Store
+Figure 4 shows an example message store. The tree is broken down in to three levels:
+1. The Root entry. This entry is just present to tie the tree structure together
+2. Service entries. There is one local service under which local folders and messages are stored, and zero or more remote services. Remote services represent message accounts.
+3. Message & Folder entries. Messages and folders, under the local service represent messages stored on the device. Messages and folders under remote services represent a local copy of messages that are present on a remote server. For example under a POP3 email service you would have copies of all the messages present on the POP3 email server, or under an SMS service you might find SMS messages that are stored on a SIM.
+The message server controls access to the entries in the store. It enforces the three levels therefore attempts to create message or folder entries directly under the root entry will fail.
+The message server provides three types of storage for each entry in the message store:
+• Index entry - TMsvEntry - intended to provide enough information for UI to display list views as shown in Figure 5. This consists of two strings and various flags (read, complete, has attachments etc).
+• Stream based file store - CMsvStore – provides storage of streams of data associated with UIDs. A standard UID is defined for storing body text. Other UIDs are specific. For example the email MTMs define a UID for storage of MIME headers. Compared to the index entry information this is used to store larger objects and is extensible, at the cost of being slower to access. From v9.0 and onwards CMsvStore provides an Attachment API for managing attachments. The Attachment API should be used as attachments can no longer be accessed directly due to Platform Security.
+• Directory of files – normally used for attachments.
+The only storage type that is always present is the index entry. The stream store and the directory of files are optional.
+
+Figure 5 Series 60 Inbox List View
+
+Figure 6 Remote and Local Entries
+As shown in Figure 6 the message store is split into two sets of entries:
+• Remote entries - entries that are representations of entries stored on a remote store .
+• Local entries - entries not linked to a remote store.
+The message server handles changes to local entries; internally it hands off changes to remote entries to the Server MTM that owns that service. Examples of operations that are handed off to Server MTMs are operations involving copying and moving messages to and from a remote service. See section 3.2.1.3.5 or more information on Server MTMs.
+Each entry within the store has a type:
+Folder – Messages can be grouped into folders. Standard folders such as inbox / outbox and user created folders.
+Message – Storage of the content of a message. Message entries can have child entries used to represent the structure of a message.
+Attachment – These represent attachments under a message entry.
+Root & Local Service Entry – There tie the tree structure together. However the Stream store associated with the root entry is sometimes used by UIs to store preferences e.g. default folder views etc.
+Remote Service - Represents a source and / or destination for messages. They are used to store the settings associated with the source / destination.
+Message Type Specific - MTMs can create other message types for use as child entries to messages they own. For example email uses a tree structure, with a message entry as the root, to represent the MIME structure of an email message; it uses folder entries to represent MIME folders and adds new types for entries representing the html body and text body parts of a message. This is shown in Figure 7.
+
+Figure 7 Email Message
+Using the message store to represent message structure allows reuse of the tree structure and makes it very simple to represent one message embedded in another. However this representation introduces performance issues as it results in each message having multiple files associated with it. The message server also keeps all index entries in memory; therefore this representation increases the memory footprint of the message server. Therefore when designing new MTMs we should think about moving away using multiple index entries to store one message in the message store.
+A default message store is created if the message server starts and no message store is present or a corrupt message store is present. The server will initially create a store with just a root entry, and then the server will create any standard folders defined in the resource file msgs.rsc. Finally the server will check whether an executable ‘mailinit.exe’ is present on the system, if it is present the server will launch the executable to allow customisation of the message store. The behaviour of ‘mailinit.exe’ is defined by the UI family of the device. However the typical behaviour is to load each of the UI Message Type Modules and allow each to perform any message type specific initialisation. For example the SMS plug-in typically creates a default service entry.
+
+3.2.1.3.2 Data File Storage (pre - v9.0)
+This section describes the files used by the message server before release v9.0. For information on the files used for release from v9.0 and onwards see section [3.2.1.3.3.1].
+Filename Access Purpose
+?:\system\Mail\index Private Message server index file, internal to message server
+?:\system\Mail\<8 hex digits> Shared via API Message server store files for services, clients access these via a messaging API.
+?:\system\Mail\<8 hex digits>.new Shared via API Temporary file used during committing message server store files.
+?:\SYSTEM\MAIL\<8 HEX DIGITS>_F\* Shared Files associated with a messaging service. These may be accessed directly by clients.
+?:\system\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits> Shared via API Message server store files for message entries, clients access these via a messaging API.
+?:\system\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits>.new Shared via API Temporary file used whilst committing message server store files.
+?:\system\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits>_F\* Shared Files associated with a message entry. These are accessed directly by clients.
+c:\system\data\msgs.ini Private Stores the drive containing the last used message store
+c:\system\Mtm\Mtm Registry v2 Private Cache of registered MTMs, internal to message server
+C:\system\data\sms_settings.dat Shared Copy of the SMS settings.
+?:\System\Mail\StoreInit.tmp Shared Created when message server runs ‘mailinit.exe’, ‘mailinit.exe’ should delete the file when it has successfully completed.
+?:\System\Mail\storedeleted.tmp Shared Created when message server finds and deletes a corrupt message store. Allows the UI to inform the user about the fact that the message store was corrupt.
+Files that are shown as private should only be accessed by the message server or by connectivity process for backup and restore purposes. Files listed as shared are accessed directly by messaging clients. Files listed as shared via API are accessed by client process but only via messaging APIs.
+3.2.1.3.3 Platform Security Compliant Message Store
+From v9.0 and onwards the message store is stored in the message server's data cage and the settings data are placed in the Central Repository. Access to the message store is only possible via message server APIs and not directly through file access. This leads to secured data storage and secured platform.
+3.2.1.3.3.1 Data caging
+Filename Purpose
+?:\private\<SID>\Mail\index Message server index file, internal to message server
+?:\ private\<SID>\Mail\<8 hex digits> Message server store files for services, clients access these via a messaging API.
+?:\ private\<SID>\Mail\<8 hex digits>.new Temporary file used during committing message server store files.
+?:\ private\<SID>\Mail\<8 hex digits>_F\* Files associated with a messaging service. These may be accessed directly by clients.
+?:\ private\<SID>\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits> Message server store files for message entries, clients access these via a messaging API.
+?:\ private\<SID>\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits>.new Temporary file used whilst committing message server store files.
+?:\ private\<SID>\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits>_F\* Files associated with a message entry. These are accessed directly by clients.
+c:\ private\<SID>\data\msgs.ini Stores the drive containing the last used message store
+c:\ private\<SID>\Mtm\Mtm Registry v2 Cache of registered MTMs, internal to message server
+?:\ private\<SID>\Mail\StoreInit.tmp Access via IPC call
+?:\ private\<SID>\Mail\storedeleted.tmp Created when message server finds and deletes a corrupt message store. Allows the UI to inform the user about the fact that the message store was corrupt.
+?\resource\messaging\bif\*.bif Registration data field with UID used in BIO framework
+
+3.2.1.3.4 How message centres display the message store
+The UI normally provides a Message Centre application to display the structure of the message store to the user. Different UIs map the structure to different views.
+
+Figure 8 Series 60 Message Centre (Composed from 2 screen shots)
+Figure 8 shows the top level view of the message centre application on a Series 60 phone. This shows that the message centre has hidden the local service and shows the standard folders at the same level as the services. Also the SMTP, SMS and MMS services are marked as hidden entries in the message store, and so do not appear in the message application.
+
+Figure 9 UIQ Message Centre
+However Figure 9 shows that the UIQ message centre has no 1-1 mapping from the structure in the message store to the structure shown to the user. Each of the message types is displayed as if its messages were contained in separate folders. Under each of these folders the user is presented with an inbox, outbox, send and drafts folder. This filtering is done in the UI layer as this functionality is not provided by the messaging API.
+3.2.1.3.5 Message Type Module Architecture
+
+Figure 10 Messaging MTM Structure (light coloured components are part of messaging subsystem)
+The MTM architecture is the plug-in scheme provided by the messaging framework to integrate different message transports into the message server. The plug-in scheme consists of four interfaces, the UI MTM, UI Data MTM, Client MTM and Server MTM. The messaging client applications loads and uses the first three which are loaded within the client’s process space. The final one the Server MTM is loaded within the message server process. The APIs for the client facing interfaces are extensible via run time type information provided by the QueryCapability API, and the InvokeAsyncFunction and InvokeSyncFunction APIs.
+3.2.1.3.5.1 UI MTM
+Handles requests from clients to view and edit messages or service settings. The MTM handles interaction with the message centre and as such the exact meaning of the APIs is defined by the UI. However common meanings are:
+• Create – Launches the editor with a new message.
+• Edit – If entry is a message this launches the editor; if entry is a service it edits the settings.
+• View – Launches the message viewer.
+• Display progress of an operation.
+3.2.1.3.5.2 UI data MTM
+This MTM provides fast access to UI components such as menu resources and bitmaps required by message centre for list views etc. Again the exact semantics are UI specific.
+There is a resource file defining UI specific functions, for example the Series 60 Messaging UI checks if the resource file contains text to display in the “New Message” menu.
+The UI data MTM also provides mapping from the message store’s TMsvEntry structure to Icons for the messaging list views and a status string, for example in the case of Nokia 9210 it is used in the outbox view to provide strings like “Resend 01:07” as shown in Figure 11. The class also provides functions to determine what operations are possible with a given entry. Examples of this are APIs that return whether the UI should allow the user to reply to the entry or to delete a service entry. The UI then uses this information to determine which menu options / short-cut keys should be allowed when the user selects a given entry.
+
+Figure 11 Nokia 9210 Outbox List View
+3.2.1.3.5.3 Client MTM
+Provides methods to create / reply and forward messages. Functions the Client MTMs provide are:
+• Create Message.
+• Reply to a Message.
+• Forward a Message.
+• Add / remove Addressees.
+• Add / remove body text.
+• Add / remove subject.
+• Add / remove attachments (the API cannot list attachments).
+The Client MTM interface is used by SendAs to provide a way of creating messages independently of the message type.
+3.2.1.3.5.4 Server MTM
+This is the final interface that makes up an MTM plug-in; it differs from the other three plug-ins in that it is loaded into the message server’s process space. The Server MTM provides access to messages under remote services. It handles connecting to remote servers to handle updating the local cache of these messages or to send messages copied to remote services when messages are copied to a remote service. The message server loads and hands off all message store operations that involve entries under a remote entry, these are the entries on the left-hand side of Figure 6.
+Functions that a Server MTM must implement:
+• Copy/MoveToLocal – called when the message server is asked to move or copy an entry that is currently under a remote service. A Server MTM might map this to retrieving a message from a remote mailbox.
+• Copy/MoveFromLocal – called when the message server is asked to move or copy from under the local service to a destination under a remote service. A Server MTM should map this to sending a message if the MTM supports sending.
+• Create, Delete, Change – called when the message server is asked to perform these operations on entries under a remote service.
+• StartCommand – this API provides a means of extending the API the Server MTM provides. Messaging clients pass a command ID and a selection of entries via the message server to the Server MTM. Examples of commands that Server MTMs might provide are: connect and synchronise the entries under a remote service with the messages on an email server, list SMS messages present on the phones SIM. These commands are MTM specific and therefore clients have to know which MTMs support which commands.
+3.2.1.3.5.5 MTM Registration
+MTMs must be registered with the message server so that clients can query what MTMs are present and the server knows which DLL to load to create a given MTM component. MTMs are registered by providing a resource file containing the MTMs UIDs, human readable name, and for each MTM interface it lists a DLL and the ordinal at which the constructor for that interface exists. The message server will search the ROM drive for MTM registration resource files on start-up and it will automatically register any MTMs found. For registration of MTMs installed on other drives, the message server provides an API to register and de-register an MTM. Registration will persist across a reboot, so an MTM only needs to be registered when it is installed on the system.
+When MTMs are registered or unregistered the message server will send events to all messaging clients with a message server session open.
+3.2.1.3.6 Message Server Client API
+The Messaging Server Client API breaks down into two categories: APIs for manipulation of the message store and utility APIs.
+3.2.1.3.6.1 Message Store manipulation APIs
+Requests from clients to modify the message store fall into three categories:
+1. Operations performed entirely with local entries (entries on the right-hand side of Figure 6) for example requests to create entries in the inbox, delete an entry from the drafts folder etc. The message server handles these operations directly.
+2. Operations that involve a remote entry (entries on the left-hand side of Figure 6) for example requests to delete an entry under a POP3 service, or copy a message to an SMTP service. The message server hands these operations off to the Server MTM that owns the service under which the remote entry is stored. The only exception to this rule is the ChangeAttributes API call. This modifies flags on an index entry and is handled by the message server for both local and remote entries. This means that a Server MTM can not rely on being called when flags like the Unread flag are changed. Note that operations can not involve two remote entries; therefore requests to copy entries between a remote service representing one POP3 account to a remote service representing another POP3 account will fail with an error.
+3. Requests that are explicitly directed at a Server MTM via the TransferCommand API. These commands are just passed to the correct Server MTM by looking up the Service ID and MTM of the first message in the selection passed into the command.
+The message server sends events when entries in the message store are modified to messaging clients that have a session open with the server.
+Where the API provides asynchronous functions to modify the message store or transfer a command to a Server MTM, the functions will return a message server operation object. This object can be used to request progress on operation or cancel the operation. Deleting the operation object returned, or closing the session used to make the request will result in the operation being cancelled, therefore a messaging client must remain running until operations it has requested have either completed or they will be cancelled. See appendix A.1 for an example of an asynchronous copy operation. If a Server MTM operating on the same remote service is already handling an operation, the message server will queue the new operation to be handled when the Server MTM becomes free. Requests for progress of operations that are queued will fail with KErrNotReady. The fact that the queue is based on the remote service ID means that you can have two Server MTMs of the same type running at the same time as long as they are operating on different services. So for example you can have two separate POP3 MTMs running synchronising different remote services with email servers.
+3.2.1.3.6.2 Utility APIs
+1. Access to MTM registries – These allow clients to construct instances of the interfaces an MTM implements.
+2. Register / Unregister an MTM.
+3. Change Drive – The message server closes the current message store and opens one on the drive specified. If no message store is present on the drive specified a new message store is created. The message sever can have only one mail store open at a time, if the current mail store is not available because a the disk the mail store is on is not present then the message server will switch the mail store back to the C: drive if an attempt is made to create a message in the inbox.
+4. Launching Editors – This launches the correct editor for a message. It is implemented by delegating the request to the UI MTM
+3.2.2 Messaging / Send As APIs
+3.2.2.1 Key Relationships and Dependencies
+
+Figure 12 SendAs Version 1 Dependencies
+SendAs version 1 and only present in releases before v9.0. SendAs uses the Messaging Client API to access the registry of Client MTMs and construct the Client MTM interfaces. The Client MTMs are then used for composing the message. SendAs requires clients to implement the MSendAsObserver interface. This interface is responsible for checking the return value of the capability queries made to Client MTMs that require a response and also for rendering message types that require it. The only message type supplied by Symbian that requires rendering is Fax, however this MTM has been removed in 8.0a and future releases.
+3.2.2.2 API Purpose - Further Elaboration
+3.2.2.2.1 SendAs API (pre – v9.0)
+The SendAs API makes use of the Client MTM interface and the Messaging Client API to provide a generic API for creating messages. Note despite the name of this component SendAs does not provide an API to send the message.
+SendAs builds a list of registered MTMs, then queries each MTM to check whether it supports sending, removing those MTMs from the list that do not support sending. This list is then provided to the messaging client application. At this point the application can add more constraints on the list of MTMs; for example it can insist the MTM supports Attachments or more than a certain size of body text. SendAs queries each of the MTMs about the requirements and will drop any MTMs from the list that does not meet them. When the application has finished adding requirements it selects one of the MTMs left in the list and uses that to compose the message, adding addresses, a subject, body text and attachments.
+SendAs supports setting a BIO Type for the message that is composed. This tells the transport that the body text represents a BIO Message. This is used when sending business cards from the contacts application as SMS messages; the contacts application puts the vCard data in the body text of the message and the transport sends it correctly. If the MTM in question supports attachments then the vCard is attached to the message.
+A new CSendAs object must be created for each message the application wishes to create.
+3.2.3 Platform Security Compliant SendAs Server (v9.0 onwards)
+
+Figure 13 SendAs Version 2 Dependencies
+From v9.0 and onwards the CSendAs has been replaced by the SendAs server component. The new SendAs server controls the access to the message store. Some of the key SendAs Server features are listed as follows.
+• Send a message once the capability policing of the client application has been completed.
+• Allow client applications to launch an editor for a specified message type.
+• Allow client applications to query the message type.
+The main client-side API is the RSendAs class. The client applications use this to connect to the Send-As server. The session object on the server-side is an instance of CSendAsSession.
+Client applications create messages using the RSendAsMessage API. Opening an RSendAsMessage object on Send-As server session creates a CSendAsMessage object in the Send-As server. There is a one-to-one mapping between an RSendAsMessage object and a CSendAsMessage object. This allows client applications to create multiple messages concurrently.
+
+3.2.4 Messaging / Schedule Send APIs
+3.2.4.1 Key Relationships and Dependencies
+
+Figure 14 Schedule Send Dependencies
+The Schedule Send Server MTM base class depends on the task scheduler to launch the schedule send executable at the correct time. To send the message with a package of data previously passed into the task scheduler by the Server MTM. The schedule send executable then uses the Messaging Client API to actually perform the requested operation.
+3.2.4.2 API Purpose - Further Elaboration
+3.2.4.2.1 Schedule Send
+The Schedule Send functionality is delivered by four components:
+Server MTM Base Class – The base class provides support to Server MTMs that wish to support scheduled operations.
+Data Structures – These are classes used to represent the data associated with a scheduled operation.
+Executable – The executable is run by the task scheduler at the scheduled time.
+The Task Scheduler – This component is part of the system libraries subsystem. Currently the SMS and Fax Server MTMs support scheduled sending.
+Clients request the Server MTM schedules operations via additional commands passed to TransferCommand API; this is passed to the Server MTM via the message server. The Server MTM packages the operation ID, a selection of message IDs, how often to poll for progress and an MTM specific buffer. It then passes this package of data to the task scheduler requesting that it launches the schedule send executable at the correct time with the packaged information.
+When the task scheduler launches the schedule send executable, it unpacks the schedule information and uses the Messaging Client API to request the Server MTM to perform the operation.
+Schedule Send supports a retry mechanism if the operation fails. The Server MTM has a resource file containing a mapping from the error codes the operation can fail with and actions to be performed. For example the SMS resource file has a mapping such that if the operation fails with an error code indicating a bad phone number the SMS will be set to failed and left in the outbox. Whereas if it fails with a error code indicating temporary network failure the send operation will be scheduled to be resent later with a maximum of three retries.
+3.2.5 Messaging / Watchers APIs
+3.2.5.1 Key Relationships and Dependencies
+
+Figure 15 Watcher Dependencies
+The watcher executable’s dependency on the message server is the result of a performance measure. The watcher process creates a message server session before initialising each of the watcher plug-ins and closes the session when it has finished. This keeps the message server running during initialisation avoiding starting and stopping the message server if each watcher plug-in opens and closes sessions.
+3.2.5.2 API Purpose - Further Elaboration
+The watcher framework consists of an executable that is launched when the device boots. The component that is responsible for launching it depends on the UI family. When the watcher.exe is launched it will load each DLL in z:\system\libs\watchers which has a second UID as KWatcherUid and calls the first DLL entry point to construct a CActive object.
+From v9.0 and onwards watcher DLLs are found by scanning the directory \resource\messaging\watchers for registry files. These files contain the name of a watcher DLL that can be loaded from ROM i.e. z:\sys\bin.
+The framework has retry behaviour if the first entry point leaves, in this case the watcher framework will start a timer and try and construct the watcher object 10 seconds later. Five attempts are made before the watcher plug-in is assumed to have failed completely. Once the watcher framework has constructed all the watchers it starts the active scheduler which should never exit.
+Watcher plug-ins typically make a request to another subsystem such that they will be completed when an external event like a fax line ringing or an SMS being received occurs. When the watcher has completed processing the request it will wait for the next event.
+No support for starting / stopping watchers is provided. This is a limitation that makes watchers unsuitable for operations like listening for messages beamed via IR, as the watcher should only run while the IR port is active.
+3.2.6 Messaging / Message URL Handler APIs
+3.2.6.1 Key Relationships and Dependencies
+
+Figure 16 Message URL Handler Dependencies
+3.2.6.2 API Purpose - Further Elaboration
+The Message URL Handler provides support for creating messages and launching messaging editors from URLs such as mailto:infobot@example.com?subject=current-issue. Note there is no dependency between the Message URL Handler application which processes the URLs and the Message URL Handler recognisers which maps from URLs to mime types.
+3.2.6.2.1 Message URL Handler Application
+This is a Symbian OS application that registers with the application framework that it can handle the mime types: x-epoc-url/fax, x-epoc-url/mailto and x-epoc-url/sms. When launched with a URL it will parse the URL to retrieve the address and other header fields and then use the SendAs API to create a new message with the correct address, headers etc. The application then uses the APIs in the MturUtils class provide by the mtmbase component in the messaging framework to launch the correct editor for the given message type. The application is marked as hidden and therefore should not be listed by UIs in application browsers.
+3.2.6.2.2 Message URL Recognisers
+This is a plug-in to the recogniser framework it will be called when the application framework wishes to recognise a file. Recognisers are called with the file name, in this case a URL, and a buffer containing the start of the file. The message URL recogniser compares the start of the URL with the URL schemes it recognises, if it finds a URL scheme it knows about it maps it to a mime type. The recogniser ignores the buffer passed in.
+Schemes recognised:
+Scheme Mime type
+mailto: X-Epoc-Url/mailto
+fax: X-Epoc-Url/fax
+sms: X-Epoc-Url/sms
+mms: X-Epoc-Url/mms
+See the application framework architectural description for more information on recognisers [R2].
+3.2.7 Messaging / SMS APIs
+3.2.7.1 Key Internal Relationships and Dependencies
+
+Figure 17 SMS Internal Dependencies
+3.2.7.2 Key External Relationships and Dependencies
+
+Figure 18 SMS External Dependencies
+3.2.7.3 API Purpose - Further Elaboration
+3.2.7.3.1 SMS Watchers
+The SMS watchers are made up of two watchers, the nbswatcher.dll and the wapwatcher.dll, and some common base classes in biowatcher.dll. The watchers listen for incoming messages from the SMS stack, part of the nbsprotocols subsystem [R3], and the WAP stack part of the WAP-Stack subsystem [R4].
+3.2.7.3.1.1 NBS Watcher
+The NBS watcher handles reception of SMS messages. When initialised by the watcher framework (see section 3.2.4) the watcher queries the bio messaging database for bio messages that are listed as having a type of ENbs. For each of these bio messages the watcher creates an object that opens a connection to the SMS stack and waits for the particular message type. The message types are either defined by the port number the message will be received on or by a string to watch for at the start of the message. For example Internet Access Configuration Point messages are start with “//SIAP11” and vCards are received on port 226. Finally the watcher listens for all other messages received from the SMS stack.
+When the NBS Watcher receives a non-class 2 SMS message it creates a new entry under the global inbox in the message store. For class 2 messages the entry is created in the class 2 folder as defined by the SMS settings, this may also be the global inbox. The details field of the entry is used to store the phone number of the incoming message or the name of the sender if the watcher finds a match for the phone number in the contacts database. The description field is used to store the first N characters of the SMS message, where N is defined in the SMS settings, or for bio messages the description as retrieved from the bio database. Bio messages also have the BioType field set to the UID of the bio message as retrieved from the bio database. The CSmsHeader class, which is a wrapper around the CSmsMessage class provided by the nbprotocols subsystem [R3], is used to externalise the SMS message to the entry’s CMsvStore. The watcher also places a copy of the body text of the message in the rich text stream of the entry’s CMsvStore.
+The NBS Watcher is also responsible for handing special SMS types including:
+• Replace Type Messages – When the watcher receives a message of this type it will scan the folder the message would have been delivered to for messages that have a matching protocol ID and from address. For each of the messages it checks whether the time stamps from the service centre and discards the older message.
+• Message Indications – The watcher can listen for incoming message waiting indications. The CSmsSettings class defines whether the watcher will listen and whether it will deliver the messages to the inbox or discard them. If the watcher is configured to listen for messages then it will use the SMS utilities in the SMS Client MTM to decode the message to determine the notification type and number of messages, e.g. 3 Email messages waiting, the strings for these messages are in the smss.rss resource file.
+• Delivery Reports – As with Message Indications the watcher can be configured to listen for these and again the SMS utilities get a string from the smss.rss resource file to put in the description field.
+The NBS Watcher handles changes to the bio database using the observer mechanism provided by the bio message database to observe when bio message types are added or removed and starting or stopping the object watching for that bio message type.
+3.2.7.3.1.2 WAP Watcher
+The WAP watcher listens for incoming messages from the WAP stack using the WAP message API [R4]. To determine ports to use to listen for messages the watcher queries the bio message database for bio message types EWsp, EWspSecure, EWap, EWapSecure and registers as an observer of the bio database and so will listen for new bio message with these types as they are added. The watcher stores the messages in the global inbox tagged with the bio type listed in the bio message database.
+3.2.7.3.2 SMS Client MTM
+The SMS Client MTM implements the standard set of Client MTM APIs described in Client MTM. In addition it provides:
+• Access to the CSmsHeader object that is used to represent the SMS message.
+• Access to the SMS settings stored in the associated SMS service.
+• The APIs required by Send As to allow Send As to create SMS messages including setting the bio type of the message to allow clients of Send As to send bio messages such as vCards and vCals. The data of the bio message is stored in the body text of the SMS message.
+• Simple check for valid SMS addresses, and SMS address is considered valid if it contains at least one digit.
+• Reading and writing SIM parameters.
+3.2.7.3.3 SMS Utilities
+These provide:
+• Classes to represent and store SMS messages (CSmsHeader), and SMS settings (CSmsSettings, CSmsMessageSettings) and a SMS number (CSmsNumber).
+• The CSmsHeader class contains and allows clients to access the CSmsMessage class that the nbsprotocols subsystem provides. This contains the entire SMS message and not just the header.
+• Functions to generate descriptions and details fields to store with SMS messages, including decoding special messages such as message indication and status report messages, reading resource file for descriptions strings of special messages, using the contacts database to replace phone numbers with names.
+• API to validate a GSM number.
+• Find the TMsvId of the SMS service entry.
+3.2.7.3.4 SMS Server MTM
+3.2.7.3.4.1 Sending Messages
+The SMS Server MTM handles sending of SMS and WAP messages via the SMS stack and the WAP stack. To support this it implements the CopyFromLocal API inherited from the Server MTM base class. It implements this as sending SMS messages and moving successfully sent messages to the Sent folder. When sending the SMS message the Server MTM checks the bio type of the message and uses the bio database to check the transport type for the bio message. The MTM supports ENbs that is sent via the SMS stack and EWap, EWapSecure that are sent via the WAP stack. The MTM does not support EWsp or EWspSecure although the watchers do support receiving them.
+If a message fails to send, sending is retried according to the settings in the smss.rss resource file as described in the schedule send section 3.2.3.
+3.2.7.3.4.2 Scheduling Messages
+The SMS Server MTM implements scheduled sending API by sub-classing from the schedule send Server MTM (see section 3.2.3). It accepts requests from clients either via the SMS Client MTM InvokeAsync API or via the CMsvSession::TransferCommand API to schedule messages to be sent or to delete existing schedules. When it receives a request to schedule a message it packages up the command and uses the scheduled send functionality to request that the task scheduler ask it to send the messages at a future point in time.
+3.2.7.3.4.3 Phone Store
+The phone store is the name given to storage of SMS messages outside of the message store. In the case of GSM phones this is the SIM. The SMS Server MTM accepts requests from clients to copy/move messages to and from the SIM and delete messages from the SIM. For example when copying to the SIM it packages up the SMS message and passes it to the SMS stack with a request to write it to the SIM. If the class2 folder has been set in the SMS settings class then the Server MTM will copy the SMS message to the SIM and then update the SMS message in the message store with details of the slot on the SIM that has been used to store the SMS and the fact that it is stored on the SIM.
+3.2.7.3.4.4 SIM Parameters
+The Server MTM provides functions to read / write SIM parameters, again these requests are passed to the SMS stack to be processed.
+3.2.8 Messaging / CDMA SMS APIs
+3.2.8.1 Key Internal Relationships and Dependencies
+
+Figure 19 CMDA SMS Internal Dependencies
+3.2.8.2 Key External Relationships and Dependencies
+`
+Figure 20 CDMA SMS External Dependencies
+3.2.8.3 API Purpose - Further Elaboration
+3.2.8.3.1 CDMA SMS Watchers
+The CDMA SMS watchers are made up of six watchers, the cdmanbswatcher.dll, vmnwatcher.dll, wemtwatcher.dll, wmtwatcher.dll, wptwatcher.dll, and the wapwatcher.dll, and some base classes in biowatcher.dll and cdmasocketwatcher. While the WAP watcher is common for both GSM and CDMA, the other watchers: CDMA NBS watcher, VMN watcher, WEMT watcher, WMT watcher, and the WPT watcher are used for CDMA only. The watchers listen for incoming messages from the CDMA SMS stack, part of the nbsprotocols subsystem [R3], and the WAP stack part of the WAP-Stack subsystem [R4].
+3.2.8.3.1.1 CDMA NBS Watcher
+The CDMA NBS watcher is similar to the NBS watcher and it handles bio messages defined in bio database. The CSmsHeader class is extended to wrap around the CCdmaSmsMessage class provided by the nbprotocols subsystem [R3], and is used to externalise the CDMA SMS message.
+For handling special CDMA SMS type, the CDMA NBS watcher is responsible for handling Message Indications as described in section 3.2.7.3.1.1 NBS Watcher.
+3.2.8.3.1.2 WAP Watcher
+The GSM WAP watcher is used to handle CDMA WAP message as well. The WAP watcher listens for incoming messages from the WAP stack, which can listen from the CDMA SMS stack or GSM SMS stack as appropriate. See 3.2.7.3.1.2 for more info about WAP watcher.
+3.2.8.3.1.3 Other CDMA Watchers
+The VMN watcher, WEMT watcher, WMT watcher and WPT watcher are CDMA watchers that handle reception of CDMA SMS messages. All CDMA SMS messages are associated with a teleservice. Therefore, each of the CDMA watchers is responsible for handling one teleservice: VMN watcher handles VMN SMS messages, WEMT watcher handles WEMT SMS messages, WMT watcher handles WMT SMS messages, and WPT watcher handles WPT SMS messages. The CSmsHeader class is reused to externalise the CDMA SMS message.
+The CDMA watchers are also responsible for handling special SMS types including:
+• Duplicate Message – When the watcher receives a duplicate message, it will discard the duplicate message as defined by the CDMA service settings.
+• User Acknowledge – The watcher can listen for user acknowledgment message of its teleservice type.
+• Delivery Acknowledge – The watcher can listen for delivery acknowledgment message of its teleservice type.
+• Read Acknowledge – The watcher can listen for read acknowledgment message of its teleservice type.
+3.2.8.3.2 CDMA SMS Client MTM
+The CDMA SMS Client MTM implements the standard set of Client MTM APIs described in Client MTM. In addition it provides:
+• Access to the CSmsHeader object that is used to represent the SMS message.
+• Access to the SMS settings stored in the associated SMS service. These settings are store in file store pre v9.0 but stored in Central Repository from v9.0 onwards.
+• The APIs required by Send As to allow Send As to create SMS messages including setting the bio type of the message to allow clients of Send As to send bio messages such as vCards and vCals. The data of the bio message is stored in the body text of the SMS message.
+• Simple check for valid SMS addresses, and SMS address is considered valid if it contains at least one digit.
+• Reading and writing SMS messages to R-UIM.
+3.2.8.3.3 CDMA SMS Utilities
+The CDMA version of SMS utilities are binary compatible with the GSM version of SMS utilities. But the classes that store SMS Message (CSMSHeader), and SMS settings (CSmsSettings, CSmsMessageSettings) and SMS number (CSmsNumber) are extended to store CDMA information. The CSmsHeader class is extended to contain and allow clients to access the CCdmaSmsMessage in addition to the CSmsMessage. Other functions provided by the GSM SMS Utilities is also provided by the CDMA version of SMS utilities, see 3.2.7.3.3 for information about GSM SMS Utilities.
+3.2.8.3.4 CDMA SMS Server MTM
+3.2.8.3.4.1 Sending Messages
+The CDMA SMS Server MTM handles sending of CDMA SMS and WAP messages via the CDMA SMS stack and the WAP stack. To support this it implements the CopyFromLocal API inherited from the Server MTM base class. It implements this as sending SMS messages and moving successfully sent messages to the Sent folder. When sending the CDMA SMS message the Server MTM will use the appropriate teleservice type. The MTM supports ENbs that is sent via the SMS stack and EWap, EWapSecure that are sent via the WAP stack. The MTM does not support EWsp or EWspSecure although the watchers do support receiving them.
+If a message fails to send, sending is retried according to the settings in the smss.rss resource file as described in the scheduled send section 3.2.4.
+3.2.8.3.4.2 Scheduling Messages
+The CDMA SMS Server MTM implements scheduled sending API by sub-classing from the schedule send Server MTM similar to implemented in the GSM SMS Server MTM. See 3.2.7.3.4.2 for more information.
+3.2.8.3.4.3 Phone Store
+In the case of CDMA phones, phone store can be phone-based storage or R-UIM based storage. The CDMA SMS Server MTM accepts requests from clients to copy/move messages to and from the phone/R-UIM and delete messages from the phone/R-UIM. For example when copying to the R-UIM it packages up the SMS message and passes it to the CDMA SMS stack with a request to write it to the R-UIM.
+3.2.8.3.5 Configuration for using CDMA SMS MTM
+The CDMA messaging components currently only support single mode, but it is designed such that it can become multimode in the future. Currently, -Dcdma option is used to for selecting CDMA mode for using emulator and building ROM.
+
+
+3.2.9 Messaging / Email APIs
+3.2.9.1 Key Internal Relationships and Dependencies
+
+Figure 19 Email Internal Dependencies
+
+3.2.9.2 Key External Relationships and Dependencies
+
+Figure 20 Email External Dependencies
+3.2.9.3 API Purpose - Further Elaboration
+3.2.9.3.1 Email Overview
+The Email plug-ins consist of a set of utilities and MTMs for POP3, IMAP4 and SMTP. For each email account a pair of services entries is created in the message store. For a POP3 account there will be an SMTP service and a POP3 service, for an IMAP4 account there will be an SMTP service and as IMAP4 service. These entries are used to store the settings for the email transport. Each of the service entries has its related ID set to the other member of the pair. The SMTP service is created invisible so the user only sees the POP3 or IMAP4 service entry, copying a message to the SMTP service will cause the SMTP Server MTM to attempt to send the message. The POP3 and IMAP4 MTMs provide functionality to synchronise with a remote email server this is achieved by extending the Client MTM interface via the InvokeAsync API. Synchronisation of a POP3 or IMAP4 account will result in copying headers and optionally body text and attachments from the email server and creating message entries under the POP3 or IMAP4 service entry.
+Email messages are represented in a common format whether they are being sent via SMTP or downloaded via POP3 or IMAP4. The email client utilities provide the classes for creating and manipulating the entry structure used to store emails. The email server side utilities provide classes to convert between the entry structure used to store emails in the message store and RFC2822 email messages sent to SMTP servers and retrieved from POP3 servers. IMAP4 email messages are parsed by the email server and the IMAP4 Server MTM requests and stores the individual parts of the messages.
+3.2.9.3.2 Email Client Utilities
+The email client utilities are part of the imcm DLL and provide classes for:
+• Storage of email messages including mime headers, RFC2822 headers, attachments, body text and encoding information in the message store
+• Manipulating email messages, for example adding attachments, replying etc.
+• To wrap up the character converters used to convert between standard character sets and Unicode. These make use of the charconv component that is part of the system libraries subsystem.
+• Storage of Email settings in the message store.
+• Progress information for email operations.
+The utilities are used directly by clients to access parts of email messages for display. CImEmailMessage provides the functionality used by clients displaying email messages, including listing attachments, getting body text and resolving URIs in M-HTML messages.
+The Email Client MTMs use the utilities when they are asked to create, reply to and forward messages CImEmailOperation provides the functionality to perform these operations. Each email message is represented by a parent message entry and then entries to represent mime folders and mime parts, see Figure 7 for an example, so adding or deleting mime parts involves walking the tree of entries and inserting / removing entries as appropriate.
+3.2.9.3.3 Email Server MTM Utilities
+The Email Server MTM Utilities are responsible for generating and parsing of RFC2822 format email messages and providing an API to wrap up a TCP/IP connection to a remote email server.
+• Parsing of RFC2822 Email Messages – The utilities provide an API that accepts the text of an RFC2822 email message a line at a time and stores the email message in messaging’s internal format for email messages. See the Email Client Utilities for details of this format. The API handles storing of RFC2822 headers, MIME headers, decoding of Base64 encoded or uuencoded attachments and decoding of text received in character sets supported by the charconv component. This API is only accessible to Server MTMs, as it requires classes that can only be instantiated while running within the message server process. See the Messaging Functional Specification [R1] for detail on which email specifications the utilities support.
+• Generation of RFC2822 Email Messages – The utilities provide an API to convert an email in messaging’s internal format into an RFC2822 email message. The API provides access to the RFC2822 text a line at a time for streaming to an SMTP server. The exact format of the email depends on the settings passed in; the API can generate plain RFC2822 email messages with uuencoded attachments, MIME email messages with Base64 encoded attachments, or M-HTML email messages with Base64 encoded attachments. See the Messaging Functional Specification [R1] for detail on which email specifications the utilities support.
+• TCP/IP socket wrapper – The utilities provide a class that abstracts a TCP/IP socket supplied by the networking subsystem into an API that supports sending and receiving lines of text to / from a remote server. This API is used to connect to remote email servers by each of the email Server MTMs. The API can either create insecure or secure sockets enabling the SSL encryption provided by the networking subsystem. It also supports changing an insecure socket into a secure socket, this enables the email Server MTMs to implement email protocols where the initial connection to the server is insecure and then a secure socket is negotiated before sending or requesting any sensitive information.
+3.2.9.3.4 POP3 MTMs
+The POP3 MTMs implements the functionality to synchronise the local message store with a remote POP3 email server.
+3.2.9.3.4.1 Client MTM
+The POP3 Client MTM implements the standard Client MTM APIs and other extensions:
+• Reply to, forward – These are accessible via the ReplyL and ForwardL APIs of a Client MTM and are implemented as calls to the email utilities class CImEmailOperation.
+• Reply to, forward, create new messages, create receipts and forward as attachment – These are accessible as commands available via the InvokeAsyncFunction API of the Client MTM, they are implemented as calls to CImEmailOperation.
+• Connecting, disconnecting and copying email while connected – These operations are accessible as commands available via the InvokeAsyncFunction API of the Client MTM, they are implemented as calls to the POP3 Server MTM.
+• Querying connection status – This command lets clients know whether the POP3 Server MTM is connected to an email server, and is available via the InvokeAsyncFunction API of the Client MTM. The Client MTM requests the information from the Server MTM.
+• Compound operations – The Client MTM provides functionality to wrap up connecting to email servers, copying / moving new messages or a selection of messages, and then optionally disconnecting. These commands are available via the InvokeAsyncFunction API of the Client MTM. The Client MTM implements this by using the CImPOP3GetMail class which requests the correct sequence of operations from the Server MTM, waiting for each operation to complete before requesting the next one.
+• Send on next connection If the Client MTM gets a request to connect to an email server it will check whether the POP3 settings. If send on next connection is requested it will launch the autosend.exe executable (see section 3.2.7.3.7) to handle sending messages waiting in the outbox.
+• Offline operations – The POP3 Client MTM has a command to cancel offline operations, this is available via the InvokeAsyncFunction API of the Client MTM. The Client MTM passes the request to the Server MTM.
+3.2.9.3.4.2 Server MTM
+The POP3 Server MTM handles the communication with the remote POP3 server and implementation of the POP3 protocol. The MTM uses CImTextServerSession to handle the communication with the email server and CImRecvConvert to parse the email messages downloaded, both are provided by the Email Server MTM Utilities.
+• Connect – The POP3 Server MTM will open a socket to the email server using CImTextServerSession and login user the username / password in the POP3 settings. After a successful connection the Server MTM will attempt to synchronise the current state of headers stored on the email server with the set stored in the message store and then start any pending offline operations. After the connect operation has completed the Server MTM will inform the message server that it is expecting more operations via the CommandExpected API and therefore the message server will not delete and unload the Server MTM.
+• Populate Message – The POP3 Server MTM treats requests to copy a message from and to the POP3 service as a request to download the full message.
+• Offline operations – When the POP3 Server MTM receives a request to copy, move, or delete and is not connected to a POP3 email server the Server MTM will store the operation in the CMsvStore of the entry being modified and perform the operation on the next connection to the email server.
+• Disconnect – When disconnecting from a remote email server the POP3 MTM will run any pending offline operations stored. After the disconnect operation completes the Server MTM will allow the message server to delete and unload the Server MTM by setting the CommandExpected API to false.
+3.2.9.3.5 IMAP4 MTMs
+The IMAP4 Server MTM implements the functionality to synchronise the local message store with a remote IMAP4 email server.
+3.2.9.3.5.1 Client MTM
+The IMAP4 Client MTM implements the standard Client MTM APIs and other extensions:
+• Connecting, disconnecting, synchronising, un/subscribing folders – These operations are accessible as commands available via the InvokeAsyncFunction API of the Client MTM, they are implemented as calls to the IMAP4 Server MTM.
+• Send on next connection – If the Client MTM gets a request to connect to an email server it will check whether the IMAP4 settings. If send on next connection is requested it will launch the autosend.exe executable (see section 3.2.7.3.7) to handle sending messages waiting in the outbox.
+• Reply to, and forward messages – These are accessible via the ReplyL and ForwardL APIs of a Client MTM and are implemented as calls to the email utilities class CImEmailOperation.
+• Reply to, forward, create new, create receipt, forward as attachment – These are accessible as commands available via the InvokeAsyncFunction API of the Client MTM, they are implemented as calls to CImEmailOperation.
+• Querying connection status – These commands let clients know whether the IMAP4 Server MTM is connected to an email server and whether it is currently processing a request. They are available via the InvokeAsyncFunction API of the Client MTM. The Client MTM requests the information from the Server MTM.
+• Compound Connection and synchronisation – The IMAP4 Client MTM provides a compound operation that connects and synchronises with an IMAP4 server. This operation is implemented as a client side object that combines requests to the IMAP4 Server MTM. The client side operation can complete the client request either after the connection, after the connection + sync or after the connection + sync + disconnect. The client will keep requesting that the inbox be resynchronised at a configurable interval so new messages received in the inbox on the server will appear under the IMAP4 inbox. The CImapConnectAndSyncOp class handles these compound operations.
+• Compound Connect and copy / move / populate messages – The IMAP4 Client MTM provides a compound operation that connects to an IMAP4 server and copies moves or populates messages. The implementation is provided by the CImImap4GetMail class which makes calls back into the IMAP4 Client MTM.
+• Offline operations – The IMAP4 Client MTM has a command to cancel offline operations, this is available via the InvokeAsyncFunction API of the Client MTM. The Client MTM passes the request to the Server MTM.
+3.2.9.3.5.2 Server MTM
+The IMAP4 Server MTM handles the communication with the remote IMAP4 server and implementation of the IMAP4 protocol. The MTM uses CImTextServerSession to handle the communication with the email server. The IMAP4 Server MTM opens two connections to the IMAP4 server this enables users to download messages while the Server MTM is performing a background synchronisation if requested by the Client MTM.
+• Connect – The IMAP4 Server MTM will open a socket to the email server using CImTextServerSession and login using the username / password in the IMAP4 settings. After a successful connection the Server MTM will optionally attempt to synchronise the current state of headers stored on the email server with the set stored in the message store and then start any pending offline operations. After the connect operation has completed the Server MTM will inform the message server that it is expecting more operations via the CommandExpected API and therefore the message server will not delete and unload the Server MTM.
+• Copy, Move messages – The IMAP4 Server MTM supports copying and moving messages between folders on the IMAP4 server and between the IMAP4 server and local folders.
+• Delete messages – The IMAP4 Server MTM will mark the email as deleted on the server; however it will not be deleted until the IMAP4 Server MTM disconnects from the server.
+• Folders – The IMAP4 Server MTM will allow folders to be subscribed, unsubscribed, renamed, copied, moved, and created within the IMAP4 service. Subscribing to a folder means that it will be visible to the user and synchronised with the remote server. The inbox is always subscribed.
+• Offline operations – When the IMAP4 Server MTM receives a request to copy, move, or delete and is not connected to an IMAP4 email server the Server MTM will store the operation in the CMsvStore of the entry being modified and perform the operation on the next connection to the email server.
+• Disconnect – When disconnecting from a remote email server the IMAP4 MTM will run any pending offline operations stored. After the disconnect operation completes the Server MTM will allow the message server to delete and unload the Server MTM by setting the CommandExpected API to false.
+
+3.2.9.3.6 SMTP MTMs
+The SMTP MTMs provide functionality to send email messages. They are made up of the Client MTM that is part of the imcm DLL and the Server MTM.
+3.2.9.3.6.1 Client MTM
+The SMTP Client MTM implements the standard Client MTM APIs including the functions required to allow clients of Send As to create email messages.
+3.2.9.3.6.2 Server MTM
+The SMTP MTMs provide functionality to send email messages; it interprets requests to copy entries to an SMTP service as a request to send those messages. In addition it responds to two extended commands via the StartCommand Server MTM interface. These commands are KSMTPMTMIsConnected that responds with whether the Server MTM is currently connected to a remote SMTP server and KSMTPMTMSendOnNextConnection which performs the same operation as copying a selection of messages to an SMTP service. The only difference between the copy operation and the KSMTPMTMSendOnNextConnection operation is that the latter can be called without a selection of messages.
+When the Server MTM receives a request to send messages it builds a selection of messages consisting of the messages passed into the operation and any messages waiting in the outbox to be sent. To determine which messages in the outbox are waiting to be sent the SMTP server checks for messages that have the same service ID as the destination of the send operation and have a sending state of KMsvSendStateWaiting, KMsvSendStateScheduled or KMsvSendStateResend. This means that any request to send messages may result in more messages being sent than explicitly listed in the selection passed to the send operation.
+The Server MTM restores its settings from the SMTP service it has been asked to copy the messages to. Then it connects to the SMTP server using the CImTextServerSession class in the Email Server MTM Utilities, passing in the SMTP server address and TCP/IP port number from the SMTP settings. Then for each message to be sent the Server MTM uses the Email Server MTM utilities to generate an RFC2822 format message to send to the SMTP server, the RFC2822 text is generated on the fly as the data is sent to the SMTP server. If the SMTP server accepts the message to be sent then the Server MTM moves the message to the sent folder and sets its sending state to sent. If the SMTP server rejects the message then the Server MTM leaves the message in the outbox and sets the sending state to failed. Separate emails are generated for BCC recipients to ensure that the SMTP server doesn’t incorrectly include BCC recipients in emails sent to addresses in the To and CC fields of the email.
+3.2.9.3.7 Autosend
+The Autosend component is an executable that is kicked off by the POP3 and IMAP4 Client MTMs if the send on next connection setting is set. This executable will just make a request to the SMTP Server MTM to send messages associated with the SMTP service related to the POP3 or IMAP4 service, wait for the operation to finish and then exit.
+3.2.10 Messaging / MMS APIs
+The MMS module has been removed from v9.0 and onwards.
+3.2.10.1 Key Internal Relationships and Dependencies
+
+Figure 21 MMS Internal Dependencies
+3.2.10.2 API Purpose - Further Elaboration
+3.2.10.2.1 MMS Overview
+The MMS MTM provides functionality for creating, accessing, sending and receiving MMS messages. Messages are sent and received without the client application needing to open or close any kind of session. The management of the MMS session is handled entirely within the MTM.
+MMS clients are alerted when a new message is available for download via the WAP Push mechanism. A WAP push watcher is provided to handle these notifications. After the notification the message can be downloaded over WSP or HTTP. Messages are sent by posting the data over WSP or HTTP. The Symbian MMS implementation can handle sending or receiving MMS message over either protocol.
+MMS messages are based on the MIME format but are binary encoded using WSP. Note that MMS messages are encoded in this way even if they are posted over HTTP as opposed to WSP. The codec component is responsible for this encoding and decoding.
+3.2.10.2.2 MMS Utilities
+3.2.10.2.2.1 Key External Relationships and Dependencies
+
+Figure 22 MMS Utilities External Dependencies
+The MMS utilities provide the message and settings encapsulation classes. The MMS settings and messages are stored in the message store, the MMS utilities provide the interfaces to access this data.
+3.2.10.2.2.2 Settings
+The settings functionality provided by the MMS utilities allows the messaging client to persist MMS settings in the message store. Supported settings include:
+ MMSC (MMS server) address
+ WSP or HTTP transport
+ Autofetch messages on notification
+ Preferred IAP for the MMS network connection
+The settings functionality is also used by the server MTM to retrieve the settings prior to message sending or fetching.
+3.2.10.2.2.3 Message Encapsulation
+The message classes provide the message access functionality. Messages can be created, stored, restored and read using these classes. Functionality includes:
+ Adding media objects to the message
+ Enumerating through media objects
+ Adding recipients, subject line, etc. to a message
+ Adding other headers to the message, e.g. expiry date
+ Finding the appropriate media object for a given URI in the SMIL part (URI resolving)
+The message data is stored in the message store using one entry per message regardless of the number of media objects added to the message. This is preferable to using multiple message entries as it is faster and uses less disk space.
+Most of the message access code is common whether it is being used on the client or server side, however some parts of it are specific. For this reason it is essential that the appropriate client or server side CMmsMessage derived class is used.
+3.2.10.2.3 MMS Watcher
+3.2.10.2.3.1 Key External Relationships and Dependencies
+
+Figure 23 MMS Watcher External Dependencies
+
+The MMS watcher plug-in is responsible for intercepting incoming MMS notifications and delivery reports then taking the appropriate action. It is implemented as a WAP Push watcher plug-in.
+When an MMS notification is received an MMS entry is created in the inbox using the MMS utilities. At this point the entry has its incomplete flag set. If the settings have the autofetch option selected then the MMS watcher initiates the fetch operation via the MMS client MTM.
+If a delivery report is received then the delivered flag is set on the appropriate sent message. If an outgoing message was sent to several recipients then there will be several delivered flags. A delivery report from each recipient will set the appropriate delivered flag.
+3.2.10.2.4 MMS Client MTM
+3.2.10.2.4.1 Key External Relationships and Dependencies
+
+Figure 24 MMS Client MTM Dependencies
+As with most other MTMs the MMS client MTM provides access to the server MTM functionality for messaging clients. It also implements the Send-As interface and reply and forward functionality.
+3.2.10.2.4.2 Send-As Implementation
+The Client MTM Send-As interface is implemented in the MMS Client MTM. The implementation differs slightly from other MTMs because additional presentation content may be generated depending on the media objects that are added. When simple combinations of images, sounds and text are added a SMIL presentation is generated to link them together. This is preferable to simple adding the objects as attachments where some clients render them as a list of files and others fail to render them at all.
+The SMIL data is constructed using templates stored in resource files, the GMXML (SMIL) composer is not used.
+3.2.10.2.4.3 Reply / Forward
+The Client MTM can be used to create replies to received messages or to create forwarded responses. The reply and forwarding operations are performed asynchronously.
+3.2.10.2.5 MMS Server MTM
+3.2.10.2.5.1 Key External Relationships and Dependencies
+
+Figure 25 MMS Server MTM Dependencies
+The Server MTM is the most complicated part the MMS implementation. It handles all of the state information required to send or fetch MMS messages. It is also responsible for managing the HTTP or WSP session and the connections to the phone network.
+3.2.10.2.5.2 Operations
+All MMS server MTM functionality is encapsulated in operations. An operation consists of the setup of a session, the sending, fetching and acknowledgements when appropriate, it then closes the session. The messaging client initiates an operation with a single call to the Client MTM, there is no need for the messaging client to explicitly establish the session or to know about the internal states. However, these internal states are available to the messaging client via the progress structure if this level of user feedback is required.
+Two types of operation are supported, background and foreground:
+A maximum of one foreground operation can be running at any one time. The messaging client can poll the server MTM for the progress of a running foreground operation, likewise it can cancel it if necessary.
+A background operation does not support progress information and can not be cancelled by the messaging client. It is possible to initiate background operations even if other background or foreground operations are pending. However, background operations are queued and a maximum of one will actually be running at any one time.
+The MMS watcher uses a background operation to perform automatic fetching. While the background autofetch is occurring it is still possible to start a foreground operation (such as sending a message) if required.
+3.2.10.2.5.3 Session and Connection Management
+The server MTM uses the HTTP Transport Framework to enable the HTTP or WSP session. HTTP or WSP can be selected at runtime by selecting the appropriate option in the settings. The server MTM is responsible for reading any HTTP proxy details from the CommDB and passing it to the HTTP framework. See the http transport framework architectural description for more information on recognisers [R5]
+The server MTM is also responsible for managing the connection to the phone network. Connections are opened when required using the RConnection mechanism, multi-homing is supported provided that the underlying HTTP framework transport plug-in also supports it.
+3.2.10.2.6 MMS Codec
+The MMS Server MTM is in charge of the state transitions, connection, session, the actual posting and fetching of the data from them, however it does not encode or decode the MMS PDUs. The encoding and decoding is performed by the MMS Codec.
+For decoding the Server MTM passes the Codec the MMS PDU data in a descriptor for processing. If the PDU contains a received MMS message then the message entry is updated with the decoded MMS data.
+For encoding the Server MTM passes a reference to the message store entry containing the un-encoded MMS data. The Codec then encodes it and returns the PDU to the Server MTM in a descriptor.
+
+
+3.2.11 Messaging / BIO APIs
+3.2.11.1 Key Internal Relationships and Dependencies
+
+Figure 26 BIO Message Internal Dependencies
+3.2.11.1.1.1 Key External Relationships and Dependencies
+
+Figure 27 Bio Parser External Dependencies
+
+3.2.11.2 API Purpose - Further Elaboration
+3.2.11.2.1 BIO Overview
+The BIO messaging components have been designed to unify and simplify the way in which system messages are processed. In this context ‘system messages’ refers to messages received on the device which are intended to update some attribute(s) on the system as opposed to being presented to the user. Examples of these types of messages include vCards which are parsed and then displayed to the user and when accepted modify the users contact database and OTA configuration messages which are again parsed before display to the user and if accepted create email accounts or internet access points.
+The BIO messaging components can be broken down into three groups:
+1) The BIO MTM - To initiate the parsing and processing of BIO messages
+2) The BIO Database - Maps port numbers, MIME types, etc. to bio types in order to identify the type of incoming BIO messages.
+3) The BIO Parsers - To parse and process the BIO message payload
+BIO messages are not receive by the bio messaging framework, they come over other message transports for example see section 3.2.6.3.1 on the SMS watchers which describes how the SMS watchers receive bio messages and use the bio framework to tag the messages with the correct bio id.
+3.2.11.2.2 BIO MTM
+The BIO client MTM is called by the messaging client to parse or process a BIO message that has been saved in the message store. It is the responsibility of a BIO watcher to save the BIO message with the BIO flag and the appropriate BIO type set.
+The BIO client MTM does very little, its primary task is to pass on the messaging client request to the server MTM. Two operations are supported, parse and process.
+The messaging client is expected to initiate the parsing of the BIO message before processing it. The parsing step involves analysing the data and storing it in a form that can be displayed to the user via the BIO message viewer.
+Once the message has been parsed the messaging client can initiate the processing of the message.
+The BIO server MTM is responsible for deferring the parsing and processing to the appropriate BIO parser. The behaviour for the parsing and processing steps varies between parsers. See the BIO Parsers section for more information.
+The bio MTM does not support sending messages and therefore does not support reply / forwarding messages. For bio messages sending / reply etc. is supported by the particular MTM that the message is sent over, for example SMS.
+3.2.11.2.3 BIO Database
+The BIO database is used to identify the type of BIO messages. It maps message attributes such as port number, MIME type or leading string to a BIO type. These are attributes are then used by clients of the bio framework to know what ports to listen for messages on. For example the SMS watchers use the leading string to wait for SMS messages that start with that string and when storing those messages in the inbox tag them with the bio id associated with that leading string. See the SMS watcher section 3.2.6.3.1 for more examples of how the BIO database can be used.
+3.2.11.2.4 BIO Parsers
+The BIO parsers are plug-ins for parsing and processing incoming BIO messages. They are invoked by the BIO Server MTM depending on the BIO type of the message being processed. Each BIO parser implements two functions, ParseL and ProcessL. The level of functionality varies between parsers. Some parsers update the final repository with the received data, e.g. WAPP updates the CommDB with the received settings. Some parsers simply save the data in an unparsed state for processing by another component, this secondary parsing is not part of the BIO framework and must be initiated by the messaging client. An example is when GFP saves vCard data as a file as opposed to updating the contacts database, the UI must then invoke the Versit parser to parse the vCard and commit it to the contacts database.
+3.2.11.2.4.1 Generic File Parser (GFP)
+The generic file parser can be used to identify and save a variety of BIO data types, e.g. vCards and vCals. The Generic File Parser does not process the data, it simply saves it in the message store for processing by another component. The file is saved as an attachment of the message entry that was parsed.
+3.2.11.2.4.2 Nokia/Ericsson OTA Parser (WAPP)
+The WAPP parser decodes Nokia/Ericsson OTA messages and updates CommDB to reflect the received settings.
+3.2.11.2.4.3 Nokia Smart Message Internet Access Parser (IACP)
+The IACP parser decodes Nokia Smart Messages and updates the CommDB and messaging settings where appropriate.
+3.2.11.2.5 BIF Files and Utilities
+The BIF files encapsulate the information required for identifying BIO messages, these details may include the expected port number, MIME type or leading string. Different BIO watcher will use different information from these files, for an example see the 3.2.6.3.1. The information can be retrieved from the BIF files by using the BIF utilities. Generally BIO aware clients will access this information via the BIO database. BIF files are resource files previous to the v6.1 release they were binary files generated by biftool.exe.
+3.2.11.2.6 Platform Security Compliant Messaging / BIO APIs
+In the platform security model the BIO parsers are run in the client space rather than in the message server space, as is done in the non-platform secure model. If the BIO parsers are run in the message server space, it allows a client process to gain the capabilities of the message server. IPC policing can protect the message server from this.
+Also, for the message server to be able to load any BIO parser it would need more capabilities than it really requires. By running the BIO parsers in the client space, both these issues are solved. The client process must be trusted with the necessary capabilities to run the specified BIO parser.
+The BIO registry files are located in the \resource\messaging\bif read-only directory. All BIO parser DLLs are located in the \sys\bin protected directory.
+
+Figure 26 BIO Message Dependencies (v9.0)
+The BIO client MTM is responsible for loading the BIO database and BIO utilities to handle parse/process requests from clients.
+The BIO registry files no longer identify the BIO parsers DLLs via their UID – the registry file must use the BIO parser DLL name to identify them.
+3.2.12 Messaging / OBEX MTM APIs
+3.2.12.1 Key Internal Relationships and Dependencies
+
+Figure 28 OBEX Internal Dependencies
+3.2.12.2 OBEX MTM Overview
+The OBEX MTM offers simple IR and Bluetooth beaming functionality. It provides an API that is consistent with other MTMs so that the underlying OBEX APIs do not need to be used directly for beaming applications. The OBEX MTM does not provide OBEX receiving functionality, in order to receive OBEX data the underlying OBEX APIs must be used directly.
+3.2.12.2.1 OBEX MTM
+The OBEX MTM is split into three parts. OBEX MTM DLLs, IR MTM DLLs and Bluetooth MTM DLLs. The OBEX MTM DLLs can not be used on their own they provide the base OBEX MTM functionality for the derived IR and Bluetooth MTMs.
+There are two APIs that can be used to create OBEX messages:
+1) The Send-As API
+2) Linked attachments by filename
+The Send-As API provides an interface consistent with other MTMs, however it requires all attachments to be copied into the message store before they can be sent, this is often undesirable for beaming applications because it is wastes disk space. For this reason a second API is provided that allows attachments to be linked to outgoing messages by filename, when this API is used there is no need to copy the attachments to the message store.
+Unlike many other MTMs after OBEX tries to send a message it is deleted from the outbox whether the sending succeeds or fails.
+3.2.12.2.1.1 OBEX MTM Key External Dependencies
+
+Figure 29 OBEX External Dependencies
+3.2.12.2.2 IR MTM
+The bulk of the OBEX MTM functionality is provided by the OBEX MTM DLLs, the IR MTM itself just sets up the parameters.
+3.2.12.2.2.1 IR MTM Key External Dependencies
+
+Figure 30 IR MTM Dependencies
+3.2.12.2.3 Bluetooth MTM
+The bulk of the OBEX MTM functionality is provided by the OBEX MTM DLLs, the Bluetooth MTM just subclasses from the OBEX MTM and sets up Bluetooth specific parameters.
+3.2.12.2.3.1 Bluetooth MTM Key External Dependencies
+
+Figure 31 Bluetooth MTM Dependencies
+3.2.12.2.4 OBEX MTM Utils
+The OBEX MTM Utils provide utility functionality used by the other OBEX MTM DLLs. The two main areas of functionality provided by this component are:
+1) Filename linking functionality
+2) Bluetooth SDP lookup
+The filename linking functionality is provided in the utilities because linked files must be added by the client side during message creation and need to be read on the server side during sending.
+
+3.2.12.2.5 Platform Security Compliant Messaging / OBEX MTM APIs
+From v9.0 and onwards the service settings of all the derived OBEX MTMs are stored in the Central Repository. The OBEX message is stored in the message store as an attachment – from v9.0 and onwards the Attachment API is used to attach the OBEX message.
+
+3.2.13 Messaging / GMXML APIs
+3.2.13.1 Key Relationships and Dependencies
+
+Figure 32 GMXML Dependencies
+3.2.13.2 Overview
+The GMXML component provides simple XML DOM parsing and validation functionality. It is intended for parsing XML that might be needed in messaging applications, specifically SMIL parsing for MMS rendering. It is not a general purpose XML parser and will not be suitable for some applications, e.g. browsing.
+3.2.13.2.1 GMXML DOM
+The DOM implementation is fit for purpose for SMIL rendering but differs from the standard DOM design in several respects, e.g. attributes are not stored as discrete nodes, for performance reasons they are stored with the element.
+The DOM tree classes are all derived from nodes. Implemented node types include elements, text and comments. The type of each element is stored as a descriptor as opposed to an enum. This is less efficient than storing it as an enum but provides maximum flexibility when dealing with unknown element types.
+Nodes are linked together in a tree structure as might be expected in a DOM implementation. The tree structure exists on the heap.
+3.2.13.2.2 GMXML Parser and Composer
+3.2.13.2.2.1 Parser
+The parser takes XML input from a buffer or file and creates the corresponding DOM structure on the heap.
+The parser is capable of performing some basic validation. In order to validate against a DTD a class that implements the GMXML DTD interface is required. The DTD interface specifies several functions that provide the required validation, e.g. one of the functions determines if a given attribute is valid for a given element. An instance of the DTD class should be passed into the parser when validation is required but can be omitted if no validation is needed.
+3.2.13.2.2.2 Composer
+The composer takes a DOM tree and generates XML output from it. The XML output is written to a file.
+3.2.13.2.3 GMXML SMIL DTD (Validator)
+The SMIL DTD validator class is an implementation of the DTD validator interface. It implements several simple functions that provide the information required to validate SMIL data. An instance of the SMIL DTD validator should be passed into the parser if SMIL validation is required.
+4 Security
+4.1 Data caging
+For data storage in the pre-platform security compliant architecture, refer to section [3.2.1.3.2]
+For the data caging in the platform security compliant architecture of v9.0 and onwards, refer to section [3.2.1.3.3]
+4.2 Backup and restore
+The message server registers the index file with the backup server. When informed about a backup/restore it releases the index file, sending events to messaging clients informing them that the message store is unavailable. When informed it can open the index file again, it checks the time stamp on the index file; if it has changed since the file was released it reloads the index file. If the newly restored index file is found to be corrupt it is deleted and a new message store is created. See the section on page 14 for details on how the message server handles corrupt stores. The client performing the restore should always wipe the existing message store before starting to copy the message store from the backup to the device.
+4.3 Capability ranges
+In the platform security compliant architecture of v9.0 and onwards, the capabilities allocated to messaging sub-systems are as listed in following table.
+4.3.1 Capabilities granted to executables
+The following table lists the executables and their capabilities and also gives a basic example for having the required capability.
+
+Executable Capability Rationale (basic example of capability requirement)
+msexe.exe ProtServ ProtServ is required to allow the msexe.exe to start a protected server. This stops processes without ProtServ from starting a server pretending to be the message server
+ ReadDeviceData ReadDeviceData is needed to able to read service settings
+ WriteDeviceData WriteDeviceData is needed to able to write service settings
+ NetworkServices NetworkServices capability is needed to access network transports (SMS, POP3, SMTP, IMAP4).
+ LocalServices LocalServices is needed to be able to access IR and Bluetooth
+ ReadUserData ReadUserData is needed to be able to read user data (e.g. service settings).
+watcher.exe ReadDeviceData ReadDeviceData is needed to able to read service settings
+ WriteDeviceData WriteDeviceData is needed to able to write service settings
+ NetworkServices NetworkServices capability is needed to access network transports (SMS).
+ LocalServices LocalServices capability is needed for the plug-ins to access IR and Bluetooth
+ ReadUserData ReadUserData is needed to be able to read user data
+ WriteUserData WriteUserData is needed to be able to write user data
+autosend.exe ReadUserData ReadUserData capability is needed to be able to read data from Outbox and SMTP server MTM.
+ WriteUserData WriteUserData capability is needed to be able to write data in Outbox and SMTP server MTM.
+ NetworkServices NetworkServices capability is needed to access network transports (SMS, POP3, SMTP, and IMAP4).
+ LocalServices LocalServices capability is needed to access the IR and Bluetooth
+SchSend.exe ReadDeviceData ReadDeviceData is needed to able to read settings data
+ NetworkServices NetworkServices capability is needed to access the network transports (SMS, POP3, SMTP, and IMAP4).
+ LocalServices LocalServices is needed to be trusted by other MTM
+ ReadUserData ReadUserData is needed to be able to read user data.
+ WriteUserData WriteUserData is needed to be able to write user data.
+SendAs.exe ReadDeviceData ReadUserData is needed to be able to read data in Outbox.
+ WriteDeviceData WriteUserData is needed to be able to write data in Outbox.
+ NetworkServices NetworkServices capability is needed to access the network transports (SMS, POP3, SMTP, and IMAP4).
+ LocalServices LocalServices is needed to be able to access IR and Bluetooth
+
+4.3.2 Capabilities granted to DLLs
+The assigned Platform Security attributes for DLLs within messaging are outlined in the following table.
+DLL Capability
+bifu.dll All –TCB
+bioc.dll All –TCB
+biodb.dll All –TCB
+bios.dll All –TCB
+biowatcher.dll same as watcher.exe
+biut.dll All –TCB
+cbcp.dll All –TCB
+enp.dll All –TCB
+gfp.dll All –TCB
+iacp.dll All –TCB
+nbswatcher.dll same as watcher.exe
+cdmanbswatcher.dll same as watcher.exe
+CdmaSocketWatcher.dll same as watcher.exe
+VMNWatcher.dll same as watcher.exe
+WEMTWatcher.dll same as watcher.exe
+WMTWatcher.dll same as watcher.exe
+WPTWatcher.dll same as watcher.exe
+wapp.dll All –TCB
+wapwatcher.dll same as watcher.exe
+smildtd.dll All –TCB
+xmldom.dll All –TCB
+xmlparser.dll All –TCB
+smiltranslator.dll All –TCB
+imcm.dll All –TCB
+imps.dll same as msexe.exe
+imut.dll All –TCB
+msgs.dll All –TCB
+msgurlrec.mdl same as AppArc.exe (once it exists; eiksrv in meantime)
+mtur.dll All –TCB
+pops.dll same as msexe.exe
+schsend.dll All –TCB
+send.dll All –TCB
+smcm.dll All –TCB
+smcm_gsm.dll Synonym for smcm.dll
+smcm_cdma.dll Synonym for smcm.dll
+smss.dll same as msexe.exe
+smss_gsm.dll Synonym for smss.dll
+smss_cdma.dll Synonym for smss.dll
+smts.dll same as msexe.exe
+btcmtm.dll All –TCB
+btsmtm.dll same as msexe.exe
+irc.dll All –TCB
+irs.dll same as msexe.exe
+obexclientmtm.dll All –TCB
+obexmtmutil.dll All –TCB
+obexservermtm.dll same as msexe.exe
+
+The reason for setting a high capability to the DLLs is to make it possible for almost anyone to link to them. Although a DLL may have capabilities ALL-TCB (All minus TCB), its real capability is limited by the process which loads the DLL.
+4.3.3 Capabilities required to use the subsystem
+The message subsystem needs to be protected against malicious clients. The following table shows the key capabilities required to do related activities in different components.
+
+Component Related Activity Required Capability and SID
+Message server Create message in local folder No capability required
+ Create message in Outbox ReadUserData, WriteUserData and MTM specific capabilities
+ Access client MTM ReadUserData, WriteUserData and MTM specific capabilities
+Watcher Allow plug-ins to wait on events (e.g. arrival of SMS) Watcher always polices if the client capabilities are trusted by the watcher framework, else it will not be loaded
+Plug-ins or clients using watcher need the same capabilities as watcher.exe to be able to be loaded by watcher.
+Autosend Send messages in background NetworkService or LocalService required by the message type
+SchSend Scheduling of operations (e.g. sending SMS) SchSend always polices to see if the process was started by the Task Scheduler – if not the process terminates without performing any of the scheduled tasks. Also, the SchSend verifies that only itself and the message server created the scheduled tasks. If this is not the case, SchSend does not performing the scheduled tasks.
+SendAs Create message Draft, move it to Outbox, and send message WriteDeviceData or WriteUserData and other capability required by the message type
+
+5 Further Information
+5.1 References
+No. Document Reference Version Description
+R1 messaging_functional_specification.doc 0.6 Messaging Functional description
+R2 SGL.GT0143.161_App-Framework_Architectural_Description.doc 1.0 App-Framework Architectural Description
+R3 NBProtocols_Subsystem_Architectural_Description.doc 0.2 NBProtocols Architectural Description
+R4 WAP-stack_architectural_analysis.doc 1.0 WAP stack architectural analysis
+R5 HTTP Transport Framework Architectural Description.doc 1.1 HTTP Transport Framework 1.1 Architectural Description
+5.2 Open Issues
+The following issues need to be resolved before this document is completed:
+1. Top-level architecture diagram showing the framework and plug-ins should be added to overview section.
+2. Message store section should talk about removable media.
+3. Define "Message Server Client API" and "Messaging Client API" in the glossary, and ensure it is consistently used in the diagrams
+4. Add a sequence diagram for receiving a vCard over SMS and integrating it into contacts
+5. Add a sequence diagram for sending an SMS
+6. Add a sequence diagram for synchronising a POP3 mail box
+7. Add a sequence diagram for connecting to an IMAP4 mail box and downloading a message
+8. Capability table should be updated after the implementation of server e.g. message server
+9. Sequence diagram may need to be changed to show secured platform operation
+10. In section [3.1.1.4] the server SendAsV2 to find a correct name
+11. Section 3.2.1.3.3.1 Data Caging file 'Mtm Registry v2'may need a correct name
+12. Breakdown diagram showing all DLL, exes, apps in the messaging subsystem for both the pre-v8.0 and post v9.0 in section[3.2]
+13. Needs to say more about how the capabilities are policed and the algorithms used for different operations
+14. The dependecy between the message server and the central repository need to be listed in the email, SMS and OBEX diagrams (e.g. message store)
+15. Section 3.2.1.2 - figure 3 - Central Repository also get used by the Message server, or server MTMs (e.g. POP3), to retrieve account settings the path, required DLL and description are not given
+16. Section 4.3.3 title can be Police requirement of the sub-system, add extra column for SID in the table and list the use of SID. For example SchSend checks for Task Scheduler SID
+
+
+5.3 Glossary
+The following technical terms and abbreviations are used within this document.
+Term Definition
+BIO
+Bearer Independent Object Smart messages e.g. vCards, vCals, and WAP provisioning messages. These can currently be received via the WAP stack, SMS stack, Bluetooth or Infrared.
+BIO Type UID that represents the content type of a BIO Message.
+Message Centre Application that displays list views of messages to the user, allowing the user to perform operations such as copying messages, sending messages creating new messages etc.
+Message Viewer Application for viewing a message.
+Message Editor Application for creating or editing a message
+Message Server Symbian OS Server that handles request to modify the Message Store
+Message Store Store of messages and related information kept in the file system on a Symbian OS device.
+Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
+Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
+Global Inbox A standard folder under the local service which is used to store incoming messages like SMS MMS etc. as opposed to an IMAP4 Inbox which would be under an IMAP4 service and is a representation of the Inbox on an IMAP4 email server.
+Central Repository centralised and secure storage facility for application settings
+OBEX Object exchange protocol, used to send objects such as vCards or files between devices via infrared or Bluetooth.
+GMXML XML parser / generator for use with SMIL formatted messages.
+UID Unique Identifier, a 32 bit number allocated from a registry owned by Symbian
+IPC Inter Process Communication
+MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
MTM Registry A list of currently installed MTMs maintained by the message server.
TLS Transport Layer Security, provides encryption of a TCP/IP socket.
M-HTML Standard for including HTML in MIME email messages see http://www.ietf.org/rfc/rfc2557.txt
@@ -38621,15 +34549,1033 @@
Message Editor Application for creating or editing a message
Message Server Symbian OS Server that handles request to modify the Message Store
Message Store Store of messages and related information kept in the file system on a Symbian OS device.
-Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
-Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
+Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
+Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
Global Inbox A standard folder under the local service which is used to store incoming messages like SMS MMS etc. as opposed to an IMAP4 Inbox which would be under an IMAP4 service and is a representation of the Inbox on an IMAP4 email server.
Central Repository centralised and secure storage facility for application settings
OBEX Object exchange protocol, used to send objects such as vCards or files between devices via infrared or Bluetooth.
GMXML XML parser / generator for use with SMIL formatted messages.
UID Unique Identifier, a 32 bit number allocated from a registry owned by Symbian
IPC Inter Process Communication
-MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
+MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
+MTM Registry A list of currently installed MTMs maintained by the message server.
+TLS Transport Layer Security, provides encryption of a TCP/IP socket.
+M-HTML Standard for including HTML in MIME email messages see http://www.ietf.org/rfc/rfc2557.txt
+MIME Specification for the format of email message bodies see http://www.ietf.org/rfc/rfc1341.txt
+RFC2822 The standard format for internet mail messages see http://www.ietf.org/rfc/rfc0822.txt
+SMTP Simple Mail Transport Protocol
+SID Secure Identification
+IMAP4 Internet Mail Access Protocol
+POP3 Post Office Protocol Version 3
+NBS Narrow Band Socket, in the messaging context this refers to the socket that is used to talk to the SMS stack for receiving and sending SMS messages
+SMS Short Message Service
+MMS Multimedia Message Service
+WAP Wireless Application Protocol
+WSP WAP Session Protocol
+HTTP Hypertext transfer protocol
+PDU Protocol Data Unit. This is the encoded form of SMS and MMS messages.
+Versit A consortium that defined standard formats for things like contacts (vCard) and calendar entries (vCals)
+SDP Service Discovery Protocol. A Bluetooth protocol that allows an applications to discover which services are available and to determine the characteristics of the services.
+SMIL Synchronized Multimedia Integration Language. Presentation language that is commonly used to define the contents of an MMS message.
+XML Extensible Mark-up Language
+DOM Document Object Model
+DTD Document Type Definition, a schema that defines the structure of an XML document.
+ESTORE Symbian OS component that provides stream based storage. Messaging uses the Permanent file store provided by ESTORE to store its index entries.
+Appendix A - Example Sequence Diagrams
+A.1 Copy to a Remote Service
+
+Figure 33 Sequence Diagram Showing Copying to a Remote Service
+Figure 33 shows a client copying a message to a remote service using the Messaging Client API. The message server then delegates the copy to the SMTP Server MTM. The Server MTM interprets the request as a request to send the message so it opens a connection to a remote SMTP server and sends the message. While the message is being sent the client can retrieve progress information from the CMsvOperation object that was returned by CMsvEntry::CopyL. The dark grey IPC line represents the split between the objects running in the client’s process space on the left and the message server’s process on the right.
+There are four basic steps:
+1. The client opens session with Message Server and creates a CMsvEntry set on the global outbox,
+2. The client then requests an asynchronous copy from the outbox to the SMTP service, a CMsvOperation object is returned. The message server loads the SMTP Server MTM and delegates the copy operation to it.
+3. The client requests progress from the CMsvOperation object, this request is passed through to the SMTP Server MTM. The client may repeat this step multiple times.
+4. The Server MTM finishes sending message. It moves the message to sent folder and completes the message server’s request. The message server completes the CMsvOperation object, which requests the final progress from the message server. The server returns the final progress and deletes the Server MTM. The CMsvOperation then completes the client’s original request.
+This diagram hides all of the internal working of the SMTP Server MTM, for information on this see below.
+A.2 SMTP Session
+
+Figure 34 Sequence Diagram Showing a SMTP Session
+Figure 34 shows the operation of the SMTP Server MTM after a request has come from the message server to copy a message to the SMTP service.
+1. SMTP Server MTM gets the request from the message server, it will build a selection of messages consisting of the union of the selection of messages passed in and the messages in the outbox that are associated with this SMTP service and are ready to be sent. The chain of classes are constructed, and a request is passed to networking to connect to the remote SMTP server, details of the server name and port are retrieved from the settings stored in the SMTP service entry.
+2. The component waits for the SMTP server to respond with a greeting indicating it is willing to talk, then sends EHLO to the server and waits for the response detailing the capabilities of the Server. After this step there could set steps to start using TLS and or SMTP AUTH depending on the SMTP settings.
+3. CImSmtpSession calls back into CMsgOutboxSend to retrieve the next message to be sent, then constructs a CImSmtpFile object to handle sending, for details on the sending see SMTP Email Send. When sending the email has completed the CImSmtpFile object is deleted.
+4. CImSmtpSession calls back into CMsgOutboxSend to retrieve the next message which returns saying there are no more messages. CImSmtpSession sends QUIT to the SMTP server and completes CMsgOutboxSend. CMsgOutboxSend deletes CImSmtpSession which tears down the connection to the SMTP server; it then completes the SMTP Server MTM. The Server MTM will then complete the message server and be deleted.
+A.3 SMTP Email Send
+
+Figure 35 Sequence Diagram Showing SMTP Transactions during Email Send.
+Figure 35 shows a CImSmtpFile object sending an email message to an SMTP server.
+1. Construct a CImSendMessage object, part of the imut component. Reset the SMTP Server
+2. Read address information from the CImHeader object stored in the message store, send address information to SMTP server.
+3. Use CImSendMessage object to read the message from the message store and generate RFC2822 message line by line. Send each line to the server as it is generated.
+4. Complete and send the message by sending a full stop to the SMTP server
+
+
+
+
+Messaging Symbian OS v7.0s, v8.0, v8.1, v9.0, v9.1 Architectural Description
+
+Status: Issued
+Team/Department : Messaging / Content & Messaging
+
+Contents
+1 INTRODUCTION 6
+1.1 PURPOSE AND SCOPE 6
+2 SUBSYSTEM OVERVIEW AND BACKGROUND 6
+3 MESSAGING ARCHITECTURE AND APIS 7
+3.1 SUBSYSTEM COMPONENTS 7
+3.1.1 Framework components 7
+3.1.1.1 Message Server and MTM architecture 7
+3.1.1.2 Schedule Send 7
+3.1.1.3 SendAs Version 1 7
+3.1.1.4 SendAs Version 2 7
+3.1.1.5 Watcher Framework 8
+3.1.1.6 Message URL Handler 8
+3.1.1.7 Bio Message Framework 8
+3.1.2 Plug-ins 8
+3.1.2.1 SMS 8
+3.1.2.2 CDMA SMS 8
+3.1.2.3 Email 9
+3.1.2.4 OBEX 9
+3.1.2.5 MMS 9
+3.1.2.6 GMXML 10
+3.1.2.7 Bio Message Plug-ins 10
+3.1.2.8 PCMTM 10
+3.1.2.9 Fax 10
+3.2 GENERAL DESCRIPTION 11
+3.2.1 Messaging / Message Server and MTM Architecture APIs 11
+3.2.1.1 Key Internal Relationships and Dependencies 11
+3.2.1.2 Key External Relationships and Dependencies 12
+3.2.1.3 API Purpose - Further Elaboration 13
+3.2.1.3.1 Message Store 13
+3.2.1.3.2 Data File Storage (pre - v9.0) 15
+3.2.1.3.3 Platform Security Compliant Message Store 16
+3.2.1.3.4 How message centres display the message store 17
+3.2.1.3.5 Message Type Module Architecture 19
+3.2.1.3.6 Message Server Client API 21
+3.2.2 Messaging / Send As APIs 22
+3.2.2.1 Key Relationships and Dependencies 22
+3.2.2.2 API Purpose - Further Elaboration 22
+3.2.2.2.1 SendAs API (pre – v9.0) 22
+3.2.3 Platform Security Compliant SendAs Server (v9.0 onwards) 23
+3.2.4 Messaging / Schedule Send APIs 24
+3.2.4.1 Key Relationships and Dependencies 24
+3.2.4.2 API Purpose - Further Elaboration 24
+3.2.4.2.1 Schedule Send 24
+3.2.5 Messaging / Watchers APIs 25
+3.2.5.1 Key Relationships and Dependencies 25
+3.2.5.2 API Purpose - Further Elaboration 25
+3.2.6 Messaging / Message URL Handler APIs 26
+3.2.6.1 Key Relationships and Dependencies 26
+3.2.6.2 API Purpose - Further Elaboration 26
+3.2.6.2.1 Message URL Handler Application 26
+3.2.6.2.2 Message URL Recognisers 27
+3.2.7 Messaging / SMS APIs 27
+3.2.7.1 Key Internal Relationships and Dependencies 27
+3.2.7.2 Key External Relationships and Dependencies 28
+3.2.7.3 API Purpose - Further Elaboration 28
+3.2.7.3.1 SMS Watchers 28
+3.2.7.3.2 SMS Client MTM 29
+3.2.7.3.3 SMS Utilities 29
+3.2.7.3.4 SMS Server MTM 30
+3.2.8 Messaging / CDMA SMS APIs 31
+3.2.8.1 Key Internal Relationships and Dependencies 31
+3.2.8.2 Key External Relationships and Dependencies 32
+3.2.8.3 API Purpose - Further Elaboration 32
+3.2.8.3.1 CDMA SMS Watchers 32
+3.2.8.3.2 CDMA SMS Client MTM 33
+3.2.8.3.3 CDMA SMS Utilities 33
+3.2.8.3.4 CDMA SMS Server MTM 33
+3.2.8.3.5 Configuration for using CDMA SMS MTM 34
+3.2.9 Messaging / Email APIs 35
+3.2.9.1 Key Internal Relationships and Dependencies 35
+3.2.9.2 Key External Relationships and Dependencies 36
+3.2.9.3 API Purpose - Further Elaboration 36
+3.2.9.3.1 Email Overview 36
+3.2.9.3.2 Email Client Utilities 37
+3.2.9.3.3 Email Server MTM Utilities 37
+3.2.9.3.4 POP3 MTMs 37
+3.2.9.3.5 IMAP4 MTMs 38
+3.2.9.3.6 SMTP MTMs 40
+3.2.9.3.7 Autosend 40
+3.2.10 Messaging / MMS APIs 40
+3.2.10.1 Key Internal Relationships and Dependencies 41
+3.2.10.2 API Purpose - Further Elaboration 41
+3.2.10.2.1 MMS Overview 41
+3.2.10.2.2 MMS Utilities 42
+3.2.10.2.3 MMS Watcher 43
+3.2.10.2.4 MMS Client MTM 43
+3.2.10.2.5 MMS Server MTM 44
+3.2.10.2.6 MMS Codec 45
+3.2.11 Messaging / BIO APIs 46
+3.2.11.1 Key Internal Relationships and Dependencies 46
+3.2.11.2 API Purpose - Further Elaboration 47
+3.2.11.2.1 BIO Overview 47
+3.2.11.2.2 BIO MTM 47
+3.2.11.2.3 BIO Database 48
+3.2.11.2.4 BIO Parsers 48
+3.2.11.2.5 BIF Files and Utilities 48
+3.2.11.2.6 Platform Security Compliant Messaging / BIO APIs 49
+3.2.12 Messaging / OBEX MTM APIs 50
+3.2.12.1 Key Internal Relationships and Dependencies 50
+3.2.12.2 OBEX MTM Overview 50
+3.2.12.2.1 OBEX MTM 50
+3.2.12.2.2 IR MTM 51
+3.2.12.2.3 Bluetooth MTM 51
+3.2.12.2.4 OBEX MTM Utils 52
+3.2.12.2.5 Platform Security Compliant Messaging / OBEX MTM APIs 52
+3.2.13 Messaging / GMXML APIs 52
+3.2.13.1 Key Relationships and Dependencies 52
+3.2.13.2 Overview 53
+3.2.13.2.1 GMXML DOM 53
+3.2.13.2.2 GMXML Parser and Composer 53
+3.2.13.2.3 GMXML SMIL DTD (Validator) 53
+4 SECURITY 54
+4.1 DATA CAGING 54
+4.2 BACKUP AND RESTORE 54
+4.3 CAPABILITY RANGES 54
+4.3.1 Capabilities granted to executables 54
+4.3.2 Capabilities granted to DLLs 55
+4.3.3 Capabilities required to use the subsystem 57
+5 FURTHER INFORMATION 59
+5.1 REFERENCES 59
+5.2 OPEN ISSUES 59
+5.3 GLOSSARY 60
+APPENDIX A - EXAMPLE SEQUENCE DIAGRAMS 62
+A.1 COPY TO A REMOTE SERVICE 62
+A.2 SMTP SESSION 64
+A.3 SMTP EMAIL SEND 66
+
+Table of Figures
+Figure 1 Where Messaging Lives 6
+Figure 2 MTM Relationships 11
+Figure 3 External Dependencies 12
+Figure 4 Message Store 13
+Figure 5 Series 60 Inbox List View 14
+Figure 6 Remote and Local Entries 14
+Figure 7 Email Message 15
+Figure 8 Series 60 Message Centre (Composed from 2 screen shots) 17
+Figure 9 UIQ Message Centre 18
+Figure 10 Messaging MTM Structure (light coloured components are part of messaging subsystem) 19
+Figure 11 Nokia 9210 Outbox List View 20
+Figure 12 SendAs Version 1 Dependencies 22
+Figure 13 SendAs Version 2 Dependencies 23
+Figure 14 Schedule Send Dependencies 24
+Figure 15 Watcher Dependencies 25
+Figure 16 Message URL Handler Dependencies 26
+Figure 17 SMS Internal Dependencies 27
+Figure 18 SMS External Dependencies 28
+Figure 19 CMDA SMS Internal Dependencies 31
+Figure 20 CDMA SMS External Dependencies 32
+Figure 19 Email Internal Dependencies 35
+Figure 20 Email External Dependencies 36
+Figure 21 MMS Internal Dependencies 41
+Figure 22 MMS Utilities External Dependencies 42
+Figure 23 MMS Watcher External Dependencies 43
+Figure 24 MMS Client MTM Dependencies 43
+Figure 25 MMS Server MTM Dependencies 44
+Figure 26 BIO Message Internal Dependencies 46
+Figure 27 Bio Parser External Dependencies 47
+Figure 26 BIO Message Dependencies (v9.0) 49
+Figure 28 OBEX Internal Dependencies 50
+Figure 29 OBEX External Dependencies 51
+Figure 30 IR MTM Dependencies 51
+Figure 31 Bluetooth MTM Dependencies 52
+Figure 32 GMXML Dependencies 52
+Figure 33 Sequence Diagram Showing Copying to a Remote Service 62
+Figure 34 Sequence Diagram Showing a SMTP Session 64
+Figure 35 Sequence Diagram Showing SMTP Transactions during Email Send. 66
+1 Introduction
+1.1 Purpose and Scope
+The Messaging Architectural Description details the architecture and APIs exposed by the Messaging Subsystem. This document does not attempt to list all functionality provided by the messaging subsystem. For details on the functionality provided and the specifications implemented by the messaging subsystem see the Messaging Functional Description [R1]. This document describes the general architecture of messaging subsystem. Information related to a particular release version is mentioned with relevant release number.
+2 Subsystem Overview and Background
+The Messaging Subsystem provides an application level API to handle the storage and transport of different message types. It sits between messaging applications and the lower level subsystems which messaging uses for storage and transmission of messages.
+
+Figure 1 Where Messaging Lives
+The message types that messaging currently supports are Email (POP3, IMAP4 & SMTP), SMS, MMS and OBEX. The set of supported message types is extensible at run time by the use of plug-in modules that are responsible for the transmission and storage of a particular message type. This means that the set of components shown communicating with the network cloud depend on the message types installed.
+3 Messaging Architecture and APIs
+3.1 Subsystem components
+The Messaging subsystem components can be split into two categories: those components that form the framework and those that plug into the framework to support specific message types. This section briefly describes each of the components, more detailed descriptions of the components and their dependencies can be found in later sections of this document.
+3.1.1 Framework components
+3.1.1.1 Message Server and MTM architecture
+The message server is the core component in the messaging subsystem. It provides the message store used to contain messages. The Message Type Module architecture also allows plug-ins to add support for new message types to the messaging subsystem.
+Component Description
+messaging\framework\serverexe Executable that links to the server component and starts the message server
+messaging\framework\server Contains classes that make up both the client and server side of the message server API.
+messaging\framework\mtmbase Base classes for the plug-ins that handle the various message types
+3.1.1.2 Schedule Send
+The Schedule Send component is an extension to the framework that provides support for scheduling of operations such as sending messages. Message type modules that wish to support this functionality can use these support components to implement scheduling. For example the SMS MTM uses this to allow scheduled sending of SMS messages.
+Component Description
+messaging\schedulesend\schedulesendmtm Base classes that handle functionality for message server plug-ins that wish to enable scheduling of sending messages.
+messaging\schedulesend\schedulesendexe Executable use to provide schedule send behaviour.
+3.1.1.3 SendAs Version 1
+This version of SendAs is supported in releases pre - v9.0. SendAs provides a high level API for applications that wish to include a “Send As” menu to allow users to send content via one of the message types supported by messaging. The application using the API does not have to be aware of the message type selected by the user. Note the API does not send the messages.
+Component Description
+messaging\sendas High level API to allow creation of messages.
+3.1.1.4 SendAs Version 2
+From v9.0 and onwards the SendAs has been replaced with client server architecture based SendAs server. The client server architecture enhances secured platform implementation. The SendAs server polices the client application. If it is not trusted with required capabilities the SendAs server will refuse the client access. The client MTM for the message type can send a message with user permission even if the client does not have the correct capabilities.
+Component Description
+messaging\sendAsV2 High level API to allow the creation and sending of messages
+
+3.1.1.5 Watcher Framework
+The watcher framework is a lightweight framework to allow plug-ins to wait on events. For example there is an SMS watcher that waits for incoming SMS messages and delivers them to the message store. The watcher framework will only load plug-ins from ROM.
+Component Description
+messaging\framework\watcher Executable that loads and runs watcher plug-ins.
+3.1.1.6 Message URL Handler
+Support for recognising messaging URLs (mailto:, sms:, fax:, mms:), and then launching an editor with a new message.
+Component Description
+messaging\urlhandler\urlhandler An application that parses the URLs and then creates a correctly addressed message and launches a message editor.
+messaging\urlhandler\recogniser Recognisers that map from the URL schemes to the mime types.
+3.1.1.7 Bio Message Framework
+The Bio Message Framework provides a framework that supports plug-ins to handle messages like vCards and Internet access point set-up messages.
+Component Description
+messaging\biomsg\BDB\BIODB Classes to maintain the database of bio registration files.
+messaging\biomsg\BIFU\BIFU Classes for reading and writing bio registration files
+messaging\biomsg\BIOC\BIOC Bio message client MTM, this is in the framework section as it forms part of the bio messaging framework it is also a plug-in to the messaging framework.
+messaging\biomsg\BIOS\BIOS Bio message server MTM, this is in the framework section as it forms part of the bio messaging framework it is also a plug-in to the messaging framework.
+3.1.2 Plug-ins
+3.1.2.1 SMS
+The SMS plug-ins provide application level support for the Short Message Service messages.
+Component Description
+messaging\biomsg\BioWatchers Plug-ins to the watcher framework to listen for SMS, WSP, and WDP messages and deliver them to the global inbox in the message store.
+messaging\sms\clientmtm A plug-in to the message server framework to provide a generic API for creation of SMS messages (SMS Client MTM & SMS utilities)
+messaging\sms\servermtm A plug-in to the message server framework to provide a generic API for sending of SMS messages (SMS Server MTM)
+3.1.2.2 CDMA SMS
+The CDMA SMS plug-ins provide application level support for the CDMA Short Message Service messages.
+Component Description
+messaging\biomsg\BioWatchersCdma Plug-ins to the watcher framework to listen for CDMA SMS messages and deliver them to the global inbox in the message store.
+messaging\sms\multimode\clientmtm A plug-in to the message server framework to provide a generic API for creation of CDMA SMS messages (CDMA SMS Client MTM)
+messaging\sms\multimode\servermtm A plug-in to the message server framework to provide a generic API for sending of CDMA SMS messages (CDMA SMS Server MTM)
+
+3.1.2.3 Email
+The email plug-ins provide support the POP3, IMAP4 and SMTP email protocols and support for parsing and generating plain test, MIME and M-HTML format email messages.
+Component Description
+messaging\email\clientmtms A plug-in to the message server framework to provide a generic API for creation of email messages (IMAP4 SMTP and POP3 Client MTMs & email utilities)
+messaging\email\imapservermtm A plug-in to the message server framework to provide a generic API for access to a remote IMAP4 server (IMAP4 Server MTM)
+messaging\email\smtpservermtm A plug-in to the message server framework to provide a generic API for access to a remote SMTP server (SMTP Server MTM)
+messaging\email\popservermtm A plug-in to the message server framework to provide generic API for access to remote POP3 server (POP3 Server MTM)
+messaging\email\servermtmutils Email utilities for parsing plain text and MIME email messages. It also provides an abstraction of the TCP/IP sockets for use by the SMTP POP3 and IMAP4 plug-ins.
+messaging\email\autosend An executable that requests SMTP Server MTM to send messages in the outbox. This is used to provide send on next connection functionality and is started by the POP3 and IMAP4 Client MTMs.
+3.1.2.4 OBEX
+The OBEX MTM is a set of plug-ins to the message server that provides support for IR and Bluetooth beaming.
+Component Description
+messaging\obex\btmtm\btclient\group\btcmtm Bluetooth Client MTM
+messaging\obex\btmtm\btserver\group\btsmtm Bluetooth Server MTM
+messaging\obex\irmtm\irclient\group\ircmtm IR Client MTM
+messaging\obex\irmtm\irserver\group\IRSMTM IR Server MTM
+messaging\obex\obexmtm\obexclient\group\obexClientMtm OBEX Client MTM, base classes for the Bluetooth and IR Client MTMs
+messaging\obex\obexmtm\obexserver\group\obexServerMtm OBEX Server MTM, base classes for the Bluetooth and IR Server MTMs
+messaging\obex\obexmtm\obexutil\group\obexMtmUtil OBEX MTM utilities
+3.1.2.5 MMS
+The MMS MTM is a plug-in to the message server that provides support for MMS messages. From v9.0 and onwards MMS MTM and related components are removed.
+Component Description
+messaging\mms\utils MMS Utilities
+messaging\mms\servermtm MMS Server MTM
+messaging\mms\mmswatcherplugins MMS plug-ins to WAP push framework to handle reception of MMS notifications
+messaging\mms\codec MMS utilities for handling MMS codecs
+messaging\mms\clientmtm MMS Client MTM
+3.1.2.6 GMXML
+GMXML is a parser/generator for SMIL presentations for MMS messages.
+Component Description
+messaging\GMXML\XMLParser XML parser designed for parsing of SMIL messages
+messaging\GMXML\XMLDom XML document object model designed for parsing of SMIL messages
+messaging\GMXML\SMILdtd SMIL DTD
+3.1.2.7 Bio Message Plug-ins
+These parsers plug into the bio messaging framework to handle specific types of bio message.
+Component Description
+messaging\biomsg\cbcp\CBCP Compact business card parser
+messaging\biomsg\enp\ENP Email notification parser
+messaging\biomsg\gfp\gfp General file parser
+messaging\biomsg\iacp\IACP Nokia Smart Message Internet Access Parser
+messaging\biomsg\wapp\wapp Nokia/Ericsson OTA Parser
+3.1.2.8 PCMTM
+Plug-in to the message server that provided email synchronisation with a PC. This component has been deprecated in 8.0a and will not been documented in the API section below.
+3.1.2.9 Fax
+Plug-in to the message server that provides fax support. This component has been deprecated in 8.0a and will not been documented in the API section below.
+
+3.2 General Description
+3.2.1 Messaging / Message Server and MTM Architecture APIs
+3.2.1.1 Key Internal Relationships and Dependencies
+
+Figure 2 MTM Relationships
+Figure 2 shows the relationship between the Message Server and the MTM plug-ins. The grey classes are realisations of the MTM interfaces defined by the messaging framework. The message server depends on the Server MTM interface. Messaging Clients depend on the Client, UI and UI Data MTM interfaces and the Message Server Client API.
+3.2.1.2 Key External Relationships and Dependencies
+
+Figure 3 External Dependencies
+The grey package representing the messaging client depends on the Client, UI and UI Data interfaces and the Messaging Client API. The message server then depends on:
+• Charconv – Provides character set conversion routines, used to convert encoded message body text to Unicode body text.
+• EStore – Provides API to handle a stream based store used for the messaging index file and the framework classes for the message store files. (omitted from other dependency diagrams as it is implied by the dependency on the message server)
+• F32 – Provides the file server APIs used to access the file system directories in which messaging stores files containing message data. (omitted from other dependency diagrams)
+• BAFL – Provides API to load the correct messaging resource file dependent on the current language and to register the message store index file with the backup server. (omitted from other dependency diagrams)
+• ETEXT – Rich text APIs used to store body text of messages, this rich text format is a Symbian Proprietary format. (omitted from other dependency diagrams)
+• EUSER – Core Symbian OS utilities such as descriptors, arrays, client / server framework, cleanup stack and others (omitted from this and other dependency diagrams).
+• Central Repository – Centralised and secure storage facility for application settings, the message server stores message settings data in the central repository (from v9.0 and onwards).
+Note that debug only dependencies such as the flogger have been omitted from dependency diagrams.
+3.2.1.3 API Purpose - Further Elaboration
+3.2.1.3.1 Message Store
+The message server provides persistent storage of messages and messaging account settings. It does this by providing a message store consisting of a tree of message entries. Multiple clients can access the message store simultaneously. Each entry in the tree can represent an email account, folder of messages, message part, etc.
+
+Figure 4 Message Store
+Figure 4 shows an example message store. The tree is broken down in to three levels:
+1. The Root entry. This entry is just present to tie the tree structure together
+2. Service entries. There is one local service under which local folders and messages are stored, and zero or more remote services. Remote services represent message accounts.
+3. Message & Folder entries. Messages and folders, under the local service represent messages stored on the device. Messages and folders under remote services represent a local copy of messages that are present on a remote server. For example under a POP3 email service you would have copies of all the messages present on the POP3 email server, or under an SMS service you might find SMS messages that are stored on a SIM.
+The message server controls access to the entries in the store. It enforces the three levels therefore attempts to create message or folder entries directly under the root entry will fail.
+The message server provides three types of storage for each entry in the message store:
+• Index entry - TMsvEntry - intended to provide enough information for UI to display list views as shown in Figure 5. This consists of two strings and various flags (read, complete, has attachments etc).
+• Stream based file store - CMsvStore – provides storage of streams of data associated with UIDs. A standard UID is defined for storing body text. Other UIDs are specific. For example the email MTMs define a UID for storage of MIME headers. Compared to the index entry information this is used to store larger objects and is extensible, at the cost of being slower to access. From v9.0 and onwards CMsvStore provides an Attachment API for managing attachments. The Attachment API should be used as attachments can no longer be accessed directly due to Platform Security.
+• Directory of files – normally used for attachments.
+The only storage type that is always present is the index entry. The stream store and the directory of files are optional.
+
+Figure 5 Series 60 Inbox List View
+
+Figure 6 Remote and Local Entries
+As shown in Figure 6 the message store is split into two sets of entries:
+• Remote entries - entries that are representations of entries stored on a remote store .
+• Local entries - entries not linked to a remote store.
+The message server handles changes to local entries; internally it hands off changes to remote entries to the Server MTM that owns that service. Examples of operations that are handed off to Server MTMs are operations involving copying and moving messages to and from a remote service. See section 3.2.1.3.5 or more information on Server MTMs.
+Each entry within the store has a type:
+Folder – Messages can be grouped into folders. Standard folders such as inbox / outbox and user created folders.
+Message – Storage of the content of a message. Message entries can have child entries used to represent the structure of a message.
+Attachment – These represent attachments under a message entry.
+Root & Local Service Entry – There tie the tree structure together. However the Stream store associated with the root entry is sometimes used by UIs to store preferences e.g. default folder views etc.
+Remote Service - Represents a source and / or destination for messages. They are used to store the settings associated with the source / destination.
+Message Type Specific - MTMs can create other message types for use as child entries to messages they own. For example email uses a tree structure, with a message entry as the root, to represent the MIME structure of an email message; it uses folder entries to represent MIME folders and adds new types for entries representing the html body and text body parts of a message. This is shown in Figure 7.
+
+Figure 7 Email Message
+Using the message store to represent message structure allows reuse of the tree structure and makes it very simple to represent one message embedded in another. However this representation introduces performance issues as it results in each message having multiple files associated with it. The message server also keeps all index entries in memory; therefore this representation increases the memory footprint of the message server. Therefore when designing new MTMs we should think about moving away using multiple index entries to store one message in the message store.
+A default message store is created if the message server starts and no message store is present or a corrupt message store is present. The server will initially create a store with just a root entry, and then the server will create any standard folders defined in the resource file msgs.rsc. Finally the server will check whether an executable ‘mailinit.exe’ is present on the system, if it is present the server will launch the executable to allow customisation of the message store. The behaviour of ‘mailinit.exe’ is defined by the UI family of the device. However the typical behaviour is to load each of the UI Message Type Modules and allow each to perform any message type specific initialisation. For example the SMS plug-in typically creates a default service entry.
+
+3.2.1.3.2 Data File Storage (pre - v9.0)
+This section describes the files used by the message server before release v9.0. For information on the files used for release from v9.0 and onwards see section [3.2.1.3.3.1].
+Filename Access Purpose
+?:\system\Mail\index Private Message server index file, internal to message server
+?:\system\Mail\<8 hex digits> Shared via API Message server store files for services, clients access these via a messaging API.
+?:\system\Mail\<8 hex digits>.new Shared via API Temporary file used during committing message server store files.
+?:\SYSTEM\MAIL\<8 HEX DIGITS>_F\* Shared Files associated with a messaging service. These may be accessed directly by clients.
+?:\system\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits> Shared via API Message server store files for message entries, clients access these via a messaging API.
+?:\system\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits>.new Shared via API Temporary file used whilst committing message server store files.
+?:\system\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits>_F\* Shared Files associated with a message entry. These are accessed directly by clients.
+c:\system\data\msgs.ini Private Stores the drive containing the last used message store
+c:\system\Mtm\Mtm Registry v2 Private Cache of registered MTMs, internal to message server
+C:\system\data\sms_settings.dat Shared Copy of the SMS settings.
+?:\System\Mail\StoreInit.tmp Shared Created when message server runs ‘mailinit.exe’, ‘mailinit.exe’ should delete the file when it has successfully completed.
+?:\System\Mail\storedeleted.tmp Shared Created when message server finds and deletes a corrupt message store. Allows the UI to inform the user about the fact that the message store was corrupt.
+Files that are shown as private should only be accessed by the message server or by connectivity process for backup and restore purposes. Files listed as shared are accessed directly by messaging clients. Files listed as shared via API are accessed by client process but only via messaging APIs.
+3.2.1.3.3 Platform Security Compliant Message Store
+From v9.0 and onwards the message store is stored in the message server's data cage and the settings data are placed in the Central Repository. Access to the message store is only possible via message server APIs and not directly through file access. This leads to secured data storage and secured platform.
+3.2.1.3.3.1 Data caging
+Filename Purpose
+?:\private\<SID>\Mail\index Message server index file, internal to message server
+?:\ private\<SID>\Mail\<8 hex digits> Message server store files for services, clients access these via a messaging API.
+?:\ private\<SID>\Mail\<8 hex digits>.new Temporary file used during committing message server store files.
+?:\ private\<SID>\Mail\<8 hex digits>_F\* Files associated with a messaging service. These may be accessed directly by clients.
+?:\ private\<SID>\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits> Message server store files for message entries, clients access these via a messaging API.
+?:\ private\<SID>\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits>.new Temporary file used whilst committing message server store files.
+?:\ private\<SID>\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits>_F\* Files associated with a message entry. These are accessed directly by clients.
+c:\ private\<SID>\data\msgs.ini Stores the drive containing the last used message store
+c:\ private\<SID>\Mtm\Mtm Registry v2 Cache of registered MTMs, internal to message server
+?:\ private\<SID>\Mail\StoreInit.tmp Access via IPC call
+?:\ private\<SID>\Mail\storedeleted.tmp Created when message server finds and deletes a corrupt message store. Allows the UI to inform the user about the fact that the message store was corrupt.
+?\resource\messaging\bif\*.bif Registration data field with UID used in BIO framework
+
+3.2.1.3.4 How message centres display the message store
+The UI normally provides a Message Centre application to display the structure of the message store to the user. Different UIs map the structure to different views.
+
+Figure 8 Series 60 Message Centre (Composed from 2 screen shots)
+Figure 8 shows the top level view of the message centre application on a Series 60 phone. This shows that the message centre has hidden the local service and shows the standard folders at the same level as the services. Also the SMTP, SMS and MMS services are marked as hidden entries in the message store, and so do not appear in the message application.
+
+Figure 9 UIQ Message Centre
+However Figure 9 shows that the UIQ message centre has no 1-1 mapping from the structure in the message store to the structure shown to the user. Each of the message types is displayed as if its messages were contained in separate folders. Under each of these folders the user is presented with an inbox, outbox, send and drafts folder. This filtering is done in the UI layer as this functionality is not provided by the messaging API.
+3.2.1.3.5 Message Type Module Architecture
+
+Figure 10 Messaging MTM Structure (light coloured components are part of messaging subsystem)
+The MTM architecture is the plug-in scheme provided by the messaging framework to integrate different message transports into the message server. The plug-in scheme consists of four interfaces, the UI MTM, UI Data MTM, Client MTM and Server MTM. The messaging client applications loads and uses the first three which are loaded within the client’s process space. The final one the Server MTM is loaded within the message server process. The APIs for the client facing interfaces are extensible via run time type information provided by the QueryCapability API, and the InvokeAsyncFunction and InvokeSyncFunction APIs.
+3.2.1.3.5.1 UI MTM
+Handles requests from clients to view and edit messages or service settings. The MTM handles interaction with the message centre and as such the exact meaning of the APIs is defined by the UI. However common meanings are:
+• Create – Launches the editor with a new message.
+• Edit – If entry is a message this launches the editor; if entry is a service it edits the settings.
+• View – Launches the message viewer.
+• Display progress of an operation.
+3.2.1.3.5.2 UI data MTM
+This MTM provides fast access to UI components such as menu resources and bitmaps required by message centre for list views etc. Again the exact semantics are UI specific.
+There is a resource file defining UI specific functions, for example the Series 60 Messaging UI checks if the resource file contains text to display in the “New Message” menu.
+The UI data MTM also provides mapping from the message store’s TMsvEntry structure to Icons for the messaging list views and a status string, for example in the case of Nokia 9210 it is used in the outbox view to provide strings like “Resend 01:07” as shown in Figure 11. The class also provides functions to determine what operations are possible with a given entry. Examples of this are APIs that return whether the UI should allow the user to reply to the entry or to delete a service entry. The UI then uses this information to determine which menu options / short-cut keys should be allowed when the user selects a given entry.
+
+Figure 11 Nokia 9210 Outbox List View
+3.2.1.3.5.3 Client MTM
+Provides methods to create / reply and forward messages. Functions the Client MTMs provide are:
+• Create Message.
+• Reply to a Message.
+• Forward a Message.
+• Add / remove Addressees.
+• Add / remove body text.
+• Add / remove subject.
+• Add / remove attachments (the API cannot list attachments).
+The Client MTM interface is used by SendAs to provide a way of creating messages independently of the message type.
+3.2.1.3.5.4 Server MTM
+This is the final interface that makes up an MTM plug-in; it differs from the other three plug-ins in that it is loaded into the message server’s process space. The Server MTM provides access to messages under remote services. It handles connecting to remote servers to handle updating the local cache of these messages or to send messages copied to remote services when messages are copied to a remote service. The message server loads and hands off all message store operations that involve entries under a remote entry, these are the entries on the left-hand side of Figure 6.
+Functions that a Server MTM must implement:
+• Copy/MoveToLocal – called when the message server is asked to move or copy an entry that is currently under a remote service. A Server MTM might map this to retrieving a message from a remote mailbox.
+• Copy/MoveFromLocal – called when the message server is asked to move or copy from under the local service to a destination under a remote service. A Server MTM should map this to sending a message if the MTM supports sending.
+• Create, Delete, Change – called when the message server is asked to perform these operations on entries under a remote service.
+• StartCommand – this API provides a means of extending the API the Server MTM provides. Messaging clients pass a command ID and a selection of entries via the message server to the Server MTM. Examples of commands that Server MTMs might provide are: connect and synchronise the entries under a remote service with the messages on an email server, list SMS messages present on the phones SIM. These commands are MTM specific and therefore clients have to know which MTMs support which commands.
+3.2.1.3.5.5 MTM Registration
+MTMs must be registered with the message server so that clients can query what MTMs are present and the server knows which DLL to load to create a given MTM component. MTMs are registered by providing a resource file containing the MTMs UIDs, human readable name, and for each MTM interface it lists a DLL and the ordinal at which the constructor for that interface exists. The message server will search the ROM drive for MTM registration resource files on start-up and it will automatically register any MTMs found. For registration of MTMs installed on other drives, the message server provides an API to register and de-register an MTM. Registration will persist across a reboot, so an MTM only needs to be registered when it is installed on the system.
+When MTMs are registered or unregistered the message server will send events to all messaging clients with a message server session open.
+3.2.1.3.6 Message Server Client API
+The Messaging Server Client API breaks down into two categories: APIs for manipulation of the message store and utility APIs.
+3.2.1.3.6.1 Message Store manipulation APIs
+Requests from clients to modify the message store fall into three categories:
+1. Operations performed entirely with local entries (entries on the right-hand side of Figure 6) for example requests to create entries in the inbox, delete an entry from the drafts folder etc. The message server handles these operations directly.
+2. Operations that involve a remote entry (entries on the left-hand side of Figure 6) for example requests to delete an entry under a POP3 service, or copy a message to an SMTP service. The message server hands these operations off to the Server MTM that owns the service under which the remote entry is stored. The only exception to this rule is the ChangeAttributes API call. This modifies flags on an index entry and is handled by the message server for both local and remote entries. This means that a Server MTM can not rely on being called when flags like the Unread flag are changed. Note that operations can not involve two remote entries; therefore requests to copy entries between a remote service representing one POP3 account to a remote service representing another POP3 account will fail with an error.
+3. Requests that are explicitly directed at a Server MTM via the TransferCommand API. These commands are just passed to the correct Server MTM by looking up the Service ID and MTM of the first message in the selection passed into the command.
+The message server sends events when entries in the message store are modified to messaging clients that have a session open with the server.
+Where the API provides asynchronous functions to modify the message store or transfer a command to a Server MTM, the functions will return a message server operation object. This object can be used to request progress on operation or cancel the operation. Deleting the operation object returned, or closing the session used to make the request will result in the operation being cancelled, therefore a messaging client must remain running until operations it has requested have either completed or they will be cancelled. See appendix A.1 for an example of an asynchronous copy operation. If a Server MTM operating on the same remote service is already handling an operation, the message server will queue the new operation to be handled when the Server MTM becomes free. Requests for progress of operations that are queued will fail with KErrNotReady. The fact that the queue is based on the remote service ID means that you can have two Server MTMs of the same type running at the same time as long as they are operating on different services. So for example you can have two separate POP3 MTMs running synchronising different remote services with email servers.
+3.2.1.3.6.2 Utility APIs
+1. Access to MTM registries – These allow clients to construct instances of the interfaces an MTM implements.
+2. Register / Unregister an MTM.
+3. Change Drive – The message server closes the current message store and opens one on the drive specified. If no message store is present on the drive specified a new message store is created. The message sever can have only one mail store open at a time, if the current mail store is not available because a the disk the mail store is on is not present then the message server will switch the mail store back to the C: drive if an attempt is made to create a message in the inbox.
+4. Launching Editors – This launches the correct editor for a message. It is implemented by delegating the request to the UI MTM
+3.2.2 Messaging / Send As APIs
+3.2.2.1 Key Relationships and Dependencies
+
+Figure 12 SendAs Version 1 Dependencies
+SendAs version 1 and only present in releases before v9.0. SendAs uses the Messaging Client API to access the registry of Client MTMs and construct the Client MTM interfaces. The Client MTMs are then used for composing the message. SendAs requires clients to implement the MSendAsObserver interface. This interface is responsible for checking the return value of the capability queries made to Client MTMs that require a response and also for rendering message types that require it. The only message type supplied by Symbian that requires rendering is Fax, however this MTM has been removed in 8.0a and future releases.
+3.2.2.2 API Purpose - Further Elaboration
+3.2.2.2.1 SendAs API (pre – v9.0)
+The SendAs API makes use of the Client MTM interface and the Messaging Client API to provide a generic API for creating messages. Note despite the name of this component SendAs does not provide an API to send the message.
+SendAs builds a list of registered MTMs, then queries each MTM to check whether it supports sending, removing those MTMs from the list that do not support sending. This list is then provided to the messaging client application. At this point the application can add more constraints on the list of MTMs; for example it can insist the MTM supports Attachments or more than a certain size of body text. SendAs queries each of the MTMs about the requirements and will drop any MTMs from the list that does not meet them. When the application has finished adding requirements it selects one of the MTMs left in the list and uses that to compose the message, adding addresses, a subject, body text and attachments.
+SendAs supports setting a BIO Type for the message that is composed. This tells the transport that the body text represents a BIO Message. This is used when sending business cards from the contacts application as SMS messages; the contacts application puts the vCard data in the body text of the message and the transport sends it correctly. If the MTM in question supports attachments then the vCard is attached to the message.
+A new CSendAs object must be created for each message the application wishes to create.
+3.2.3 Platform Security Compliant SendAs Server (v9.0 onwards)
+
+Figure 13 SendAs Version 2 Dependencies
+From v9.0 and onwards the CSendAs has been replaced by the SendAs server component. The new SendAs server controls the access to the message store. Some of the key SendAs Server features are listed as follows.
+• Send a message once the capability policing of the client application has been completed.
+• Allow client applications to launch an editor for a specified message type.
+• Allow client applications to query the message type.
+The main client-side API is the RSendAs class. The client applications use this to connect to the Send-As server. The session object on the server-side is an instance of CSendAsSession.
+Client applications create messages using the RSendAsMessage API. Opening an RSendAsMessage object on Send-As server session creates a CSendAsMessage object in the Send-As server. There is a one-to-one mapping between an RSendAsMessage object and a CSendAsMessage object. This allows client applications to create multiple messages concurrently.
+
+3.2.4 Messaging / Schedule Send APIs
+3.2.4.1 Key Relationships and Dependencies
+
+Figure 14 Schedule Send Dependencies
+The Schedule Send Server MTM base class depends on the task scheduler to launch the schedule send executable at the correct time. To send the message with a package of data previously passed into the task scheduler by the Server MTM. The schedule send executable then uses the Messaging Client API to actually perform the requested operation.
+3.2.4.2 API Purpose - Further Elaboration
+3.2.4.2.1 Schedule Send
+The Schedule Send functionality is delivered by four components:
+Server MTM Base Class – The base class provides support to Server MTMs that wish to support scheduled operations.
+Data Structures – These are classes used to represent the data associated with a scheduled operation.
+Executable – The executable is run by the task scheduler at the scheduled time.
+The Task Scheduler – This component is part of the system libraries subsystem. Currently the SMS and Fax Server MTMs support scheduled sending.
+Clients request the Server MTM schedules operations via additional commands passed to TransferCommand API; this is passed to the Server MTM via the message server. The Server MTM packages the operation ID, a selection of message IDs, how often to poll for progress and an MTM specific buffer. It then passes this package of data to the task scheduler requesting that it launches the schedule send executable at the correct time with the packaged information.
+When the task scheduler launches the schedule send executable, it unpacks the schedule information and uses the Messaging Client API to request the Server MTM to perform the operation.
+Schedule Send supports a retry mechanism if the operation fails. The Server MTM has a resource file containing a mapping from the error codes the operation can fail with and actions to be performed. For example the SMS resource file has a mapping such that if the operation fails with an error code indicating a bad phone number the SMS will be set to failed and left in the outbox. Whereas if it fails with a error code indicating temporary network failure the send operation will be scheduled to be resent later with a maximum of three retries.
+3.2.5 Messaging / Watchers APIs
+3.2.5.1 Key Relationships and Dependencies
+
+Figure 15 Watcher Dependencies
+The watcher executable’s dependency on the message server is the result of a performance measure. The watcher process creates a message server session before initialising each of the watcher plug-ins and closes the session when it has finished. This keeps the message server running during initialisation avoiding starting and stopping the message server if each watcher plug-in opens and closes sessions.
+3.2.5.2 API Purpose - Further Elaboration
+The watcher framework consists of an executable that is launched when the device boots. The component that is responsible for launching it depends on the UI family. When the watcher.exe is launched it will load each DLL in z:\system\libs\watchers which has a second UID as KWatcherUid and calls the first DLL entry point to construct a CActive object.
+From v9.0 and onwards watcher DLLs are found by scanning the directory \resource\messaging\watchers for registry files. These files contain the name of a watcher DLL that can be loaded from ROM i.e. z:\sys\bin.
+The framework has retry behaviour if the first entry point leaves, in this case the watcher framework will start a timer and try and construct the watcher object 10 seconds later. Five attempts are made before the watcher plug-in is assumed to have failed completely. Once the watcher framework has constructed all the watchers it starts the active scheduler which should never exit.
+Watcher plug-ins typically make a request to another subsystem such that they will be completed when an external event like a fax line ringing or an SMS being received occurs. When the watcher has completed processing the request it will wait for the next event.
+No support for starting / stopping watchers is provided. This is a limitation that makes watchers unsuitable for operations like listening for messages beamed via IR, as the watcher should only run while the IR port is active.
+3.2.6 Messaging / Message URL Handler APIs
+3.2.6.1 Key Relationships and Dependencies
+
+Figure 16 Message URL Handler Dependencies
+3.2.6.2 API Purpose - Further Elaboration
+The Message URL Handler provides support for creating messages and launching messaging editors from URLs such as mailto:infobot@example.com?subject=current-issue. Note there is no dependency between the Message URL Handler application which processes the URLs and the Message URL Handler recognisers which maps from URLs to mime types.
+3.2.6.2.1 Message URL Handler Application
+This is a Symbian OS application that registers with the application framework that it can handle the mime types: x-epoc-url/fax, x-epoc-url/mailto and x-epoc-url/sms. When launched with a URL it will parse the URL to retrieve the address and other header fields and then use the SendAs API to create a new message with the correct address, headers etc. The application then uses the APIs in the MturUtils class provide by the mtmbase component in the messaging framework to launch the correct editor for the given message type. The application is marked as hidden and therefore should not be listed by UIs in application browsers.
+3.2.6.2.2 Message URL Recognisers
+This is a plug-in to the recogniser framework it will be called when the application framework wishes to recognise a file. Recognisers are called with the file name, in this case a URL, and a buffer containing the start of the file. The message URL recogniser compares the start of the URL with the URL schemes it recognises, if it finds a URL scheme it knows about it maps it to a mime type. The recogniser ignores the buffer passed in.
+Schemes recognised:
+Scheme Mime type
+mailto: X-Epoc-Url/mailto
+fax: X-Epoc-Url/fax
+sms: X-Epoc-Url/sms
+mms: X-Epoc-Url/mms
+See the application framework architectural description for more information on recognisers [R2].
+3.2.7 Messaging / SMS APIs
+3.2.7.1 Key Internal Relationships and Dependencies
+
+Figure 17 SMS Internal Dependencies
+3.2.7.2 Key External Relationships and Dependencies
+
+Figure 18 SMS External Dependencies
+3.2.7.3 API Purpose - Further Elaboration
+3.2.7.3.1 SMS Watchers
+The SMS watchers are made up of two watchers, the nbswatcher.dll and the wapwatcher.dll, and some common base classes in biowatcher.dll. The watchers listen for incoming messages from the SMS stack, part of the nbsprotocols subsystem [R3], and the WAP stack part of the WAP-Stack subsystem [R4].
+3.2.7.3.1.1 NBS Watcher
+The NBS watcher handles reception of SMS messages. When initialised by the watcher framework (see section 3.2.4) the watcher queries the bio messaging database for bio messages that are listed as having a type of ENbs. For each of these bio messages the watcher creates an object that opens a connection to the SMS stack and waits for the particular message type. The message types are either defined by the port number the message will be received on or by a string to watch for at the start of the message. For example Internet Access Configuration Point messages are start with “//SIAP11” and vCards are received on port 226. Finally the watcher listens for all other messages received from the SMS stack.
+When the NBS Watcher receives a non-class 2 SMS message it creates a new entry under the global inbox in the message store. For class 2 messages the entry is created in the class 2 folder as defined by the SMS settings, this may also be the global inbox. The details field of the entry is used to store the phone number of the incoming message or the name of the sender if the watcher finds a match for the phone number in the contacts database. The description field is used to store the first N characters of the SMS message, where N is defined in the SMS settings, or for bio messages the description as retrieved from the bio database. Bio messages also have the BioType field set to the UID of the bio message as retrieved from the bio database. The CSmsHeader class, which is a wrapper around the CSmsMessage class provided by the nbprotocols subsystem [R3], is used to externalise the SMS message to the entry’s CMsvStore. The watcher also places a copy of the body text of the message in the rich text stream of the entry’s CMsvStore.
+The NBS Watcher is also responsible for handing special SMS types including:
+• Replace Type Messages – When the watcher receives a message of this type it will scan the folder the message would have been delivered to for messages that have a matching protocol ID and from address. For each of the messages it checks whether the time stamps from the service centre and discards the older message.
+• Message Indications – The watcher can listen for incoming message waiting indications. The CSmsSettings class defines whether the watcher will listen and whether it will deliver the messages to the inbox or discard them. If the watcher is configured to listen for messages then it will use the SMS utilities in the SMS Client MTM to decode the message to determine the notification type and number of messages, e.g. 3 Email messages waiting, the strings for these messages are in the smss.rss resource file.
+• Delivery Reports – As with Message Indications the watcher can be configured to listen for these and again the SMS utilities get a string from the smss.rss resource file to put in the description field.
+The NBS Watcher handles changes to the bio database using the observer mechanism provided by the bio message database to observe when bio message types are added or removed and starting or stopping the object watching for that bio message type.
+3.2.7.3.1.2 WAP Watcher
+The WAP watcher listens for incoming messages from the WAP stack using the WAP message API [R4]. To determine ports to use to listen for messages the watcher queries the bio message database for bio message types EWsp, EWspSecure, EWap, EWapSecure and registers as an observer of the bio database and so will listen for new bio message with these types as they are added. The watcher stores the messages in the global inbox tagged with the bio type listed in the bio message database.
+3.2.7.3.2 SMS Client MTM
+The SMS Client MTM implements the standard set of Client MTM APIs described in Client MTM. In addition it provides:
+• Access to the CSmsHeader object that is used to represent the SMS message.
+• Access to the SMS settings stored in the associated SMS service.
+• The APIs required by Send As to allow Send As to create SMS messages including setting the bio type of the message to allow clients of Send As to send bio messages such as vCards and vCals. The data of the bio message is stored in the body text of the SMS message.
+• Simple check for valid SMS addresses, and SMS address is considered valid if it contains at least one digit.
+• Reading and writing SIM parameters.
+3.2.7.3.3 SMS Utilities
+These provide:
+• Classes to represent and store SMS messages (CSmsHeader), and SMS settings (CSmsSettings, CSmsMessageSettings) and a SMS number (CSmsNumber).
+• The CSmsHeader class contains and allows clients to access the CSmsMessage class that the nbsprotocols subsystem provides. This contains the entire SMS message and not just the header.
+• Functions to generate descriptions and details fields to store with SMS messages, including decoding special messages such as message indication and status report messages, reading resource file for descriptions strings of special messages, using the contacts database to replace phone numbers with names.
+• API to validate a GSM number.
+• Find the TMsvId of the SMS service entry.
+3.2.7.3.4 SMS Server MTM
+3.2.7.3.4.1 Sending Messages
+The SMS Server MTM handles sending of SMS and WAP messages via the SMS stack and the WAP stack. To support this it implements the CopyFromLocal API inherited from the Server MTM base class. It implements this as sending SMS messages and moving successfully sent messages to the Sent folder. When sending the SMS message the Server MTM checks the bio type of the message and uses the bio database to check the transport type for the bio message. The MTM supports ENbs that is sent via the SMS stack and EWap, EWapSecure that are sent via the WAP stack. The MTM does not support EWsp or EWspSecure although the watchers do support receiving them.
+If a message fails to send, sending is retried according to the settings in the smss.rss resource file as described in the schedule send section 3.2.3.
+3.2.7.3.4.2 Scheduling Messages
+The SMS Server MTM implements scheduled sending API by sub-classing from the schedule send Server MTM (see section 3.2.3). It accepts requests from clients either via the SMS Client MTM InvokeAsync API or via the CMsvSession::TransferCommand API to schedule messages to be sent or to delete existing schedules. When it receives a request to schedule a message it packages up the command and uses the scheduled send functionality to request that the task scheduler ask it to send the messages at a future point in time.
+3.2.7.3.4.3 Phone Store
+The phone store is the name given to storage of SMS messages outside of the message store. In the case of GSM phones this is the SIM. The SMS Server MTM accepts requests from clients to copy/move messages to and from the SIM and delete messages from the SIM. For example when copying to the SIM it packages up the SMS message and passes it to the SMS stack with a request to write it to the SIM. If the class2 folder has been set in the SMS settings class then the Server MTM will copy the SMS message to the SIM and then update the SMS message in the message store with details of the slot on the SIM that has been used to store the SMS and the fact that it is stored on the SIM.
+3.2.7.3.4.4 SIM Parameters
+The Server MTM provides functions to read / write SIM parameters, again these requests are passed to the SMS stack to be processed.
+3.2.8 Messaging / CDMA SMS APIs
+3.2.8.1 Key Internal Relationships and Dependencies
+
+Figure 19 CMDA SMS Internal Dependencies
+3.2.8.2 Key External Relationships and Dependencies
+`
+Figure 20 CDMA SMS External Dependencies
+3.2.8.3 API Purpose - Further Elaboration
+3.2.8.3.1 CDMA SMS Watchers
+The CDMA SMS watchers are made up of six watchers, the cdmanbswatcher.dll, vmnwatcher.dll, wemtwatcher.dll, wmtwatcher.dll, wptwatcher.dll, and the wapwatcher.dll, and some base classes in biowatcher.dll and cdmasocketwatcher. While the WAP watcher is common for both GSM and CDMA, the other watchers: CDMA NBS watcher, VMN watcher, WEMT watcher, WMT watcher, and the WPT watcher are used for CDMA only. The watchers listen for incoming messages from the CDMA SMS stack, part of the nbsprotocols subsystem [R3], and the WAP stack part of the WAP-Stack subsystem [R4].
+3.2.8.3.1.1 CDMA NBS Watcher
+The CDMA NBS watcher is similar to the NBS watcher and it handles bio messages defined in bio database. The CSmsHeader class is extended to wrap around the CCdmaSmsMessage class provided by the nbprotocols subsystem [R3], and is used to externalise the CDMA SMS message.
+For handling special CDMA SMS type, the CDMA NBS watcher is responsible for handling Message Indications as described in section 3.2.7.3.1.1 NBS Watcher.
+3.2.8.3.1.2 WAP Watcher
+The GSM WAP watcher is used to handle CDMA WAP message as well. The WAP watcher listens for incoming messages from the WAP stack, which can listen from the CDMA SMS stack or GSM SMS stack as appropriate. See 3.2.7.3.1.2 for more info about WAP watcher.
+3.2.8.3.1.3 Other CDMA Watchers
+The VMN watcher, WEMT watcher, WMT watcher and WPT watcher are CDMA watchers that handle reception of CDMA SMS messages. All CDMA SMS messages are associated with a teleservice. Therefore, each of the CDMA watchers is responsible for handling one teleservice: VMN watcher handles VMN SMS messages, WEMT watcher handles WEMT SMS messages, WMT watcher handles WMT SMS messages, and WPT watcher handles WPT SMS messages. The CSmsHeader class is reused to externalise the CDMA SMS message.
+The CDMA watchers are also responsible for handling special SMS types including:
+• Duplicate Message – When the watcher receives a duplicate message, it will discard the duplicate message as defined by the CDMA service settings.
+• User Acknowledge – The watcher can listen for user acknowledgment message of its teleservice type.
+• Delivery Acknowledge – The watcher can listen for delivery acknowledgment message of its teleservice type.
+• Read Acknowledge – The watcher can listen for read acknowledgment message of its teleservice type.
+3.2.8.3.2 CDMA SMS Client MTM
+The CDMA SMS Client MTM implements the standard set of Client MTM APIs described in Client MTM. In addition it provides:
+• Access to the CSmsHeader object that is used to represent the SMS message.
+• Access to the SMS settings stored in the associated SMS service. These settings are store in file store pre v9.0 but stored in Central Repository from v9.0 onwards.
+• The APIs required by Send As to allow Send As to create SMS messages including setting the bio type of the message to allow clients of Send As to send bio messages such as vCards and vCals. The data of the bio message is stored in the body text of the SMS message.
+• Simple check for valid SMS addresses, and SMS address is considered valid if it contains at least one digit.
+• Reading and writing SMS messages to R-UIM.
+3.2.8.3.3 CDMA SMS Utilities
+The CDMA version of SMS utilities are binary compatible with the GSM version of SMS utilities. But the classes that store SMS Message (CSMSHeader), and SMS settings (CSmsSettings, CSmsMessageSettings) and SMS number (CSmsNumber) are extended to store CDMA information. The CSmsHeader class is extended to contain and allow clients to access the CCdmaSmsMessage in addition to the CSmsMessage. Other functions provided by the GSM SMS Utilities is also provided by the CDMA version of SMS utilities, see 3.2.7.3.3 for information about GSM SMS Utilities.
+3.2.8.3.4 CDMA SMS Server MTM
+3.2.8.3.4.1 Sending Messages
+The CDMA SMS Server MTM handles sending of CDMA SMS and WAP messages via the CDMA SMS stack and the WAP stack. To support this it implements the CopyFromLocal API inherited from the Server MTM base class. It implements this as sending SMS messages and moving successfully sent messages to the Sent folder. When sending the CDMA SMS message the Server MTM will use the appropriate teleservice type. The MTM supports ENbs that is sent via the SMS stack and EWap, EWapSecure that are sent via the WAP stack. The MTM does not support EWsp or EWspSecure although the watchers do support receiving them.
+If a message fails to send, sending is retried according to the settings in the smss.rss resource file as described in the scheduled send section 3.2.4.
+3.2.8.3.4.2 Scheduling Messages
+The CDMA SMS Server MTM implements scheduled sending API by sub-classing from the schedule send Server MTM similar to implemented in the GSM SMS Server MTM. See 3.2.7.3.4.2 for more information.
+3.2.8.3.4.3 Phone Store
+In the case of CDMA phones, phone store can be phone-based storage or R-UIM based storage. The CDMA SMS Server MTM accepts requests from clients to copy/move messages to and from the phone/R-UIM and delete messages from the phone/R-UIM. For example when copying to the R-UIM it packages up the SMS message and passes it to the CDMA SMS stack with a request to write it to the R-UIM.
+3.2.8.3.5 Configuration for using CDMA SMS MTM
+The CDMA messaging components currently only support single mode, but it is designed such that it can become multimode in the future. Currently, -Dcdma option is used to for selecting CDMA mode for using emulator and building ROM.
+
+
+3.2.9 Messaging / Email APIs
+3.2.9.1 Key Internal Relationships and Dependencies
+
+Figure 19 Email Internal Dependencies
+
+3.2.9.2 Key External Relationships and Dependencies
+
+Figure 20 Email External Dependencies
+3.2.9.3 API Purpose - Further Elaboration
+3.2.9.3.1 Email Overview
+The Email plug-ins consist of a set of utilities and MTMs for POP3, IMAP4 and SMTP. For each email account a pair of services entries is created in the message store. For a POP3 account there will be an SMTP service and a POP3 service, for an IMAP4 account there will be an SMTP service and as IMAP4 service. These entries are used to store the settings for the email transport. Each of the service entries has its related ID set to the other member of the pair. The SMTP service is created invisible so the user only sees the POP3 or IMAP4 service entry, copying a message to the SMTP service will cause the SMTP Server MTM to attempt to send the message. The POP3 and IMAP4 MTMs provide functionality to synchronise with a remote email server this is achieved by extending the Client MTM interface via the InvokeAsync API. Synchronisation of a POP3 or IMAP4 account will result in copying headers and optionally body text and attachments from the email server and creating message entries under the POP3 or IMAP4 service entry.
+Email messages are represented in a common format whether they are being sent via SMTP or downloaded via POP3 or IMAP4. The email client utilities provide the classes for creating and manipulating the entry structure used to store emails. The email server side utilities provide classes to convert between the entry structure used to store emails in the message store and RFC2822 email messages sent to SMTP servers and retrieved from POP3 servers. IMAP4 email messages are parsed by the email server and the IMAP4 Server MTM requests and stores the individual parts of the messages.
+3.2.9.3.2 Email Client Utilities
+The email client utilities are part of the imcm DLL and provide classes for:
+• Storage of email messages including mime headers, RFC2822 headers, attachments, body text and encoding information in the message store
+• Manipulating email messages, for example adding attachments, replying etc.
+• To wrap up the character converters used to convert between standard character sets and Unicode. These make use of the charconv component that is part of the system libraries subsystem.
+• Storage of Email settings in the message store.
+• Progress information for email operations.
+The utilities are used directly by clients to access parts of email messages for display. CImEmailMessage provides the functionality used by clients displaying email messages, including listing attachments, getting body text and resolving URIs in M-HTML messages.
+The Email Client MTMs use the utilities when they are asked to create, reply to and forward messages CImEmailOperation provides the functionality to perform these operations. Each email message is represented by a parent message entry and then entries to represent mime folders and mime parts, see Figure 7 for an example, so adding or deleting mime parts involves walking the tree of entries and inserting / removing entries as appropriate.
+3.2.9.3.3 Email Server MTM Utilities
+The Email Server MTM Utilities are responsible for generating and parsing of RFC2822 format email messages and providing an API to wrap up a TCP/IP connection to a remote email server.
+• Parsing of RFC2822 Email Messages – The utilities provide an API that accepts the text of an RFC2822 email message a line at a time and stores the email message in messaging’s internal format for email messages. See the Email Client Utilities for details of this format. The API handles storing of RFC2822 headers, MIME headers, decoding of Base64 encoded or uuencoded attachments and decoding of text received in character sets supported by the charconv component. This API is only accessible to Server MTMs, as it requires classes that can only be instantiated while running within the message server process. See the Messaging Functional Specification [R1] for detail on which email specifications the utilities support.
+• Generation of RFC2822 Email Messages – The utilities provide an API to convert an email in messaging’s internal format into an RFC2822 email message. The API provides access to the RFC2822 text a line at a time for streaming to an SMTP server. The exact format of the email depends on the settings passed in; the API can generate plain RFC2822 email messages with uuencoded attachments, MIME email messages with Base64 encoded attachments, or M-HTML email messages with Base64 encoded attachments. See the Messaging Functional Specification [R1] for detail on which email specifications the utilities support.
+• TCP/IP socket wrapper – The utilities provide a class that abstracts a TCP/IP socket supplied by the networking subsystem into an API that supports sending and receiving lines of text to / from a remote server. This API is used to connect to remote email servers by each of the email Server MTMs. The API can either create insecure or secure sockets enabling the SSL encryption provided by the networking subsystem. It also supports changing an insecure socket into a secure socket, this enables the email Server MTMs to implement email protocols where the initial connection to the server is insecure and then a secure socket is negotiated before sending or requesting any sensitive information.
+3.2.9.3.4 POP3 MTMs
+The POP3 MTMs implements the functionality to synchronise the local message store with a remote POP3 email server.
+3.2.9.3.4.1 Client MTM
+The POP3 Client MTM implements the standard Client MTM APIs and other extensions:
+• Reply to, forward – These are accessible via the ReplyL and ForwardL APIs of a Client MTM and are implemented as calls to the email utilities class CImEmailOperation.
+• Reply to, forward, create new messages, create receipts and forward as attachment – These are accessible as commands available via the InvokeAsyncFunction API of the Client MTM, they are implemented as calls to CImEmailOperation.
+• Connecting, disconnecting and copying email while connected – These operations are accessible as commands available via the InvokeAsyncFunction API of the Client MTM, they are implemented as calls to the POP3 Server MTM.
+• Querying connection status – This command lets clients know whether the POP3 Server MTM is connected to an email server, and is available via the InvokeAsyncFunction API of the Client MTM. The Client MTM requests the information from the Server MTM.
+• Compound operations – The Client MTM provides functionality to wrap up connecting to email servers, copying / moving new messages or a selection of messages, and then optionally disconnecting. These commands are available via the InvokeAsyncFunction API of the Client MTM. The Client MTM implements this by using the CImPOP3GetMail class which requests the correct sequence of operations from the Server MTM, waiting for each operation to complete before requesting the next one.
+• Send on next connection If the Client MTM gets a request to connect to an email server it will check whether the POP3 settings. If send on next connection is requested it will launch the autosend.exe executable (see section 3.2.7.3.7) to handle sending messages waiting in the outbox.
+• Offline operations – The POP3 Client MTM has a command to cancel offline operations, this is available via the InvokeAsyncFunction API of the Client MTM. The Client MTM passes the request to the Server MTM.
+3.2.9.3.4.2 Server MTM
+The POP3 Server MTM handles the communication with the remote POP3 server and implementation of the POP3 protocol. The MTM uses CImTextServerSession to handle the communication with the email server and CImRecvConvert to parse the email messages downloaded, both are provided by the Email Server MTM Utilities.
+• Connect – The POP3 Server MTM will open a socket to the email server using CImTextServerSession and login user the username / password in the POP3 settings. After a successful connection the Server MTM will attempt to synchronise the current state of headers stored on the email server with the set stored in the message store and then start any pending offline operations. After the connect operation has completed the Server MTM will inform the message server that it is expecting more operations via the CommandExpected API and therefore the message server will not delete and unload the Server MTM.
+• Populate Message – The POP3 Server MTM treats requests to copy a message from and to the POP3 service as a request to download the full message.
+• Offline operations – When the POP3 Server MTM receives a request to copy, move, or delete and is not connected to a POP3 email server the Server MTM will store the operation in the CMsvStore of the entry being modified and perform the operation on the next connection to the email server.
+• Disconnect – When disconnecting from a remote email server the POP3 MTM will run any pending offline operations stored. After the disconnect operation completes the Server MTM will allow the message server to delete and unload the Server MTM by setting the CommandExpected API to false.
+3.2.9.3.5 IMAP4 MTMs
+The IMAP4 Server MTM implements the functionality to synchronise the local message store with a remote IMAP4 email server.
+3.2.9.3.5.1 Client MTM
+The IMAP4 Client MTM implements the standard Client MTM APIs and other extensions:
+• Connecting, disconnecting, synchronising, un/subscribing folders – These operations are accessible as commands available via the InvokeAsyncFunction API of the Client MTM, they are implemented as calls to the IMAP4 Server MTM.
+• Send on next connection – If the Client MTM gets a request to connect to an email server it will check whether the IMAP4 settings. If send on next connection is requested it will launch the autosend.exe executable (see section 3.2.7.3.7) to handle sending messages waiting in the outbox.
+• Reply to, and forward messages – These are accessible via the ReplyL and ForwardL APIs of a Client MTM and are implemented as calls to the email utilities class CImEmailOperation.
+• Reply to, forward, create new, create receipt, forward as attachment – These are accessible as commands available via the InvokeAsyncFunction API of the Client MTM, they are implemented as calls to CImEmailOperation.
+• Querying connection status – These commands let clients know whether the IMAP4 Server MTM is connected to an email server and whether it is currently processing a request. They are available via the InvokeAsyncFunction API of the Client MTM. The Client MTM requests the information from the Server MTM.
+• Compound Connection and synchronisation – The IMAP4 Client MTM provides a compound operation that connects and synchronises with an IMAP4 server. This operation is implemented as a client side object that combines requests to the IMAP4 Server MTM. The client side operation can complete the client request either after the connection, after the connection + sync or after the connection + sync + disconnect. The client will keep requesting that the inbox be resynchronised at a configurable interval so new messages received in the inbox on the server will appear under the IMAP4 inbox. The CImapConnectAndSyncOp class handles these compound operations.
+• Compound Connect and copy / move / populate messages – The IMAP4 Client MTM provides a compound operation that connects to an IMAP4 server and copies moves or populates messages. The implementation is provided by the CImImap4GetMail class which makes calls back into the IMAP4 Client MTM.
+• Offline operations – The IMAP4 Client MTM has a command to cancel offline operations, this is available via the InvokeAsyncFunction API of the Client MTM. The Client MTM passes the request to the Server MTM.
+3.2.9.3.5.2 Server MTM
+The IMAP4 Server MTM handles the communication with the remote IMAP4 server and implementation of the IMAP4 protocol. The MTM uses CImTextServerSession to handle the communication with the email server. The IMAP4 Server MTM opens two connections to the IMAP4 server this enables users to download messages while the Server MTM is performing a background synchronisation if requested by the Client MTM.
+• Connect – The IMAP4 Server MTM will open a socket to the email server using CImTextServerSession and login using the username / password in the IMAP4 settings. After a successful connection the Server MTM will optionally attempt to synchronise the current state of headers stored on the email server with the set stored in the message store and then start any pending offline operations. After the connect operation has completed the Server MTM will inform the message server that it is expecting more operations via the CommandExpected API and therefore the message server will not delete and unload the Server MTM.
+• Copy, Move messages – The IMAP4 Server MTM supports copying and moving messages between folders on the IMAP4 server and between the IMAP4 server and local folders.
+• Delete messages – The IMAP4 Server MTM will mark the email as deleted on the server; however it will not be deleted until the IMAP4 Server MTM disconnects from the server.
+• Folders – The IMAP4 Server MTM will allow folders to be subscribed, unsubscribed, renamed, copied, moved, and created within the IMAP4 service. Subscribing to a folder means that it will be visible to the user and synchronised with the remote server. The inbox is always subscribed.
+• Offline operations – When the IMAP4 Server MTM receives a request to copy, move, or delete and is not connected to an IMAP4 email server the Server MTM will store the operation in the CMsvStore of the entry being modified and perform the operation on the next connection to the email server.
+• Disconnect – When disconnecting from a remote email server the IMAP4 MTM will run any pending offline operations stored. After the disconnect operation completes the Server MTM will allow the message server to delete and unload the Server MTM by setting the CommandExpected API to false.
+
+3.2.9.3.6 SMTP MTMs
+The SMTP MTMs provide functionality to send email messages. They are made up of the Client MTM that is part of the imcm DLL and the Server MTM.
+3.2.9.3.6.1 Client MTM
+The SMTP Client MTM implements the standard Client MTM APIs including the functions required to allow clients of Send As to create email messages.
+3.2.9.3.6.2 Server MTM
+The SMTP MTMs provide functionality to send email messages; it interprets requests to copy entries to an SMTP service as a request to send those messages. In addition it responds to two extended commands via the StartCommand Server MTM interface. These commands are KSMTPMTMIsConnected that responds with whether the Server MTM is currently connected to a remote SMTP server and KSMTPMTMSendOnNextConnection which performs the same operation as copying a selection of messages to an SMTP service. The only difference between the copy operation and the KSMTPMTMSendOnNextConnection operation is that the latter can be called without a selection of messages.
+When the Server MTM receives a request to send messages it builds a selection of messages consisting of the messages passed into the operation and any messages waiting in the outbox to be sent. To determine which messages in the outbox are waiting to be sent the SMTP server checks for messages that have the same service ID as the destination of the send operation and have a sending state of KMsvSendStateWaiting, KMsvSendStateScheduled or KMsvSendStateResend. This means that any request to send messages may result in more messages being sent than explicitly listed in the selection passed to the send operation.
+The Server MTM restores its settings from the SMTP service it has been asked to copy the messages to. Then it connects to the SMTP server using the CImTextServerSession class in the Email Server MTM Utilities, passing in the SMTP server address and TCP/IP port number from the SMTP settings. Then for each message to be sent the Server MTM uses the Email Server MTM utilities to generate an RFC2822 format message to send to the SMTP server, the RFC2822 text is generated on the fly as the data is sent to the SMTP server. If the SMTP server accepts the message to be sent then the Server MTM moves the message to the sent folder and sets its sending state to sent. If the SMTP server rejects the message then the Server MTM leaves the message in the outbox and sets the sending state to failed. Separate emails are generated for BCC recipients to ensure that the SMTP server doesn’t incorrectly include BCC recipients in emails sent to addresses in the To and CC fields of the email.
+3.2.9.3.7 Autosend
+The Autosend component is an executable that is kicked off by the POP3 and IMAP4 Client MTMs if the send on next connection setting is set. This executable will just make a request to the SMTP Server MTM to send messages associated with the SMTP service related to the POP3 or IMAP4 service, wait for the operation to finish and then exit.
+3.2.10 Messaging / MMS APIs
+The MMS module has been removed from v9.0 and onwards.
+3.2.10.1 Key Internal Relationships and Dependencies
+
+Figure 21 MMS Internal Dependencies
+3.2.10.2 API Purpose - Further Elaboration
+3.2.10.2.1 MMS Overview
+The MMS MTM provides functionality for creating, accessing, sending and receiving MMS messages. Messages are sent and received without the client application needing to open or close any kind of session. The management of the MMS session is handled entirely within the MTM.
+MMS clients are alerted when a new message is available for download via the WAP Push mechanism. A WAP push watcher is provided to handle these notifications. After the notification the message can be downloaded over WSP or HTTP. Messages are sent by posting the data over WSP or HTTP. The Symbian MMS implementation can handle sending or receiving MMS message over either protocol.
+MMS messages are based on the MIME format but are binary encoded using WSP. Note that MMS messages are encoded in this way even if they are posted over HTTP as opposed to WSP. The codec component is responsible for this encoding and decoding.
+3.2.10.2.2 MMS Utilities
+3.2.10.2.2.1 Key External Relationships and Dependencies
+
+Figure 22 MMS Utilities External Dependencies
+The MMS utilities provide the message and settings encapsulation classes. The MMS settings and messages are stored in the message store, the MMS utilities provide the interfaces to access this data.
+3.2.10.2.2.2 Settings
+The settings functionality provided by the MMS utilities allows the messaging client to persist MMS settings in the message store. Supported settings include:
+ MMSC (MMS server) address
+ WSP or HTTP transport
+ Autofetch messages on notification
+ Preferred IAP for the MMS network connection
+The settings functionality is also used by the server MTM to retrieve the settings prior to message sending or fetching.
+3.2.10.2.2.3 Message Encapsulation
+The message classes provide the message access functionality. Messages can be created, stored, restored and read using these classes. Functionality includes:
+ Adding media objects to the message
+ Enumerating through media objects
+ Adding recipients, subject line, etc. to a message
+ Adding other headers to the message, e.g. expiry date
+ Finding the appropriate media object for a given URI in the SMIL part (URI resolving)
+The message data is stored in the message store using one entry per message regardless of the number of media objects added to the message. This is preferable to using multiple message entries as it is faster and uses less disk space.
+Most of the message access code is common whether it is being used on the client or server side, however some parts of it are specific. For this reason it is essential that the appropriate client or server side CMmsMessage derived class is used.
+3.2.10.2.3 MMS Watcher
+3.2.10.2.3.1 Key External Relationships and Dependencies
+
+Figure 23 MMS Watcher External Dependencies
+
+The MMS watcher plug-in is responsible for intercepting incoming MMS notifications and delivery reports then taking the appropriate action. It is implemented as a WAP Push watcher plug-in.
+When an MMS notification is received an MMS entry is created in the inbox using the MMS utilities. At this point the entry has its incomplete flag set. If the settings have the autofetch option selected then the MMS watcher initiates the fetch operation via the MMS client MTM.
+If a delivery report is received then the delivered flag is set on the appropriate sent message. If an outgoing message was sent to several recipients then there will be several delivered flags. A delivery report from each recipient will set the appropriate delivered flag.
+3.2.10.2.4 MMS Client MTM
+3.2.10.2.4.1 Key External Relationships and Dependencies
+
+Figure 24 MMS Client MTM Dependencies
+As with most other MTMs the MMS client MTM provides access to the server MTM functionality for messaging clients. It also implements the Send-As interface and reply and forward functionality.
+3.2.10.2.4.2 Send-As Implementation
+The Client MTM Send-As interface is implemented in the MMS Client MTM. The implementation differs slightly from other MTMs because additional presentation content may be generated depending on the media objects that are added. When simple combinations of images, sounds and text are added a SMIL presentation is generated to link them together. This is preferable to simple adding the objects as attachments where some clients render them as a list of files and others fail to render them at all.
+The SMIL data is constructed using templates stored in resource files, the GMXML (SMIL) composer is not used.
+3.2.10.2.4.3 Reply / Forward
+The Client MTM can be used to create replies to received messages or to create forwarded responses. The reply and forwarding operations are performed asynchronously.
+3.2.10.2.5 MMS Server MTM
+3.2.10.2.5.1 Key External Relationships and Dependencies
+
+Figure 25 MMS Server MTM Dependencies
+The Server MTM is the most complicated part the MMS implementation. It handles all of the state information required to send or fetch MMS messages. It is also responsible for managing the HTTP or WSP session and the connections to the phone network.
+3.2.10.2.5.2 Operations
+All MMS server MTM functionality is encapsulated in operations. An operation consists of the setup of a session, the sending, fetching and acknowledgements when appropriate, it then closes the session. The messaging client initiates an operation with a single call to the Client MTM, there is no need for the messaging client to explicitly establish the session or to know about the internal states. However, these internal states are available to the messaging client via the progress structure if this level of user feedback is required.
+Two types of operation are supported, background and foreground:
+A maximum of one foreground operation can be running at any one time. The messaging client can poll the server MTM for the progress of a running foreground operation, likewise it can cancel it if necessary.
+A background operation does not support progress information and can not be cancelled by the messaging client. It is possible to initiate background operations even if other background or foreground operations are pending. However, background operations are queued and a maximum of one will actually be running at any one time.
+The MMS watcher uses a background operation to perform automatic fetching. While the background autofetch is occurring it is still possible to start a foreground operation (such as sending a message) if required.
+3.2.10.2.5.3 Session and Connection Management
+The server MTM uses the HTTP Transport Framework to enable the HTTP or WSP session. HTTP or WSP can be selected at runtime by selecting the appropriate option in the settings. The server MTM is responsible for reading any HTTP proxy details from the CommDB and passing it to the HTTP framework. See the http transport framework architectural description for more information on recognisers [R5]
+The server MTM is also responsible for managing the connection to the phone network. Connections are opened when required using the RConnection mechanism, multi-homing is supported provided that the underlying HTTP framework transport plug-in also supports it.
+3.2.10.2.6 MMS Codec
+The MMS Server MTM is in charge of the state transitions, connection, session, the actual posting and fetching of the data from them, however it does not encode or decode the MMS PDUs. The encoding and decoding is performed by the MMS Codec.
+For decoding the Server MTM passes the Codec the MMS PDU data in a descriptor for processing. If the PDU contains a received MMS message then the message entry is updated with the decoded MMS data.
+For encoding the Server MTM passes a reference to the message store entry containing the un-encoded MMS data. The Codec then encodes it and returns the PDU to the Server MTM in a descriptor.
+
+
+3.2.11 Messaging / BIO APIs
+3.2.11.1 Key Internal Relationships and Dependencies
+
+Figure 26 BIO Message Internal Dependencies
+3.2.11.1.1.1 Key External Relationships and Dependencies
+
+Figure 27 Bio Parser External Dependencies
+
+3.2.11.2 API Purpose - Further Elaboration
+3.2.11.2.1 BIO Overview
+The BIO messaging components have been designed to unify and simplify the way in which system messages are processed. In this context ‘system messages’ refers to messages received on the device which are intended to update some attribute(s) on the system as opposed to being presented to the user. Examples of these types of messages include vCards which are parsed and then displayed to the user and when accepted modify the users contact database and OTA configuration messages which are again parsed before display to the user and if accepted create email accounts or internet access points.
+The BIO messaging components can be broken down into three groups:
+1) The BIO MTM - To initiate the parsing and processing of BIO messages
+2) The BIO Database - Maps port numbers, MIME types, etc. to bio types in order to identify the type of incoming BIO messages.
+3) The BIO Parsers - To parse and process the BIO message payload
+BIO messages are not receive by the bio messaging framework, they come over other message transports for example see section 3.2.6.3.1 on the SMS watchers which describes how the SMS watchers receive bio messages and use the bio framework to tag the messages with the correct bio id.
+3.2.11.2.2 BIO MTM
+The BIO client MTM is called by the messaging client to parse or process a BIO message that has been saved in the message store. It is the responsibility of a BIO watcher to save the BIO message with the BIO flag and the appropriate BIO type set.
+The BIO client MTM does very little, its primary task is to pass on the messaging client request to the server MTM. Two operations are supported, parse and process.
+The messaging client is expected to initiate the parsing of the BIO message before processing it. The parsing step involves analysing the data and storing it in a form that can be displayed to the user via the BIO message viewer.
+Once the message has been parsed the messaging client can initiate the processing of the message.
+The BIO server MTM is responsible for deferring the parsing and processing to the appropriate BIO parser. The behaviour for the parsing and processing steps varies between parsers. See the BIO Parsers section for more information.
+The bio MTM does not support sending messages and therefore does not support reply / forwarding messages. For bio messages sending / reply etc. is supported by the particular MTM that the message is sent over, for example SMS.
+3.2.11.2.3 BIO Database
+The BIO database is used to identify the type of BIO messages. It maps message attributes such as port number, MIME type or leading string to a BIO type. These are attributes are then used by clients of the bio framework to know what ports to listen for messages on. For example the SMS watchers use the leading string to wait for SMS messages that start with that string and when storing those messages in the inbox tag them with the bio id associated with that leading string. See the SMS watcher section 3.2.6.3.1 for more examples of how the BIO database can be used.
+3.2.11.2.4 BIO Parsers
+The BIO parsers are plug-ins for parsing and processing incoming BIO messages. They are invoked by the BIO Server MTM depending on the BIO type of the message being processed. Each BIO parser implements two functions, ParseL and ProcessL. The level of functionality varies between parsers. Some parsers update the final repository with the received data, e.g. WAPP updates the CommDB with the received settings. Some parsers simply save the data in an unparsed state for processing by another component, this secondary parsing is not part of the BIO framework and must be initiated by the messaging client. An example is when GFP saves vCard data as a file as opposed to updating the contacts database, the UI must then invoke the Versit parser to parse the vCard and commit it to the contacts database.
+3.2.11.2.4.1 Generic File Parser (GFP)
+The generic file parser can be used to identify and save a variety of BIO data types, e.g. vCards and vCals. The Generic File Parser does not process the data, it simply saves it in the message store for processing by another component. The file is saved as an attachment of the message entry that was parsed.
+3.2.11.2.4.2 Nokia/Ericsson OTA Parser (WAPP)
+The WAPP parser decodes Nokia/Ericsson OTA messages and updates CommDB to reflect the received settings.
+3.2.11.2.4.3 Nokia Smart Message Internet Access Parser (IACP)
+The IACP parser decodes Nokia Smart Messages and updates the CommDB and messaging settings where appropriate.
+3.2.11.2.5 BIF Files and Utilities
+The BIF files encapsulate the information required for identifying BIO messages, these details may include the expected port number, MIME type or leading string. Different BIO watcher will use different information from these files, for an example see the 3.2.6.3.1. The information can be retrieved from the BIF files by using the BIF utilities. Generally BIO aware clients will access this information via the BIO database. BIF files are resource files previous to the v6.1 release they were binary files generated by biftool.exe.
+3.2.11.2.6 Platform Security Compliant Messaging / BIO APIs
+In the platform security model the BIO parsers are run in the client space rather than in the message server space, as is done in the non-platform secure model. If the BIO parsers are run in the message server space, it allows a client process to gain the capabilities of the message server. IPC policing can protect the message server from this.
+Also, for the message server to be able to load any BIO parser it would need more capabilities than it really requires. By running the BIO parsers in the client space, both these issues are solved. The client process must be trusted with the necessary capabilities to run the specified BIO parser.
+The BIO registry files are located in the \resource\messaging\bif read-only directory. All BIO parser DLLs are located in the \sys\bin protected directory.
+
+Figure 26 BIO Message Dependencies (v9.0)
+The BIO client MTM is responsible for loading the BIO database and BIO utilities to handle parse/process requests from clients.
+The BIO registry files no longer identify the BIO parsers DLLs via their UID – the registry file must use the BIO parser DLL name to identify them.
+3.2.12 Messaging / OBEX MTM APIs
+3.2.12.1 Key Internal Relationships and Dependencies
+
+Figure 28 OBEX Internal Dependencies
+3.2.12.2 OBEX MTM Overview
+The OBEX MTM offers simple IR and Bluetooth beaming functionality. It provides an API that is consistent with other MTMs so that the underlying OBEX APIs do not need to be used directly for beaming applications. The OBEX MTM does not provide OBEX receiving functionality, in order to receive OBEX data the underlying OBEX APIs must be used directly.
+3.2.12.2.1 OBEX MTM
+The OBEX MTM is split into three parts. OBEX MTM DLLs, IR MTM DLLs and Bluetooth MTM DLLs. The OBEX MTM DLLs can not be used on their own they provide the base OBEX MTM functionality for the derived IR and Bluetooth MTMs.
+There are two APIs that can be used to create OBEX messages:
+1) The Send-As API
+2) Linked attachments by filename
+The Send-As API provides an interface consistent with other MTMs, however it requires all attachments to be copied into the message store before they can be sent, this is often undesirable for beaming applications because it is wastes disk space. For this reason a second API is provided that allows attachments to be linked to outgoing messages by filename, when this API is used there is no need to copy the attachments to the message store.
+Unlike many other MTMs after OBEX tries to send a message it is deleted from the outbox whether the sending succeeds or fails.
+3.2.12.2.1.1 OBEX MTM Key External Dependencies
+
+Figure 29 OBEX External Dependencies
+3.2.12.2.2 IR MTM
+The bulk of the OBEX MTM functionality is provided by the OBEX MTM DLLs, the IR MTM itself just sets up the parameters.
+3.2.12.2.2.1 IR MTM Key External Dependencies
+
+Figure 30 IR MTM Dependencies
+3.2.12.2.3 Bluetooth MTM
+The bulk of the OBEX MTM functionality is provided by the OBEX MTM DLLs, the Bluetooth MTM just subclasses from the OBEX MTM and sets up Bluetooth specific parameters.
+3.2.12.2.3.1 Bluetooth MTM Key External Dependencies
+
+Figure 31 Bluetooth MTM Dependencies
+3.2.12.2.4 OBEX MTM Utils
+The OBEX MTM Utils provide utility functionality used by the other OBEX MTM DLLs. The two main areas of functionality provided by this component are:
+1) Filename linking functionality
+2) Bluetooth SDP lookup
+The filename linking functionality is provided in the utilities because linked files must be added by the client side during message creation and need to be read on the server side during sending.
+
+3.2.12.2.5 Platform Security Compliant Messaging / OBEX MTM APIs
+From v9.0 and onwards the service settings of all the derived OBEX MTMs are stored in the Central Repository. The OBEX message is stored in the message store as an attachment – from v9.0 and onwards the Attachment API is used to attach the OBEX message.
+
+3.2.13 Messaging / GMXML APIs
+3.2.13.1 Key Relationships and Dependencies
+
+Figure 32 GMXML Dependencies
+3.2.13.2 Overview
+The GMXML component provides simple XML DOM parsing and validation functionality. It is intended for parsing XML that might be needed in messaging applications, specifically SMIL parsing for MMS rendering. It is not a general purpose XML parser and will not be suitable for some applications, e.g. browsing.
+3.2.13.2.1 GMXML DOM
+The DOM implementation is fit for purpose for SMIL rendering but differs from the standard DOM design in several respects, e.g. attributes are not stored as discrete nodes, for performance reasons they are stored with the element.
+The DOM tree classes are all derived from nodes. Implemented node types include elements, text and comments. The type of each element is stored as a descriptor as opposed to an enum. This is less efficient than storing it as an enum but provides maximum flexibility when dealing with unknown element types.
+Nodes are linked together in a tree structure as might be expected in a DOM implementation. The tree structure exists on the heap.
+3.2.13.2.2 GMXML Parser and Composer
+3.2.13.2.2.1 Parser
+The parser takes XML input from a buffer or file and creates the corresponding DOM structure on the heap.
+The parser is capable of performing some basic validation. In order to validate against a DTD a class that implements the GMXML DTD interface is required. The DTD interface specifies several functions that provide the required validation, e.g. one of the functions determines if a given attribute is valid for a given element. An instance of the DTD class should be passed into the parser when validation is required but can be omitted if no validation is needed.
+3.2.13.2.2.2 Composer
+The composer takes a DOM tree and generates XML output from it. The XML output is written to a file.
+3.2.13.2.3 GMXML SMIL DTD (Validator)
+The SMIL DTD validator class is an implementation of the DTD validator interface. It implements several simple functions that provide the information required to validate SMIL data. An instance of the SMIL DTD validator should be passed into the parser if SMIL validation is required.
+4 Security
+4.1 Data caging
+For data storage in the pre-platform security compliant architecture, refer to section [3.2.1.3.2]
+For the data caging in the platform security compliant architecture of v9.0 and onwards, refer to section [3.2.1.3.3]
+4.2 Backup and restore
+The message server registers the index file with the backup server. When informed about a backup/restore it releases the index file, sending events to messaging clients informing them that the message store is unavailable. When informed it can open the index file again, it checks the time stamp on the index file; if it has changed since the file was released it reloads the index file. If the newly restored index file is found to be corrupt it is deleted and a new message store is created. See the section on page 14 for details on how the message server handles corrupt stores. The client performing the restore should always wipe the existing message store before starting to copy the message store from the backup to the device.
+4.3 Capability ranges
+In the platform security compliant architecture of v9.0 and onwards, the capabilities allocated to messaging sub-systems are as listed in following table.
+4.3.1 Capabilities granted to executables
+The following table lists the executables and their capabilities and also gives a basic example for having the required capability.
+
+Executable Capability Rationale (basic example of capability requirement)
+msexe.exe ProtServ ProtServ is required to allow the msexe.exe to start a protected server. This stops processes without ProtServ from starting a server pretending to be the message server
+ ReadDeviceData ReadDeviceData is needed to able to read service settings
+ WriteDeviceData WriteDeviceData is needed to able to write service settings
+ NetworkServices NetworkServices capability is needed to access network transports (SMS, POP3, SMTP, IMAP4).
+ LocalServices LocalServices is needed to be able to access IR and Bluetooth
+ ReadUserData ReadUserData is needed to be able to read user data (e.g. service settings).
+watcher.exe ReadDeviceData ReadDeviceData is needed to able to read service settings
+ WriteDeviceData WriteDeviceData is needed to able to write service settings
+ NetworkServices NetworkServices capability is needed to access network transports (SMS).
+ LocalServices LocalServices capability is needed for the plug-ins to access IR and Bluetooth
+ ReadUserData ReadUserData is needed to be able to read user data
+ WriteUserData WriteUserData is needed to be able to write user data
+autosend.exe ReadUserData ReadUserData capability is needed to be able to read data from Outbox and SMTP server MTM.
+ WriteUserData WriteUserData capability is needed to be able to write data in Outbox and SMTP server MTM.
+ NetworkServices NetworkServices capability is needed to access network transports (SMS, POP3, SMTP, and IMAP4).
+ LocalServices LocalServices capability is needed to access the IR and Bluetooth
+SchSend.exe ReadDeviceData ReadDeviceData is needed to able to read settings data
+ NetworkServices NetworkServices capability is needed to access the network transports (SMS, POP3, SMTP, and IMAP4).
+ LocalServices LocalServices is needed to be trusted by other MTM
+ ReadUserData ReadUserData is needed to be able to read user data.
+ WriteUserData WriteUserData is needed to be able to write user data.
+SendAs.exe ReadDeviceData ReadUserData is needed to be able to read data in Outbox.
+ WriteDeviceData WriteUserData is needed to be able to write data in Outbox.
+ NetworkServices NetworkServices capability is needed to access the network transports (SMS, POP3, SMTP, and IMAP4).
+ LocalServices LocalServices is needed to be able to access IR and Bluetooth
+
+4.3.2 Capabilities granted to DLLs
+The assigned Platform Security attributes for DLLs within messaging are outlined in the following table.
+DLL Capability
+bifu.dll All –TCB
+bioc.dll All –TCB
+biodb.dll All –TCB
+bios.dll All –TCB
+biowatcher.dll same as watcher.exe
+biut.dll All –TCB
+cbcp.dll All –TCB
+enp.dll All –TCB
+gfp.dll All –TCB
+iacp.dll All –TCB
+nbswatcher.dll same as watcher.exe
+cdmanbswatcher.dll same as watcher.exe
+CdmaSocketWatcher.dll same as watcher.exe
+VMNWatcher.dll same as watcher.exe
+WEMTWatcher.dll same as watcher.exe
+WMTWatcher.dll same as watcher.exe
+WPTWatcher.dll same as watcher.exe
+wapp.dll All –TCB
+wapwatcher.dll same as watcher.exe
+smildtd.dll All –TCB
+xmldom.dll All –TCB
+xmlparser.dll All –TCB
+smiltranslator.dll All –TCB
+imcm.dll All –TCB
+imps.dll same as msexe.exe
+imut.dll All –TCB
+msgs.dll All –TCB
+msgurlrec.mdl same as AppArc.exe (once it exists; eiksrv in meantime)
+mtur.dll All –TCB
+pops.dll same as msexe.exe
+schsend.dll All –TCB
+send.dll All –TCB
+smcm.dll All –TCB
+smcm_gsm.dll Synonym for smcm.dll
+smcm_cdma.dll Synonym for smcm.dll
+smss.dll same as msexe.exe
+smss_gsm.dll Synonym for smss.dll
+smss_cdma.dll Synonym for smss.dll
+smts.dll same as msexe.exe
+btcmtm.dll All –TCB
+btsmtm.dll same as msexe.exe
+irc.dll All –TCB
+irs.dll same as msexe.exe
+obexclientmtm.dll All –TCB
+obexmtmutil.dll All –TCB
+obexservermtm.dll same as msexe.exe
+
+The reason for setting a high capability to the DLLs is to make it possible for almost anyone to link to them. Although a DLL may have capabilities ALL-TCB (All minus TCB), its real capability is limited by the process which loads the DLL.
+4.3.3 Capabilities required to use the subsystem
+The message subsystem needs to be protected against malicious clients. The following table shows the key capabilities required to do related activities in different components.
+
+Component Related Activity Required Capability and SID
+Message server Create message in local folder No capability required
+ Create message in Outbox ReadUserData, WriteUserData and MTM specific capabilities
+ Access client MTM ReadUserData, WriteUserData and MTM specific capabilities
+Watcher Allow plug-ins to wait on events (e.g. arrival of SMS) Watcher always polices if the client capabilities are trusted by the watcher framework, else it will not be loaded
+Plug-ins or clients using watcher need the same capabilities as watcher.exe to be able to be loaded by watcher.
+Autosend Send messages in background NetworkService or LocalService required by the message type
+SchSend Scheduling of operations (e.g. sending SMS) SchSend always polices to see if the process was started by the Task Scheduler – if not the process terminates without performing any of the scheduled tasks. Also, the SchSend verifies that only itself and the message server created the scheduled tasks. If this is not the case, SchSend does not performing the scheduled tasks.
+SendAs Create message Draft, move it to Outbox, and send message WriteDeviceData or WriteUserData and other capability required by the message type
+
+5 Further Information
+5.1 References
+No. Document Reference Version Description
+R1 messaging_functional_specification.doc 0.6 Messaging Functional description
+R2 SGL.GT0143.161_App-Framework_Architectural_Description.doc 1.0 App-Framework Architectural Description
+R3 NBProtocols_Subsystem_Architectural_Description.doc 0.2 NBProtocols Architectural Description
+R4 WAP-stack_architectural_analysis.doc 1.0 WAP stack architectural analysis
+R5 HTTP Transport Framework Architectural Description.doc 1.1 HTTP Transport Framework 1.1 Architectural Description
+5.2 Open Issues
+The following issues need to be resolved before this document is completed:
+1. Top-level architecture diagram showing the framework and plug-ins should be added to overview section.
+2. Message store section should talk about removable media.
+3. Define "Message Server Client API" and "Messaging Client API" in the glossary, and ensure it is consistently used in the diagrams
+4. Add a sequence diagram for receiving a vCard over SMS and integrating it into contacts
+5. Add a sequence diagram for sending an SMS
+6. Add a sequence diagram for synchronising a POP3 mail box
+7. Add a sequence diagram for connecting to an IMAP4 mail box and downloading a message
+8. Capability table should be updated after the implementation of server e.g. message server
+9. Sequence diagram may need to be changed to show secured platform operation
+10. In section [3.1.1.4] the server SendAsV2 to find a correct name
+11. Section 3.2.1.3.3.1 Data Caging file 'Mtm Registry v2'may need a correct name
+12. Breakdown diagram showing all DLL, exes, apps in the messaging subsystem for both the pre-v8.0 and post v9.0 in section[3.2]
+13. Needs to say more about how the capabilities are policed and the algorithms used for different operations
+14. The dependecy between the message server and the central repository need to be listed in the email, SMS and OBEX diagrams (e.g. message store)
+15. Section 3.2.1.2 - figure 3 - Central Repository also get used by the Message server, or server MTMs (e.g. POP3), to retrieve account settings the path, required DLL and description are not given
+16. Section 4.3.3 title can be Police requirement of the sub-system, add extra column for SID in the table and list the use of SID. For example SchSend checks for Task Scheduler SID
+
+
+5.3 Glossary
+The following technical terms and abbreviations are used within this document.
+Term Definition
+BIO
+Bearer Independent Object Smart messages e.g. vCards, vCals, and WAP provisioning messages. These can currently be received via the WAP stack, SMS stack, Bluetooth or Infrared.
+BIO Type UID that represents the content type of a BIO Message.
+Message Centre Application that displays list views of messages to the user, allowing the user to perform operations such as copying messages, sending messages creating new messages etc.
+Message Viewer Application for viewing a message.
+Message Editor Application for creating or editing a message
+Message Server Symbian OS Server that handles request to modify the Message Store
+Message Store Store of messages and related information kept in the file system on a Symbian OS device.
+Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
+Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
+Global Inbox A standard folder under the local service which is used to store incoming messages like SMS MMS etc. as opposed to an IMAP4 Inbox which would be under an IMAP4 service and is a representation of the Inbox on an IMAP4 email server.
+Central Repository centralised and secure storage facility for application settings
+OBEX Object exchange protocol, used to send objects such as vCards or files between devices via infrared or Bluetooth.
+GMXML XML parser / generator for use with SMIL formatted messages.
+UID Unique Identifier, a 32 bit number allocated from a registry owned by Symbian
+IPC Inter Process Communication
+MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
MTM Registry A list of currently installed MTMs maintained by the message server.
TLS Transport Layer Security, provides encryption of a TCP/IP socket.
M-HTML Standard for including HTML in MIME email messages see http://www.ietf.org/rfc/rfc2557.txt
@@ -39639,15 +36585,15 @@
Message Editor Application for creating or editing a message
Message Server Symbian OS Server that handles request to modify the Message Store
Message Store Store of messages and related information kept in the file system on a Symbian OS device.
-Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
-Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
+Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
+Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
Global Inbox A standard folder under the local service which is used to store incoming messages like SMS MMS etc. as opposed to an IMAP4 Inbox which would be under an IMAP4 service and is a representation of the Inbox on an IMAP4 email server.
Central Repository centralised and secure storage facility for application settings
OBEX Object exchange protocol, used to send objects such as vCards or files between devices via infrared or Bluetooth.
GMXML XML parser / generator for use with SMIL formatted messages.
UID Unique Identifier, a 32 bit number allocated from a registry owned by Symbian
IPC Inter Process Communication
-MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
+MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
MTM Registry A list of currently installed MTMs maintained by the message server.
TLS Transport Layer Security, provides encryption of a TCP/IP socket.
M-HTML Standard for including HTML in MIME email messages see http://www.ietf.org/rfc/rfc2557.txt
@@ -40657,15 +37603,15 @@
Message Editor Application for creating or editing a message
Message Server Symbian OS Server that handles request to modify the Message Store
Message Store Store of messages and related information kept in the file system on a Symbian OS device.
-Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
-Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
+Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
+Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
Global Inbox A standard folder under the local service which is used to store incoming messages like SMS MMS etc. as opposed to an IMAP4 Inbox which would be under an IMAP4 service and is a representation of the Inbox on an IMAP4 email server.
Central Repository centralised and secure storage facility for application settings
OBEX Object exchange protocol, used to send objects such as vCards or files between devices via infrared or Bluetooth.
GMXML XML parser / generator for use with SMIL formatted messages.
UID Unique Identifier, a 32 bit number allocated from a registry owned by Symbian
IPC Inter Process Communication
-MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
+MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
MTM Registry A list of currently installed MTMs maintained by the message server.
TLS Transport Layer Security, provides encryption of a TCP/IP socket.
M-HTML Standard for including HTML in MIME email messages see http://www.ietf.org/rfc/rfc2557.txt
@@ -41675,15 +38621,1033 @@
Message Editor Application for creating or editing a message
Message Server Symbian OS Server that handles request to modify the Message Store
Message Store Store of messages and related information kept in the file system on a Symbian OS device.
-Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
-Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
+Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
+Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
Global Inbox A standard folder under the local service which is used to store incoming messages like SMS MMS etc. as opposed to an IMAP4 Inbox which would be under an IMAP4 service and is a representation of the Inbox on an IMAP4 email server.
Central Repository centralised and secure storage facility for application settings
OBEX Object exchange protocol, used to send objects such as vCards or files between devices via infrared or Bluetooth.
GMXML XML parser / generator for use with SMIL formatted messages.
UID Unique Identifier, a 32 bit number allocated from a registry owned by Symbian
IPC Inter Process Communication
-MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
+MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
+MTM Registry A list of currently installed MTMs maintained by the message server.
+TLS Transport Layer Security, provides encryption of a TCP/IP socket.
+M-HTML Standard for including HTML in MIME email messages see http://www.ietf.org/rfc/rfc2557.txt
+MIME Specification for the format of email message bodies see http://www.ietf.org/rfc/rfc1341.txt
+RFC2822 The standard format for internet mail messages see http://www.ietf.org/rfc/rfc0822.txt
+SMTP Simple Mail Transport Protocol
+SID Secure Identification
+IMAP4 Internet Mail Access Protocol
+POP3 Post Office Protocol Version 3
+NBS Narrow Band Socket, in the messaging context this refers to the socket that is used to talk to the SMS stack for receiving and sending SMS messages
+SMS Short Message Service
+MMS Multimedia Message Service
+WAP Wireless Application Protocol
+WSP WAP Session Protocol
+HTTP Hypertext transfer protocol
+PDU Protocol Data Unit. This is the encoded form of SMS and MMS messages.
+Versit A consortium that defined standard formats for things like contacts (vCard) and calendar entries (vCals)
+SDP Service Discovery Protocol. A Bluetooth protocol that allows an applications to discover which services are available and to determine the characteristics of the services.
+SMIL Synchronized Multimedia Integration Language. Presentation language that is commonly used to define the contents of an MMS message.
+XML Extensible Mark-up Language
+DOM Document Object Model
+DTD Document Type Definition, a schema that defines the structure of an XML document.
+ESTORE Symbian OS component that provides stream based storage. Messaging uses the Permanent file store provided by ESTORE to store its index entries.
+Appendix A - Example Sequence Diagrams
+A.1 Copy to a Remote Service
+
+Figure 33 Sequence Diagram Showing Copying to a Remote Service
+Figure 33 shows a client copying a message to a remote service using the Messaging Client API. The message server then delegates the copy to the SMTP Server MTM. The Server MTM interprets the request as a request to send the message so it opens a connection to a remote SMTP server and sends the message. While the message is being sent the client can retrieve progress information from the CMsvOperation object that was returned by CMsvEntry::CopyL. The dark grey IPC line represents the split between the objects running in the client’s process space on the left and the message server’s process on the right.
+There are four basic steps:
+1. The client opens session with Message Server and creates a CMsvEntry set on the global outbox,
+2. The client then requests an asynchronous copy from the outbox to the SMTP service, a CMsvOperation object is returned. The message server loads the SMTP Server MTM and delegates the copy operation to it.
+3. The client requests progress from the CMsvOperation object, this request is passed through to the SMTP Server MTM. The client may repeat this step multiple times.
+4. The Server MTM finishes sending message. It moves the message to sent folder and completes the message server’s request. The message server completes the CMsvOperation object, which requests the final progress from the message server. The server returns the final progress and deletes the Server MTM. The CMsvOperation then completes the client’s original request.
+This diagram hides all of the internal working of the SMTP Server MTM, for information on this see below.
+A.2 SMTP Session
+
+Figure 34 Sequence Diagram Showing a SMTP Session
+Figure 34 shows the operation of the SMTP Server MTM after a request has come from the message server to copy a message to the SMTP service.
+1. SMTP Server MTM gets the request from the message server, it will build a selection of messages consisting of the union of the selection of messages passed in and the messages in the outbox that are associated with this SMTP service and are ready to be sent. The chain of classes are constructed, and a request is passed to networking to connect to the remote SMTP server, details of the server name and port are retrieved from the settings stored in the SMTP service entry.
+2. The component waits for the SMTP server to respond with a greeting indicating it is willing to talk, then sends EHLO to the server and waits for the response detailing the capabilities of the Server. After this step there could set steps to start using TLS and or SMTP AUTH depending on the SMTP settings.
+3. CImSmtpSession calls back into CMsgOutboxSend to retrieve the next message to be sent, then constructs a CImSmtpFile object to handle sending, for details on the sending see SMTP Email Send. When sending the email has completed the CImSmtpFile object is deleted.
+4. CImSmtpSession calls back into CMsgOutboxSend to retrieve the next message which returns saying there are no more messages. CImSmtpSession sends QUIT to the SMTP server and completes CMsgOutboxSend. CMsgOutboxSend deletes CImSmtpSession which tears down the connection to the SMTP server; it then completes the SMTP Server MTM. The Server MTM will then complete the message server and be deleted.
+A.3 SMTP Email Send
+
+Figure 35 Sequence Diagram Showing SMTP Transactions during Email Send.
+Figure 35 shows a CImSmtpFile object sending an email message to an SMTP server.
+1. Construct a CImSendMessage object, part of the imut component. Reset the SMTP Server
+2. Read address information from the CImHeader object stored in the message store, send address information to SMTP server.
+3. Use CImSendMessage object to read the message from the message store and generate RFC2822 message line by line. Send each line to the server as it is generated.
+4. Complete and send the message by sending a full stop to the SMTP server
+
+
+
+
+Messaging Symbian OS v7.0s, v8.0, v8.1, v9.0, v9.1 Architectural Description
+
+Status: Issued
+Team/Department : Messaging / Content & Messaging
+
+Contents
+1 INTRODUCTION 6
+1.1 PURPOSE AND SCOPE 6
+2 SUBSYSTEM OVERVIEW AND BACKGROUND 6
+3 MESSAGING ARCHITECTURE AND APIS 7
+3.1 SUBSYSTEM COMPONENTS 7
+3.1.1 Framework components 7
+3.1.1.1 Message Server and MTM architecture 7
+3.1.1.2 Schedule Send 7
+3.1.1.3 SendAs Version 1 7
+3.1.1.4 SendAs Version 2 7
+3.1.1.5 Watcher Framework 8
+3.1.1.6 Message URL Handler 8
+3.1.1.7 Bio Message Framework 8
+3.1.2 Plug-ins 8
+3.1.2.1 SMS 8
+3.1.2.2 CDMA SMS 8
+3.1.2.3 Email 9
+3.1.2.4 OBEX 9
+3.1.2.5 MMS 9
+3.1.2.6 GMXML 10
+3.1.2.7 Bio Message Plug-ins 10
+3.1.2.8 PCMTM 10
+3.1.2.9 Fax 10
+3.2 GENERAL DESCRIPTION 11
+3.2.1 Messaging / Message Server and MTM Architecture APIs 11
+3.2.1.1 Key Internal Relationships and Dependencies 11
+3.2.1.2 Key External Relationships and Dependencies 12
+3.2.1.3 API Purpose - Further Elaboration 13
+3.2.1.3.1 Message Store 13
+3.2.1.3.2 Data File Storage (pre - v9.0) 15
+3.2.1.3.3 Platform Security Compliant Message Store 16
+3.2.1.3.4 How message centres display the message store 17
+3.2.1.3.5 Message Type Module Architecture 19
+3.2.1.3.6 Message Server Client API 21
+3.2.2 Messaging / Send As APIs 22
+3.2.2.1 Key Relationships and Dependencies 22
+3.2.2.2 API Purpose - Further Elaboration 22
+3.2.2.2.1 SendAs API (pre – v9.0) 22
+3.2.3 Platform Security Compliant SendAs Server (v9.0 onwards) 23
+3.2.4 Messaging / Schedule Send APIs 24
+3.2.4.1 Key Relationships and Dependencies 24
+3.2.4.2 API Purpose - Further Elaboration 24
+3.2.4.2.1 Schedule Send 24
+3.2.5 Messaging / Watchers APIs 25
+3.2.5.1 Key Relationships and Dependencies 25
+3.2.5.2 API Purpose - Further Elaboration 25
+3.2.6 Messaging / Message URL Handler APIs 26
+3.2.6.1 Key Relationships and Dependencies 26
+3.2.6.2 API Purpose - Further Elaboration 26
+3.2.6.2.1 Message URL Handler Application 26
+3.2.6.2.2 Message URL Recognisers 27
+3.2.7 Messaging / SMS APIs 27
+3.2.7.1 Key Internal Relationships and Dependencies 27
+3.2.7.2 Key External Relationships and Dependencies 28
+3.2.7.3 API Purpose - Further Elaboration 28
+3.2.7.3.1 SMS Watchers 28
+3.2.7.3.2 SMS Client MTM 29
+3.2.7.3.3 SMS Utilities 29
+3.2.7.3.4 SMS Server MTM 30
+3.2.8 Messaging / CDMA SMS APIs 31
+3.2.8.1 Key Internal Relationships and Dependencies 31
+3.2.8.2 Key External Relationships and Dependencies 32
+3.2.8.3 API Purpose - Further Elaboration 32
+3.2.8.3.1 CDMA SMS Watchers 32
+3.2.8.3.2 CDMA SMS Client MTM 33
+3.2.8.3.3 CDMA SMS Utilities 33
+3.2.8.3.4 CDMA SMS Server MTM 33
+3.2.8.3.5 Configuration for using CDMA SMS MTM 34
+3.2.9 Messaging / Email APIs 35
+3.2.9.1 Key Internal Relationships and Dependencies 35
+3.2.9.2 Key External Relationships and Dependencies 36
+3.2.9.3 API Purpose - Further Elaboration 36
+3.2.9.3.1 Email Overview 36
+3.2.9.3.2 Email Client Utilities 37
+3.2.9.3.3 Email Server MTM Utilities 37
+3.2.9.3.4 POP3 MTMs 37
+3.2.9.3.5 IMAP4 MTMs 38
+3.2.9.3.6 SMTP MTMs 40
+3.2.9.3.7 Autosend 40
+3.2.10 Messaging / MMS APIs 40
+3.2.10.1 Key Internal Relationships and Dependencies 41
+3.2.10.2 API Purpose - Further Elaboration 41
+3.2.10.2.1 MMS Overview 41
+3.2.10.2.2 MMS Utilities 42
+3.2.10.2.3 MMS Watcher 43
+3.2.10.2.4 MMS Client MTM 43
+3.2.10.2.5 MMS Server MTM 44
+3.2.10.2.6 MMS Codec 45
+3.2.11 Messaging / BIO APIs 46
+3.2.11.1 Key Internal Relationships and Dependencies 46
+3.2.11.2 API Purpose - Further Elaboration 47
+3.2.11.2.1 BIO Overview 47
+3.2.11.2.2 BIO MTM 47
+3.2.11.2.3 BIO Database 48
+3.2.11.2.4 BIO Parsers 48
+3.2.11.2.5 BIF Files and Utilities 48
+3.2.11.2.6 Platform Security Compliant Messaging / BIO APIs 49
+3.2.12 Messaging / OBEX MTM APIs 50
+3.2.12.1 Key Internal Relationships and Dependencies 50
+3.2.12.2 OBEX MTM Overview 50
+3.2.12.2.1 OBEX MTM 50
+3.2.12.2.2 IR MTM 51
+3.2.12.2.3 Bluetooth MTM 51
+3.2.12.2.4 OBEX MTM Utils 52
+3.2.12.2.5 Platform Security Compliant Messaging / OBEX MTM APIs 52
+3.2.13 Messaging / GMXML APIs 52
+3.2.13.1 Key Relationships and Dependencies 52
+3.2.13.2 Overview 53
+3.2.13.2.1 GMXML DOM 53
+3.2.13.2.2 GMXML Parser and Composer 53
+3.2.13.2.3 GMXML SMIL DTD (Validator) 53
+4 SECURITY 54
+4.1 DATA CAGING 54
+4.2 BACKUP AND RESTORE 54
+4.3 CAPABILITY RANGES 54
+4.3.1 Capabilities granted to executables 54
+4.3.2 Capabilities granted to DLLs 55
+4.3.3 Capabilities required to use the subsystem 57
+5 FURTHER INFORMATION 59
+5.1 REFERENCES 59
+5.2 OPEN ISSUES 59
+5.3 GLOSSARY 60
+APPENDIX A - EXAMPLE SEQUENCE DIAGRAMS 62
+A.1 COPY TO A REMOTE SERVICE 62
+A.2 SMTP SESSION 64
+A.3 SMTP EMAIL SEND 66
+
+Table of Figures
+Figure 1 Where Messaging Lives 6
+Figure 2 MTM Relationships 11
+Figure 3 External Dependencies 12
+Figure 4 Message Store 13
+Figure 5 Series 60 Inbox List View 14
+Figure 6 Remote and Local Entries 14
+Figure 7 Email Message 15
+Figure 8 Series 60 Message Centre (Composed from 2 screen shots) 17
+Figure 9 UIQ Message Centre 18
+Figure 10 Messaging MTM Structure (light coloured components are part of messaging subsystem) 19
+Figure 11 Nokia 9210 Outbox List View 20
+Figure 12 SendAs Version 1 Dependencies 22
+Figure 13 SendAs Version 2 Dependencies 23
+Figure 14 Schedule Send Dependencies 24
+Figure 15 Watcher Dependencies 25
+Figure 16 Message URL Handler Dependencies 26
+Figure 17 SMS Internal Dependencies 27
+Figure 18 SMS External Dependencies 28
+Figure 19 CMDA SMS Internal Dependencies 31
+Figure 20 CDMA SMS External Dependencies 32
+Figure 19 Email Internal Dependencies 35
+Figure 20 Email External Dependencies 36
+Figure 21 MMS Internal Dependencies 41
+Figure 22 MMS Utilities External Dependencies 42
+Figure 23 MMS Watcher External Dependencies 43
+Figure 24 MMS Client MTM Dependencies 43
+Figure 25 MMS Server MTM Dependencies 44
+Figure 26 BIO Message Internal Dependencies 46
+Figure 27 Bio Parser External Dependencies 47
+Figure 26 BIO Message Dependencies (v9.0) 49
+Figure 28 OBEX Internal Dependencies 50
+Figure 29 OBEX External Dependencies 51
+Figure 30 IR MTM Dependencies 51
+Figure 31 Bluetooth MTM Dependencies 52
+Figure 32 GMXML Dependencies 52
+Figure 33 Sequence Diagram Showing Copying to a Remote Service 62
+Figure 34 Sequence Diagram Showing a SMTP Session 64
+Figure 35 Sequence Diagram Showing SMTP Transactions during Email Send. 66
+1 Introduction
+1.1 Purpose and Scope
+The Messaging Architectural Description details the architecture and APIs exposed by the Messaging Subsystem. This document does not attempt to list all functionality provided by the messaging subsystem. For details on the functionality provided and the specifications implemented by the messaging subsystem see the Messaging Functional Description [R1]. This document describes the general architecture of messaging subsystem. Information related to a particular release version is mentioned with relevant release number.
+2 Subsystem Overview and Background
+The Messaging Subsystem provides an application level API to handle the storage and transport of different message types. It sits between messaging applications and the lower level subsystems which messaging uses for storage and transmission of messages.
+
+Figure 1 Where Messaging Lives
+The message types that messaging currently supports are Email (POP3, IMAP4 & SMTP), SMS, MMS and OBEX. The set of supported message types is extensible at run time by the use of plug-in modules that are responsible for the transmission and storage of a particular message type. This means that the set of components shown communicating with the network cloud depend on the message types installed.
+3 Messaging Architecture and APIs
+3.1 Subsystem components
+The Messaging subsystem components can be split into two categories: those components that form the framework and those that plug into the framework to support specific message types. This section briefly describes each of the components, more detailed descriptions of the components and their dependencies can be found in later sections of this document.
+3.1.1 Framework components
+3.1.1.1 Message Server and MTM architecture
+The message server is the core component in the messaging subsystem. It provides the message store used to contain messages. The Message Type Module architecture also allows plug-ins to add support for new message types to the messaging subsystem.
+Component Description
+messaging\framework\serverexe Executable that links to the server component and starts the message server
+messaging\framework\server Contains classes that make up both the client and server side of the message server API.
+messaging\framework\mtmbase Base classes for the plug-ins that handle the various message types
+3.1.1.2 Schedule Send
+The Schedule Send component is an extension to the framework that provides support for scheduling of operations such as sending messages. Message type modules that wish to support this functionality can use these support components to implement scheduling. For example the SMS MTM uses this to allow scheduled sending of SMS messages.
+Component Description
+messaging\schedulesend\schedulesendmtm Base classes that handle functionality for message server plug-ins that wish to enable scheduling of sending messages.
+messaging\schedulesend\schedulesendexe Executable use to provide schedule send behaviour.
+3.1.1.3 SendAs Version 1
+This version of SendAs is supported in releases pre - v9.0. SendAs provides a high level API for applications that wish to include a “Send As” menu to allow users to send content via one of the message types supported by messaging. The application using the API does not have to be aware of the message type selected by the user. Note the API does not send the messages.
+Component Description
+messaging\sendas High level API to allow creation of messages.
+3.1.1.4 SendAs Version 2
+From v9.0 and onwards the SendAs has been replaced with client server architecture based SendAs server. The client server architecture enhances secured platform implementation. The SendAs server polices the client application. If it is not trusted with required capabilities the SendAs server will refuse the client access. The client MTM for the message type can send a message with user permission even if the client does not have the correct capabilities.
+Component Description
+messaging\sendAsV2 High level API to allow the creation and sending of messages
+
+3.1.1.5 Watcher Framework
+The watcher framework is a lightweight framework to allow plug-ins to wait on events. For example there is an SMS watcher that waits for incoming SMS messages and delivers them to the message store. The watcher framework will only load plug-ins from ROM.
+Component Description
+messaging\framework\watcher Executable that loads and runs watcher plug-ins.
+3.1.1.6 Message URL Handler
+Support for recognising messaging URLs (mailto:, sms:, fax:, mms:), and then launching an editor with a new message.
+Component Description
+messaging\urlhandler\urlhandler An application that parses the URLs and then creates a correctly addressed message and launches a message editor.
+messaging\urlhandler\recogniser Recognisers that map from the URL schemes to the mime types.
+3.1.1.7 Bio Message Framework
+The Bio Message Framework provides a framework that supports plug-ins to handle messages like vCards and Internet access point set-up messages.
+Component Description
+messaging\biomsg\BDB\BIODB Classes to maintain the database of bio registration files.
+messaging\biomsg\BIFU\BIFU Classes for reading and writing bio registration files
+messaging\biomsg\BIOC\BIOC Bio message client MTM, this is in the framework section as it forms part of the bio messaging framework it is also a plug-in to the messaging framework.
+messaging\biomsg\BIOS\BIOS Bio message server MTM, this is in the framework section as it forms part of the bio messaging framework it is also a plug-in to the messaging framework.
+3.1.2 Plug-ins
+3.1.2.1 SMS
+The SMS plug-ins provide application level support for the Short Message Service messages.
+Component Description
+messaging\biomsg\BioWatchers Plug-ins to the watcher framework to listen for SMS, WSP, and WDP messages and deliver them to the global inbox in the message store.
+messaging\sms\clientmtm A plug-in to the message server framework to provide a generic API for creation of SMS messages (SMS Client MTM & SMS utilities)
+messaging\sms\servermtm A plug-in to the message server framework to provide a generic API for sending of SMS messages (SMS Server MTM)
+3.1.2.2 CDMA SMS
+The CDMA SMS plug-ins provide application level support for the CDMA Short Message Service messages.
+Component Description
+messaging\biomsg\BioWatchersCdma Plug-ins to the watcher framework to listen for CDMA SMS messages and deliver them to the global inbox in the message store.
+messaging\sms\multimode\clientmtm A plug-in to the message server framework to provide a generic API for creation of CDMA SMS messages (CDMA SMS Client MTM)
+messaging\sms\multimode\servermtm A plug-in to the message server framework to provide a generic API for sending of CDMA SMS messages (CDMA SMS Server MTM)
+
+3.1.2.3 Email
+The email plug-ins provide support the POP3, IMAP4 and SMTP email protocols and support for parsing and generating plain test, MIME and M-HTML format email messages.
+Component Description
+messaging\email\clientmtms A plug-in to the message server framework to provide a generic API for creation of email messages (IMAP4 SMTP and POP3 Client MTMs & email utilities)
+messaging\email\imapservermtm A plug-in to the message server framework to provide a generic API for access to a remote IMAP4 server (IMAP4 Server MTM)
+messaging\email\smtpservermtm A plug-in to the message server framework to provide a generic API for access to a remote SMTP server (SMTP Server MTM)
+messaging\email\popservermtm A plug-in to the message server framework to provide generic API for access to remote POP3 server (POP3 Server MTM)
+messaging\email\servermtmutils Email utilities for parsing plain text and MIME email messages. It also provides an abstraction of the TCP/IP sockets for use by the SMTP POP3 and IMAP4 plug-ins.
+messaging\email\autosend An executable that requests SMTP Server MTM to send messages in the outbox. This is used to provide send on next connection functionality and is started by the POP3 and IMAP4 Client MTMs.
+3.1.2.4 OBEX
+The OBEX MTM is a set of plug-ins to the message server that provides support for IR and Bluetooth beaming.
+Component Description
+messaging\obex\btmtm\btclient\group\btcmtm Bluetooth Client MTM
+messaging\obex\btmtm\btserver\group\btsmtm Bluetooth Server MTM
+messaging\obex\irmtm\irclient\group\ircmtm IR Client MTM
+messaging\obex\irmtm\irserver\group\IRSMTM IR Server MTM
+messaging\obex\obexmtm\obexclient\group\obexClientMtm OBEX Client MTM, base classes for the Bluetooth and IR Client MTMs
+messaging\obex\obexmtm\obexserver\group\obexServerMtm OBEX Server MTM, base classes for the Bluetooth and IR Server MTMs
+messaging\obex\obexmtm\obexutil\group\obexMtmUtil OBEX MTM utilities
+3.1.2.5 MMS
+The MMS MTM is a plug-in to the message server that provides support for MMS messages. From v9.0 and onwards MMS MTM and related components are removed.
+Component Description
+messaging\mms\utils MMS Utilities
+messaging\mms\servermtm MMS Server MTM
+messaging\mms\mmswatcherplugins MMS plug-ins to WAP push framework to handle reception of MMS notifications
+messaging\mms\codec MMS utilities for handling MMS codecs
+messaging\mms\clientmtm MMS Client MTM
+3.1.2.6 GMXML
+GMXML is a parser/generator for SMIL presentations for MMS messages.
+Component Description
+messaging\GMXML\XMLParser XML parser designed for parsing of SMIL messages
+messaging\GMXML\XMLDom XML document object model designed for parsing of SMIL messages
+messaging\GMXML\SMILdtd SMIL DTD
+3.1.2.7 Bio Message Plug-ins
+These parsers plug into the bio messaging framework to handle specific types of bio message.
+Component Description
+messaging\biomsg\cbcp\CBCP Compact business card parser
+messaging\biomsg\enp\ENP Email notification parser
+messaging\biomsg\gfp\gfp General file parser
+messaging\biomsg\iacp\IACP Nokia Smart Message Internet Access Parser
+messaging\biomsg\wapp\wapp Nokia/Ericsson OTA Parser
+3.1.2.8 PCMTM
+Plug-in to the message server that provided email synchronisation with a PC. This component has been deprecated in 8.0a and will not been documented in the API section below.
+3.1.2.9 Fax
+Plug-in to the message server that provides fax support. This component has been deprecated in 8.0a and will not been documented in the API section below.
+
+3.2 General Description
+3.2.1 Messaging / Message Server and MTM Architecture APIs
+3.2.1.1 Key Internal Relationships and Dependencies
+
+Figure 2 MTM Relationships
+Figure 2 shows the relationship between the Message Server and the MTM plug-ins. The grey classes are realisations of the MTM interfaces defined by the messaging framework. The message server depends on the Server MTM interface. Messaging Clients depend on the Client, UI and UI Data MTM interfaces and the Message Server Client API.
+3.2.1.2 Key External Relationships and Dependencies
+
+Figure 3 External Dependencies
+The grey package representing the messaging client depends on the Client, UI and UI Data interfaces and the Messaging Client API. The message server then depends on:
+• Charconv – Provides character set conversion routines, used to convert encoded message body text to Unicode body text.
+• EStore – Provides API to handle a stream based store used for the messaging index file and the framework classes for the message store files. (omitted from other dependency diagrams as it is implied by the dependency on the message server)
+• F32 – Provides the file server APIs used to access the file system directories in which messaging stores files containing message data. (omitted from other dependency diagrams)
+• BAFL – Provides API to load the correct messaging resource file dependent on the current language and to register the message store index file with the backup server. (omitted from other dependency diagrams)
+• ETEXT – Rich text APIs used to store body text of messages, this rich text format is a Symbian Proprietary format. (omitted from other dependency diagrams)
+• EUSER – Core Symbian OS utilities such as descriptors, arrays, client / server framework, cleanup stack and others (omitted from this and other dependency diagrams).
+• Central Repository – Centralised and secure storage facility for application settings, the message server stores message settings data in the central repository (from v9.0 and onwards).
+Note that debug only dependencies such as the flogger have been omitted from dependency diagrams.
+3.2.1.3 API Purpose - Further Elaboration
+3.2.1.3.1 Message Store
+The message server provides persistent storage of messages and messaging account settings. It does this by providing a message store consisting of a tree of message entries. Multiple clients can access the message store simultaneously. Each entry in the tree can represent an email account, folder of messages, message part, etc.
+
+Figure 4 Message Store
+Figure 4 shows an example message store. The tree is broken down in to three levels:
+1. The Root entry. This entry is just present to tie the tree structure together
+2. Service entries. There is one local service under which local folders and messages are stored, and zero or more remote services. Remote services represent message accounts.
+3. Message & Folder entries. Messages and folders, under the local service represent messages stored on the device. Messages and folders under remote services represent a local copy of messages that are present on a remote server. For example under a POP3 email service you would have copies of all the messages present on the POP3 email server, or under an SMS service you might find SMS messages that are stored on a SIM.
+The message server controls access to the entries in the store. It enforces the three levels therefore attempts to create message or folder entries directly under the root entry will fail.
+The message server provides three types of storage for each entry in the message store:
+• Index entry - TMsvEntry - intended to provide enough information for UI to display list views as shown in Figure 5. This consists of two strings and various flags (read, complete, has attachments etc).
+• Stream based file store - CMsvStore – provides storage of streams of data associated with UIDs. A standard UID is defined for storing body text. Other UIDs are specific. For example the email MTMs define a UID for storage of MIME headers. Compared to the index entry information this is used to store larger objects and is extensible, at the cost of being slower to access. From v9.0 and onwards CMsvStore provides an Attachment API for managing attachments. The Attachment API should be used as attachments can no longer be accessed directly due to Platform Security.
+• Directory of files – normally used for attachments.
+The only storage type that is always present is the index entry. The stream store and the directory of files are optional.
+
+Figure 5 Series 60 Inbox List View
+
+Figure 6 Remote and Local Entries
+As shown in Figure 6 the message store is split into two sets of entries:
+• Remote entries - entries that are representations of entries stored on a remote store .
+• Local entries - entries not linked to a remote store.
+The message server handles changes to local entries; internally it hands off changes to remote entries to the Server MTM that owns that service. Examples of operations that are handed off to Server MTMs are operations involving copying and moving messages to and from a remote service. See section 3.2.1.3.5 or more information on Server MTMs.
+Each entry within the store has a type:
+Folder – Messages can be grouped into folders. Standard folders such as inbox / outbox and user created folders.
+Message – Storage of the content of a message. Message entries can have child entries used to represent the structure of a message.
+Attachment – These represent attachments under a message entry.
+Root & Local Service Entry – There tie the tree structure together. However the Stream store associated with the root entry is sometimes used by UIs to store preferences e.g. default folder views etc.
+Remote Service - Represents a source and / or destination for messages. They are used to store the settings associated with the source / destination.
+Message Type Specific - MTMs can create other message types for use as child entries to messages they own. For example email uses a tree structure, with a message entry as the root, to represent the MIME structure of an email message; it uses folder entries to represent MIME folders and adds new types for entries representing the html body and text body parts of a message. This is shown in Figure 7.
+
+Figure 7 Email Message
+Using the message store to represent message structure allows reuse of the tree structure and makes it very simple to represent one message embedded in another. However this representation introduces performance issues as it results in each message having multiple files associated with it. The message server also keeps all index entries in memory; therefore this representation increases the memory footprint of the message server. Therefore when designing new MTMs we should think about moving away using multiple index entries to store one message in the message store.
+A default message store is created if the message server starts and no message store is present or a corrupt message store is present. The server will initially create a store with just a root entry, and then the server will create any standard folders defined in the resource file msgs.rsc. Finally the server will check whether an executable ‘mailinit.exe’ is present on the system, if it is present the server will launch the executable to allow customisation of the message store. The behaviour of ‘mailinit.exe’ is defined by the UI family of the device. However the typical behaviour is to load each of the UI Message Type Modules and allow each to perform any message type specific initialisation. For example the SMS plug-in typically creates a default service entry.
+
+3.2.1.3.2 Data File Storage (pre - v9.0)
+This section describes the files used by the message server before release v9.0. For information on the files used for release from v9.0 and onwards see section [3.2.1.3.3.1].
+Filename Access Purpose
+?:\system\Mail\index Private Message server index file, internal to message server
+?:\system\Mail\<8 hex digits> Shared via API Message server store files for services, clients access these via a messaging API.
+?:\system\Mail\<8 hex digits>.new Shared via API Temporary file used during committing message server store files.
+?:\SYSTEM\MAIL\<8 HEX DIGITS>_F\* Shared Files associated with a messaging service. These may be accessed directly by clients.
+?:\system\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits> Shared via API Message server store files for message entries, clients access these via a messaging API.
+?:\system\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits>.new Shared via API Temporary file used whilst committing message server store files.
+?:\system\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits>_F\* Shared Files associated with a message entry. These are accessed directly by clients.
+c:\system\data\msgs.ini Private Stores the drive containing the last used message store
+c:\system\Mtm\Mtm Registry v2 Private Cache of registered MTMs, internal to message server
+C:\system\data\sms_settings.dat Shared Copy of the SMS settings.
+?:\System\Mail\StoreInit.tmp Shared Created when message server runs ‘mailinit.exe’, ‘mailinit.exe’ should delete the file when it has successfully completed.
+?:\System\Mail\storedeleted.tmp Shared Created when message server finds and deletes a corrupt message store. Allows the UI to inform the user about the fact that the message store was corrupt.
+Files that are shown as private should only be accessed by the message server or by connectivity process for backup and restore purposes. Files listed as shared are accessed directly by messaging clients. Files listed as shared via API are accessed by client process but only via messaging APIs.
+3.2.1.3.3 Platform Security Compliant Message Store
+From v9.0 and onwards the message store is stored in the message server's data cage and the settings data are placed in the Central Repository. Access to the message store is only possible via message server APIs and not directly through file access. This leads to secured data storage and secured platform.
+3.2.1.3.3.1 Data caging
+Filename Purpose
+?:\private\<SID>\Mail\index Message server index file, internal to message server
+?:\ private\<SID>\Mail\<8 hex digits> Message server store files for services, clients access these via a messaging API.
+?:\ private\<SID>\Mail\<8 hex digits>.new Temporary file used during committing message server store files.
+?:\ private\<SID>\Mail\<8 hex digits>_F\* Files associated with a messaging service. These may be accessed directly by clients.
+?:\ private\<SID>\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits> Message server store files for message entries, clients access these via a messaging API.
+?:\ private\<SID>\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits>.new Temporary file used whilst committing message server store files.
+?:\ private\<SID>\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits>_F\* Files associated with a message entry. These are accessed directly by clients.
+c:\ private\<SID>\data\msgs.ini Stores the drive containing the last used message store
+c:\ private\<SID>\Mtm\Mtm Registry v2 Cache of registered MTMs, internal to message server
+?:\ private\<SID>\Mail\StoreInit.tmp Access via IPC call
+?:\ private\<SID>\Mail\storedeleted.tmp Created when message server finds and deletes a corrupt message store. Allows the UI to inform the user about the fact that the message store was corrupt.
+?\resource\messaging\bif\*.bif Registration data field with UID used in BIO framework
+
+3.2.1.3.4 How message centres display the message store
+The UI normally provides a Message Centre application to display the structure of the message store to the user. Different UIs map the structure to different views.
+
+Figure 8 Series 60 Message Centre (Composed from 2 screen shots)
+Figure 8 shows the top level view of the message centre application on a Series 60 phone. This shows that the message centre has hidden the local service and shows the standard folders at the same level as the services. Also the SMTP, SMS and MMS services are marked as hidden entries in the message store, and so do not appear in the message application.
+
+Figure 9 UIQ Message Centre
+However Figure 9 shows that the UIQ message centre has no 1-1 mapping from the structure in the message store to the structure shown to the user. Each of the message types is displayed as if its messages were contained in separate folders. Under each of these folders the user is presented with an inbox, outbox, send and drafts folder. This filtering is done in the UI layer as this functionality is not provided by the messaging API.
+3.2.1.3.5 Message Type Module Architecture
+
+Figure 10 Messaging MTM Structure (light coloured components are part of messaging subsystem)
+The MTM architecture is the plug-in scheme provided by the messaging framework to integrate different message transports into the message server. The plug-in scheme consists of four interfaces, the UI MTM, UI Data MTM, Client MTM and Server MTM. The messaging client applications loads and uses the first three which are loaded within the client’s process space. The final one the Server MTM is loaded within the message server process. The APIs for the client facing interfaces are extensible via run time type information provided by the QueryCapability API, and the InvokeAsyncFunction and InvokeSyncFunction APIs.
+3.2.1.3.5.1 UI MTM
+Handles requests from clients to view and edit messages or service settings. The MTM handles interaction with the message centre and as such the exact meaning of the APIs is defined by the UI. However common meanings are:
+• Create – Launches the editor with a new message.
+• Edit – If entry is a message this launches the editor; if entry is a service it edits the settings.
+• View – Launches the message viewer.
+• Display progress of an operation.
+3.2.1.3.5.2 UI data MTM
+This MTM provides fast access to UI components such as menu resources and bitmaps required by message centre for list views etc. Again the exact semantics are UI specific.
+There is a resource file defining UI specific functions, for example the Series 60 Messaging UI checks if the resource file contains text to display in the “New Message” menu.
+The UI data MTM also provides mapping from the message store’s TMsvEntry structure to Icons for the messaging list views and a status string, for example in the case of Nokia 9210 it is used in the outbox view to provide strings like “Resend 01:07” as shown in Figure 11. The class also provides functions to determine what operations are possible with a given entry. Examples of this are APIs that return whether the UI should allow the user to reply to the entry or to delete a service entry. The UI then uses this information to determine which menu options / short-cut keys should be allowed when the user selects a given entry.
+
+Figure 11 Nokia 9210 Outbox List View
+3.2.1.3.5.3 Client MTM
+Provides methods to create / reply and forward messages. Functions the Client MTMs provide are:
+• Create Message.
+• Reply to a Message.
+• Forward a Message.
+• Add / remove Addressees.
+• Add / remove body text.
+• Add / remove subject.
+• Add / remove attachments (the API cannot list attachments).
+The Client MTM interface is used by SendAs to provide a way of creating messages independently of the message type.
+3.2.1.3.5.4 Server MTM
+This is the final interface that makes up an MTM plug-in; it differs from the other three plug-ins in that it is loaded into the message server’s process space. The Server MTM provides access to messages under remote services. It handles connecting to remote servers to handle updating the local cache of these messages or to send messages copied to remote services when messages are copied to a remote service. The message server loads and hands off all message store operations that involve entries under a remote entry, these are the entries on the left-hand side of Figure 6.
+Functions that a Server MTM must implement:
+• Copy/MoveToLocal – called when the message server is asked to move or copy an entry that is currently under a remote service. A Server MTM might map this to retrieving a message from a remote mailbox.
+• Copy/MoveFromLocal – called when the message server is asked to move or copy from under the local service to a destination under a remote service. A Server MTM should map this to sending a message if the MTM supports sending.
+• Create, Delete, Change – called when the message server is asked to perform these operations on entries under a remote service.
+• StartCommand – this API provides a means of extending the API the Server MTM provides. Messaging clients pass a command ID and a selection of entries via the message server to the Server MTM. Examples of commands that Server MTMs might provide are: connect and synchronise the entries under a remote service with the messages on an email server, list SMS messages present on the phones SIM. These commands are MTM specific and therefore clients have to know which MTMs support which commands.
+3.2.1.3.5.5 MTM Registration
+MTMs must be registered with the message server so that clients can query what MTMs are present and the server knows which DLL to load to create a given MTM component. MTMs are registered by providing a resource file containing the MTMs UIDs, human readable name, and for each MTM interface it lists a DLL and the ordinal at which the constructor for that interface exists. The message server will search the ROM drive for MTM registration resource files on start-up and it will automatically register any MTMs found. For registration of MTMs installed on other drives, the message server provides an API to register and de-register an MTM. Registration will persist across a reboot, so an MTM only needs to be registered when it is installed on the system.
+When MTMs are registered or unregistered the message server will send events to all messaging clients with a message server session open.
+3.2.1.3.6 Message Server Client API
+The Messaging Server Client API breaks down into two categories: APIs for manipulation of the message store and utility APIs.
+3.2.1.3.6.1 Message Store manipulation APIs
+Requests from clients to modify the message store fall into three categories:
+1. Operations performed entirely with local entries (entries on the right-hand side of Figure 6) for example requests to create entries in the inbox, delete an entry from the drafts folder etc. The message server handles these operations directly.
+2. Operations that involve a remote entry (entries on the left-hand side of Figure 6) for example requests to delete an entry under a POP3 service, or copy a message to an SMTP service. The message server hands these operations off to the Server MTM that owns the service under which the remote entry is stored. The only exception to this rule is the ChangeAttributes API call. This modifies flags on an index entry and is handled by the message server for both local and remote entries. This means that a Server MTM can not rely on being called when flags like the Unread flag are changed. Note that operations can not involve two remote entries; therefore requests to copy entries between a remote service representing one POP3 account to a remote service representing another POP3 account will fail with an error.
+3. Requests that are explicitly directed at a Server MTM via the TransferCommand API. These commands are just passed to the correct Server MTM by looking up the Service ID and MTM of the first message in the selection passed into the command.
+The message server sends events when entries in the message store are modified to messaging clients that have a session open with the server.
+Where the API provides asynchronous functions to modify the message store or transfer a command to a Server MTM, the functions will return a message server operation object. This object can be used to request progress on operation or cancel the operation. Deleting the operation object returned, or closing the session used to make the request will result in the operation being cancelled, therefore a messaging client must remain running until operations it has requested have either completed or they will be cancelled. See appendix A.1 for an example of an asynchronous copy operation. If a Server MTM operating on the same remote service is already handling an operation, the message server will queue the new operation to be handled when the Server MTM becomes free. Requests for progress of operations that are queued will fail with KErrNotReady. The fact that the queue is based on the remote service ID means that you can have two Server MTMs of the same type running at the same time as long as they are operating on different services. So for example you can have two separate POP3 MTMs running synchronising different remote services with email servers.
+3.2.1.3.6.2 Utility APIs
+1. Access to MTM registries – These allow clients to construct instances of the interfaces an MTM implements.
+2. Register / Unregister an MTM.
+3. Change Drive – The message server closes the current message store and opens one on the drive specified. If no message store is present on the drive specified a new message store is created. The message sever can have only one mail store open at a time, if the current mail store is not available because a the disk the mail store is on is not present then the message server will switch the mail store back to the C: drive if an attempt is made to create a message in the inbox.
+4. Launching Editors – This launches the correct editor for a message. It is implemented by delegating the request to the UI MTM
+3.2.2 Messaging / Send As APIs
+3.2.2.1 Key Relationships and Dependencies
+
+Figure 12 SendAs Version 1 Dependencies
+SendAs version 1 and only present in releases before v9.0. SendAs uses the Messaging Client API to access the registry of Client MTMs and construct the Client MTM interfaces. The Client MTMs are then used for composing the message. SendAs requires clients to implement the MSendAsObserver interface. This interface is responsible for checking the return value of the capability queries made to Client MTMs that require a response and also for rendering message types that require it. The only message type supplied by Symbian that requires rendering is Fax, however this MTM has been removed in 8.0a and future releases.
+3.2.2.2 API Purpose - Further Elaboration
+3.2.2.2.1 SendAs API (pre – v9.0)
+The SendAs API makes use of the Client MTM interface and the Messaging Client API to provide a generic API for creating messages. Note despite the name of this component SendAs does not provide an API to send the message.
+SendAs builds a list of registered MTMs, then queries each MTM to check whether it supports sending, removing those MTMs from the list that do not support sending. This list is then provided to the messaging client application. At this point the application can add more constraints on the list of MTMs; for example it can insist the MTM supports Attachments or more than a certain size of body text. SendAs queries each of the MTMs about the requirements and will drop any MTMs from the list that does not meet them. When the application has finished adding requirements it selects one of the MTMs left in the list and uses that to compose the message, adding addresses, a subject, body text and attachments.
+SendAs supports setting a BIO Type for the message that is composed. This tells the transport that the body text represents a BIO Message. This is used when sending business cards from the contacts application as SMS messages; the contacts application puts the vCard data in the body text of the message and the transport sends it correctly. If the MTM in question supports attachments then the vCard is attached to the message.
+A new CSendAs object must be created for each message the application wishes to create.
+3.2.3 Platform Security Compliant SendAs Server (v9.0 onwards)
+
+Figure 13 SendAs Version 2 Dependencies
+From v9.0 and onwards the CSendAs has been replaced by the SendAs server component. The new SendAs server controls the access to the message store. Some of the key SendAs Server features are listed as follows.
+• Send a message once the capability policing of the client application has been completed.
+• Allow client applications to launch an editor for a specified message type.
+• Allow client applications to query the message type.
+The main client-side API is the RSendAs class. The client applications use this to connect to the Send-As server. The session object on the server-side is an instance of CSendAsSession.
+Client applications create messages using the RSendAsMessage API. Opening an RSendAsMessage object on Send-As server session creates a CSendAsMessage object in the Send-As server. There is a one-to-one mapping between an RSendAsMessage object and a CSendAsMessage object. This allows client applications to create multiple messages concurrently.
+
+3.2.4 Messaging / Schedule Send APIs
+3.2.4.1 Key Relationships and Dependencies
+
+Figure 14 Schedule Send Dependencies
+The Schedule Send Server MTM base class depends on the task scheduler to launch the schedule send executable at the correct time. To send the message with a package of data previously passed into the task scheduler by the Server MTM. The schedule send executable then uses the Messaging Client API to actually perform the requested operation.
+3.2.4.2 API Purpose - Further Elaboration
+3.2.4.2.1 Schedule Send
+The Schedule Send functionality is delivered by four components:
+Server MTM Base Class – The base class provides support to Server MTMs that wish to support scheduled operations.
+Data Structures – These are classes used to represent the data associated with a scheduled operation.
+Executable – The executable is run by the task scheduler at the scheduled time.
+The Task Scheduler – This component is part of the system libraries subsystem. Currently the SMS and Fax Server MTMs support scheduled sending.
+Clients request the Server MTM schedules operations via additional commands passed to TransferCommand API; this is passed to the Server MTM via the message server. The Server MTM packages the operation ID, a selection of message IDs, how often to poll for progress and an MTM specific buffer. It then passes this package of data to the task scheduler requesting that it launches the schedule send executable at the correct time with the packaged information.
+When the task scheduler launches the schedule send executable, it unpacks the schedule information and uses the Messaging Client API to request the Server MTM to perform the operation.
+Schedule Send supports a retry mechanism if the operation fails. The Server MTM has a resource file containing a mapping from the error codes the operation can fail with and actions to be performed. For example the SMS resource file has a mapping such that if the operation fails with an error code indicating a bad phone number the SMS will be set to failed and left in the outbox. Whereas if it fails with a error code indicating temporary network failure the send operation will be scheduled to be resent later with a maximum of three retries.
+3.2.5 Messaging / Watchers APIs
+3.2.5.1 Key Relationships and Dependencies
+
+Figure 15 Watcher Dependencies
+The watcher executable’s dependency on the message server is the result of a performance measure. The watcher process creates a message server session before initialising each of the watcher plug-ins and closes the session when it has finished. This keeps the message server running during initialisation avoiding starting and stopping the message server if each watcher plug-in opens and closes sessions.
+3.2.5.2 API Purpose - Further Elaboration
+The watcher framework consists of an executable that is launched when the device boots. The component that is responsible for launching it depends on the UI family. When the watcher.exe is launched it will load each DLL in z:\system\libs\watchers which has a second UID as KWatcherUid and calls the first DLL entry point to construct a CActive object.
+From v9.0 and onwards watcher DLLs are found by scanning the directory \resource\messaging\watchers for registry files. These files contain the name of a watcher DLL that can be loaded from ROM i.e. z:\sys\bin.
+The framework has retry behaviour if the first entry point leaves, in this case the watcher framework will start a timer and try and construct the watcher object 10 seconds later. Five attempts are made before the watcher plug-in is assumed to have failed completely. Once the watcher framework has constructed all the watchers it starts the active scheduler which should never exit.
+Watcher plug-ins typically make a request to another subsystem such that they will be completed when an external event like a fax line ringing or an SMS being received occurs. When the watcher has completed processing the request it will wait for the next event.
+No support for starting / stopping watchers is provided. This is a limitation that makes watchers unsuitable for operations like listening for messages beamed via IR, as the watcher should only run while the IR port is active.
+3.2.6 Messaging / Message URL Handler APIs
+3.2.6.1 Key Relationships and Dependencies
+
+Figure 16 Message URL Handler Dependencies
+3.2.6.2 API Purpose - Further Elaboration
+The Message URL Handler provides support for creating messages and launching messaging editors from URLs such as mailto:infobot@example.com?subject=current-issue. Note there is no dependency between the Message URL Handler application which processes the URLs and the Message URL Handler recognisers which maps from URLs to mime types.
+3.2.6.2.1 Message URL Handler Application
+This is a Symbian OS application that registers with the application framework that it can handle the mime types: x-epoc-url/fax, x-epoc-url/mailto and x-epoc-url/sms. When launched with a URL it will parse the URL to retrieve the address and other header fields and then use the SendAs API to create a new message with the correct address, headers etc. The application then uses the APIs in the MturUtils class provide by the mtmbase component in the messaging framework to launch the correct editor for the given message type. The application is marked as hidden and therefore should not be listed by UIs in application browsers.
+3.2.6.2.2 Message URL Recognisers
+This is a plug-in to the recogniser framework it will be called when the application framework wishes to recognise a file. Recognisers are called with the file name, in this case a URL, and a buffer containing the start of the file. The message URL recogniser compares the start of the URL with the URL schemes it recognises, if it finds a URL scheme it knows about it maps it to a mime type. The recogniser ignores the buffer passed in.
+Schemes recognised:
+Scheme Mime type
+mailto: X-Epoc-Url/mailto
+fax: X-Epoc-Url/fax
+sms: X-Epoc-Url/sms
+mms: X-Epoc-Url/mms
+See the application framework architectural description for more information on recognisers [R2].
+3.2.7 Messaging / SMS APIs
+3.2.7.1 Key Internal Relationships and Dependencies
+
+Figure 17 SMS Internal Dependencies
+3.2.7.2 Key External Relationships and Dependencies
+
+Figure 18 SMS External Dependencies
+3.2.7.3 API Purpose - Further Elaboration
+3.2.7.3.1 SMS Watchers
+The SMS watchers are made up of two watchers, the nbswatcher.dll and the wapwatcher.dll, and some common base classes in biowatcher.dll. The watchers listen for incoming messages from the SMS stack, part of the nbsprotocols subsystem [R3], and the WAP stack part of the WAP-Stack subsystem [R4].
+3.2.7.3.1.1 NBS Watcher
+The NBS watcher handles reception of SMS messages. When initialised by the watcher framework (see section 3.2.4) the watcher queries the bio messaging database for bio messages that are listed as having a type of ENbs. For each of these bio messages the watcher creates an object that opens a connection to the SMS stack and waits for the particular message type. The message types are either defined by the port number the message will be received on or by a string to watch for at the start of the message. For example Internet Access Configuration Point messages are start with “//SIAP11” and vCards are received on port 226. Finally the watcher listens for all other messages received from the SMS stack.
+When the NBS Watcher receives a non-class 2 SMS message it creates a new entry under the global inbox in the message store. For class 2 messages the entry is created in the class 2 folder as defined by the SMS settings, this may also be the global inbox. The details field of the entry is used to store the phone number of the incoming message or the name of the sender if the watcher finds a match for the phone number in the contacts database. The description field is used to store the first N characters of the SMS message, where N is defined in the SMS settings, or for bio messages the description as retrieved from the bio database. Bio messages also have the BioType field set to the UID of the bio message as retrieved from the bio database. The CSmsHeader class, which is a wrapper around the CSmsMessage class provided by the nbprotocols subsystem [R3], is used to externalise the SMS message to the entry’s CMsvStore. The watcher also places a copy of the body text of the message in the rich text stream of the entry’s CMsvStore.
+The NBS Watcher is also responsible for handing special SMS types including:
+• Replace Type Messages – When the watcher receives a message of this type it will scan the folder the message would have been delivered to for messages that have a matching protocol ID and from address. For each of the messages it checks whether the time stamps from the service centre and discards the older message.
+• Message Indications – The watcher can listen for incoming message waiting indications. The CSmsSettings class defines whether the watcher will listen and whether it will deliver the messages to the inbox or discard them. If the watcher is configured to listen for messages then it will use the SMS utilities in the SMS Client MTM to decode the message to determine the notification type and number of messages, e.g. 3 Email messages waiting, the strings for these messages are in the smss.rss resource file.
+• Delivery Reports – As with Message Indications the watcher can be configured to listen for these and again the SMS utilities get a string from the smss.rss resource file to put in the description field.
+The NBS Watcher handles changes to the bio database using the observer mechanism provided by the bio message database to observe when bio message types are added or removed and starting or stopping the object watching for that bio message type.
+3.2.7.3.1.2 WAP Watcher
+The WAP watcher listens for incoming messages from the WAP stack using the WAP message API [R4]. To determine ports to use to listen for messages the watcher queries the bio message database for bio message types EWsp, EWspSecure, EWap, EWapSecure and registers as an observer of the bio database and so will listen for new bio message with these types as they are added. The watcher stores the messages in the global inbox tagged with the bio type listed in the bio message database.
+3.2.7.3.2 SMS Client MTM
+The SMS Client MTM implements the standard set of Client MTM APIs described in Client MTM. In addition it provides:
+• Access to the CSmsHeader object that is used to represent the SMS message.
+• Access to the SMS settings stored in the associated SMS service.
+• The APIs required by Send As to allow Send As to create SMS messages including setting the bio type of the message to allow clients of Send As to send bio messages such as vCards and vCals. The data of the bio message is stored in the body text of the SMS message.
+• Simple check for valid SMS addresses, and SMS address is considered valid if it contains at least one digit.
+• Reading and writing SIM parameters.
+3.2.7.3.3 SMS Utilities
+These provide:
+• Classes to represent and store SMS messages (CSmsHeader), and SMS settings (CSmsSettings, CSmsMessageSettings) and a SMS number (CSmsNumber).
+• The CSmsHeader class contains and allows clients to access the CSmsMessage class that the nbsprotocols subsystem provides. This contains the entire SMS message and not just the header.
+• Functions to generate descriptions and details fields to store with SMS messages, including decoding special messages such as message indication and status report messages, reading resource file for descriptions strings of special messages, using the contacts database to replace phone numbers with names.
+• API to validate a GSM number.
+• Find the TMsvId of the SMS service entry.
+3.2.7.3.4 SMS Server MTM
+3.2.7.3.4.1 Sending Messages
+The SMS Server MTM handles sending of SMS and WAP messages via the SMS stack and the WAP stack. To support this it implements the CopyFromLocal API inherited from the Server MTM base class. It implements this as sending SMS messages and moving successfully sent messages to the Sent folder. When sending the SMS message the Server MTM checks the bio type of the message and uses the bio database to check the transport type for the bio message. The MTM supports ENbs that is sent via the SMS stack and EWap, EWapSecure that are sent via the WAP stack. The MTM does not support EWsp or EWspSecure although the watchers do support receiving them.
+If a message fails to send, sending is retried according to the settings in the smss.rss resource file as described in the schedule send section 3.2.3.
+3.2.7.3.4.2 Scheduling Messages
+The SMS Server MTM implements scheduled sending API by sub-classing from the schedule send Server MTM (see section 3.2.3). It accepts requests from clients either via the SMS Client MTM InvokeAsync API or via the CMsvSession::TransferCommand API to schedule messages to be sent or to delete existing schedules. When it receives a request to schedule a message it packages up the command and uses the scheduled send functionality to request that the task scheduler ask it to send the messages at a future point in time.
+3.2.7.3.4.3 Phone Store
+The phone store is the name given to storage of SMS messages outside of the message store. In the case of GSM phones this is the SIM. The SMS Server MTM accepts requests from clients to copy/move messages to and from the SIM and delete messages from the SIM. For example when copying to the SIM it packages up the SMS message and passes it to the SMS stack with a request to write it to the SIM. If the class2 folder has been set in the SMS settings class then the Server MTM will copy the SMS message to the SIM and then update the SMS message in the message store with details of the slot on the SIM that has been used to store the SMS and the fact that it is stored on the SIM.
+3.2.7.3.4.4 SIM Parameters
+The Server MTM provides functions to read / write SIM parameters, again these requests are passed to the SMS stack to be processed.
+3.2.8 Messaging / CDMA SMS APIs
+3.2.8.1 Key Internal Relationships and Dependencies
+
+Figure 19 CMDA SMS Internal Dependencies
+3.2.8.2 Key External Relationships and Dependencies
+`
+Figure 20 CDMA SMS External Dependencies
+3.2.8.3 API Purpose - Further Elaboration
+3.2.8.3.1 CDMA SMS Watchers
+The CDMA SMS watchers are made up of six watchers, the cdmanbswatcher.dll, vmnwatcher.dll, wemtwatcher.dll, wmtwatcher.dll, wptwatcher.dll, and the wapwatcher.dll, and some base classes in biowatcher.dll and cdmasocketwatcher. While the WAP watcher is common for both GSM and CDMA, the other watchers: CDMA NBS watcher, VMN watcher, WEMT watcher, WMT watcher, and the WPT watcher are used for CDMA only. The watchers listen for incoming messages from the CDMA SMS stack, part of the nbsprotocols subsystem [R3], and the WAP stack part of the WAP-Stack subsystem [R4].
+3.2.8.3.1.1 CDMA NBS Watcher
+The CDMA NBS watcher is similar to the NBS watcher and it handles bio messages defined in bio database. The CSmsHeader class is extended to wrap around the CCdmaSmsMessage class provided by the nbprotocols subsystem [R3], and is used to externalise the CDMA SMS message.
+For handling special CDMA SMS type, the CDMA NBS watcher is responsible for handling Message Indications as described in section 3.2.7.3.1.1 NBS Watcher.
+3.2.8.3.1.2 WAP Watcher
+The GSM WAP watcher is used to handle CDMA WAP message as well. The WAP watcher listens for incoming messages from the WAP stack, which can listen from the CDMA SMS stack or GSM SMS stack as appropriate. See 3.2.7.3.1.2 for more info about WAP watcher.
+3.2.8.3.1.3 Other CDMA Watchers
+The VMN watcher, WEMT watcher, WMT watcher and WPT watcher are CDMA watchers that handle reception of CDMA SMS messages. All CDMA SMS messages are associated with a teleservice. Therefore, each of the CDMA watchers is responsible for handling one teleservice: VMN watcher handles VMN SMS messages, WEMT watcher handles WEMT SMS messages, WMT watcher handles WMT SMS messages, and WPT watcher handles WPT SMS messages. The CSmsHeader class is reused to externalise the CDMA SMS message.
+The CDMA watchers are also responsible for handling special SMS types including:
+• Duplicate Message – When the watcher receives a duplicate message, it will discard the duplicate message as defined by the CDMA service settings.
+• User Acknowledge – The watcher can listen for user acknowledgment message of its teleservice type.
+• Delivery Acknowledge – The watcher can listen for delivery acknowledgment message of its teleservice type.
+• Read Acknowledge – The watcher can listen for read acknowledgment message of its teleservice type.
+3.2.8.3.2 CDMA SMS Client MTM
+The CDMA SMS Client MTM implements the standard set of Client MTM APIs described in Client MTM. In addition it provides:
+• Access to the CSmsHeader object that is used to represent the SMS message.
+• Access to the SMS settings stored in the associated SMS service. These settings are store in file store pre v9.0 but stored in Central Repository from v9.0 onwards.
+• The APIs required by Send As to allow Send As to create SMS messages including setting the bio type of the message to allow clients of Send As to send bio messages such as vCards and vCals. The data of the bio message is stored in the body text of the SMS message.
+• Simple check for valid SMS addresses, and SMS address is considered valid if it contains at least one digit.
+• Reading and writing SMS messages to R-UIM.
+3.2.8.3.3 CDMA SMS Utilities
+The CDMA version of SMS utilities are binary compatible with the GSM version of SMS utilities. But the classes that store SMS Message (CSMSHeader), and SMS settings (CSmsSettings, CSmsMessageSettings) and SMS number (CSmsNumber) are extended to store CDMA information. The CSmsHeader class is extended to contain and allow clients to access the CCdmaSmsMessage in addition to the CSmsMessage. Other functions provided by the GSM SMS Utilities is also provided by the CDMA version of SMS utilities, see 3.2.7.3.3 for information about GSM SMS Utilities.
+3.2.8.3.4 CDMA SMS Server MTM
+3.2.8.3.4.1 Sending Messages
+The CDMA SMS Server MTM handles sending of CDMA SMS and WAP messages via the CDMA SMS stack and the WAP stack. To support this it implements the CopyFromLocal API inherited from the Server MTM base class. It implements this as sending SMS messages and moving successfully sent messages to the Sent folder. When sending the CDMA SMS message the Server MTM will use the appropriate teleservice type. The MTM supports ENbs that is sent via the SMS stack and EWap, EWapSecure that are sent via the WAP stack. The MTM does not support EWsp or EWspSecure although the watchers do support receiving them.
+If a message fails to send, sending is retried according to the settings in the smss.rss resource file as described in the scheduled send section 3.2.4.
+3.2.8.3.4.2 Scheduling Messages
+The CDMA SMS Server MTM implements scheduled sending API by sub-classing from the schedule send Server MTM similar to implemented in the GSM SMS Server MTM. See 3.2.7.3.4.2 for more information.
+3.2.8.3.4.3 Phone Store
+In the case of CDMA phones, phone store can be phone-based storage or R-UIM based storage. The CDMA SMS Server MTM accepts requests from clients to copy/move messages to and from the phone/R-UIM and delete messages from the phone/R-UIM. For example when copying to the R-UIM it packages up the SMS message and passes it to the CDMA SMS stack with a request to write it to the R-UIM.
+3.2.8.3.5 Configuration for using CDMA SMS MTM
+The CDMA messaging components currently only support single mode, but it is designed such that it can become multimode in the future. Currently, -Dcdma option is used to for selecting CDMA mode for using emulator and building ROM.
+
+
+3.2.9 Messaging / Email APIs
+3.2.9.1 Key Internal Relationships and Dependencies
+
+Figure 19 Email Internal Dependencies
+
+3.2.9.2 Key External Relationships and Dependencies
+
+Figure 20 Email External Dependencies
+3.2.9.3 API Purpose - Further Elaboration
+3.2.9.3.1 Email Overview
+The Email plug-ins consist of a set of utilities and MTMs for POP3, IMAP4 and SMTP. For each email account a pair of services entries is created in the message store. For a POP3 account there will be an SMTP service and a POP3 service, for an IMAP4 account there will be an SMTP service and as IMAP4 service. These entries are used to store the settings for the email transport. Each of the service entries has its related ID set to the other member of the pair. The SMTP service is created invisible so the user only sees the POP3 or IMAP4 service entry, copying a message to the SMTP service will cause the SMTP Server MTM to attempt to send the message. The POP3 and IMAP4 MTMs provide functionality to synchronise with a remote email server this is achieved by extending the Client MTM interface via the InvokeAsync API. Synchronisation of a POP3 or IMAP4 account will result in copying headers and optionally body text and attachments from the email server and creating message entries under the POP3 or IMAP4 service entry.
+Email messages are represented in a common format whether they are being sent via SMTP or downloaded via POP3 or IMAP4. The email client utilities provide the classes for creating and manipulating the entry structure used to store emails. The email server side utilities provide classes to convert between the entry structure used to store emails in the message store and RFC2822 email messages sent to SMTP servers and retrieved from POP3 servers. IMAP4 email messages are parsed by the email server and the IMAP4 Server MTM requests and stores the individual parts of the messages.
+3.2.9.3.2 Email Client Utilities
+The email client utilities are part of the imcm DLL and provide classes for:
+• Storage of email messages including mime headers, RFC2822 headers, attachments, body text and encoding information in the message store
+• Manipulating email messages, for example adding attachments, replying etc.
+• To wrap up the character converters used to convert between standard character sets and Unicode. These make use of the charconv component that is part of the system libraries subsystem.
+• Storage of Email settings in the message store.
+• Progress information for email operations.
+The utilities are used directly by clients to access parts of email messages for display. CImEmailMessage provides the functionality used by clients displaying email messages, including listing attachments, getting body text and resolving URIs in M-HTML messages.
+The Email Client MTMs use the utilities when they are asked to create, reply to and forward messages CImEmailOperation provides the functionality to perform these operations. Each email message is represented by a parent message entry and then entries to represent mime folders and mime parts, see Figure 7 for an example, so adding or deleting mime parts involves walking the tree of entries and inserting / removing entries as appropriate.
+3.2.9.3.3 Email Server MTM Utilities
+The Email Server MTM Utilities are responsible for generating and parsing of RFC2822 format email messages and providing an API to wrap up a TCP/IP connection to a remote email server.
+• Parsing of RFC2822 Email Messages – The utilities provide an API that accepts the text of an RFC2822 email message a line at a time and stores the email message in messaging’s internal format for email messages. See the Email Client Utilities for details of this format. The API handles storing of RFC2822 headers, MIME headers, decoding of Base64 encoded or uuencoded attachments and decoding of text received in character sets supported by the charconv component. This API is only accessible to Server MTMs, as it requires classes that can only be instantiated while running within the message server process. See the Messaging Functional Specification [R1] for detail on which email specifications the utilities support.
+• Generation of RFC2822 Email Messages – The utilities provide an API to convert an email in messaging’s internal format into an RFC2822 email message. The API provides access to the RFC2822 text a line at a time for streaming to an SMTP server. The exact format of the email depends on the settings passed in; the API can generate plain RFC2822 email messages with uuencoded attachments, MIME email messages with Base64 encoded attachments, or M-HTML email messages with Base64 encoded attachments. See the Messaging Functional Specification [R1] for detail on which email specifications the utilities support.
+• TCP/IP socket wrapper – The utilities provide a class that abstracts a TCP/IP socket supplied by the networking subsystem into an API that supports sending and receiving lines of text to / from a remote server. This API is used to connect to remote email servers by each of the email Server MTMs. The API can either create insecure or secure sockets enabling the SSL encryption provided by the networking subsystem. It also supports changing an insecure socket into a secure socket, this enables the email Server MTMs to implement email protocols where the initial connection to the server is insecure and then a secure socket is negotiated before sending or requesting any sensitive information.
+3.2.9.3.4 POP3 MTMs
+The POP3 MTMs implements the functionality to synchronise the local message store with a remote POP3 email server.
+3.2.9.3.4.1 Client MTM
+The POP3 Client MTM implements the standard Client MTM APIs and other extensions:
+• Reply to, forward – These are accessible via the ReplyL and ForwardL APIs of a Client MTM and are implemented as calls to the email utilities class CImEmailOperation.
+• Reply to, forward, create new messages, create receipts and forward as attachment – These are accessible as commands available via the InvokeAsyncFunction API of the Client MTM, they are implemented as calls to CImEmailOperation.
+• Connecting, disconnecting and copying email while connected – These operations are accessible as commands available via the InvokeAsyncFunction API of the Client MTM, they are implemented as calls to the POP3 Server MTM.
+• Querying connection status – This command lets clients know whether the POP3 Server MTM is connected to an email server, and is available via the InvokeAsyncFunction API of the Client MTM. The Client MTM requests the information from the Server MTM.
+• Compound operations – The Client MTM provides functionality to wrap up connecting to email servers, copying / moving new messages or a selection of messages, and then optionally disconnecting. These commands are available via the InvokeAsyncFunction API of the Client MTM. The Client MTM implements this by using the CImPOP3GetMail class which requests the correct sequence of operations from the Server MTM, waiting for each operation to complete before requesting the next one.
+• Send on next connection If the Client MTM gets a request to connect to an email server it will check whether the POP3 settings. If send on next connection is requested it will launch the autosend.exe executable (see section 3.2.7.3.7) to handle sending messages waiting in the outbox.
+• Offline operations – The POP3 Client MTM has a command to cancel offline operations, this is available via the InvokeAsyncFunction API of the Client MTM. The Client MTM passes the request to the Server MTM.
+3.2.9.3.4.2 Server MTM
+The POP3 Server MTM handles the communication with the remote POP3 server and implementation of the POP3 protocol. The MTM uses CImTextServerSession to handle the communication with the email server and CImRecvConvert to parse the email messages downloaded, both are provided by the Email Server MTM Utilities.
+• Connect – The POP3 Server MTM will open a socket to the email server using CImTextServerSession and login user the username / password in the POP3 settings. After a successful connection the Server MTM will attempt to synchronise the current state of headers stored on the email server with the set stored in the message store and then start any pending offline operations. After the connect operation has completed the Server MTM will inform the message server that it is expecting more operations via the CommandExpected API and therefore the message server will not delete and unload the Server MTM.
+• Populate Message – The POP3 Server MTM treats requests to copy a message from and to the POP3 service as a request to download the full message.
+• Offline operations – When the POP3 Server MTM receives a request to copy, move, or delete and is not connected to a POP3 email server the Server MTM will store the operation in the CMsvStore of the entry being modified and perform the operation on the next connection to the email server.
+• Disconnect – When disconnecting from a remote email server the POP3 MTM will run any pending offline operations stored. After the disconnect operation completes the Server MTM will allow the message server to delete and unload the Server MTM by setting the CommandExpected API to false.
+3.2.9.3.5 IMAP4 MTMs
+The IMAP4 Server MTM implements the functionality to synchronise the local message store with a remote IMAP4 email server.
+3.2.9.3.5.1 Client MTM
+The IMAP4 Client MTM implements the standard Client MTM APIs and other extensions:
+• Connecting, disconnecting, synchronising, un/subscribing folders – These operations are accessible as commands available via the InvokeAsyncFunction API of the Client MTM, they are implemented as calls to the IMAP4 Server MTM.
+• Send on next connection – If the Client MTM gets a request to connect to an email server it will check whether the IMAP4 settings. If send on next connection is requested it will launch the autosend.exe executable (see section 3.2.7.3.7) to handle sending messages waiting in the outbox.
+• Reply to, and forward messages – These are accessible via the ReplyL and ForwardL APIs of a Client MTM and are implemented as calls to the email utilities class CImEmailOperation.
+• Reply to, forward, create new, create receipt, forward as attachment – These are accessible as commands available via the InvokeAsyncFunction API of the Client MTM, they are implemented as calls to CImEmailOperation.
+• Querying connection status – These commands let clients know whether the IMAP4 Server MTM is connected to an email server and whether it is currently processing a request. They are available via the InvokeAsyncFunction API of the Client MTM. The Client MTM requests the information from the Server MTM.
+• Compound Connection and synchronisation – The IMAP4 Client MTM provides a compound operation that connects and synchronises with an IMAP4 server. This operation is implemented as a client side object that combines requests to the IMAP4 Server MTM. The client side operation can complete the client request either after the connection, after the connection + sync or after the connection + sync + disconnect. The client will keep requesting that the inbox be resynchronised at a configurable interval so new messages received in the inbox on the server will appear under the IMAP4 inbox. The CImapConnectAndSyncOp class handles these compound operations.
+• Compound Connect and copy / move / populate messages – The IMAP4 Client MTM provides a compound operation that connects to an IMAP4 server and copies moves or populates messages. The implementation is provided by the CImImap4GetMail class which makes calls back into the IMAP4 Client MTM.
+• Offline operations – The IMAP4 Client MTM has a command to cancel offline operations, this is available via the InvokeAsyncFunction API of the Client MTM. The Client MTM passes the request to the Server MTM.
+3.2.9.3.5.2 Server MTM
+The IMAP4 Server MTM handles the communication with the remote IMAP4 server and implementation of the IMAP4 protocol. The MTM uses CImTextServerSession to handle the communication with the email server. The IMAP4 Server MTM opens two connections to the IMAP4 server this enables users to download messages while the Server MTM is performing a background synchronisation if requested by the Client MTM.
+• Connect – The IMAP4 Server MTM will open a socket to the email server using CImTextServerSession and login using the username / password in the IMAP4 settings. After a successful connection the Server MTM will optionally attempt to synchronise the current state of headers stored on the email server with the set stored in the message store and then start any pending offline operations. After the connect operation has completed the Server MTM will inform the message server that it is expecting more operations via the CommandExpected API and therefore the message server will not delete and unload the Server MTM.
+• Copy, Move messages – The IMAP4 Server MTM supports copying and moving messages between folders on the IMAP4 server and between the IMAP4 server and local folders.
+• Delete messages – The IMAP4 Server MTM will mark the email as deleted on the server; however it will not be deleted until the IMAP4 Server MTM disconnects from the server.
+• Folders – The IMAP4 Server MTM will allow folders to be subscribed, unsubscribed, renamed, copied, moved, and created within the IMAP4 service. Subscribing to a folder means that it will be visible to the user and synchronised with the remote server. The inbox is always subscribed.
+• Offline operations – When the IMAP4 Server MTM receives a request to copy, move, or delete and is not connected to an IMAP4 email server the Server MTM will store the operation in the CMsvStore of the entry being modified and perform the operation on the next connection to the email server.
+• Disconnect – When disconnecting from a remote email server the IMAP4 MTM will run any pending offline operations stored. After the disconnect operation completes the Server MTM will allow the message server to delete and unload the Server MTM by setting the CommandExpected API to false.
+
+3.2.9.3.6 SMTP MTMs
+The SMTP MTMs provide functionality to send email messages. They are made up of the Client MTM that is part of the imcm DLL and the Server MTM.
+3.2.9.3.6.1 Client MTM
+The SMTP Client MTM implements the standard Client MTM APIs including the functions required to allow clients of Send As to create email messages.
+3.2.9.3.6.2 Server MTM
+The SMTP MTMs provide functionality to send email messages; it interprets requests to copy entries to an SMTP service as a request to send those messages. In addition it responds to two extended commands via the StartCommand Server MTM interface. These commands are KSMTPMTMIsConnected that responds with whether the Server MTM is currently connected to a remote SMTP server and KSMTPMTMSendOnNextConnection which performs the same operation as copying a selection of messages to an SMTP service. The only difference between the copy operation and the KSMTPMTMSendOnNextConnection operation is that the latter can be called without a selection of messages.
+When the Server MTM receives a request to send messages it builds a selection of messages consisting of the messages passed into the operation and any messages waiting in the outbox to be sent. To determine which messages in the outbox are waiting to be sent the SMTP server checks for messages that have the same service ID as the destination of the send operation and have a sending state of KMsvSendStateWaiting, KMsvSendStateScheduled or KMsvSendStateResend. This means that any request to send messages may result in more messages being sent than explicitly listed in the selection passed to the send operation.
+The Server MTM restores its settings from the SMTP service it has been asked to copy the messages to. Then it connects to the SMTP server using the CImTextServerSession class in the Email Server MTM Utilities, passing in the SMTP server address and TCP/IP port number from the SMTP settings. Then for each message to be sent the Server MTM uses the Email Server MTM utilities to generate an RFC2822 format message to send to the SMTP server, the RFC2822 text is generated on the fly as the data is sent to the SMTP server. If the SMTP server accepts the message to be sent then the Server MTM moves the message to the sent folder and sets its sending state to sent. If the SMTP server rejects the message then the Server MTM leaves the message in the outbox and sets the sending state to failed. Separate emails are generated for BCC recipients to ensure that the SMTP server doesn’t incorrectly include BCC recipients in emails sent to addresses in the To and CC fields of the email.
+3.2.9.3.7 Autosend
+The Autosend component is an executable that is kicked off by the POP3 and IMAP4 Client MTMs if the send on next connection setting is set. This executable will just make a request to the SMTP Server MTM to send messages associated with the SMTP service related to the POP3 or IMAP4 service, wait for the operation to finish and then exit.
+3.2.10 Messaging / MMS APIs
+The MMS module has been removed from v9.0 and onwards.
+3.2.10.1 Key Internal Relationships and Dependencies
+
+Figure 21 MMS Internal Dependencies
+3.2.10.2 API Purpose - Further Elaboration
+3.2.10.2.1 MMS Overview
+The MMS MTM provides functionality for creating, accessing, sending and receiving MMS messages. Messages are sent and received without the client application needing to open or close any kind of session. The management of the MMS session is handled entirely within the MTM.
+MMS clients are alerted when a new message is available for download via the WAP Push mechanism. A WAP push watcher is provided to handle these notifications. After the notification the message can be downloaded over WSP or HTTP. Messages are sent by posting the data over WSP or HTTP. The Symbian MMS implementation can handle sending or receiving MMS message over either protocol.
+MMS messages are based on the MIME format but are binary encoded using WSP. Note that MMS messages are encoded in this way even if they are posted over HTTP as opposed to WSP. The codec component is responsible for this encoding and decoding.
+3.2.10.2.2 MMS Utilities
+3.2.10.2.2.1 Key External Relationships and Dependencies
+
+Figure 22 MMS Utilities External Dependencies
+The MMS utilities provide the message and settings encapsulation classes. The MMS settings and messages are stored in the message store, the MMS utilities provide the interfaces to access this data.
+3.2.10.2.2.2 Settings
+The settings functionality provided by the MMS utilities allows the messaging client to persist MMS settings in the message store. Supported settings include:
+ MMSC (MMS server) address
+ WSP or HTTP transport
+ Autofetch messages on notification
+ Preferred IAP for the MMS network connection
+The settings functionality is also used by the server MTM to retrieve the settings prior to message sending or fetching.
+3.2.10.2.2.3 Message Encapsulation
+The message classes provide the message access functionality. Messages can be created, stored, restored and read using these classes. Functionality includes:
+ Adding media objects to the message
+ Enumerating through media objects
+ Adding recipients, subject line, etc. to a message
+ Adding other headers to the message, e.g. expiry date
+ Finding the appropriate media object for a given URI in the SMIL part (URI resolving)
+The message data is stored in the message store using one entry per message regardless of the number of media objects added to the message. This is preferable to using multiple message entries as it is faster and uses less disk space.
+Most of the message access code is common whether it is being used on the client or server side, however some parts of it are specific. For this reason it is essential that the appropriate client or server side CMmsMessage derived class is used.
+3.2.10.2.3 MMS Watcher
+3.2.10.2.3.1 Key External Relationships and Dependencies
+
+Figure 23 MMS Watcher External Dependencies
+
+The MMS watcher plug-in is responsible for intercepting incoming MMS notifications and delivery reports then taking the appropriate action. It is implemented as a WAP Push watcher plug-in.
+When an MMS notification is received an MMS entry is created in the inbox using the MMS utilities. At this point the entry has its incomplete flag set. If the settings have the autofetch option selected then the MMS watcher initiates the fetch operation via the MMS client MTM.
+If a delivery report is received then the delivered flag is set on the appropriate sent message. If an outgoing message was sent to several recipients then there will be several delivered flags. A delivery report from each recipient will set the appropriate delivered flag.
+3.2.10.2.4 MMS Client MTM
+3.2.10.2.4.1 Key External Relationships and Dependencies
+
+Figure 24 MMS Client MTM Dependencies
+As with most other MTMs the MMS client MTM provides access to the server MTM functionality for messaging clients. It also implements the Send-As interface and reply and forward functionality.
+3.2.10.2.4.2 Send-As Implementation
+The Client MTM Send-As interface is implemented in the MMS Client MTM. The implementation differs slightly from other MTMs because additional presentation content may be generated depending on the media objects that are added. When simple combinations of images, sounds and text are added a SMIL presentation is generated to link them together. This is preferable to simple adding the objects as attachments where some clients render them as a list of files and others fail to render them at all.
+The SMIL data is constructed using templates stored in resource files, the GMXML (SMIL) composer is not used.
+3.2.10.2.4.3 Reply / Forward
+The Client MTM can be used to create replies to received messages or to create forwarded responses. The reply and forwarding operations are performed asynchronously.
+3.2.10.2.5 MMS Server MTM
+3.2.10.2.5.1 Key External Relationships and Dependencies
+
+Figure 25 MMS Server MTM Dependencies
+The Server MTM is the most complicated part the MMS implementation. It handles all of the state information required to send or fetch MMS messages. It is also responsible for managing the HTTP or WSP session and the connections to the phone network.
+3.2.10.2.5.2 Operations
+All MMS server MTM functionality is encapsulated in operations. An operation consists of the setup of a session, the sending, fetching and acknowledgements when appropriate, it then closes the session. The messaging client initiates an operation with a single call to the Client MTM, there is no need for the messaging client to explicitly establish the session or to know about the internal states. However, these internal states are available to the messaging client via the progress structure if this level of user feedback is required.
+Two types of operation are supported, background and foreground:
+A maximum of one foreground operation can be running at any one time. The messaging client can poll the server MTM for the progress of a running foreground operation, likewise it can cancel it if necessary.
+A background operation does not support progress information and can not be cancelled by the messaging client. It is possible to initiate background operations even if other background or foreground operations are pending. However, background operations are queued and a maximum of one will actually be running at any one time.
+The MMS watcher uses a background operation to perform automatic fetching. While the background autofetch is occurring it is still possible to start a foreground operation (such as sending a message) if required.
+3.2.10.2.5.3 Session and Connection Management
+The server MTM uses the HTTP Transport Framework to enable the HTTP or WSP session. HTTP or WSP can be selected at runtime by selecting the appropriate option in the settings. The server MTM is responsible for reading any HTTP proxy details from the CommDB and passing it to the HTTP framework. See the http transport framework architectural description for more information on recognisers [R5]
+The server MTM is also responsible for managing the connection to the phone network. Connections are opened when required using the RConnection mechanism, multi-homing is supported provided that the underlying HTTP framework transport plug-in also supports it.
+3.2.10.2.6 MMS Codec
+The MMS Server MTM is in charge of the state transitions, connection, session, the actual posting and fetching of the data from them, however it does not encode or decode the MMS PDUs. The encoding and decoding is performed by the MMS Codec.
+For decoding the Server MTM passes the Codec the MMS PDU data in a descriptor for processing. If the PDU contains a received MMS message then the message entry is updated with the decoded MMS data.
+For encoding the Server MTM passes a reference to the message store entry containing the un-encoded MMS data. The Codec then encodes it and returns the PDU to the Server MTM in a descriptor.
+
+
+3.2.11 Messaging / BIO APIs
+3.2.11.1 Key Internal Relationships and Dependencies
+
+Figure 26 BIO Message Internal Dependencies
+3.2.11.1.1.1 Key External Relationships and Dependencies
+
+Figure 27 Bio Parser External Dependencies
+
+3.2.11.2 API Purpose - Further Elaboration
+3.2.11.2.1 BIO Overview
+The BIO messaging components have been designed to unify and simplify the way in which system messages are processed. In this context ‘system messages’ refers to messages received on the device which are intended to update some attribute(s) on the system as opposed to being presented to the user. Examples of these types of messages include vCards which are parsed and then displayed to the user and when accepted modify the users contact database and OTA configuration messages which are again parsed before display to the user and if accepted create email accounts or internet access points.
+The BIO messaging components can be broken down into three groups:
+1) The BIO MTM - To initiate the parsing and processing of BIO messages
+2) The BIO Database - Maps port numbers, MIME types, etc. to bio types in order to identify the type of incoming BIO messages.
+3) The BIO Parsers - To parse and process the BIO message payload
+BIO messages are not receive by the bio messaging framework, they come over other message transports for example see section 3.2.6.3.1 on the SMS watchers which describes how the SMS watchers receive bio messages and use the bio framework to tag the messages with the correct bio id.
+3.2.11.2.2 BIO MTM
+The BIO client MTM is called by the messaging client to parse or process a BIO message that has been saved in the message store. It is the responsibility of a BIO watcher to save the BIO message with the BIO flag and the appropriate BIO type set.
+The BIO client MTM does very little, its primary task is to pass on the messaging client request to the server MTM. Two operations are supported, parse and process.
+The messaging client is expected to initiate the parsing of the BIO message before processing it. The parsing step involves analysing the data and storing it in a form that can be displayed to the user via the BIO message viewer.
+Once the message has been parsed the messaging client can initiate the processing of the message.
+The BIO server MTM is responsible for deferring the parsing and processing to the appropriate BIO parser. The behaviour for the parsing and processing steps varies between parsers. See the BIO Parsers section for more information.
+The bio MTM does not support sending messages and therefore does not support reply / forwarding messages. For bio messages sending / reply etc. is supported by the particular MTM that the message is sent over, for example SMS.
+3.2.11.2.3 BIO Database
+The BIO database is used to identify the type of BIO messages. It maps message attributes such as port number, MIME type or leading string to a BIO type. These are attributes are then used by clients of the bio framework to know what ports to listen for messages on. For example the SMS watchers use the leading string to wait for SMS messages that start with that string and when storing those messages in the inbox tag them with the bio id associated with that leading string. See the SMS watcher section 3.2.6.3.1 for more examples of how the BIO database can be used.
+3.2.11.2.4 BIO Parsers
+The BIO parsers are plug-ins for parsing and processing incoming BIO messages. They are invoked by the BIO Server MTM depending on the BIO type of the message being processed. Each BIO parser implements two functions, ParseL and ProcessL. The level of functionality varies between parsers. Some parsers update the final repository with the received data, e.g. WAPP updates the CommDB with the received settings. Some parsers simply save the data in an unparsed state for processing by another component, this secondary parsing is not part of the BIO framework and must be initiated by the messaging client. An example is when GFP saves vCard data as a file as opposed to updating the contacts database, the UI must then invoke the Versit parser to parse the vCard and commit it to the contacts database.
+3.2.11.2.4.1 Generic File Parser (GFP)
+The generic file parser can be used to identify and save a variety of BIO data types, e.g. vCards and vCals. The Generic File Parser does not process the data, it simply saves it in the message store for processing by another component. The file is saved as an attachment of the message entry that was parsed.
+3.2.11.2.4.2 Nokia/Ericsson OTA Parser (WAPP)
+The WAPP parser decodes Nokia/Ericsson OTA messages and updates CommDB to reflect the received settings.
+3.2.11.2.4.3 Nokia Smart Message Internet Access Parser (IACP)
+The IACP parser decodes Nokia Smart Messages and updates the CommDB and messaging settings where appropriate.
+3.2.11.2.5 BIF Files and Utilities
+The BIF files encapsulate the information required for identifying BIO messages, these details may include the expected port number, MIME type or leading string. Different BIO watcher will use different information from these files, for an example see the 3.2.6.3.1. The information can be retrieved from the BIF files by using the BIF utilities. Generally BIO aware clients will access this information via the BIO database. BIF files are resource files previous to the v6.1 release they were binary files generated by biftool.exe.
+3.2.11.2.6 Platform Security Compliant Messaging / BIO APIs
+In the platform security model the BIO parsers are run in the client space rather than in the message server space, as is done in the non-platform secure model. If the BIO parsers are run in the message server space, it allows a client process to gain the capabilities of the message server. IPC policing can protect the message server from this.
+Also, for the message server to be able to load any BIO parser it would need more capabilities than it really requires. By running the BIO parsers in the client space, both these issues are solved. The client process must be trusted with the necessary capabilities to run the specified BIO parser.
+The BIO registry files are located in the \resource\messaging\bif read-only directory. All BIO parser DLLs are located in the \sys\bin protected directory.
+
+Figure 26 BIO Message Dependencies (v9.0)
+The BIO client MTM is responsible for loading the BIO database and BIO utilities to handle parse/process requests from clients.
+The BIO registry files no longer identify the BIO parsers DLLs via their UID – the registry file must use the BIO parser DLL name to identify them.
+3.2.12 Messaging / OBEX MTM APIs
+3.2.12.1 Key Internal Relationships and Dependencies
+
+Figure 28 OBEX Internal Dependencies
+3.2.12.2 OBEX MTM Overview
+The OBEX MTM offers simple IR and Bluetooth beaming functionality. It provides an API that is consistent with other MTMs so that the underlying OBEX APIs do not need to be used directly for beaming applications. The OBEX MTM does not provide OBEX receiving functionality, in order to receive OBEX data the underlying OBEX APIs must be used directly.
+3.2.12.2.1 OBEX MTM
+The OBEX MTM is split into three parts. OBEX MTM DLLs, IR MTM DLLs and Bluetooth MTM DLLs. The OBEX MTM DLLs can not be used on their own they provide the base OBEX MTM functionality for the derived IR and Bluetooth MTMs.
+There are two APIs that can be used to create OBEX messages:
+1) The Send-As API
+2) Linked attachments by filename
+The Send-As API provides an interface consistent with other MTMs, however it requires all attachments to be copied into the message store before they can be sent, this is often undesirable for beaming applications because it is wastes disk space. For this reason a second API is provided that allows attachments to be linked to outgoing messages by filename, when this API is used there is no need to copy the attachments to the message store.
+Unlike many other MTMs after OBEX tries to send a message it is deleted from the outbox whether the sending succeeds or fails.
+3.2.12.2.1.1 OBEX MTM Key External Dependencies
+
+Figure 29 OBEX External Dependencies
+3.2.12.2.2 IR MTM
+The bulk of the OBEX MTM functionality is provided by the OBEX MTM DLLs, the IR MTM itself just sets up the parameters.
+3.2.12.2.2.1 IR MTM Key External Dependencies
+
+Figure 30 IR MTM Dependencies
+3.2.12.2.3 Bluetooth MTM
+The bulk of the OBEX MTM functionality is provided by the OBEX MTM DLLs, the Bluetooth MTM just subclasses from the OBEX MTM and sets up Bluetooth specific parameters.
+3.2.12.2.3.1 Bluetooth MTM Key External Dependencies
+
+Figure 31 Bluetooth MTM Dependencies
+3.2.12.2.4 OBEX MTM Utils
+The OBEX MTM Utils provide utility functionality used by the other OBEX MTM DLLs. The two main areas of functionality provided by this component are:
+1) Filename linking functionality
+2) Bluetooth SDP lookup
+The filename linking functionality is provided in the utilities because linked files must be added by the client side during message creation and need to be read on the server side during sending.
+
+3.2.12.2.5 Platform Security Compliant Messaging / OBEX MTM APIs
+From v9.0 and onwards the service settings of all the derived OBEX MTMs are stored in the Central Repository. The OBEX message is stored in the message store as an attachment – from v9.0 and onwards the Attachment API is used to attach the OBEX message.
+
+3.2.13 Messaging / GMXML APIs
+3.2.13.1 Key Relationships and Dependencies
+
+Figure 32 GMXML Dependencies
+3.2.13.2 Overview
+The GMXML component provides simple XML DOM parsing and validation functionality. It is intended for parsing XML that might be needed in messaging applications, specifically SMIL parsing for MMS rendering. It is not a general purpose XML parser and will not be suitable for some applications, e.g. browsing.
+3.2.13.2.1 GMXML DOM
+The DOM implementation is fit for purpose for SMIL rendering but differs from the standard DOM design in several respects, e.g. attributes are not stored as discrete nodes, for performance reasons they are stored with the element.
+The DOM tree classes are all derived from nodes. Implemented node types include elements, text and comments. The type of each element is stored as a descriptor as opposed to an enum. This is less efficient than storing it as an enum but provides maximum flexibility when dealing with unknown element types.
+Nodes are linked together in a tree structure as might be expected in a DOM implementation. The tree structure exists on the heap.
+3.2.13.2.2 GMXML Parser and Composer
+3.2.13.2.2.1 Parser
+The parser takes XML input from a buffer or file and creates the corresponding DOM structure on the heap.
+The parser is capable of performing some basic validation. In order to validate against a DTD a class that implements the GMXML DTD interface is required. The DTD interface specifies several functions that provide the required validation, e.g. one of the functions determines if a given attribute is valid for a given element. An instance of the DTD class should be passed into the parser when validation is required but can be omitted if no validation is needed.
+3.2.13.2.2.2 Composer
+The composer takes a DOM tree and generates XML output from it. The XML output is written to a file.
+3.2.13.2.3 GMXML SMIL DTD (Validator)
+The SMIL DTD validator class is an implementation of the DTD validator interface. It implements several simple functions that provide the information required to validate SMIL data. An instance of the SMIL DTD validator should be passed into the parser if SMIL validation is required.
+4 Security
+4.1 Data caging
+For data storage in the pre-platform security compliant architecture, refer to section [3.2.1.3.2]
+For the data caging in the platform security compliant architecture of v9.0 and onwards, refer to section [3.2.1.3.3]
+4.2 Backup and restore
+The message server registers the index file with the backup server. When informed about a backup/restore it releases the index file, sending events to messaging clients informing them that the message store is unavailable. When informed it can open the index file again, it checks the time stamp on the index file; if it has changed since the file was released it reloads the index file. If the newly restored index file is found to be corrupt it is deleted and a new message store is created. See the section on page 14 for details on how the message server handles corrupt stores. The client performing the restore should always wipe the existing message store before starting to copy the message store from the backup to the device.
+4.3 Capability ranges
+In the platform security compliant architecture of v9.0 and onwards, the capabilities allocated to messaging sub-systems are as listed in following table.
+4.3.1 Capabilities granted to executables
+The following table lists the executables and their capabilities and also gives a basic example for having the required capability.
+
+Executable Capability Rationale (basic example of capability requirement)
+msexe.exe ProtServ ProtServ is required to allow the msexe.exe to start a protected server. This stops processes without ProtServ from starting a server pretending to be the message server
+ ReadDeviceData ReadDeviceData is needed to able to read service settings
+ WriteDeviceData WriteDeviceData is needed to able to write service settings
+ NetworkServices NetworkServices capability is needed to access network transports (SMS, POP3, SMTP, IMAP4).
+ LocalServices LocalServices is needed to be able to access IR and Bluetooth
+ ReadUserData ReadUserData is needed to be able to read user data (e.g. service settings).
+watcher.exe ReadDeviceData ReadDeviceData is needed to able to read service settings
+ WriteDeviceData WriteDeviceData is needed to able to write service settings
+ NetworkServices NetworkServices capability is needed to access network transports (SMS).
+ LocalServices LocalServices capability is needed for the plug-ins to access IR and Bluetooth
+ ReadUserData ReadUserData is needed to be able to read user data
+ WriteUserData WriteUserData is needed to be able to write user data
+autosend.exe ReadUserData ReadUserData capability is needed to be able to read data from Outbox and SMTP server MTM.
+ WriteUserData WriteUserData capability is needed to be able to write data in Outbox and SMTP server MTM.
+ NetworkServices NetworkServices capability is needed to access network transports (SMS, POP3, SMTP, and IMAP4).
+ LocalServices LocalServices capability is needed to access the IR and Bluetooth
+SchSend.exe ReadDeviceData ReadDeviceData is needed to able to read settings data
+ NetworkServices NetworkServices capability is needed to access the network transports (SMS, POP3, SMTP, and IMAP4).
+ LocalServices LocalServices is needed to be trusted by other MTM
+ ReadUserData ReadUserData is needed to be able to read user data.
+ WriteUserData WriteUserData is needed to be able to write user data.
+SendAs.exe ReadDeviceData ReadUserData is needed to be able to read data in Outbox.
+ WriteDeviceData WriteUserData is needed to be able to write data in Outbox.
+ NetworkServices NetworkServices capability is needed to access the network transports (SMS, POP3, SMTP, and IMAP4).
+ LocalServices LocalServices is needed to be able to access IR and Bluetooth
+
+4.3.2 Capabilities granted to DLLs
+The assigned Platform Security attributes for DLLs within messaging are outlined in the following table.
+DLL Capability
+bifu.dll All –TCB
+bioc.dll All –TCB
+biodb.dll All –TCB
+bios.dll All –TCB
+biowatcher.dll same as watcher.exe
+biut.dll All –TCB
+cbcp.dll All –TCB
+enp.dll All –TCB
+gfp.dll All –TCB
+iacp.dll All –TCB
+nbswatcher.dll same as watcher.exe
+cdmanbswatcher.dll same as watcher.exe
+CdmaSocketWatcher.dll same as watcher.exe
+VMNWatcher.dll same as watcher.exe
+WEMTWatcher.dll same as watcher.exe
+WMTWatcher.dll same as watcher.exe
+WPTWatcher.dll same as watcher.exe
+wapp.dll All –TCB
+wapwatcher.dll same as watcher.exe
+smildtd.dll All –TCB
+xmldom.dll All –TCB
+xmlparser.dll All –TCB
+smiltranslator.dll All –TCB
+imcm.dll All –TCB
+imps.dll same as msexe.exe
+imut.dll All –TCB
+msgs.dll All –TCB
+msgurlrec.mdl same as AppArc.exe (once it exists; eiksrv in meantime)
+mtur.dll All –TCB
+pops.dll same as msexe.exe
+schsend.dll All –TCB
+send.dll All –TCB
+smcm.dll All –TCB
+smcm_gsm.dll Synonym for smcm.dll
+smcm_cdma.dll Synonym for smcm.dll
+smss.dll same as msexe.exe
+smss_gsm.dll Synonym for smss.dll
+smss_cdma.dll Synonym for smss.dll
+smts.dll same as msexe.exe
+btcmtm.dll All –TCB
+btsmtm.dll same as msexe.exe
+irc.dll All –TCB
+irs.dll same as msexe.exe
+obexclientmtm.dll All –TCB
+obexmtmutil.dll All –TCB
+obexservermtm.dll same as msexe.exe
+
+The reason for setting a high capability to the DLLs is to make it possible for almost anyone to link to them. Although a DLL may have capabilities ALL-TCB (All minus TCB), its real capability is limited by the process which loads the DLL.
+4.3.3 Capabilities required to use the subsystem
+The message subsystem needs to be protected against malicious clients. The following table shows the key capabilities required to do related activities in different components.
+
+Component Related Activity Required Capability and SID
+Message server Create message in local folder No capability required
+ Create message in Outbox ReadUserData, WriteUserData and MTM specific capabilities
+ Access client MTM ReadUserData, WriteUserData and MTM specific capabilities
+Watcher Allow plug-ins to wait on events (e.g. arrival of SMS) Watcher always polices if the client capabilities are trusted by the watcher framework, else it will not be loaded
+Plug-ins or clients using watcher need the same capabilities as watcher.exe to be able to be loaded by watcher.
+Autosend Send messages in background NetworkService or LocalService required by the message type
+SchSend Scheduling of operations (e.g. sending SMS) SchSend always polices to see if the process was started by the Task Scheduler – if not the process terminates without performing any of the scheduled tasks. Also, the SchSend verifies that only itself and the message server created the scheduled tasks. If this is not the case, SchSend does not performing the scheduled tasks.
+SendAs Create message Draft, move it to Outbox, and send message WriteDeviceData or WriteUserData and other capability required by the message type
+
+5 Further Information
+5.1 References
+No. Document Reference Version Description
+R1 messaging_functional_specification.doc 0.6 Messaging Functional description
+R2 SGL.GT0143.161_App-Framework_Architectural_Description.doc 1.0 App-Framework Architectural Description
+R3 NBProtocols_Subsystem_Architectural_Description.doc 0.2 NBProtocols Architectural Description
+R4 WAP-stack_architectural_analysis.doc 1.0 WAP stack architectural analysis
+R5 HTTP Transport Framework Architectural Description.doc 1.1 HTTP Transport Framework 1.1 Architectural Description
+5.2 Open Issues
+The following issues need to be resolved before this document is completed:
+1. Top-level architecture diagram showing the framework and plug-ins should be added to overview section.
+2. Message store section should talk about removable media.
+3. Define "Message Server Client API" and "Messaging Client API" in the glossary, and ensure it is consistently used in the diagrams
+4. Add a sequence diagram for receiving a vCard over SMS and integrating it into contacts
+5. Add a sequence diagram for sending an SMS
+6. Add a sequence diagram for synchronising a POP3 mail box
+7. Add a sequence diagram for connecting to an IMAP4 mail box and downloading a message
+8. Capability table should be updated after the implementation of server e.g. message server
+9. Sequence diagram may need to be changed to show secured platform operation
+10. In section [3.1.1.4] the server SendAsV2 to find a correct name
+11. Section 3.2.1.3.3.1 Data Caging file 'Mtm Registry v2'may need a correct name
+12. Breakdown diagram showing all DLL, exes, apps in the messaging subsystem for both the pre-v8.0 and post v9.0 in section[3.2]
+13. Needs to say more about how the capabilities are policed and the algorithms used for different operations
+14. The dependecy between the message server and the central repository need to be listed in the email, SMS and OBEX diagrams (e.g. message store)
+15. Section 3.2.1.2 - figure 3 - Central Repository also get used by the Message server, or server MTMs (e.g. POP3), to retrieve account settings the path, required DLL and description are not given
+16. Section 4.3.3 title can be Police requirement of the sub-system, add extra column for SID in the table and list the use of SID. For example SchSend checks for Task Scheduler SID
+
+
+5.3 Glossary
+The following technical terms and abbreviations are used within this document.
+Term Definition
+BIO
+Bearer Independent Object Smart messages e.g. vCards, vCals, and WAP provisioning messages. These can currently be received via the WAP stack, SMS stack, Bluetooth or Infrared.
+BIO Type UID that represents the content type of a BIO Message.
+Message Centre Application that displays list views of messages to the user, allowing the user to perform operations such as copying messages, sending messages creating new messages etc.
+Message Viewer Application for viewing a message.
+Message Editor Application for creating or editing a message
+Message Server Symbian OS Server that handles request to modify the Message Store
+Message Store Store of messages and related information kept in the file system on a Symbian OS device.
+Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
+Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
+Global Inbox A standard folder under the local service which is used to store incoming messages like SMS MMS etc. as opposed to an IMAP4 Inbox which would be under an IMAP4 service and is a representation of the Inbox on an IMAP4 email server.
+Central Repository centralised and secure storage facility for application settings
+OBEX Object exchange protocol, used to send objects such as vCards or files between devices via infrared or Bluetooth.
+GMXML XML parser / generator for use with SMIL formatted messages.
+UID Unique Identifier, a 32 bit number allocated from a registry owned by Symbian
+IPC Inter Process Communication
+MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
MTM Registry A list of currently installed MTMs maintained by the message server.
TLS Transport Layer Security, provides encryption of a TCP/IP socket.
M-HTML Standard for including HTML in MIME email messages see http://www.ietf.org/rfc/rfc2557.txt
@@ -42693,15 +40657,15 @@
Message Editor Application for creating or editing a message
Message Server Symbian OS Server that handles request to modify the Message Store
Message Store Store of messages and related information kept in the file system on a Symbian OS device.
-Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
-Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
+Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
+Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
Global Inbox A standard folder under the local service which is used to store incoming messages like SMS MMS etc. as opposed to an IMAP4 Inbox which would be under an IMAP4 service and is a representation of the Inbox on an IMAP4 email server.
Central Repository centralised and secure storage facility for application settings
OBEX Object exchange protocol, used to send objects such as vCards or files between devices via infrared or Bluetooth.
GMXML XML parser / generator for use with SMIL formatted messages.
UID Unique Identifier, a 32 bit number allocated from a registry owned by Symbian
IPC Inter Process Communication
-MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
+MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
MTM Registry A list of currently installed MTMs maintained by the message server.
TLS Transport Layer Security, provides encryption of a TCP/IP socket.
M-HTML Standard for including HTML in MIME email messages see http://www.ietf.org/rfc/rfc2557.txt
@@ -43711,15 +41675,1033 @@
Message Editor Application for creating or editing a message
Message Server Symbian OS Server that handles request to modify the Message Store
Message Store Store of messages and related information kept in the file system on a Symbian OS device.
-Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
-Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
+Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
+Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
Global Inbox A standard folder under the local service which is used to store incoming messages like SMS MMS etc. as opposed to an IMAP4 Inbox which would be under an IMAP4 service and is a representation of the Inbox on an IMAP4 email server.
Central Repository centralised and secure storage facility for application settings
OBEX Object exchange protocol, used to send objects such as vCards or files between devices via infrared or Bluetooth.
GMXML XML parser / generator for use with SMIL formatted messages.
UID Unique Identifier, a 32 bit number allocated from a registry owned by Symbian
IPC Inter Process Communication
-MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
+MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
+MTM Registry A list of currently installed MTMs maintained by the message server.
+TLS Transport Layer Security, provides encryption of a TCP/IP socket.
+M-HTML Standard for including HTML in MIME email messages see http://www.ietf.org/rfc/rfc2557.txt
+MIME Specification for the format of email message bodies see http://www.ietf.org/rfc/rfc1341.txt
+RFC2822 The standard format for internet mail messages see http://www.ietf.org/rfc/rfc0822.txt
+SMTP Simple Mail Transport Protocol
+SID Secure Identification
+IMAP4 Internet Mail Access Protocol
+POP3 Post Office Protocol Version 3
+NBS Narrow Band Socket, in the messaging context this refers to the socket that is used to talk to the SMS stack for receiving and sending SMS messages
+SMS Short Message Service
+MMS Multimedia Message Service
+WAP Wireless Application Protocol
+WSP WAP Session Protocol
+HTTP Hypertext transfer protocol
+PDU Protocol Data Unit. This is the encoded form of SMS and MMS messages.
+Versit A consortium that defined standard formats for things like contacts (vCard) and calendar entries (vCals)
+SDP Service Discovery Protocol. A Bluetooth protocol that allows an applications to discover which services are available and to determine the characteristics of the services.
+SMIL Synchronized Multimedia Integration Language. Presentation language that is commonly used to define the contents of an MMS message.
+XML Extensible Mark-up Language
+DOM Document Object Model
+DTD Document Type Definition, a schema that defines the structure of an XML document.
+ESTORE Symbian OS component that provides stream based storage. Messaging uses the Permanent file store provided by ESTORE to store its index entries.
+Appendix A - Example Sequence Diagrams
+A.1 Copy to a Remote Service
+
+Figure 33 Sequence Diagram Showing Copying to a Remote Service
+Figure 33 shows a client copying a message to a remote service using the Messaging Client API. The message server then delegates the copy to the SMTP Server MTM. The Server MTM interprets the request as a request to send the message so it opens a connection to a remote SMTP server and sends the message. While the message is being sent the client can retrieve progress information from the CMsvOperation object that was returned by CMsvEntry::CopyL. The dark grey IPC line represents the split between the objects running in the client’s process space on the left and the message server’s process on the right.
+There are four basic steps:
+1. The client opens session with Message Server and creates a CMsvEntry set on the global outbox,
+2. The client then requests an asynchronous copy from the outbox to the SMTP service, a CMsvOperation object is returned. The message server loads the SMTP Server MTM and delegates the copy operation to it.
+3. The client requests progress from the CMsvOperation object, this request is passed through to the SMTP Server MTM. The client may repeat this step multiple times.
+4. The Server MTM finishes sending message. It moves the message to sent folder and completes the message server’s request. The message server completes the CMsvOperation object, which requests the final progress from the message server. The server returns the final progress and deletes the Server MTM. The CMsvOperation then completes the client’s original request.
+This diagram hides all of the internal working of the SMTP Server MTM, for information on this see below.
+A.2 SMTP Session
+
+Figure 34 Sequence Diagram Showing a SMTP Session
+Figure 34 shows the operation of the SMTP Server MTM after a request has come from the message server to copy a message to the SMTP service.
+1. SMTP Server MTM gets the request from the message server, it will build a selection of messages consisting of the union of the selection of messages passed in and the messages in the outbox that are associated with this SMTP service and are ready to be sent. The chain of classes are constructed, and a request is passed to networking to connect to the remote SMTP server, details of the server name and port are retrieved from the settings stored in the SMTP service entry.
+2. The component waits for the SMTP server to respond with a greeting indicating it is willing to talk, then sends EHLO to the server and waits for the response detailing the capabilities of the Server. After this step there could set steps to start using TLS and or SMTP AUTH depending on the SMTP settings.
+3. CImSmtpSession calls back into CMsgOutboxSend to retrieve the next message to be sent, then constructs a CImSmtpFile object to handle sending, for details on the sending see SMTP Email Send. When sending the email has completed the CImSmtpFile object is deleted.
+4. CImSmtpSession calls back into CMsgOutboxSend to retrieve the next message which returns saying there are no more messages. CImSmtpSession sends QUIT to the SMTP server and completes CMsgOutboxSend. CMsgOutboxSend deletes CImSmtpSession which tears down the connection to the SMTP server; it then completes the SMTP Server MTM. The Server MTM will then complete the message server and be deleted.
+A.3 SMTP Email Send
+
+Figure 35 Sequence Diagram Showing SMTP Transactions during Email Send.
+Figure 35 shows a CImSmtpFile object sending an email message to an SMTP server.
+1. Construct a CImSendMessage object, part of the imut component. Reset the SMTP Server
+2. Read address information from the CImHeader object stored in the message store, send address information to SMTP server.
+3. Use CImSendMessage object to read the message from the message store and generate RFC2822 message line by line. Send each line to the server as it is generated.
+4. Complete and send the message by sending a full stop to the SMTP server
+
+
+
+
+Messaging Symbian OS v7.0s, v8.0, v8.1, v9.0, v9.1 Architectural Description
+
+Status: Issued
+Team/Department : Messaging / Content & Messaging
+
+Contents
+1 INTRODUCTION 6
+1.1 PURPOSE AND SCOPE 6
+2 SUBSYSTEM OVERVIEW AND BACKGROUND 6
+3 MESSAGING ARCHITECTURE AND APIS 7
+3.1 SUBSYSTEM COMPONENTS 7
+3.1.1 Framework components 7
+3.1.1.1 Message Server and MTM architecture 7
+3.1.1.2 Schedule Send 7
+3.1.1.3 SendAs Version 1 7
+3.1.1.4 SendAs Version 2 7
+3.1.1.5 Watcher Framework 8
+3.1.1.6 Message URL Handler 8
+3.1.1.7 Bio Message Framework 8
+3.1.2 Plug-ins 8
+3.1.2.1 SMS 8
+3.1.2.2 CDMA SMS 8
+3.1.2.3 Email 9
+3.1.2.4 OBEX 9
+3.1.2.5 MMS 9
+3.1.2.6 GMXML 10
+3.1.2.7 Bio Message Plug-ins 10
+3.1.2.8 PCMTM 10
+3.1.2.9 Fax 10
+3.2 GENERAL DESCRIPTION 11
+3.2.1 Messaging / Message Server and MTM Architecture APIs 11
+3.2.1.1 Key Internal Relationships and Dependencies 11
+3.2.1.2 Key External Relationships and Dependencies 12
+3.2.1.3 API Purpose - Further Elaboration 13
+3.2.1.3.1 Message Store 13
+3.2.1.3.2 Data File Storage (pre - v9.0) 15
+3.2.1.3.3 Platform Security Compliant Message Store 16
+3.2.1.3.4 How message centres display the message store 17
+3.2.1.3.5 Message Type Module Architecture 19
+3.2.1.3.6 Message Server Client API 21
+3.2.2 Messaging / Send As APIs 22
+3.2.2.1 Key Relationships and Dependencies 22
+3.2.2.2 API Purpose - Further Elaboration 22
+3.2.2.2.1 SendAs API (pre – v9.0) 22
+3.2.3 Platform Security Compliant SendAs Server (v9.0 onwards) 23
+3.2.4 Messaging / Schedule Send APIs 24
+3.2.4.1 Key Relationships and Dependencies 24
+3.2.4.2 API Purpose - Further Elaboration 24
+3.2.4.2.1 Schedule Send 24
+3.2.5 Messaging / Watchers APIs 25
+3.2.5.1 Key Relationships and Dependencies 25
+3.2.5.2 API Purpose - Further Elaboration 25
+3.2.6 Messaging / Message URL Handler APIs 26
+3.2.6.1 Key Relationships and Dependencies 26
+3.2.6.2 API Purpose - Further Elaboration 26
+3.2.6.2.1 Message URL Handler Application 26
+3.2.6.2.2 Message URL Recognisers 27
+3.2.7 Messaging / SMS APIs 27
+3.2.7.1 Key Internal Relationships and Dependencies 27
+3.2.7.2 Key External Relationships and Dependencies 28
+3.2.7.3 API Purpose - Further Elaboration 28
+3.2.7.3.1 SMS Watchers 28
+3.2.7.3.2 SMS Client MTM 29
+3.2.7.3.3 SMS Utilities 29
+3.2.7.3.4 SMS Server MTM 30
+3.2.8 Messaging / CDMA SMS APIs 31
+3.2.8.1 Key Internal Relationships and Dependencies 31
+3.2.8.2 Key External Relationships and Dependencies 32
+3.2.8.3 API Purpose - Further Elaboration 32
+3.2.8.3.1 CDMA SMS Watchers 32
+3.2.8.3.2 CDMA SMS Client MTM 33
+3.2.8.3.3 CDMA SMS Utilities 33
+3.2.8.3.4 CDMA SMS Server MTM 33
+3.2.8.3.5 Configuration for using CDMA SMS MTM 34
+3.2.9 Messaging / Email APIs 35
+3.2.9.1 Key Internal Relationships and Dependencies 35
+3.2.9.2 Key External Relationships and Dependencies 36
+3.2.9.3 API Purpose - Further Elaboration 36
+3.2.9.3.1 Email Overview 36
+3.2.9.3.2 Email Client Utilities 37
+3.2.9.3.3 Email Server MTM Utilities 37
+3.2.9.3.4 POP3 MTMs 37
+3.2.9.3.5 IMAP4 MTMs 38
+3.2.9.3.6 SMTP MTMs 40
+3.2.9.3.7 Autosend 40
+3.2.10 Messaging / MMS APIs 40
+3.2.10.1 Key Internal Relationships and Dependencies 41
+3.2.10.2 API Purpose - Further Elaboration 41
+3.2.10.2.1 MMS Overview 41
+3.2.10.2.2 MMS Utilities 42
+3.2.10.2.3 MMS Watcher 43
+3.2.10.2.4 MMS Client MTM 43
+3.2.10.2.5 MMS Server MTM 44
+3.2.10.2.6 MMS Codec 45
+3.2.11 Messaging / BIO APIs 46
+3.2.11.1 Key Internal Relationships and Dependencies 46
+3.2.11.2 API Purpose - Further Elaboration 47
+3.2.11.2.1 BIO Overview 47
+3.2.11.2.2 BIO MTM 47
+3.2.11.2.3 BIO Database 48
+3.2.11.2.4 BIO Parsers 48
+3.2.11.2.5 BIF Files and Utilities 48
+3.2.11.2.6 Platform Security Compliant Messaging / BIO APIs 49
+3.2.12 Messaging / OBEX MTM APIs 50
+3.2.12.1 Key Internal Relationships and Dependencies 50
+3.2.12.2 OBEX MTM Overview 50
+3.2.12.2.1 OBEX MTM 50
+3.2.12.2.2 IR MTM 51
+3.2.12.2.3 Bluetooth MTM 51
+3.2.12.2.4 OBEX MTM Utils 52
+3.2.12.2.5 Platform Security Compliant Messaging / OBEX MTM APIs 52
+3.2.13 Messaging / GMXML APIs 52
+3.2.13.1 Key Relationships and Dependencies 52
+3.2.13.2 Overview 53
+3.2.13.2.1 GMXML DOM 53
+3.2.13.2.2 GMXML Parser and Composer 53
+3.2.13.2.3 GMXML SMIL DTD (Validator) 53
+4 SECURITY 54
+4.1 DATA CAGING 54
+4.2 BACKUP AND RESTORE 54
+4.3 CAPABILITY RANGES 54
+4.3.1 Capabilities granted to executables 54
+4.3.2 Capabilities granted to DLLs 55
+4.3.3 Capabilities required to use the subsystem 57
+5 FURTHER INFORMATION 59
+5.1 REFERENCES 59
+5.2 OPEN ISSUES 59
+5.3 GLOSSARY 60
+APPENDIX A - EXAMPLE SEQUENCE DIAGRAMS 62
+A.1 COPY TO A REMOTE SERVICE 62
+A.2 SMTP SESSION 64
+A.3 SMTP EMAIL SEND 66
+
+Table of Figures
+Figure 1 Where Messaging Lives 6
+Figure 2 MTM Relationships 11
+Figure 3 External Dependencies 12
+Figure 4 Message Store 13
+Figure 5 Series 60 Inbox List View 14
+Figure 6 Remote and Local Entries 14
+Figure 7 Email Message 15
+Figure 8 Series 60 Message Centre (Composed from 2 screen shots) 17
+Figure 9 UIQ Message Centre 18
+Figure 10 Messaging MTM Structure (light coloured components are part of messaging subsystem) 19
+Figure 11 Nokia 9210 Outbox List View 20
+Figure 12 SendAs Version 1 Dependencies 22
+Figure 13 SendAs Version 2 Dependencies 23
+Figure 14 Schedule Send Dependencies 24
+Figure 15 Watcher Dependencies 25
+Figure 16 Message URL Handler Dependencies 26
+Figure 17 SMS Internal Dependencies 27
+Figure 18 SMS External Dependencies 28
+Figure 19 CMDA SMS Internal Dependencies 31
+Figure 20 CDMA SMS External Dependencies 32
+Figure 19 Email Internal Dependencies 35
+Figure 20 Email External Dependencies 36
+Figure 21 MMS Internal Dependencies 41
+Figure 22 MMS Utilities External Dependencies 42
+Figure 23 MMS Watcher External Dependencies 43
+Figure 24 MMS Client MTM Dependencies 43
+Figure 25 MMS Server MTM Dependencies 44
+Figure 26 BIO Message Internal Dependencies 46
+Figure 27 Bio Parser External Dependencies 47
+Figure 26 BIO Message Dependencies (v9.0) 49
+Figure 28 OBEX Internal Dependencies 50
+Figure 29 OBEX External Dependencies 51
+Figure 30 IR MTM Dependencies 51
+Figure 31 Bluetooth MTM Dependencies 52
+Figure 32 GMXML Dependencies 52
+Figure 33 Sequence Diagram Showing Copying to a Remote Service 62
+Figure 34 Sequence Diagram Showing a SMTP Session 64
+Figure 35 Sequence Diagram Showing SMTP Transactions during Email Send. 66
+1 Introduction
+1.1 Purpose and Scope
+The Messaging Architectural Description details the architecture and APIs exposed by the Messaging Subsystem. This document does not attempt to list all functionality provided by the messaging subsystem. For details on the functionality provided and the specifications implemented by the messaging subsystem see the Messaging Functional Description [R1]. This document describes the general architecture of messaging subsystem. Information related to a particular release version is mentioned with relevant release number.
+2 Subsystem Overview and Background
+The Messaging Subsystem provides an application level API to handle the storage and transport of different message types. It sits between messaging applications and the lower level subsystems which messaging uses for storage and transmission of messages.
+
+Figure 1 Where Messaging Lives
+The message types that messaging currently supports are Email (POP3, IMAP4 & SMTP), SMS, MMS and OBEX. The set of supported message types is extensible at run time by the use of plug-in modules that are responsible for the transmission and storage of a particular message type. This means that the set of components shown communicating with the network cloud depend on the message types installed.
+3 Messaging Architecture and APIs
+3.1 Subsystem components
+The Messaging subsystem components can be split into two categories: those components that form the framework and those that plug into the framework to support specific message types. This section briefly describes each of the components, more detailed descriptions of the components and their dependencies can be found in later sections of this document.
+3.1.1 Framework components
+3.1.1.1 Message Server and MTM architecture
+The message server is the core component in the messaging subsystem. It provides the message store used to contain messages. The Message Type Module architecture also allows plug-ins to add support for new message types to the messaging subsystem.
+Component Description
+messaging\framework\serverexe Executable that links to the server component and starts the message server
+messaging\framework\server Contains classes that make up both the client and server side of the message server API.
+messaging\framework\mtmbase Base classes for the plug-ins that handle the various message types
+3.1.1.2 Schedule Send
+The Schedule Send component is an extension to the framework that provides support for scheduling of operations such as sending messages. Message type modules that wish to support this functionality can use these support components to implement scheduling. For example the SMS MTM uses this to allow scheduled sending of SMS messages.
+Component Description
+messaging\schedulesend\schedulesendmtm Base classes that handle functionality for message server plug-ins that wish to enable scheduling of sending messages.
+messaging\schedulesend\schedulesendexe Executable use to provide schedule send behaviour.
+3.1.1.3 SendAs Version 1
+This version of SendAs is supported in releases pre - v9.0. SendAs provides a high level API for applications that wish to include a “Send As” menu to allow users to send content via one of the message types supported by messaging. The application using the API does not have to be aware of the message type selected by the user. Note the API does not send the messages.
+Component Description
+messaging\sendas High level API to allow creation of messages.
+3.1.1.4 SendAs Version 2
+From v9.0 and onwards the SendAs has been replaced with client server architecture based SendAs server. The client server architecture enhances secured platform implementation. The SendAs server polices the client application. If it is not trusted with required capabilities the SendAs server will refuse the client access. The client MTM for the message type can send a message with user permission even if the client does not have the correct capabilities.
+Component Description
+messaging\sendAsV2 High level API to allow the creation and sending of messages
+
+3.1.1.5 Watcher Framework
+The watcher framework is a lightweight framework to allow plug-ins to wait on events. For example there is an SMS watcher that waits for incoming SMS messages and delivers them to the message store. The watcher framework will only load plug-ins from ROM.
+Component Description
+messaging\framework\watcher Executable that loads and runs watcher plug-ins.
+3.1.1.6 Message URL Handler
+Support for recognising messaging URLs (mailto:, sms:, fax:, mms:), and then launching an editor with a new message.
+Component Description
+messaging\urlhandler\urlhandler An application that parses the URLs and then creates a correctly addressed message and launches a message editor.
+messaging\urlhandler\recogniser Recognisers that map from the URL schemes to the mime types.
+3.1.1.7 Bio Message Framework
+The Bio Message Framework provides a framework that supports plug-ins to handle messages like vCards and Internet access point set-up messages.
+Component Description
+messaging\biomsg\BDB\BIODB Classes to maintain the database of bio registration files.
+messaging\biomsg\BIFU\BIFU Classes for reading and writing bio registration files
+messaging\biomsg\BIOC\BIOC Bio message client MTM, this is in the framework section as it forms part of the bio messaging framework it is also a plug-in to the messaging framework.
+messaging\biomsg\BIOS\BIOS Bio message server MTM, this is in the framework section as it forms part of the bio messaging framework it is also a plug-in to the messaging framework.
+3.1.2 Plug-ins
+3.1.2.1 SMS
+The SMS plug-ins provide application level support for the Short Message Service messages.
+Component Description
+messaging\biomsg\BioWatchers Plug-ins to the watcher framework to listen for SMS, WSP, and WDP messages and deliver them to the global inbox in the message store.
+messaging\sms\clientmtm A plug-in to the message server framework to provide a generic API for creation of SMS messages (SMS Client MTM & SMS utilities)
+messaging\sms\servermtm A plug-in to the message server framework to provide a generic API for sending of SMS messages (SMS Server MTM)
+3.1.2.2 CDMA SMS
+The CDMA SMS plug-ins provide application level support for the CDMA Short Message Service messages.
+Component Description
+messaging\biomsg\BioWatchersCdma Plug-ins to the watcher framework to listen for CDMA SMS messages and deliver them to the global inbox in the message store.
+messaging\sms\multimode\clientmtm A plug-in to the message server framework to provide a generic API for creation of CDMA SMS messages (CDMA SMS Client MTM)
+messaging\sms\multimode\servermtm A plug-in to the message server framework to provide a generic API for sending of CDMA SMS messages (CDMA SMS Server MTM)
+
+3.1.2.3 Email
+The email plug-ins provide support the POP3, IMAP4 and SMTP email protocols and support for parsing and generating plain test, MIME and M-HTML format email messages.
+Component Description
+messaging\email\clientmtms A plug-in to the message server framework to provide a generic API for creation of email messages (IMAP4 SMTP and POP3 Client MTMs & email utilities)
+messaging\email\imapservermtm A plug-in to the message server framework to provide a generic API for access to a remote IMAP4 server (IMAP4 Server MTM)
+messaging\email\smtpservermtm A plug-in to the message server framework to provide a generic API for access to a remote SMTP server (SMTP Server MTM)
+messaging\email\popservermtm A plug-in to the message server framework to provide generic API for access to remote POP3 server (POP3 Server MTM)
+messaging\email\servermtmutils Email utilities for parsing plain text and MIME email messages. It also provides an abstraction of the TCP/IP sockets for use by the SMTP POP3 and IMAP4 plug-ins.
+messaging\email\autosend An executable that requests SMTP Server MTM to send messages in the outbox. This is used to provide send on next connection functionality and is started by the POP3 and IMAP4 Client MTMs.
+3.1.2.4 OBEX
+The OBEX MTM is a set of plug-ins to the message server that provides support for IR and Bluetooth beaming.
+Component Description
+messaging\obex\btmtm\btclient\group\btcmtm Bluetooth Client MTM
+messaging\obex\btmtm\btserver\group\btsmtm Bluetooth Server MTM
+messaging\obex\irmtm\irclient\group\ircmtm IR Client MTM
+messaging\obex\irmtm\irserver\group\IRSMTM IR Server MTM
+messaging\obex\obexmtm\obexclient\group\obexClientMtm OBEX Client MTM, base classes for the Bluetooth and IR Client MTMs
+messaging\obex\obexmtm\obexserver\group\obexServerMtm OBEX Server MTM, base classes for the Bluetooth and IR Server MTMs
+messaging\obex\obexmtm\obexutil\group\obexMtmUtil OBEX MTM utilities
+3.1.2.5 MMS
+The MMS MTM is a plug-in to the message server that provides support for MMS messages. From v9.0 and onwards MMS MTM and related components are removed.
+Component Description
+messaging\mms\utils MMS Utilities
+messaging\mms\servermtm MMS Server MTM
+messaging\mms\mmswatcherplugins MMS plug-ins to WAP push framework to handle reception of MMS notifications
+messaging\mms\codec MMS utilities for handling MMS codecs
+messaging\mms\clientmtm MMS Client MTM
+3.1.2.6 GMXML
+GMXML is a parser/generator for SMIL presentations for MMS messages.
+Component Description
+messaging\GMXML\XMLParser XML parser designed for parsing of SMIL messages
+messaging\GMXML\XMLDom XML document object model designed for parsing of SMIL messages
+messaging\GMXML\SMILdtd SMIL DTD
+3.1.2.7 Bio Message Plug-ins
+These parsers plug into the bio messaging framework to handle specific types of bio message.
+Component Description
+messaging\biomsg\cbcp\CBCP Compact business card parser
+messaging\biomsg\enp\ENP Email notification parser
+messaging\biomsg\gfp\gfp General file parser
+messaging\biomsg\iacp\IACP Nokia Smart Message Internet Access Parser
+messaging\biomsg\wapp\wapp Nokia/Ericsson OTA Parser
+3.1.2.8 PCMTM
+Plug-in to the message server that provided email synchronisation with a PC. This component has been deprecated in 8.0a and will not been documented in the API section below.
+3.1.2.9 Fax
+Plug-in to the message server that provides fax support. This component has been deprecated in 8.0a and will not been documented in the API section below.
+
+3.2 General Description
+3.2.1 Messaging / Message Server and MTM Architecture APIs
+3.2.1.1 Key Internal Relationships and Dependencies
+
+Figure 2 MTM Relationships
+Figure 2 shows the relationship between the Message Server and the MTM plug-ins. The grey classes are realisations of the MTM interfaces defined by the messaging framework. The message server depends on the Server MTM interface. Messaging Clients depend on the Client, UI and UI Data MTM interfaces and the Message Server Client API.
+3.2.1.2 Key External Relationships and Dependencies
+
+Figure 3 External Dependencies
+The grey package representing the messaging client depends on the Client, UI and UI Data interfaces and the Messaging Client API. The message server then depends on:
+• Charconv – Provides character set conversion routines, used to convert encoded message body text to Unicode body text.
+• EStore – Provides API to handle a stream based store used for the messaging index file and the framework classes for the message store files. (omitted from other dependency diagrams as it is implied by the dependency on the message server)
+• F32 – Provides the file server APIs used to access the file system directories in which messaging stores files containing message data. (omitted from other dependency diagrams)
+• BAFL – Provides API to load the correct messaging resource file dependent on the current language and to register the message store index file with the backup server. (omitted from other dependency diagrams)
+• ETEXT – Rich text APIs used to store body text of messages, this rich text format is a Symbian Proprietary format. (omitted from other dependency diagrams)
+• EUSER – Core Symbian OS utilities such as descriptors, arrays, client / server framework, cleanup stack and others (omitted from this and other dependency diagrams).
+• Central Repository – Centralised and secure storage facility for application settings, the message server stores message settings data in the central repository (from v9.0 and onwards).
+Note that debug only dependencies such as the flogger have been omitted from dependency diagrams.
+3.2.1.3 API Purpose - Further Elaboration
+3.2.1.3.1 Message Store
+The message server provides persistent storage of messages and messaging account settings. It does this by providing a message store consisting of a tree of message entries. Multiple clients can access the message store simultaneously. Each entry in the tree can represent an email account, folder of messages, message part, etc.
+
+Figure 4 Message Store
+Figure 4 shows an example message store. The tree is broken down in to three levels:
+1. The Root entry. This entry is just present to tie the tree structure together
+2. Service entries. There is one local service under which local folders and messages are stored, and zero or more remote services. Remote services represent message accounts.
+3. Message & Folder entries. Messages and folders, under the local service represent messages stored on the device. Messages and folders under remote services represent a local copy of messages that are present on a remote server. For example under a POP3 email service you would have copies of all the messages present on the POP3 email server, or under an SMS service you might find SMS messages that are stored on a SIM.
+The message server controls access to the entries in the store. It enforces the three levels therefore attempts to create message or folder entries directly under the root entry will fail.
+The message server provides three types of storage for each entry in the message store:
+• Index entry - TMsvEntry - intended to provide enough information for UI to display list views as shown in Figure 5. This consists of two strings and various flags (read, complete, has attachments etc).
+• Stream based file store - CMsvStore – provides storage of streams of data associated with UIDs. A standard UID is defined for storing body text. Other UIDs are specific. For example the email MTMs define a UID for storage of MIME headers. Compared to the index entry information this is used to store larger objects and is extensible, at the cost of being slower to access. From v9.0 and onwards CMsvStore provides an Attachment API for managing attachments. The Attachment API should be used as attachments can no longer be accessed directly due to Platform Security.
+• Directory of files – normally used for attachments.
+The only storage type that is always present is the index entry. The stream store and the directory of files are optional.
+
+Figure 5 Series 60 Inbox List View
+
+Figure 6 Remote and Local Entries
+As shown in Figure 6 the message store is split into two sets of entries:
+• Remote entries - entries that are representations of entries stored on a remote store .
+• Local entries - entries not linked to a remote store.
+The message server handles changes to local entries; internally it hands off changes to remote entries to the Server MTM that owns that service. Examples of operations that are handed off to Server MTMs are operations involving copying and moving messages to and from a remote service. See section 3.2.1.3.5 or more information on Server MTMs.
+Each entry within the store has a type:
+Folder – Messages can be grouped into folders. Standard folders such as inbox / outbox and user created folders.
+Message – Storage of the content of a message. Message entries can have child entries used to represent the structure of a message.
+Attachment – These represent attachments under a message entry.
+Root & Local Service Entry – There tie the tree structure together. However the Stream store associated with the root entry is sometimes used by UIs to store preferences e.g. default folder views etc.
+Remote Service - Represents a source and / or destination for messages. They are used to store the settings associated with the source / destination.
+Message Type Specific - MTMs can create other message types for use as child entries to messages they own. For example email uses a tree structure, with a message entry as the root, to represent the MIME structure of an email message; it uses folder entries to represent MIME folders and adds new types for entries representing the html body and text body parts of a message. This is shown in Figure 7.
+
+Figure 7 Email Message
+Using the message store to represent message structure allows reuse of the tree structure and makes it very simple to represent one message embedded in another. However this representation introduces performance issues as it results in each message having multiple files associated with it. The message server also keeps all index entries in memory; therefore this representation increases the memory footprint of the message server. Therefore when designing new MTMs we should think about moving away using multiple index entries to store one message in the message store.
+A default message store is created if the message server starts and no message store is present or a corrupt message store is present. The server will initially create a store with just a root entry, and then the server will create any standard folders defined in the resource file msgs.rsc. Finally the server will check whether an executable ‘mailinit.exe’ is present on the system, if it is present the server will launch the executable to allow customisation of the message store. The behaviour of ‘mailinit.exe’ is defined by the UI family of the device. However the typical behaviour is to load each of the UI Message Type Modules and allow each to perform any message type specific initialisation. For example the SMS plug-in typically creates a default service entry.
+
+3.2.1.3.2 Data File Storage (pre - v9.0)
+This section describes the files used by the message server before release v9.0. For information on the files used for release from v9.0 and onwards see section [3.2.1.3.3.1].
+Filename Access Purpose
+?:\system\Mail\index Private Message server index file, internal to message server
+?:\system\Mail\<8 hex digits> Shared via API Message server store files for services, clients access these via a messaging API.
+?:\system\Mail\<8 hex digits>.new Shared via API Temporary file used during committing message server store files.
+?:\SYSTEM\MAIL\<8 HEX DIGITS>_F\* Shared Files associated with a messaging service. These may be accessed directly by clients.
+?:\system\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits> Shared via API Message server store files for message entries, clients access these via a messaging API.
+?:\system\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits>.new Shared via API Temporary file used whilst committing message server store files.
+?:\system\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits>_F\* Shared Files associated with a message entry. These are accessed directly by clients.
+c:\system\data\msgs.ini Private Stores the drive containing the last used message store
+c:\system\Mtm\Mtm Registry v2 Private Cache of registered MTMs, internal to message server
+C:\system\data\sms_settings.dat Shared Copy of the SMS settings.
+?:\System\Mail\StoreInit.tmp Shared Created when message server runs ‘mailinit.exe’, ‘mailinit.exe’ should delete the file when it has successfully completed.
+?:\System\Mail\storedeleted.tmp Shared Created when message server finds and deletes a corrupt message store. Allows the UI to inform the user about the fact that the message store was corrupt.
+Files that are shown as private should only be accessed by the message server or by connectivity process for backup and restore purposes. Files listed as shared are accessed directly by messaging clients. Files listed as shared via API are accessed by client process but only via messaging APIs.
+3.2.1.3.3 Platform Security Compliant Message Store
+From v9.0 and onwards the message store is stored in the message server's data cage and the settings data are placed in the Central Repository. Access to the message store is only possible via message server APIs and not directly through file access. This leads to secured data storage and secured platform.
+3.2.1.3.3.1 Data caging
+Filename Purpose
+?:\private\<SID>\Mail\index Message server index file, internal to message server
+?:\ private\<SID>\Mail\<8 hex digits> Message server store files for services, clients access these via a messaging API.
+?:\ private\<SID>\Mail\<8 hex digits>.new Temporary file used during committing message server store files.
+?:\ private\<SID>\Mail\<8 hex digits>_F\* Files associated with a messaging service. These may be accessed directly by clients.
+?:\ private\<SID>\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits> Message server store files for message entries, clients access these via a messaging API.
+?:\ private\<SID>\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits>.new Temporary file used whilst committing message server store files.
+?:\ private\<SID>\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits>_F\* Files associated with a message entry. These are accessed directly by clients.
+c:\ private\<SID>\data\msgs.ini Stores the drive containing the last used message store
+c:\ private\<SID>\Mtm\Mtm Registry v2 Cache of registered MTMs, internal to message server
+?:\ private\<SID>\Mail\StoreInit.tmp Access via IPC call
+?:\ private\<SID>\Mail\storedeleted.tmp Created when message server finds and deletes a corrupt message store. Allows the UI to inform the user about the fact that the message store was corrupt.
+?\resource\messaging\bif\*.bif Registration data field with UID used in BIO framework
+
+3.2.1.3.4 How message centres display the message store
+The UI normally provides a Message Centre application to display the structure of the message store to the user. Different UIs map the structure to different views.
+
+Figure 8 Series 60 Message Centre (Composed from 2 screen shots)
+Figure 8 shows the top level view of the message centre application on a Series 60 phone. This shows that the message centre has hidden the local service and shows the standard folders at the same level as the services. Also the SMTP, SMS and MMS services are marked as hidden entries in the message store, and so do not appear in the message application.
+
+Figure 9 UIQ Message Centre
+However Figure 9 shows that the UIQ message centre has no 1-1 mapping from the structure in the message store to the structure shown to the user. Each of the message types is displayed as if its messages were contained in separate folders. Under each of these folders the user is presented with an inbox, outbox, send and drafts folder. This filtering is done in the UI layer as this functionality is not provided by the messaging API.
+3.2.1.3.5 Message Type Module Architecture
+
+Figure 10 Messaging MTM Structure (light coloured components are part of messaging subsystem)
+The MTM architecture is the plug-in scheme provided by the messaging framework to integrate different message transports into the message server. The plug-in scheme consists of four interfaces, the UI MTM, UI Data MTM, Client MTM and Server MTM. The messaging client applications loads and uses the first three which are loaded within the client’s process space. The final one the Server MTM is loaded within the message server process. The APIs for the client facing interfaces are extensible via run time type information provided by the QueryCapability API, and the InvokeAsyncFunction and InvokeSyncFunction APIs.
+3.2.1.3.5.1 UI MTM
+Handles requests from clients to view and edit messages or service settings. The MTM handles interaction with the message centre and as such the exact meaning of the APIs is defined by the UI. However common meanings are:
+• Create – Launches the editor with a new message.
+• Edit – If entry is a message this launches the editor; if entry is a service it edits the settings.
+• View – Launches the message viewer.
+• Display progress of an operation.
+3.2.1.3.5.2 UI data MTM
+This MTM provides fast access to UI components such as menu resources and bitmaps required by message centre for list views etc. Again the exact semantics are UI specific.
+There is a resource file defining UI specific functions, for example the Series 60 Messaging UI checks if the resource file contains text to display in the “New Message” menu.
+The UI data MTM also provides mapping from the message store’s TMsvEntry structure to Icons for the messaging list views and a status string, for example in the case of Nokia 9210 it is used in the outbox view to provide strings like “Resend 01:07” as shown in Figure 11. The class also provides functions to determine what operations are possible with a given entry. Examples of this are APIs that return whether the UI should allow the user to reply to the entry or to delete a service entry. The UI then uses this information to determine which menu options / short-cut keys should be allowed when the user selects a given entry.
+
+Figure 11 Nokia 9210 Outbox List View
+3.2.1.3.5.3 Client MTM
+Provides methods to create / reply and forward messages. Functions the Client MTMs provide are:
+• Create Message.
+• Reply to a Message.
+• Forward a Message.
+• Add / remove Addressees.
+• Add / remove body text.
+• Add / remove subject.
+• Add / remove attachments (the API cannot list attachments).
+The Client MTM interface is used by SendAs to provide a way of creating messages independently of the message type.
+3.2.1.3.5.4 Server MTM
+This is the final interface that makes up an MTM plug-in; it differs from the other three plug-ins in that it is loaded into the message server’s process space. The Server MTM provides access to messages under remote services. It handles connecting to remote servers to handle updating the local cache of these messages or to send messages copied to remote services when messages are copied to a remote service. The message server loads and hands off all message store operations that involve entries under a remote entry, these are the entries on the left-hand side of Figure 6.
+Functions that a Server MTM must implement:
+• Copy/MoveToLocal – called when the message server is asked to move or copy an entry that is currently under a remote service. A Server MTM might map this to retrieving a message from a remote mailbox.
+• Copy/MoveFromLocal – called when the message server is asked to move or copy from under the local service to a destination under a remote service. A Server MTM should map this to sending a message if the MTM supports sending.
+• Create, Delete, Change – called when the message server is asked to perform these operations on entries under a remote service.
+• StartCommand – this API provides a means of extending the API the Server MTM provides. Messaging clients pass a command ID and a selection of entries via the message server to the Server MTM. Examples of commands that Server MTMs might provide are: connect and synchronise the entries under a remote service with the messages on an email server, list SMS messages present on the phones SIM. These commands are MTM specific and therefore clients have to know which MTMs support which commands.
+3.2.1.3.5.5 MTM Registration
+MTMs must be registered with the message server so that clients can query what MTMs are present and the server knows which DLL to load to create a given MTM component. MTMs are registered by providing a resource file containing the MTMs UIDs, human readable name, and for each MTM interface it lists a DLL and the ordinal at which the constructor for that interface exists. The message server will search the ROM drive for MTM registration resource files on start-up and it will automatically register any MTMs found. For registration of MTMs installed on other drives, the message server provides an API to register and de-register an MTM. Registration will persist across a reboot, so an MTM only needs to be registered when it is installed on the system.
+When MTMs are registered or unregistered the message server will send events to all messaging clients with a message server session open.
+3.2.1.3.6 Message Server Client API
+The Messaging Server Client API breaks down into two categories: APIs for manipulation of the message store and utility APIs.
+3.2.1.3.6.1 Message Store manipulation APIs
+Requests from clients to modify the message store fall into three categories:
+1. Operations performed entirely with local entries (entries on the right-hand side of Figure 6) for example requests to create entries in the inbox, delete an entry from the drafts folder etc. The message server handles these operations directly.
+2. Operations that involve a remote entry (entries on the left-hand side of Figure 6) for example requests to delete an entry under a POP3 service, or copy a message to an SMTP service. The message server hands these operations off to the Server MTM that owns the service under which the remote entry is stored. The only exception to this rule is the ChangeAttributes API call. This modifies flags on an index entry and is handled by the message server for both local and remote entries. This means that a Server MTM can not rely on being called when flags like the Unread flag are changed. Note that operations can not involve two remote entries; therefore requests to copy entries between a remote service representing one POP3 account to a remote service representing another POP3 account will fail with an error.
+3. Requests that are explicitly directed at a Server MTM via the TransferCommand API. These commands are just passed to the correct Server MTM by looking up the Service ID and MTM of the first message in the selection passed into the command.
+The message server sends events when entries in the message store are modified to messaging clients that have a session open with the server.
+Where the API provides asynchronous functions to modify the message store or transfer a command to a Server MTM, the functions will return a message server operation object. This object can be used to request progress on operation or cancel the operation. Deleting the operation object returned, or closing the session used to make the request will result in the operation being cancelled, therefore a messaging client must remain running until operations it has requested have either completed or they will be cancelled. See appendix A.1 for an example of an asynchronous copy operation. If a Server MTM operating on the same remote service is already handling an operation, the message server will queue the new operation to be handled when the Server MTM becomes free. Requests for progress of operations that are queued will fail with KErrNotReady. The fact that the queue is based on the remote service ID means that you can have two Server MTMs of the same type running at the same time as long as they are operating on different services. So for example you can have two separate POP3 MTMs running synchronising different remote services with email servers.
+3.2.1.3.6.2 Utility APIs
+1. Access to MTM registries – These allow clients to construct instances of the interfaces an MTM implements.
+2. Register / Unregister an MTM.
+3. Change Drive – The message server closes the current message store and opens one on the drive specified. If no message store is present on the drive specified a new message store is created. The message sever can have only one mail store open at a time, if the current mail store is not available because a the disk the mail store is on is not present then the message server will switch the mail store back to the C: drive if an attempt is made to create a message in the inbox.
+4. Launching Editors – This launches the correct editor for a message. It is implemented by delegating the request to the UI MTM
+3.2.2 Messaging / Send As APIs
+3.2.2.1 Key Relationships and Dependencies
+
+Figure 12 SendAs Version 1 Dependencies
+SendAs version 1 and only present in releases before v9.0. SendAs uses the Messaging Client API to access the registry of Client MTMs and construct the Client MTM interfaces. The Client MTMs are then used for composing the message. SendAs requires clients to implement the MSendAsObserver interface. This interface is responsible for checking the return value of the capability queries made to Client MTMs that require a response and also for rendering message types that require it. The only message type supplied by Symbian that requires rendering is Fax, however this MTM has been removed in 8.0a and future releases.
+3.2.2.2 API Purpose - Further Elaboration
+3.2.2.2.1 SendAs API (pre – v9.0)
+The SendAs API makes use of the Client MTM interface and the Messaging Client API to provide a generic API for creating messages. Note despite the name of this component SendAs does not provide an API to send the message.
+SendAs builds a list of registered MTMs, then queries each MTM to check whether it supports sending, removing those MTMs from the list that do not support sending. This list is then provided to the messaging client application. At this point the application can add more constraints on the list of MTMs; for example it can insist the MTM supports Attachments or more than a certain size of body text. SendAs queries each of the MTMs about the requirements and will drop any MTMs from the list that does not meet them. When the application has finished adding requirements it selects one of the MTMs left in the list and uses that to compose the message, adding addresses, a subject, body text and attachments.
+SendAs supports setting a BIO Type for the message that is composed. This tells the transport that the body text represents a BIO Message. This is used when sending business cards from the contacts application as SMS messages; the contacts application puts the vCard data in the body text of the message and the transport sends it correctly. If the MTM in question supports attachments then the vCard is attached to the message.
+A new CSendAs object must be created for each message the application wishes to create.
+3.2.3 Platform Security Compliant SendAs Server (v9.0 onwards)
+
+Figure 13 SendAs Version 2 Dependencies
+From v9.0 and onwards the CSendAs has been replaced by the SendAs server component. The new SendAs server controls the access to the message store. Some of the key SendAs Server features are listed as follows.
+• Send a message once the capability policing of the client application has been completed.
+• Allow client applications to launch an editor for a specified message type.
+• Allow client applications to query the message type.
+The main client-side API is the RSendAs class. The client applications use this to connect to the Send-As server. The session object on the server-side is an instance of CSendAsSession.
+Client applications create messages using the RSendAsMessage API. Opening an RSendAsMessage object on Send-As server session creates a CSendAsMessage object in the Send-As server. There is a one-to-one mapping between an RSendAsMessage object and a CSendAsMessage object. This allows client applications to create multiple messages concurrently.
+
+3.2.4 Messaging / Schedule Send APIs
+3.2.4.1 Key Relationships and Dependencies
+
+Figure 14 Schedule Send Dependencies
+The Schedule Send Server MTM base class depends on the task scheduler to launch the schedule send executable at the correct time. To send the message with a package of data previously passed into the task scheduler by the Server MTM. The schedule send executable then uses the Messaging Client API to actually perform the requested operation.
+3.2.4.2 API Purpose - Further Elaboration
+3.2.4.2.1 Schedule Send
+The Schedule Send functionality is delivered by four components:
+Server MTM Base Class – The base class provides support to Server MTMs that wish to support scheduled operations.
+Data Structures – These are classes used to represent the data associated with a scheduled operation.
+Executable – The executable is run by the task scheduler at the scheduled time.
+The Task Scheduler – This component is part of the system libraries subsystem. Currently the SMS and Fax Server MTMs support scheduled sending.
+Clients request the Server MTM schedules operations via additional commands passed to TransferCommand API; this is passed to the Server MTM via the message server. The Server MTM packages the operation ID, a selection of message IDs, how often to poll for progress and an MTM specific buffer. It then passes this package of data to the task scheduler requesting that it launches the schedule send executable at the correct time with the packaged information.
+When the task scheduler launches the schedule send executable, it unpacks the schedule information and uses the Messaging Client API to request the Server MTM to perform the operation.
+Schedule Send supports a retry mechanism if the operation fails. The Server MTM has a resource file containing a mapping from the error codes the operation can fail with and actions to be performed. For example the SMS resource file has a mapping such that if the operation fails with an error code indicating a bad phone number the SMS will be set to failed and left in the outbox. Whereas if it fails with a error code indicating temporary network failure the send operation will be scheduled to be resent later with a maximum of three retries.
+3.2.5 Messaging / Watchers APIs
+3.2.5.1 Key Relationships and Dependencies
+
+Figure 15 Watcher Dependencies
+The watcher executable’s dependency on the message server is the result of a performance measure. The watcher process creates a message server session before initialising each of the watcher plug-ins and closes the session when it has finished. This keeps the message server running during initialisation avoiding starting and stopping the message server if each watcher plug-in opens and closes sessions.
+3.2.5.2 API Purpose - Further Elaboration
+The watcher framework consists of an executable that is launched when the device boots. The component that is responsible for launching it depends on the UI family. When the watcher.exe is launched it will load each DLL in z:\system\libs\watchers which has a second UID as KWatcherUid and calls the first DLL entry point to construct a CActive object.
+From v9.0 and onwards watcher DLLs are found by scanning the directory \resource\messaging\watchers for registry files. These files contain the name of a watcher DLL that can be loaded from ROM i.e. z:\sys\bin.
+The framework has retry behaviour if the first entry point leaves, in this case the watcher framework will start a timer and try and construct the watcher object 10 seconds later. Five attempts are made before the watcher plug-in is assumed to have failed completely. Once the watcher framework has constructed all the watchers it starts the active scheduler which should never exit.
+Watcher plug-ins typically make a request to another subsystem such that they will be completed when an external event like a fax line ringing or an SMS being received occurs. When the watcher has completed processing the request it will wait for the next event.
+No support for starting / stopping watchers is provided. This is a limitation that makes watchers unsuitable for operations like listening for messages beamed via IR, as the watcher should only run while the IR port is active.
+3.2.6 Messaging / Message URL Handler APIs
+3.2.6.1 Key Relationships and Dependencies
+
+Figure 16 Message URL Handler Dependencies
+3.2.6.2 API Purpose - Further Elaboration
+The Message URL Handler provides support for creating messages and launching messaging editors from URLs such as mailto:infobot@example.com?subject=current-issue. Note there is no dependency between the Message URL Handler application which processes the URLs and the Message URL Handler recognisers which maps from URLs to mime types.
+3.2.6.2.1 Message URL Handler Application
+This is a Symbian OS application that registers with the application framework that it can handle the mime types: x-epoc-url/fax, x-epoc-url/mailto and x-epoc-url/sms. When launched with a URL it will parse the URL to retrieve the address and other header fields and then use the SendAs API to create a new message with the correct address, headers etc. The application then uses the APIs in the MturUtils class provide by the mtmbase component in the messaging framework to launch the correct editor for the given message type. The application is marked as hidden and therefore should not be listed by UIs in application browsers.
+3.2.6.2.2 Message URL Recognisers
+This is a plug-in to the recogniser framework it will be called when the application framework wishes to recognise a file. Recognisers are called with the file name, in this case a URL, and a buffer containing the start of the file. The message URL recogniser compares the start of the URL with the URL schemes it recognises, if it finds a URL scheme it knows about it maps it to a mime type. The recogniser ignores the buffer passed in.
+Schemes recognised:
+Scheme Mime type
+mailto: X-Epoc-Url/mailto
+fax: X-Epoc-Url/fax
+sms: X-Epoc-Url/sms
+mms: X-Epoc-Url/mms
+See the application framework architectural description for more information on recognisers [R2].
+3.2.7 Messaging / SMS APIs
+3.2.7.1 Key Internal Relationships and Dependencies
+
+Figure 17 SMS Internal Dependencies
+3.2.7.2 Key External Relationships and Dependencies
+
+Figure 18 SMS External Dependencies
+3.2.7.3 API Purpose - Further Elaboration
+3.2.7.3.1 SMS Watchers
+The SMS watchers are made up of two watchers, the nbswatcher.dll and the wapwatcher.dll, and some common base classes in biowatcher.dll. The watchers listen for incoming messages from the SMS stack, part of the nbsprotocols subsystem [R3], and the WAP stack part of the WAP-Stack subsystem [R4].
+3.2.7.3.1.1 NBS Watcher
+The NBS watcher handles reception of SMS messages. When initialised by the watcher framework (see section 3.2.4) the watcher queries the bio messaging database for bio messages that are listed as having a type of ENbs. For each of these bio messages the watcher creates an object that opens a connection to the SMS stack and waits for the particular message type. The message types are either defined by the port number the message will be received on or by a string to watch for at the start of the message. For example Internet Access Configuration Point messages are start with “//SIAP11” and vCards are received on port 226. Finally the watcher listens for all other messages received from the SMS stack.
+When the NBS Watcher receives a non-class 2 SMS message it creates a new entry under the global inbox in the message store. For class 2 messages the entry is created in the class 2 folder as defined by the SMS settings, this may also be the global inbox. The details field of the entry is used to store the phone number of the incoming message or the name of the sender if the watcher finds a match for the phone number in the contacts database. The description field is used to store the first N characters of the SMS message, where N is defined in the SMS settings, or for bio messages the description as retrieved from the bio database. Bio messages also have the BioType field set to the UID of the bio message as retrieved from the bio database. The CSmsHeader class, which is a wrapper around the CSmsMessage class provided by the nbprotocols subsystem [R3], is used to externalise the SMS message to the entry’s CMsvStore. The watcher also places a copy of the body text of the message in the rich text stream of the entry’s CMsvStore.
+The NBS Watcher is also responsible for handing special SMS types including:
+• Replace Type Messages – When the watcher receives a message of this type it will scan the folder the message would have been delivered to for messages that have a matching protocol ID and from address. For each of the messages it checks whether the time stamps from the service centre and discards the older message.
+• Message Indications – The watcher can listen for incoming message waiting indications. The CSmsSettings class defines whether the watcher will listen and whether it will deliver the messages to the inbox or discard them. If the watcher is configured to listen for messages then it will use the SMS utilities in the SMS Client MTM to decode the message to determine the notification type and number of messages, e.g. 3 Email messages waiting, the strings for these messages are in the smss.rss resource file.
+• Delivery Reports – As with Message Indications the watcher can be configured to listen for these and again the SMS utilities get a string from the smss.rss resource file to put in the description field.
+The NBS Watcher handles changes to the bio database using the observer mechanism provided by the bio message database to observe when bio message types are added or removed and starting or stopping the object watching for that bio message type.
+3.2.7.3.1.2 WAP Watcher
+The WAP watcher listens for incoming messages from the WAP stack using the WAP message API [R4]. To determine ports to use to listen for messages the watcher queries the bio message database for bio message types EWsp, EWspSecure, EWap, EWapSecure and registers as an observer of the bio database and so will listen for new bio message with these types as they are added. The watcher stores the messages in the global inbox tagged with the bio type listed in the bio message database.
+3.2.7.3.2 SMS Client MTM
+The SMS Client MTM implements the standard set of Client MTM APIs described in Client MTM. In addition it provides:
+• Access to the CSmsHeader object that is used to represent the SMS message.
+• Access to the SMS settings stored in the associated SMS service.
+• The APIs required by Send As to allow Send As to create SMS messages including setting the bio type of the message to allow clients of Send As to send bio messages such as vCards and vCals. The data of the bio message is stored in the body text of the SMS message.
+• Simple check for valid SMS addresses, and SMS address is considered valid if it contains at least one digit.
+• Reading and writing SIM parameters.
+3.2.7.3.3 SMS Utilities
+These provide:
+• Classes to represent and store SMS messages (CSmsHeader), and SMS settings (CSmsSettings, CSmsMessageSettings) and a SMS number (CSmsNumber).
+• The CSmsHeader class contains and allows clients to access the CSmsMessage class that the nbsprotocols subsystem provides. This contains the entire SMS message and not just the header.
+• Functions to generate descriptions and details fields to store with SMS messages, including decoding special messages such as message indication and status report messages, reading resource file for descriptions strings of special messages, using the contacts database to replace phone numbers with names.
+• API to validate a GSM number.
+• Find the TMsvId of the SMS service entry.
+3.2.7.3.4 SMS Server MTM
+3.2.7.3.4.1 Sending Messages
+The SMS Server MTM handles sending of SMS and WAP messages via the SMS stack and the WAP stack. To support this it implements the CopyFromLocal API inherited from the Server MTM base class. It implements this as sending SMS messages and moving successfully sent messages to the Sent folder. When sending the SMS message the Server MTM checks the bio type of the message and uses the bio database to check the transport type for the bio message. The MTM supports ENbs that is sent via the SMS stack and EWap, EWapSecure that are sent via the WAP stack. The MTM does not support EWsp or EWspSecure although the watchers do support receiving them.
+If a message fails to send, sending is retried according to the settings in the smss.rss resource file as described in the schedule send section 3.2.3.
+3.2.7.3.4.2 Scheduling Messages
+The SMS Server MTM implements scheduled sending API by sub-classing from the schedule send Server MTM (see section 3.2.3). It accepts requests from clients either via the SMS Client MTM InvokeAsync API or via the CMsvSession::TransferCommand API to schedule messages to be sent or to delete existing schedules. When it receives a request to schedule a message it packages up the command and uses the scheduled send functionality to request that the task scheduler ask it to send the messages at a future point in time.
+3.2.7.3.4.3 Phone Store
+The phone store is the name given to storage of SMS messages outside of the message store. In the case of GSM phones this is the SIM. The SMS Server MTM accepts requests from clients to copy/move messages to and from the SIM and delete messages from the SIM. For example when copying to the SIM it packages up the SMS message and passes it to the SMS stack with a request to write it to the SIM. If the class2 folder has been set in the SMS settings class then the Server MTM will copy the SMS message to the SIM and then update the SMS message in the message store with details of the slot on the SIM that has been used to store the SMS and the fact that it is stored on the SIM.
+3.2.7.3.4.4 SIM Parameters
+The Server MTM provides functions to read / write SIM parameters, again these requests are passed to the SMS stack to be processed.
+3.2.8 Messaging / CDMA SMS APIs
+3.2.8.1 Key Internal Relationships and Dependencies
+
+Figure 19 CMDA SMS Internal Dependencies
+3.2.8.2 Key External Relationships and Dependencies
+`
+Figure 20 CDMA SMS External Dependencies
+3.2.8.3 API Purpose - Further Elaboration
+3.2.8.3.1 CDMA SMS Watchers
+The CDMA SMS watchers are made up of six watchers, the cdmanbswatcher.dll, vmnwatcher.dll, wemtwatcher.dll, wmtwatcher.dll, wptwatcher.dll, and the wapwatcher.dll, and some base classes in biowatcher.dll and cdmasocketwatcher. While the WAP watcher is common for both GSM and CDMA, the other watchers: CDMA NBS watcher, VMN watcher, WEMT watcher, WMT watcher, and the WPT watcher are used for CDMA only. The watchers listen for incoming messages from the CDMA SMS stack, part of the nbsprotocols subsystem [R3], and the WAP stack part of the WAP-Stack subsystem [R4].
+3.2.8.3.1.1 CDMA NBS Watcher
+The CDMA NBS watcher is similar to the NBS watcher and it handles bio messages defined in bio database. The CSmsHeader class is extended to wrap around the CCdmaSmsMessage class provided by the nbprotocols subsystem [R3], and is used to externalise the CDMA SMS message.
+For handling special CDMA SMS type, the CDMA NBS watcher is responsible for handling Message Indications as described in section 3.2.7.3.1.1 NBS Watcher.
+3.2.8.3.1.2 WAP Watcher
+The GSM WAP watcher is used to handle CDMA WAP message as well. The WAP watcher listens for incoming messages from the WAP stack, which can listen from the CDMA SMS stack or GSM SMS stack as appropriate. See 3.2.7.3.1.2 for more info about WAP watcher.
+3.2.8.3.1.3 Other CDMA Watchers
+The VMN watcher, WEMT watcher, WMT watcher and WPT watcher are CDMA watchers that handle reception of CDMA SMS messages. All CDMA SMS messages are associated with a teleservice. Therefore, each of the CDMA watchers is responsible for handling one teleservice: VMN watcher handles VMN SMS messages, WEMT watcher handles WEMT SMS messages, WMT watcher handles WMT SMS messages, and WPT watcher handles WPT SMS messages. The CSmsHeader class is reused to externalise the CDMA SMS message.
+The CDMA watchers are also responsible for handling special SMS types including:
+• Duplicate Message – When the watcher receives a duplicate message, it will discard the duplicate message as defined by the CDMA service settings.
+• User Acknowledge – The watcher can listen for user acknowledgment message of its teleservice type.
+• Delivery Acknowledge – The watcher can listen for delivery acknowledgment message of its teleservice type.
+• Read Acknowledge – The watcher can listen for read acknowledgment message of its teleservice type.
+3.2.8.3.2 CDMA SMS Client MTM
+The CDMA SMS Client MTM implements the standard set of Client MTM APIs described in Client MTM. In addition it provides:
+• Access to the CSmsHeader object that is used to represent the SMS message.
+• Access to the SMS settings stored in the associated SMS service. These settings are store in file store pre v9.0 but stored in Central Repository from v9.0 onwards.
+• The APIs required by Send As to allow Send As to create SMS messages including setting the bio type of the message to allow clients of Send As to send bio messages such as vCards and vCals. The data of the bio message is stored in the body text of the SMS message.
+• Simple check for valid SMS addresses, and SMS address is considered valid if it contains at least one digit.
+• Reading and writing SMS messages to R-UIM.
+3.2.8.3.3 CDMA SMS Utilities
+The CDMA version of SMS utilities are binary compatible with the GSM version of SMS utilities. But the classes that store SMS Message (CSMSHeader), and SMS settings (CSmsSettings, CSmsMessageSettings) and SMS number (CSmsNumber) are extended to store CDMA information. The CSmsHeader class is extended to contain and allow clients to access the CCdmaSmsMessage in addition to the CSmsMessage. Other functions provided by the GSM SMS Utilities is also provided by the CDMA version of SMS utilities, see 3.2.7.3.3 for information about GSM SMS Utilities.
+3.2.8.3.4 CDMA SMS Server MTM
+3.2.8.3.4.1 Sending Messages
+The CDMA SMS Server MTM handles sending of CDMA SMS and WAP messages via the CDMA SMS stack and the WAP stack. To support this it implements the CopyFromLocal API inherited from the Server MTM base class. It implements this as sending SMS messages and moving successfully sent messages to the Sent folder. When sending the CDMA SMS message the Server MTM will use the appropriate teleservice type. The MTM supports ENbs that is sent via the SMS stack and EWap, EWapSecure that are sent via the WAP stack. The MTM does not support EWsp or EWspSecure although the watchers do support receiving them.
+If a message fails to send, sending is retried according to the settings in the smss.rss resource file as described in the scheduled send section 3.2.4.
+3.2.8.3.4.2 Scheduling Messages
+The CDMA SMS Server MTM implements scheduled sending API by sub-classing from the schedule send Server MTM similar to implemented in the GSM SMS Server MTM. See 3.2.7.3.4.2 for more information.
+3.2.8.3.4.3 Phone Store
+In the case of CDMA phones, phone store can be phone-based storage or R-UIM based storage. The CDMA SMS Server MTM accepts requests from clients to copy/move messages to and from the phone/R-UIM and delete messages from the phone/R-UIM. For example when copying to the R-UIM it packages up the SMS message and passes it to the CDMA SMS stack with a request to write it to the R-UIM.
+3.2.8.3.5 Configuration for using CDMA SMS MTM
+The CDMA messaging components currently only support single mode, but it is designed such that it can become multimode in the future. Currently, -Dcdma option is used to for selecting CDMA mode for using emulator and building ROM.
+
+
+3.2.9 Messaging / Email APIs
+3.2.9.1 Key Internal Relationships and Dependencies
+
+Figure 19 Email Internal Dependencies
+
+3.2.9.2 Key External Relationships and Dependencies
+
+Figure 20 Email External Dependencies
+3.2.9.3 API Purpose - Further Elaboration
+3.2.9.3.1 Email Overview
+The Email plug-ins consist of a set of utilities and MTMs for POP3, IMAP4 and SMTP. For each email account a pair of services entries is created in the message store. For a POP3 account there will be an SMTP service and a POP3 service, for an IMAP4 account there will be an SMTP service and as IMAP4 service. These entries are used to store the settings for the email transport. Each of the service entries has its related ID set to the other member of the pair. The SMTP service is created invisible so the user only sees the POP3 or IMAP4 service entry, copying a message to the SMTP service will cause the SMTP Server MTM to attempt to send the message. The POP3 and IMAP4 MTMs provide functionality to synchronise with a remote email server this is achieved by extending the Client MTM interface via the InvokeAsync API. Synchronisation of a POP3 or IMAP4 account will result in copying headers and optionally body text and attachments from the email server and creating message entries under the POP3 or IMAP4 service entry.
+Email messages are represented in a common format whether they are being sent via SMTP or downloaded via POP3 or IMAP4. The email client utilities provide the classes for creating and manipulating the entry structure used to store emails. The email server side utilities provide classes to convert between the entry structure used to store emails in the message store and RFC2822 email messages sent to SMTP servers and retrieved from POP3 servers. IMAP4 email messages are parsed by the email server and the IMAP4 Server MTM requests and stores the individual parts of the messages.
+3.2.9.3.2 Email Client Utilities
+The email client utilities are part of the imcm DLL and provide classes for:
+• Storage of email messages including mime headers, RFC2822 headers, attachments, body text and encoding information in the message store
+• Manipulating email messages, for example adding attachments, replying etc.
+• To wrap up the character converters used to convert between standard character sets and Unicode. These make use of the charconv component that is part of the system libraries subsystem.
+• Storage of Email settings in the message store.
+• Progress information for email operations.
+The utilities are used directly by clients to access parts of email messages for display. CImEmailMessage provides the functionality used by clients displaying email messages, including listing attachments, getting body text and resolving URIs in M-HTML messages.
+The Email Client MTMs use the utilities when they are asked to create, reply to and forward messages CImEmailOperation provides the functionality to perform these operations. Each email message is represented by a parent message entry and then entries to represent mime folders and mime parts, see Figure 7 for an example, so adding or deleting mime parts involves walking the tree of entries and inserting / removing entries as appropriate.
+3.2.9.3.3 Email Server MTM Utilities
+The Email Server MTM Utilities are responsible for generating and parsing of RFC2822 format email messages and providing an API to wrap up a TCP/IP connection to a remote email server.
+• Parsing of RFC2822 Email Messages – The utilities provide an API that accepts the text of an RFC2822 email message a line at a time and stores the email message in messaging’s internal format for email messages. See the Email Client Utilities for details of this format. The API handles storing of RFC2822 headers, MIME headers, decoding of Base64 encoded or uuencoded attachments and decoding of text received in character sets supported by the charconv component. This API is only accessible to Server MTMs, as it requires classes that can only be instantiated while running within the message server process. See the Messaging Functional Specification [R1] for detail on which email specifications the utilities support.
+• Generation of RFC2822 Email Messages – The utilities provide an API to convert an email in messaging’s internal format into an RFC2822 email message. The API provides access to the RFC2822 text a line at a time for streaming to an SMTP server. The exact format of the email depends on the settings passed in; the API can generate plain RFC2822 email messages with uuencoded attachments, MIME email messages with Base64 encoded attachments, or M-HTML email messages with Base64 encoded attachments. See the Messaging Functional Specification [R1] for detail on which email specifications the utilities support.
+• TCP/IP socket wrapper – The utilities provide a class that abstracts a TCP/IP socket supplied by the networking subsystem into an API that supports sending and receiving lines of text to / from a remote server. This API is used to connect to remote email servers by each of the email Server MTMs. The API can either create insecure or secure sockets enabling the SSL encryption provided by the networking subsystem. It also supports changing an insecure socket into a secure socket, this enables the email Server MTMs to implement email protocols where the initial connection to the server is insecure and then a secure socket is negotiated before sending or requesting any sensitive information.
+3.2.9.3.4 POP3 MTMs
+The POP3 MTMs implements the functionality to synchronise the local message store with a remote POP3 email server.
+3.2.9.3.4.1 Client MTM
+The POP3 Client MTM implements the standard Client MTM APIs and other extensions:
+• Reply to, forward – These are accessible via the ReplyL and ForwardL APIs of a Client MTM and are implemented as calls to the email utilities class CImEmailOperation.
+• Reply to, forward, create new messages, create receipts and forward as attachment – These are accessible as commands available via the InvokeAsyncFunction API of the Client MTM, they are implemented as calls to CImEmailOperation.
+• Connecting, disconnecting and copying email while connected – These operations are accessible as commands available via the InvokeAsyncFunction API of the Client MTM, they are implemented as calls to the POP3 Server MTM.
+• Querying connection status – This command lets clients know whether the POP3 Server MTM is connected to an email server, and is available via the InvokeAsyncFunction API of the Client MTM. The Client MTM requests the information from the Server MTM.
+• Compound operations – The Client MTM provides functionality to wrap up connecting to email servers, copying / moving new messages or a selection of messages, and then optionally disconnecting. These commands are available via the InvokeAsyncFunction API of the Client MTM. The Client MTM implements this by using the CImPOP3GetMail class which requests the correct sequence of operations from the Server MTM, waiting for each operation to complete before requesting the next one.
+• Send on next connection If the Client MTM gets a request to connect to an email server it will check whether the POP3 settings. If send on next connection is requested it will launch the autosend.exe executable (see section 3.2.7.3.7) to handle sending messages waiting in the outbox.
+• Offline operations – The POP3 Client MTM has a command to cancel offline operations, this is available via the InvokeAsyncFunction API of the Client MTM. The Client MTM passes the request to the Server MTM.
+3.2.9.3.4.2 Server MTM
+The POP3 Server MTM handles the communication with the remote POP3 server and implementation of the POP3 protocol. The MTM uses CImTextServerSession to handle the communication with the email server and CImRecvConvert to parse the email messages downloaded, both are provided by the Email Server MTM Utilities.
+• Connect – The POP3 Server MTM will open a socket to the email server using CImTextServerSession and login user the username / password in the POP3 settings. After a successful connection the Server MTM will attempt to synchronise the current state of headers stored on the email server with the set stored in the message store and then start any pending offline operations. After the connect operation has completed the Server MTM will inform the message server that it is expecting more operations via the CommandExpected API and therefore the message server will not delete and unload the Server MTM.
+• Populate Message – The POP3 Server MTM treats requests to copy a message from and to the POP3 service as a request to download the full message.
+• Offline operations – When the POP3 Server MTM receives a request to copy, move, or delete and is not connected to a POP3 email server the Server MTM will store the operation in the CMsvStore of the entry being modified and perform the operation on the next connection to the email server.
+• Disconnect – When disconnecting from a remote email server the POP3 MTM will run any pending offline operations stored. After the disconnect operation completes the Server MTM will allow the message server to delete and unload the Server MTM by setting the CommandExpected API to false.
+3.2.9.3.5 IMAP4 MTMs
+The IMAP4 Server MTM implements the functionality to synchronise the local message store with a remote IMAP4 email server.
+3.2.9.3.5.1 Client MTM
+The IMAP4 Client MTM implements the standard Client MTM APIs and other extensions:
+• Connecting, disconnecting, synchronising, un/subscribing folders – These operations are accessible as commands available via the InvokeAsyncFunction API of the Client MTM, they are implemented as calls to the IMAP4 Server MTM.
+• Send on next connection – If the Client MTM gets a request to connect to an email server it will check whether the IMAP4 settings. If send on next connection is requested it will launch the autosend.exe executable (see section 3.2.7.3.7) to handle sending messages waiting in the outbox.
+• Reply to, and forward messages – These are accessible via the ReplyL and ForwardL APIs of a Client MTM and are implemented as calls to the email utilities class CImEmailOperation.
+• Reply to, forward, create new, create receipt, forward as attachment – These are accessible as commands available via the InvokeAsyncFunction API of the Client MTM, they are implemented as calls to CImEmailOperation.
+• Querying connection status – These commands let clients know whether the IMAP4 Server MTM is connected to an email server and whether it is currently processing a request. They are available via the InvokeAsyncFunction API of the Client MTM. The Client MTM requests the information from the Server MTM.
+• Compound Connection and synchronisation – The IMAP4 Client MTM provides a compound operation that connects and synchronises with an IMAP4 server. This operation is implemented as a client side object that combines requests to the IMAP4 Server MTM. The client side operation can complete the client request either after the connection, after the connection + sync or after the connection + sync + disconnect. The client will keep requesting that the inbox be resynchronised at a configurable interval so new messages received in the inbox on the server will appear under the IMAP4 inbox. The CImapConnectAndSyncOp class handles these compound operations.
+• Compound Connect and copy / move / populate messages – The IMAP4 Client MTM provides a compound operation that connects to an IMAP4 server and copies moves or populates messages. The implementation is provided by the CImImap4GetMail class which makes calls back into the IMAP4 Client MTM.
+• Offline operations – The IMAP4 Client MTM has a command to cancel offline operations, this is available via the InvokeAsyncFunction API of the Client MTM. The Client MTM passes the request to the Server MTM.
+3.2.9.3.5.2 Server MTM
+The IMAP4 Server MTM handles the communication with the remote IMAP4 server and implementation of the IMAP4 protocol. The MTM uses CImTextServerSession to handle the communication with the email server. The IMAP4 Server MTM opens two connections to the IMAP4 server this enables users to download messages while the Server MTM is performing a background synchronisation if requested by the Client MTM.
+• Connect – The IMAP4 Server MTM will open a socket to the email server using CImTextServerSession and login using the username / password in the IMAP4 settings. After a successful connection the Server MTM will optionally attempt to synchronise the current state of headers stored on the email server with the set stored in the message store and then start any pending offline operations. After the connect operation has completed the Server MTM will inform the message server that it is expecting more operations via the CommandExpected API and therefore the message server will not delete and unload the Server MTM.
+• Copy, Move messages – The IMAP4 Server MTM supports copying and moving messages between folders on the IMAP4 server and between the IMAP4 server and local folders.
+• Delete messages – The IMAP4 Server MTM will mark the email as deleted on the server; however it will not be deleted until the IMAP4 Server MTM disconnects from the server.
+• Folders – The IMAP4 Server MTM will allow folders to be subscribed, unsubscribed, renamed, copied, moved, and created within the IMAP4 service. Subscribing to a folder means that it will be visible to the user and synchronised with the remote server. The inbox is always subscribed.
+• Offline operations – When the IMAP4 Server MTM receives a request to copy, move, or delete and is not connected to an IMAP4 email server the Server MTM will store the operation in the CMsvStore of the entry being modified and perform the operation on the next connection to the email server.
+• Disconnect – When disconnecting from a remote email server the IMAP4 MTM will run any pending offline operations stored. After the disconnect operation completes the Server MTM will allow the message server to delete and unload the Server MTM by setting the CommandExpected API to false.
+
+3.2.9.3.6 SMTP MTMs
+The SMTP MTMs provide functionality to send email messages. They are made up of the Client MTM that is part of the imcm DLL and the Server MTM.
+3.2.9.3.6.1 Client MTM
+The SMTP Client MTM implements the standard Client MTM APIs including the functions required to allow clients of Send As to create email messages.
+3.2.9.3.6.2 Server MTM
+The SMTP MTMs provide functionality to send email messages; it interprets requests to copy entries to an SMTP service as a request to send those messages. In addition it responds to two extended commands via the StartCommand Server MTM interface. These commands are KSMTPMTMIsConnected that responds with whether the Server MTM is currently connected to a remote SMTP server and KSMTPMTMSendOnNextConnection which performs the same operation as copying a selection of messages to an SMTP service. The only difference between the copy operation and the KSMTPMTMSendOnNextConnection operation is that the latter can be called without a selection of messages.
+When the Server MTM receives a request to send messages it builds a selection of messages consisting of the messages passed into the operation and any messages waiting in the outbox to be sent. To determine which messages in the outbox are waiting to be sent the SMTP server checks for messages that have the same service ID as the destination of the send operation and have a sending state of KMsvSendStateWaiting, KMsvSendStateScheduled or KMsvSendStateResend. This means that any request to send messages may result in more messages being sent than explicitly listed in the selection passed to the send operation.
+The Server MTM restores its settings from the SMTP service it has been asked to copy the messages to. Then it connects to the SMTP server using the CImTextServerSession class in the Email Server MTM Utilities, passing in the SMTP server address and TCP/IP port number from the SMTP settings. Then for each message to be sent the Server MTM uses the Email Server MTM utilities to generate an RFC2822 format message to send to the SMTP server, the RFC2822 text is generated on the fly as the data is sent to the SMTP server. If the SMTP server accepts the message to be sent then the Server MTM moves the message to the sent folder and sets its sending state to sent. If the SMTP server rejects the message then the Server MTM leaves the message in the outbox and sets the sending state to failed. Separate emails are generated for BCC recipients to ensure that the SMTP server doesn’t incorrectly include BCC recipients in emails sent to addresses in the To and CC fields of the email.
+3.2.9.3.7 Autosend
+The Autosend component is an executable that is kicked off by the POP3 and IMAP4 Client MTMs if the send on next connection setting is set. This executable will just make a request to the SMTP Server MTM to send messages associated with the SMTP service related to the POP3 or IMAP4 service, wait for the operation to finish and then exit.
+3.2.10 Messaging / MMS APIs
+The MMS module has been removed from v9.0 and onwards.
+3.2.10.1 Key Internal Relationships and Dependencies
+
+Figure 21 MMS Internal Dependencies
+3.2.10.2 API Purpose - Further Elaboration
+3.2.10.2.1 MMS Overview
+The MMS MTM provides functionality for creating, accessing, sending and receiving MMS messages. Messages are sent and received without the client application needing to open or close any kind of session. The management of the MMS session is handled entirely within the MTM.
+MMS clients are alerted when a new message is available for download via the WAP Push mechanism. A WAP push watcher is provided to handle these notifications. After the notification the message can be downloaded over WSP or HTTP. Messages are sent by posting the data over WSP or HTTP. The Symbian MMS implementation can handle sending or receiving MMS message over either protocol.
+MMS messages are based on the MIME format but are binary encoded using WSP. Note that MMS messages are encoded in this way even if they are posted over HTTP as opposed to WSP. The codec component is responsible for this encoding and decoding.
+3.2.10.2.2 MMS Utilities
+3.2.10.2.2.1 Key External Relationships and Dependencies
+
+Figure 22 MMS Utilities External Dependencies
+The MMS utilities provide the message and settings encapsulation classes. The MMS settings and messages are stored in the message store, the MMS utilities provide the interfaces to access this data.
+3.2.10.2.2.2 Settings
+The settings functionality provided by the MMS utilities allows the messaging client to persist MMS settings in the message store. Supported settings include:
+ MMSC (MMS server) address
+ WSP or HTTP transport
+ Autofetch messages on notification
+ Preferred IAP for the MMS network connection
+The settings functionality is also used by the server MTM to retrieve the settings prior to message sending or fetching.
+3.2.10.2.2.3 Message Encapsulation
+The message classes provide the message access functionality. Messages can be created, stored, restored and read using these classes. Functionality includes:
+ Adding media objects to the message
+ Enumerating through media objects
+ Adding recipients, subject line, etc. to a message
+ Adding other headers to the message, e.g. expiry date
+ Finding the appropriate media object for a given URI in the SMIL part (URI resolving)
+The message data is stored in the message store using one entry per message regardless of the number of media objects added to the message. This is preferable to using multiple message entries as it is faster and uses less disk space.
+Most of the message access code is common whether it is being used on the client or server side, however some parts of it are specific. For this reason it is essential that the appropriate client or server side CMmsMessage derived class is used.
+3.2.10.2.3 MMS Watcher
+3.2.10.2.3.1 Key External Relationships and Dependencies
+
+Figure 23 MMS Watcher External Dependencies
+
+The MMS watcher plug-in is responsible for intercepting incoming MMS notifications and delivery reports then taking the appropriate action. It is implemented as a WAP Push watcher plug-in.
+When an MMS notification is received an MMS entry is created in the inbox using the MMS utilities. At this point the entry has its incomplete flag set. If the settings have the autofetch option selected then the MMS watcher initiates the fetch operation via the MMS client MTM.
+If a delivery report is received then the delivered flag is set on the appropriate sent message. If an outgoing message was sent to several recipients then there will be several delivered flags. A delivery report from each recipient will set the appropriate delivered flag.
+3.2.10.2.4 MMS Client MTM
+3.2.10.2.4.1 Key External Relationships and Dependencies
+
+Figure 24 MMS Client MTM Dependencies
+As with most other MTMs the MMS client MTM provides access to the server MTM functionality for messaging clients. It also implements the Send-As interface and reply and forward functionality.
+3.2.10.2.4.2 Send-As Implementation
+The Client MTM Send-As interface is implemented in the MMS Client MTM. The implementation differs slightly from other MTMs because additional presentation content may be generated depending on the media objects that are added. When simple combinations of images, sounds and text are added a SMIL presentation is generated to link them together. This is preferable to simple adding the objects as attachments where some clients render them as a list of files and others fail to render them at all.
+The SMIL data is constructed using templates stored in resource files, the GMXML (SMIL) composer is not used.
+3.2.10.2.4.3 Reply / Forward
+The Client MTM can be used to create replies to received messages or to create forwarded responses. The reply and forwarding operations are performed asynchronously.
+3.2.10.2.5 MMS Server MTM
+3.2.10.2.5.1 Key External Relationships and Dependencies
+
+Figure 25 MMS Server MTM Dependencies
+The Server MTM is the most complicated part the MMS implementation. It handles all of the state information required to send or fetch MMS messages. It is also responsible for managing the HTTP or WSP session and the connections to the phone network.
+3.2.10.2.5.2 Operations
+All MMS server MTM functionality is encapsulated in operations. An operation consists of the setup of a session, the sending, fetching and acknowledgements when appropriate, it then closes the session. The messaging client initiates an operation with a single call to the Client MTM, there is no need for the messaging client to explicitly establish the session or to know about the internal states. However, these internal states are available to the messaging client via the progress structure if this level of user feedback is required.
+Two types of operation are supported, background and foreground:
+A maximum of one foreground operation can be running at any one time. The messaging client can poll the server MTM for the progress of a running foreground operation, likewise it can cancel it if necessary.
+A background operation does not support progress information and can not be cancelled by the messaging client. It is possible to initiate background operations even if other background or foreground operations are pending. However, background operations are queued and a maximum of one will actually be running at any one time.
+The MMS watcher uses a background operation to perform automatic fetching. While the background autofetch is occurring it is still possible to start a foreground operation (such as sending a message) if required.
+3.2.10.2.5.3 Session and Connection Management
+The server MTM uses the HTTP Transport Framework to enable the HTTP or WSP session. HTTP or WSP can be selected at runtime by selecting the appropriate option in the settings. The server MTM is responsible for reading any HTTP proxy details from the CommDB and passing it to the HTTP framework. See the http transport framework architectural description for more information on recognisers [R5]
+The server MTM is also responsible for managing the connection to the phone network. Connections are opened when required using the RConnection mechanism, multi-homing is supported provided that the underlying HTTP framework transport plug-in also supports it.
+3.2.10.2.6 MMS Codec
+The MMS Server MTM is in charge of the state transitions, connection, session, the actual posting and fetching of the data from them, however it does not encode or decode the MMS PDUs. The encoding and decoding is performed by the MMS Codec.
+For decoding the Server MTM passes the Codec the MMS PDU data in a descriptor for processing. If the PDU contains a received MMS message then the message entry is updated with the decoded MMS data.
+For encoding the Server MTM passes a reference to the message store entry containing the un-encoded MMS data. The Codec then encodes it and returns the PDU to the Server MTM in a descriptor.
+
+
+3.2.11 Messaging / BIO APIs
+3.2.11.1 Key Internal Relationships and Dependencies
+
+Figure 26 BIO Message Internal Dependencies
+3.2.11.1.1.1 Key External Relationships and Dependencies
+
+Figure 27 Bio Parser External Dependencies
+
+3.2.11.2 API Purpose - Further Elaboration
+3.2.11.2.1 BIO Overview
+The BIO messaging components have been designed to unify and simplify the way in which system messages are processed. In this context ‘system messages’ refers to messages received on the device which are intended to update some attribute(s) on the system as opposed to being presented to the user. Examples of these types of messages include vCards which are parsed and then displayed to the user and when accepted modify the users contact database and OTA configuration messages which are again parsed before display to the user and if accepted create email accounts or internet access points.
+The BIO messaging components can be broken down into three groups:
+1) The BIO MTM - To initiate the parsing and processing of BIO messages
+2) The BIO Database - Maps port numbers, MIME types, etc. to bio types in order to identify the type of incoming BIO messages.
+3) The BIO Parsers - To parse and process the BIO message payload
+BIO messages are not receive by the bio messaging framework, they come over other message transports for example see section 3.2.6.3.1 on the SMS watchers which describes how the SMS watchers receive bio messages and use the bio framework to tag the messages with the correct bio id.
+3.2.11.2.2 BIO MTM
+The BIO client MTM is called by the messaging client to parse or process a BIO message that has been saved in the message store. It is the responsibility of a BIO watcher to save the BIO message with the BIO flag and the appropriate BIO type set.
+The BIO client MTM does very little, its primary task is to pass on the messaging client request to the server MTM. Two operations are supported, parse and process.
+The messaging client is expected to initiate the parsing of the BIO message before processing it. The parsing step involves analysing the data and storing it in a form that can be displayed to the user via the BIO message viewer.
+Once the message has been parsed the messaging client can initiate the processing of the message.
+The BIO server MTM is responsible for deferring the parsing and processing to the appropriate BIO parser. The behaviour for the parsing and processing steps varies between parsers. See the BIO Parsers section for more information.
+The bio MTM does not support sending messages and therefore does not support reply / forwarding messages. For bio messages sending / reply etc. is supported by the particular MTM that the message is sent over, for example SMS.
+3.2.11.2.3 BIO Database
+The BIO database is used to identify the type of BIO messages. It maps message attributes such as port number, MIME type or leading string to a BIO type. These are attributes are then used by clients of the bio framework to know what ports to listen for messages on. For example the SMS watchers use the leading string to wait for SMS messages that start with that string and when storing those messages in the inbox tag them with the bio id associated with that leading string. See the SMS watcher section 3.2.6.3.1 for more examples of how the BIO database can be used.
+3.2.11.2.4 BIO Parsers
+The BIO parsers are plug-ins for parsing and processing incoming BIO messages. They are invoked by the BIO Server MTM depending on the BIO type of the message being processed. Each BIO parser implements two functions, ParseL and ProcessL. The level of functionality varies between parsers. Some parsers update the final repository with the received data, e.g. WAPP updates the CommDB with the received settings. Some parsers simply save the data in an unparsed state for processing by another component, this secondary parsing is not part of the BIO framework and must be initiated by the messaging client. An example is when GFP saves vCard data as a file as opposed to updating the contacts database, the UI must then invoke the Versit parser to parse the vCard and commit it to the contacts database.
+3.2.11.2.4.1 Generic File Parser (GFP)
+The generic file parser can be used to identify and save a variety of BIO data types, e.g. vCards and vCals. The Generic File Parser does not process the data, it simply saves it in the message store for processing by another component. The file is saved as an attachment of the message entry that was parsed.
+3.2.11.2.4.2 Nokia/Ericsson OTA Parser (WAPP)
+The WAPP parser decodes Nokia/Ericsson OTA messages and updates CommDB to reflect the received settings.
+3.2.11.2.4.3 Nokia Smart Message Internet Access Parser (IACP)
+The IACP parser decodes Nokia Smart Messages and updates the CommDB and messaging settings where appropriate.
+3.2.11.2.5 BIF Files and Utilities
+The BIF files encapsulate the information required for identifying BIO messages, these details may include the expected port number, MIME type or leading string. Different BIO watcher will use different information from these files, for an example see the 3.2.6.3.1. The information can be retrieved from the BIF files by using the BIF utilities. Generally BIO aware clients will access this information via the BIO database. BIF files are resource files previous to the v6.1 release they were binary files generated by biftool.exe.
+3.2.11.2.6 Platform Security Compliant Messaging / BIO APIs
+In the platform security model the BIO parsers are run in the client space rather than in the message server space, as is done in the non-platform secure model. If the BIO parsers are run in the message server space, it allows a client process to gain the capabilities of the message server. IPC policing can protect the message server from this.
+Also, for the message server to be able to load any BIO parser it would need more capabilities than it really requires. By running the BIO parsers in the client space, both these issues are solved. The client process must be trusted with the necessary capabilities to run the specified BIO parser.
+The BIO registry files are located in the \resource\messaging\bif read-only directory. All BIO parser DLLs are located in the \sys\bin protected directory.
+
+Figure 26 BIO Message Dependencies (v9.0)
+The BIO client MTM is responsible for loading the BIO database and BIO utilities to handle parse/process requests from clients.
+The BIO registry files no longer identify the BIO parsers DLLs via their UID – the registry file must use the BIO parser DLL name to identify them.
+3.2.12 Messaging / OBEX MTM APIs
+3.2.12.1 Key Internal Relationships and Dependencies
+
+Figure 28 OBEX Internal Dependencies
+3.2.12.2 OBEX MTM Overview
+The OBEX MTM offers simple IR and Bluetooth beaming functionality. It provides an API that is consistent with other MTMs so that the underlying OBEX APIs do not need to be used directly for beaming applications. The OBEX MTM does not provide OBEX receiving functionality, in order to receive OBEX data the underlying OBEX APIs must be used directly.
+3.2.12.2.1 OBEX MTM
+The OBEX MTM is split into three parts. OBEX MTM DLLs, IR MTM DLLs and Bluetooth MTM DLLs. The OBEX MTM DLLs can not be used on their own they provide the base OBEX MTM functionality for the derived IR and Bluetooth MTMs.
+There are two APIs that can be used to create OBEX messages:
+1) The Send-As API
+2) Linked attachments by filename
+The Send-As API provides an interface consistent with other MTMs, however it requires all attachments to be copied into the message store before they can be sent, this is often undesirable for beaming applications because it is wastes disk space. For this reason a second API is provided that allows attachments to be linked to outgoing messages by filename, when this API is used there is no need to copy the attachments to the message store.
+Unlike many other MTMs after OBEX tries to send a message it is deleted from the outbox whether the sending succeeds or fails.
+3.2.12.2.1.1 OBEX MTM Key External Dependencies
+
+Figure 29 OBEX External Dependencies
+3.2.12.2.2 IR MTM
+The bulk of the OBEX MTM functionality is provided by the OBEX MTM DLLs, the IR MTM itself just sets up the parameters.
+3.2.12.2.2.1 IR MTM Key External Dependencies
+
+Figure 30 IR MTM Dependencies
+3.2.12.2.3 Bluetooth MTM
+The bulk of the OBEX MTM functionality is provided by the OBEX MTM DLLs, the Bluetooth MTM just subclasses from the OBEX MTM and sets up Bluetooth specific parameters.
+3.2.12.2.3.1 Bluetooth MTM Key External Dependencies
+
+Figure 31 Bluetooth MTM Dependencies
+3.2.12.2.4 OBEX MTM Utils
+The OBEX MTM Utils provide utility functionality used by the other OBEX MTM DLLs. The two main areas of functionality provided by this component are:
+1) Filename linking functionality
+2) Bluetooth SDP lookup
+The filename linking functionality is provided in the utilities because linked files must be added by the client side during message creation and need to be read on the server side during sending.
+
+3.2.12.2.5 Platform Security Compliant Messaging / OBEX MTM APIs
+From v9.0 and onwards the service settings of all the derived OBEX MTMs are stored in the Central Repository. The OBEX message is stored in the message store as an attachment – from v9.0 and onwards the Attachment API is used to attach the OBEX message.
+
+3.2.13 Messaging / GMXML APIs
+3.2.13.1 Key Relationships and Dependencies
+
+Figure 32 GMXML Dependencies
+3.2.13.2 Overview
+The GMXML component provides simple XML DOM parsing and validation functionality. It is intended for parsing XML that might be needed in messaging applications, specifically SMIL parsing for MMS rendering. It is not a general purpose XML parser and will not be suitable for some applications, e.g. browsing.
+3.2.13.2.1 GMXML DOM
+The DOM implementation is fit for purpose for SMIL rendering but differs from the standard DOM design in several respects, e.g. attributes are not stored as discrete nodes, for performance reasons they are stored with the element.
+The DOM tree classes are all derived from nodes. Implemented node types include elements, text and comments. The type of each element is stored as a descriptor as opposed to an enum. This is less efficient than storing it as an enum but provides maximum flexibility when dealing with unknown element types.
+Nodes are linked together in a tree structure as might be expected in a DOM implementation. The tree structure exists on the heap.
+3.2.13.2.2 GMXML Parser and Composer
+3.2.13.2.2.1 Parser
+The parser takes XML input from a buffer or file and creates the corresponding DOM structure on the heap.
+The parser is capable of performing some basic validation. In order to validate against a DTD a class that implements the GMXML DTD interface is required. The DTD interface specifies several functions that provide the required validation, e.g. one of the functions determines if a given attribute is valid for a given element. An instance of the DTD class should be passed into the parser when validation is required but can be omitted if no validation is needed.
+3.2.13.2.2.2 Composer
+The composer takes a DOM tree and generates XML output from it. The XML output is written to a file.
+3.2.13.2.3 GMXML SMIL DTD (Validator)
+The SMIL DTD validator class is an implementation of the DTD validator interface. It implements several simple functions that provide the information required to validate SMIL data. An instance of the SMIL DTD validator should be passed into the parser if SMIL validation is required.
+4 Security
+4.1 Data caging
+For data storage in the pre-platform security compliant architecture, refer to section [3.2.1.3.2]
+For the data caging in the platform security compliant architecture of v9.0 and onwards, refer to section [3.2.1.3.3]
+4.2 Backup and restore
+The message server registers the index file with the backup server. When informed about a backup/restore it releases the index file, sending events to messaging clients informing them that the message store is unavailable. When informed it can open the index file again, it checks the time stamp on the index file; if it has changed since the file was released it reloads the index file. If the newly restored index file is found to be corrupt it is deleted and a new message store is created. See the section on page 14 for details on how the message server handles corrupt stores. The client performing the restore should always wipe the existing message store before starting to copy the message store from the backup to the device.
+4.3 Capability ranges
+In the platform security compliant architecture of v9.0 and onwards, the capabilities allocated to messaging sub-systems are as listed in following table.
+4.3.1 Capabilities granted to executables
+The following table lists the executables and their capabilities and also gives a basic example for having the required capability.
+
+Executable Capability Rationale (basic example of capability requirement)
+msexe.exe ProtServ ProtServ is required to allow the msexe.exe to start a protected server. This stops processes without ProtServ from starting a server pretending to be the message server
+ ReadDeviceData ReadDeviceData is needed to able to read service settings
+ WriteDeviceData WriteDeviceData is needed to able to write service settings
+ NetworkServices NetworkServices capability is needed to access network transports (SMS, POP3, SMTP, IMAP4).
+ LocalServices LocalServices is needed to be able to access IR and Bluetooth
+ ReadUserData ReadUserData is needed to be able to read user data (e.g. service settings).
+watcher.exe ReadDeviceData ReadDeviceData is needed to able to read service settings
+ WriteDeviceData WriteDeviceData is needed to able to write service settings
+ NetworkServices NetworkServices capability is needed to access network transports (SMS).
+ LocalServices LocalServices capability is needed for the plug-ins to access IR and Bluetooth
+ ReadUserData ReadUserData is needed to be able to read user data
+ WriteUserData WriteUserData is needed to be able to write user data
+autosend.exe ReadUserData ReadUserData capability is needed to be able to read data from Outbox and SMTP server MTM.
+ WriteUserData WriteUserData capability is needed to be able to write data in Outbox and SMTP server MTM.
+ NetworkServices NetworkServices capability is needed to access network transports (SMS, POP3, SMTP, and IMAP4).
+ LocalServices LocalServices capability is needed to access the IR and Bluetooth
+SchSend.exe ReadDeviceData ReadDeviceData is needed to able to read settings data
+ NetworkServices NetworkServices capability is needed to access the network transports (SMS, POP3, SMTP, and IMAP4).
+ LocalServices LocalServices is needed to be trusted by other MTM
+ ReadUserData ReadUserData is needed to be able to read user data.
+ WriteUserData WriteUserData is needed to be able to write user data.
+SendAs.exe ReadDeviceData ReadUserData is needed to be able to read data in Outbox.
+ WriteDeviceData WriteUserData is needed to be able to write data in Outbox.
+ NetworkServices NetworkServices capability is needed to access the network transports (SMS, POP3, SMTP, and IMAP4).
+ LocalServices LocalServices is needed to be able to access IR and Bluetooth
+
+4.3.2 Capabilities granted to DLLs
+The assigned Platform Security attributes for DLLs within messaging are outlined in the following table.
+DLL Capability
+bifu.dll All –TCB
+bioc.dll All –TCB
+biodb.dll All –TCB
+bios.dll All –TCB
+biowatcher.dll same as watcher.exe
+biut.dll All –TCB
+cbcp.dll All –TCB
+enp.dll All –TCB
+gfp.dll All –TCB
+iacp.dll All –TCB
+nbswatcher.dll same as watcher.exe
+cdmanbswatcher.dll same as watcher.exe
+CdmaSocketWatcher.dll same as watcher.exe
+VMNWatcher.dll same as watcher.exe
+WEMTWatcher.dll same as watcher.exe
+WMTWatcher.dll same as watcher.exe
+WPTWatcher.dll same as watcher.exe
+wapp.dll All –TCB
+wapwatcher.dll same as watcher.exe
+smildtd.dll All –TCB
+xmldom.dll All –TCB
+xmlparser.dll All –TCB
+smiltranslator.dll All –TCB
+imcm.dll All –TCB
+imps.dll same as msexe.exe
+imut.dll All –TCB
+msgs.dll All –TCB
+msgurlrec.mdl same as AppArc.exe (once it exists; eiksrv in meantime)
+mtur.dll All –TCB
+pops.dll same as msexe.exe
+schsend.dll All –TCB
+send.dll All –TCB
+smcm.dll All –TCB
+smcm_gsm.dll Synonym for smcm.dll
+smcm_cdma.dll Synonym for smcm.dll
+smss.dll same as msexe.exe
+smss_gsm.dll Synonym for smss.dll
+smss_cdma.dll Synonym for smss.dll
+smts.dll same as msexe.exe
+btcmtm.dll All –TCB
+btsmtm.dll same as msexe.exe
+irc.dll All –TCB
+irs.dll same as msexe.exe
+obexclientmtm.dll All –TCB
+obexmtmutil.dll All –TCB
+obexservermtm.dll same as msexe.exe
+
+The reason for setting a high capability to the DLLs is to make it possible for almost anyone to link to them. Although a DLL may have capabilities ALL-TCB (All minus TCB), its real capability is limited by the process which loads the DLL.
+4.3.3 Capabilities required to use the subsystem
+The message subsystem needs to be protected against malicious clients. The following table shows the key capabilities required to do related activities in different components.
+
+Component Related Activity Required Capability and SID
+Message server Create message in local folder No capability required
+ Create message in Outbox ReadUserData, WriteUserData and MTM specific capabilities
+ Access client MTM ReadUserData, WriteUserData and MTM specific capabilities
+Watcher Allow plug-ins to wait on events (e.g. arrival of SMS) Watcher always polices if the client capabilities are trusted by the watcher framework, else it will not be loaded
+Plug-ins or clients using watcher need the same capabilities as watcher.exe to be able to be loaded by watcher.
+Autosend Send messages in background NetworkService or LocalService required by the message type
+SchSend Scheduling of operations (e.g. sending SMS) SchSend always polices to see if the process was started by the Task Scheduler – if not the process terminates without performing any of the scheduled tasks. Also, the SchSend verifies that only itself and the message server created the scheduled tasks. If this is not the case, SchSend does not performing the scheduled tasks.
+SendAs Create message Draft, move it to Outbox, and send message WriteDeviceData or WriteUserData and other capability required by the message type
+
+5 Further Information
+5.1 References
+No. Document Reference Version Description
+R1 messaging_functional_specification.doc 0.6 Messaging Functional description
+R2 SGL.GT0143.161_App-Framework_Architectural_Description.doc 1.0 App-Framework Architectural Description
+R3 NBProtocols_Subsystem_Architectural_Description.doc 0.2 NBProtocols Architectural Description
+R4 WAP-stack_architectural_analysis.doc 1.0 WAP stack architectural analysis
+R5 HTTP Transport Framework Architectural Description.doc 1.1 HTTP Transport Framework 1.1 Architectural Description
+5.2 Open Issues
+The following issues need to be resolved before this document is completed:
+1. Top-level architecture diagram showing the framework and plug-ins should be added to overview section.
+2. Message store section should talk about removable media.
+3. Define "Message Server Client API" and "Messaging Client API" in the glossary, and ensure it is consistently used in the diagrams
+4. Add a sequence diagram for receiving a vCard over SMS and integrating it into contacts
+5. Add a sequence diagram for sending an SMS
+6. Add a sequence diagram for synchronising a POP3 mail box
+7. Add a sequence diagram for connecting to an IMAP4 mail box and downloading a message
+8. Capability table should be updated after the implementation of server e.g. message server
+9. Sequence diagram may need to be changed to show secured platform operation
+10. In section [3.1.1.4] the server SendAsV2 to find a correct name
+11. Section 3.2.1.3.3.1 Data Caging file 'Mtm Registry v2'may need a correct name
+12. Breakdown diagram showing all DLL, exes, apps in the messaging subsystem for both the pre-v8.0 and post v9.0 in section[3.2]
+13. Needs to say more about how the capabilities are policed and the algorithms used for different operations
+14. The dependecy between the message server and the central repository need to be listed in the email, SMS and OBEX diagrams (e.g. message store)
+15. Section 3.2.1.2 - figure 3 - Central Repository also get used by the Message server, or server MTMs (e.g. POP3), to retrieve account settings the path, required DLL and description are not given
+16. Section 4.3.3 title can be Police requirement of the sub-system, add extra column for SID in the table and list the use of SID. For example SchSend checks for Task Scheduler SID
+
+
+5.3 Glossary
+The following technical terms and abbreviations are used within this document.
+Term Definition
+BIO
+Bearer Independent Object Smart messages e.g. vCards, vCals, and WAP provisioning messages. These can currently be received via the WAP stack, SMS stack, Bluetooth or Infrared.
+BIO Type UID that represents the content type of a BIO Message.
+Message Centre Application that displays list views of messages to the user, allowing the user to perform operations such as copying messages, sending messages creating new messages etc.
+Message Viewer Application for viewing a message.
+Message Editor Application for creating or editing a message
+Message Server Symbian OS Server that handles request to modify the Message Store
+Message Store Store of messages and related information kept in the file system on a Symbian OS device.
+Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
+Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
+Global Inbox A standard folder under the local service which is used to store incoming messages like SMS MMS etc. as opposed to an IMAP4 Inbox which would be under an IMAP4 service and is a representation of the Inbox on an IMAP4 email server.
+Central Repository centralised and secure storage facility for application settings
+OBEX Object exchange protocol, used to send objects such as vCards or files between devices via infrared or Bluetooth.
+GMXML XML parser / generator for use with SMIL formatted messages.
+UID Unique Identifier, a 32 bit number allocated from a registry owned by Symbian
+IPC Inter Process Communication
+MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
MTM Registry A list of currently installed MTMs maintained by the message server.
TLS Transport Layer Security, provides encryption of a TCP/IP socket.
M-HTML Standard for including HTML in MIME email messages see http://www.ietf.org/rfc/rfc2557.txt
@@ -44729,15 +43711,15 @@
Message Editor Application for creating or editing a message
Message Server Symbian OS Server that handles request to modify the Message Store
Message Store Store of messages and related information kept in the file system on a Symbian OS device.
-Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
-Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
+Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
+Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
Global Inbox A standard folder under the local service which is used to store incoming messages like SMS MMS etc. as opposed to an IMAP4 Inbox which would be under an IMAP4 service and is a representation of the Inbox on an IMAP4 email server.
Central Repository centralised and secure storage facility for application settings
OBEX Object exchange protocol, used to send objects such as vCards or files between devices via infrared or Bluetooth.
GMXML XML parser / generator for use with SMIL formatted messages.
UID Unique Identifier, a 32 bit number allocated from a registry owned by Symbian
IPC Inter Process Communication
-MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
+MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
MTM Registry A list of currently installed MTMs maintained by the message server.
TLS Transport Layer Security, provides encryption of a TCP/IP socket.
M-HTML Standard for including HTML in MIME email messages see http://www.ietf.org/rfc/rfc2557.txt
@@ -45747,15 +44729,15 @@
Message Editor Application for creating or editing a message
Message Server Symbian OS Server that handles request to modify the Message Store
Message Store Store of messages and related information kept in the file system on a Symbian OS device.
-Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
-Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
+Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
+Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
Global Inbox A standard folder under the local service which is used to store incoming messages like SMS MMS etc. as opposed to an IMAP4 Inbox which would be under an IMAP4 service and is a representation of the Inbox on an IMAP4 email server.
Central Repository centralised and secure storage facility for application settings
OBEX Object exchange protocol, used to send objects such as vCards or files between devices via infrared or Bluetooth.
GMXML XML parser / generator for use with SMIL formatted messages.
UID Unique Identifier, a 32 bit number allocated from a registry owned by Symbian
IPC Inter Process Communication
-MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
+MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
MTM Registry A list of currently installed MTMs maintained by the message server.
TLS Transport Layer Security, provides encryption of a TCP/IP socket.
M-HTML Standard for including HTML in MIME email messages see http://www.ietf.org/rfc/rfc2557.txt
@@ -46765,15 +45747,15 @@
Message Editor Application for creating or editing a message
Message Server Symbian OS Server that handles request to modify the Message Store
Message Store Store of messages and related information kept in the file system on a Symbian OS device.
-Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
-Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
+Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
+Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
Global Inbox A standard folder under the local service which is used to store incoming messages like SMS MMS etc. as opposed to an IMAP4 Inbox which would be under an IMAP4 service and is a representation of the Inbox on an IMAP4 email server.
Central Repository centralised and secure storage facility for application settings
OBEX Object exchange protocol, used to send objects such as vCards or files between devices via infrared or Bluetooth.
GMXML XML parser / generator for use with SMIL formatted messages.
UID Unique Identifier, a 32 bit number allocated from a registry owned by Symbian
IPC Inter Process Communication
-MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
+MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
MTM Registry A list of currently installed MTMs maintained by the message server.
TLS Transport Layer Security, provides encryption of a TCP/IP socket.
M-HTML Standard for including HTML in MIME email messages see http://www.ietf.org/rfc/rfc2557.txt
@@ -46826,3 +45808,1021 @@
4. Complete and send the message by sending a full stop to the SMTP server
+
+
+Messaging Symbian OS v7.0s, v8.0, v8.1, v9.0, v9.1 Architectural Description
+
+Status: Issued
+Team/Department : Messaging / Content & Messaging
+
+Contents
+1 INTRODUCTION 6
+1.1 PURPOSE AND SCOPE 6
+2 SUBSYSTEM OVERVIEW AND BACKGROUND 6
+3 MESSAGING ARCHITECTURE AND APIS 7
+3.1 SUBSYSTEM COMPONENTS 7
+3.1.1 Framework components 7
+3.1.1.1 Message Server and MTM architecture 7
+3.1.1.2 Schedule Send 7
+3.1.1.3 SendAs Version 1 7
+3.1.1.4 SendAs Version 2 7
+3.1.1.5 Watcher Framework 8
+3.1.1.6 Message URL Handler 8
+3.1.1.7 Bio Message Framework 8
+3.1.2 Plug-ins 8
+3.1.2.1 SMS 8
+3.1.2.2 CDMA SMS 8
+3.1.2.3 Email 9
+3.1.2.4 OBEX 9
+3.1.2.5 MMS 9
+3.1.2.6 GMXML 10
+3.1.2.7 Bio Message Plug-ins 10
+3.1.2.8 PCMTM 10
+3.1.2.9 Fax 10
+3.2 GENERAL DESCRIPTION 11
+3.2.1 Messaging / Message Server and MTM Architecture APIs 11
+3.2.1.1 Key Internal Relationships and Dependencies 11
+3.2.1.2 Key External Relationships and Dependencies 12
+3.2.1.3 API Purpose - Further Elaboration 13
+3.2.1.3.1 Message Store 13
+3.2.1.3.2 Data File Storage (pre - v9.0) 15
+3.2.1.3.3 Platform Security Compliant Message Store 16
+3.2.1.3.4 How message centres display the message store 17
+3.2.1.3.5 Message Type Module Architecture 19
+3.2.1.3.6 Message Server Client API 21
+3.2.2 Messaging / Send As APIs 22
+3.2.2.1 Key Relationships and Dependencies 22
+3.2.2.2 API Purpose - Further Elaboration 22
+3.2.2.2.1 SendAs API (pre – v9.0) 22
+3.2.3 Platform Security Compliant SendAs Server (v9.0 onwards) 23
+3.2.4 Messaging / Schedule Send APIs 24
+3.2.4.1 Key Relationships and Dependencies 24
+3.2.4.2 API Purpose - Further Elaboration 24
+3.2.4.2.1 Schedule Send 24
+3.2.5 Messaging / Watchers APIs 25
+3.2.5.1 Key Relationships and Dependencies 25
+3.2.5.2 API Purpose - Further Elaboration 25
+3.2.6 Messaging / Message URL Handler APIs 26
+3.2.6.1 Key Relationships and Dependencies 26
+3.2.6.2 API Purpose - Further Elaboration 26
+3.2.6.2.1 Message URL Handler Application 26
+3.2.6.2.2 Message URL Recognisers 27
+3.2.7 Messaging / SMS APIs 27
+3.2.7.1 Key Internal Relationships and Dependencies 27
+3.2.7.2 Key External Relationships and Dependencies 28
+3.2.7.3 API Purpose - Further Elaboration 28
+3.2.7.3.1 SMS Watchers 28
+3.2.7.3.2 SMS Client MTM 29
+3.2.7.3.3 SMS Utilities 29
+3.2.7.3.4 SMS Server MTM 30
+3.2.8 Messaging / CDMA SMS APIs 31
+3.2.8.1 Key Internal Relationships and Dependencies 31
+3.2.8.2 Key External Relationships and Dependencies 32
+3.2.8.3 API Purpose - Further Elaboration 32
+3.2.8.3.1 CDMA SMS Watchers 32
+3.2.8.3.2 CDMA SMS Client MTM 33
+3.2.8.3.3 CDMA SMS Utilities 33
+3.2.8.3.4 CDMA SMS Server MTM 33
+3.2.8.3.5 Configuration for using CDMA SMS MTM 34
+3.2.9 Messaging / Email APIs 35
+3.2.9.1 Key Internal Relationships and Dependencies 35
+3.2.9.2 Key External Relationships and Dependencies 36
+3.2.9.3 API Purpose - Further Elaboration 36
+3.2.9.3.1 Email Overview 36
+3.2.9.3.2 Email Client Utilities 37
+3.2.9.3.3 Email Server MTM Utilities 37
+3.2.9.3.4 POP3 MTMs 37
+3.2.9.3.5 IMAP4 MTMs 38
+3.2.9.3.6 SMTP MTMs 40
+3.2.9.3.7 Autosend 40
+3.2.10 Messaging / MMS APIs 40
+3.2.10.1 Key Internal Relationships and Dependencies 41
+3.2.10.2 API Purpose - Further Elaboration 41
+3.2.10.2.1 MMS Overview 41
+3.2.10.2.2 MMS Utilities 42
+3.2.10.2.3 MMS Watcher 43
+3.2.10.2.4 MMS Client MTM 43
+3.2.10.2.5 MMS Server MTM 44
+3.2.10.2.6 MMS Codec 45
+3.2.11 Messaging / BIO APIs 46
+3.2.11.1 Key Internal Relationships and Dependencies 46
+3.2.11.2 API Purpose - Further Elaboration 47
+3.2.11.2.1 BIO Overview 47
+3.2.11.2.2 BIO MTM 47
+3.2.11.2.3 BIO Database 48
+3.2.11.2.4 BIO Parsers 48
+3.2.11.2.5 BIF Files and Utilities 48
+3.2.11.2.6 Platform Security Compliant Messaging / BIO APIs 49
+3.2.12 Messaging / OBEX MTM APIs 50
+3.2.12.1 Key Internal Relationships and Dependencies 50
+3.2.12.2 OBEX MTM Overview 50
+3.2.12.2.1 OBEX MTM 50
+3.2.12.2.2 IR MTM 51
+3.2.12.2.3 Bluetooth MTM 51
+3.2.12.2.4 OBEX MTM Utils 52
+3.2.12.2.5 Platform Security Compliant Messaging / OBEX MTM APIs 52
+3.2.13 Messaging / GMXML APIs 52
+3.2.13.1 Key Relationships and Dependencies 52
+3.2.13.2 Overview 53
+3.2.13.2.1 GMXML DOM 53
+3.2.13.2.2 GMXML Parser and Composer 53
+3.2.13.2.3 GMXML SMIL DTD (Validator) 53
+4 SECURITY 54
+4.1 DATA CAGING 54
+4.2 BACKUP AND RESTORE 54
+4.3 CAPABILITY RANGES 54
+4.3.1 Capabilities granted to executables 54
+4.3.2 Capabilities granted to DLLs 55
+4.3.3 Capabilities required to use the subsystem 57
+5 FURTHER INFORMATION 59
+5.1 REFERENCES 59
+5.2 OPEN ISSUES 59
+5.3 GLOSSARY 60
+APPENDIX A - EXAMPLE SEQUENCE DIAGRAMS 62
+A.1 COPY TO A REMOTE SERVICE 62
+A.2 SMTP SESSION 64
+A.3 SMTP EMAIL SEND 66
+
+Table of Figures
+Figure 1 Where Messaging Lives 6
+Figure 2 MTM Relationships 11
+Figure 3 External Dependencies 12
+Figure 4 Message Store 13
+Figure 5 Series 60 Inbox List View 14
+Figure 6 Remote and Local Entries 14
+Figure 7 Email Message 15
+Figure 8 Series 60 Message Centre (Composed from 2 screen shots) 17
+Figure 9 UIQ Message Centre 18
+Figure 10 Messaging MTM Structure (light coloured components are part of messaging subsystem) 19
+Figure 11 Nokia 9210 Outbox List View 20
+Figure 12 SendAs Version 1 Dependencies 22
+Figure 13 SendAs Version 2 Dependencies 23
+Figure 14 Schedule Send Dependencies 24
+Figure 15 Watcher Dependencies 25
+Figure 16 Message URL Handler Dependencies 26
+Figure 17 SMS Internal Dependencies 27
+Figure 18 SMS External Dependencies 28
+Figure 19 CMDA SMS Internal Dependencies 31
+Figure 20 CDMA SMS External Dependencies 32
+Figure 19 Email Internal Dependencies 35
+Figure 20 Email External Dependencies 36
+Figure 21 MMS Internal Dependencies 41
+Figure 22 MMS Utilities External Dependencies 42
+Figure 23 MMS Watcher External Dependencies 43
+Figure 24 MMS Client MTM Dependencies 43
+Figure 25 MMS Server MTM Dependencies 44
+Figure 26 BIO Message Internal Dependencies 46
+Figure 27 Bio Parser External Dependencies 47
+Figure 26 BIO Message Dependencies (v9.0) 49
+Figure 28 OBEX Internal Dependencies 50
+Figure 29 OBEX External Dependencies 51
+Figure 30 IR MTM Dependencies 51
+Figure 31 Bluetooth MTM Dependencies 52
+Figure 32 GMXML Dependencies 52
+Figure 33 Sequence Diagram Showing Copying to a Remote Service 62
+Figure 34 Sequence Diagram Showing a SMTP Session 64
+Figure 35 Sequence Diagram Showing SMTP Transactions during Email Send. 66
+1 Introduction
+1.1 Purpose and Scope
+The Messaging Architectural Description details the architecture and APIs exposed by the Messaging Subsystem. This document does not attempt to list all functionality provided by the messaging subsystem. For details on the functionality provided and the specifications implemented by the messaging subsystem see the Messaging Functional Description [R1]. This document describes the general architecture of messaging subsystem. Information related to a particular release version is mentioned with relevant release number.
+2 Subsystem Overview and Background
+The Messaging Subsystem provides an application level API to handle the storage and transport of different message types. It sits between messaging applications and the lower level subsystems which messaging uses for storage and transmission of messages.
+
+Figure 1 Where Messaging Lives
+The message types that messaging currently supports are Email (POP3, IMAP4 & SMTP), SMS, MMS and OBEX. The set of supported message types is extensible at run time by the use of plug-in modules that are responsible for the transmission and storage of a particular message type. This means that the set of components shown communicating with the network cloud depend on the message types installed.
+3 Messaging Architecture and APIs
+3.1 Subsystem components
+The Messaging subsystem components can be split into two categories: those components that form the framework and those that plug into the framework to support specific message types. This section briefly describes each of the components, more detailed descriptions of the components and their dependencies can be found in later sections of this document.
+3.1.1 Framework components
+3.1.1.1 Message Server and MTM architecture
+The message server is the core component in the messaging subsystem. It provides the message store used to contain messages. The Message Type Module architecture also allows plug-ins to add support for new message types to the messaging subsystem.
+Component Description
+messaging\framework\serverexe Executable that links to the server component and starts the message server
+messaging\framework\server Contains classes that make up both the client and server side of the message server API.
+messaging\framework\mtmbase Base classes for the plug-ins that handle the various message types
+3.1.1.2 Schedule Send
+The Schedule Send component is an extension to the framework that provides support for scheduling of operations such as sending messages. Message type modules that wish to support this functionality can use these support components to implement scheduling. For example the SMS MTM uses this to allow scheduled sending of SMS messages.
+Component Description
+messaging\schedulesend\schedulesendmtm Base classes that handle functionality for message server plug-ins that wish to enable scheduling of sending messages.
+messaging\schedulesend\schedulesendexe Executable use to provide schedule send behaviour.
+3.1.1.3 SendAs Version 1
+This version of SendAs is supported in releases pre - v9.0. SendAs provides a high level API for applications that wish to include a “Send As” menu to allow users to send content via one of the message types supported by messaging. The application using the API does not have to be aware of the message type selected by the user. Note the API does not send the messages.
+Component Description
+messaging\sendas High level API to allow creation of messages.
+3.1.1.4 SendAs Version 2
+From v9.0 and onwards the SendAs has been replaced with client server architecture based SendAs server. The client server architecture enhances secured platform implementation. The SendAs server polices the client application. If it is not trusted with required capabilities the SendAs server will refuse the client access. The client MTM for the message type can send a message with user permission even if the client does not have the correct capabilities.
+Component Description
+messaging\sendAsV2 High level API to allow the creation and sending of messages
+
+3.1.1.5 Watcher Framework
+The watcher framework is a lightweight framework to allow plug-ins to wait on events. For example there is an SMS watcher that waits for incoming SMS messages and delivers them to the message store. The watcher framework will only load plug-ins from ROM.
+Component Description
+messaging\framework\watcher Executable that loads and runs watcher plug-ins.
+3.1.1.6 Message URL Handler
+Support for recognising messaging URLs (mailto:, sms:, fax:, mms:), and then launching an editor with a new message.
+Component Description
+messaging\urlhandler\urlhandler An application that parses the URLs and then creates a correctly addressed message and launches a message editor.
+messaging\urlhandler\recogniser Recognisers that map from the URL schemes to the mime types.
+3.1.1.7 Bio Message Framework
+The Bio Message Framework provides a framework that supports plug-ins to handle messages like vCards and Internet access point set-up messages.
+Component Description
+messaging\biomsg\BDB\BIODB Classes to maintain the database of bio registration files.
+messaging\biomsg\BIFU\BIFU Classes for reading and writing bio registration files
+messaging\biomsg\BIOC\BIOC Bio message client MTM, this is in the framework section as it forms part of the bio messaging framework it is also a plug-in to the messaging framework.
+messaging\biomsg\BIOS\BIOS Bio message server MTM, this is in the framework section as it forms part of the bio messaging framework it is also a plug-in to the messaging framework.
+3.1.2 Plug-ins
+3.1.2.1 SMS
+The SMS plug-ins provide application level support for the Short Message Service messages.
+Component Description
+messaging\biomsg\BioWatchers Plug-ins to the watcher framework to listen for SMS, WSP, and WDP messages and deliver them to the global inbox in the message store.
+messaging\sms\clientmtm A plug-in to the message server framework to provide a generic API for creation of SMS messages (SMS Client MTM & SMS utilities)
+messaging\sms\servermtm A plug-in to the message server framework to provide a generic API for sending of SMS messages (SMS Server MTM)
+3.1.2.2 CDMA SMS
+The CDMA SMS plug-ins provide application level support for the CDMA Short Message Service messages.
+Component Description
+messaging\biomsg\BioWatchersCdma Plug-ins to the watcher framework to listen for CDMA SMS messages and deliver them to the global inbox in the message store.
+messaging\sms\multimode\clientmtm A plug-in to the message server framework to provide a generic API for creation of CDMA SMS messages (CDMA SMS Client MTM)
+messaging\sms\multimode\servermtm A plug-in to the message server framework to provide a generic API for sending of CDMA SMS messages (CDMA SMS Server MTM)
+
+3.1.2.3 Email
+The email plug-ins provide support the POP3, IMAP4 and SMTP email protocols and support for parsing and generating plain test, MIME and M-HTML format email messages.
+Component Description
+messaging\email\clientmtms A plug-in to the message server framework to provide a generic API for creation of email messages (IMAP4 SMTP and POP3 Client MTMs & email utilities)
+messaging\email\imapservermtm A plug-in to the message server framework to provide a generic API for access to a remote IMAP4 server (IMAP4 Server MTM)
+messaging\email\smtpservermtm A plug-in to the message server framework to provide a generic API for access to a remote SMTP server (SMTP Server MTM)
+messaging\email\popservermtm A plug-in to the message server framework to provide generic API for access to remote POP3 server (POP3 Server MTM)
+messaging\email\servermtmutils Email utilities for parsing plain text and MIME email messages. It also provides an abstraction of the TCP/IP sockets for use by the SMTP POP3 and IMAP4 plug-ins.
+messaging\email\autosend An executable that requests SMTP Server MTM to send messages in the outbox. This is used to provide send on next connection functionality and is started by the POP3 and IMAP4 Client MTMs.
+3.1.2.4 OBEX
+The OBEX MTM is a set of plug-ins to the message server that provides support for IR and Bluetooth beaming.
+Component Description
+messaging\obex\btmtm\btclient\group\btcmtm Bluetooth Client MTM
+messaging\obex\btmtm\btserver\group\btsmtm Bluetooth Server MTM
+messaging\obex\irmtm\irclient\group\ircmtm IR Client MTM
+messaging\obex\irmtm\irserver\group\IRSMTM IR Server MTM
+messaging\obex\obexmtm\obexclient\group\obexClientMtm OBEX Client MTM, base classes for the Bluetooth and IR Client MTMs
+messaging\obex\obexmtm\obexserver\group\obexServerMtm OBEX Server MTM, base classes for the Bluetooth and IR Server MTMs
+messaging\obex\obexmtm\obexutil\group\obexMtmUtil OBEX MTM utilities
+3.1.2.5 MMS
+The MMS MTM is a plug-in to the message server that provides support for MMS messages. From v9.0 and onwards MMS MTM and related components are removed.
+Component Description
+messaging\mms\utils MMS Utilities
+messaging\mms\servermtm MMS Server MTM
+messaging\mms\mmswatcherplugins MMS plug-ins to WAP push framework to handle reception of MMS notifications
+messaging\mms\codec MMS utilities for handling MMS codecs
+messaging\mms\clientmtm MMS Client MTM
+3.1.2.6 GMXML
+GMXML is a parser/generator for SMIL presentations for MMS messages.
+Component Description
+messaging\GMXML\XMLParser XML parser designed for parsing of SMIL messages
+messaging\GMXML\XMLDom XML document object model designed for parsing of SMIL messages
+messaging\GMXML\SMILdtd SMIL DTD
+3.1.2.7 Bio Message Plug-ins
+These parsers plug into the bio messaging framework to handle specific types of bio message.
+Component Description
+messaging\biomsg\cbcp\CBCP Compact business card parser
+messaging\biomsg\enp\ENP Email notification parser
+messaging\biomsg\gfp\gfp General file parser
+messaging\biomsg\iacp\IACP Nokia Smart Message Internet Access Parser
+messaging\biomsg\wapp\wapp Nokia/Ericsson OTA Parser
+3.1.2.8 PCMTM
+Plug-in to the message server that provided email synchronisation with a PC. This component has been deprecated in 8.0a and will not been documented in the API section below.
+3.1.2.9 Fax
+Plug-in to the message server that provides fax support. This component has been deprecated in 8.0a and will not been documented in the API section below.
+
+3.2 General Description
+3.2.1 Messaging / Message Server and MTM Architecture APIs
+3.2.1.1 Key Internal Relationships and Dependencies
+
+Figure 2 MTM Relationships
+Figure 2 shows the relationship between the Message Server and the MTM plug-ins. The grey classes are realisations of the MTM interfaces defined by the messaging framework. The message server depends on the Server MTM interface. Messaging Clients depend on the Client, UI and UI Data MTM interfaces and the Message Server Client API.
+3.2.1.2 Key External Relationships and Dependencies
+
+Figure 3 External Dependencies
+The grey package representing the messaging client depends on the Client, UI and UI Data interfaces and the Messaging Client API. The message server then depends on:
+• Charconv – Provides character set conversion routines, used to convert encoded message body text to Unicode body text.
+• EStore – Provides API to handle a stream based store used for the messaging index file and the framework classes for the message store files. (omitted from other dependency diagrams as it is implied by the dependency on the message server)
+• F32 – Provides the file server APIs used to access the file system directories in which messaging stores files containing message data. (omitted from other dependency diagrams)
+• BAFL – Provides API to load the correct messaging resource file dependent on the current language and to register the message store index file with the backup server. (omitted from other dependency diagrams)
+• ETEXT – Rich text APIs used to store body text of messages, this rich text format is a Symbian Proprietary format. (omitted from other dependency diagrams)
+• EUSER – Core Symbian OS utilities such as descriptors, arrays, client / server framework, cleanup stack and others (omitted from this and other dependency diagrams).
+• Central Repository – Centralised and secure storage facility for application settings, the message server stores message settings data in the central repository (from v9.0 and onwards).
+Note that debug only dependencies such as the flogger have been omitted from dependency diagrams.
+3.2.1.3 API Purpose - Further Elaboration
+3.2.1.3.1 Message Store
+The message server provides persistent storage of messages and messaging account settings. It does this by providing a message store consisting of a tree of message entries. Multiple clients can access the message store simultaneously. Each entry in the tree can represent an email account, folder of messages, message part, etc.
+
+Figure 4 Message Store
+Figure 4 shows an example message store. The tree is broken down in to three levels:
+1. The Root entry. This entry is just present to tie the tree structure together
+2. Service entries. There is one local service under which local folders and messages are stored, and zero or more remote services. Remote services represent message accounts.
+3. Message & Folder entries. Messages and folders, under the local service represent messages stored on the device. Messages and folders under remote services represent a local copy of messages that are present on a remote server. For example under a POP3 email service you would have copies of all the messages present on the POP3 email server, or under an SMS service you might find SMS messages that are stored on a SIM.
+The message server controls access to the entries in the store. It enforces the three levels therefore attempts to create message or folder entries directly under the root entry will fail.
+The message server provides three types of storage for each entry in the message store:
+• Index entry - TMsvEntry - intended to provide enough information for UI to display list views as shown in Figure 5. This consists of two strings and various flags (read, complete, has attachments etc).
+• Stream based file store - CMsvStore – provides storage of streams of data associated with UIDs. A standard UID is defined for storing body text. Other UIDs are specific. For example the email MTMs define a UID for storage of MIME headers. Compared to the index entry information this is used to store larger objects and is extensible, at the cost of being slower to access. From v9.0 and onwards CMsvStore provides an Attachment API for managing attachments. The Attachment API should be used as attachments can no longer be accessed directly due to Platform Security.
+• Directory of files – normally used for attachments.
+The only storage type that is always present is the index entry. The stream store and the directory of files are optional.
+
+Figure 5 Series 60 Inbox List View
+
+Figure 6 Remote and Local Entries
+As shown in Figure 6 the message store is split into two sets of entries:
+• Remote entries - entries that are representations of entries stored on a remote store .
+• Local entries - entries not linked to a remote store.
+The message server handles changes to local entries; internally it hands off changes to remote entries to the Server MTM that owns that service. Examples of operations that are handed off to Server MTMs are operations involving copying and moving messages to and from a remote service. See section 3.2.1.3.5 or more information on Server MTMs.
+Each entry within the store has a type:
+Folder – Messages can be grouped into folders. Standard folders such as inbox / outbox and user created folders.
+Message – Storage of the content of a message. Message entries can have child entries used to represent the structure of a message.
+Attachment – These represent attachments under a message entry.
+Root & Local Service Entry – There tie the tree structure together. However the Stream store associated with the root entry is sometimes used by UIs to store preferences e.g. default folder views etc.
+Remote Service - Represents a source and / or destination for messages. They are used to store the settings associated with the source / destination.
+Message Type Specific - MTMs can create other message types for use as child entries to messages they own. For example email uses a tree structure, with a message entry as the root, to represent the MIME structure of an email message; it uses folder entries to represent MIME folders and adds new types for entries representing the html body and text body parts of a message. This is shown in Figure 7.
+
+Figure 7 Email Message
+Using the message store to represent message structure allows reuse of the tree structure and makes it very simple to represent one message embedded in another. However this representation introduces performance issues as it results in each message having multiple files associated with it. The message server also keeps all index entries in memory; therefore this representation increases the memory footprint of the message server. Therefore when designing new MTMs we should think about moving away using multiple index entries to store one message in the message store.
+A default message store is created if the message server starts and no message store is present or a corrupt message store is present. The server will initially create a store with just a root entry, and then the server will create any standard folders defined in the resource file msgs.rsc. Finally the server will check whether an executable ‘mailinit.exe’ is present on the system, if it is present the server will launch the executable to allow customisation of the message store. The behaviour of ‘mailinit.exe’ is defined by the UI family of the device. However the typical behaviour is to load each of the UI Message Type Modules and allow each to perform any message type specific initialisation. For example the SMS plug-in typically creates a default service entry.
+
+3.2.1.3.2 Data File Storage (pre - v9.0)
+This section describes the files used by the message server before release v9.0. For information on the files used for release from v9.0 and onwards see section [3.2.1.3.3.1].
+Filename Access Purpose
+?:\system\Mail\index Private Message server index file, internal to message server
+?:\system\Mail\<8 hex digits> Shared via API Message server store files for services, clients access these via a messaging API.
+?:\system\Mail\<8 hex digits>.new Shared via API Temporary file used during committing message server store files.
+?:\SYSTEM\MAIL\<8 HEX DIGITS>_F\* Shared Files associated with a messaging service. These may be accessed directly by clients.
+?:\system\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits> Shared via API Message server store files for message entries, clients access these via a messaging API.
+?:\system\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits>.new Shared via API Temporary file used whilst committing message server store files.
+?:\system\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits>_F\* Shared Files associated with a message entry. These are accessed directly by clients.
+c:\system\data\msgs.ini Private Stores the drive containing the last used message store
+c:\system\Mtm\Mtm Registry v2 Private Cache of registered MTMs, internal to message server
+C:\system\data\sms_settings.dat Shared Copy of the SMS settings.
+?:\System\Mail\StoreInit.tmp Shared Created when message server runs ‘mailinit.exe’, ‘mailinit.exe’ should delete the file when it has successfully completed.
+?:\System\Mail\storedeleted.tmp Shared Created when message server finds and deletes a corrupt message store. Allows the UI to inform the user about the fact that the message store was corrupt.
+Files that are shown as private should only be accessed by the message server or by connectivity process for backup and restore purposes. Files listed as shared are accessed directly by messaging clients. Files listed as shared via API are accessed by client process but only via messaging APIs.
+3.2.1.3.3 Platform Security Compliant Message Store
+From v9.0 and onwards the message store is stored in the message server's data cage and the settings data are placed in the Central Repository. Access to the message store is only possible via message server APIs and not directly through file access. This leads to secured data storage and secured platform.
+3.2.1.3.3.1 Data caging
+Filename Purpose
+?:\private\<SID>\Mail\index Message server index file, internal to message server
+?:\ private\<SID>\Mail\<8 hex digits> Message server store files for services, clients access these via a messaging API.
+?:\ private\<SID>\Mail\<8 hex digits>.new Temporary file used during committing message server store files.
+?:\ private\<SID>\Mail\<8 hex digits>_F\* Files associated with a messaging service. These may be accessed directly by clients.
+?:\ private\<SID>\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits> Message server store files for message entries, clients access these via a messaging API.
+?:\ private\<SID>\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits>.new Temporary file used whilst committing message server store files.
+?:\ private\<SID>\Mail\<8 hex digits>_S\<hex digit>\<8 hex digits>_F\* Files associated with a message entry. These are accessed directly by clients.
+c:\ private\<SID>\data\msgs.ini Stores the drive containing the last used message store
+c:\ private\<SID>\Mtm\Mtm Registry v2 Cache of registered MTMs, internal to message server
+?:\ private\<SID>\Mail\StoreInit.tmp Access via IPC call
+?:\ private\<SID>\Mail\storedeleted.tmp Created when message server finds and deletes a corrupt message store. Allows the UI to inform the user about the fact that the message store was corrupt.
+?\resource\messaging\bif\*.bif Registration data field with UID used in BIO framework
+
+3.2.1.3.4 How message centres display the message store
+The UI normally provides a Message Centre application to display the structure of the message store to the user. Different UIs map the structure to different views.
+
+Figure 8 Series 60 Message Centre (Composed from 2 screen shots)
+Figure 8 shows the top level view of the message centre application on a Series 60 phone. This shows that the message centre has hidden the local service and shows the standard folders at the same level as the services. Also the SMTP, SMS and MMS services are marked as hidden entries in the message store, and so do not appear in the message application.
+
+Figure 9 UIQ Message Centre
+However Figure 9 shows that the UIQ message centre has no 1-1 mapping from the structure in the message store to the structure shown to the user. Each of the message types is displayed as if its messages were contained in separate folders. Under each of these folders the user is presented with an inbox, outbox, send and drafts folder. This filtering is done in the UI layer as this functionality is not provided by the messaging API.
+3.2.1.3.5 Message Type Module Architecture
+
+Figure 10 Messaging MTM Structure (light coloured components are part of messaging subsystem)
+The MTM architecture is the plug-in scheme provided by the messaging framework to integrate different message transports into the message server. The plug-in scheme consists of four interfaces, the UI MTM, UI Data MTM, Client MTM and Server MTM. The messaging client applications loads and uses the first three which are loaded within the client’s process space. The final one the Server MTM is loaded within the message server process. The APIs for the client facing interfaces are extensible via run time type information provided by the QueryCapability API, and the InvokeAsyncFunction and InvokeSyncFunction APIs.
+3.2.1.3.5.1 UI MTM
+Handles requests from clients to view and edit messages or service settings. The MTM handles interaction with the message centre and as such the exact meaning of the APIs is defined by the UI. However common meanings are:
+• Create – Launches the editor with a new message.
+• Edit – If entry is a message this launches the editor; if entry is a service it edits the settings.
+• View – Launches the message viewer.
+• Display progress of an operation.
+3.2.1.3.5.2 UI data MTM
+This MTM provides fast access to UI components such as menu resources and bitmaps required by message centre for list views etc. Again the exact semantics are UI specific.
+There is a resource file defining UI specific functions, for example the Series 60 Messaging UI checks if the resource file contains text to display in the “New Message” menu.
+The UI data MTM also provides mapping from the message store’s TMsvEntry structure to Icons for the messaging list views and a status string, for example in the case of Nokia 9210 it is used in the outbox view to provide strings like “Resend 01:07” as shown in Figure 11. The class also provides functions to determine what operations are possible with a given entry. Examples of this are APIs that return whether the UI should allow the user to reply to the entry or to delete a service entry. The UI then uses this information to determine which menu options / short-cut keys should be allowed when the user selects a given entry.
+
+Figure 11 Nokia 9210 Outbox List View
+3.2.1.3.5.3 Client MTM
+Provides methods to create / reply and forward messages. Functions the Client MTMs provide are:
+• Create Message.
+• Reply to a Message.
+• Forward a Message.
+• Add / remove Addressees.
+• Add / remove body text.
+• Add / remove subject.
+• Add / remove attachments (the API cannot list attachments).
+The Client MTM interface is used by SendAs to provide a way of creating messages independently of the message type.
+3.2.1.3.5.4 Server MTM
+This is the final interface that makes up an MTM plug-in; it differs from the other three plug-ins in that it is loaded into the message server’s process space. The Server MTM provides access to messages under remote services. It handles connecting to remote servers to handle updating the local cache of these messages or to send messages copied to remote services when messages are copied to a remote service. The message server loads and hands off all message store operations that involve entries under a remote entry, these are the entries on the left-hand side of Figure 6.
+Functions that a Server MTM must implement:
+• Copy/MoveToLocal – called when the message server is asked to move or copy an entry that is currently under a remote service. A Server MTM might map this to retrieving a message from a remote mailbox.
+• Copy/MoveFromLocal – called when the message server is asked to move or copy from under the local service to a destination under a remote service. A Server MTM should map this to sending a message if the MTM supports sending.
+• Create, Delete, Change – called when the message server is asked to perform these operations on entries under a remote service.
+• StartCommand – this API provides a means of extending the API the Server MTM provides. Messaging clients pass a command ID and a selection of entries via the message server to the Server MTM. Examples of commands that Server MTMs might provide are: connect and synchronise the entries under a remote service with the messages on an email server, list SMS messages present on the phones SIM. These commands are MTM specific and therefore clients have to know which MTMs support which commands.
+3.2.1.3.5.5 MTM Registration
+MTMs must be registered with the message server so that clients can query what MTMs are present and the server knows which DLL to load to create a given MTM component. MTMs are registered by providing a resource file containing the MTMs UIDs, human readable name, and for each MTM interface it lists a DLL and the ordinal at which the constructor for that interface exists. The message server will search the ROM drive for MTM registration resource files on start-up and it will automatically register any MTMs found. For registration of MTMs installed on other drives, the message server provides an API to register and de-register an MTM. Registration will persist across a reboot, so an MTM only needs to be registered when it is installed on the system.
+When MTMs are registered or unregistered the message server will send events to all messaging clients with a message server session open.
+3.2.1.3.6 Message Server Client API
+The Messaging Server Client API breaks down into two categories: APIs for manipulation of the message store and utility APIs.
+3.2.1.3.6.1 Message Store manipulation APIs
+Requests from clients to modify the message store fall into three categories:
+1. Operations performed entirely with local entries (entries on the right-hand side of Figure 6) for example requests to create entries in the inbox, delete an entry from the drafts folder etc. The message server handles these operations directly.
+2. Operations that involve a remote entry (entries on the left-hand side of Figure 6) for example requests to delete an entry under a POP3 service, or copy a message to an SMTP service. The message server hands these operations off to the Server MTM that owns the service under which the remote entry is stored. The only exception to this rule is the ChangeAttributes API call. This modifies flags on an index entry and is handled by the message server for both local and remote entries. This means that a Server MTM can not rely on being called when flags like the Unread flag are changed. Note that operations can not involve two remote entries; therefore requests to copy entries between a remote service representing one POP3 account to a remote service representing another POP3 account will fail with an error.
+3. Requests that are explicitly directed at a Server MTM via the TransferCommand API. These commands are just passed to the correct Server MTM by looking up the Service ID and MTM of the first message in the selection passed into the command.
+The message server sends events when entries in the message store are modified to messaging clients that have a session open with the server.
+Where the API provides asynchronous functions to modify the message store or transfer a command to a Server MTM, the functions will return a message server operation object. This object can be used to request progress on operation or cancel the operation. Deleting the operation object returned, or closing the session used to make the request will result in the operation being cancelled, therefore a messaging client must remain running until operations it has requested have either completed or they will be cancelled. See appendix A.1 for an example of an asynchronous copy operation. If a Server MTM operating on the same remote service is already handling an operation, the message server will queue the new operation to be handled when the Server MTM becomes free. Requests for progress of operations that are queued will fail with KErrNotReady. The fact that the queue is based on the remote service ID means that you can have two Server MTMs of the same type running at the same time as long as they are operating on different services. So for example you can have two separate POP3 MTMs running synchronising different remote services with email servers.
+3.2.1.3.6.2 Utility APIs
+1. Access to MTM registries – These allow clients to construct instances of the interfaces an MTM implements.
+2. Register / Unregister an MTM.
+3. Change Drive – The message server closes the current message store and opens one on the drive specified. If no message store is present on the drive specified a new message store is created. The message sever can have only one mail store open at a time, if the current mail store is not available because a the disk the mail store is on is not present then the message server will switch the mail store back to the C: drive if an attempt is made to create a message in the inbox.
+4. Launching Editors – This launches the correct editor for a message. It is implemented by delegating the request to the UI MTM
+3.2.2 Messaging / Send As APIs
+3.2.2.1 Key Relationships and Dependencies
+
+Figure 12 SendAs Version 1 Dependencies
+SendAs version 1 and only present in releases before v9.0. SendAs uses the Messaging Client API to access the registry of Client MTMs and construct the Client MTM interfaces. The Client MTMs are then used for composing the message. SendAs requires clients to implement the MSendAsObserver interface. This interface is responsible for checking the return value of the capability queries made to Client MTMs that require a response and also for rendering message types that require it. The only message type supplied by Symbian that requires rendering is Fax, however this MTM has been removed in 8.0a and future releases.
+3.2.2.2 API Purpose - Further Elaboration
+3.2.2.2.1 SendAs API (pre – v9.0)
+The SendAs API makes use of the Client MTM interface and the Messaging Client API to provide a generic API for creating messages. Note despite the name of this component SendAs does not provide an API to send the message.
+SendAs builds a list of registered MTMs, then queries each MTM to check whether it supports sending, removing those MTMs from the list that do not support sending. This list is then provided to the messaging client application. At this point the application can add more constraints on the list of MTMs; for example it can insist the MTM supports Attachments or more than a certain size of body text. SendAs queries each of the MTMs about the requirements and will drop any MTMs from the list that does not meet them. When the application has finished adding requirements it selects one of the MTMs left in the list and uses that to compose the message, adding addresses, a subject, body text and attachments.
+SendAs supports setting a BIO Type for the message that is composed. This tells the transport that the body text represents a BIO Message. This is used when sending business cards from the contacts application as SMS messages; the contacts application puts the vCard data in the body text of the message and the transport sends it correctly. If the MTM in question supports attachments then the vCard is attached to the message.
+A new CSendAs object must be created for each message the application wishes to create.
+3.2.3 Platform Security Compliant SendAs Server (v9.0 onwards)
+
+Figure 13 SendAs Version 2 Dependencies
+From v9.0 and onwards the CSendAs has been replaced by the SendAs server component. The new SendAs server controls the access to the message store. Some of the key SendAs Server features are listed as follows.
+• Send a message once the capability policing of the client application has been completed.
+• Allow client applications to launch an editor for a specified message type.
+• Allow client applications to query the message type.
+The main client-side API is the RSendAs class. The client applications use this to connect to the Send-As server. The session object on the server-side is an instance of CSendAsSession.
+Client applications create messages using the RSendAsMessage API. Opening an RSendAsMessage object on Send-As server session creates a CSendAsMessage object in the Send-As server. There is a one-to-one mapping between an RSendAsMessage object and a CSendAsMessage object. This allows client applications to create multiple messages concurrently.
+
+3.2.4 Messaging / Schedule Send APIs
+3.2.4.1 Key Relationships and Dependencies
+
+Figure 14 Schedule Send Dependencies
+The Schedule Send Server MTM base class depends on the task scheduler to launch the schedule send executable at the correct time. To send the message with a package of data previously passed into the task scheduler by the Server MTM. The schedule send executable then uses the Messaging Client API to actually perform the requested operation.
+3.2.4.2 API Purpose - Further Elaboration
+3.2.4.2.1 Schedule Send
+The Schedule Send functionality is delivered by four components:
+Server MTM Base Class – The base class provides support to Server MTMs that wish to support scheduled operations.
+Data Structures – These are classes used to represent the data associated with a scheduled operation.
+Executable – The executable is run by the task scheduler at the scheduled time.
+The Task Scheduler – This component is part of the system libraries subsystem. Currently the SMS and Fax Server MTMs support scheduled sending.
+Clients request the Server MTM schedules operations via additional commands passed to TransferCommand API; this is passed to the Server MTM via the message server. The Server MTM packages the operation ID, a selection of message IDs, how often to poll for progress and an MTM specific buffer. It then passes this package of data to the task scheduler requesting that it launches the schedule send executable at the correct time with the packaged information.
+When the task scheduler launches the schedule send executable, it unpacks the schedule information and uses the Messaging Client API to request the Server MTM to perform the operation.
+Schedule Send supports a retry mechanism if the operation fails. The Server MTM has a resource file containing a mapping from the error codes the operation can fail with and actions to be performed. For example the SMS resource file has a mapping such that if the operation fails with an error code indicating a bad phone number the SMS will be set to failed and left in the outbox. Whereas if it fails with a error code indicating temporary network failure the send operation will be scheduled to be resent later with a maximum of three retries.
+3.2.5 Messaging / Watchers APIs
+3.2.5.1 Key Relationships and Dependencies
+
+Figure 15 Watcher Dependencies
+The watcher executable’s dependency on the message server is the result of a performance measure. The watcher process creates a message server session before initialising each of the watcher plug-ins and closes the session when it has finished. This keeps the message server running during initialisation avoiding starting and stopping the message server if each watcher plug-in opens and closes sessions.
+3.2.5.2 API Purpose - Further Elaboration
+The watcher framework consists of an executable that is launched when the device boots. The component that is responsible for launching it depends on the UI family. When the watcher.exe is launched it will load each DLL in z:\system\libs\watchers which has a second UID as KWatcherUid and calls the first DLL entry point to construct a CActive object.
+From v9.0 and onwards watcher DLLs are found by scanning the directory \resource\messaging\watchers for registry files. These files contain the name of a watcher DLL that can be loaded from ROM i.e. z:\sys\bin.
+The framework has retry behaviour if the first entry point leaves, in this case the watcher framework will start a timer and try and construct the watcher object 10 seconds later. Five attempts are made before the watcher plug-in is assumed to have failed completely. Once the watcher framework has constructed all the watchers it starts the active scheduler which should never exit.
+Watcher plug-ins typically make a request to another subsystem such that they will be completed when an external event like a fax line ringing or an SMS being received occurs. When the watcher has completed processing the request it will wait for the next event.
+No support for starting / stopping watchers is provided. This is a limitation that makes watchers unsuitable for operations like listening for messages beamed via IR, as the watcher should only run while the IR port is active.
+3.2.6 Messaging / Message URL Handler APIs
+3.2.6.1 Key Relationships and Dependencies
+
+Figure 16 Message URL Handler Dependencies
+3.2.6.2 API Purpose - Further Elaboration
+The Message URL Handler provides support for creating messages and launching messaging editors from URLs such as mailto:infobot@example.com?subject=current-issue. Note there is no dependency between the Message URL Handler application which processes the URLs and the Message URL Handler recognisers which maps from URLs to mime types.
+3.2.6.2.1 Message URL Handler Application
+This is a Symbian OS application that registers with the application framework that it can handle the mime types: x-epoc-url/fax, x-epoc-url/mailto and x-epoc-url/sms. When launched with a URL it will parse the URL to retrieve the address and other header fields and then use the SendAs API to create a new message with the correct address, headers etc. The application then uses the APIs in the MturUtils class provide by the mtmbase component in the messaging framework to launch the correct editor for the given message type. The application is marked as hidden and therefore should not be listed by UIs in application browsers.
+3.2.6.2.2 Message URL Recognisers
+This is a plug-in to the recogniser framework it will be called when the application framework wishes to recognise a file. Recognisers are called with the file name, in this case a URL, and a buffer containing the start of the file. The message URL recogniser compares the start of the URL with the URL schemes it recognises, if it finds a URL scheme it knows about it maps it to a mime type. The recogniser ignores the buffer passed in.
+Schemes recognised:
+Scheme Mime type
+mailto: X-Epoc-Url/mailto
+fax: X-Epoc-Url/fax
+sms: X-Epoc-Url/sms
+mms: X-Epoc-Url/mms
+See the application framework architectural description for more information on recognisers [R2].
+3.2.7 Messaging / SMS APIs
+3.2.7.1 Key Internal Relationships and Dependencies
+
+Figure 17 SMS Internal Dependencies
+3.2.7.2 Key External Relationships and Dependencies
+
+Figure 18 SMS External Dependencies
+3.2.7.3 API Purpose - Further Elaboration
+3.2.7.3.1 SMS Watchers
+The SMS watchers are made up of two watchers, the nbswatcher.dll and the wapwatcher.dll, and some common base classes in biowatcher.dll. The watchers listen for incoming messages from the SMS stack, part of the nbsprotocols subsystem [R3], and the WAP stack part of the WAP-Stack subsystem [R4].
+3.2.7.3.1.1 NBS Watcher
+The NBS watcher handles reception of SMS messages. When initialised by the watcher framework (see section 3.2.4) the watcher queries the bio messaging database for bio messages that are listed as having a type of ENbs. For each of these bio messages the watcher creates an object that opens a connection to the SMS stack and waits for the particular message type. The message types are either defined by the port number the message will be received on or by a string to watch for at the start of the message. For example Internet Access Configuration Point messages are start with “//SIAP11” and vCards are received on port 226. Finally the watcher listens for all other messages received from the SMS stack.
+When the NBS Watcher receives a non-class 2 SMS message it creates a new entry under the global inbox in the message store. For class 2 messages the entry is created in the class 2 folder as defined by the SMS settings, this may also be the global inbox. The details field of the entry is used to store the phone number of the incoming message or the name of the sender if the watcher finds a match for the phone number in the contacts database. The description field is used to store the first N characters of the SMS message, where N is defined in the SMS settings, or for bio messages the description as retrieved from the bio database. Bio messages also have the BioType field set to the UID of the bio message as retrieved from the bio database. The CSmsHeader class, which is a wrapper around the CSmsMessage class provided by the nbprotocols subsystem [R3], is used to externalise the SMS message to the entry’s CMsvStore. The watcher also places a copy of the body text of the message in the rich text stream of the entry’s CMsvStore.
+The NBS Watcher is also responsible for handing special SMS types including:
+• Replace Type Messages – When the watcher receives a message of this type it will scan the folder the message would have been delivered to for messages that have a matching protocol ID and from address. For each of the messages it checks whether the time stamps from the service centre and discards the older message.
+• Message Indications – The watcher can listen for incoming message waiting indications. The CSmsSettings class defines whether the watcher will listen and whether it will deliver the messages to the inbox or discard them. If the watcher is configured to listen for messages then it will use the SMS utilities in the SMS Client MTM to decode the message to determine the notification type and number of messages, e.g. 3 Email messages waiting, the strings for these messages are in the smss.rss resource file.
+• Delivery Reports – As with Message Indications the watcher can be configured to listen for these and again the SMS utilities get a string from the smss.rss resource file to put in the description field.
+The NBS Watcher handles changes to the bio database using the observer mechanism provided by the bio message database to observe when bio message types are added or removed and starting or stopping the object watching for that bio message type.
+3.2.7.3.1.2 WAP Watcher
+The WAP watcher listens for incoming messages from the WAP stack using the WAP message API [R4]. To determine ports to use to listen for messages the watcher queries the bio message database for bio message types EWsp, EWspSecure, EWap, EWapSecure and registers as an observer of the bio database and so will listen for new bio message with these types as they are added. The watcher stores the messages in the global inbox tagged with the bio type listed in the bio message database.
+3.2.7.3.2 SMS Client MTM
+The SMS Client MTM implements the standard set of Client MTM APIs described in Client MTM. In addition it provides:
+• Access to the CSmsHeader object that is used to represent the SMS message.
+• Access to the SMS settings stored in the associated SMS service.
+• The APIs required by Send As to allow Send As to create SMS messages including setting the bio type of the message to allow clients of Send As to send bio messages such as vCards and vCals. The data of the bio message is stored in the body text of the SMS message.
+• Simple check for valid SMS addresses, and SMS address is considered valid if it contains at least one digit.
+• Reading and writing SIM parameters.
+3.2.7.3.3 SMS Utilities
+These provide:
+• Classes to represent and store SMS messages (CSmsHeader), and SMS settings (CSmsSettings, CSmsMessageSettings) and a SMS number (CSmsNumber).
+• The CSmsHeader class contains and allows clients to access the CSmsMessage class that the nbsprotocols subsystem provides. This contains the entire SMS message and not just the header.
+• Functions to generate descriptions and details fields to store with SMS messages, including decoding special messages such as message indication and status report messages, reading resource file for descriptions strings of special messages, using the contacts database to replace phone numbers with names.
+• API to validate a GSM number.
+• Find the TMsvId of the SMS service entry.
+3.2.7.3.4 SMS Server MTM
+3.2.7.3.4.1 Sending Messages
+The SMS Server MTM handles sending of SMS and WAP messages via the SMS stack and the WAP stack. To support this it implements the CopyFromLocal API inherited from the Server MTM base class. It implements this as sending SMS messages and moving successfully sent messages to the Sent folder. When sending the SMS message the Server MTM checks the bio type of the message and uses the bio database to check the transport type for the bio message. The MTM supports ENbs that is sent via the SMS stack and EWap, EWapSecure that are sent via the WAP stack. The MTM does not support EWsp or EWspSecure although the watchers do support receiving them.
+If a message fails to send, sending is retried according to the settings in the smss.rss resource file as described in the schedule send section 3.2.3.
+3.2.7.3.4.2 Scheduling Messages
+The SMS Server MTM implements scheduled sending API by sub-classing from the schedule send Server MTM (see section 3.2.3). It accepts requests from clients either via the SMS Client MTM InvokeAsync API or via the CMsvSession::TransferCommand API to schedule messages to be sent or to delete existing schedules. When it receives a request to schedule a message it packages up the command and uses the scheduled send functionality to request that the task scheduler ask it to send the messages at a future point in time.
+3.2.7.3.4.3 Phone Store
+The phone store is the name given to storage of SMS messages outside of the message store. In the case of GSM phones this is the SIM. The SMS Server MTM accepts requests from clients to copy/move messages to and from the SIM and delete messages from the SIM. For example when copying to the SIM it packages up the SMS message and passes it to the SMS stack with a request to write it to the SIM. If the class2 folder has been set in the SMS settings class then the Server MTM will copy the SMS message to the SIM and then update the SMS message in the message store with details of the slot on the SIM that has been used to store the SMS and the fact that it is stored on the SIM.
+3.2.7.3.4.4 SIM Parameters
+The Server MTM provides functions to read / write SIM parameters, again these requests are passed to the SMS stack to be processed.
+3.2.8 Messaging / CDMA SMS APIs
+3.2.8.1 Key Internal Relationships and Dependencies
+
+Figure 19 CMDA SMS Internal Dependencies
+3.2.8.2 Key External Relationships and Dependencies
+`
+Figure 20 CDMA SMS External Dependencies
+3.2.8.3 API Purpose - Further Elaboration
+3.2.8.3.1 CDMA SMS Watchers
+The CDMA SMS watchers are made up of six watchers, the cdmanbswatcher.dll, vmnwatcher.dll, wemtwatcher.dll, wmtwatcher.dll, wptwatcher.dll, and the wapwatcher.dll, and some base classes in biowatcher.dll and cdmasocketwatcher. While the WAP watcher is common for both GSM and CDMA, the other watchers: CDMA NBS watcher, VMN watcher, WEMT watcher, WMT watcher, and the WPT watcher are used for CDMA only. The watchers listen for incoming messages from the CDMA SMS stack, part of the nbsprotocols subsystem [R3], and the WAP stack part of the WAP-Stack subsystem [R4].
+3.2.8.3.1.1 CDMA NBS Watcher
+The CDMA NBS watcher is similar to the NBS watcher and it handles bio messages defined in bio database. The CSmsHeader class is extended to wrap around the CCdmaSmsMessage class provided by the nbprotocols subsystem [R3], and is used to externalise the CDMA SMS message.
+For handling special CDMA SMS type, the CDMA NBS watcher is responsible for handling Message Indications as described in section 3.2.7.3.1.1 NBS Watcher.
+3.2.8.3.1.2 WAP Watcher
+The GSM WAP watcher is used to handle CDMA WAP message as well. The WAP watcher listens for incoming messages from the WAP stack, which can listen from the CDMA SMS stack or GSM SMS stack as appropriate. See 3.2.7.3.1.2 for more info about WAP watcher.
+3.2.8.3.1.3 Other CDMA Watchers
+The VMN watcher, WEMT watcher, WMT watcher and WPT watcher are CDMA watchers that handle reception of CDMA SMS messages. All CDMA SMS messages are associated with a teleservice. Therefore, each of the CDMA watchers is responsible for handling one teleservice: VMN watcher handles VMN SMS messages, WEMT watcher handles WEMT SMS messages, WMT watcher handles WMT SMS messages, and WPT watcher handles WPT SMS messages. The CSmsHeader class is reused to externalise the CDMA SMS message.
+The CDMA watchers are also responsible for handling special SMS types including:
+• Duplicate Message – When the watcher receives a duplicate message, it will discard the duplicate message as defined by the CDMA service settings.
+• User Acknowledge – The watcher can listen for user acknowledgment message of its teleservice type.
+• Delivery Acknowledge – The watcher can listen for delivery acknowledgment message of its teleservice type.
+• Read Acknowledge – The watcher can listen for read acknowledgment message of its teleservice type.
+3.2.8.3.2 CDMA SMS Client MTM
+The CDMA SMS Client MTM implements the standard set of Client MTM APIs described in Client MTM. In addition it provides:
+• Access to the CSmsHeader object that is used to represent the SMS message.
+• Access to the SMS settings stored in the associated SMS service. These settings are store in file store pre v9.0 but stored in Central Repository from v9.0 onwards.
+• The APIs required by Send As to allow Send As to create SMS messages including setting the bio type of the message to allow clients of Send As to send bio messages such as vCards and vCals. The data of the bio message is stored in the body text of the SMS message.
+• Simple check for valid SMS addresses, and SMS address is considered valid if it contains at least one digit.
+• Reading and writing SMS messages to R-UIM.
+3.2.8.3.3 CDMA SMS Utilities
+The CDMA version of SMS utilities are binary compatible with the GSM version of SMS utilities. But the classes that store SMS Message (CSMSHeader), and SMS settings (CSmsSettings, CSmsMessageSettings) and SMS number (CSmsNumber) are extended to store CDMA information. The CSmsHeader class is extended to contain and allow clients to access the CCdmaSmsMessage in addition to the CSmsMessage. Other functions provided by the GSM SMS Utilities is also provided by the CDMA version of SMS utilities, see 3.2.7.3.3 for information about GSM SMS Utilities.
+3.2.8.3.4 CDMA SMS Server MTM
+3.2.8.3.4.1 Sending Messages
+The CDMA SMS Server MTM handles sending of CDMA SMS and WAP messages via the CDMA SMS stack and the WAP stack. To support this it implements the CopyFromLocal API inherited from the Server MTM base class. It implements this as sending SMS messages and moving successfully sent messages to the Sent folder. When sending the CDMA SMS message the Server MTM will use the appropriate teleservice type. The MTM supports ENbs that is sent via the SMS stack and EWap, EWapSecure that are sent via the WAP stack. The MTM does not support EWsp or EWspSecure although the watchers do support receiving them.
+If a message fails to send, sending is retried according to the settings in the smss.rss resource file as described in the scheduled send section 3.2.4.
+3.2.8.3.4.2 Scheduling Messages
+The CDMA SMS Server MTM implements scheduled sending API by sub-classing from the schedule send Server MTM similar to implemented in the GSM SMS Server MTM. See 3.2.7.3.4.2 for more information.
+3.2.8.3.4.3 Phone Store
+In the case of CDMA phones, phone store can be phone-based storage or R-UIM based storage. The CDMA SMS Server MTM accepts requests from clients to copy/move messages to and from the phone/R-UIM and delete messages from the phone/R-UIM. For example when copying to the R-UIM it packages up the SMS message and passes it to the CDMA SMS stack with a request to write it to the R-UIM.
+3.2.8.3.5 Configuration for using CDMA SMS MTM
+The CDMA messaging components currently only support single mode, but it is designed such that it can become multimode in the future. Currently, -Dcdma option is used to for selecting CDMA mode for using emulator and building ROM.
+
+
+3.2.9 Messaging / Email APIs
+3.2.9.1 Key Internal Relationships and Dependencies
+
+Figure 19 Email Internal Dependencies
+
+3.2.9.2 Key External Relationships and Dependencies
+
+Figure 20 Email External Dependencies
+3.2.9.3 API Purpose - Further Elaboration
+3.2.9.3.1 Email Overview
+The Email plug-ins consist of a set of utilities and MTMs for POP3, IMAP4 and SMTP. For each email account a pair of services entries is created in the message store. For a POP3 account there will be an SMTP service and a POP3 service, for an IMAP4 account there will be an SMTP service and as IMAP4 service. These entries are used to store the settings for the email transport. Each of the service entries has its related ID set to the other member of the pair. The SMTP service is created invisible so the user only sees the POP3 or IMAP4 service entry, copying a message to the SMTP service will cause the SMTP Server MTM to attempt to send the message. The POP3 and IMAP4 MTMs provide functionality to synchronise with a remote email server this is achieved by extending the Client MTM interface via the InvokeAsync API. Synchronisation of a POP3 or IMAP4 account will result in copying headers and optionally body text and attachments from the email server and creating message entries under the POP3 or IMAP4 service entry.
+Email messages are represented in a common format whether they are being sent via SMTP or downloaded via POP3 or IMAP4. The email client utilities provide the classes for creating and manipulating the entry structure used to store emails. The email server side utilities provide classes to convert between the entry structure used to store emails in the message store and RFC2822 email messages sent to SMTP servers and retrieved from POP3 servers. IMAP4 email messages are parsed by the email server and the IMAP4 Server MTM requests and stores the individual parts of the messages.
+3.2.9.3.2 Email Client Utilities
+The email client utilities are part of the imcm DLL and provide classes for:
+• Storage of email messages including mime headers, RFC2822 headers, attachments, body text and encoding information in the message store
+• Manipulating email messages, for example adding attachments, replying etc.
+• To wrap up the character converters used to convert between standard character sets and Unicode. These make use of the charconv component that is part of the system libraries subsystem.
+• Storage of Email settings in the message store.
+• Progress information for email operations.
+The utilities are used directly by clients to access parts of email messages for display. CImEmailMessage provides the functionality used by clients displaying email messages, including listing attachments, getting body text and resolving URIs in M-HTML messages.
+The Email Client MTMs use the utilities when they are asked to create, reply to and forward messages CImEmailOperation provides the functionality to perform these operations. Each email message is represented by a parent message entry and then entries to represent mime folders and mime parts, see Figure 7 for an example, so adding or deleting mime parts involves walking the tree of entries and inserting / removing entries as appropriate.
+3.2.9.3.3 Email Server MTM Utilities
+The Email Server MTM Utilities are responsible for generating and parsing of RFC2822 format email messages and providing an API to wrap up a TCP/IP connection to a remote email server.
+• Parsing of RFC2822 Email Messages – The utilities provide an API that accepts the text of an RFC2822 email message a line at a time and stores the email message in messaging’s internal format for email messages. See the Email Client Utilities for details of this format. The API handles storing of RFC2822 headers, MIME headers, decoding of Base64 encoded or uuencoded attachments and decoding of text received in character sets supported by the charconv component. This API is only accessible to Server MTMs, as it requires classes that can only be instantiated while running within the message server process. See the Messaging Functional Specification [R1] for detail on which email specifications the utilities support.
+• Generation of RFC2822 Email Messages – The utilities provide an API to convert an email in messaging’s internal format into an RFC2822 email message. The API provides access to the RFC2822 text a line at a time for streaming to an SMTP server. The exact format of the email depends on the settings passed in; the API can generate plain RFC2822 email messages with uuencoded attachments, MIME email messages with Base64 encoded attachments, or M-HTML email messages with Base64 encoded attachments. See the Messaging Functional Specification [R1] for detail on which email specifications the utilities support.
+• TCP/IP socket wrapper – The utilities provide a class that abstracts a TCP/IP socket supplied by the networking subsystem into an API that supports sending and receiving lines of text to / from a remote server. This API is used to connect to remote email servers by each of the email Server MTMs. The API can either create insecure or secure sockets enabling the SSL encryption provided by the networking subsystem. It also supports changing an insecure socket into a secure socket, this enables the email Server MTMs to implement email protocols where the initial connection to the server is insecure and then a secure socket is negotiated before sending or requesting any sensitive information.
+3.2.9.3.4 POP3 MTMs
+The POP3 MTMs implements the functionality to synchronise the local message store with a remote POP3 email server.
+3.2.9.3.4.1 Client MTM
+The POP3 Client MTM implements the standard Client MTM APIs and other extensions:
+• Reply to, forward – These are accessible via the ReplyL and ForwardL APIs of a Client MTM and are implemented as calls to the email utilities class CImEmailOperation.
+• Reply to, forward, create new messages, create receipts and forward as attachment – These are accessible as commands available via the InvokeAsyncFunction API of the Client MTM, they are implemented as calls to CImEmailOperation.
+• Connecting, disconnecting and copying email while connected – These operations are accessible as commands available via the InvokeAsyncFunction API of the Client MTM, they are implemented as calls to the POP3 Server MTM.
+• Querying connection status – This command lets clients know whether the POP3 Server MTM is connected to an email server, and is available via the InvokeAsyncFunction API of the Client MTM. The Client MTM requests the information from the Server MTM.
+• Compound operations – The Client MTM provides functionality to wrap up connecting to email servers, copying / moving new messages or a selection of messages, and then optionally disconnecting. These commands are available via the InvokeAsyncFunction API of the Client MTM. The Client MTM implements this by using the CImPOP3GetMail class which requests the correct sequence of operations from the Server MTM, waiting for each operation to complete before requesting the next one.
+• Send on next connection If the Client MTM gets a request to connect to an email server it will check whether the POP3 settings. If send on next connection is requested it will launch the autosend.exe executable (see section 3.2.7.3.7) to handle sending messages waiting in the outbox.
+• Offline operations – The POP3 Client MTM has a command to cancel offline operations, this is available via the InvokeAsyncFunction API of the Client MTM. The Client MTM passes the request to the Server MTM.
+3.2.9.3.4.2 Server MTM
+The POP3 Server MTM handles the communication with the remote POP3 server and implementation of the POP3 protocol. The MTM uses CImTextServerSession to handle the communication with the email server and CImRecvConvert to parse the email messages downloaded, both are provided by the Email Server MTM Utilities.
+• Connect – The POP3 Server MTM will open a socket to the email server using CImTextServerSession and login user the username / password in the POP3 settings. After a successful connection the Server MTM will attempt to synchronise the current state of headers stored on the email server with the set stored in the message store and then start any pending offline operations. After the connect operation has completed the Server MTM will inform the message server that it is expecting more operations via the CommandExpected API and therefore the message server will not delete and unload the Server MTM.
+• Populate Message – The POP3 Server MTM treats requests to copy a message from and to the POP3 service as a request to download the full message.
+• Offline operations – When the POP3 Server MTM receives a request to copy, move, or delete and is not connected to a POP3 email server the Server MTM will store the operation in the CMsvStore of the entry being modified and perform the operation on the next connection to the email server.
+• Disconnect – When disconnecting from a remote email server the POP3 MTM will run any pending offline operations stored. After the disconnect operation completes the Server MTM will allow the message server to delete and unload the Server MTM by setting the CommandExpected API to false.
+3.2.9.3.5 IMAP4 MTMs
+The IMAP4 Server MTM implements the functionality to synchronise the local message store with a remote IMAP4 email server.
+3.2.9.3.5.1 Client MTM
+The IMAP4 Client MTM implements the standard Client MTM APIs and other extensions:
+• Connecting, disconnecting, synchronising, un/subscribing folders – These operations are accessible as commands available via the InvokeAsyncFunction API of the Client MTM, they are implemented as calls to the IMAP4 Server MTM.
+• Send on next connection – If the Client MTM gets a request to connect to an email server it will check whether the IMAP4 settings. If send on next connection is requested it will launch the autosend.exe executable (see section 3.2.7.3.7) to handle sending messages waiting in the outbox.
+• Reply to, and forward messages – These are accessible via the ReplyL and ForwardL APIs of a Client MTM and are implemented as calls to the email utilities class CImEmailOperation.
+• Reply to, forward, create new, create receipt, forward as attachment – These are accessible as commands available via the InvokeAsyncFunction API of the Client MTM, they are implemented as calls to CImEmailOperation.
+• Querying connection status – These commands let clients know whether the IMAP4 Server MTM is connected to an email server and whether it is currently processing a request. They are available via the InvokeAsyncFunction API of the Client MTM. The Client MTM requests the information from the Server MTM.
+• Compound Connection and synchronisation – The IMAP4 Client MTM provides a compound operation that connects and synchronises with an IMAP4 server. This operation is implemented as a client side object that combines requests to the IMAP4 Server MTM. The client side operation can complete the client request either after the connection, after the connection + sync or after the connection + sync + disconnect. The client will keep requesting that the inbox be resynchronised at a configurable interval so new messages received in the inbox on the server will appear under the IMAP4 inbox. The CImapConnectAndSyncOp class handles these compound operations.
+• Compound Connect and copy / move / populate messages – The IMAP4 Client MTM provides a compound operation that connects to an IMAP4 server and copies moves or populates messages. The implementation is provided by the CImImap4GetMail class which makes calls back into the IMAP4 Client MTM.
+• Offline operations – The IMAP4 Client MTM has a command to cancel offline operations, this is available via the InvokeAsyncFunction API of the Client MTM. The Client MTM passes the request to the Server MTM.
+3.2.9.3.5.2 Server MTM
+The IMAP4 Server MTM handles the communication with the remote IMAP4 server and implementation of the IMAP4 protocol. The MTM uses CImTextServerSession to handle the communication with the email server. The IMAP4 Server MTM opens two connections to the IMAP4 server this enables users to download messages while the Server MTM is performing a background synchronisation if requested by the Client MTM.
+• Connect – The IMAP4 Server MTM will open a socket to the email server using CImTextServerSession and login using the username / password in the IMAP4 settings. After a successful connection the Server MTM will optionally attempt to synchronise the current state of headers stored on the email server with the set stored in the message store and then start any pending offline operations. After the connect operation has completed the Server MTM will inform the message server that it is expecting more operations via the CommandExpected API and therefore the message server will not delete and unload the Server MTM.
+• Copy, Move messages – The IMAP4 Server MTM supports copying and moving messages between folders on the IMAP4 server and between the IMAP4 server and local folders.
+• Delete messages – The IMAP4 Server MTM will mark the email as deleted on the server; however it will not be deleted until the IMAP4 Server MTM disconnects from the server.
+• Folders – The IMAP4 Server MTM will allow folders to be subscribed, unsubscribed, renamed, copied, moved, and created within the IMAP4 service. Subscribing to a folder means that it will be visible to the user and synchronised with the remote server. The inbox is always subscribed.
+• Offline operations – When the IMAP4 Server MTM receives a request to copy, move, or delete and is not connected to an IMAP4 email server the Server MTM will store the operation in the CMsvStore of the entry being modified and perform the operation on the next connection to the email server.
+• Disconnect – When disconnecting from a remote email server the IMAP4 MTM will run any pending offline operations stored. After the disconnect operation completes the Server MTM will allow the message server to delete and unload the Server MTM by setting the CommandExpected API to false.
+
+3.2.9.3.6 SMTP MTMs
+The SMTP MTMs provide functionality to send email messages. They are made up of the Client MTM that is part of the imcm DLL and the Server MTM.
+3.2.9.3.6.1 Client MTM
+The SMTP Client MTM implements the standard Client MTM APIs including the functions required to allow clients of Send As to create email messages.
+3.2.9.3.6.2 Server MTM
+The SMTP MTMs provide functionality to send email messages; it interprets requests to copy entries to an SMTP service as a request to send those messages. In addition it responds to two extended commands via the StartCommand Server MTM interface. These commands are KSMTPMTMIsConnected that responds with whether the Server MTM is currently connected to a remote SMTP server and KSMTPMTMSendOnNextConnection which performs the same operation as copying a selection of messages to an SMTP service. The only difference between the copy operation and the KSMTPMTMSendOnNextConnection operation is that the latter can be called without a selection of messages.
+When the Server MTM receives a request to send messages it builds a selection of messages consisting of the messages passed into the operation and any messages waiting in the outbox to be sent. To determine which messages in the outbox are waiting to be sent the SMTP server checks for messages that have the same service ID as the destination of the send operation and have a sending state of KMsvSendStateWaiting, KMsvSendStateScheduled or KMsvSendStateResend. This means that any request to send messages may result in more messages being sent than explicitly listed in the selection passed to the send operation.
+The Server MTM restores its settings from the SMTP service it has been asked to copy the messages to. Then it connects to the SMTP server using the CImTextServerSession class in the Email Server MTM Utilities, passing in the SMTP server address and TCP/IP port number from the SMTP settings. Then for each message to be sent the Server MTM uses the Email Server MTM utilities to generate an RFC2822 format message to send to the SMTP server, the RFC2822 text is generated on the fly as the data is sent to the SMTP server. If the SMTP server accepts the message to be sent then the Server MTM moves the message to the sent folder and sets its sending state to sent. If the SMTP server rejects the message then the Server MTM leaves the message in the outbox and sets the sending state to failed. Separate emails are generated for BCC recipients to ensure that the SMTP server doesn’t incorrectly include BCC recipients in emails sent to addresses in the To and CC fields of the email.
+3.2.9.3.7 Autosend
+The Autosend component is an executable that is kicked off by the POP3 and IMAP4 Client MTMs if the send on next connection setting is set. This executable will just make a request to the SMTP Server MTM to send messages associated with the SMTP service related to the POP3 or IMAP4 service, wait for the operation to finish and then exit.
+3.2.10 Messaging / MMS APIs
+The MMS module has been removed from v9.0 and onwards.
+3.2.10.1 Key Internal Relationships and Dependencies
+
+Figure 21 MMS Internal Dependencies
+3.2.10.2 API Purpose - Further Elaboration
+3.2.10.2.1 MMS Overview
+The MMS MTM provides functionality for creating, accessing, sending and receiving MMS messages. Messages are sent and received without the client application needing to open or close any kind of session. The management of the MMS session is handled entirely within the MTM.
+MMS clients are alerted when a new message is available for download via the WAP Push mechanism. A WAP push watcher is provided to handle these notifications. After the notification the message can be downloaded over WSP or HTTP. Messages are sent by posting the data over WSP or HTTP. The Symbian MMS implementation can handle sending or receiving MMS message over either protocol.
+MMS messages are based on the MIME format but are binary encoded using WSP. Note that MMS messages are encoded in this way even if they are posted over HTTP as opposed to WSP. The codec component is responsible for this encoding and decoding.
+3.2.10.2.2 MMS Utilities
+3.2.10.2.2.1 Key External Relationships and Dependencies
+
+Figure 22 MMS Utilities External Dependencies
+The MMS utilities provide the message and settings encapsulation classes. The MMS settings and messages are stored in the message store, the MMS utilities provide the interfaces to access this data.
+3.2.10.2.2.2 Settings
+The settings functionality provided by the MMS utilities allows the messaging client to persist MMS settings in the message store. Supported settings include:
+ MMSC (MMS server) address
+ WSP or HTTP transport
+ Autofetch messages on notification
+ Preferred IAP for the MMS network connection
+The settings functionality is also used by the server MTM to retrieve the settings prior to message sending or fetching.
+3.2.10.2.2.3 Message Encapsulation
+The message classes provide the message access functionality. Messages can be created, stored, restored and read using these classes. Functionality includes:
+ Adding media objects to the message
+ Enumerating through media objects
+ Adding recipients, subject line, etc. to a message
+ Adding other headers to the message, e.g. expiry date
+ Finding the appropriate media object for a given URI in the SMIL part (URI resolving)
+The message data is stored in the message store using one entry per message regardless of the number of media objects added to the message. This is preferable to using multiple message entries as it is faster and uses less disk space.
+Most of the message access code is common whether it is being used on the client or server side, however some parts of it are specific. For this reason it is essential that the appropriate client or server side CMmsMessage derived class is used.
+3.2.10.2.3 MMS Watcher
+3.2.10.2.3.1 Key External Relationships and Dependencies
+
+Figure 23 MMS Watcher External Dependencies
+
+The MMS watcher plug-in is responsible for intercepting incoming MMS notifications and delivery reports then taking the appropriate action. It is implemented as a WAP Push watcher plug-in.
+When an MMS notification is received an MMS entry is created in the inbox using the MMS utilities. At this point the entry has its incomplete flag set. If the settings have the autofetch option selected then the MMS watcher initiates the fetch operation via the MMS client MTM.
+If a delivery report is received then the delivered flag is set on the appropriate sent message. If an outgoing message was sent to several recipients then there will be several delivered flags. A delivery report from each recipient will set the appropriate delivered flag.
+3.2.10.2.4 MMS Client MTM
+3.2.10.2.4.1 Key External Relationships and Dependencies
+
+Figure 24 MMS Client MTM Dependencies
+As with most other MTMs the MMS client MTM provides access to the server MTM functionality for messaging clients. It also implements the Send-As interface and reply and forward functionality.
+3.2.10.2.4.2 Send-As Implementation
+The Client MTM Send-As interface is implemented in the MMS Client MTM. The implementation differs slightly from other MTMs because additional presentation content may be generated depending on the media objects that are added. When simple combinations of images, sounds and text are added a SMIL presentation is generated to link them together. This is preferable to simple adding the objects as attachments where some clients render them as a list of files and others fail to render them at all.
+The SMIL data is constructed using templates stored in resource files, the GMXML (SMIL) composer is not used.
+3.2.10.2.4.3 Reply / Forward
+The Client MTM can be used to create replies to received messages or to create forwarded responses. The reply and forwarding operations are performed asynchronously.
+3.2.10.2.5 MMS Server MTM
+3.2.10.2.5.1 Key External Relationships and Dependencies
+
+Figure 25 MMS Server MTM Dependencies
+The Server MTM is the most complicated part the MMS implementation. It handles all of the state information required to send or fetch MMS messages. It is also responsible for managing the HTTP or WSP session and the connections to the phone network.
+3.2.10.2.5.2 Operations
+All MMS server MTM functionality is encapsulated in operations. An operation consists of the setup of a session, the sending, fetching and acknowledgements when appropriate, it then closes the session. The messaging client initiates an operation with a single call to the Client MTM, there is no need for the messaging client to explicitly establish the session or to know about the internal states. However, these internal states are available to the messaging client via the progress structure if this level of user feedback is required.
+Two types of operation are supported, background and foreground:
+A maximum of one foreground operation can be running at any one time. The messaging client can poll the server MTM for the progress of a running foreground operation, likewise it can cancel it if necessary.
+A background operation does not support progress information and can not be cancelled by the messaging client. It is possible to initiate background operations even if other background or foreground operations are pending. However, background operations are queued and a maximum of one will actually be running at any one time.
+The MMS watcher uses a background operation to perform automatic fetching. While the background autofetch is occurring it is still possible to start a foreground operation (such as sending a message) if required.
+3.2.10.2.5.3 Session and Connection Management
+The server MTM uses the HTTP Transport Framework to enable the HTTP or WSP session. HTTP or WSP can be selected at runtime by selecting the appropriate option in the settings. The server MTM is responsible for reading any HTTP proxy details from the CommDB and passing it to the HTTP framework. See the http transport framework architectural description for more information on recognisers [R5]
+The server MTM is also responsible for managing the connection to the phone network. Connections are opened when required using the RConnection mechanism, multi-homing is supported provided that the underlying HTTP framework transport plug-in also supports it.
+3.2.10.2.6 MMS Codec
+The MMS Server MTM is in charge of the state transitions, connection, session, the actual posting and fetching of the data from them, however it does not encode or decode the MMS PDUs. The encoding and decoding is performed by the MMS Codec.
+For decoding the Server MTM passes the Codec the MMS PDU data in a descriptor for processing. If the PDU contains a received MMS message then the message entry is updated with the decoded MMS data.
+For encoding the Server MTM passes a reference to the message store entry containing the un-encoded MMS data. The Codec then encodes it and returns the PDU to the Server MTM in a descriptor.
+
+
+3.2.11 Messaging / BIO APIs
+3.2.11.1 Key Internal Relationships and Dependencies
+
+Figure 26 BIO Message Internal Dependencies
+3.2.11.1.1.1 Key External Relationships and Dependencies
+
+Figure 27 Bio Parser External Dependencies
+
+3.2.11.2 API Purpose - Further Elaboration
+3.2.11.2.1 BIO Overview
+The BIO messaging components have been designed to unify and simplify the way in which system messages are processed. In this context ‘system messages’ refers to messages received on the device which are intended to update some attribute(s) on the system as opposed to being presented to the user. Examples of these types of messages include vCards which are parsed and then displayed to the user and when accepted modify the users contact database and OTA configuration messages which are again parsed before display to the user and if accepted create email accounts or internet access points.
+The BIO messaging components can be broken down into three groups:
+1) The BIO MTM - To initiate the parsing and processing of BIO messages
+2) The BIO Database - Maps port numbers, MIME types, etc. to bio types in order to identify the type of incoming BIO messages.
+3) The BIO Parsers - To parse and process the BIO message payload
+BIO messages are not receive by the bio messaging framework, they come over other message transports for example see section 3.2.6.3.1 on the SMS watchers which describes how the SMS watchers receive bio messages and use the bio framework to tag the messages with the correct bio id.
+3.2.11.2.2 BIO MTM
+The BIO client MTM is called by the messaging client to parse or process a BIO message that has been saved in the message store. It is the responsibility of a BIO watcher to save the BIO message with the BIO flag and the appropriate BIO type set.
+The BIO client MTM does very little, its primary task is to pass on the messaging client request to the server MTM. Two operations are supported, parse and process.
+The messaging client is expected to initiate the parsing of the BIO message before processing it. The parsing step involves analysing the data and storing it in a form that can be displayed to the user via the BIO message viewer.
+Once the message has been parsed the messaging client can initiate the processing of the message.
+The BIO server MTM is responsible for deferring the parsing and processing to the appropriate BIO parser. The behaviour for the parsing and processing steps varies between parsers. See the BIO Parsers section for more information.
+The bio MTM does not support sending messages and therefore does not support reply / forwarding messages. For bio messages sending / reply etc. is supported by the particular MTM that the message is sent over, for example SMS.
+3.2.11.2.3 BIO Database
+The BIO database is used to identify the type of BIO messages. It maps message attributes such as port number, MIME type or leading string to a BIO type. These are attributes are then used by clients of the bio framework to know what ports to listen for messages on. For example the SMS watchers use the leading string to wait for SMS messages that start with that string and when storing those messages in the inbox tag them with the bio id associated with that leading string. See the SMS watcher section 3.2.6.3.1 for more examples of how the BIO database can be used.
+3.2.11.2.4 BIO Parsers
+The BIO parsers are plug-ins for parsing and processing incoming BIO messages. They are invoked by the BIO Server MTM depending on the BIO type of the message being processed. Each BIO parser implements two functions, ParseL and ProcessL. The level of functionality varies between parsers. Some parsers update the final repository with the received data, e.g. WAPP updates the CommDB with the received settings. Some parsers simply save the data in an unparsed state for processing by another component, this secondary parsing is not part of the BIO framework and must be initiated by the messaging client. An example is when GFP saves vCard data as a file as opposed to updating the contacts database, the UI must then invoke the Versit parser to parse the vCard and commit it to the contacts database.
+3.2.11.2.4.1 Generic File Parser (GFP)
+The generic file parser can be used to identify and save a variety of BIO data types, e.g. vCards and vCals. The Generic File Parser does not process the data, it simply saves it in the message store for processing by another component. The file is saved as an attachment of the message entry that was parsed.
+3.2.11.2.4.2 Nokia/Ericsson OTA Parser (WAPP)
+The WAPP parser decodes Nokia/Ericsson OTA messages and updates CommDB to reflect the received settings.
+3.2.11.2.4.3 Nokia Smart Message Internet Access Parser (IACP)
+The IACP parser decodes Nokia Smart Messages and updates the CommDB and messaging settings where appropriate.
+3.2.11.2.5 BIF Files and Utilities
+The BIF files encapsulate the information required for identifying BIO messages, these details may include the expected port number, MIME type or leading string. Different BIO watcher will use different information from these files, for an example see the 3.2.6.3.1. The information can be retrieved from the BIF files by using the BIF utilities. Generally BIO aware clients will access this information via the BIO database. BIF files are resource files previous to the v6.1 release they were binary files generated by biftool.exe.
+3.2.11.2.6 Platform Security Compliant Messaging / BIO APIs
+In the platform security model the BIO parsers are run in the client space rather than in the message server space, as is done in the non-platform secure model. If the BIO parsers are run in the message server space, it allows a client process to gain the capabilities of the message server. IPC policing can protect the message server from this.
+Also, for the message server to be able to load any BIO parser it would need more capabilities than it really requires. By running the BIO parsers in the client space, both these issues are solved. The client process must be trusted with the necessary capabilities to run the specified BIO parser.
+The BIO registry files are located in the \resource\messaging\bif read-only directory. All BIO parser DLLs are located in the \sys\bin protected directory.
+
+Figure 26 BIO Message Dependencies (v9.0)
+The BIO client MTM is responsible for loading the BIO database and BIO utilities to handle parse/process requests from clients.
+The BIO registry files no longer identify the BIO parsers DLLs via their UID – the registry file must use the BIO parser DLL name to identify them.
+3.2.12 Messaging / OBEX MTM APIs
+3.2.12.1 Key Internal Relationships and Dependencies
+
+Figure 28 OBEX Internal Dependencies
+3.2.12.2 OBEX MTM Overview
+The OBEX MTM offers simple IR and Bluetooth beaming functionality. It provides an API that is consistent with other MTMs so that the underlying OBEX APIs do not need to be used directly for beaming applications. The OBEX MTM does not provide OBEX receiving functionality, in order to receive OBEX data the underlying OBEX APIs must be used directly.
+3.2.12.2.1 OBEX MTM
+The OBEX MTM is split into three parts. OBEX MTM DLLs, IR MTM DLLs and Bluetooth MTM DLLs. The OBEX MTM DLLs can not be used on their own they provide the base OBEX MTM functionality for the derived IR and Bluetooth MTMs.
+There are two APIs that can be used to create OBEX messages:
+1) The Send-As API
+2) Linked attachments by filename
+The Send-As API provides an interface consistent with other MTMs, however it requires all attachments to be copied into the message store before they can be sent, this is often undesirable for beaming applications because it is wastes disk space. For this reason a second API is provided that allows attachments to be linked to outgoing messages by filename, when this API is used there is no need to copy the attachments to the message store.
+Unlike many other MTMs after OBEX tries to send a message it is deleted from the outbox whether the sending succeeds or fails.
+3.2.12.2.1.1 OBEX MTM Key External Dependencies
+
+Figure 29 OBEX External Dependencies
+3.2.12.2.2 IR MTM
+The bulk of the OBEX MTM functionality is provided by the OBEX MTM DLLs, the IR MTM itself just sets up the parameters.
+3.2.12.2.2.1 IR MTM Key External Dependencies
+
+Figure 30 IR MTM Dependencies
+3.2.12.2.3 Bluetooth MTM
+The bulk of the OBEX MTM functionality is provided by the OBEX MTM DLLs, the Bluetooth MTM just subclasses from the OBEX MTM and sets up Bluetooth specific parameters.
+3.2.12.2.3.1 Bluetooth MTM Key External Dependencies
+
+Figure 31 Bluetooth MTM Dependencies
+3.2.12.2.4 OBEX MTM Utils
+The OBEX MTM Utils provide utility functionality used by the other OBEX MTM DLLs. The two main areas of functionality provided by this component are:
+1) Filename linking functionality
+2) Bluetooth SDP lookup
+The filename linking functionality is provided in the utilities because linked files must be added by the client side during message creation and need to be read on the server side during sending.
+
+3.2.12.2.5 Platform Security Compliant Messaging / OBEX MTM APIs
+From v9.0 and onwards the service settings of all the derived OBEX MTMs are stored in the Central Repository. The OBEX message is stored in the message store as an attachment – from v9.0 and onwards the Attachment API is used to attach the OBEX message.
+
+3.2.13 Messaging / GMXML APIs
+3.2.13.1 Key Relationships and Dependencies
+
+Figure 32 GMXML Dependencies
+3.2.13.2 Overview
+The GMXML component provides simple XML DOM parsing and validation functionality. It is intended for parsing XML that might be needed in messaging applications, specifically SMIL parsing for MMS rendering. It is not a general purpose XML parser and will not be suitable for some applications, e.g. browsing.
+3.2.13.2.1 GMXML DOM
+The DOM implementation is fit for purpose for SMIL rendering but differs from the standard DOM design in several respects, e.g. attributes are not stored as discrete nodes, for performance reasons they are stored with the element.
+The DOM tree classes are all derived from nodes. Implemented node types include elements, text and comments. The type of each element is stored as a descriptor as opposed to an enum. This is less efficient than storing it as an enum but provides maximum flexibility when dealing with unknown element types.
+Nodes are linked together in a tree structure as might be expected in a DOM implementation. The tree structure exists on the heap.
+3.2.13.2.2 GMXML Parser and Composer
+3.2.13.2.2.1 Parser
+The parser takes XML input from a buffer or file and creates the corresponding DOM structure on the heap.
+The parser is capable of performing some basic validation. In order to validate against a DTD a class that implements the GMXML DTD interface is required. The DTD interface specifies several functions that provide the required validation, e.g. one of the functions determines if a given attribute is valid for a given element. An instance of the DTD class should be passed into the parser when validation is required but can be omitted if no validation is needed.
+3.2.13.2.2.2 Composer
+The composer takes a DOM tree and generates XML output from it. The XML output is written to a file.
+3.2.13.2.3 GMXML SMIL DTD (Validator)
+The SMIL DTD validator class is an implementation of the DTD validator interface. It implements several simple functions that provide the information required to validate SMIL data. An instance of the SMIL DTD validator should be passed into the parser if SMIL validation is required.
+4 Security
+4.1 Data caging
+For data storage in the pre-platform security compliant architecture, refer to section [3.2.1.3.2]
+For the data caging in the platform security compliant architecture of v9.0 and onwards, refer to section [3.2.1.3.3]
+4.2 Backup and restore
+The message server registers the index file with the backup server. When informed about a backup/restore it releases the index file, sending events to messaging clients informing them that the message store is unavailable. When informed it can open the index file again, it checks the time stamp on the index file; if it has changed since the file was released it reloads the index file. If the newly restored index file is found to be corrupt it is deleted and a new message store is created. See the section on page 14 for details on how the message server handles corrupt stores. The client performing the restore should always wipe the existing message store before starting to copy the message store from the backup to the device.
+4.3 Capability ranges
+In the platform security compliant architecture of v9.0 and onwards, the capabilities allocated to messaging sub-systems are as listed in following table.
+4.3.1 Capabilities granted to executables
+The following table lists the executables and their capabilities and also gives a basic example for having the required capability.
+
+Executable Capability Rationale (basic example of capability requirement)
+msexe.exe ProtServ ProtServ is required to allow the msexe.exe to start a protected server. This stops processes without ProtServ from starting a server pretending to be the message server
+ ReadDeviceData ReadDeviceData is needed to able to read service settings
+ WriteDeviceData WriteDeviceData is needed to able to write service settings
+ NetworkServices NetworkServices capability is needed to access network transports (SMS, POP3, SMTP, IMAP4).
+ LocalServices LocalServices is needed to be able to access IR and Bluetooth
+ ReadUserData ReadUserData is needed to be able to read user data (e.g. service settings).
+watcher.exe ReadDeviceData ReadDeviceData is needed to able to read service settings
+ WriteDeviceData WriteDeviceData is needed to able to write service settings
+ NetworkServices NetworkServices capability is needed to access network transports (SMS).
+ LocalServices LocalServices capability is needed for the plug-ins to access IR and Bluetooth
+ ReadUserData ReadUserData is needed to be able to read user data
+ WriteUserData WriteUserData is needed to be able to write user data
+autosend.exe ReadUserData ReadUserData capability is needed to be able to read data from Outbox and SMTP server MTM.
+ WriteUserData WriteUserData capability is needed to be able to write data in Outbox and SMTP server MTM.
+ NetworkServices NetworkServices capability is needed to access network transports (SMS, POP3, SMTP, and IMAP4).
+ LocalServices LocalServices capability is needed to access the IR and Bluetooth
+SchSend.exe ReadDeviceData ReadDeviceData is needed to able to read settings data
+ NetworkServices NetworkServices capability is needed to access the network transports (SMS, POP3, SMTP, and IMAP4).
+ LocalServices LocalServices is needed to be trusted by other MTM
+ ReadUserData ReadUserData is needed to be able to read user data.
+ WriteUserData WriteUserData is needed to be able to write user data.
+SendAs.exe ReadDeviceData ReadUserData is needed to be able to read data in Outbox.
+ WriteDeviceData WriteUserData is needed to be able to write data in Outbox.
+ NetworkServices NetworkServices capability is needed to access the network transports (SMS, POP3, SMTP, and IMAP4).
+ LocalServices LocalServices is needed to be able to access IR and Bluetooth
+
+4.3.2 Capabilities granted to DLLs
+The assigned Platform Security attributes for DLLs within messaging are outlined in the following table.
+DLL Capability
+bifu.dll All –TCB
+bioc.dll All –TCB
+biodb.dll All –TCB
+bios.dll All –TCB
+biowatcher.dll same as watcher.exe
+biut.dll All –TCB
+cbcp.dll All –TCB
+enp.dll All –TCB
+gfp.dll All –TCB
+iacp.dll All –TCB
+nbswatcher.dll same as watcher.exe
+cdmanbswatcher.dll same as watcher.exe
+CdmaSocketWatcher.dll same as watcher.exe
+VMNWatcher.dll same as watcher.exe
+WEMTWatcher.dll same as watcher.exe
+WMTWatcher.dll same as watcher.exe
+WPTWatcher.dll same as watcher.exe
+wapp.dll All –TCB
+wapwatcher.dll same as watcher.exe
+smildtd.dll All –TCB
+xmldom.dll All –TCB
+xmlparser.dll All –TCB
+smiltranslator.dll All –TCB
+imcm.dll All –TCB
+imps.dll same as msexe.exe
+imut.dll All –TCB
+msgs.dll All –TCB
+msgurlrec.mdl same as AppArc.exe (once it exists; eiksrv in meantime)
+mtur.dll All –TCB
+pops.dll same as msexe.exe
+schsend.dll All –TCB
+send.dll All –TCB
+smcm.dll All –TCB
+smcm_gsm.dll Synonym for smcm.dll
+smcm_cdma.dll Synonym for smcm.dll
+smss.dll same as msexe.exe
+smss_gsm.dll Synonym for smss.dll
+smss_cdma.dll Synonym for smss.dll
+smts.dll same as msexe.exe
+btcmtm.dll All –TCB
+btsmtm.dll same as msexe.exe
+irc.dll All –TCB
+irs.dll same as msexe.exe
+obexclientmtm.dll All –TCB
+obexmtmutil.dll All –TCB
+obexservermtm.dll same as msexe.exe
+
+The reason for setting a high capability to the DLLs is to make it possible for almost anyone to link to them. Although a DLL may have capabilities ALL-TCB (All minus TCB), its real capability is limited by the process which loads the DLL.
+4.3.3 Capabilities required to use the subsystem
+The message subsystem needs to be protected against malicious clients. The following table shows the key capabilities required to do related activities in different components.
+
+Component Related Activity Required Capability and SID
+Message server Create message in local folder No capability required
+ Create message in Outbox ReadUserData, WriteUserData and MTM specific capabilities
+ Access client MTM ReadUserData, WriteUserData and MTM specific capabilities
+Watcher Allow plug-ins to wait on events (e.g. arrival of SMS) Watcher always polices if the client capabilities are trusted by the watcher framework, else it will not be loaded
+Plug-ins or clients using watcher need the same capabilities as watcher.exe to be able to be loaded by watcher.
+Autosend Send messages in background NetworkService or LocalService required by the message type
+SchSend Scheduling of operations (e.g. sending SMS) SchSend always polices to see if the process was started by the Task Scheduler – if not the process terminates without performing any of the scheduled tasks. Also, the SchSend verifies that only itself and the message server created the scheduled tasks. If this is not the case, SchSend does not performing the scheduled tasks.
+SendAs Create message Draft, move it to Outbox, and send message WriteDeviceData or WriteUserData and other capability required by the message type
+
+5 Further Information
+5.1 References
+No. Document Reference Version Description
+R1 messaging_functional_specification.doc 0.6 Messaging Functional description
+R2 SGL.GT0143.161_App-Framework_Architectural_Description.doc 1.0 App-Framework Architectural Description
+R3 NBProtocols_Subsystem_Architectural_Description.doc 0.2 NBProtocols Architectural Description
+R4 WAP-stack_architectural_analysis.doc 1.0 WAP stack architectural analysis
+R5 HTTP Transport Framework Architectural Description.doc 1.1 HTTP Transport Framework 1.1 Architectural Description
+5.2 Open Issues
+The following issues need to be resolved before this document is completed:
+1. Top-level architecture diagram showing the framework and plug-ins should be added to overview section.
+2. Message store section should talk about removable media.
+3. Define "Message Server Client API" and "Messaging Client API" in the glossary, and ensure it is consistently used in the diagrams
+4. Add a sequence diagram for receiving a vCard over SMS and integrating it into contacts
+5. Add a sequence diagram for sending an SMS
+6. Add a sequence diagram for synchronising a POP3 mail box
+7. Add a sequence diagram for connecting to an IMAP4 mail box and downloading a message
+8. Capability table should be updated after the implementation of server e.g. message server
+9. Sequence diagram may need to be changed to show secured platform operation
+10. In section [3.1.1.4] the server SendAsV2 to find a correct name
+11. Section 3.2.1.3.3.1 Data Caging file 'Mtm Registry v2'may need a correct name
+12. Breakdown diagram showing all DLL, exes, apps in the messaging subsystem for both the pre-v8.0 and post v9.0 in section[3.2]
+13. Needs to say more about how the capabilities are policed and the algorithms used for different operations
+14. The dependecy between the message server and the central repository need to be listed in the email, SMS and OBEX diagrams (e.g. message store)
+15. Section 3.2.1.2 - figure 3 - Central Repository also get used by the Message server, or server MTMs (e.g. POP3), to retrieve account settings the path, required DLL and description are not given
+16. Section 4.3.3 title can be Police requirement of the sub-system, add extra column for SID in the table and list the use of SID. For example SchSend checks for Task Scheduler SID
+
+
+5.3 Glossary
+The following technical terms and abbreviations are used within this document.
+Term Definition
+BIO
+Bearer Independent Object Smart messages e.g. vCards, vCals, and WAP provisioning messages. These can currently be received via the WAP stack, SMS stack, Bluetooth or Infrared.
+BIO Type UID that represents the content type of a BIO Message.
+Message Centre Application that displays list views of messages to the user, allowing the user to perform operations such as copying messages, sending messages creating new messages etc.
+Message Viewer Application for viewing a message.
+Message Editor Application for creating or editing a message
+Message Server Symbian OS Server that handles request to modify the Message Store
+Message Store Store of messages and related information kept in the file system on a Symbian OS device.
+Local Entry An Entry in the Message Store that descends from the local service, the entries on the right hand side of Figure 6
+Remote Entry An Entry in the Message Store that descends from a remote service, the entries on the left hand side of Figure 6
+Global Inbox A standard folder under the local service which is used to store incoming messages like SMS MMS etc. as opposed to an IMAP4 Inbox which would be under an IMAP4 service and is a representation of the Inbox on an IMAP4 email server.
+Central Repository centralised and secure storage facility for application settings
+OBEX Object exchange protocol, used to send objects such as vCards or files between devices via infrared or Bluetooth.
+GMXML XML parser / generator for use with SMIL formatted messages.
+UID Unique Identifier, a 32 bit number allocated from a registry owned by Symbian
+IPC Inter Process Communication
+MTM Message Type Module is a plug-in to the message server providing support for a given message type for example IMAP4 or SMS. Each MTM is split into 4 interfaces: Client MTM, Server MTM, UI MTM and UI Data MTM. See section 3.2.1.3.5 for more detail.
+MTM Registry A list of currently installed MTMs maintained by the message server.
+TLS Transport Layer Security, provides encryption of a TCP/IP socket.
+M-HTML Standard for including HTML in MIME email messages see http://www.ietf.org/rfc/rfc2557.txt
+MIME Specification for the format of email message bodies see http://www.ietf.org/rfc/rfc1341.txt
+RFC2822 The standard format for internet mail messages see http://www.ietf.org/rfc/rfc0822.txt
+SMTP Simple Mail Transport Protocol
+SID Secure Identification
+IMAP4 Internet Mail Access Protocol
+POP3 Post Office Protocol Version 3
+NBS Narrow Band Socket, in the messaging context this refers to the socket that is used to talk to the SMS stack for receiving and sending SMS messages
+SMS Short Message Service
+MMS Multimedia Message Service
+WAP Wireless Application Protocol
+WSP WAP Session Protocol
+HTTP Hypertext transfer protocol
+PDU Protocol Data Unit. This is the encoded form of SMS and MMS messages.
+Versit A consortium that defined standard formats for things like contacts (vCard) and calendar entries (vCals)
+SDP Service Discovery Protocol. A Bluetooth protocol that allows an applications to discover which services are available and to determine the characteristics of the services.
+SMIL Synchronized Multimedia Integration Language. Presentation language that is commonly used to define the contents of an MMS message.
+XML Extensible Mark-up Language
+DOM Document Object Model
+DTD Document Type Definition, a schema that defines the structure of an XML document.
+ESTORE Symbian OS component that provides stream based storage. Messaging uses the Permanent file store provided by ESTORE to store its index entries.
+Appendix A - Example Sequence Diagrams
+A.1 Copy to a Remote Service
+
+Figure 33 Sequence Diagram Showing Copying to a Remote Service
+Figure 33 shows a client copying a message to a remote service using the Messaging Client API. The message server then delegates the copy to the SMTP Server MTM. The Server MTM interprets the request as a request to send the message so it opens a connection to a remote SMTP server and sends the message. While the message is being sent the client can retrieve progress information from the CMsvOperation object that was returned by CMsvEntry::CopyL. The dark grey IPC line represents the split between the objects running in the client’s process space on the left and the message server’s process on the right.
+There are four basic steps:
+1. The client opens session with Message Server and creates a CMsvEntry set on the global outbox,
+2. The client then requests an asynchronous copy from the outbox to the SMTP service, a CMsvOperation object is returned. The message server loads the SMTP Server MTM and delegates the copy operation to it.
+3. The client requests progress from the CMsvOperation object, this request is passed through to the SMTP Server MTM. The client may repeat this step multiple times.
+4. The Server MTM finishes sending message. It moves the message to sent folder and completes the message server’s request. The message server completes the CMsvOperation object, which requests the final progress from the message server. The server returns the final progress and deletes the Server MTM. The CMsvOperation then completes the client’s original request.
+This diagram hides all of the internal working of the SMTP Server MTM, for information on this see below.
+A.2 SMTP Session
+
+Figure 34 Sequence Diagram Showing a SMTP Session
+Figure 34 shows the operation of the SMTP Server MTM after a request has come from the message server to copy a message to the SMTP service.
+1. SMTP Server MTM gets the request from the message server, it will build a selection of messages consisting of the union of the selection of messages passed in and the messages in the outbox that are associated with this SMTP service and are ready to be sent. The chain of classes are constructed, and a request is passed to networking to connect to the remote SMTP server, details of the server name and port are retrieved from the settings stored in the SMTP service entry.
+2. The component waits for the SMTP server to respond with a greeting indicating it is willing to talk, then sends EHLO to the server and waits for the response detailing the capabilities of the Server. After this step there could set steps to start using TLS and or SMTP AUTH depending on the SMTP settings.
+3. CImSmtpSession calls back into CMsgOutboxSend to retrieve the next message to be sent, then constructs a CImSmtpFile object to handle sending, for details on the sending see SMTP Email Send. When sending the email has completed the CImSmtpFile object is deleted.
+4. CImSmtpSession calls back into CMsgOutboxSend to retrieve the next message which returns saying there are no more messages. CImSmtpSession sends QUIT to the SMTP server and completes CMsgOutboxSend. CMsgOutboxSend deletes CImSmtpSession which tears down the connection to the SMTP server; it then completes the SMTP Server MTM. The Server MTM will then complete the message server and be deleted.
+A.3 SMTP Email Send
+
+Figure 35 Sequence Diagram Showing SMTP Transactions during Email Send.
+Figure 35 shows a CImSmtpFile object sending an email message to an SMTP server.
+1. Construct a CImSendMessage object, part of the imut component. Reset the SMTP Server
+2. Read address information from the CImHeader object stored in the message store, send address information to SMTP server.
+3. Use CImSendMessage object to read the message from the message store and generate RFC2822 message line by line. Send each line to the server as it is generated.
+4. Complete and send the message by sending a full stop to the SMTP server
+
+