IAMTVTuner Interface

The IAMTVTuner interface inherits from IAMTuner and provides methods that enable an application to control a TV tuner device. The interface supports tuners for analog broadcast television, AM/FM, Digital Satellite Service (DSS), and digital television. The Microsoft-supplied TV Tuner filter for Microsoft® Windows® Driver Model (WDM) tuner devices, which implements this interface, supports worldwide tuning coverage.

The basic order of operations when controlling a TV tuner card is as follows:

If necessary, establish a video path from the tuner through a crossbar to the video digitizer using the IAMCrossbar interface.
Call the IAMTuner::put_Mode method to set the tuner card to the type of broadcast to be received (analog TV, digital TV, AM radio, FM radio, and so on).
Set the country code with IAMTuner::put_CountryCode to establish the correct TV channel-to-frequency mappings.
For each input on the tuner, call put_InputType to set the input type to cable or antenna. Use put_ConnectInput to select one of the available tuner inputs.
Call get_TVFormat to retrieve the current video format, and then use this value to set the analog video decoder filter with a call to IAMAnalogVideoDecoder::put_TVFormat.
Call IAMTuner::put_Channel to begin viewing.

IAMTVTuner supports tuners with multiple input pins, to allow for multiple devices and multiple transmission types.

IAMTVTuner maps TV channels to specific frequencies through the IAMTuner::put_Channel and IAMTVTuner::AutoTune methods. These methods handle the details of the conversion so that the hardware driver receives an exact frequency.

Implement this interface when you write a filter that can tune a TV tuner card.

Use this interface from an application to set TV channels and to get or set information about their frequencies. This interface can also determine what analog video standards your TV tuner card supports.

Methods in Vtable Order

IUnknown methods Description
QueryInterface Retrieves pointers to supported interfaces.
AddRef Increments the reference count.
Release Decrements the reference count.

IAMTuner methods Description

put_Channel Sets the TV channel.
get_Channel Retrieves the TV channel that the encoder is currently set to.
ChannelMinMax Retrieves the highest and lowest channels available.
put_CountryCode Sets the country code to establish the frequency to use.
get_CountryCode Retrieves the country code that establishes the current channel-to-frequency mapping.
put_TuningSpace Sets a storage index for regional channel-to-frequency mappings.
get_TuningSpace Retrieves the storage index for regional fine tuning.
Logon Logs a user onto the system.
Logout Logs a user off the system.
SignalPresent Retrieves the strength of the signal on a given channel.
put_Mode Sets the mode of operation for a multifunction tuner.
get_Mode Retrieves the mode of operation for a multifunction tuner.
GetAvailableModes Determines which video modes are available on the tuner.
RegisterNotificationCallBack Allows an object that implements the IAMTunerNotification interface to receive event notifications when the tuner changes state.
UnRegisterNotificationCallBack Unregister an object for notification of events.

IAMTVTuner methods Description

get_AvailableTVFormats Retrieves all the analog video TV standards that the tuner supports.
get_TVFormat Retrieves the current analog video TV standard in use.
AutoTune Scans for a precise signal on the channel's frequency.
StoreAutoTune Saves the fine-tuning information for all channels.
get_NumInputConnections Retrieves the number of TV sources plugged into the tuner filter.
put_InputType Sets the tuner input type (cable or antenna).
get_InputType Retrieves the input type.
put_ConnectInput Sets the hardware tuner input connection.
get_ConnectInput Retrieves the hardware tuner input connection.
get_VideoFrequency Retrieves the current video frequency.
get_AudioFrequency Retrieves the current audio frequency.

IUnknown methods	Description
QueryInterface	Retrieves pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IAMTuner methods	Description
put_Channel	Sets the TV channel.
get_Channel	Retrieves the TV channel that the encoder is currently set to.
ChannelMinMax	Retrieves the highest and lowest channels available.
put_CountryCode	Sets the country code to establish the frequency to use.
get_CountryCode	Retrieves the country code that establishes the current channel-to-frequency mapping.
put_TuningSpace	Sets a storage index for regional channel-to-frequency mappings.
get_TuningSpace	Retrieves the storage index for regional fine tuning.
Logon	Logs a user onto the system.
Logout	Logs a user off the system.
SignalPresent	Retrieves the strength of the signal on a given channel.
put_Mode	Sets the mode of operation for a multifunction tuner.
get_Mode	Retrieves the mode of operation for a multifunction tuner.
GetAvailableModes	Determines which video modes are available on the tuner.
RegisterNotificationCallBack	Allows an object that implements the IAMTunerNotification interface to receive event notifications when the tuner changes state.
UnRegisterNotificationCallBack	Unregister an object for notification of events.
IAMTVTuner methods	Description
get_AvailableTVFormats	Retrieves all the analog video TV standards that the tuner supports.
get_TVFormat	Retrieves the current analog video TV standard in use.
AutoTune	Scans for a precise signal on the channel's frequency.
StoreAutoTune	Saves the fine-tuning information for all channels.
get_NumInputConnections	Retrieves the number of TV sources plugged into the tuner filter.
put_InputType	Sets the tuner input type (cable or antenna).
get_InputType	Retrieves the input type.
put_ConnectInput	Sets the hardware tuner input connection.
get_ConnectInput	Retrieves the hardware tuner input connection.
get_VideoFrequency	Retrieves the current video frequency.
get_AudioFrequency	Retrieves the current audio frequency.

