<?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-E6B77879-DA27-5D8C-B72D-A165F80CFF3B" xml:lang="en"><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>           Multimode ETel component architecture          </title>
<image href="GUID-E55B3ACD-4651-5FBD-AC9F-511E5CBCC0C9_d0e50545_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 id="GUID-68CA7D2A-AB2E-4ADC-9286-337D6D15D34F"><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>              Multimode ETel key classes            </title>
<image href="GUID-9147F8AF-01B3-5110-8FE7-A6318B5048D9_d0e50566_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. <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;
TBool result = EFalse;
iTelServer.IsSupportedByModule(iTsyName, funcFlags, result);
if (result)
    // if MM supported...
</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;
_LIT(KANumber, "+46 123 4567");
address.iTelNumber = KANumber;    
address.iTypeOfNumber = RMobilePhone::EInternationalNumber;
address.iNumberPlan = RMobilePhone::ENationalNumberPlan;
</codeblock> </section>
</conbody></concept>