Interface IKsAggregateControl (ksproxy.h)

Artigo
08/07/2023

A interface IKsAggregateControl fornece métodos que adicionam e removem servidores COM como provedores de agregação em objetos KS que dão suporte à interface.

O IID (identificador de interface) para essa interface é IID_IKsAggregateControl.

Herança

A interface IKsAggregateControl herda da interface IUnknown .

Métodos

A interface IKsAggregateControl tem esses métodos.


IKsAggregateControl::KsAddAggregate O método KsAddAggregate adiciona um servidor COM como um provedor de agregação à lista de provedores de interface para o objeto KS que expõe a interface IKsAggregateControl.
IKsAggregateControl::KsRemoveAggregate O método KsRemoveAggregate remove um provedor de agregação de servidor COM adicionado anteriormente da lista de provedores de interface para o objeto KS que expõe a interface IKsAggregateControl.

Comentários

Todos os conjuntos de propriedades, métodos e eventos compatíveis com um filtro KS ou pin podem ser representados na representação de proxy DirectShow do objeto de filtro ou fixação por zero ou mais interfaces agregadas, caixas de diálogo e assim por diante. Essas interfaces agregadas do cliente são extensões definidas que podem ser usadas para se comunicar com o objeto KS subjacente para representar a funcionalidade do conjunto. Uma extensão de conjunto é um servidor COM registrado, que é carregado por meio de CoCreateInstance pelo filtro KS ou pin no momento da criação do identificador.

A principal finalidade das extensões de conjunto é permitir a agregação de interfaces para dar suporte a algum conjunto por meio de uma ou mais interfaces COM. No entanto, uma implementação também pode incluir suporte a caixas de diálogo, processamento assíncrono em threads e assim por diante. O registro de um manipulador de conjunto permite que um indique uma interface específica que deve ser agregada ou que uma lista de interfaces sem nome será exposta. No primeiro caso, somente as consultas apropriadas são enviadas para o objeto e, no último, todas as consultas que não correspondem a uma interface já compatível são enviadas para esse objeto de extensão.

Uma extensão também pode receber notificações de alterações de estado dando suporte à interface IDistributorNotify . Se o objeto de extensão der suporte a essa interface, ele será notificado de todas as alterações de estado iniciar, parar e pausar antes que o próprio filtro processe essas alterações. Além disso, o método IDistributorNotify::NotifyGraphChange é usado em extensões de objeto pin para indicar que a instância do pino KS acabou de ser fechada. Esse método é usado apenas para extensões de interface de pino e é chamado em um objeto de extensão sempre que o pino é desconectado ou reconectado, enquanto o objeto de extensão ainda é carregado e agregado pelo objeto pin.

A notificação sobre alterações de conexão de pin é necessária porque as extensões não são descarregadas quando um pino é desconectado. Em vez disso, as extensões são carregadas na primeira vez em que o pino é conectado e deixado carregado por meio de desconexões e reconexões, a menos que uma reconexão indique que o conjunto de extensões específico não tem mais suporte no pino. Esse fato permite que um objeto de extensão mantenha o estado entre reconexões, mas também significa que uma extensão pode exigir informações sobre se o pino KS está conectado no momento. A extensão pode determinar essas informações chamando o método IKsObject::KsGetObjectHandle para consultar o identificador de objeto do pino KS quando a extensão receber uma chamada NotifyGraphChange . Quando a extensão é carregada pela primeira vez, ela pode assumir que o pino está conectado e qualquer notificação subsequente pode implicar uma desconexão ou reconexão. Assim, a notificação ocorre após a alteração real ocorrer, em vez de alterações de estado, que notificam antes.

Uma extensão de conjunto é basicamente um servidor COM que, opcionalmente, expõe a interface IDistributorNotify e zero ou mais outras interfaces agregadas que podem ser usadas por um cliente do filtro para manipular conjuntos que o objeto de extensão representa. Em uma solicitação de criação de objeto de extensão por meio de CoCreateInstance, o servidor sempre recebe um IUnknown externo com o qual criar o objeto COM. Esse IUnknown é uma interface no objeto de filtro ou pino que está carregando extensões do conjunto. O ponteiro da interface IUnknown pode ser usado para consultar informações ou interfaces do filtro ou do pino, como IKsControl. No entanto, nenhuma referência deve ser deixada no objeto externo, pois resultará em uma contagem de referência circular. O uso das interfaces sem uma contagem de referência é aceitável, pois a extensão é agregada pelo objeto externo e, por definição, é destruída quando a contagem de referência do objeto externo atinge zero.

Para carregar extensões de conjunto, o proxy procura o GUID de cada conjunto coletado do filtro ou do pino, determinando se cada um está presente no registro. O GUID para cada conjunto que deve ter uma extensão carregada é:

HKLM\System\CurrentControlSet\Control\MediaInterfaces\{set guid}

Se essa subchave estiver presente, o GUID do conjunto corresponderá diretamente ao GUID usado no parâmetro de servidor COM da chamada CoCreateInstance . Cada subchave também pode ter uma iid de valor binário nomeada que contém a representação binária do GUID para a interface a ser agregada para essa extensão de conjunto. Esse é o GUID da interface que fará com que um QueryInterface no filtro ou pin seja enviado ao servidor COM para essa extensão. Se esse valor nomeado não estiver presente na subchave, todas as chamadas queryInterface desconhecidas serão roteadas por meio desse objeto de extensão, permitindo assim que ele dê suporte a muitas interfaces para um determinado conjunto exposto no objeto subjacente. O GUID do conjunto pode ser usado como o identificador de interface definindo iid como o GUID do conjunto ou não definindo um valor iid. No último caso, consultas adicionais sem suporte podem ser enviadas para o objeto de extensão.

Embora a chave do Registro MediaInterfaces possa ser usada para indicar explicitamente qual interface (se houver) o provedor agrega, toda a entrada não precisa estar presente. A implicação é que qualquer servidor COM pode ser carregado por meio de IKsAggregateControl para que esse servidor COM forneça interfaces agregadas, independentemente de o servidor COM estar listado na chave do Registro MediaInterfaces .

Para conjuntos com suporte e que já têm manipuladores de objetos de extensão definidos que são registrados automaticamente no momento da instalação ou quando um tipo específico de dispositivo é adicionado ao sistema, a instalação do driver não precisa executar nenhum trabalho adicional na exposição dessas interfaces COM para o filtro. No entanto, para expor interfaces COM para conjuntos privados, a entrada MediaInterfaces e a entrada do servidor COM precisam ser adicionadas quando o filtro é instalado.

O proxy também permite que um filtro substitua o servidor COM por um conjunto registrado em MediaInterfaces. Para substituir, crie uma chave SetAliases na chave do Registro da interface Plug and Play. CLSID e FriendlyName estão localizados no caminho HKLM\...\SetAliases.

Além disso, insira o valor nomeado {set guid}, que é o formato de cadeia de caracteres do GUID definido, como o valor binário do GUID para a subchave MediaInterfaces de substituição. Portanto, para esse filtro ou qualquer objeto sob esse filtro, todos os conjuntos com esse GUID usarão esse GUID alternativo para procurar uma entrada MediaInterfaces em vez do GUID do próprio conjunto. A nova entrada MediaInterfaces seria registrada como de costume.

Para obter mais informações sobre IDistributorNotify, IUnknown e CoCreateInstance, consulte a documentação do SDK do Microsoft Windows.