--------------------------------------------------------------------------------
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.