B2C2, Inc. - Software Development Kit

IB2C2MPEG2TunerCtrl2

  IB2C2MPEG2TunerCtrl2      
  Call Sequences and Overview      
    Setting      
    Getting      
  Methods      
           

In order to receive programs, the broadband receiver must first lock onto a channel. This is accomplished by controlling the tuner. IB2C2MPEG2TunerCtrl2 supports satellite, cable, and terrestrial tuners. IB2C2MPEG2TunerCtrl2 methods allow software to lock onto a channel, including the monitoring of receiver (tuner module) performance statistics such as BER and Uncorrected Blocks.

In Windows, IB2C2MPEG2TunerCtrl2 is an interface implemented on the B2C2MPEG2Filter.

In Linux, IB2C2MPEG2TunerCtrl2 is instantiated as a member of B2C2MPEG2Adapter, which controls B2C2's broadband device.

Call Sequences and Overview

Setting

IB2C2MPEG2TunerCtrl2 allows various tuner parameters such as IB2C2MPEG2TunerCtrl2::SetFrequency to be set. Once all required parameters have been set, the IB2C2MPEG2TunerCtrl2::SetTunerStatus method must be called to send the settings to the tuner. Afterwards, IB2C2MPEG2TunerCtrl2::CheckLock method can be called to determine if the tuner is in lock.

Getting

The IB2C2MPEG2TunerCtrl2::CheckLock method must be called before making calls that GET any kind of tuner settings, status, or signal quality/strength/SNR, since, if the tuner is not in lock these returns would be undefined or invalid.

Methods

For backwards compatibility IB2C2MPEG2TunerCtrl is defined. But the derived class IB2C2MPEG2TunerCtrl2 interface supports all methods from previous version IB2C2MPEG2TunerCtrl. Methods for all versions are shown in the table.

IUnknown Methods

Description

x
Operating System (Windows, Linux)
QueryInterface Retrieves pointers to supported interfaces.   W
AddRef Increments the reference count.   W
Release Decrements the reference count.   W

IB2C2MPEG2TunerCtrl  Methods

Description

Applicable Tuner Type

Operating System (Windows, Linux)
CheckLock Checks lock status of tuner. All W, L
GetChannel Gets current Channel value. Terrestrial ATSC W, L
GetFrequency Gets current Transponder Frequency value. Terrestrial ATSC W, L
GetModulation Gets current Modulation value. Terrestrial ATSC W, L
GetPreErrorCorrectionBER Gets current pre-error-correction Bit Error Rate value. Terrestrial ATSC W, L
GetSignalLevel Obsolete. - W, L
GetSignalQuality Gets current Signal Quality value. All* W, L
GetSignalStrength Gets current Signal Strength value. All* W, L
GetSNR Gets current Signal to Noise Ratio value. Terrestrial ATSC W, L
GetSymbolRate Gets current Symbol Rate value. Terrestrial ATSC W, L
GetTotalBlocks Gets current value for count of Total Blocks. All* W, L
GetTunerCapabilities Gets current tuner capability values. All W, L
GetUncorrectedBlocks Gets current value for count of Uncorrected Blocks. All* W, L
Initialize In Windows, creates connection to tuner control interface of B2C2MPEG2Filter. Not needed for Linux. All W, L
SetChannel Sets Channel value. Terrestrial ATSC W, L
SetDiseqc Sets DiSEqC value. Satellite W, L
SetFec Sets FEC value. Satellite W, L
SetFrequency Sets Transponder Frequency value in MHz. All W, L
SetLnbFrequency Sets LNB Frequency value. Satellite W, L
SetLnbKHz Sets LNB Selection value. Satellite W, L
SetModulation Sets Modulation value. Cable W, L
SetPolarity Sets Polarity value. Satellite W, L
SetSymbolRate Sets Symbol Rate value. Satellite, Cable W, L
SetTunerStatus Sends values to tuner for tuning. All W, L

IB2C2MPEG2TunerCtrl2  Methods

Description

Applicable Tuner Type

