<?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 task

  PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">

<task id="GUID-130C21D7-0A39-5A54-8545-C82B2ED4398C" xml:lang="en"><title>Simultaneous

Call Tutorial</title><shortdesc>This tutorial describes how to handle two call with the telephony

API for applications. </shortdesc><prolog><metadata><keywords/></metadata></prolog><taskbody>

<context id="GUID-02566DCB-EFC4-4C74-A9FD-98417AC0AF9D"><p>This state diagram shows how to dial or answer one or two calls

at a time. </p> <fig id="GUID-3603A3BF-5E3F-5945-B762-42411EF4B497">

<title>              Simultaneous Call State Diagram            </title>

<image href="GUID-7E6634DC-7F07-5687-AFEE-D5BD268B8E1D_d0e61445_href.png" placement="inline"/>

</fig> <p>The boxes are states. The enumeration value in each box is the status

of the voice line. <xref href="GUID-0DA6722B-0700-5612-884A-F3B7733E5252.dita">Voice

line status</xref> describes these states and their meaning. The arrows show

events that trigger a change of state. In these events, a word in <b>bold</b> indicates

a <xref href="GUID-97D402C8-B4B7-385A-92B3-D3FCC0CA575A.dita"><apiname>CTelephony</apiname></xref> method that you can call. </p> </context>

<steps id="GUID-20511421-E888-5AA6-8C8A-8B03AF9532EA">

<step id="GUID-207F7101-D6BC-54B3-A6FD-BE4FA0C44CE4"><cmd/>

<substeps id="GUID-3C223BD1-B3D3-54BF-9CE2-4CF0397C26A6">

<substep id="GUID-D333CDDA-E565-5009-BB68-364FDFAEE537"><cmd/>

<info>check the <xref href="GUID-0DA6722B-0700-5612-884A-F3B7733E5252.dita">Voice

line status</xref> for other calls </info>

<info><ul>

<li id="GUID-6E5035AE-AA11-5D46-A6FA-FCFF600C3964"><p>if the line is <i>Idle</i> (<xref href="GUID-97D402C8-B4B7-385A-92B3-D3FCC0CA575A.dita#GUID-97D402C8-B4B7-385A-92B3-D3FCC0CA575A/GUID-52E51C0C-8C27-311D-8B6B-223F899DB2C9"><apiname>CTelephony::EStatusIdle</apiname></xref>)

then no calls are in progress </p> </li>

<li id="GUID-0B35A0D6-2BB1-54ED-A562-653031ECBE91"><p>if the line is <i>on

hold</i> (<xref href="GUID-97D402C8-B4B7-385A-92B3-D3FCC0CA575A.dita#GUID-97D402C8-B4B7-385A-92B3-D3FCC0CA575A/GUID-7F347F6A-0B02-34BC-B082-3449EA63A148"><apiname>CTelephony::EStatusHold</apiname></xref>) then there is another

call in progress, but it is on hold and you can still dial or answer a second

call. Now go to point four below </p> </li>

<li id="GUID-A939F59B-59A4-56CE-8949-5DE28588EE57"><p>if another call is active,

you must wait until it completes before you can dial or receive a call. </p> </li>

</ul> </info>

</substep>

<substep id="GUID-DEF3414F-6836-57E2-96A9-6E824696F29A"><cmd/>

<info> <xref href="GUID-05759C1B-6731-52A1-8EC0-2570E01FC7BC.dita"> Dial a call</xref>  </info>

<info>while no calls are in progress, the line's status is <xref href="GUID-97D402C8-B4B7-385A-92B3-D3FCC0CA575A.dita#GUID-97D402C8-B4B7-385A-92B3-D3FCC0CA575A/GUID-52E51C0C-8C27-311D-8B6B-223F899DB2C9"><apiname>CTelephony::EStatusIdle</apiname></xref>.

