7 Nokia Corporation - initial contribution. |
7 Nokia Corporation - initial contribution. |
8 Contributors: |
8 Contributors: |
9 --> |
9 --> |
10 <!DOCTYPE concept |
10 <!DOCTYPE concept |
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
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( |
12 <concept id="GUID-E0470135-DB19-5D3C-AF95-C412CBF515B2" xml:lang="en"><title>Multimode |
|
13 Messaging</title><shortdesc>The Multimode telephony API provides a number of specialised messaging |
|
14 classes that are derived from <codeph>RTelSubSessionBase</codeph>. One of |
|
15 the classes is responsible for SMS, another for Broadcast and another for |
|
16 USSD messaging. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
17 <p>The following table describes the three messaging types. </p> |
|
18 <table id="GUID-E54D8AA1-BC1F-5706-B1BA-9193BB33FE0E"> |
|
19 <tgroup cols="5"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/><colspec colname="col3"/><colspec colname="col4"/> |
|
20 <thead> |
|
21 <row> |
|
22 <entry>Type</entry> |
|
23 <entry>Required</entry> |
|
24 <entry>GSM</entry> |
|
25 <entry>WCDMA</entry> |
|
26 <entry>CDMA</entry> |
|
27 </row> |
|
28 </thead> |
|
29 <tbody> |
|
30 <row> |
|
31 <entry><p> <xref href="GUID-E0470135-DB19-5D3C-AF95-C412CBF515B2.dita#GUID-E0470135-DB19-5D3C-AF95-C412CBF515B2/GUID-DF523227-DADA-578A-8816-3144C7125663">SMS |
|
32 messaging</xref> </p> </entry> |
|
33 <entry><p>No </p> </entry> |
|
34 <entry><p>Yes </p> </entry> |
|
35 <entry><p>Yes </p> </entry> |
|
36 <entry><p>Yes </p> </entry> |
|
37 </row> |
|
38 <row> |
|
39 <entry><p> <xref href="GUID-E0470135-DB19-5D3C-AF95-C412CBF515B2.dita#GUID-E0470135-DB19-5D3C-AF95-C412CBF515B2/GUID-DA0E39B0-0051-50AA-9A62-C9BC9E25A7F0">Broadcast |
|
40 messaging</xref> </p> </entry> |
|
41 <entry><p>No </p> </entry> |
|
42 <entry><p>Yes </p> </entry> |
|
43 <entry><p>Yes </p> </entry> |
|
44 <entry><p>Yes </p> </entry> |
|
45 </row> |
|
46 <row> |
|
47 <entry><p> <xref href="GUID-E0470135-DB19-5D3C-AF95-C412CBF515B2.dita#GUID-E0470135-DB19-5D3C-AF95-C412CBF515B2/GUID-35CCDB86-E5B2-5CB8-B662-50144F376221">USSD |
|
48 messaging</xref> </p> </entry> |
|
49 <entry><p>No </p> </entry> |
|
50 <entry><p>Yes </p> </entry> |
|
51 <entry><p>Yes </p> </entry> |
|
52 <entry><p>No </p> </entry> |
|
53 </row> |
|
54 </tbody> |
|
55 </tgroup> |
|
56 </table> |
|
57 <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 |
|
58 to the Short Message Service provided by GSM, WCDMA and CDMA networks. </p> <p>In |
|
59 CDMA mode, SMS has three protocol layers: Relay lowest level, Transport and |
|
60 Teleservice. Relay is the lowest level while Transport and Teleservice are |
|
61 application level. <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>RMobileSmsMessaging</apiname></xref> provides |
|
62 an interface to the Transport layer. Usually, the Teleservice layer is implemented |
|
63 in a sockets protocol module. The Teleservice layer, rather than <codeph>RMobileSmsMessaging</codeph>, |
|
64 would be the interface used by applications to send SMS messages. SMS messages |
|
65 are passed across the API as Packet Data Units (PDUs). </p> <p>Segmentation |
|
66 and reassembly of long SMS messages over 255 bytes is not provided by the |
|
67 API, and must be provided by a higher-level module such as the <filepath>smsprot.prt</filepath> protocol |
|
68 module. </p> <p> <codeph>RMobileSmsMessaging</codeph> allows clients to: </p> <ul> |
|
69 <li id="GUID-D1645129-9195-5CB4-9DC5-39952782B309"><p>open an SMS sub-session |
|
70 using <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>RMobileSmsMessaging::Open()</apiname></xref> </p> </li> |
|
71 <li id="GUID-C5FACABA-62EA-5E54-9B89-60BFEFFC8D22"><p>retrieve capabilities |
|
72 using <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>RMobileSmsMessaging::GetCaps()</apiname></xref>. |
|
73 Capabilities are encapsulated in a packaged <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>RMobileSmsMessaging::TMobileSmsCapsV1</apiname></xref> object. </p> </li> |
|
74 <li id="GUID-67D3CF37-546D-596C-8A8E-72D3D4DE6F8F"><p>retrieve the mode the |
|
75 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> |
|
76 <li id="GUID-A1687E1D-6105-58CD-A308-213C39682007"><p>set the mode the phone |
|
77 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> |
|
78 <li id="GUID-9F6EADDA-BEA0-57D0-8F3E-0330C3841217"><p>wait for the next incoming |
|
79 SMS message using <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>RMobileSmsMessaging::ReceiveMessage()</apiname></xref> </p> </li> |
|
80 <li id="GUID-DDF357F7-F520-5365-B943-4A548B888864"><p>send a positive acknowledgement |
|
81 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> |
|
82 <li id="GUID-2BDABC27-1EA1-5022-8A2B-2C94B3287136"><p>send a negative acknowledgement |
|
83 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> |
|
84 <li id="GUID-7C0F5FE5-AAC3-50D5-9457-87C70DD7EFD5"><p>tell the network to |
|
85 resume transferring SMS to the phone, after reception has been suspended because |
|
86 SMS storage is full using <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>RMobileSmsMessaging::ResumeSmsReception()</apiname></xref> </p> </li> |
|
87 <li id="GUID-DBC2E3D5-E2B6-5137-A34C-C5B5822F824C"><p>get the bearer type |
|
88 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> |
|
89 <li id="GUID-56C1FD58-8DF7-5DE2-A0E2-5A9123F77384"><p>set the bearer type |
|
90 using <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>RMobileSmsMessaging::SetMoSmsBearer()</apiname></xref> </p> </li> |
|
91 <li id="GUID-ADE3F254-0E6D-5AE9-A3A9-6F70BA5B0CD4"><p>be notified if the bearer |
|
92 type changes using <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>RMobileSmsMessaging::NotifyMoSmsBearerChange()</apiname></xref> </p> </li> |
|
93 <li id="GUID-D1968BB6-CFBB-58C3-A935-BAE5C8B37F4D"><p>send an SMS message |
|
94 to the network using <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>RMobileSmsMessaging::SendMessage()</apiname></xref> </p> </li> |
|
95 <li id="GUID-C2DF7C65-DCBF-53DA-BDFC-70BE0F98EAE2"><p>get the number of phone-side |
|
96 SMS message stores using <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>RMobileSmsMessaging::EnumerateMessageStores()</apiname></xref> </p> </li> |
|
97 <li id="GUID-55AAC64A-826F-5055-8E48-40F2DE17FC68"><p>get information about |
|
98 a specified SMS message store indicated using <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>RMobileSmsMessaging::GetMessageStoreInfo()</apiname></xref>. |
|
99 Such information is encapsulated in a packaged <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>RMobilePhoneStore::TMobilePhoneStoreInfoV1</apiname></xref> object. </p> </li> |
|
100 <li id="GUID-D1108DBA-BCD7-5D83-955A-7AB53C96C5EE"><p>get a list of GSM-specific |
|
101 SMS parameters stored in SIM . Examples of these parameters are Service Centre |
|
102 Address. Clients use <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>CRetrieveMobilePhoneSmspList</apiname></xref> to |
|
103 get the list and returns a <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>CMobilePhoneSmspList</apiname></xref> object. |
|
104 Each parameter is encapsulated in an <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>RMobileSmsMessaging::TMobileSmspEntryV1</apiname></xref> object. </p> </li> |
|
105 </ul> <p><b>Example </b> </p> <p>The following code sends the message <codeph>aPdu</codeph> to |
|
106 the destination <codeph>aDest</codeph> over GSM. </p> <p>The code assumes <codeph>iMobilePhone</codeph> is |
|
107 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, |
108 const RMobileSmsMessaging::TMobileSmsGsmTpdu& aPdu, |
14 const TDesC& aDest) |
109 const TDesC& aDest) |
15 { |
110 { |
16 // Open SMS session |
111 // Open SMS session |
17 RMobileSmsMessaging smsSession; |
112 RMobileSmsMessaging smsSession; |
47 } |
142 } |
48 |
143 |
49 // Clean up |
144 // Clean up |
50 CleanupStack::PopAndDestroy(); // calls smsSession.Close() |
145 CleanupStack::PopAndDestroy(); // calls smsSession.Close() |
51 } |
146 } |
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& aMessageData) |
147 </codeblock> </section> |
|
148 <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 |
|
149 to the broadcast messaging services provided by GSM, WCDMA and CDMA networks. </p> <p>Clients |
|
150 open an <codeph>RMobileBroadcastMessaging</codeph> sub-session and then wait |
|
151 for incoming broadcast messages. The broadcast messages received can depend |
|
152 on a message filter that defines the languages and identifiers of acceptable |
|
153 and unacceptable messages. </p> <p> <codeph>RMobileBroadcastMessaging</codeph> allows |
|
154 clients to: </p> <ul> |
|
155 <li id="GUID-434C178E-B910-5BF5-8DBD-6BCA5F6B43F5"><p>open a broadcast messaging |
|
156 sub-session using <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>RMobileBroadcastMessaging::Open()</apiname></xref> </p> </li> |
|
157 <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>. |
|
158 Capabilities are encapsulated in a packaged <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>RMobileBroadcastMessaging::TMobileBroadcastCapsV1</apiname></xref> object. </p> </li> |
|
159 <li id="GUID-AC7EBDE6-9A98-5339-8750-E92468B54FBF"><p>wait for the next incoming |
|
160 broadcast message using <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>RMobileBroadcastMessaging::ReceiveMessage()</apiname></xref> </p> </li> |
|
161 <li id="GUID-1082EACA-75A7-53DB-866B-F6033F955EA5"><p>get filter on and off |
|
162 settings using <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>RMobileBroadcastMessaging::GetFilterSetting()</apiname></xref> </p> </li> |
|
163 <li id="GUID-D15B6A4F-8F25-5A69-A072-9C83137AE9E6"><p>set filter on and off |
|
164 settings using <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>RMobileBroadcastMessaging::SetFilterSetting()</apiname></xref> </p> </li> |
|
165 <li id="GUID-4998DA72-5B42-56D3-AA3E-34C421071AA6"><p>be notified when the |
|
166 filter on and off settings change using <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>RMobileBroadcastMessaging::NotifyFilterSettingChange()</apiname></xref> </p> </li> |
|
167 <li id="GUID-014ADE4E-57B7-53D1-87AC-9E1462AB4A2D"><p>get the broadcast message |
|
168 language filter using <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>RMobileBroadcastMessaging::GetLanguageFilter()</apiname></xref> </p> </li> |
|
169 <li id="GUID-FACF1599-7D0F-5CC1-8064-B3040721349A"><p>set the broadcast message |
|
170 language filter using <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>RMobileBroadcastMessaging::SetLanguageFilter()</apiname></xref> </p> </li> |
|
171 <li id="GUID-553BBB69-99AF-5396-9240-24192F7EC399"><p>be notified when the |
|
172 message language filter changes using <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>RMobileBroadcastMessaging::NotifyLanguageFilterChange()</apiname></xref> </p> </li> |
|
173 <li id="GUID-4DD55A70-A8BE-5131-B4AB-C1E56650EA45"><p>retrieve a list of identifiers |
|
174 by which to filter messages. Clients use <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>CRetrieveMobilePhoneBroadcastIdList</apiname></xref> to |
|
175 get the list, a <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>CMobilePhoneBroadcastIdList</apiname></xref> object. |
|
176 Each identifier is encapsulated in an <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>RMobileBroadcastMessaging::TMobileBroadcastIdEntryV1</apiname></xref> object. </p> </li> |
|
177 <li id="GUID-B3815D23-A48D-5833-BA99-9BE45DEB447C"><p>store a new version |
|
178 of the entire list of filter identifiers using <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>RMobileBroadcastMessaging::StoreBroadcastIdListL()</apiname></xref> </p> </li> |
|
179 <li id="GUID-16B29B8E-58B7-5B17-AE2B-2F894B0606D2"><p>be notified if the filter |
|
180 identifier list changes using <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>RMobileBroadcastMessaging::NotifyBroadcastIdListChange()</apiname></xref> </p> </li> |
|
181 </ul> <p><b>Example </b> </p> <p>The following code gets the contents of the next |
|
182 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& aMessageData) |
53 { |
183 { |
54 // Open session |
184 // Open session |
55 RMobileBroadcastMessaging bmSession; |
185 RMobileBroadcastMessaging bmSession; |
56 User::LeaveIfError(bmSession.Open(iMobilePhone)); |
186 User::LeaveIfError(bmSession.Open(iMobilePhone)); |
57 CleanupClosePushL(bmSession); |
187 CleanupClosePushL(bmSession); |
73 User::LeaveIfError(status.Int()); |
203 User::LeaveIfError(status.Int()); |
74 } |
204 } |
75 |
205 |
76 // Clean up |
206 // Clean up |
77 CleanupStack::PopAndDestroy(); // calls bmSession.Close() |
207 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( |
208 }</codeblock> </section> |
|
209 <section id="GUID-35CCDB86-E5B2-5CB8-B662-50144F376221"><title>USSD messaging</title> <p>The |
|
210 Unstructured Supplementary Service Data (USSD) service provided by GSM/ WCDMA |
|
211 networks transmits information over the network signalling channels. </p> <p>USSD |
|
212 is incorporated in the messaging functionality because of its potential use |
|
213 as a bearer for WAP or other overlying protocol. The USSD protocol is therefore |
|
214 suitable for implementation within a Sockets protocol (.PRT) module. </p> <p> <codeph>RMobileUssdMessaging</codeph> allows |
|
215 clients to: </p> <ul> |
|
216 <li id="GUID-FC45DB15-C427-53C8-84CA-835C669ED9BB"><p>open a USSD messaging |
|
217 sub-session using <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>RMobileUssdMessaging::Open()</apiname></xref> </p> </li> |
|
218 <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 |
|
219 are encapsulated in a packaged <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>RMobileUssdMessaging::TMobileUssdCapsV1</apiname></xref> object. </p> </li> |
|
220 <li id="GUID-9A001189-6CEC-54BA-86CA-0C5094E9374E"><p>wait for the next incoming |
|
221 USSD message using <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>RMobileUssdMessaging::ReceiveMessage()</apiname></xref> </p> </li> |
|
222 <li id="GUID-60174DD0-738C-533D-86DA-159D1E86671C"><p>send a UUSD message |
|
223 using <xref href="GUID-D8BBA972-82CB-3561-8913-4659103C263C.dita"><apiname>RMobileUssdMessaging::SendMessage()</apiname></xref> </p> </li> |
|
224 </ul> <p><b>Example </b> </p> <p>The following code gets in <codeph>aMessageData</codeph> the |
|
225 contents, and in <codeph>aUssdAtts</codeph> the attributes, of the next USSD |
|
226 message received. </p> <codeblock id="GUID-E82E8B54-2E8A-5D0F-A7EA-5DFEB0EA06E1" xml:space="preserve">void CClientApp::ReceiveUssdMessageL( |
79 RMobileUssdMessaging::TGsmUssdMessageData& aMessageData, |
227 RMobileUssdMessaging::TGsmUssdMessageData& aMessageData, |
80 RMobileUssdMessaging::TMobileUssdAttributesV1& aUssdAtts) |
228 RMobileUssdMessaging::TMobileUssdAttributesV1& aUssdAtts) |
81 { |
229 { |
82 // Open session |
230 // Open session |
83 RMobileUssdMessaging ussdSession; |
231 RMobileUssdMessaging ussdSession; |