<?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-30C8FE14-00CA-5B7F-9970-30E9632F00A6" xml:lang="en"><title>Call

Status and Call Control Tutorial</title><shortdesc>This tutorial describes how to manipulate the call status and control

call information. </shortdesc><prolog><metadata><keywords/></metadata></prolog><taskbody>

<context><p>The two diagrams below show the call state transitions for: </p> <ul>

<li id="GUID-0E180A6C-517F-57F3-AC24-ECA8E2483B6A"><p>outbound calls or Mobile

Originated (MO) calls </p> </li>

<li id="GUID-C34D2BE3-8A92-59B2-8A71-7919D0525328"><p>inbound calls or Mobile

Terminated (MT) calls </p> </li>

</ul> <fig id="GUID-4BE26EDE-C073-5F33-AD39-D1659B3D936A">

<title>              MO call state diagram            </title>

<image href="GUID-F041E4F2-AAA3-5C8C-B8C6-646974DEF76E_d0e49420_href.png" placement="inline"/>

</fig> <fig id="GUID-D9D38F90-FB12-5B14-8AAB-C1A305D11948">

<title>              MT call state diagram            </title>

<image href="GUID-04B1D977-EE3F-5EC6-B1C7-68F6E4C801E2_d0e49428_href.png" placement="inline"/>

</fig><p><xref href="GUID-7B623041-5DB3-3EF6-AAF4-5AA89B519855.dita"><apiname>RMobileCall</apiname></xref> provides the functions to manipulate

and control call actions. 

</p><p> The high level steps to use the call control information are: 

</p> </context>

<steps id="GUID-2AFAD0AA-C0DB-5E8F-9754-43A26EAF026A">

<step id="GUID-4A98A960-296F-589F-9FB8-8C8BE3436FF0"><cmd>Use <xref href="GUID-7B623041-5DB3-3EF6-AAF4-5AA89B519855.dita"><apiname>RMobileCall::GetMobileCallCaps()</apiname></xref> to get the

dynamic call control and call event capabilities. </cmd>

<info>The call control capabilities are dynamic and can change with the status

of the active call and calls. The capabilities also depend on the network

and the subscription of the user. </info>

</step>

<step id="GUID-9D344B64-982A-5DD4-9B26-859A8B37E903"><cmd>Use <xref href="GUID-7B623041-5DB3-3EF6-AAF4-5AA89B519855.dita"><apiname>RMobileCall::NotifyMobileCallCapsChange()</apiname></xref> to

get the notification of the capability changes. </cmd>

</step>

<step id="GUID-B2F48CCB-297E-5150-BED8-F38F8600B3D9"><cmd>Use <xref href="GUID-7B623041-5DB3-3EF6-AAF4-5AA89B519855.dita"><apiname>RMobileCall::GetMobileCallStatus()</apiname></xref> to

get the call status. </cmd>

</step>

<step id="GUID-9A58C0FC-20FE-5836-8DAE-4B26911BB653"><cmd>Use <xref href="GUID-7B623041-5DB3-3EF6-AAF4-5AA89B519855.dita"><apiname>RMobileCall::NotifyMobileCallStatusChange()</apiname></xref> to

get the notification of call status changes. </cmd>

</step>

<step id="GUID-5830289C-4978-59D1-BFC8-D835CCB5D142"><cmd>Use <xref href="GUID-7B623041-5DB3-3EF6-AAF4-5AA89B519855.dita"><apiname>RMobileCall::NotifyCallEvent()</apiname></xref> to

get the notification of call events. </cmd>

</step>

<step id="GUID-9566472C-A341-5D94-B197-859DBC7A3BAD"><cmd>Use <xref href="GUID-7B623041-5DB3-3EF6-AAF4-5AA89B519855.dita"><apiname>RMobileCall::Hold()</apiname></xref> to

put a call on hold. </cmd>

</step>

