<?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-E0470135-DB19-5D3C-AF95-C412CBF515B2" xml:lang="en"><title>Multimode

Messaging</title><shortdesc>The Multimode telephony API provides a number of specialised messaging

classes that are derived from <codeph>RTelSubSessionBase</codeph>. One of

the classes is responsible for SMS, another for Broadcast and another for

USSD messaging. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>The following table describes the three messaging types. </p>

<table id="GUID-E54D8AA1-BC1F-5706-B1BA-9193BB33FE0E">

<tgroup cols="5"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/><colspec colname="col3"/><colspec colname="col4"/>

<thead>

<row>

<entry>Type</entry>

<entry>Required</entry>

<entry>GSM</entry>

<entry>WCDMA</entry>

<entry>CDMA</entry>

</row>

</thead>

<tbody>

<row>

<entry><p> <xref href="GUID-E0470135-DB19-5D3C-AF95-C412CBF515B2.dita#GUID-E0470135-DB19-5D3C-AF95-C412CBF515B2/GUID-DF523227-DADA-578A-8816-3144C7125663">SMS

messaging</xref>  </p> </entry>

<entry><p>No </p> </entry>

<entry><p>Yes </p> </entry>

<entry><p>Yes </p> </entry>

<entry><p>Yes </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-E0470135-DB19-5D3C-AF95-C412CBF515B2.dita#GUID-E0470135-DB19-5D3C-AF95-C412CBF515B2/GUID-DA0E39B0-0051-50AA-9A62-C9BC9E25A7F0">Broadcast

messaging</xref>  </p> </entry>

<entry><p>No </p> </entry>

<entry><p>Yes </p> </entry>

<entry><p>Yes </p> </entry>

<entry><p>Yes </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-E0470135-DB19-5D3C-AF95-C412CBF515B2.dita#GUID-E0470135-DB19-5D3C-AF95-C412CBF515B2/GUID-35CCDB86-E5B2-5CB8-B662-50144F376221">USSD

messaging</xref>  </p> </entry>

<entry><p>No </p> </entry>

<entry><p>Yes </p> </entry>

<entry><p>Yes </p> </entry>

<entry><p>No </p> </entry>

</row>

</tbody>

</tgroup>

</table>

<section id="GUID-DF523227-DADA-578A-8816-3144C7125663"><title>SMS messaging</title> <p> <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>RMobileSmsMessaging</apiname></xref> provides access

to the Short Message Service provided by GSM, WCDMA and CDMA networks. </p> <p>In

CDMA mode, SMS has three protocol layers: Relay lowest level, Transport and

Teleservice. Relay is the lowest level while Transport and Teleservice are

application level. <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>RMobileSmsMessaging</apiname></xref> provides

an interface to the Transport layer. Usually, the Teleservice layer is implemented

in a sockets protocol module. The Teleservice layer, rather than <codeph>RMobileSmsMessaging</codeph>,

would be the interface used by applications to send SMS messages. SMS messages

are passed across the API as Packet Data Units (PDUs). </p> <p>Segmentation

and reassembly of long SMS messages over 255 bytes is not provided by the

API, and must be provided by a higher-level module such as the <filepath>smsprot.prt</filepath> protocol

module. </p> <p> <codeph>RMobileSmsMessaging</codeph> allows clients to: </p> <ul>

<li id="GUID-D1645129-9195-5CB4-9DC5-39952782B309"><p>open an SMS sub-session

using <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>RMobileSmsMessaging::Open()</apiname></xref>  </p> </li>

<li id="GUID-C5FACABA-62EA-5E54-9B89-60BFEFFC8D22"><p>retrieve capabilities

using <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>RMobileSmsMessaging::GetCaps()</apiname></xref>.

Capabilities are encapsulated in a packaged <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>RMobileSmsMessaging::TMobileSmsCapsV1</apiname></xref> object. </p> </li>

<li id="GUID-67D3CF37-546D-596C-8A8E-72D3D4DE6F8F"><p>retrieve the mode the

phone uses to handle incoming SMS messages before passing them on to TSY using <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>RMobileSmsMessaging::GetReceiveMode()</apiname></xref>. </p> </li>

<li id="GUID-A1687E1D-6105-58CD-A308-213C39682007"><p>set the mode the phone

uses to handle incoming SMS messages before passing them on to TSY using <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>RMobileSmsMessaging::SetReceiveMode()</apiname></xref>  </p> </li>

<li id="GUID-9F6EADDA-BEA0-57D0-8F3E-0330C3841217"><p>wait for the next incoming

SMS message using <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>RMobileSmsMessaging::ReceiveMessage()</apiname></xref>  </p> </li>

<li id="GUID-DDF357F7-F520-5365-B943-4A548B888864"><p>send a positive acknowledgement

