<?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-3C9BE2FF-8D5C-51D0-8BC1-BED7BC1288BA"><title>Turn On Broadcast Receiver Tutorial</title><prolog><metadata><keywords/></metadata></prolog><conbody><p>This document helps you to understand how <xref href="GUID-617CD367-CF68-3932-8E77-669820A7B9AF.dita"><apiname>RDvbhReceiver</apiname></xref> handles session setup and power-up, to communicate with the Broadcast Receiver hardware. </p> <section><title>Purpose</title> <p>This tutorial tells you about how to open a session and to power on the Broadcast Receiver hardware. The purpose is to end up with a session to a powered-on receiver. </p> <p><b>Required Background</b> </p> <p>In order to open a session an <xref href="GUID-617CD367-CF68-3932-8E77-669820A7B9AF.dita"><apiname>RDvbhReceiver</apiname></xref> instance is created between it and the receiver. </p> <p><b>Introduction</b> </p> <p>You may think of a <xref href="GUID-617CD367-CF68-3932-8E77-669820A7B9AF.dita"><apiname>RDvbhReceiver</apiname></xref> instance as a handle to the DVB-H receiver hardware resource. This resource may have many simultaneous handles and provides reference counts to keep track of and manage its simultaneous clients. </p> <p><b>Setup and Configuration Requirements</b> </p> <p>For efficient use of <xref href="GUID-617CD367-CF68-3932-8E77-669820A7B9AF.dita"><apiname>RDvbhReceiver</apiname></xref> handles in general, it is recommended that you follow these guidelines: </p> <ul><li id="GUID-26348675-0832-58C2-B846-BFE7E9924020"><p>IP data reception should use a single <xref href="GUID-617CD367-CF68-3932-8E77-669820A7B9AF.dita"><apiname>RDvbhReceiver</apiname></xref> instance. </p> </li> <li id="GUID-CA887DD3-792A-5A4C-A7A5-6ADFF0BDAEC0"><p>Tunning should use at least one other <xref href="GUID-617CD367-CF68-3932-8E77-669820A7B9AF.dita"><apiname>RDvbhReceiver</apiname></xref> instance. </p> </li> </ul> <p>Clients should be aware when they call methods on their instances, that there may be other <xref href="GUID-617CD367-CF68-3932-8E77-669820A7B9AF.dita"><apiname>RDvbhReceiver</apiname></xref> clients accessing the same shared resource. For example, if a client disables the receiver by calling <xref href="GUID-617CD367-CF68-3932-8E77-669820A7B9AF.dita#GUID-617CD367-CF68-3932-8E77-669820A7B9AF/GUID-36FEEFAF-D70C-3503-A7EE-3E82F477699F"><apiname>RDvbhReceiver::SetDisabled()</apiname></xref> with the argument as ETrue this disables the receiver for all clients, not just for the one that made the call. So it is important that the mobile TV middleware as a whole carefully manages its <xref href="GUID-617CD367-CF68-3932-8E77-669820A7B9AF.dita"><apiname>RDvbhReceiver</apiname></xref> instances to avoid contention. </p> </section> <section><title>Using Turn On Broadcast Receiver Tutorial</title> <p>The following tasks will be covered in this tutorial: </p> <ul><li id="GUID-D6F0DB8F-6761-57AE-94EE-AA46C55CB385"><p><xref href="GUID-3C9BE2FF-8D5C-51D0-8BC1-BED7BC1288BA.dita#GUID-3C9BE2FF-8D5C-51D0-8BC1-BED7BC1288BA/GUID-360040E8-ABBF-5095-BDE3-E489E97810D0">How to open a session for the Broadcast Reciever</xref>  </p> </li> <li id="GUID-37BEF1D6-24F5-5717-BCB8-C22FC0911FDA"><p><xref href="GUID-3C9BE2FF-8D5C-51D0-8BC1-BED7BC1288BA.dita#GUID-3C9BE2FF-8D5C-51D0-8BC1-BED7BC1288BA/GUID-A3B8DB8A-4870-511D-8915-CCE73477C4DD">How to power-on the Broadcast Reciever</xref>  </p> </li> </ul> <p id="GUID-360040E8-ABBF-5095-BDE3-E489E97810D0"><b>Basic Procedure To Open Session For Broadcast Reciever</b> </p> <p> <b>The high level steps to open a session for the Broadcast Reciever are shown here:</b>  </p> <ol id="GUID-E6A4A7C2-8491-5ABD-8748-B27F5AE31D7F"><li id="GUID-DE401BB4-E87D-5F48-878C-90FB00357CBA"><p>A session to the Broadcast Receiver is created by calling <xref href="GUID-617CD367-CF68-3932-8E77-669820A7B9AF.dita#GUID-617CD367-CF68-3932-8E77-669820A7B9AF/GUID-44B80593-8400-3084-AC33-B8E4F00DFE8F"><apiname>RDvbhReceiver::Open()</apiname></xref>. The Client is not in contact with the receiver until <xref href="GUID-617CD367-CF68-3932-8E77-669820A7B9AF.dita#GUID-617CD367-CF68-3932-8E77-669820A7B9AF/GUID-44B80593-8400-3084-AC33-B8E4F00DFE8F"><apiname>RDvbhReceiver::Open()</apiname></xref> is successfully called. </p> </li> <li id="GUID-B7B91045-B08A-5E5D-9CA3-6F0AB7E3757C"><p> <xref href="GUID-617CD367-CF68-3932-8E77-669820A7B9AF.dita#GUID-617CD367-CF68-3932-8E77-669820A7B9AF/GUID-44B80593-8400-3084-AC33-B8E4F00DFE8F"><apiname>RDvbhReceiver::Open()</apiname></xref> should normally not fail. But the error code should always be checked in case of unusual situations like the device running out of memory. In this case KErrNoMemory would be returned and the session to the Broadcast Receiver would not be opened. Clients should be prepared to accept any other system-wide error code. </p> <p>If a client calls a method on a <xref href="GUID-617CD367-CF68-3932-8E77-669820A7B9AF.dita"><apiname>RDvbhReceiver</apiname></xref> instance before <xref href="GUID-617CD367-CF68-3932-8E77-669820A7B9AF.dita#GUID-617CD367-CF68-3932-8E77-669820A7B9AF/GUID-44B80593-8400-3084-AC33-B8E4F00DFE8F"><apiname>RDvbhReceiver::Open()</apiname></xref> has been successfully called, KErrNotReady will be returned. </p> <p> <b>Note:- </b> You can call <xref href="GUID-617CD367-CF68-3932-8E77-669820A7B9AF.dita#GUID-617CD367-CF68-3932-8E77-669820A7B9AF/GUID-9635DE2C-FCF0-3401-8A77-0C72EC783608"><apiname>RDvbhReceiver::GetDvbhVersion()</apiname></xref> to retrieve the version of DVB-H hardware from the receiver, before calling <xref href="GUID-617CD367-CF68-3932-8E77-669820A7B9AF.dita#GUID-617CD367-CF68-3932-8E77-669820A7B9AF/GUID-44B80593-8400-3084-AC33-B8E4F00DFE8F"><apiname>RDvbhReceiver::Open()</apiname></xref>. </p> </li> </ol> <p><b>Example </b> </p> <codeblock id="GUID-2073EEA7-F539-58F6-A06E-BB2F3DD2327A" xml:space="preserve">

