<?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-87CD8C58-F6B9-5D6B-9D7B-862979DE3B6F" xml:lang="en"><title>Notification

Request Tutorial</title><shortdesc>This tutorial describes how to receive notification of the events

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

<context id="GUID-1EA31B19-BBB0-5723-9896-66666FEABC1D"><p> <xref href="GUID-97D402C8-B4B7-385A-92B3-D3FCC0CA575A.dita"><apiname>CTelephony</apiname></xref> can

notify the client applications about the status changes to the events like: </p> <ul>

<li id="GUID-180B5C84-9ECB-55FE-8B9E-E84ED56C32A3"><p>to detect inbound calls </p> </li>

<li id="GUID-8305981A-F9B6-52EC-97F1-CF74C0238315"><p>to detect the phone

charger connection </p> </li>

<li id="GUID-F0140C6D-2A85-587B-91BB-C432918518AF"><p>battery charge information </p> </li>

</ul> <p>The client applications can get the notification of the events that

contain a <b>notification event</b>, an <b>information class</b> and a <b>cancellation

code</b>. For example, the <xref href="GUID-0DA6722B-0700-5612-884A-F3B7733E5252.dita">Voice

Line Status</xref> event describes that the client applications can receive

the notification when it changes. The event description contains: </p> <table id="GUID-603AF473-FC6E-52FE-A2B7-CA4211A0D9BF">

<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>

<thead>

<row>

<entry>Item</entry>

<entry>Description</entry>

</row>

</thead>

<tbody>

<row>

<entry><p> <xref href="GUID-97D402C8-B4B7-385A-92B3-D3FCC0CA575A.dita"><apiname>CTelephony::EVoiceLineStatusChange</apiname></xref>  </p> </entry>

<entry><p>notification event </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-97D402C8-B4B7-385A-92B3-D3FCC0CA575A.dita"><apiname>CTelephony::TCallStatus</apiname></xref>  </p> </entry>

<entry><p>information class </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-97D402C8-B4B7-385A-92B3-D3FCC0CA575A.dita"><apiname>CTelephony::EVoiceLineStatusChangeCancel</apiname></xref>  </p> </entry>

<entry><p>cancellation code </p> </entry>

</row>

</tbody>

</tgroup>

</table> </context>

<steps id="GUID-0A66184A-7434-5CA1-B4A6-D07BB52AB6A9">

<step id="GUID-78BA430F-A345-52AC-833A-FE170FEAF79A"><cmd/>

<info>create an instance of <xref href="GUID-97D402C8-B4B7-385A-92B3-D3FCC0CA575A.dita"><apiname>CTelephony</apiname></xref> </info>

<stepxmp><codeblock id="GUID-8E9E0D08-7AB5-537F-880E-8342F38BA6C4" xml:space="preserve">CTelephony* telephonyApi = CTelephony::NewL();

CleanupStack::PushL( telephonyApi );</codeblock> </stepxmp>

</step>

<step id="GUID-570A8873-7F1E-5569-9791-9F530FE03520"><cmd/>

<info>create an instance of the class, passing it the pointer to <xref href="GUID-97D402C8-B4B7-385A-92B3-D3FCC0CA575A.dita"><apiname>CTelephony</apiname></xref> </info>

<stepxmp><codeblock id="GUID-901E03A3-028E-5B2D-B336-3CD1E309F692" xml:space="preserve">CNotifyExample *exampleObject = new CNotifyExample( telephonyApi );

CleanupStack::PushL( exampleObject );</codeblock> </stepxmp>

</step>

<step id="GUID-CC391D40-F006-5874-95EF-36683EE2180B"><cmd/>

<info>call the object's <codeph>RequestNotification</codeph> method to start

the request. This calls <xref href="GUID-97D402C8-B4B7-385A-92B3-D3FCC0CA575A.dita"><apiname>CTelephony::NotifyChange()</apiname></xref>  </info>

<stepxmp><codeblock id="GUID-EFC8D54E-B490-5E5E-A742-8E0796CA48BE" xml:space="preserve">exampleObject-&gt;RequestNotification();</codeblock> </stepxmp>

<info>pass the notification event and an empty instance of the information

class. This method starts an asynchronous operation that completes when the

requested notification event occurs </info>

<info>The new status will have been written into the <codeph>TCallStatus</codeph> object

that was given to <codeph>NotifyChange()</codeph>  </info>

</step>

<step id="GUID-34EEDBDE-BA17-5261-8B22-222AAA95D3E2"><cmd/>

