ITuningSpaceContainer::TuningSpacesForName

The TuningSpacesForName method retrieves a collection of tuning spaces that match the specified name.

Syntax

HRESULT TuningSpacesForName(
    BSTR Name,
    ITuningSpaces** ppTuningSpaces
);

Parameters

Name

[in]  String that contains a regular expression to match against either the friendly name or the unique name of the tuning space.

ppTuningSpaces

[out] Address of variable that receives an ITuningSpaces interface pointer. Use this interface to enumerate the collection. The caller must release the interface.

Return Values

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

Example Code

CComPtr <ITuningSpaceContainer>  pTuningSpaceContainer;
// Create the SystemTuningSpaces object (not shown).

// Try to match any tuning spaces named "Local (something) Cable".
CComPtr<ITuningSpaces> pTunes;
CComBSTR bstrName("Local.*Cable");
hr = pITuningSpaceContainer->TuningSpacesForName(bstrName, &pTunes);
if (SUCCEEDED(hr))
{
    // Find the size of the returned collection.
    long cCount = 0;
    hr = pTunes->get_Count(&cCount);
    if (SUCCEEDED(hr) && (cCount > 0))
    {
        // Enumerate the collection.
        CComPtr<IEnumTuningSpaces> pTuneEnum;
        hr = pTunes->get_EnumTuningSpaces(&pTuneEnum);
        if (SUCCEEDED(hr))
        {
            // Use IEnumTuningSpaces to iterate through the collection.
        }
    }
}

Remarks

The returned collection might be empty, if no tuning spaces match the name.

See Also

• ITuningSpaceContainer Interface