To dial a call, use <xref href="GUID-97D402C8-B4B7-385A-92B3-D3FCC0CA575A.dita#GUID-97D402C8-B4B7-385A-92B3-D3FCC0CA575A/GUID-E7A25EB6-B7FD-31DF-9A03-F100F93D7138"><apiname>CTelephony::DialNewCall()</apiname></xref>. If dialling

was successful and the remote party answers the call then the line's status

will become <xref href="GUID-97D402C8-B4B7-385A-92B3-D3FCC0CA575A.dita#GUID-97D402C8-B4B7-385A-92B3-D3FCC0CA575A/GUID-641B7EAB-56C6-3E9C-A53C-EE382925E1CE"><apiname>CTelephony::EStatusConnected</apiname></xref>. </info>

</substep>

<substep id="GUID-1D1F2233-367B-57E7-B4A5-A36CD4C53C8C"><cmd/>

<info> <xref href="GUID-D6334249-E61D-55E7-9D0E-95231DC3621F.dita">Answer a call</xref>  </info>

<info>while no calls are in progress, the line's status is <xref href="GUID-97D402C8-B4B7-385A-92B3-D3FCC0CA575A.dita#GUID-97D402C8-B4B7-385A-92B3-D3FCC0CA575A/GUID-52E51C0C-8C27-311D-8B6B-223F899DB2C9"><apiname>CTelephony::EStatusIdle</apiname></xref>.

When a remote party calls your phone, the voice line's status will change

to <xref href="GUID-97D402C8-B4B7-385A-92B3-D3FCC0CA575A.dita#GUID-97D402C8-B4B7-385A-92B3-D3FCC0CA575A/GUID-7632FB7B-0272-39CB-B71A-C3C09EEB5E88"><apiname>CTelephony::EStatusRinging</apiname></xref>. </info>

<info>When the status is <codeph>CTelephony::EStatusRinging</codeph>, use <xref href="GUID-97D402C8-B4B7-385A-92B3-D3FCC0CA575A.dita#GUID-97D402C8-B4B7-385A-92B3-D3FCC0CA575A/GUID-6D12DBA4-8902-3649-B144-47C91F16C4B3"><apiname>CTelephony::AnswerIncomingCall()</apiname></xref> to

answer the call. The status will change to <xref href="GUID-97D402C8-B4B7-385A-92B3-D3FCC0CA575A.dita#GUID-97D402C8-B4B7-385A-92B3-D3FCC0CA575A/GUID-641B7EAB-56C6-3E9C-A53C-EE382925E1CE"><apiname>CTelephony::EStatusConnected</apiname></xref> and

the phone user can talk to the remote party. </info>

</substep>

<substep id="GUID-A96B6019-65E1-5D10-9639-0F2D65E8FAE1"><cmd/>

<info> <xref href="GUID-91082AAB-DC8D-5AEA-A6C1-DD89932244FB.dita">Terminate the

call</xref> </info>

</substep>

<substep id="GUID-C60ABD8F-C3D0-51F6-9A31-C1A9CDA27B24"><cmd/>

<info>detect <xref href="GUID-42B10CBF-D45A-580F-A639-E2495FF3B4F3.dita">Remote

Termination</xref> of a call </info>

</substep>

<substep id="GUID-EF4ECB49-F37F-54C7-96C8-9105D54AEA43"><cmd/>

<info> <xref href="GUID-1907CF0B-2F4B-50F6-B676-7B7059B7FF74.dita">Hold a Call</xref>  </info>

</substep>

<substep id="GUID-BB6D7BB5-4BEF-5D4D-B763-2EA7E8828D0F"><cmd/>

<info> <xref href="GUID-FFBD95C6-0B12-5FD7-BA69-89BBFB97F0A1.dita">Resume a call</xref>  </info>

</substep>

<substep id="GUID-75078A44-B3EE-50CB-A746-C79D78228398"><cmd/>

<info> <xref href="GUID-9C5A86D2-E602-55AE-B54B-8511E70CD23D.dita">Send DTMF tones

