<?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 concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept xml:lang="en" id="GUID-24BD5003-7E85-5BDF-A991-0D0DAE45B5DE"><title>Receiver Information Notifications</title><prolog><metadata><keywords/></metadata></prolog><conbody><p>This document is about the receiving notification of changes to the receiver information. </p> <section><title>Purpose</title> <p>This tutorial helps you to request to be notified of changes to receiver information by observing objects appropriate for the information. </p> <p><b>Required Background</b> </p> <p>In order to be notified of changes to receiver information, you will require a <xref href="GUID-CC7A9DBB-559F-3773-BEA4-BD56F495F736.dita"><apiname>CDvbhReceiverInfo</apiname></xref> instances, which is created using <xref href="GUID-CC7A9DBB-559F-3773-BEA4-BD56F495F736.dita#GUID-CC7A9DBB-559F-3773-BEA4-BD56F495F736/GUID-74AE525B-ADC3-3928-8249-C643626D8256"><apiname>CDvbhReceiverInfo::NewL()</apiname></xref> or <xref href="GUID-CC7A9DBB-559F-3773-BEA4-BD56F495F736.dita#GUID-CC7A9DBB-559F-3773-BEA4-BD56F495F736/GUID-B9B5107E-F9D2-368F-85B0-28149D5254AF"><apiname>CDvbhReceiverInfo::NewLC()</apiname></xref>. </p> <p>You need to have an observer object appropriate for the information which will be a concrete realisations of one more of the following interface classes: </p> <ul><li id="GUID-7E4AE88D-2C2E-5D8D-984B-A541F9C5500F"><p> <xref href="GUID-E03EB6B3-A318-3401-9B39-9ECDF25F3935.dita"><apiname>MDvbhStateObserver</apiname></xref> used for receiving notifications of state changes </p> </li> <li id="GUID-629257C1-8934-562A-8E87-CDA3C48F6EC7"><p> <xref href="GUID-5461F8B8-4DF7-3E64-BB3E-B06138CAD364.dita"><apiname>MDvbhSignalQualityObserver</apiname></xref> used for receiving notifications of signal quality changes </p> </li> <li id="GUID-358776F3-3E58-596A-9A7C-22370A238043"><p> <xref href="GUID-67FE4031-3B14-378B-BEB0-3B606F2F5CD0.dita"><apiname>MDvbhPlatformObserver</apiname></xref> used for receiving notifications of platform changes </p> </li> <li id="GUID-72DC5C1F-8263-5A95-82AA-5A4E070A37DD"><p> <xref href="GUID-9A76F530-3177-3490-BD52-7F9528179C73.dita"><apiname>MDvbhNetworkTimeObserver</apiname></xref> used for receiving notifications of network time changes </p> </li> <li id="GUID-A3C9F6BC-52B4-5F0D-8EC4-8A2E4A3F419D"><p> <xref href="GUID-5956E1FB-7A62-304F-9301-ED079FC37DDF.dita"><apiname>MDvbhFrequencyObserver</apiname></xref> used for receiving notifications of frequency changes </p> </li> <li id="GUID-1D4267F3-1C98-5697-8EC5-8959A6A4C314"><p> <xref href="GUID-56FABBD7-D93A-37E4-8591-0A34701371E8.dita"><apiname>MDvbhCellIdObserver</apiname></xref> used for receiving notifications of cellId changes </p> </li> <li id="GUID-31FAE1AD-0B9D-526C-9AB7-5DC262C30848"><p> <xref href="GUID-495FBE09-313A-359F-84D0-763B79306C00.dita"><apiname>MDvbhNetworkIdObserver</apiname></xref> used for receiving notifications of networkId changes </p> </li> </ul> <p><b>Introduction</b> </p> <p> <xref href="GUID-CC7A9DBB-559F-3773-BEA4-BD56F495F736.dita"><apiname>CDvbhReceiverInfo</apiname></xref> is used for receiving notifications of state changes, signal quality changes, platform changes, network time changes, frequency changes, cellId changes and networkId changes. </p> <p><b>Setup and Configuration Requirements</b> </p> <p> </p> <p>Each of the above observer classes contains a single callback function, to be called by <xref href="GUID-CC7A9DBB-559F-3773-BEA4-BD56F495F736.dita"><apiname>CDvbhReceiverInfo</apiname></xref> whenever the information to which it relates changes. The callback functions are: </p> <ul><li id="GUID-B27BD75D-5C8F-50BF-A4E7-D3A9B80B5F33"><p> <xref href="GUID-E03EB6B3-A318-3401-9B39-9ECDF25F3935.dita#GUID-E03EB6B3-A318-3401-9B39-9ECDF25F3935/GUID-64065E2C-9B8A-37B6-8A8F-66BC67E1CC01"><apiname>MDvbhStateObserver::DvbhStateChange()</apiname></xref>  </p> </li> <li id="GUID-0C252A25-4B31-5A3C-9C50-05840D7F6C13"><p> <xref href="GUID-5461F8B8-4DF7-3E64-BB3E-B06138CAD364.dita#GUID-5461F8B8-4DF7-3E64-BB3E-B06138CAD364/GUID-5231E5DA-155F-3004-A014-84EC8FA6D511"><apiname>MDvbhSignalQualityObserver::DvbhSignalQualityChange()</apiname></xref> </p> </li> <li id="GUID-41E5ED71-F661-5FFB-ACB1-B9532E383F7C"><p> <xref href="GUID-67FE4031-3B14-378B-BEB0-3B606F2F5CD0.dita#GUID-67FE4031-3B14-378B-BEB0-3B606F2F5CD0/GUID-00329C8F-63E0-37B2-A7DD-66CF5B33FE49"><apiname>MDvbhPlatformObserver::DvbhPlatformChange()</apiname></xref> </p> </li> <li id="GUID-09EC1147-B5B6-5BD2-86E0-FB19B544BA80"><p> <xref href="GUID-9A76F530-3177-3490-BD52-7F9528179C73.dita#GUID-9A76F530-3177-3490-BD52-7F9528179C73/GUID-B07EA487-C845-3494-AB62-6DEC247CD1A7"><apiname>MDvbhNetworkTimeObserver::DvbhNetworkTimeChange()</apiname></xref> </p> </li> <li id="GUID-135354AC-3AE8-525C-BC3B-401E5A9CA4A9"><p> <xref href="GUID-5956E1FB-7A62-304F-9301-ED079FC37DDF.dita#GUID-5956E1FB-7A62-304F-9301-ED079FC37DDF/GUID-3DAFA91E-3146-388B-8B3D-6E88CE049218"><apiname>MDvbhFrequencyObserver::DvbhFrequencyChange()</apiname></xref> </p> </li> <li id="GUID-91C21312-FEC6-5FDA-9E75-AA4968F4E4DD"><p> <xref href="GUID-56FABBD7-D93A-37E4-8591-0A34701371E8.dita#GUID-56FABBD7-D93A-37E4-8591-0A34701371E8/GUID-8A020940-C31A-3255-BA5B-B2D3382305DA"><apiname>MDvbhCellIdObserver::DvbhCellIdChange()</apiname></xref>  </p> </li> <li id="GUID-F1FBC3DD-9E69-510B-AE82-117576055351"><p> <xref href="GUID-495FBE09-313A-359F-84D0-763B79306C00.dita#GUID-495FBE09-313A-359F-84D0-763B79306C00/GUID-595B6BAB-B5D3-3900-9B1D-6AA79993D2E9"><apiname>MDvbhNetworkIdObserver::DvbhNetworkIdChange()</apiname></xref> </p> </li> </ul> </section> <section><title>Using Receiver Information Notified Changes Tutorial </title> <p>The Following tasks will be covered in this tutorial: </p> <ul><li id="GUID-B5B90CB9-AF31-5D4E-A2B7-1BFBB19EE1DC"><p><xref href="GUID-24BD5003-7E85-5BDF-A991-0D0DAE45B5DE.dita#GUID-24BD5003-7E85-5BDF-A991-0D0DAE45B5DE/GUID-6C0B835C-BBF8-5CEA-ABC5-18FFDA64D9F9">How to receive notification of changes to receiver information</xref>  </p> </li> </ul> <p id="GUID-6C0B835C-BBF8-5CEA-ABC5-18FFDA64D9F9"><b>Basic Procedure</b> </p> <p>The high level steps to receive notification changes of receiver information are shown here: </p> <ol id="GUID-196F923D-896B-5F69-AFCD-CA478E9406F5"><li id="GUID-883F7CE0-416F-5E18-BB49-FF11ED0C1252"><p>Implement the M-class appropriate to the information you want to observe. </p> </li> <li id="GUID-8235BF1A-6B3B-5D9D-B5B6-A1FAC3A24227"><p>Call the appropriate set observer method for the information you want to observe, passing in your M-class object. For example to receive the state changes, call <xref href="GUID-CC7A9DBB-559F-3773-BEA4-BD56F495F736.dita#GUID-CC7A9DBB-559F-3773-BEA4-BD56F495F736/GUID-62F13C1E-84F7-3C71-81A2-DFBE98A22158"><apiname>CDvbhReceiverInfo::SetStateObserver()</apiname></xref> function. </p> <p>List of consequences to receive notification of changes to receiver information are: </p> <ul><li id="GUID-E5E359E4-2096-5271-B208-6FB446923D7D"><p>Whenever the related information changes, the call back function on the registered observer object is executed and you will be informed in this way. Once an observer is registered, it remains registered until either <xref href="GUID-CC7A9DBB-559F-3773-BEA4-BD56F495F736.dita"><apiname>CDvbhReceiverInfo</apiname></xref> instance is destroyed, or until a new observer is registered with another call to same set observer method. It is worth nothing that observers are registered with individual instances, not with any resource shared between instances. </p> </li> <li id="GUID-D7338658-D988-5A01-A4D5-1A030DB7C3B3"><p>Thus it is possible for two <xref href="GUID-CC7A9DBB-559F-3773-BEA4-BD56F495F736.dita"><apiname>CDvbhReceiverInfo</apiname></xref> instances to have different <xref href="GUID-E03EB6B3-A318-3401-9B39-9ECDF25F3935.dita"><apiname>MDvbhStateObserver</apiname></xref> instances registered simultaneously. For example when the state changes, callbacks on both of these observers are called. </p> </li> </ul> </li> </ol> <p><b>Example </b> </p> <codeblock id="GUID-DA8FD43F-3BD0-5150-9611-50070CCB1D35" xml:space="preserve">

