Microsoft DirectX 8.0

ITuner Interface

ITuner is implemented on the Network Provider filter.

MethodNameDescription
get_TuningSpaceGets the Tuning Space currently in effect for the Network Provider.
put_TuningSpaceSets the Tuning Space for the Network Provider.
EnumTuningSpacesCreates a collection of the Tuning Spaces preferred by this implementation.
get_TuneRequestGets the Tune Request currently in effect for the Network Provider.
put_TuneRequestSets the Tune Request for the Network Provider.
ValidateReturns a value indicating that the Tune Request can be carried out.
get_PreferredComponentTypesGets the collection of ComponentType objects used for default component selection.
put_PreferredComponentTypesSets the collection of ComponentType objects used for default component selection.
get_SignalStrengthRetrieves the Network Provider-specific signal strength metric.
TriggerSignalEventsPuts the Network Provider into a mode where ISignalEvents::OnSignal will be repeatedly called.

ITuner::get_TuningSpace

ITuner Interface

Gets the Tuning Space currently in effect for the Network Provider.

Syntax

HRESULT get_TuningSpace(
    ITuningSpace** TuningSpace
    );

Parameters

TuningSpace
[out, retval] Address of an ITuningSpace interface pointer that will be set to the current Tuning Space.

Return Value

Returns S_OK if successful. If the method fails, error information can be retrieved using the standard COM IErrorInfo interface.

ITuner::put_TuningSpace

ITuner Interface

Sets the Tuning Space for the Network Provider.

Syntax

HRESULT put_TuningSpace(
    ITuningSpace* TuningSpace
    );

Parameters

TuningSpace
[in] Pointer to the Tuning Space that will be set in the Network Provider.

Return Value

Returns S_OK if successful. If the method fails, error information can be retrieved using the standard COM IErrorInfo interface.

ITuner::EnumTuningSpaces

ITuner Interface

Creates a collection of Tuning Spaces preferred by this implementation.

Syntax

HRESULT EnumTuningSpaces(
    IEnumTuningSpaces** ppEnum
    );

Parameters

ppEnum
[out, retval] Address of a IEnumTuningSpaces interface pointer that will be set to the returned collection.

Return Value

Returns S_OK if successful. If the method fails, error information can be retrieved using the standard COM IErrorInfo interface.

Remarks

This list is a subset of the compatible tuning spaces for this implementation.

ITuner::get_TuneRequest

ITuner Interface

Gets the Tune Request currently in effect for the Network Provider.

Syntax

HRESULT get_TuneRequest(
    ITuneRequest** TuneRequest
    );

Parameters

TuneRequest
[out, retval] Address of an ITuneRequest interface pointer that will be set to the returned object.

Return Value

Returns S_OK if successful. If the method fails, error information can be retrieved using the standard COM IErrorInfo interface.

Remarks

After a Tune Request is submitted to the Tuner, its Components collection will be filled in. By calling get_TuneRequest after tuning to the program, an application can determine which components are currently available for that program, and then use the IComponent::put_Status method on the Component objects in the collection to activate or inactivate them. This is how an application, for example, changes from an English audio stream to a Spanish audio stream.

ITuner::put_TuneRequest

ITuner Interface

Sets the Tune Request currently in effect for the Network Provider.

Syntax

HRESULT put_TuneRequest(
    ITuneRequest* TuneRequest
    );

Parameters

TuneRequest
[in] Pointer to an ITuneRequest object that will be used to set the Network Provider.

Return Value

Returns S_OK if successful. If the method fails, error information can be retrieved using the standard COM IErrorInfo interface.

Remarks

Calling this method initiates a tuning operation based on the properties of the Tune Request. The tuning operation may be asynchronously attempted.

ITuner::Validate

ITuner Interface

Returns a value indicating that the Tune Request can be carried out.

Syntax

HRESULT Validate(
    ITuneRequest* TuneRequest
    );

Parameters

TuneRequest
[in] Pointer to the Tune Request object

Return Value

Returns S_OK if successful. If the method fails, error information can be retrieved using the standard COM IErrorInfo interface.

Remarks

Takes an IUnknown* as input. the Network Provider will first Query for its preferred Tune Request interface(s). If any are found, the Network Provider will validate that the tune request could be carried out. If none are available, it will then query for its preferred Tuning Space interface(s). If any are found, the Network Provider will validate that if could configure itself for the given tuning space.

ITuner::get_PreferredComponentTypes

ITuner Interface

Gets the collection of ComponentType objects used for default component selection.

Syntax

HRESULT get_PreferredComponentTypes(
    IComponentTypes** ComponentTypes
    );

Parameters

ComponentTypes
[out, retval] Address of an IComponentTypes interface pointer that receives the collection of ComponentType objects.

Return Value

Returns S_OK if successful. If the method fails, error information can be retrieved using the standard COM IErrorInfo interface.

Remarks

When a program ends, there may be a new set of substreams ("components") available, so at that time the Tuner will automatically examine the list of preferred component types and select a substream based on that list. If no list is available, the Tuner will make a selection based on other factors. Applications call this method simply to examine the current list.

ITuner::put_PreferredComponentTypes

ITuner Interface

Sets the collection of ComponentType objects used for default component selection.

Syntax

HRESULT put_PreferredComponentTypes(
    IComponentTypes* ComponentTypes
    );

Parameters

ComponentTypes
[in] Pointer to an IComponentTypes interface that contains the collection of ComponentType objects.

Return Value

Returns S_OK if successful. If the method fails, error information can be retrieved using the standard COM IErrorInfo interface.

Remarks

Applications create a list of preferred component types by instantiating an empty ComponentTypes collection, filling it, then submitting it to the Tuner using put_PreferredComponentTypes.

ITuner::get_SignalStrength

ITuner Interface

Retrieves the Network Provider-specific signal strength metric.

Syntax

HRESULT get_SignalStrength(
    long* Strength
    );

Parameters

Strength
[out, retval] Pointer to a variable of type long that receives the signal strength.

Return Value

Returns S_OK if successful. If the method fails, error information can be retrieved using the standard COM IErrorInfo interface.

Remarks

-1 means can't determine, 0 means not tuned, highest value means best signal. For digital tuners, this also accounts for the FEC bit error rate (BER).

ITuner::TriggerSignalEvents

ITuner Interface

Puts the Network Provider into a mode where ISignalEvents::OnSignal will be repeatedly called.

Syntax

HRESULT TriggerSignalEvents(
    long Interval
    );

Parameters

Interval
[in] Variable of type long that specifies the interval at which to send the trigger events.

Return Value

Returns S_OK if successful. If the method fails, error information can be retrieved using the standard COM IErrorInfo interface.

Remarks

Returns E_NOTIMPL if this mode isn't supported. Takes an interval in milliseconds, specifying the rate at which Signal events are generated.