<?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 id="GUID-567585CC-26EC-553D-99D5-D3C178C455F6" xml:lang="en"><title>Configuring

DVB-H Signal Scanning</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>This topic gives you information about the initial setup for DVB-H Signal

Scanning. </p>

<section><title>Purpose</title> <p>The purpose of this topic is to set and

get the scan configuration for DVB-H Signals. </p> </section>

<section><title>Required Background</title><p>You may wish to specify the

scan parameters, before initiating a signal scan. But this step is optional

and by default, if you do not specify any parameters hardware defaults are

used. If you wish to set scan parameters, this is done by calling <xref href="GUID-617CD367-CF68-3932-8E77-669820A7B9AF.dita#GUID-617CD367-CF68-3932-8E77-669820A7B9AF/GUID-B988EC58-EAB0-3644-8AF7-1DBCE06E3E7B"><apiname>RDvbhReceiver::SetScanConfiguration()</apiname></xref> with

a <xref href="GUID-D84731C4-A3C8-37E3-887A-25906530E595.dita"><apiname>TDvbhScanConfiguration</apiname></xref> object containing the following

information: </p> <ul>

<li id="GUID-01EF5C12-BB71-57FA-B50F-7B13095F0367"><p>Start Frequency (in

Hz) : First frequency to scan. </p> </li>

<li id="GUID-507724E9-9BFB-5C31-B719-E76BAEF5442A"><p>End Frequency (in Hz)

: Last frequency to scan. </p> </li>

<li id="GUID-D053DDFC-B583-5003-9D0F-F551B68EC433"><p>Signal Bandwidth (in

Hz) : Increment frequency is used to compute the next frequency to scan. </p> </li>

<li id="GUID-15567754-A0FC-51EA-8FB9-8BF84F1621E3"><p>Scan Options: <xref href="GUID-176D1C2A-3D04-318B-9C57-EDFBB8CB4CF6.dita"><apiname>EDvbhScanOptionNormal</apiname></xref> to

indicate that the user supplied parameters should be used or <xref href="GUID-78E062FD-A5FD-3231-84DE-BFFEAC3F373D.dita"><apiname>EDvbhScanOptionFullScan</apiname></xref> to

indicate that hardware defaults are used. </p> </li>

</ul> <p>You can determine the current scan configuration being used by the

receiver by calling <xref href="GUID-617CD367-CF68-3932-8E77-669820A7B9AF.dita#GUID-617CD367-CF68-3932-8E77-669820A7B9AF/GUID-10C24DC2-2E9A-3671-94D6-B1910B0FA4A2"><apiname>RDvbhReceiver::GetScanConfigurationRI()</apiname></xref>,

and then passing in a reference to an unpopulated <xref href="GUID-D84731C4-A3C8-37E3-887A-25906530E595.dita"><apiname>TDvbhScanConfiguration</apiname></xref> object. </p></section>

<section><title>Setup and Configuration Requirements</title><p>In order to

initiate a signal scan, mobile TV middleware must implement <xref href="GUID-7A97A0BE-1EDA-380F-B5BB-630E3E0614C4.dita#GUID-7A97A0BE-1EDA-380F-B5BB-630E3E0614C4/GUID-5B931754-A048-3AB0-AC2E-C62472A56717"><apiname>MDvbhScanObserver::DvbhScanProgress()</apiname></xref>.

This function is called by the receiver during the scan process, whenever

it has results to report back to the client. Typically, it is called at least

once each time the receiver finishes scanning a particular frequency. Its

argument is a <xref href="GUID-3F9D2682-8DA6-3493-8B78-8AF1B841A895.dita"><apiname>TDvbhScanResult</apiname></xref> which contains the following

parameters: </p> <ul>

<li id="GUID-85F195A7-05BD-5852-9135-7782A58A087D"><p>Frequency scanned in

Hz. </p> </li>

<li id="GUID-6FE32282-3AEC-5F02-86E2-88248040FEB7"><p>Status of DVB-H signal

frequency, as bitmap of TDvbhSignalStatus values. </p> </li>

<li id="GUID-9DBFAF67-7C0D-5237-9316-370575D09F3E"><p>IP platform that was

found on this frequency. If none was found, it is indicated in status field.

If more than one is found, then <xref href="GUID-7A97A0BE-1EDA-380F-B5BB-630E3E0614C4.dita#GUID-7A97A0BE-1EDA-380F-B5BB-630E3E0614C4/GUID-5B931754-A048-3AB0-AC2E-C62472A56717"><apiname>MDvbhScanObserver::DvbhScanProgress()</apiname></xref> is

called again for each platform found. </p> </li>

<li id="GUID-06DD363E-9EA2-5F8B-A5CB-4151E242E90F"><p>DVB-H network that was

found on frequency. If none was found, it is indicated in status field. If

more than one is found, then <xref href="GUID-7A97A0BE-1EDA-380F-B5BB-630E3E0614C4.dita#GUID-7A97A0BE-1EDA-380F-B5BB-630E3E0614C4/GUID-5B931754-A048-3AB0-AC2E-C62472A56717"><apiname>MDvbhScanObserver::DvbhScanProgress()</apiname></xref> is

called again for each network found. </p> </li>