//Context: Assume the following code is part of some CExampleClient method,

//where CExampleClient is a class that implements MDvbhStateObserver 

//(e.g. class CExampleClient : public CBase, public MDvbhStateObserver).

//Assume that CExampleClient::iReceiver has not been initialised.

User::LeaveIfError(iReceiver.Open()); 

// State is Inactive to begin with.

User::LeaveIfError(iReceiverInfo->SetStateObserver(*this));

//From now on, whenever the receiver state changes,

//CExampleClient::DvbhStateChange() will be called.

User::LeaveIfError(iReceiver.PowerOn());

//This causes the state to transition to Booting, which will cause

//CExampleClient::DvbhStateChange() to be run.  When booting completes,

//the state will transition to NoPlatform and this will cause

//CExampleClient::DvbhStateChange() to be run again, and so on....

//CExampleClient code:

void CExampleClient::DvbhStateChange(TDvbhState& aNewState)

    {

    //Client writes code here to do whatever it needs to do when the

    //state changes.  In our example, it has just powered on the receiver

    //so it may want to be informed when it has finished booting and

 //transitioned to the NoPlatform state so that it can start a signal

 //scan.

    ...

    }

</codeblock> </section> </conbody><related-links><link href="GUID-A66DF817-736E-53E5-869A-AD67A27E4410.dita"><linktext>Accessing DVB-H Receiver Information