Operating System (Windows, Linux)
GetDiseqc Gets current DiSEqC value. Satellite W, L
GetFec Gets current FEC value. Satellite W, L
GetGuardInterval Gets current Guard Interval. Terrestrial DVB W, L
GetLnbFrequency Gets current LNB Frequency value. Satellite W, L
GetLnbKHz Gets current LNB Selection value. Satellite W, L
GetPolarity Gets current Polarity value. Satellite W, L
GetCorrectedBlocks Gets current value for count of Corrected Blocks. All* W, L
SetFrequencyKHz Sets Transponder Frequency value in kHz. All W, L
SetGuardInterval Sets Guard Interval. Terrestrial DVB W, L
SetTunerStatusEx Sends values to tuner for tuning with optional argument for defining how many times the SDK should check whether the tuner is in lock. All W, L
  * Tuner dependent. Use GetTunerCapabilities to determine whether or not the function is supported by this tuner.

 


IB2C2MPEG2TunerCtrl2::CheckLock

Return to Top

Checks lock status of tuner.

Syntax

HRESULT CheckLock();

Parameters

None

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Remarks

A successful return code indicates that the tuner is in lock.


IB2C2MPEG2TunerCtrl2::GetChannel

Return to Top

Gets current Channel value.

Syntax

HRESULT GetChannel(

long * plChannel

);

Parameters

plChannel

[out] Pointer to a variable created by the caller. Variable will hold Channel number.

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Remarks

None.

See also

SetChannel


IB2C2MPEG2TunerCtrl2::GetFrequency

Return to Top

Gets current Transponder Frequency in MHz.

Syntax

HRESULT GetFrequency(

long * plFrequencyMHz

);

Parameters

plFrequencyMHz

[out] Pointer to a long variable created by the caller. Variable will hold the Transponder Frequency in MHz.

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Remarks

None.

See also

SetFrequency


IB2C2MPEG2TunerCtrl2::GetModulation

Return to Top

Gets current Modulation value.

Syntax

HRESULT GetModulation(

long * plModulation

);

Parameters

plModulation

[out] Pointer to a long variable created by the caller. Variable will hold the Modulation value. (Use eModulation enumerated type defined in header file b2c2_defs.h delivered as part of the SDK.) Possible values are:

QAM_4
QAM_16
QAM_32
QAM_64
QAM_128
QAM_256

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Remarks

Return value is a member of enum tTunerModulation defined at b2c2_defs.h.

See also

SetModulation


IB2C2MPEG2TunerCtrl2::GetPreErrorCorrectionBER

Return to Top

Gets current pre-error-correction Bit Error Rate (BER) value.

Syntax

HRESULT GetPreErrorCorrectionBER(

float * pfBER,

bool bWait

);

Parameters

pfBER

[out] Pointer to a variable created by the caller. Variable will hold Bit Error Rate.

bWait

(Not used.)

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Remarks

None.


IB2C2MPEG2TunerCtrl2::GetSignalLevel

The GetSignalLevel function is obsolete and is implemented for backwards compatibility only. Current version uses GetSignalStrength or GetSignalQuality method, depending on the tuner type.

Return to Top

Syntax

HRESULT GetSignalLevel(

float * pfDbm

);

Parameters

pfDbm

[out] Pointer to a variable created by the caller. Variable will hold Signal Level in dBm.

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Remarks

None.


IB2C2MPEG2TunerCtrl2::GetSignalQuality

Return to Top

Gets current Signal Quality value in %.

Syntax

HRESULT GetSignalQuality(

long * plSignalQuality

);

Parameters

plSignalQuality

[out] Pointer to a variable created by the caller. Variable will hold Signal Quality in %.

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Remarks

Some tuners do not support this function. The member dwPerformanceMonitoring of the structure returned by GetTunerCapabilities indicates whether or not the tuner supports GetSignalQuality (see b2c2_defs.h; SIGNAL_QUALITY_SUPPORTED is set).


IB2C2MPEG2TunerCtrl2::GetSignalStrength

Return to Top

Gets current Signal Strength value in %.

Syntax

HRESULT GetSignalStrength(

long * plSignalStrength

);

Parameters

plSignalStrength

[out] Pointer to a variable created by the caller. Variable will hold Signal Strength in %.

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Remarks

Some tuners do not support this function. The member dwPerformanceMonitoring of the structure returned by GetTunerCapabilities indicates whether or not the tuner supports GetSignalStrength (see b2c2_defs.h; SIGNAL_STRENGTH_SUPPORTED is set).


IB2C2MPEG2TunerCtrl2::GetSNR

Return to Top

Gets current Signal to Noise Ratio (SNR) value.

Syntax

HRESULT GetSNR(

float * pfSNR

);

Parameters

pfSNR

[out] Pointer to a variable created by the caller. Variable will hold Signal to Noise Ratio.

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Remarks

None.


IB2C2MPEG2TunerCtrl2::GetSymbolRate