IAMTVTuner::AutoTune

IAMTVTuner Interface

Scans for a precise signal on the channel's frequency.

Syntax

HRESULT AutoTune(
    long lChannel,
    long *plFoundSignal
);

Parameters

lChannel
[in] TV channel number.
plFoundSignal
[out] Pointer to a variable indicating whether the channel's frequency was found; nonzero indicates found, zero indicates not found.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

TV channels generally map to a unique frequency depending on regional variances. To avoid interference between multiple transmitters that are assigned the same channel when they are in close geographic proximity, small frequency offsets are introduced at each transmitter. In the United States, this offset ranges up to +/– 26.25 kilohertz (kHz).
This method handles the channel-to-frequency conversion and scans for the most precise frequency. Store these values by calling the IAMTVTuner::StoreAutoTune method. You can find base frequencies for channels in the Country/Region Codes and Channel-to-Frequency Mappings appendix.

IAMTVTuner::get_AudioFrequency

IAMTVTuner Interface

Retrieves the currently tuned audio frequency.

Syntax

HRESULT get_AudioFrequency(
    long *lFreq
);

Parameters

lFreq
[out] Pointer to the audio frequency.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

This is a diagnostic method that enables you to examine the exact frequency being used for a given channel.

IAMTVTuner::get_AvailableTVFormats

IAMTVTuner Interface

Retrieves all the analog video TV standards that the tuner supports.

Syntax

HRESULT get_AvailableTVFormats(
    long *lAnalogVideoStandard
);

Parameters

lAnalogVideoStandard
[out] Pointer to the combination of supported analog video standards.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

For supported formats, see the AnalogVideoStandard enumerated data type.

IAMTVTuner::get_ConnectInput

IAMTVTuner Interface

Retrieves the hardware tuner input connection.

Syntax

HRESULT get_ConnectInput (
    long *plIndex
);

Parameters

plIndex
[out] Pointer to the input pin to get the connection for.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

IAMTVTuner::get_InputType

IAMTVTuner Interface

Retrieves the input type set in put_InputType.

Syntax

HRESULT get_InputType (
    long lIndex,
    TunerInputType *pInputType
);

Parameters

lIndex
[in] Index value that specifies the input pin that will be set.
pInputType
[out] Pointer to the TunerInputType connection type; either cable (TunerInputCable) or antenna (TunerInputAntenna).

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

IAMTVTuner::get_NumInputConnections

IAMTVTuner Interface

Retrieves the number of TV sources plugged into the tuner filter.

Syntax

HRESULT get_NumInputConnections(
    long *plNumInputConnections
);

Parameters

plNumInputConnections
[out] Pointer to the number of TV sources plugged into the tuner filter.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

IAMTVTuner::get_TVFormat

IAMTVTuner Interface

Retrieves the current analog video TV standard in use.

Syntax

HRESULT get_TVFormat(
    long *plAnalogVideoStandard
);

Parameters

plAnalogVideoStandard
[out] Pointer to the analog video standard currently in use by the TV Tuner filter.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

For supported formats, see the AnalogVideoStandard enumerated data type.

IAMTVTuner::get_VideoFrequency

IAMTVTuner Interface

Retrieves the current video frequency.

Syntax

HRESULT get_VideoFrequency(
    long *lFreq
);

Parameters

lFreq
[out] Pointer to the video frequency.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

This is a diagnostic method that enables you to examine the exact frequency being used for a given channel.

IAMTVTuner::put_ConnectInput

IAMTVTuner Interface

Sets the hardware tuner input connection.

Syntax

HRESULT put_ConnectInput(
    long lIndex
);

Parameters

lIndex
[in] Index value of the input pin to set connection for.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

IAMTVTuner::put_InputType

IAMTVTuner Interface

Sets the tuner input type (cable or antenna).

Syntax

HRESULT put_InputType(
    long lIndex,
    TunerInputType InputType
);

Parameters

lIndex
[in] Index value that specifies the input pin to be set.
InputType
[in] Value indicating the connection type, as specified in the TunerInputType data type.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

IAMTVTuner::StoreAutoTune

IAMTVTuner Interface

Saves the fine-tuning information for all channels.

Syntax

HRESULT StoreAutoTune(void);

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

Override the channel-to-frequency information stored by this method by setting a new country code in the IAMTuner::put_CountryCode method. For a listing of country codes, see Country/Region Codes and Channel-to-Frequency Mappings.