IAMTVTuner Interface

The IAMTVTuner interface is implemented on filters that provide TV tuning capabilities. A TV tuner filter is a device that selects an analog broadcast or cable channel to be viewed. The IAMTVTuner interface enables applications to set these transmission types through the TunerInputType enumerated data type.

Because Microsoft® Video for Windows® wasn't written with TV tuning capabilities in mind, you can implement TV tuner filters only on operating systems that can interpret TV tuning information. The Windows Driver Model implements a version that contains international channel to frequency mapping tables, found in the Country Codes and Channel to Frequency Mappings appendix, which you can use in a filter graph.

The IAMTVTuner interface supports multistandard analog decoders, which you can enumerate and select by using the get_AvailableTVFormats method. The AnalogVideoStandard data type contains these formats, which include NTSC, PAL, and SECAM, among others. IAMTVTuner also supports tuners with multiple input pins, to allow for multiple devices and multiple transmission types.

IAMTVTuner also maps TV channels to specific frequencies through the IAMTVTuner::put_Channel and IAMTVTuner::AutoTune methods. These methods handle the details of the conversion so that the hardware driver receives an exact frequency. Because channels in different countries map to different frequencies, worldwide mapping tables are provided in the Country Codes and Channel to Frequency Mappings appendix. Override the existing country code by selecting the new value from the appendix and passing it in as the parameter for the IAMTVTuner::put_CountryCode method. This is useful when a country wants to receive broadcast video from a different national source.

When to Implement

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

When to Use

Use this interface when setting TV channels and to get or set information about their frequencies. This interface can also determine what analog video standards your TV supports.

Methods in Vtable Order

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

IAMTVTuner methods	Description
get_AvailableTVFormats	Retrieves all the analog video TV standards that are supported by the tuner.
get_TVFormat	Retrieves the current analog video TV standard in use.
put_Channel	Sets the TV channel.
get_Channel	Retrieves the current TV channel set by put_Channel.
ChannelMinMax	Retrieves the highest and lowest channels available.
AutoTune	Scans for a precise signal on the channel's frequency.
StoreAutoTune	Saves the fine-tuning information for all channels.
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 set in put_TuningSpace.
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 (Cable or Antenna) set in put_InputType.
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.

HRESULT AutoTune(
  long lChannel,
  long * plFoundSignal
  );

Parameters

lChannel

[in] TV channel number.

plFoundSignal

[out] Value indicating whether the channel's frequency was found; TRUE indicates found, FALSE indicates not found.

Return Values

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 US, 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. Base frequencies for channels can be found in the Country Codes and Channel to Frequency Mappings appendix.

---

IAMTVTuner::ChannelMinMax

IAMTVTuner Interface

Retrieves the highest and lowest channels available.

HRESULT ChannelMinMax(
  long *lChannelMin,
  long *lChannelMax
  );

Parameters

lChannelMin

[out] Pointer to the lowest channel.

lChannelMax

[out] Pointer to the highest channel.

Return Values

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

Remarks

Frequencies for channels are found in the Country Codes and Channel to Frequency Mappings appendix.

---

IAMTVTuner::get_AudioFrequency

IAMTVTuner Interface

Retrieves the currently tuned audio frequency.

HRESULT get_ AudioFrequency(
  long *lFreq
  );

Parameters

lFreq

[out] Pointer to the audio frequency.

Return Values

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

---

IAMTVTuner::get_AvailableTVFormats

IAMTVTuner Interface

Retrieves all the analog video TV standards that are supported by the tuner.

HRESULT get_ AvailableTVFormats(
  long *lAnalogVideoStandard
  );

Parameters

lAnalogVideoStandard

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

Return Values

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

Remarks

See the AnalogVideoStandard enumerated data type for supported formats.

---

IAMTVTuner::get_Channel

IAMTVTuner Interface

Retrieves the current TV channel set by put_Channel.

HRESULT get_Channel (
  long * plChannel,
  long *plVideoSubChannel,
  long *plAudioSubChannel
  );

Parameters

plChannel

[out] Pointer to the channel.

plVideoSubChannel

[out] Pointer to a predefined video subchannel value. Specify AMTUNER_SUBCHAN_NO_TUNE for no tuning or AMTUNER_SUBCHAN_DEFAULT for default subchannel.

plAudioSubChannel

[out] Pointer to a predefined audio subchannel value. Specify AMTUNER_SUBCHAN_NO_TUNE for no tuning or AMTUNER_SUBCHAN_DEFAULT for default subchannel.

Return Values

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

Remarks

See the Country Codes and Channel to Frequency Mappings appendix for frequencies for plChannel.

---

IAMTVTuner::get_ConnectInput

IAMTVTuner Interface

Retrieves the hardware tuner input connection.

HRESULT get_ConnectInput (
  long *plIndex
  );

Parameters

plIndex

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

Return Values

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

---

IAMTVTuner::get_CountryCode

IAMTVTuner Interface

