Interface IKsAggregateControl (ksproxy.h)
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. |
Observações
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 pin 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 definida é um servidor COM registrado, que é carregado por meio de CoCreateInstance pelo filtro KS ou fixação 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 conjuntos 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 com suporte 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 de 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 pin 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ão 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 recebe 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 oposição às alterações de estado, que notificam antes.
Uma extensão definida é 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 apresenta uma IUnknown externa com a qual criar o objeto COM. Este IUnknown é uma interface no objeto de filtro ou pino que está carregando extensões de conjunto. O ponteiro de interface IUnknown pode ser usado para consultar informações ou interfaces do filtro ou pino, como IKsControl. No entanto, nenhuma referência deve ser deixada no objeto externo, pois resultará em uma contagem de referência circular. Usar as 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 que a interface seja agregada para essa extensão de conjunto. Esse é o GUID de 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 serão roteadas por meio desse objeto de extensão, permitindo 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. Neste último caso, consultas adicionais sem suporte podem ser enviadas para o objeto de extensão.
Embora o MediaInterfaces chave do Registro possa ser usado 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 no MediaInterfaces chave do Registro.
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 seu 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 {guid de conjunto}, que é o formato de cadeia de caracteres do GUID definido, como o valor binário do GUID para a substituição MediaInterfaces subchave. Assim, 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 do seria registrada como de costume.
Para obter mais informações sobre IDistributorNotify, IUnknowne CoCreateInstance, consulte a documentação do SDK do Microsoft Windows.
Requisitos
| Requisito | Valor |
|---|---|
| da Plataforma de Destino | Windows |
| cabeçalho | ksproxy.h (inclua Ksproxy.h) |