1 <?xml version="1.0" encoding="utf-8"?>

     2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

     3 <!-- This component and the accompanying materials are made available under the terms of the License 

     4 "Eclipse Public License v1.0" which accompanies this distribution, 

     5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

     6 <!-- Initial Contributors:

     7     Nokia Corporation - initial contribution.

     8 Contributors: 

     9 -->

    10 <!DOCTYPE task

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

    12 <task id="GUID-A12C6F14-5FFC-50BE-A837-5EA569C8AB52" xml:lang="en"><title>Telephony

    13 Watcher Tutorial </title><shortdesc>This tutorial describes how to use the telephony watchers in Symbian

    14 platform. </shortdesc><prolog><metadata><keywords/></metadata></prolog><taskbody>

    15 <context id="GUID-1BFC0D23-48B9-51EB-9AAD-B6CB285AFABD"><p>The telephony watchers

    16 provide the signal strength and the call indicator information to all the

    17 registered clients applications. The client application must register with

    18 the <xref href="GUID-FE910347-7CC1-5241-B443-88AD3F5A96EF.dita">Publish and Subscribe</xref> framework

    19 to receive the information. The telephony watchers enable the clients to retrieve

    20 information about network signal strength and call status. </p> </context>

    21 <steps id="GUID-B24B6C77-2F08-5250-8B60-3E30E6318EE6">

    22 <step id="GUID-5A0A8EED-700A-5B5C-955C-7130C6B736DE"><cmd>Create an instance

    23 of watchers </cmd>

    24 <info>If the watcher was started earlier, re-start them to reset the values. </info>

    25 </step>

    26 <step id="GUID-03A10CA1-D4D9-5690-AB0E-7AF972590F1C"><cmd>Create a handle

    27 to the publish and subscribe with RProperty::Attach(). </cmd>

    28 <info>Input the system category and the property key as the argument. The

    29 keys are defined in the system agent header <codeph>sacls.h</codeph>. Use <codeph>KUidCurrentCall</codeph> for

    30 call status and <codeph>KUidNetworkStatus</codeph> for network status information. </info>

    31 </step>

    32 <step id="GUID-D93E2115-84AE-5253-9C87-640E471A10BE"><cmd>Use <xref href="GUID-3791FC66-0A5E-3A55-96BB-E725EF3B96D5.dita#GUID-3791FC66-0A5E-3A55-96BB-E725EF3B96D5/GUID-8211769E-8E51-3F23-847E-DDDA3055A205"><apiname>RPropety::Subscribe()</apiname></xref> to

    33 subscribe to the property and use <xref href="GUID-C4776034-D190-3FC4-AF45-C7F195093AC3.dita#GUID-C4776034-D190-3FC4-AF45-C7F195093AC3/GUID-79308052-0AAC-3E6F-9597-5D1890572666"><apiname>RProperty::Get()</apiname></xref> to retrieve

    34 the updated information. </cmd>

    35 </step>

    36 <step id="GUID-6DCF841E-7CDB-5904-BD75-D7D7C74255F7"><cmd>The retrieved information

    37 can be displayed to the user. </cmd>

    38 </step>

    39 <step id="GUID-BB6E5967-CC50-5324-8EFA-E22558AE80D8"><cmd/>

    40 <info>Follow the steps 1 - 4 to retrieve the other value. </info>

    41 </step>

    42 </steps>

    43 <example id="GUID-13058B4E-5AA3-5C21-AD74-0B10215CF14B"><title>Watcher example</title> <p>The

    44 example code below describes how to retrieve the network signal status with

    45 the telephony watcher. </p> <codeblock id="GUID-71C4B1E3-5887-5A57-8498-211A6D915F00" xml:space="preserve">

    46 //assume that the watcher is stopped 

    47 

    48 StartWatcher();

    49 

    50 TInt state;

    51 TRequestStatus    status;

    52 RProperty property;

    53 

    54 

    55 //initial network status

    56 

    57 TInt ret = RProperty.Get(KUidSystemCategory, KUidChargerStatus.iUid, state);

    58 

    59 // display the value

    60 ...

    61 

    62 //attach to the network status property

    63 

    64 ret = property.Attach(KUidSystemCategory,KUidNetworkStatus.iUid);

    65 

    66 

    67 //subscripe to the property

    68 

    69 property.Subscribe(status);

    70 

    71 User::WaitForRequest(status);

    72 

    73 property.Subscribe(status);

    74 propertty.Get(state);

    75 

    76 //display the value

    77 ...

    78 

    79 </codeblock> </example>

    80 </taskbody></task>