Return to Top

Gets current Symbol Rate in MS/s.

Syntax

HRESULT GetSymbolRate(

long * plSymbolRate

);

Parameters

plSymbolRate

[out] Pointer to a variable created by the caller. Variable will hold the Symbol Rate in KS/s.

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Remarks

None.

See also

SetSymbolRate


IB2C2MPEG2TunerCtrl2::GetTotalBlocks

Return to Top

Gets current count of Total Blocks.

Syntax

HRESULT GetTotalBlocks(

long * plCount

);

Parameters

plCount

[out] Pointer to a variable created by the caller. Variable will hold count of Total Blocks.

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Remarks

The counter will be cleared after the function is called; the value returned is the number of Total Blocks since the last call of this function. This function is tuner dependent; use GetTunerCapabilities to determine whether or not it is supported by this tuner.


IB2C2MPEG2TunerCtrl2::GetTunerCapabilities

Return to Top

Identifies capabilities of particular tuner (ex: frequency range).

Syntax

HRESULT GetTunerCapabilities(

tTunerCapabilities * pTunerCapabilities,

long * plSize

);

Parameters

pTunerCapabilities

[out] Pointer to a structure defined in the header file b2c2_defs.h. The caller provides the structure.

plSize

[out] Pointer to a long variable created by the caller. Variable will hold the size of the structure (bytes) returned.

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Remarks

None.


IB2C2MPEG2TunerCtrl2::GetUncorrectedBlocks

Return to Top

Gets current count of Uncorrected Blocks.

Syntax

HRESULT GetUncorrectedBlocks(

long * plCount

);

Parameters

plCount

[out] Pointer to a variable created by the caller. Variable will hold count of Uncorrected Blocks.

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Remarks

The counter will be cleared after the function is called; the value returned is the number of Uncorrected Blocks since the last call of this function. This function is tuner dependent; use GetTunerCapabilities to determine whether or not it is supported by this tuner.


IB2C2MPEG2TunerCtrl2::Initialize

Return to Top

In Windows, creates connection to Tuner Control interface of B2C2MPEG2Filter. (See sample applications for more information.) This method is implemented in Linux for compatibility with the Windows SDK, but performs no operation.

Syntax

HRESULT Initialize();

Parameters

None.

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Remarks

None.


IB2C2MPEG2TunerCtrl2::SetChannel

Return to Top

Sets Channel value.

Syntax

HRESULT SetChannel(

long lChannel

);

Parameters

lChannel

[in] Channel number.

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Remarks

The value is sent to the tuner when IB2C2MPEG2TunerCtrl2::SetTunerStatus method is called.

See also

GetChannel


IB2C2MPEG2TunerCtrl2::SetDiseqc

Return to Top

Sets DiSEqC value.

Syntax

HRESULT SetDiseqc(

long lDiseqc

);

Parameters

lDiseqc

[in] DiSEqC value. Use eDiseqc enumerated type defined in header file b2c2_defs.h delivered as part of the SDK. Possible values are:

DISEQC_NONE
DISEQC_SIMPLE_A
DISEQC_SIMPLE_B
DISEQC_LEVEL_1_A_A
DISEQC_LEVEL_1_B_A
DISEQC_LEVEL_1_A_B
DISEQC_LEVEL_1_B_B

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Remarks

The value is sent to the tuner when IB2C2MPEG2TunerCtrl2::SetTunerStatus method is called.


IB2C2MPEG2TunerCtrl2::SetFec

Return to Top

Sets FEC value.

Syntax

HRESULT SetFec(

long lFec

);

Parameters

lFec

[in] FEC value. Use eFEC enumerated type defined in header file b2c2_defs.h delivered as part of the SDK. Possible values are:

FEC_1_2
FEC_2_3
FEC_3_4
FEC_5_6
FEC_7_8
FEC_AUTO

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Remarks

The value is sent to the tuner when IB2C2MPEG2TunerCtrl2::SetTunerStatus method is called.


IB2C2MPEG2TunerCtrl2::SetFrequency

Return to Top

Sets Transponder Frequency value in MHz.

Syntax

HRESULT SetFrequency(

long lFrequencyMHz

);

Parameters

lFrequencyMHz

[in] Transponder Frequency in MHz. Must be greater than or equal to zero. The upper limit is tuner dependent.

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Remarks

The value is sent to the tuner when IB2C2MPEG2TunerCtrl2::SetTunerStatus method is called.

See also

GetFrequency; SetFrequencyKHz