for an SMS after successful decoding and storage using <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>RMobileSmsMessaging::AckSmsStored()</apiname></xref>  </p> </li>

<li id="GUID-2BDABC27-1EA1-5022-8A2B-2C94B3287136"><p>send a negative acknowledgement

for an SMS after failure in decoding and storage using <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>RMobileSmsMessaging::NackSmsStored()</apiname></xref>  </p> </li>

<li id="GUID-7C0F5FE5-AAC3-50D5-9457-87C70DD7EFD5"><p>tell the network to

resume transferring SMS to the phone, after reception has been suspended because

SMS storage is full using <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>RMobileSmsMessaging::ResumeSmsReception()</apiname></xref>  </p> </li>

<li id="GUID-DBC2E3D5-E2B6-5137-A34C-C5B5822F824C"><p>get the bearer type

which is CSD or packet-switched for sending SMS messages using <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>RMobileSmsMessaging::SetMoSmsBearer()</apiname></xref>  </p> </li>

<li id="GUID-56C1FD58-8DF7-5DE2-A0E2-5A9123F77384"><p>set the bearer type

using <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>RMobileSmsMessaging::SetMoSmsBearer()</apiname></xref>  </p> </li>

<li id="GUID-ADE3F254-0E6D-5AE9-A3A9-6F70BA5B0CD4"><p>be notified if the bearer

type changes using <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>RMobileSmsMessaging::NotifyMoSmsBearerChange()</apiname></xref>  </p> </li>

<li id="GUID-D1968BB6-CFBB-58C3-A935-BAE5C8B37F4D"><p>send an SMS message

to the network using <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>RMobileSmsMessaging::SendMessage()</apiname></xref>  </p> </li>

<li id="GUID-C2DF7C65-DCBF-53DA-BDFC-70BE0F98EAE2"><p>get the number of phone-side

SMS message stores using <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>RMobileSmsMessaging::EnumerateMessageStores()</apiname></xref>  </p> </li>

<li id="GUID-55AAC64A-826F-5055-8E48-40F2DE17FC68"><p>get information about

a specified SMS message store indicated using <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>RMobileSmsMessaging::GetMessageStoreInfo()</apiname></xref>.

Such information is encapsulated in a packaged <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>RMobilePhoneStore::TMobilePhoneStoreInfoV1</apiname></xref> object. </p> </li>

<li id="GUID-D1108DBA-BCD7-5D83-955A-7AB53C96C5EE"><p>get a list of GSM-specific

SMS parameters stored in SIM . Examples of these parameters are Service Centre

Address. Clients use <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>CRetrieveMobilePhoneSmspList</apiname></xref> to

get the list and returns a <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>CMobilePhoneSmspList</apiname></xref> object.

Each parameter is encapsulated in an <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>RMobileSmsMessaging::TMobileSmspEntryV1</apiname></xref> object. </p> </li>

</ul> <p><b>Example </b> </p> <p>The following code sends the message <codeph>aPdu</codeph> to

the destination <codeph>aDest</codeph> over GSM. </p> <p>The code assumes <codeph>iMobilePhone</codeph> is

an <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>RMobilePhone</apiname></xref> object. </p> <codeblock id="GUID-D70DC6E9-0205-5AB7-B397-E63D29DCE790" xml:space="preserve">void CClientApp::SendSMSL(

        const RMobileSmsMessaging::TMobileSmsGsmTpdu& aPdu, 

        const TDesC& aDest)

    {

    // Open SMS session

    RMobileSmsMessaging smsSession;

    User::LeaveIfError(smsSession.Open(iMobilePhone));

    CleanupClosePushL(smsSession);

    // Get SMS capabilities

    RMobileSmsMessaging::TMobileSmsCapsV1 smsCaps;

    RMobileSmsMessaging::TMobileSmsCapsV1Pckg smsCapsPckg(smsCaps);

    User::LeaveIfError(smsSession.GetCaps(smsCapsPckg));

    // Test if SMS can be sent over GSM

    if ( smsCaps.iSmsMode & RMobileSmsMessaging::KCapsGsmSms

        & ( (smsCaps.iSmsControl & RMobileSmsMessaging::KCapsSendWithAck ) || 

            (smsCaps.iSmsControl & RMobileSmsMessaging::KCapsSendNoAck )))

        {

        // Set the required bearer

        TRequestStatus status;

        smsSession.SetMoSmsBearer(status, RMobileSmsMessaging::ESmsBearerCircuitPreferred);

        User::WaitForRequest(status);

        User::LeaveIfError(status.Int());

        // Set destination address and data format attributes

        RMobileSmsMessaging::TMobileSmsSendAttributesV1 sendAtts;

        sendAtts.iDestination.iTelNumber = aDest;

        sendAtts.iDataFormat = RMobileSmsMessaging::EFormatGsmTpdu;

        RMobileSmsMessaging::TMobileSmsSendAttributesV1Pckg sendAttsPckg(sendAtts);

        // Send the message

        smsSession.SendMessage(status, aPdu, sendAttsPckg);

        User::WaitForRequest(status);

        User::LeaveIfError(status.Int());

        }

    // Clean up

    CleanupStack::PopAndDestroy(); // calls smsSession.Close()

    }

