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

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

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

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

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

     6 <!-- Initial Contributors:

     7     Nokia Corporation - initial contribution.

     8 Contributors: 

     9 -->

    10 <!DOCTYPE concept

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

    12 <concept xml:lang="en" id="GUID-E0470135-DB19-5D3C-AF95-C412CBF515B2"><title>Multimode Messaging</title><shortdesc>The Multimode telephony API provides a number of specialised messaging classes that are derived from <apiname>RTelSubSessionBase</apiname>. 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(

    13         const RMobileSmsMessaging::TMobileSmsGsmTpdu& aPdu, 

    14         const TDesC& aDest)

    15     {

    16     // Open SMS session

    17     RMobileSmsMessaging smsSession;

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

    19     CleanupClosePushL(smsSession);

    20 

    21     // Get SMS capabilities

    22     RMobileSmsMessaging::TMobileSmsCapsV1 smsCaps;

    23     RMobileSmsMessaging::TMobileSmsCapsV1Pckg smsCapsPckg(smsCaps);

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

    25 

    26     // Test if SMS can be sent over GSM

    27     if ( smsCaps.iSmsMode & RMobileSmsMessaging::KCapsGsmSms

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

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

    30         {

    31         // Set the required bearer

    32         TRequestStatus status;

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

    34         User::WaitForRequest(status);

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

    36 

    37         // Set destination address and data format attributes

    38         RMobileSmsMessaging::TMobileSmsSendAttributesV1 sendAtts;

    39         sendAtts.iDestination.iTelNumber = aDest;

    40         sendAtts.iDataFormat = RMobileSmsMessaging::EFormatGsmTpdu;

    41         RMobileSmsMessaging::TMobileSmsSendAttributesV1Pckg sendAttsPckg(sendAtts);

    42 

    43         // Send the message

    44         smsSession.SendMessage(status, aPdu, sendAttsPckg);

    45         User::WaitForRequest(status);

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

    47         }

    48      

    49     // Clean up

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

    51     }

    52 </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)

    53     {

    54     // Open session

    55     RMobileBroadcastMessaging bmSession;

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

    57     CleanupClosePushL(bmSession);

    58 

    59     // Get BM capabilities

    60     RMobileBroadcastMessaging::TMobileBroadcastCapsV1 bmCaps;

    61     RMobileBroadcastMessaging::TMobileBroadcastCapsV1Pckg bmCapsPckg(bmCaps);

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

    63 

    64     // Test if GSM 03.41 cell broadcast messages are supported

    65     if (bmCaps.iModeCaps & RMobileBroadcastMessaging::KCapsGsmTpduFormat)

    66         {

    67         // Get the next received broadcast message

    68         RMobileBroadcastMessaging::TMobileBroadcastAttributesV1 bmAtts;

    69         RMobileBroadcastMessaging::TMobileBroadcastAttributesV1Pckg bmAttsPckg(bmAtts);

    70         TRequestStatus status;

    71         bmSession.ReceiveMessage(status, aMessageData, bmAttsPckg);

    72         User::WaitForRequest(status);

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

    74         }

    75      

    76     // Clean up

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

    78     }</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(

    79     RMobileUssdMessaging::TGsmUssdMessageData& aMessageData,

    80     RMobileUssdMessaging::TMobileUssdAttributesV1& aUssdAtts)

    81     {

    82     // Open session

    83     RMobileUssdMessaging ussdSession;

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

    85     CleanupClosePushL(ussdSession);

    86 

    87     // Get ussd capabilities

    88     RMobileUssdMessaging::TMobileUssdCapsV1 ussdCaps;

    89     RMobileUssdMessaging::TMobileUssdCapsV1Pckg ussdCapsPckg(ussdCaps);

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

    91 

    92     // Test if USSD messages can be received

    93     if (ussdCaps.iUssdTypes & RMobileUssdMessaging::KCapsMTUssd)

    94         {

    95         // Get the next received Ussd message

    96         RMobileUssdMessaging::TMobileUssdAttributesV1Pckg ussdAttsPckg(aUssdAtts);

    97         TRequestStatus status;

    98         ussdSession.ReceiveMessage(status, aMessageData, ussdAttsPckg);

    99         User::WaitForRequest(status);

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

   101         }

   102      

   103     // Clean up

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

   105     }</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>