IB2C2MPEG2TunerCtrl2::SetLnbFrequency

Return to Top

Sets LNB Frequency value.

Syntax

HRESULT SetLnbFrequency(

long lFrequencyMHz

);

Parameters

lFrequencyMHz

[in] LNB Frequency in MHz. Must be greater than or equal to zero and less than Transponder Frequency set by IB2C2MPEG2TunerCtrl2::SetFrequency or by IB2C2MPEG2TunerCtrl2::SetFrequencyKHz.

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Remarks

The value is sent to the tuner when IB2C2MPEG2TunerCtrl2::SetTunerStatus method is called.


IB2C2MPEG2TunerCtrl2::SetLnbKHz

Return to Top

Sets LNB kHz selection value.

Syntax

HRESULT SetLnbKHz(

long lLnbKHz

);

Parameters

lLnbKHz

[in] LNB kHz Selection value. Use eLNBSelection enumerated type defined in header file b2c2_defs.h delivered as part of the SDK. Possible values are:

LNB_SELECTION_0
LNB_SELECTION_22
LNB_SELECTION_33
LNB_SELECTION_44

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Remarks

The value is sent to the tuner when IB2C2MPEG2TunerCtrl2::SetTunerStatus method is called.


IB2C2MPEG2TunerCtrl2::SetModulation

Return to Top

Sets Modulation value.

Syntax

HRESULT SetModulation(

long lModulation

);

Parameters

lModulation

[in] Modulation value. Use eModulation enumerated type defined in header file b2c2_defs.h delivered as part of the SDK. Possible values are:

QAM_4
QAM_16
QAM_32
QAM_64
QAM_128
QAM_256

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Remarks

The value is sent to the tuner when IB2C2MPEG2TunerCtrl2::SetTunerStatus method is called.

See also

GetModulation


IB2C2MPEG2TunerCtrl2::SetPolarity

Return to Top

Sets Polarity value.

Syntax

HRESULT SetPolarity(

long lPolarity

);

Parameters

lPolarity

[in] Polarity value. Use ePolarity enumerated type defined in header file b2c2_defs.h delivered as part of the SDK. Possible values are:

POLARITY_HORIZONTAL
POLARITY_VERTICAL

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Remarks

The value is sent to the tuner when IB2C2MPEG2TunerCtrl2::SetTunerStatus method is called.


IB2C2MPEG2TunerCtrl2::SetSymbolRate

Return to Top

Sets Symbol Rate value.

Syntax

HRESULT SetSymbolRate(

long lSymbolRate

);

Parameters

lSymbolRate

[in] Symbol Rate in KS/s. Must be greater than or equal to zero. The upper limit is tuner dependent and can be queried by GetTunerCapabilities.

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Remarks

The value is sent to the tuner when IB2C2MPEG2TunerCtrl2::SetTunerStatus method is called.

See also

GetSymbolRate; GetTunerCapabilities


IB2C2MPEG2TunerCtrl2::SetTunerStatus

Return to Top

Sends tuner parameter values to the tuner and waits until the tuner gets in lock or times out. The time-out value depends on the tuner type.

Syntax

HRESULT SetTunerStatus();

Parameters

None.

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Remarks

A successful return code indicates that the tuner is in lock.


IB2C2MPEG2TunerCtrl2::GetDiseqc

Return to Top

Gets current DiSEqC value.

Syntax

HRESULT GetDiseqc(

long * plDiseqc

);

Parameters

plDiseqc

[out] Pointer to a long variable created by the user where the DiSEqC value will be stored. eDiseqc enumerated types are defined in header file b2c2_defs.h delivered as part of the SDK. Possible values are:

DISEQC_NONE
DISEQC_SIMPLE_A
DISEQC_SIMPLE_B
DISEQC_LEVEL_1_A_A
DISEQC_LEVEL_1_B_A
DISEQC_LEVEL_1_A_B
DISEQC_LEVEL_1_B_B

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Remarks

None.


IB2C2MPEG2TunerCtrl2::GetFec

Return to Top

Gets current FEC value.

Syntax

HRESULT GetFec(

long * plFec

);

Parameters

plFec

[out] Pointer to a long variable created by the user where the FEC value will be stored. eFEC enumerated types are defined in header file b2c2_defs.h delivered as part of the SDK. Possible values are:

FEC_1_2
FEC_2_3
FEC_3_4
FEC_5_6
FEC_7_8
FEC_AUTO

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Remarks

None.


