IAMTuner Interface

The IAMTuner interface is the base class for IAMTVTuner, which inherits all the IAMTuner methods. For more information on controlling a TV tuner using Microsoft® DirectShow®, see the IAMTVTuner documentation.

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 tuner is set to.
ChannelMinMax Retrieves the minimum and maximum channel available.
put_CountryCode Sets the country code to establish the frequency to use.
get_CountryCode Retrieves the country code.

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 a multifunction tuner to the specified mode.
get_Mode Retrieves the current mode on a multifunction tuner.
GetAvailableModes Retrieves the tuner's supported modes.
RegisterNotificationCallBack Allows an object that implements the IAMTunerNotification interface to receive event notifications when the tuner changes state.
UnRegisterNotificationCallBack Unregisters an object for event notifications.

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 tuner is set to.
ChannelMinMax	Retrieves the minimum and maximum channel available.
put_CountryCode	Sets the country code to establish the frequency to use.
get_CountryCode	Retrieves the country code.
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 a multifunction tuner to the specified mode.
get_Mode	Retrieves the current mode on a multifunction tuner.
GetAvailableModes	Retrieves the tuner's supported modes.
RegisterNotificationCallBack	Allows an object that implements the IAMTunerNotification interface to receive event notifications when the tuner changes state.
UnRegisterNotificationCallBack	Unregisters an object for event notifications.

IAMTuner::ChannelMinMax

IAMTuner Interface

Retrieves the highest and lowest channels available.

Syntax

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

Parameters

lChannelMin
[out] Pointer to a variable that receives the lowest channel.
lChannelMax
[out] Pointer to a variable that receives the highest channel.

Return Value

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

IAMTuner::get_Channel

IAMTuner Interface

Retrieves the TV channel that the tuner is set to.

Syntax

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

Parameters

plChannel
[out] Pointer to a variable that receives the channel. For frequencies, see Country/Region Codes and Channel-to-Frequency Mappings.
plVideoSubChannel
[out] Pointer to a variable that receives 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 variable that receives a predefined audio subchannel value. Specify AMTUNER_SUBCHAN_NO_TUNE for no tuning or AMTUNER_SUBCHAN_DEFAULT for default subchannel.

Return Value

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

IAMTuner::get_CountryCode

IAMTuner Interface

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

Syntax

HRESULT get_CountryCode(
    long *plCountryCode
);

Parameters

plCountryCode
[out] Pointer to a variable that receives the country code currently in use by the TV Tuner filter.

Return Value

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

Remarks

The 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. For a list of country codes, see Country/Region Codes and Channel-to-Frequency Mappings.

IAMTuner::get_Mode

IAMTuner Interface

Retrieves the current mode on a multifunction tuner.

Syntax

HRESULT get_Mode(
    AMTunerModeType *plMode
);

Parameters

plMode
[out] Pointer to a variable that receives a flag indicating the current mode setting. The possible values are defined in the AMTunerModeType enumeration.

Return Value

Returns an HRESULT value.

IAMTuner::get_TuningSpace

IAMTuner Interface

Retrieves the tuning space.

Syntax

HRESULT get_TuningSpace(
    long *plTuningSpace
);

Parameters

*plTuningSpace
[out] Pointer to a variable that receives the current tuning space.

Return Value

Returns an HRESULT value.

Remarks

The application defines the value retrieved by this method; it is set through a call to put_TuningSpace.

IAMTuner::GetAvailableModes

IAMTuner Interface

Retrieves the tuner's supported modes.

Syntax

HRESULT GetAvailableModes(
    long *plModes
);

Parameters

plModes
[out] Pointer to a variable that receives any combination of the values as specified in the AMTunerModeType enumeration.

Return Value

Returns an HRESULT value.

IAMTuner::Logon

IAMTuner Interface

Logs a user onto the system.

Syntax

HRESULT Logon(
    HANDLE hCurrentUser
);