</codeblock> </section>

<section id="GUID-DA0E39B0-0051-50AA-9A62-C9BC9E25A7F0"><title>Broadcast messaging</title> <p> <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>RMobileBroadcastMessaging</apiname></xref> provides access

to the broadcast messaging services provided by GSM, WCDMA and CDMA networks. </p> <p>Clients

open an <codeph>RMobileBroadcastMessaging</codeph> sub-session and then wait

for incoming broadcast messages. The broadcast messages received can depend

on a message filter that defines the languages and identifiers of acceptable

and unacceptable messages. </p> <p> <codeph>RMobileBroadcastMessaging</codeph> allows

clients to: </p> <ul>

<li id="GUID-434C178E-B910-5BF5-8DBD-6BCA5F6B43F5"><p>open a broadcast messaging

sub-session using <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>RMobileBroadcastMessaging::Open()</apiname></xref>  </p> </li>

<li id="GUID-20104F53-6D01-5331-9A12-1E180170C920"><p>get capabilities using <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>RMobileBroadcastMessaging::GetCaps()</apiname></xref>.

Capabilities are encapsulated in a packaged <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>RMobileBroadcastMessaging::TMobileBroadcastCapsV1</apiname></xref> object. </p> </li>

<li id="GUID-AC7EBDE6-9A98-5339-8750-E92468B54FBF"><p>wait for the next incoming

broadcast message using <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>RMobileBroadcastMessaging::ReceiveMessage()</apiname></xref>  </p> </li>

<li id="GUID-1082EACA-75A7-53DB-866B-F6033F955EA5"><p>get filter on and off

settings using <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>RMobileBroadcastMessaging::GetFilterSetting()</apiname></xref>  </p> </li>

<li id="GUID-D15B6A4F-8F25-5A69-A072-9C83137AE9E6"><p>set filter on and off

settings using <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>RMobileBroadcastMessaging::SetFilterSetting()</apiname></xref>  </p> </li>

<li id="GUID-4998DA72-5B42-56D3-AA3E-34C421071AA6"><p>be notified when the

filter on and off settings change using <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>RMobileBroadcastMessaging::NotifyFilterSettingChange()</apiname></xref>  </p> </li>

<li id="GUID-014ADE4E-57B7-53D1-87AC-9E1462AB4A2D"><p>get the broadcast message

language filter using <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>RMobileBroadcastMessaging::GetLanguageFilter()</apiname></xref>  </p> </li>

<li id="GUID-FACF1599-7D0F-5CC1-8064-B3040721349A"><p>set the broadcast message

language filter using <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>RMobileBroadcastMessaging::SetLanguageFilter()</apiname></xref>  </p> </li>

<li id="GUID-553BBB69-99AF-5396-9240-24192F7EC399"><p>be notified when the

message language filter changes using <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>RMobileBroadcastMessaging::NotifyLanguageFilterChange()</apiname></xref>  </p> </li>

<li id="GUID-4DD55A70-A8BE-5131-B4AB-C1E56650EA45"><p>retrieve a list of identifiers

by which to filter messages. Clients use <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>CRetrieveMobilePhoneBroadcastIdList</apiname></xref> to

get the list, a <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>CMobilePhoneBroadcastIdList</apiname></xref> object.

Each identifier is encapsulated in an <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>RMobileBroadcastMessaging::TMobileBroadcastIdEntryV1</apiname></xref> object. </p> </li>

<li id="GUID-B3815D23-A48D-5833-BA99-9BE45DEB447C"><p>store a new version

of the entire list of filter identifiers using <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>RMobileBroadcastMessaging::StoreBroadcastIdListL()</apiname></xref>  </p> </li>

<li id="GUID-16B29B8E-58B7-5B17-AE2B-2F894B0606D2"><p>be notified if the filter

identifier list changes using <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>RMobileBroadcastMessaging::NotifyBroadcastIdListChange()</apiname></xref>  </p> </li>

</ul> <p><b>Example </b> </p> <p>The following code gets the contents of the next

