Distribuidores Plug-in

[O recurso associado a esta página, DirectShow, é um recurso herdado. Foi substituído por MediaPlayer, IMFMediaEnginee Audio/Video Capture in Media Foundation. Esses recursos foram otimizados para Windows 10 e Windows 11. A Microsoft recomenda vivamente que o novo código utilize MediaPlayer, IMFMediaEngine e Captura de Áudio/Vídeo no Media Foundation em vez de DirectShow, quando possível. A Microsoft sugere que o código existente que usa as APIs herdadas seja reescrito para usar as novas APIs, se possível.]

Os distribuidores de plug-in (PIDs) são uma maneira de estender a funcionalidade do gerenciador de gráficos de filtro. Um distribuidor de plug-in é um objeto COM que o gerenciador de gráficos de filtro agrega em tempo de execução. Os aplicativos obtêm acesso ao PID através do gerenciador de gráficos de filtro.

Quando o gerenciador de gráfico de filtro é consultado para uma interface que ele não suporta, ele procura no registro uma chave com o seguinte formulário:

HKEY_CLASSES_ROOT\Interface\IID\Distributor

IID é uma cadeia de caracteres que contém o identificador de interface. Se a entrada do Registro existir, o valor da entrada definirá o identificador de classe (CLSID) de um PID que suporta a interface. O gerenciador de gráficos de filtro agrega o PID e retorna um ponteiro de interface, agindo assim como o externo IUnknown para o PID. Quando o aplicativo chama métodos na interface, na verdade está chamando-os no PID. No entanto, a existência do PID é transparente para o pedido.

O termo distribuidor deriva do fato de que um PID pode consultar seu ponteiro de IUnknown externo para interfaces no gerenciador de gráficos de filtro. Chamando o IFilterGraph::EnumFilters método, o PID pode enumerar os filtros no gráfico e distribuir chamadas de método para esses filtros. Dessa forma, um PID pode servir como um único ponto de controle para o aplicativo chamar métodos em filtros.

Quando o gerenciador de gráficos de filtro agrega um PID, ele consulta o PID para o interface IDistributorNotify. Se o PID suportar essa interface, o gerenciador de gráficos de filtro o usará para notificar o PID sobre alterações no gráfico:

• Quando o gráfico de filtro alterna entre os estados run, paused e stop, ele chama IDistributorNotify::Run, IDistributorNotify::P auseou IDistributorNotify::Stop.
• Quando um relógio de referência é definido, o gerenciador de gráficos de filtro chama IDistributorNotify::SetSyncSource.
• Quando filtros são adicionados ou removidos, ou conexões de pino são alteradas, o gerenciador de gráficos de filtro chama IDistributorNotify::NotifyGraphChange.

Para implementar um PID personalizado, crie um objeto COM que ofereça suporte à agregação. Ele deve suportar uma interface que o gerenciador de gráficos de filtro ainda não suporta. Opcionalmente, ele pode suportar o IDistributorNotify interface.

Se o PID obtiver quaisquer ponteiros de interface do gerenciador de gráficos de filtro, ele deve liberá-los imediatamente. Caso contrário, ele pode criar uma contagem de referência circular, o que pode impedir que o gerenciador de gráficos de filtro seja destruído. Manter uma contagem de referência no gerenciador de gráficos de filtro é desnecessário em qualquer caso, porque o gerenciador de gráfico de filtro controla a vida útil do PID.

Como um PID é projetado especificamente para agregação pelo gerenciador de gráficos de filtro, convém impor isso no método do construtor do PID. Verifique se o ponteiro externo IUnknown está NULL e, em caso afirmativo, retorne o código de erro VFW_E_NEED_OWNER. (Consulte Códigos de erro e sucesso.) Além disso, para evitar que outros objetos agreguem o PID, você pode consultar o ponteiro externo IUnknown para a interfaceIGraphBuilder. Retornar um código de erro se o objeto não expor IGraphBuilder.