Parameters

hCurrentUser
[in] Handle to an application-defined data structure that identifies the current user.

Return Value

Returns an HRESULT value.

Remarks

The Logon and Logout methods enable you to implement selective user access.

IAMTuner::Logout

IAMTuner Interface

Logs out the current user.

Syntax

HRESULT Logout(void);

Return Value

Returns an HRESULT value.

IAMTuner::put_Channel

IAMTuner Interface

Sets the TV channel.

Syntax

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. Meaningful only for satellite broadcasts.
lAudioSubChannel
Predefined audio subchannel value. Specify AMTUNER_SUBCHAN_NO_TUNE for no tuning or AMTUNER_SUBCHAN_DEFAULT for default subchannel. Meaningful only for satellite broadcasts.

Return Value

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. For a list of frequencies for channels, see Country/Region Codes and Channel-to-Frequency Mappings.

IAMTuner::put_CountryCode

IAMTuner Interface

Sets the country code to establish the frequency to use.

Syntax

HRESULT put_CountryCode(
    long lCountryCode
);

Parameters

lCountryCode
[in] Value indicating the country code.

Return Value

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.
Because channels in different countries map to different frequencies, worldwide mapping tables are provided in the Country/Region 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 put_CountryCode method. This is useful when a country wants to receive broadcast video from a different national source.

IAMTuner::put_Mode

IAMTuner Interface

Sets a multifunction tuner to the specified mode.

Syntax

HRESULT put_Mode(
    AMTunerModeType lMode
);

Parameters

lMode
[in] Flag indicating which mode to switch to. Possible values are defined in the AMTunerModeType enumeration.
You can also set the mode to digital TV if the card supports it. To do this, define AMTUNER_MODE_DTV with a value of 0x0010.

Return Value

Returns an HRESULT value.

IAMTuner::put_TuningSpace

IAMTuner Interface

Sets a storage index for regional channel-to-frequency mappings.

Syntax

HRESULT put_TuningSpace(
    long lTuningSpace
);

Parameters

lTuningSpace
[in] Value indicating the current locale.

Return Value

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.

IAMTuner::RegisterNotificationCallBack

IAMTuner Interface

Allows an object that implements the IAMTunerNotification interface to receive event notifications when the tuner changes state.

Syntax

HRESULT RegisterNotificationCallBack(
    IAMTunerNotification *pNotify
    long lEvents
);

Parameters

pNotify
[in] Pointer to the IAMTunerNotification interface of an object that will receive the tuner event notifications.
lEvents
[in] Flag indicating that an event has occurred. The only value currently defined is AMTUNER_EVENT_CHANGED.

Return Value

Returns an HRESULT value.

IAMTuner::SignalPresent

IAMTuner Interface

Retrieves the strength of the signal on a given channel.

Syntax

HRESULT SignalPresent(
    long *plSignalStrength
);

Parameters

plSignalStrength
[out] Pointer to a variable that receives a value indicating whether a signal is present on the current channel. Can be one of the following values.
AMTUNER_HASNOSIGNALSTRENGTH -1
AMTUNER_NOSIGNAL 0
AMTUNER_SIGNALPRESENT 1

A value of AMTUNER_HASNOSIGNALSTRENGTH means the signal strength cannot be determined at this time.

Return Value

Returns an HRESULT value.

IAMTuner::UnRegisterNotificationCallBack

IAMTuner Interface

Unregisters an object for event notifications.

Syntax

HRESULT UnRegisterNotificationCallBack(
    IAMTunerNotification *pNotify
);

Parameters

pNotify
[in] Pointer to the IAMTunerNotification interface that was specified in a previous call to RegisterNotificationCallBack.

Return Value

Returns an HRESULT value.

AMTUNER_HASNOSIGNALSTRENGTH	-1
AMTUNER_NOSIGNAL	0
AMTUNER_SIGNALPRESENT	1