GSM broadcast message received in <codeph>aMessageData</codeph>. </p> <codeblock id="GUID-239DABF4-BBEF-543F-8177-4478BA62DF9B" xml:space="preserve">void CClientApp::ReceiveBroadcastMessageL(RMobileBroadcastMessaging::TGsmBroadcastMessageData&amp; aMessageData)

    {

    // Open session

    RMobileBroadcastMessaging bmSession;

    User::LeaveIfError(bmSession.Open(iMobilePhone));

    CleanupClosePushL(bmSession);

    // Get BM capabilities

    RMobileBroadcastMessaging::TMobileBroadcastCapsV1 bmCaps;

    RMobileBroadcastMessaging::TMobileBroadcastCapsV1Pckg bmCapsPckg(bmCaps);

    User::LeaveIfError(bmSession.GetCaps(bmCapsPckg));

    // Test if GSM 03.41 cell broadcast messages are supported

    if (bmCaps.iModeCaps & RMobileBroadcastMessaging::KCapsGsmTpduFormat)

        {

        // Get the next received broadcast message

        RMobileBroadcastMessaging::TMobileBroadcastAttributesV1 bmAtts;

        RMobileBroadcastMessaging::TMobileBroadcastAttributesV1Pckg bmAttsPckg(bmAtts);

        TRequestStatus status;

        bmSession.ReceiveMessage(status, aMessageData, bmAttsPckg);

        User::WaitForRequest(status);

        User::LeaveIfError(status.Int());

        }

    // Clean up

    CleanupStack::PopAndDestroy(); // calls bmSession.Close()

    }</codeblock> </section>

<section id="GUID-35CCDB86-E5B2-5CB8-B662-50144F376221"><title>USSD messaging</title> <p>The

Unstructured Supplementary Service Data (USSD) service provided by GSM/ WCDMA

networks transmits information over the network signalling channels. </p> <p>USSD

is incorporated in the messaging functionality because of its potential use

as a bearer for WAP or other overlying protocol. The USSD protocol is therefore

suitable for implementation within a Sockets protocol (.PRT) module. </p> <p> <codeph>RMobileUssdMessaging</codeph> allows

clients to: </p> <ul>

<li id="GUID-FC45DB15-C427-53C8-84CA-835C669ED9BB"><p>open a USSD messaging

sub-session using <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>RMobileUssdMessaging::Open()</apiname></xref>  </p> </li>

<li id="GUID-0E276A2D-C581-51A7-BAF7-07E9BB8EFC9D"><p>get capabilities using <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>RMobileUssdMessaging::GetCaps()</apiname></xref>. Capabilities

are encapsulated in a packaged <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>RMobileUssdMessaging::TMobileUssdCapsV1</apiname></xref> object. </p> </li>

<li id="GUID-9A001189-6CEC-54BA-86CA-0C5094E9374E"><p>wait for the next incoming

USSD message using <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>RMobileUssdMessaging::ReceiveMessage()</apiname></xref>  </p> </li>

<li id="GUID-60174DD0-738C-533D-86DA-159D1E86671C"><p>send a UUSD message

using <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>RMobileUssdMessaging::SendMessage()</apiname></xref>  </p> </li>

</ul> <p><b>Example </b> </p> <p>The following code gets in <codeph>aMessageData</codeph> the

contents, and in <codeph>aUssdAtts</codeph> the attributes, of the next USSD

message received. </p> <codeblock id="GUID-E82E8B54-2E8A-5D0F-A7EA-5DFEB0EA06E1" xml:space="preserve">void CClientApp::ReceiveUssdMessageL(

    RMobileUssdMessaging::TGsmUssdMessageData& aMessageData,

    RMobileUssdMessaging::TMobileUssdAttributesV1& aUssdAtts)

    {

    // Open session

    RMobileUssdMessaging ussdSession;

    User::LeaveIfError(ussdSession.Open(iMobilePhone));

    CleanupClosePushL(ussdSession);

    // Get ussd capabilities

    RMobileUssdMessaging::TMobileUssdCapsV1 ussdCaps;

    RMobileUssdMessaging::TMobileUssdCapsV1Pckg ussdCapsPckg(ussdCaps);

    User::LeaveIfError(ussdSession.GetCaps(ussdCapsPckg));

    // Test if USSD messages can be received

    if (ussdCaps.iUssdTypes & RMobileUssdMessaging::KCapsMTUssd)

        {

        // Get the next received Ussd message

        RMobileUssdMessaging::TMobileUssdAttributesV1Pckg ussdAttsPckg(aUssdAtts);

        TRequestStatus status;

        ussdSession.ReceiveMessage(status, aMessageData, ussdAttsPckg);

        User::WaitForRequest(status);

        User::LeaveIfError(status.Int());

        }

    // Clean up

    CleanupStack::PopAndDestroy(); // calls ussdSession.Close()

    }</codeblock> </section>

</conbody><related-links>

<link href="GUID-B8F07736-F598-59F0-A004-02A8CBE40554.dita#GUID-B8F07736-F598-59F0-A004-02A8CBE40554/GUID-E6D28D2B-5201-569E-881D-1D5A0BDC41B0">

<linktext>SMS message store</linktext></link>

</related-links></concept>