down the line</xref>  </info>

</substep>

<substep id="GUID-4B8ED301-CAA2-5629-A697-73E6E0122F5E"><cmd/>

<info> <xref href="GUID-0DA6722B-0700-5612-884A-F3B7733E5252.dita">Line and call

information</xref>  </info>

</substep>

<substep id="GUID-8CB212E7-2B55-580E-9DD4-D5A1694B94FA"><cmd/>

<info> <xref href="GUID-D6334249-E61D-55E7-9D0E-95231DC3621F.dita#GUID-D6334249-E61D-55E7-9D0E-95231DC3621F/GUID-19AC29A6-3A34-57E8-A0BE-8242CF60BF86">Answer

a second call</xref>  </info>

<info>at some point, a remote party might try to ring your phone. It is answered

in the same way as the first </info>

<info>The voice line state will change to <xref href="GUID-97D402C8-B4B7-385A-92B3-D3FCC0CA575A.dita#GUID-97D402C8-B4B7-385A-92B3-D3FCC0CA575A/GUID-7632FB7B-0272-39CB-B71A-C3C09EEB5E88"><apiname>CTelephony::EStatusRinging</apiname></xref>.

You can receive notification when this occurs; see <xref href="GUID-D6334249-E61D-55E7-9D0E-95231DC3621F.dita">Detect

an incoming call</xref>. Before answering the second call, you must put the

original call on hold. This is shown in the diagram above. </info>

</substep>

<substep id="GUID-E4B328AF-66D5-5E21-BF74-7057D58694E6"><cmd/>

<info> <xref href="GUID-05759C1B-6731-52A1-8EC0-2570E01FC7BC.dita#GUID-05759C1B-6731-52A1-8EC0-2570E01FC7BC/GUID-8A1C0CE1-31F8-5B78-9FDC-D2BF46B2924F">Dial

a second call</xref>  </info>

<info>you can also dial a second call in the same way as the first. Once again,

you must put your original call on hold before dialling the second call </info>

</substep>

<substep id="GUID-B8904540-FBA9-5351-B298-11681E3C9AA9"><cmd/>

<info>a <xref href="GUID-97D402C8-B4B7-385A-92B3-D3FCC0CA575A.dita#GUID-97D402C8-B4B7-385A-92B3-D3FCC0CA575A/GUID-86D48DF2-1AA1-337A-A270-6703FF29C958"><apiname>CTelephony::TCallId</apiname></xref> will be given to you when you

successfully connect a second call. You will also have a <codeph>CTelephony::TCallId</codeph> from

the first call. Now you will be the owner of two calls: at any one time, one

will always be active and one will always be on hold. </info>

<info>Now you can: </info>

<info><ul>

<li id="GUID-B1B06B62-725A-5ACC-92AB-169F8C83EF2F"><p> <xref href="GUID-91082AAB-DC8D-5AEA-A6C1-DD89932244FB.dita">Terminate

either call</xref>. If you terminate the <b>active</b> call then you will

be left with a call on hold. If you terminate the <b>on-hold</b> call then

you will be left with an active call. </p> </li>

<li id="GUID-590E8FC0-A09F-5CE5-BAE4-958439E35968"><p> <xref href="GUID-42B10CBF-D45A-580F-A639-E2495FF3B4F3.dita">Detect

remote party terminating either call</xref>. Once again, if the <b>active</b> call

ends then you will be left with a call on hold and vice versa. </p> </li>

<li id="GUID-1638D67F-33E6-50EA-A122-FA54D08E6213"><p> <xref href="GUID-E2D4973C-FE93-5DE7-B04E-19B7701621C3.dita">Swap

held and active calls</xref>. </p> </li>

</ul> </info>

</substep>

</substeps>

</step>

</steps>

</taskbody><related-links>

<link href="GUID-6ABEF478-F3DB-524E-A500-9431B42C6665.dita"><linktext>Single Call

                Tutorial</linktext></link>

</related-links></task>