Configuring DVB-H Signal Scanning

Purpose

The purpose of this topic is to set and get the scan configuration for DVB-H Signals.

Required Background

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 RDvbhReceiver::SetScanConfiguration() with a TDvbhScanConfiguration object containing the following information:

• Start Frequency (in Hz) : First frequency to scan.

• End Frequency (in Hz) : Last frequency to scan.

• Signal Bandwidth (in Hz) : Increment frequency is used to compute the next frequency to scan.

• Scan Options: EDvbhScanOptionNormal to indicate that the user supplied parameters should be used or EDvbhScanOptionFullScan to indicate that hardware defaults are used.

You can determine the current scan configuration being used by the receiver by calling RDvbhReceiver::GetScanConfigurationRI(), and then passing in a reference to an unpopulated TDvbhScanConfiguration object.

Setup and Configuration Requirements

In order to initiate a signal scan, mobile TV middleware must implement MDvbhScanObserver::DvbhScanProgress(). 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 TDvbhScanResult which contains the following parameters:

• Frequency scanned in Hz.

• Status of DVB-H signal frequency, as bitmap of TDvbhSignalStatus values.

• 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 MDvbhScanObserver::DvbhScanProgress() is called again for each platform found.

• 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 MDvbhScanObserver::DvbhScanProgress() is called again for each network found.

• Progress of the scan is shown between 0 and 100 percentage representation.

To describe how you should implement MDvbhScanObserver::DvbhScanProgress() is beyond the scope of this document, but some typical tasks might be:

• Building up a list of frequencies on which DVB-H signals are found.

• Building up a list of available IP platforms.

• Building up a list of available DVB-H networks.

• Reporting scan progress to the end user.

Using DVB-H Signal Scanning

The following task is performed:

• Scanning for DVB-H signals

Example

The example code for scanning DVB-H signals is shown below:

//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());
    ...
    }

Cancelling a Scan

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 RDvbhReceiver::CancelScan().

If a scan is active when RDvbhReceiver::CancelScan() 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.

If a scan is not active when RDvbhReceiver::CancelScan() is called, nothing happens.