12 <concept xml:lang="en" id="GUID-E6B77879-DA27-5D8C-B72D-A165F80CFF3B"><title>Architecture</title><prolog><metadata><keywords/></metadata></prolog><conbody><p>Multimode telephony extends the basic telephony interfaces offered by the core telephony API. Similar to the Core telephony API, the Multimode API take client requests and passes them to the ETel server. The server then passes the request to the telephony driver of the device (<filepath>.TSY</filepath> module), which manages communications with the telephony hardware itself. Depending on the device, the <filepath>.TSY</filepath> may support a single mode for example GSM or be multimode. </p> <p>The following diagram shows these component relationships: </p> <fig id="GUID-9006D69B-605B-554C-9836-155062098DE8"><title>

    12 <concept id="GUID-E6B77879-DA27-5D8C-B72D-A165F80CFF3B" xml:lang="en"><title>Architecture</title><prolog><metadata><keywords/></metadata></prolog><conbody>

    13           Multimode ETel component architecture 

    13 <p>Multimode telephony extends the basic telephony interfaces offered by the

    14         </title> <image href="GUID-E55B3ACD-4651-5FBD-AC9F-511E5CBCC0C9_d0e45703_href.png" placement="inline"/></fig> <p>Much of the functionality defined in Multimode ETel is <i>optional</i>, meaning that a .TSY is not required to support it. Clients should use the capability-checking interfaces supplied by Multimode ETel to ensure that such functionality is available before attempting to use it. </p> <section><title>Description</title> <p>The diagram below shows the key classes in the Core and Multimode APIs and their inheritance relationships. The top package is ETel Core, the lower package is Multimode ETel. </p> <fig id="GUID-90475AD2-04DF-5ECE-BA0D-28FD9500E6AB"><title>

    14 core telephony API. Similar to the Core telephony API, the Multimode API take

    15              Multimode ETel key classes 

    15 client requests and passes them to the ETel server. The server then passes

    16           </title> <image href="GUID-9147F8AF-01B3-5110-8FE7-A6318B5048D9_d0e45722_href.png" placement="inline"/></fig> <p>The key Multimode ETel classes are R-classes. The purpose of these classes is to communicate with the telephony server. All of the classes shown derive, directly or indirectly, from <xref href="GUID-9CE46AD7-722E-3831-A359-C90A350E931D.dita"><apiname>RTelSubSessionBase</apiname></xref>, which manages a sub-session to the telephony server. </p> <p>The classes are summarised below: </p> <ul><li id="GUID-84A609E9-EF74-5425-9433-7F4F0B9E01FF"><p> <xref href="GUID-9CE46AD7-722E-3831-A359-C90A350E931D.dita"><apiname>RMobilePhone</apiname></xref> encapsulates the properties of the phone that do not relate to a particular line or call, and derives from <xref href="GUID-9CE46AD7-722E-3831-A359-C90A350E931D.dita"><apiname>RPhone</apiname></xref> interface of the core telephony API. It provides the following: </p> <ul><li id="GUID-C646F3F5-2D1C-5BE9-8AAC-AB0B3C4C3213"><p>phone capabilities and status </p> </li> <li id="GUID-6F8DF782-57C4-58D3-848D-778AFCDB0344"><p>network settings and status </p> </li> <li id="GUID-43286FE2-8F5F-5DDE-AC78-9EC92AE5B757"><p>phone security settings </p> </li> <li id="GUID-F98DF15E-EC2E-5F03-8202-1F3FFCDB1325"><p>phone-wide settings for a large number of advanced services, such as call forwarding, barring, waiting, and charge information </p> </li> </ul> </li> <li id="GUID-0E707A36-8304-585A-85B4-AD078AB359AB"><p> <xref href="GUID-9CE46AD7-722E-3831-A359-C90A350E931D.dita"><apiname>RMobileCall</apiname></xref> encapsulates information and functionality for a particular call, and derives from <xref href="GUID-9CE46AD7-722E-3831-A359-C90A350E931D.dita"><apiname>RCall</apiname></xref> interface of the core telephony. It provides the following: </p> <ul><li id="GUID-14E789FE-386C-54CA-A5C7-6C5311F4AF92"><p>call capabilities and status </p> </li> <li id="GUID-A98E071E-CA6E-524C-BD2A-77A5988376EC"><p>advanced call control, including transferring calls, and putting calls on-hold </p> </li> <li id="GUID-99B5AB50-8557-529F-81BA-7E962EA4E413"><p>extended functionality to support data calls, including HSCSD </p> </li> <li id="GUID-36197642-242C-58C9-AAE4-2A37A7C81854"><p>status information and control functions for calls using Call Completion on Busy (CCBS), and User-To-User Signalling (UUS) services of the GSM. </p> </li> </ul> </li> <li id="GUID-194E1591-BB06-52A6-A983-ED3C466B78FF"><p> <xref href="GUID-9CE46AD7-722E-3831-A359-C90A350E931D.dita"><apiname>RMobileLine</apiname></xref> derives from <xref href="GUID-9CE46AD7-722E-3831-A359-C90A350E931D.dita"><apiname>RLine</apiname></xref> interface of the core telephony API, and provides additional line status information, such as if the line is on-hold. </p> </li> <li id="GUID-FA228326-A009-552F-B22E-B4C51A836693"><p> <xref href="GUID-9CE46AD7-722E-3831-A359-C90A350E931D.dita"><apiname>RMobileConferenceCall</apiname></xref> provides functions to manage a collection of calls as a conference call. </p> </li> <li id="GUID-03219F88-6F34-5828-9DF3-2E43C17D7751"><p> <xref href="GUID-9CE46AD7-722E-3831-A359-C90A350E931D.dita"><apiname>RMobileSmsMessaging</apiname></xref>, <xref href="GUID-9CE46AD7-722E-3831-A359-C90A350E931D.dita"><apiname>RMobileBroadcastMessaging</apiname></xref>, and <xref href="GUID-9CE46AD7-722E-3831-A359-C90A350E931D.dita"><apiname>RMobileUssdMessaging</apiname></xref> are specialised messaging classes, respectively for SMS, Broadcast messages, and USSD messaging. </p> </li> <li id="GUID-3BCC5489-CB2A-5045-BEAA-CB99C6F9F36F"><p> <xref href="GUID-9CE46AD7-722E-3831-A359-C90A350E931D.dita"><apiname>RMobilePhoneStore</apiname></xref> and its derived classes provide management for the various types of information that can be stored on the phone and the ICC card including SMS messages, and address book information. </p> </li> </ul> <p>The API also provides a number of list classes, derived from <xref href="GUID-9CE46AD7-722E-3831-A359-C90A350E931D.dita"><apiname>CMobilePhoneListBase</apiname></xref>, which allow clients to retrieve easily groups of settings and information. </p> <p><b>Note on code samples </b> </p> <p>Many of the functions described in this guide are asynchronous, and are used by an active object. For purposes of conciseness, the code samples do not use active objects, but, unrealistically, synchronously wait for the function to return (using <codeph>User::WaitForRequest()</codeph>). </p> </section> <section id="GUID-E065354F-66E6-57B4-A7E7-C4C3A6038939"><title>High-level multimode capabilities</title> <p>A TSY is not required to support all the functionality defined by Multimode telephony although it supports all core telephony functionality. Optional functionality is divided by the API into a number of functional areas, such as, support for Call Waiting, and for SMS messaging. To query a TSY about the functional areas it supports, use <xref href="GUID-9CE46AD7-722E-3831-A359-C90A350E931D.dita"><apiname>RTelServer::IsSupportedByModule()</apiname></xref>. </p> <p>Flags for the functional areas are defined in enumerations. <xref href="GUID-9CE46AD7-722E-3831-A359-C90A350E931D.dita"><apiname>TMultimodeETelV1Api</apiname></xref> defines flags for the functional areas defined in the Symbian OS v7.0 release. <xref href="GUID-9CE46AD7-722E-3831-A359-C90A350E931D.dita"><apiname>TMultimodeETelV2Api</apiname></xref>, <xref href="GUID-9CE46AD7-722E-3831-A359-C90A350E931D.dita"><apiname>TMultimodeETelV3Api</apiname></xref>, and <xref href="GUID-9CE46AD7-722E-3831-A359-C90A350E931D.dita"><apiname>TMultimodeETelV4Api</apiname></xref> define flags for additional functional areas defined in later releases. </p> <p>Functional areas have individual query functions that offer detailed capability information on that area. For example, <xref href="GUID-9CE46AD7-722E-3831-A359-C90A350E931D.dita"><apiname>RMobilePhone::GetMultimodeCaps()</apiname></xref> queries for the phone's supported modes. </p> <p><b>Example </b> </p> <p>The following code tests if the TSY supports multimode telephony API at all, by querying using the <xref href="GUID-9CE46AD7-722E-3831-A359-C90A350E931D.dita"><apiname>KETelExtMultimodeV1</apiname></xref> flag. If multimode is supported, then other flags can be used to query for support for particular areas. </p> <p>The code assumes <codeph>iTsyName</codeph> holds the name of the TSY in use. </p> <codeblock id="GUID-6EE6B824-942D-573E-8197-96DB4D5A483B" xml:space="preserve">TInt funcFlags = KETelExtMultimodeV1;

    16 the request to the telephony driver of the device (<filepath>.TSY</filepath> module),

    17 which manages communications with the telephony hardware itself. Depending

    18 on the device, the <filepath>.TSY</filepath> may support a single mode for

    19 example GSM or be multimode. </p>

    20 <p>The following diagram shows these component relationships: </p>

    21 <fig id="GUID-9006D69B-605B-554C-9836-155062098DE8">

    22 <title>           Multimode ETel component architecture          </title>

    23 <image href="GUID-E55B3ACD-4651-5FBD-AC9F-511E5CBCC0C9_d0e51959_href.png" placement="inline"/>

    24 </fig>

    25 <p>Much of the functionality defined in Multimode ETel is <i>optional</i>,

    26 meaning that a .TSY is not required to support it. Clients should use the

    27 capability-checking interfaces supplied by Multimode ETel to ensure that such

    28 functionality is available before attempting to use it. </p>

    29 <section id="GUID-68CA7D2A-AB2E-4ADC-9286-337D6D15D34F"><title>Description</title> <p>The diagram below shows the key classes

    30 in the Core and Multimode APIs and their inheritance relationships. The top

    31 package is ETel Core, the lower package is Multimode ETel. </p> <fig id="GUID-90475AD2-04DF-5ECE-BA0D-28FD9500E6AB">

    32 <title>              Multimode ETel key classes            </title>

    33 <image href="GUID-9147F8AF-01B3-5110-8FE7-A6318B5048D9_d0e51980_href.png" placement="inline"/>

    34 </fig> <p>The key Multimode ETel classes are R-classes. The purpose of these

    35 classes is to communicate with the telephony server. All of the classes shown

    36 derive, directly or indirectly, from <xref href="GUID-9CE46AD7-722E-3831-A359-C90A350E931D.dita"><apiname>RTelSubSessionBase</apiname></xref>,

    37 which manages a sub-session to the telephony server. </p> <p>The classes are

    38 summarised below: </p> <ul>

    39 <li id="GUID-84A609E9-EF74-5425-9433-7F4F0B9E01FF"><p> <xref href="GUID-9CE46AD7-722E-3831-A359-C90A350E931D.dita"><apiname>RMobilePhone</apiname></xref> encapsulates

    40 the properties of the phone that do not relate to a particular line or call,

    41 and derives from <xref href="GUID-9CE46AD7-722E-3831-A359-C90A350E931D.dita"><apiname>RPhone</apiname></xref> interface of the

    42 core telephony API. It provides the following: </p> <ul>

    43 <li id="GUID-C646F3F5-2D1C-5BE9-8AAC-AB0B3C4C3213"><p>phone capabilities and

    44 status </p> </li>

    45 <li id="GUID-6F8DF782-57C4-58D3-848D-778AFCDB0344"><p>network settings and

    46 status </p> </li>

    47 <li id="GUID-43286FE2-8F5F-5DDE-AC78-9EC92AE5B757"><p>phone security settings </p> </li>

    48 <li id="GUID-F98DF15E-EC2E-5F03-8202-1F3FFCDB1325"><p>phone-wide settings

    49 for a large number of advanced services, such as call forwarding, barring,

    50 waiting, and charge information </p> </li>

    51 </ul> </li>

    52 <li id="GUID-0E707A36-8304-585A-85B4-AD078AB359AB"><p> <xref href="GUID-9CE46AD7-722E-3831-A359-C90A350E931D.dita"><apiname>RMobileCall</apiname></xref> encapsulates

    53 information and functionality for a particular call, and derives from <xref href="GUID-9CE46AD7-722E-3831-A359-C90A350E931D.dita"><apiname>RCall</apiname></xref> interface of the core telephony. It provides

    54 the following: </p> <ul>

    55 <li id="GUID-14E789FE-386C-54CA-A5C7-6C5311F4AF92"><p>call capabilities and

    56 status </p> </li>

    57 <li id="GUID-A98E071E-CA6E-524C-BD2A-77A5988376EC"><p>advanced call control,

    58 including transferring calls, and putting calls on-hold </p> </li>

    59 <li id="GUID-99B5AB50-8557-529F-81BA-7E962EA4E413"><p>extended functionality

    60 to support data calls, including HSCSD </p> </li>

    61 <li id="GUID-36197642-242C-58C9-AAE4-2A37A7C81854"><p>status information and

    62 control functions for calls using Call Completion on Busy (CCBS), and User-To-User

    63 Signalling (UUS) services of the GSM. </p> </li>

    64 </ul> </li>

    65 <li id="GUID-194E1591-BB06-52A6-A983-ED3C466B78FF"><p> <xref href="GUID-9CE46AD7-722E-3831-A359-C90A350E931D.dita"><apiname>RMobileLine</apiname></xref> derives

    66 from <xref href="GUID-9CE46AD7-722E-3831-A359-C90A350E931D.dita"><apiname>RLine</apiname></xref> interface of the core telephony

    67 API, and provides additional line status information, such as if the line

    68 is on-hold. </p> </li>

    69 <li id="GUID-FA228326-A009-552F-B22E-B4C51A836693"><p> <xref href="GUID-9CE46AD7-722E-3831-A359-C90A350E931D.dita"><apiname>RMobileConferenceCall</apiname></xref> provides

    70 functions to manage a collection of calls as a conference call. </p> </li>

    71 <li id="GUID-03219F88-6F34-5828-9DF3-2E43C17D7751"><p> <xref href="GUID-9CE46AD7-722E-3831-A359-C90A350E931D.dita"><apiname>RMobileSmsMessaging</apiname></xref>, <xref href="GUID-9CE46AD7-722E-3831-A359-C90A350E931D.dita"><apiname>RMobileBroadcastMessaging</apiname></xref>, and <xref href="GUID-9CE46AD7-722E-3831-A359-C90A350E931D.dita"><apiname>RMobileUssdMessaging</apiname></xref> are

    72 specialised messaging classes, respectively for SMS, Broadcast messages, and

    73 USSD messaging. </p> </li>

    74 <li id="GUID-3BCC5489-CB2A-5045-BEAA-CB99C6F9F36F"><p> <xref href="GUID-9CE46AD7-722E-3831-A359-C90A350E931D.dita"><apiname>RMobilePhoneStore</apiname></xref> and

    75 its derived classes provide management for the various types of information

    76 that can be stored on the phone and the ICC card including SMS messages, and

    77 address book information. </p> </li>

    78 </ul> <p>The API also provides a number of list classes, derived from <xref href="GUID-9CE46AD7-722E-3831-A359-C90A350E931D.dita"><apiname>CMobilePhoneListBase</apiname></xref>, which allow clients to retrieve

    79 easily groups of settings and information. </p> <p><b>Note on code samples </b> </p> <p>Many of the functions described in this

    80 guide are asynchronous, and are used by an active object. For purposes of

    81 conciseness, the code samples do not use active objects, but, unrealistically,

    82 synchronously wait for the function to return (using <codeph>User::WaitForRequest()</codeph>). </p> </section>

    83 <section id="GUID-E065354F-66E6-57B4-A7E7-C4C3A6038939"><title>High-level

    84 multimode capabilities</title> <p>A TSY is not required to support all the

    85 functionality defined by Multimode telephony although it supports all core

    86 telephony functionality. Optional functionality is divided by the API into

    87 a number of functional areas, such as, support for Call Waiting, and for SMS

    88 messaging. To query a TSY about the functional areas it supports, use <xref href="GUID-9CE46AD7-722E-3831-A359-C90A350E931D.dita"><apiname>RTelServer::IsSupportedByModule()</apiname></xref>. </p> <p>Flags

    89 for the functional areas are defined in enumerations. <xref href="GUID-9CE46AD7-722E-3831-A359-C90A350E931D.dita"><apiname>TMultimodeETelV1Api</apiname></xref> defines

    90 flags for the functional areas. <xref href="GUID-9CE46AD7-722E-3831-A359-C90A350E931D.dita"><apiname>TMultimodeETelV2Api</apiname></xref>, <xref href="GUID-9CE46AD7-722E-3831-A359-C90A350E931D.dita"><apiname>TMultimodeETelV3Api</apiname></xref>, and <xref href="GUID-9CE46AD7-722E-3831-A359-C90A350E931D.dita"><apiname>TMultimodeETelV4Api</apiname></xref> define

    91 flags for additional functional areas defined in later releases. </p> <p>Functional

    92 areas have individual query functions that offer detailed capability information

    93 on that area. For example, <xref href="GUID-9CE46AD7-722E-3831-A359-C90A350E931D.dita"><apiname>RMobilePhone::GetMultimodeCaps()</apiname></xref> queries

    94 for the phone's supported modes. </p> <p><b>Example </b> </p> <p>The following code tests if the TSY supports multimode

    95 telephony API at all, by querying using the <xref href="GUID-9CE46AD7-722E-3831-A359-C90A350E931D.dita"><apiname>KETelExtMultimodeV1</apiname></xref> flag.

    96 If multimode is supported, then other flags can be used to query for support

    97 for particular areas. </p> <p>The code assumes <codeph>iTsyName</codeph> holds

    98 the name of the TSY in use. </p> <codeblock id="GUID-6EE6B824-942D-573E-8197-96DB4D5A483B" xml:space="preserve">TInt funcFlags = KETelExtMultimodeV1;

    21 </codeblock> <p><b>Notes </b> </p> <p>Some <xref href="GUID-9CE46AD7-722E-3831-A359-C90A350E931D.dita"><apiname>TMultimodeETelV1Api</apiname></xref> flags specify areas common to all modes, others to particular modes. </p> </section> <section id="GUID-BAF464B8-6CFA-5FCB-B488-CD02CD187465"><title>Multimode phone number</title> <p>A phone number for use with the multimode telephony is stored as a <xref href="GUID-9CE46AD7-722E-3831-A359-C90A350E931D.dita"><apiname>RMobilePhone::TMobileAddress</apiname></xref> object. This has a buffer that stores the phone number and flags indicating the type of number for example national, international and network specific. It also stores the numbering plan for example national, ISDN and telex formats in which the number is stored. </p> <p><b>Example </b> </p> <p>The following code creates an address object to store an international phone number, formatted using the national number plan. In this example the UK representation of a Swedish number is used. </p> <codeblock id="GUID-77D958D7-0194-5F69-AF3E-6D6B98EA8D23" xml:space="preserve">RMobilePhone::TMobileAddress address;

   103 </codeblock> <p><b>Notes </b> </p> <p>Some <xref href="GUID-9CE46AD7-722E-3831-A359-C90A350E931D.dita"><apiname>TMultimodeETelV1Api</apiname></xref> flags

   104 specify areas common to all modes, others to particular modes. </p> </section>

   105 <section id="GUID-BAF464B8-6CFA-5FCB-B488-CD02CD187465"><title>Multimode phone

   106 number</title> <p>A phone number for use with the multimode telephony is stored

   107 as a <xref href="GUID-9CE46AD7-722E-3831-A359-C90A350E931D.dita"><apiname>RMobilePhone::TMobileAddress</apiname></xref> object.

   108 This has a buffer that stores the phone number and flags indicating the type

   109 of number for example national, international and network specific. It also

   110 stores the numbering plan for example national, ISDN and telex formats in

   111 which the number is stored. </p> <p><b>Example </b> </p> <p>The following code creates an address object to store

   112 an international phone number, formatted using the national number plan. In

   113 this example the UK representation of a Swedish number is used. </p> <codeblock id="GUID-77D958D7-0194-5F69-AF3E-6D6B98EA8D23" xml:space="preserve">RMobilePhone::TMobileAddress address;

    26 </codeblock> </section> </conbody></concept>

   118 </codeblock> </section>

   119 </conbody></concept>