Použití enumerátoru systémových zařízení

[Funkce přidružená k této stránce DirectShow je starší funkce. Byla nahrazena MediaPlayer, IMFMediaEnginea Audio/Video Capture v Media Foundation. Tyto funkce jsou optimalizované pro Windows 10 a Windows 11. Microsoft důrazně doporučuje, aby nový kód používal MediaPlayer, MMFMediaEngine a Audio/Video Capture v Media Foundation místo DirectShow, pokud je to možné. Microsoft navrhuje, aby se stávající kód, který používá starší rozhraní API, přepsal, aby se nová rozhraní API používala, pokud je to možné.]

Enumerátor systémových zařízení poskytuje jednotný způsob, jak vytvořit výčet filtrů registrovaných v systému uživatele podle kategorie. Kromě toho rozlišuje mezi jednotlivými hardwarovými zařízeními, i když je stejný filtr podporuje. To je zvlášť užitečné pro zařízení, která používají model ovladače Systému Windows (WDM) a filtr KSProxy. Uživatel může mít například několik zařízení pro zachytávání videa WDM, která podporují stejný filtr. Enumerátor systémových zařízení je považuje za samostatné instance zařízení.

Enumerátor systémových zařízení funguje vytvořením výčtu pro určitou kategorii, jako je například zachytávání zvuku nebo komprese videa. Enumerátor kategorií vrátí jedinečný moniker pro každé zařízení v kategorii. Enumerátor kategorií automaticky obsahuje všechna relevantní zařízení Plug and Play v kategorii. Seznam kategorií najdete v tématu Kategorie filtrů.

Chcete-li použít enumerátor systémových zařízení, postupujte takto:

1. Vytvořte výčet systémových zařízení voláním CoCreateInstance. Identifikátor třídy (CLSID) je CLSID_SystemDeviceEnum.
2. Získejte enumerátor kategorie voláním ICreateDevEnum::CreateClassEnumerator s CLSID požadované kategorie. Tato metoda vrátí ukazatel rozhraní IEnumMoniker. Pokud je kategorie prázdná (nebo neexistuje), metoda vrátí S_FALSE místo kódu chyby. Pokud ano, vrácený ukazatel IEnumMoniker je NULL a pokus o jeho dereferencování způsobí výjimku. Proto explicitně otestujte S_OK při volání CreateClassEnumerator, místo volání obvyklého makra SUCCEEDED.
3. Pomocí metody IEnumMoniker::Next zadejte výčet jednotlivých monikerů. Tato metoda vrátí ukazatel rozhraní IMoniker. Když Next metoda dosáhne konce výčtu, vrátí také S_FALSE, takže znovu zkontrolujte S_OK.
4. Chcete-li načíst popisný název zařízení, například pro zobrazení v uživatelském rozhraní, vyvolejte metodu IMoniker::BindToStorage.
5. Pokud chcete vytvořit a inicializovat filtr DirectShow, který spravuje zařízení, zavolejte IMoniker::BindToObject na monikeru. Zavolejte IFilterGraph::AddFilter pro přidání filtru do grafu.

Tento proces znázorňuje následující diagram.

Následující příklad ukazuje, jak vytvořit výčet video kompresorů nainstalovaných v systému uživatele. V zájmu stručnosti příklad provádí minimální kontrolu chyb.

// Create the System Device Enumerator.
HRESULT hr;
ICreateDevEnum *pSysDevEnum = NULL;
hr = CoCreateInstance(CLSID_SystemDeviceEnum, NULL, CLSCTX_INPROC_SERVER,
    IID_ICreateDevEnum, (void **)&pSysDevEnum);
if (FAILED(hr))
{
    return hr;
}

// Obtain a class enumerator for the video compressor category.
IEnumMoniker *pEnumCat = NULL;
hr = pSysDevEnum->CreateClassEnumerator(CLSID_VideoCompressorCategory, &pEnumCat, 0);

if (hr == S_OK) 
{
    // Enumerate the monikers.
    IMoniker *pMoniker = NULL;
    ULONG cFetched;
    while(pEnumCat->Next(1, &pMoniker, &cFetched) == S_OK)
    {
        IPropertyBag *pPropBag;
        hr = pMoniker->BindToStorage(0, 0, IID_IPropertyBag, 
            (void **)&pPropBag);
        if (SUCCEEDED(hr))
        {
            // To retrieve the filter's friendly name, do the following:
            VARIANT varName;
            VariantInit(&varName);
            hr = pPropBag->Read(L"FriendlyName", &varName, 0);
            if (SUCCEEDED(hr))
            {
                // Display the name in your UI somehow.
            }
            VariantClear(&varName);

            // To create an instance of the filter, do the following:
            IBaseFilter *pFilter;
            hr = pMoniker->BindToObject(NULL, NULL, IID_IBaseFilter,
                (void**)&pFilter);
            // Now add the filter to the graph. 
            //Remember to release pFilter later.
            pPropBag->Release();
        }
        pMoniker->Release();
    }
    pEnumCat->Release();
}
pSysDevEnum->Release();

Označení zařízení

Pro zařízení moniker můžete předat moniker do metody IFilterGraph2::AddSourceFilterForMoniker, aby se vytvořil zachytávací filtr pro zařízení. Například kód najdete v dokumentaci pro danou metodu.

Metoda IMoniker::GetDisplayName vrátí zobrazovaný název monikeru. I když je zobrazovaný název čitelný, obvykle ho nebudete zobrazovat koncovému uživateli. Místo toho získejte popisný název z kontejneru vlastností, jak bylo dříve popsáno.

Metodu IMoniker::ParseDisplayName nebo funkci MkParseDisplayName lze použít k vytvoření výchozího monikeru zařízení pro danou kategorii filtru. Použijte zobrazovaný název ve formátu @device:*:{category-clsid}, kde category-clsid představuje řetězcovou reprezentaci identifikátoru GUID kategorie. Výchozí moniker je první moniker vrácený enumerátorem zařízení pro danou kategorii.