Retrieves the country code that establishes the current channel to frequency mapping.

HRESULT get_CountryCode (
  long * plCountryCode
  );

Parameters

plCountryCode

[in] Country code currently in use by the TV Tuner filter.

Return Values

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

Remarks

The IAMTVTuner::put_CountryCode method determines which channel to frequency mapping table to use. This establishes the base frequencies for the given country. Use the IAMTVTuner::AutoTune method to determine the exact frequencies for specific regions.

Override the country code when a country wants to receive broadcast video from a different national source. See the Country Codes and Channel to Frequency Mappings appendix for a list of country codes.

---

IAMTVTuner::get_InputType

IAMTVTuner Interface

Retrieves the input type set in put_InputType.

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 Values

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.

HRESULT get_ NumInputConnections(
  long * plNumInputConnections
  );

Parameters

plNumInputConnections

[out] Number of TV sources plugged into the tuner filter.

Return Values

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

---

IAMTVTuner::get_TuningSpace

IAMTVTuner Interface

Gets the storage index for regional fine tuning set in put_TuningSpace.

HRESULT get_TuningSpace(
  long * plTuningSpace
  );

Parameters

plTuningSpace

[out] Value specifying the current locale.

Return Values

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

Remarks

As TV tuners move into portable systems, you must retain locale-specific mappings of available channels and their actual frequencies. Formulating different lTuningSpace values for each locale provides a way of switching the channel/frequency mappings when moving from region to region.

---

IAMTVTuner::get_TVFormat

IAMTVTuner Interface

Retrieves the current analog video TV standard in use.

HRESULT get_ TVFormat(
  long * plAnalogVideoStandard );

Parameters

plAnalogVideoStandard

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

Return Values

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

Remarks

See the AnalogVideoStandard enumerated data type for supported formats.

---

IAMTVTuner::get_VideoFrequency

IAMTVTuner Interface

Retrieves the current video frequency.

HRESULT get_VideoFrequency(
  long *lFreq
  );

Parameters

lFreq

[out] Pointer to the video frequency.

Return Values

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

---

IAMTVTuner::put_Channel

IAMTVTuner Interface

Sets the TV channel.

HRESULT put_ Channel(
  long lChannel,
  long lVideoSubChannel,
  long lAudioSubChannel
  );

Parameters

lChannel

[in] TV channel number.

lVideoSubChannel

Predefined video subchannel value. Specify AMTUNER_SUBCHAN_NO_TUNE for no tuning or AMTUNER_SUBCHAN_DEFAULT for default subchannel.

lAudioSubChannel

Predefined audio subchannel value. Specify AMTUNER_SUBCHAN_NO_TUNE for no tuning or AMTUNER_SUBCHAN_DEFAULT for default subchannel.

Return Values

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

Remarks

This method handles the channel to frequency function call that converts the TV channel to a TV frequency. Frequencies for channels are found in the Country Codes and Channel to Frequency Mappings appendix.

---

IAMTVTuner::put_ConnectInput

IAMTVTuner Interface

Sets the hardware tuner input connection.

HRESULT put_ ConnectInput(
  long lIndex
  );

Parameters

lIndex

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

Return Values

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

---

IAMTVTuner::put_CountryCode

IAMTVTuner Interface

Sets the country code to establish the frequency to use.

HRESULT put_ CountryCode(
  long lCountryCode
  );

Parameters

lCountryCode

[in] Value indicating the country code.

Return Values

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

Remarks

This method establishes the base frequencies for the given country. Use the IAMTVTuner::AutoTune method to determine the exact frequencies for specific regions, unless there are previously cached settings for the new country.

Override the country code when a country wants to receive broadcast video from a different national source. See the Country Codes and Channel to Frequency Mappings appendix for a list of country codes.

---

IAMTVTuner::put_InputType

IAMTVTuner Interface

Sets the tuner input type (cable or antenna).

HRESULT put_ InputType(
  long lIndex,
  TunerInputType InputType
  );

Parameters

lIndex

[in] Index value that specifies the input pin to be set.

InputType

[in] Indicates the connection type, as specified in the TunerInputType data type.

Return Values

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

---

IAMTVTuner::put_TuningSpace

IAMTVTuner Interface

Sets a storage index for regional channel to frequency mappings.

HRESULT put_TuningSpace(
  long lTuningSpace
  );

Parameters

lTuningSpace

[in] Value indicating the current locale.

Return Values

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

Remarks

As TV tuners move into portable systems, you must retain locale-specific mappings of available channels and their actual frequencies. Formulating different lTuningSpace values for each locale provides a way of switching the channel to frequency mappings when moving from region to region.

---

IAMTVTuner::StoreAutoTune

IAMTVTuner Interface

Saves the fine-tuning information for all channels.

HRESULT StoreAutoTune( );

Return Values

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 IAMTVTuner::put_CountryCode method. See the Country Codes and Channel to Frequency Mappings appendix for a listing of country codes.

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Top of Page