IB2C2MPEG2TunerCtrl2::GetGuardInterval

Return to Top

Gets current Guard Interval value.

Syntax

HRESULT GetGuardInterval(

long * plGuardInterval

);

Parameters

plGuardInterval

[out] Pointer to long variable where value for Guard Interval will be stored. eGuardInterval enumerated types are defined in header file b2c2_defs.h delivered as part of the SDK. Possible values are:

GUARD_INTERVAL_1_32
GUARD_INTERVAL_1_16
GUARD_INTERVAL_1_8
GUARD_INTERVAL_1_4
GUARD_INTERVAL_AUTO

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Remarks

None.


IB2C2MPEG2TunerCtrl2::GetLnbFrequency

Return to Top

Gets current LNB Frequency value.

Syntax

HRESULT GetLnbFrequency(

long * plFrequencyMHz

);

Parameters

plFrequencyMHz

[out] Pointer to a long variable created by the user where the LNB Frequency value in MHz will be stored.

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Remarks

None.


IB2C2MPEG2TunerCtrl2::GetLnbKHz

Return to Top

Gets current LNB kHz selection value.

Syntax

HRESULT GetLnbKHz(

long * plLnbKHz

);

Parameters

plLnbKHz

[out] Pointer to a long variable created by the user where the LNB kHz Selection value will be stored. eLNBSelection enumerated types are defined in header file b2c2_defs.h delivered as part of the SDK. Possible values are:

LNB_SELECTION_0
LNB_SELECTION_22
LNB_SELECTION_33
LNB_SELECTION_44

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Remarks

None.


IB2C2MPEG2TunerCtrl2::GetPolarity

Return to Top

Gets current Polarity value.

Syntax

HRESULT GetPolarity(

long * plPolarity

);

Parameters

plPolarity

[out] Pointer to a long variable created by the user where the Polarity value will be stored. ePolarity enumerated types are defined in header file b2c2_defs.h delivered as part of the SDK. Possible values are:

POLARITY_HORIZONTAL
POLARITY_VERTICAL

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Remarks

None.


IB2C2MPEG2TunerCtrl2::GetCorrectedBlocks

Return to Top

Gets current count of Corrected Blocks.

Syntax

HRESULT GetCorrectedBlocks(

long * plCount

);

Parameters

plCount

[out] Pointer to a variable created by the caller. Variable will hold count of Corrected Blocks.

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Remarks

The counter will be cleared after the function is called; the value returned is the number of Corrected Blocks since the last call of this function. This function is tuner dependent; use GetTunerCapabilities to determine whether or not it is supported by this tuner.


IB2C2MPEG2TunerCtrl2::SetFrequencyKHz

Return to Top

Sets Transponder Frequency value in kHz.

Syntax

HRESULT SetFrequencyKHz(

long lFrequencyKHz

);

Parameters

lFrequencyKHz

[in] Transponder Frequency in kHz. Must be greater than or equal to zero. The upper limit is tuner dependent.

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Remarks

The value is sent to the tuner when IB2C2MPEG2TunerCtrl2::SetTunerStatus method is called.

See also

SetFrequency


IB2C2MPEG2TunerCtrl2::SetGuardInterval

Return to Top

Sets Guard Interval value.

Syntax

HRESULT SetGuardInterval(

long lGuardInterval

);

Parameters

lGuardInterval

[in] Guard Interval value. Use eGuardInterval enumerated type defined in header file b2c2_defs.h delivered as part of the SDK. Possible values are:

GUARD_INTERVAL_1_32
GUARD_INTERVAL_1_16
GUARD_INTERVAL_1_8
GUARD_INTERVAL_1_4
GUARD_INTERVAL_AUTO

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Remarks

The value is sent to the tuner when IB2C2MPEG2TunerCtrl2::SetTunerStatus method is called.


IB2C2MPEG2TunerCtrl2::SetTunerStatusEx

Return to Top

Sends values to tuner for tuning with optional argument for defining how many times the SDK should check whether the tuner is in lock. The wait time between each check is 50 ms.

Syntax

HRESULT SetTunerStatusEx(

long lRepeatCheckLock

);

Parameters

lRepeatCheckLock

Number of times the SDK should check whether the tuner is in lock.

Return Value

Returns an HRESULT value. Use SUCCEEDED and FAILED macros to interpret the return value.

Remarks

A successful return code indicates that the tuner is in lock.


Copyright © 1998-2002 B2C2, Inc. Proprietary and Confidential