Microsoft DirectX 8.0

ITuningSpace Interface

The ITuningSpace interface is the base class that provides the common functionality for all network-specific tuning spaces. The Tuning Space Container will never co-create an instance of an object that exposes only ITuningSpace, but always an object that supports some interface derived from ITuningSpace, such as IASTCTuningSpace.

MethodNameDescription
get_UniqueNameRetrieves a unique name for the Tuning Space. Can be either a short name, or a GUID.
put_UniqueNameSets a unique name for the Tuning Space. Can be either a short name, or a GUID.
get_FriendlyNameRetrieves the localized, user-friendly name of the Tuning Space.
put_FriendlyNameSets the localized, user-friendly name of the Tuning Space.
get_CLSIDGets the CLSID of the tuning space as a BSTR.
get_NetworkTypeRetrieves the network type of the tuning space as a BSTR.
put_NetworkTypeSets the network type for this tuning space as a BSTR.
get__NetworkTypeRetrieves the network type of the tuning space as a GUID.
put__NetworkTypeSets the network type for this tuning space as a REFCLSID.
CreateTuneRequestCreates a COM object representing an empty (uninitialized) Tune Request.
EnumCategoryGUIDs(Currently not implemented.) Creates an enumerator for the DirectShow category GUIDs, representing classes of filters that support the tuning space.
EnumDeviceMonikers(Currently not implemented.) Creates an enumerator of device monikers representing the tuner inputs (filters) supporting this tuning space.
get_DefaultPreferredComponentTypesReturns an enumeration of the preferred component types, which specify parameters such as the preferred audio stream.
put_DefaultPreferredComponentTypesCreates an enumeration of the preferred component types, which specify parameters such as the preferred audio stream.
get_FrequencyMappingRetrieves the frequency mapping previously created by the network provider by a call to put_FrequencyMapping.
put_FrequencyMappingCreates a frequency/channel map, frequency/transponder map, or whatever other mapping from carrier frequencies to frequency identifiers is appropriate for the tuning space.
get_DefaultLocatorRetrieves the default Locator on the local system.
put_DefaultLocatorSets the default Locator on the local system.
CloneCreates a new copy of the tuning space.

ITuningSpace::get_UniqueName

ITuningSpace Interface

Retrieves a unique name for the Tuning Space. Can be either a short name, or a GUID.

Syntax

HRESULT get_UniqueName(
    BSTR* Name
    );

Parameters

Name
[out, retval] Pointer to a variable of type BSTR that receives the unique name.

Return Value

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

Remarks

The unique name can be any string that is globally unique.

ITuningSpace::put_UniqueName

ITuningSpace Interface

Sets a unique name for the Tuning Space. Can be either a short name, or a GUID.

Syntax

HRESULT put_UniqueName(
    BSTR Name
    );

Parameters

Name
[in] Variable of type BSTR that specifies the unique name.

Return Value

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

ITuningSpace::get_FriendlyName

ITuningSpace Interface

Retrieves the localized, user-friendly name of the Tuning Space.

Syntax

HRESULT get_FriendlyName(
    BSTR* Name
    );

Parameters

Name
[out, retval] Pointer to a variable of type BSTR that receives the user-friendly name.

Return Value

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

ITuningSpace::put_FriendlyName

ITuningSpace Interface

Sets the localized, user-friendly name of the Tuning Space.

Syntax

HRESULT put_FriendlyName(
    BSTR Name
    );

Parameters

Name
[in] Variable of type BSTR that specifies the user-friendly name.

Return Value

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

ITuningSpace::get_CLSID

ITuningSpace Interface

Gets the CLSID of the tuning space as a BSTR.

Syntax

HRESULT get_CLSID(
    BSTR* SpaceCLSID
    );

Parameters

SpaceCLSID
[out, retval] Pointer to a variable of type BSTR that receives the CLSID of the tuning space.

Return Value

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

Remarks

This method provides script access to the IPersist::GetClassID method.

ITuningSpace::get_NetworkType

ITuningSpace Interface

Retrieves the network type of the tuning space as a BSTR.

Syntax

HRESULT get_NetworkType(
    BSTR* NetworkTypeGuid
    );

Parameters

NetworkTypeGuid
[out, retval] Pointer to a variable of type BSTR that receives the GUID that indicates the network type.

Return Value

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

Remarks

Use the GUID retrieved in this method as the CLSID when creating the Network Provider filter when building the filter graph. This method is provided for Visual Basic® and scripting applications. C++ applications should use get__NetworkType to retrieve the network type as a native GUID data type.

ITuningSpace::put_NetworkType

ITuningSpace Interface

Specifies the network type of the tuning space as a BSTR.

Syntax

HRESULT put_NetworkType(
    BSTR NetworkTypeGuid
    );

Parameters

NetworkTypeGuid
[in] Variable of type BSTR that specifies the network type.

Return Value

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

Remarks

This method is provided for Visual Basic® and scripting applications. C++ applications should use put__NetworkType.

ITuningSpace::get__NetworkType

ITuningSpace Interface

Retrieves the network type of the tuning space as a GUID.

Syntax

HRESULT get_NetworkType(
    GUID* NetworkTypeGuid
    );

Parameters

NetworkTypeGuid
[out, retval] Pointer to a variable of type GUID that receives the network type.

Return Value

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

Remarks

Use the GUID retrieved in this method as the CLSID when creating the Network Provider filter when building the filter graph.

