--------------------------------------------------------------------------------

S60 3rd Edition: TextMTM Example v1.1

--------------------------------------------------------------------------------

 

This C++ code example demonstrates the key functionality of the

Messaging subsystem by implementing and using its own messaging protocol with the

Symbian Message Type Module (MTM) for S60 3rd Edition and later releases. The

target audience is e-mail developers implementing their own e-mail protocol

(for example, Push e-mail service), where  preinstalled S60 platform e-mail MTMs

(POP3, IMAP4) cannot be used.

 

The package demonstrates how to:

 

- develop and install an MTM

- create an account (mailbox) which is shown in the messaging application

- create a simple viewer/editor (implemented as a server application) for

  creating and sending messages

- provide support for sending from other applications

- receive notifications of new messages

- use the drafts and sent folder

 

Message sending and receiving are echoed locally.

 

Note that Symbian platform security imposes heavy capability requirements for

MTMs (up to ALL -TCB capabilities in S60 3rd Edition and S60 3rd Edition,

Feature Pack 1) For further details, see capability requirements section.

 

 

PREREQUISITES

--------------------------------------------------------------------------------

 

- Advanced Symbian OS

- Asynchronous services

- Client/Server architecture

 

 

IMPORTANT FILES/CLASSES

--------------------------------------------------------------------------------

 

MTM implementation project directories:

 

Client

    client MTM implementation

UI

    UI MTM implementation

UIData

    UI data MTM implementation

Server

    Server MTM implementation

Install

    Installer, registers MTMs

Deinstaller

    Uninstaller, deregisters MTMs

Viewer

    Editor and Viewer implementation

Util

    Utilities

 

Important Symbian/S60 classes:

 

CBaseMtmUi, CBaseMtmUiData, CBaseMtm, CBaseServerMtm, TMsvEntry, CMsvStore,

CClientMtmRegistry, MNcnNotification, CSendUi

 

 

CAPABILITY REQUIREMENTS

--------------------------------------------------------------------------------

 

Symbian platform security imposes heavy requirements for public DLLs

in terms of platform security capabilities. This affects messaging component

(MTM) developers in the following way:

 

Public-side MTM components (Client MTM, UI MTM, and UI Data MTM):

--------------------------------------------------------------------------------

 

In S60 3rd Edition and Feature Pack 1, all public-side MTM components (Client MTM,

UI MTM, and UI Data MTM) need to have the ALL -TCB capabilities since some of the

built-in loading processes have these capabilities.  This applies similarly to

adding the MTM as a SendUI menu item available to all applications. Because of these

heavy capability requirements, any MTM implementation has to go through the Symbian

Signed process. It also has to get manufacturer approval in S60 3rd Edition and

S60 3rd Edition, FP1.

 

From S60 3rd Edition, Feature Pack 2 onwards, instead of ALL -TCB capabilities,

only the following capabilities are needed: LocalServices, ReadUserData,

WriteUserData, NetworkServices, UserEnvironment, ReadDeviceData, WriteDeviceData,

NetworkControl, and DiskAdmin (the last one is required by the MessageCentre).

 

Private-side MTM component (Server MTM):

----------------------------------------

 

The Server MTM component (Server MTM) requires capabilities equal to

the loading process - that is, the messaging server. From S60 3rd Edition

onwards (including S60 3rd Edition, FP2), the Server MTM component should have

exactly these capabilities: LocalServices, ReadUserData, WriteUserData,

NetworkServices, ProtServ, ReadDeviceData, WriteDeviceData, and NetworkControl.

 

KNOWN ISSUES

--------------------------------------------------------------------------------

 

Notifications do not work on the emulator of the S60 3rd Edition, MR SDK.

 

The example can only be installed on phone memory as TextMTMService is created

on the C:\ drive. As a result, installation is forced to C-drive.

 

Service creation:

--------------------

The TextMTM currently uses the built-in mechanism of the Messaging application

to create the service. Note that this only works on Eseries devices (because

they categorize TextMTM as one of the e-mail MTMs). On any other S60 device

the TextMTM is not a recognized MTM type which causes an error message about

service not being created.

 

To avoid this issue, it is recommended that third party MTMs implement their

own settings UI (application) where to service is created from.

 

SendUI support:

--------------

 

The TextMTM example only supports body text. Note that in S60 3rd Edition, the

Notes application gives body text only to SMS and MMS editors. All other MTMs get

file handle attachments: Notes puts the text into file and passes the attachment

handle to SendUI which then passes it to the MTM. Because TextMTM cannot handle

the attachment, the editor remains empty. From S60 3rd Edition, Feature Pack 1

onwards the Notes application checks if the MTM service supports bodytext or

attachment and selects the handle accordingly. So from S60 3rd Edition, Feature

