Tuning Spaces

Microsoft DirectShow 9.0

Tuning Spaces

A tuning space repesents a specific network type, such as ATSC digital antenna or DVB cable. A tuning space object performs several functions:

• It stores information about the network, such as the range of physical channels.
• It is a factory for tune requests.
• It is persistable, so it can be stored in the system registry.

Default tuning spaces are provided for analog cable, analog antenna, ATSC digital cable, ATSC digital antenna, and analog auxiliary input. See Default Tuning Spaces for more information. Third parties can create their own tuning spaces to support DVB-T, DVB-S, or other network types.

Every tuning space object exposes the ITuningSpace interface. Additional network-specific interfaces are derived from ITuningSpace. For example, an ATSC tuning space exposes the IATSCTuningSpace interface.

System Tuning Spaces Collection

The SystemTuningSpaces object is a collection of all the tuning spaces available on the local system. Use this object to enumerate available tuning spaces and to add new tuning spaces. The SystemTuningSpaces object exposes the ITuningSpaceContainer interface.

The following code shows how to create the SystemTuningSpaces object and enumerate the tuning spaces using the ITuningSpaceContainer::get_EnumTuningSpaces method:

// Create the SystemTuningSpaces container.
CComPtr <ITuningSpaceContainer> pTuningSpaceContainer;
hr = pITuningSpaceContainer.CoCreateInstance(CLSID_SystemTuningSpaces);
if (SUCCEEDED(hr))
{
    // Get the enumerator for the collection.
    CComPtr<IEnumTuningSpaces> pTuningSpaceEnum;
    hr = pTuningSpaceContainer->get_EnumTuningSpaces(&pTuningSpaceEnum);
    if (SUCCEEDED(hr))
    {
        // Loop through the collection.
        CComPtr<ITuningSpace> pTuningSpace;
        while (S_OK == pTuningSpaceEnum->Next(1, &pTuningSpace, NULL))
        {
            // pTuningSpace points to the next tuning space.
            // You can query this pointer for derived interfaces.
        }
    }
}

Every tuning space has a UniqueName property, which is unique within a given computer's SystemTuningSpaces collection. Use this property to find a particular tuning space; call ITuningSpace::get_UniqueName to get the property.

Creating Tune Requests

To create a new tune request, call the ITuningSpace::CreateTuneRequest method on the tuning space. This method returns a tune request object that corresponds to the network type for that tuning space. The new tune request object is unitialized; tuning information for a specific channel or program must be added by calling methods on the tune request. For more information, see Tune Requests.

Creating New Tuning Spaces

Microsoft provides Network Provider filters for DVB tuning, and the Unified Tuning Model defines objects and interfaces for DVB tuning. However, there are no default DVB tuning spaces, because many of the required parameters are specific to individual broadcasters. In order to support DVB tuning, therefore, you must create a new tuning space and add it to the system registry, as follows:

1. Create a DVB tuning space object. Use the DVBTuningSpace object for DVB-T or DVB-C, and the DVBSTuningSpace object for DVB-S.
2. Set properties on the tuning space, using ITuningSpace and derived interfaces.
3. Create a DVB locator object (DVBTLocator or DVBSLocator).
4. Set properties on the locator, using ILocator and derived interfaces. For more information about locators, see Locators.
5. Assign the locator as the default locator for the tuning space, by calling the ITuningSpace::put_DefaultLocator method.
6. Optionally, create default component types. Assign them as the perferred component types for the tuning space by calling the ITuningSpace::put_DefaultPreferredComponentTypes method. For more information, see Components.
7. Add the tuning space to the SystemTuningSpaces collection, by calling the ITuningSpaceContainer::Add method. The SystemTuningSpaces object automatically persists the tuning space in the registry.

You can also modify an existing tuning space. To do so, retrieve the tuning space from the SystemTuningSpaces collection, set the desired properties, and call ITuningSpaceContainer::put_Item to save the modified tuning space back into the collection.