<?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&amp; aPdu, 
        const TDesC&amp; 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 &amp; RMobileSmsMessaging::KCapsGsmSms
        &amp; ( (smsCaps.iSmsControl &amp; RMobileSmsMessaging::KCapsSendWithAck ) || 
            (smsCaps.iSmsControl &amp; 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 &amp; 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&amp; aMessageData,
    RMobileUssdMessaging::TMobileUssdAttributesV1&amp; 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 &amp; 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>