<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-BAD138D5-2914-5C6E-9FA4-F7A3CCB85E6D" xml:lang="en"><title>MTM

Capabilities</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>This section provides guidelines to the MTM implementors for assigning

the capability set for different types of MTMs. </p>

<section id="GUID-4E471C88-ECAD-4146-8B68-F0AA19F9D726"><title>Description</title> <p>MTMs are implemented as DLLs. According

to the Symbian platform security model a DLL can be loaded by a process only

if the DLL has a capability set equal to or greater than the capability set

of the process loading it. </p> <p>The characteristics of a plug-in module

are described by its set of capabilities. The standard capabilities are characteristics,

such as the maximum message body size, the maximum total size of a message,

the character widths supported by a message type, presence or absence of support

for attachments, presence or absence of support for the subject field, folders

and so on. Capabilities are referenced by unique identifiers, which are managed

by Symbian. </p> <p>The capability set is defined in the MMP files of the

MTMs. The following sections list the capability set required by the Symbian

platform for each type of MTM. </p> </section>

<section id="GUID-73371E92-1175-45D5-827B-B83FEE2EA4D6"><title>Server MTM</title> <p>A Server MTM is always loaded by the

Messaging Server. It is therefore necessary for the Server MTMs to have the

following capability set assigned. </p> <p> <codeph>ReadDeviceData WriteDeviceData

ProtServ NetworkControl           NetworkServices LocalServices ReadUserData

WriteUserData</codeph>  </p> </section>

<section id="GUID-61FBEBAA-B470-455F-9FC9-7D78225A1337"><title>Client MTMs, UI MTMs and UI Data MTMs</title> <p>These MTMs

are used by modules both within and outside of the Messaging Framework. If

a Client MTM is to provide all the supported Messaging functionality it must

have at least the minimum capabilities listed below. </p> <p> <codeph>ReadDeviceData

WriteDeviceData NetworkServices LocalServices           ReadUserData WriteUserData</codeph>  </p> <p>If

a Client MTM does not need to provide the complete set of Messaging functionality

then a subset of the capabilities mentioned above may be selected. For example,

if a Client MTM communicates over a local connection, such as IR or Bluetooth,

it needs the <codeph>LocalServices</codeph> capability only and does not need

the <codeph>NetworkServices</codeph> capability. Refer to the Platform Security

Engineering Guide to understand the requirements for each capability recommended

above. </p> <p>Authors of Client MTMs that are loaded by the standard Messaging

applications must give their MTMs the capabilities that those applications

have, that is, the capabilities of Client MTMs are determined by the processes

that load them. </p> <p>The capabilities that need to be selected for applications

that use Client MTMs depends on the functionality that those applications

provide. If the Client MTM does not have those capabilities, the application

will not be able to load the MTM. It is up to the creator of the MTM to make

sure that it is assigned enough capabilities to be loaded into applications

that require that MTM. </p> </section>

<section id="GUID-ED8C15BD-A2C9-564B-8339-36C6C9C508D1"><title>Security capability

specification</title> <p>With the introduction of platform security, individual

MTMs are required to specify the additional security capabilities that Messaging

client applications require in order to send messages by that MTM. These capabilities

must be set in the <xref href="GUID-92D6CC11-C597-5D00-AAE5-866289B7462F.dita">MTM

resource file</xref> that describes the MTM's properties. </p> <p>This is

done using the resource structure <codeph>MTM_SECURITY_CAPABILITY_SET</codeph>.

This has a single array member capabilities that specifies the required capabilities:

each value must be a capability as defined in <codeph>TCapability</codeph>.

For example, this resource specifies that the client must have the local services

(for example, Bluetooth) capability: </p> <codeblock id="GUID-B19B4A70-BB61-5492-98DA-CE8E44D1AF8E" xml:space="preserve">

RESOURCE MTM_SECURITY_CAPABILITY_SET 

    {

    capabilities = { ECapabilityLocalServices }; 

    }</codeblock> <p>An <codeph>MTM_SECURITY_CAPABILITY_SET</codeph> must

be the third resource in the resource file (following the <codeph>MTM_INFO_FILE</codeph> and <codeph>MTM_CAPABILITIES</codeph> resources),

even if the MTM requires no additional capabilities to be defined. </p> <p> <codeph>MTM_CAPABILITIES</codeph> has

nothing to do with platform security, but specifies flags used by <codeph>SendAs</codeph>.

If the MTM can support <codeph>SendAs</codeph>, it should define the resource

as: </p> <codeblock id="GUID-CC28EEDB-2CD0-57BB-A66E-FA1B73C1D596" xml:space="preserve">

RESOURCE MTM_CAPABILITIES 

    {

    send_capability=1; 

    body_capability=1; 

    }</codeblock> <p>If the MTM does not support SendAs, use the following: </p> <codeblock id="GUID-BD133C80-D048-5E49-BBB2-66BD6D6A80D2" xml:space="preserve">

RESOURCE MTM_CAPABILITIES 

    {

    }</codeblock> </section>

<section id="GUID-19478D49-AFD6-4130-9B4D-6C531A36D9C4"><title>Specifying the capability set</title> <p>Developers are advised

that keywords such as <codeph>ReadDeviceData</codeph> are case sensitive,

and care should be taken when specifying them in the MMP file. For example

a server side MTM will have the capability set defined in the MMP file as

follows: </p> <p> <codeph>CAPABILITY ReadDeviceData WriteDeviceData ProtServ

NetworkControl           NetworkServices LocalServices ReadUserData WriteUserData </codeph>  </p> </section>

<section id="GUID-D9D4A690-CB0D-4855-A4AE-E5BC46801DA8"><title>Example</title> <codeblock id="GUID-DEF8AF54-2EA9-541F-A8D5-10C7C4690D1F" xml:space="preserve">// TXUT.MMP

//

// Copyright © 2000 Symbian Ltd.  All rights reserved.

target          TXUT.dll

targettype      dll

uid      0x1000008d 0x10003C75

VENDORID 0x70000001

CAPABILITY   ReadDeviceData WriteDeviceData ProtServ NetworkControl NetworkServices LocalServices ReadUserData WriteUserData LocalServices ReaduserData WriteUserData

source          txut.cpp txutdll.cpp

userinclude     .

systeminclude   \Epoc32\include

library         euser.lib estor.lib msgs.lib efsrv.lib 

library         centralrepository.lib  

// v2 def files

#if defined(WINS)

    deffile .\txutWINS.def

#else

    deffile .\txutEABI.def    

#endif

nostrictdef</codeblock> </section>