<info>you can see all the notification events in <xref href="GUID-97D402C8-B4B7-385A-92B3-D3FCC0CA575A.dita"><apiname>CTelephony::TNotificationEvent</apiname></xref>.

This also shows which information class is associated with each event </info>

</step>

<step id="GUID-BC613CF8-E088-55CF-A721-420B6ADC70FD"><cmd/>

<info>you can cancel a request for notification any time before the operation

finished. Do this by passing <xref href="GUID-97D402C8-B4B7-385A-92B3-D3FCC0CA575A.dita"><apiname>CTelephony::CancelAsync()</apiname></xref> the

cancellation code </info>

<info><p><note> You should not request notification before the  previous notification

request is either completed or cancelled. The notification request is started

after the active object is created, so there could not be a request. If you

are <bold>not</bold> sure that previous requests for that object have

completed, call the<xref href="GUID-067293BF-B28C-3CEC-92F4-1351A795EA7F.dita#GUID-067293BF-B28C-3CEC-92F4-1351A795EA7F/GUID-0BEA3D01-369A-3ED4-A8DB-22D3B1A11C97"><apiname>CActive::Cancel</apiname></xref> method before issuing

a new request:<codeblock xml:space="preserve">exampleObject-&gt;Cancel();exampleObject-&gt;RequestNotification();</codeblock> 

This will cancel any previous requests.</note></p></info>

</step>

</steps>

<example id="GUID-6366AAAA-6C55-517C-B702-420730097399"><title>Voice line

status example</title> <p>Here is an active object that detects a change in

voice line status. It doesn't do much when the voice line status changes;

it simply stores the new status values and then starts the next asynchronous

operation. </p> <p>This is a basic <xref href="GUID-890F06C6-DE32-5EB1-BF0F-D41794F47AE1.dita">Active

Object</xref>. You will need to know about active objects in order to use <codeph>CTelephony</codeph>'s

notification abilities. </p> <codeblock id="GUID-86411553-8C98-5D4E-BBC5-5F7F3C8D8D91" xml:space="preserve">

 /*

   Example CTelephony Notification

   This class uses the CTelephony API to get notification when a

   phone's voice line status changes.

   This class is an active object.  You will need to have knowledge of

   active objects in order to understand this class.  All active

   object are derived from CActive.

   This program can be easily modified to get notification when other

   events occur.

   See CTelephony::TNotificationEvent for a list of

   events.

   */

#include <e32base.h>

#include <Etel3rdParty.h>

class CNotifyExample : public CActive

{

 public:

    // Constructor/Destructor

    CNotifyExample( CTelephony* aTelephony );

    // Request voice line status change notification

    void RequestNotification();

 private:

    /*

    These are the pure virtual methods from CActive that

    MUST be implemented by all active objects

    */

    void RunL();

    void DoCancel();

 private:

    /*

    A reference to a CTelephony, obtained with CTelephony::NewL()

    or NewLC()

    */

    CTelephony* iTelephony;

    /*

    When the voice line status changes (and hence the asynchronous

    operation completes) the new voice line status is written into

    iLineStatus. Until this point, iLineStatus is not valid.

    If you change this class to get notification of other events,

    then change this class. CTelephony::TNotificationEvent lists

    the classes associated with each event.

    */

    CTelephony::TCallStatusV1 iLineStatus;

    CTelephony::TCallStatusV1Pckg iLineStatusPckg;

};

/*

   Default constructor.  Pass it a reference to a CTelephony, created

   with CTelephony::NewL() or NewLC()

   */

CNotifyExample::CNotifyExample(CTelephony* aTelephony): CActive( EPriorityStandard ), iTelephony( aTelephony ), iLineStatusPckg( iLineStatus )

    {

        //default constructor

        iLineStatus.iStatus = CTelephony::EStatusUnknown;

    }

/*

   This method requests notification by calling

   CTelephony::NotifyChange() to initialise an asynchronous operation.

   Then it immediately calls CActive::SetActive to start the

   operation.  The operation completes when the notification event

   occurs.

   In this case, we tell CTelephony to wait for the

   CTelephony::EVoiceLineStatusChange notification event, hence the

   event occurs when the voice line status changes.

   For other events, change the notification event in the call to

   CTelephony::NotifyChange().  The CTelephony::TNotificationEvent

   description  all the notification events.

   It also list the information class to

   pass to CTelephony::NotifyChange().  The TCallStatus

   class is associated with CTelephony::EVoiceLineStatusChange.

   */

