--------------------------------------------------------------------------------
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 at 
http://www.forum.nokia.com/main/1%2C%2C90%2C00.html?surveyId=7c838053-2474-4359-979b-591d56738601/S60_3rd_Edition_Creating_Custom_Message_Type_Modules_v1_2_en.zip