<li id="GUID-0C85DE38-6E66-524B-A96D-984DA4F4D944"><p>Progress of the scan

is shown between 0 and 100 percentage representation. </p> </li>

</ul> <p>To describe how you should implement <xref href="GUID-7A97A0BE-1EDA-380F-B5BB-630E3E0614C4.dita#GUID-7A97A0BE-1EDA-380F-B5BB-630E3E0614C4/GUID-5B931754-A048-3AB0-AC2E-C62472A56717"><apiname>MDvbhScanObserver::DvbhScanProgress()</apiname></xref> is

beyond the scope of this document, but some typical tasks might be: </p> <ul>

<li id="GUID-70312D47-0035-53AD-9E79-B15EDDCE4414"><p>Building up a list of

frequencies on which DVB-H signals are found. </p> </li>

<li id="GUID-B23013A9-C99B-5D84-9A99-5BE9091B87E1"><p>Building up a list of

available IP platforms. </p> </li>

<li id="GUID-8CDF854D-344D-5E5E-A694-D95BBDE85EDF"><p>Building up a list of

available DVB-H networks. </p> </li>

<li id="GUID-E86E8004-3964-5645-B985-7E8A7705760E"><p>Reporting scan progress

to the end user. </p> </li>

</ul></section>

<section><title>Using DVB-H Signal Scanning </title> <p>The following task

is performed:</p> <ul>

<li id="GUID-D4C94859-AF9E-5F60-8728-3C57591A53C3"><p><xref href="GUID-82D16EB2-BFFE-4607-9DBA-640F062E1408.dita">Scanning

for DVB-H signals</xref> </p> </li>

</ul> </section>

<section><title>Example</title><p>The example code for scanning DVB-H signals

is shown below:</p><codeblock id="GUID-E23036B7-83BE-5A85-9475-60D1473F60BB" xml:space="preserve">

//Context: The following takes place in some method of an active object

//that implements MDvbhScanObserver (e.g. class CExampleClient :

//public CActive, public MDvbhScanObserver). Its member iReceiver is an

//RDvbhReceiver that has previously been initialised.Receiver state is NoPlatform

User::LeaveIfError(iReceiver.Scan(*this, iStatus));

SetActive();

//While the active object is outstanding,

//CExampleClient::DvbhScanProgress() will be called periodically by

//the receiver, each time it has finished scanning a frequency.  When the

//active object completes, if all went well, the object will have a list

//of available IP Platforms at its disposal.

// Example CExampleClient methods

void CExampleClient::DvbhScanProgress(const TDvbhScanResult&

                                             aResult)

    {

    //Analyse aResult.

    //Possibly add platform to list of available IP platforms.

    //Possibly inform application/end user of current progress.

    ...

    }

void CExampleClient::RunL()

    {

    //Called when Scan()completes.  Check iStatus for completion code.

    //(KErrNone, KErrCancelled, KErrNotReady, etc.) and act accordingly,

    //e.g. ReturnListOfPlatformsToApplication(GetListOfPlatforms());

    ...

    }

</codeblock></section>

<section><title>Cancelling a Scan</title> <p>If the signal scan takes a long

time to complete due to bad reception conditions, the end user may wish to

cancel it before it has completed. This is done by calling <xref href="GUID-617CD367-CF68-3932-8E77-669820A7B9AF.dita#GUID-617CD367-CF68-3932-8E77-669820A7B9AF/GUID-C696FEFD-63F9-3654-8315-1FE2504AE037"><apiname>RDvbhReceiver::CancelScan()</apiname></xref>. </p> <p>If

a scan is active when <xref href="GUID-617CD367-CF68-3932-8E77-669820A7B9AF.dita#GUID-617CD367-CF68-3932-8E77-669820A7B9AF/GUID-C696FEFD-63F9-3654-8315-1FE2504AE037"><apiname>RDvbhReceiver::CancelScan()</apiname></xref> is called,

request will complete with eroor this may lead to KErrCancelled for creating

partial list of available IP platforms. If this happens, then scan data is

valid. </p> <p>If a scan is not active when <xref href="GUID-617CD367-CF68-3932-8E77-669820A7B9AF.dita#GUID-617CD367-CF68-3932-8E77-669820A7B9AF/GUID-C696FEFD-63F9-3654-8315-1FE2504AE037"><apiname>RDvbhReceiver::CancelScan()</apiname></xref> is

called, nothing happens. </p> </section>

</conbody><related-links>

<link href="GUID-3C9BE2FF-8D5C-51D0-8BC1-BED7BC1288BA.dita"><linktext>Turn On Broadcast

Receiver</linktext></link>

<link href="GUID-2C8BE998-BCCE-5A06-AFC1-4B611D9233AB.dita"><linktext>Turn Off

Broadcast Receiver</linktext></link>

<link href="GUID-0297CAF5-4EB7-5E84-8A8C-8758D6F3B75F.dita"><linktext>Setting Data

Reception</linktext></link>

<link href="GUID-743D3117-095B-58D5-947D-A8713475C9A5.dita"><linktext>Tuning IP

Platform</linktext></link>

<link href="GUID-F5FE22F3-B7C4-50B3-9B36-5CB8BC1BA18A.dita"><linktext>Receiving

Broadcast Data</linktext></link>