<?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-6ABEF478-F3DB-524E-A500-9431B42C6665" xml:lang="en"><title>Single

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

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

<context id="GUID-CF841B4F-0F62-5933-AD58-0A0593980732"><p>This state diagram

shows how to dial or answer one call at a time. It presumes there are no other

calls being made. </p> <fig id="GUID-5735A736-7536-507E-92CC-8A766D8B8F66">

<title>              Single Call State Diagram            </title>

<image href="GUID-A2EFD9AD-F230-545C-8C5D-193F717B9FE2_d0e34881_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 the states and their meaning. You can also find

the status of individual calls. The line state and the call state are the

same in a single call. </p> <p>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-6399570A-7FAF-5709-91B9-2168145F7F6C">

<step id="GUID-30E27A7D-0792-5B77-AEE5-189A681CDDA0"><cmd/>

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

line status</xref>  </info>

<substeps id="GUID-12C8410C-2874-4502-B046-39EC0DC0E696">

<substep id="GUID-27EC866D-B7B3-4305-9996-404B51378BE5"><cmd/>

<info>if the line is Idle(<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>) no calls

are in progress </info>

</substep>

<substep id="GUID-FF977DFD-6547-4FD6-B1B6-04D3F7E31ADC"><cmd/>

<info>if the line is on hold(<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 </info>

</substep>

<substep id="GUID-956106AF-B740-48B8-B474-5442BE357FD6"><cmd/>

<info>if a call is active, you must wait until it completes before you can

dial or receive a call. To detect when this occurs, see <xref href="GUID-87CD8C58-F6B9-5D6B-9D7B-862979DE3B6F.dita">Notification

Request Tutorial</xref>  </info>

</substep>

</substeps>

</step>

<step id="GUID-27A87414-B446-5C5D-BCBE-72F543062D67"><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 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>. </info>

<info>If successful and the remotes party answers the call then the line status

is <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>

</step>

<step id="GUID-2D16FAAD-3900-5313-9C45-4E7867BF4453"><cmd/>

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

<info>When no calls are in progress, the line 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>. </info>

<info>When a remote party calls your phone, the voice line 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 <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>, 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 changes 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>

</step>

<step id="GUID-7398BBDB-3EA9-5575-A04F-47292ADA05BD"><cmd/>

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

call</xref>  </info>

</step>

<step id="GUID-85EFB23C-DE86-5614-928F-A12ADF8E799E"><cmd/>

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

party call termination</xref>  </info>

</step>

<step id="GUID-28C01974-AB55-5AFC-A5CD-A5054AC06A51"><cmd/>

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

</step>

<step id="GUID-F3CA48F5-F03E-5CC5-BBCE-A1B3F122861C"><cmd/>

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

</step>

<step id="GUID-809085D2-7B65-5C40-88EA-E3619158D7F6"><cmd/>

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

</step>

</steps>

<result><p> When you successfully dial or answer a call, you will be given

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> the identifies the call. 

</p><p>A remote party might try to ring your phone. 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 ignore this

call. You can still terminate, hold, resume and send DTMF. 

</p></result>

</taskbody><related-links>

<link href="GUID-130C21D7-0A39-5A54-8545-C82B2ED4398C.dita"><linktext>Simultaneous

                Call Tutorial</linktext></link>