<step id="GUID-611A978B-43B6-50AD-98CE-F8A536837F7E"><cmd>Use <xref href="GUID-7B623041-5DB3-3EF6-AAF4-5AA89B519855.dita"><apiname>RMobileCall::Resume()</apiname></xref> to

resume a call from hold. </cmd>

</step>

<step id="GUID-9CDC62D0-5284-5AA9-A45A-7458872B04A6"><cmd>Use <xref href="GUID-7B623041-5DB3-3EF6-AAF4-5AA89B519855.dita"><apiname>RMobileCall::Swap()</apiname></xref> to

swap between a call on hold and an active call. </cmd>

</step>

<step id="GUID-C9CA5D70-4009-5220-89B8-87D9CFD3431C"><cmd>Use <xref href="GUID-7B623041-5DB3-3EF6-AAF4-5AA89B519855.dita"><apiname>RMobileCall::Deflect()</apiname></xref> to

divert an incoming call to another destination. </cmd>

</step>

<step id="GUID-6EE40A86-E04C-587B-BC94-90ED69BB8E44"><cmd>Use <xref href="GUID-7B623041-5DB3-3EF6-AAF4-5AA89B519855.dita"><apiname>RMobileCall::Transfer()</apiname></xref> to

transfer a call to another user. </cmd>

</step>

<step id="GUID-A031E802-B369-5A7F-80DF-19D39A0CAB14"><cmd>Use <xref href="GUID-7B623041-5DB3-3EF6-AAF4-5AA89B519855.dita"><apiname>RMobileCall::GoOneToOne()</apiname></xref> to

transfer the call to one user of a conference call. </cmd>

</step>

</steps>

<example><title>Call control example</title> <p>The following code declares

an enumeration that lists the various call control commands, and provides

a switch function that carries out the specified command. </p> <codeblock id="GUID-88C9CE8E-1F05-5B22-B800-ACF3646CE69A" xml:space="preserve">/// Call control commands

enum TCallControlCommand

    {

    EPutOnHold,            // Put call on hold

    EResumeHeld,        // Resume on hold call

    ESwapHoldAndOngoing,// Swap an on-hold and an ongoing call

    EDeflectIncoming,    // Redirect an incoming call

    ETransferToRemote,    // Transfer one call to remote party of another call

    EConferenceOneToOne // Go "one-to-one" within a conference call

    };

// Execute a call control command

void CClientApp::CallControlL(RMobileCall& aCall, TCallControlCommand aCommand, TRequestStatus& aStatus)

    {

    // Get call capabilities to check can execute command

    RMobileCall::TMobileCallCapsV1 callCaps;

    RMobileCall::TMobileCallCapsV1Pckg callCapsPckg(callCaps);

    User::LeaveIfError(aCall.GetMobileCallCaps(callCapsPckg));

    switch (aCommand)

        {

        case EPutOnHold:

            if (callCaps.iCallControlCaps & RMobileCall::KCapsHold)

             {

                aCall.Hold(aStatus);

             } 

        break;

        case EResumeHeld:

             if (callCaps.iCallControlCaps & RMobileCall::KCapsResume)

            {

                aCall.Resume(aStatus);

            }

        break;

        case ESwapHoldAndOngoing:

            if (callCaps.iCallControlCaps & RMobileCall::KCapsSwap)

            {

                aCall.Swap(aStatus);

            }    

        break;

        case EDeflectIncoming:

            if (callCaps.iCallControlCaps & RMobileCall::KCapsDeflect)

            {

                aCall.Deflect(aStatus, RMobileCall::EDeflectRegisteredNumber, RMobilePhone::TMobileAddress());

            }    

        break;

        case ETransferToRemote:

            if (callCaps.iCallControlCaps & RMobileCall::KCapsTransfer)

            {

                aCall.Transfer(aStatus);

            }

        break;

        case EConferenceOneToOne:

            if (callCaps.iCallControlCaps & RMobileCall::KCapsOneToOne)

            {

                aCall.GoOneToOne(aStatus);

            }

        break;

        default:

        break;

        };

    };</codeblock> </example>

</taskbody></task>