TInt result = iReceiver.Open();

if (result != KErrNone)

    {

    //Take some action.

    return HandleOpenError(result);

    };

//A communication channel to the receiver is established, so you can use it.

</codeblock> <p id="GUID-A3B8DB8A-4870-511D-8915-CCE73477C4DD"><b>Basic Procedure To Power-on The Broadcast Receiver</b> </p> <p> <b>The high level steps to power-on the Broadcast Receiver are shown here:</b>  </p> <p>To receive the DVB-H broadcasts, the receiver must be powered on. Each client which requires the hardware to remain power on must call <xref href="GUID-617CD367-CF68-3932-8E77-669820A7B9AF.dita#GUID-617CD367-CF68-3932-8E77-669820A7B9AF/GUID-3C48A641-C307-37D6-9931-D627363C8942"><apiname>RDvbhReceiver::PowerOn()</apiname></xref>. </p> <ol id="GUID-86321805-6497-580E-9FA7-BB4BF2FDC24E"><li id="GUID-0B411A75-CE79-532B-8EF8-E776E9B701C1"><p>To power on, call <xref href="GUID-617CD367-CF68-3932-8E77-669820A7B9AF.dita#GUID-617CD367-CF68-3932-8E77-669820A7B9AF/GUID-3C48A641-C307-37D6-9931-D627363C8942"><apiname>RDvbhReceiver::PowerOn()</apiname></xref> which causes the receiver to boot hardware, if it is not already powered on. Once done, it need not be done again unless the receiver is powered down, disabled or goes into fatal error state. </p> </li> <li id="GUID-44D937C0-C134-537E-8E25-DC909EAF2F94"><p>Once the booting sequence is successfully completed, the receiver may configure and use the DVB-H receiver. </p> </li> </ol> <p><b>Example </b> </p> <codeblock id="GUID-420B7F8B-BDCE-552F-83E1-9BFEC37E241B" xml:space="preserve">

//Pre condition – iReceiver.Open() has previously been called successfully

TInt result = iReceiver.PowerOn();

if (result != KErrNone)

    {

    //Take some action.

    return HandlePowerOnFailure(result);

    }

//Post condition – the receiver is powered on

</codeblock> </section> </conbody><related-links><link href="GUID-2C8BE998-BCCE-5A06-AFC1-4B611D9233AB.dita"><linktext>Turn Off Broadcast Receiver Tutorial</linktext> </link> <link href="GUID-0297CAF5-4EB7-5E84-8A8C-8758D6F3B75F.dita"><linktext>Setting Data Reception Tutorial</linktext> </link> <link href="GUID-567585CC-26EC-553D-99D5-D3C178C455F6.dita"><linktext>DVB-H Signal Scanning Tutorial</linktext> </link> <link href="GUID-743D3117-095B-58D5-947D-A8713475C9A5.dita"><linktext>Tuning IP Platform Tutorial</linktext> </link> <link href="GUID-F5FE22F3-B7C4-50B3-9B36-5CB8BC1BA18A.dita"><linktext>Receiving Broadcast Data