<?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-A12C6F14-5FFC-50BE-A837-5EA569C8AB52" xml:lang="en"><title>Telephony

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

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

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

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

registered clients applications. The client application must register with

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

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

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

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

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

of watchers </cmd>

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

</step>

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

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

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

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

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

</step>

<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

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

the updated information. </cmd>

</step>

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

can be displayed to the user. </cmd>

</step>

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

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

</step>

</steps>

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

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

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

//assume that the watcher is stopped 

StartWatcher();

TInt state;

TRequestStatus    status;

RProperty property;

//initial network status

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

// display the value

...

//attach to the network status property

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

//subscripe to the property

property.Subscribe(status);

User::WaitForRequest(status);

property.Subscribe(status);

propertty.Get(state);

//display the value

...

</codeblock> </example>