<?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 &lt;bold&gt;not&lt;/bold&gt; 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 &lt;e32base.h&gt;
#include &lt;Etel3rdParty.h&gt;

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-&gt;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-&gt;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-&gt;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-&gt;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-&gt;CancelAsync(---Insert cancellation code--- );
    }</codeblock> </li>
</ul> </postreq>
</taskbody></task>