Pack 1 onwards, the body text is successfully copied to the editor of the TextMTM

application.

 

To ensure SendUI support in various applications, the third party MTMs should be

prepared that the bodytext can be delivered to MTM as a text file attachment,

even if the MTM does not declare to support attachments.        

 

 

RUNNING THE EXAMPLE

--------------------------------------------------------------------------------

 

- Run txinstall.exe to set up the MTM. The C:\data\TextMTMService directory is

  created.

 

- Open the Messaging application and select Options -> Settings -> Create a new

  TextMTM account. Note: the settings dialog in Eseries devices

  is slightly different and there the TextMTM is seen as a new e-mail account.

 

- You should now have a new entry ("mailbox") in the main view list with a

  cubicle icon. The MTMs are ready to use.

 

- Create a new message by selecting New message -> TextMTM (or

  New message -> E-Mail -> TextMTM in Eseries devices). Type text

  to the message and select Send or Save to Drafts from the Options menu.

 

- Sent messages are copied to c:\data\TextMTMService, or in the emulator to

  epoc32\winscw\c\data\TextMtmService

 

- You can alternatively create .txt files to the c:\data\TextMTMService

  directory using, for example, the File Manager application.

 

- Use the refresh service function on the service to "receive" new messages

  (retrieved from c:\data\TextMTMService). Then you also get a notification of

  new messages.

 

- No entries are moved to Outbox since sending occurs immediately (writing to

  the file system \Epoc32\winscw\c\data\TextMTMService)

 

SendUI functionality:

 

- You can also send text notes via the TextMTM protocol in the preinstalled

  Notes application (see restrictions in the Known issues section). Choose any

  note and then Send -> TextMTM.

 

- The TextMTM does not support attachments. Because of this, you can only send

plain text in the message body.

 

 

BUILD & INSTALLATION INSTRUCTIONS

--------------------------------------------------------------------------------

 

The source code can be compiled on all S60 3rd Edition SDKs, for example for

Maintenance Release:

 

Emulator (WINSCW):

 

    cd group

    bldmake bldfiles

    abld build winscw udeb

 

Mobile device:

 

    cd group

    bldmake bldfiles

    abld build gcce urel

    cd ..\sis

    makesis -dC:\Symbian\9.1\S60_3rd_MR TextMTM_gcce_urel.pkg

 

To install and run the application on the device, the sis package must be signed

with your certificate (ALL -TCB needed):

 

    signsis TextMTM_gcce_urel.sis TextMTM_gcce_urel.sisx mycert.cer mykey.key \

    <mypass if any>

 

See www.symbiansigned.com for information about Developer Certificates and how

to obtain a Manufacturer Approved Developer Certificate.

 

 

COMPATIBILITY

--------------------------------------------------------------------------------

 

S60 3rd Edition

S60 3rd Edition, Feature Pack 1

S60 3rd Edition, Feature Pack 2

 

Tested with Nokia E50, Nokia E61, Nokia E61i, Nokia E70, Nokia E90, Nokia N71,

Nokia N73, Nokia N95 8GB, Nokia 6220 Classic, and Nokia 6290.

 

Created and tested with S60 3rd Edition Maintenance Release SDK, S60 3rd

Edition FP1 SDK, and S60 3rd Edition FP2 Beta SDK.

 

 

VERSION HISTORY

--------------------------------------------------------------------------------

 

1.1 Release (minor update)

 

- SendUI issue fixed: E-series devices fail with "Feature Not Supported" when

  trying to send a message through SendUI. Workaround was to overwrite SetSubjectL

  and SubjectL with empty implementation. See

http://wiki.forum.nokia.com/index.php/KIS000725_-_%22Send_via_E-mail%22_fails_in_

Nokia_Eseries_devices_with_a_3rd_party_MTM

- Missing body text issue fixed

- Soft key label issue fixed

- Scalability issue fixed

- Missing cursor issue fixed

- Installation forced to C-drive

- MTM Viewer hidden from application menu

- Certain stability issues fixed

 

1.0 Release (minor update)

 

MNCNNotification functionality fixed. The Drafts and Sent folders of the

Messaging application are now used.

 

0.9 Beta Release

 

Major update for S60 3rd Edition focusing on Push e-mail use case. Based on the

initial TexTMTM example created for S60 2nd Edition. Published only in Forum

Nokia PRO.

 

 

RELATED DOCUMENTATION

--------------------------------------------------------------------------------

 

S60 3rd Edition: Creating Custom Message Type Modules (in this package).

 

 

EVALUATE THIS RESOURCE

--------------------------------------------------------------------------------

 

Please spare a moment to help us improve documentation quality and recognize the

examples you find most valuable, by rating this resource.