B2C2, Inc. - Software Development Kit |
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.
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.
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.
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. |
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.
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
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
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
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.
The GetSignalLevel function is obsolete and is implemented for backwards compatibility only. Current version uses GetSignalStrength or GetSignalQuality method, depending on the tuner type.
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.
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).
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).
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.
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
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.
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.
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.
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.
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
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.
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.
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
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.
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.
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
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.
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
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.
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.
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.
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.
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.
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.
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.
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.
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
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.
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.