ITuningSpace::put__NetworkType

ITuningSpace Interface

Specifies the network type of the tuning space as a REFCLSID.

Syntax

HRESULT put__NetworkType(
    REFCLSID NetworkTypeGuid
    );

Parameters

NetworkTypeGuid
[in] Variable of type REFCLSID that specifies the network type.

Return Value

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

ITuningSpace::CreateTuneRequest

ITuningSpace Interface

Creates a COM object representing an empty (uninitialized) Tune Request.

Syntax

HRESULT CreateTuneRequest(
    ITuneRequest** TuneRequest
    );

Parameters

TuneRequest
[out, retval] Address of an ITuneRequest interface pointer that receives the new 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

This method returns the ITuneRequest base class interface, but this interface cannot be used to create a tune request. To create a tune request you must use the derived interface that is associated with the type of tuning space you are using. To obtain the derived interface, call QueryInterface on the returned ITuneRequest object and specify the required interface. The following table shows the relationships between tuning spaces and tune requests.

Tuning SpaceTune Request
IAnalogTVTuningSpaceIID_IChannelTuneRequest
IAnalogRadioTuningSpaceIID_IChannelTuneRequest
IDVBTuningSpaceIID_IDVBTuneRequest
IATSCTuningSpaceIID_IATSCChannelTuneRequest

ITuningSpace::EnumCategoryGUIDs

ITuningSpace Interface

(Currently not implemented.) Creates an enumerator for the DirectShow category GUIDs, representing classes of filters that support the tuning space.

Syntax

HRESULT EnumCategoryGUIDs(
    IEnumGUID** ppEnum
    );

Parameters

ppEnum
[out, retval] Address of an IEnumGUID interface pointer that receives the returned enumeration object.

Return Value

Returns E_NOTIMPL.

Remarks

This method is hidden from automation languages.

ITuningSpace::EnumDeviceMonikers

ITuningSpace Interface

(Currently not implemented.) Creates an enumerator of device monikers representing the tuner inputs (filters) supporting this tuning space.

Syntax

HRESULT EnumDeviceMonikers(
    IEnumMoniker** ppEnum
    );

Parameters

ppEnum
[out, retval] Address of an IEnumMoniker interface pointer that receives the returned enumeration object.

Return Value

Returns E_NOTIMPL.

Remarks

This method is hidden from automation languages.

ITuningSpace::get_DefaultPreferredComponentTypes

ITuningSpace Interface

Returns an enumeration of the preferred component types, which specify parameters such as the preferred audio stream.

Syntax

HRESULT get_DefaultPreferredComponentTypes(
    IComponentTypes** ComponentTypes
    );

Parameters

ComponentTypes
[out, retval] Address of an IComponentTypes interface pointer that receives 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

A "component" in this context means a stream within the program. An example of a "preferred component" would be an audio stream in English. When multiple components or streams are available, the Tuner will always attempt to play the preferred ones first.

ITuningSpace::put_DefaultPreferredComponentTypes

ITuningSpace Interface

Creates an enumeration of the preferred component types, which specify parameters such as the preferred audio stream.

Syntax

HRESULT put_DefaultPreferredComponentTypes(
    IComponentTypes* NewComponentTypes
    );

Parameters

NewComponentTypes
[in] Pointer to an IComponentTypes interface on the ComponentTypes object that specifies the default preferred component types.

Return Value

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

ITuningSpace::get_FrequencyMapping

ITuningSpace Interface

Retrieves the frequency mapping previously created by the network provider by a call to put_FrequencyMapping.

Syntax

HRESULT get_FrequencyMapping(
    BSTR* pMapping
    );

Parameters

pMapping
[out, retval] BSTR that receives the frequency mappings created by 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

The BSTR is treated as a binary blob. It is expected to contain embedded nulls, and it may be formatted internally in whatever fashion the network provider sees fit.

ITuningSpace::put_FrequencyMapping

ITuningSpace Interface

Creates a frequency/channel map, frequency/transponder map, or whatever other mapping from carrier frequencies to frequency identifiers is appropriate for the tuning space.

Syntax

HRESULT put_FrequencyMapping(
    BSTR Mapping
    );

Parameters

Mapping
[in] BSTR that contains the frequency mappings.

Return Value

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

Remarks

This method is used by the network provider to store a string that contains the frequency mappings. The

ITuningSpace::get_DefaultLocator

ITuningSpace Interface

Retrieves the default Locator on the local system.

Syntax

HRESULT get_DefaultLocator(
    ILocator** LocatorVal
    );

Parameters

LocatorVal
[out, retval] Address of a pointer that receives the returned ILocator interface.

Return Value

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

Remarks

The default locator can be used as a starting point for the IScanningTuner object after installation

ITuningSpace::put_DefaultLocator

ITuningSpace Interface

Sets the default Locator on the local system.

Syntax

HRESULT put_DefaultLocator(
    ILocator* LocatorVal
    );

Parameters

LocatorVal
[in] Pointer to an ILocator interface on the object to be set as the default Locator.

Return Value

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

Remarks

The default locator can be used as a starting point for the IScanningTuner object after installation

ITuningSpace::Clone

ITuningSpace Interface

Creates a new copy of the tuning space.

Syntax

HRESULT Clone(
    ITuningSpace** NewTS
    );

Parameters

NewTS
[out, retval] Address of an ITuningSpace interface pointer that will be set to the new TuningSpace object.

Return Value

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