void CNotifyExample::RequestNotification()

    {

    /*

    Panic if this object is already performing an asynchronous

    operation

          */

    _LIT( KNotifyExamplePanic, "CNotifyExample" );

    __ASSERT_ALWAYS( !IsActive(), User::Panic( KNotifyExamplePanic, 1 ));

    iTelephony->NotifyChange( iStatus, CTelephony::EVoiceLineStatusChange, iLineStatusPckg );

    SetActive();

    }

/*

   The active object's RunL method is called when the asynchronous

   event completes.  In this case, RunL is called when the voice line

   status changes.  When this occurs, the new voice line status is

   written to the iLineStatus.  iLineStatus was passed to

   CTelephony::NotifyChange() when the asynchronous operation was

   started.

   This is where you put your code to respond to your chosen

   notification event.

   In all active objects, iStatus indicates whether the asynchronous

   operation succeeded, failed, or is still in progress.  KErrNone

   indicates success, and hence the value in iStatus is valid.

   */

void CNotifyExample::RunL()

    {

    if( iStatus==KErrNone )

        {

        /*

        Insert code to respond to the change of voice line status

        here.  A typical use to answer a call if the voice line

        status is 'ringing' (EStatusRinging)

        Remember that you must implement a RunError() method if

        your code in RunL can leave.

        */

            if( iLineStatus.iStatus == CTelephony::EStatusRinging ); // Answer call by calling 'AnswerIncomingCall()'

            {

            /* Request the next notification */

            iTelephony->NotifyChange( iStatus, CTelephony::ESignalStrengthChange, iLineStatusPckg );

            SetActive();

            }

        }

    }

/*

   Like all active objects, you must supply a DoCancel() method to

   cancel the asynchronous operation.  This must cancel a CTelephony

   notification operation with CTelephony::CancelAsync.  Give the method

   the appropriate 'cancellation event' from those in 'TCancellationRequest'

   In this case, we are cancelling the "voice line status Change" event,

   and so we need to supply the EVoiceLineStatusChange cancellation code.

   If you change this class to respond to a different notification

   event, remember to change the call to CTelephony::CancelAsync.

   */

void CNotifyExample::DoCancel()

    {

        iTelephony->CancelAsync( CTelephony::EVoiceLineStatusChangeCancel );

    }  </codeblock> </example>

<postreq id="GUID-CD5428AA-DCE8-5BEA-AEC4-7A159853EF76"><p><b>Receive notification of other events </b> </p> <p>The previous examples

detect changes in voice line status. You can adapt this example for other

events as follows: </p> <ul>

<li id="GUID-BC170E42-C666-5882-AA89-13804DC9B28E"><p>In the <codeph>RequestNotification()</codeph> method,

pass <xref href="GUID-97D402C8-B4B7-385A-92B3-D3FCC0CA575A.dita"><apiname>CTelephony::NotifyChange()</apiname></xref> the <b>notification

event</b> you want to detect, listed in <xref href="GUID-97D402C8-B4B7-385A-92B3-D3FCC0CA575A.dita"><apiname>CTelephony::TNotificationEvent</apiname></xref>.

Each event has an <b>information class</b> associated with it, which stores

the new information after it has changed. Pass <codeph>NotifyChange()</codeph> an

instance of the information class, too: </p> <codeblock id="GUID-D7A25EFA-D6C0-5EE3-965E-795F6DD99FF6" xml:space="preserve">CNotifyExample::RequestNotification()

    {

    _LIT( KNotifyExamplePanic, "CNotifyExample" );

    __ASSERT_ALWAYS( !IsActive(), User::Panic( KNotifyExamplePanic, 1 ));

    iTelephony->NotifyChange( iStatus, 

                              ---Insert notification event---

                              ---Insert packaged information class instance--- );

    SetActive();

    }</codeblock> <p>You will need to declare the information class instance

in the <codeph>CNotifyExample</codeph>'s declaration. </p> </li>

<li id="GUID-FE3772D6-9624-528F-BDDD-0B474466CB0E"><p>Change the code in <codeph>CNotifyExample::RunL</codeph> that

handles the event. </p> </li>

<li id="GUID-F104AF0D-D6AC-5052-9A96-010B49D5C600"><p>Change the <codeph>DoCancel</codeph> method

to cancel the correct event. Insert the correct <b>cancellation code</b> from

those in <xref href="GUID-97D402C8-B4B7-385A-92B3-D3FCC0CA575A.dita"><apiname>CTelephony::TCancellationRequest</apiname></xref>: </p> <codeblock id="GUID-2E58B2CD-BC95-5C79-86D9-0EC6EA81C9AF" xml:space="preserve">CNotifyExample::DoCancel()

    {

    iTelephony->CancelAsync(---Insert cancellation code--- );

    }</codeblock> </li>

</ul> </postreq>