Interfaccia IKsAggregateControl (ksproxy.h)

Articolo
02/07/2025

L'interfaccia IKsAggregateControl fornisce metodi che aggiungono e rimuovono i server COM come provider di aggregazione su oggetti KS che supportano l'interfaccia .

L'identificatore di interfaccia (IID) per questa interfaccia è IID_IKsAggregateControl.

Eredità

L'interfaccia IKsAggregateControl eredita dall'interfaccia IUnknown.

Metodi

L'interfaccia IKsAggregateControl dispone di questi metodi.


IKsAggregateControl::KsAddAggregate Il metodo KsAddAggregate aggiunge un server COM come provider di aggregazione all'elenco dei provider di interfaccia per l'oggetto KS che espone l'interfaccia IKsAggregateControl.
IKsAggregateControl::KsRemoveAggregate Il metodo KsRemoveAggregate rimuove un provider di aggregazione server COM aggiunto in precedenza dall'elenco dei provider di interfaccia per l'oggetto KS che espone l'interfaccia IKsAggregateControl.

Osservazioni

Tutti i set di proprietà, metodo ed eventi supportati da un filtro KS o un pin possono essere rappresentati nella rappresentazione proxy DirectShow del filtro o dell'oggetto pin per zero o più interfacce aggregate, dialoghi e così via. Queste interfacce aggregate client sono estensioni impostate che possono quindi essere usate per comunicare con l'oggetto KS sottostante per rappresentare la funzionalità del set. Un'estensione set è un server COM registrato, caricato tramite CoCreateInstance dal filtro KS o dal pin al momento della creazione dell'handle.

Lo scopo principale delle estensioni dei set è consentire l'aggregazione di interfacce in modo da supportare alcuni set tramite una o più interfacce COM. Tuttavia, un'implementazione può includere anche il supporto di dialoghi, l'elaborazione asincrona nei thread e così via. La registrazione di un gestore set consente di indicare un'interfaccia specifica che deve essere aggregata o che verrà esposto un elenco senza nome di interfacce. Nel primo caso vengono inviate solo le query appropriate all'oggetto e in quest'ultima tutte le query che non corrispondono a un'interfaccia già supportata vengono inviate a questo oggetto di estensione.

Un'estensione può anche ricevere notifiche di modifiche di stato supportando l'interfaccia IDistributorNotify. Se l'oggetto estensione supporta questa interfaccia, riceverà una notifica di tutte le modifiche di avvio, arresto e sospensione dello stato prima che il filtro stesso elabora tali modifiche. Inoltre, il metodo IDistributorNotify::NotifyGraphChange viene usato sulle estensioni dell'oggetto pin per indicare che l'istanza del pin KS è stata appena chiusa. Questo metodo viene usato solo per le estensioni dell'interfaccia pin e viene chiamato su un oggetto di estensione ogni volta che il pin viene disconnesso o riconnesso, mentre l'oggetto di estensione è ancora caricato e aggregato dall'oggetto pin.

La notifica sulle modifiche alla connessione pin è necessaria perché le estensioni non vengono scaricate quando un pin viene disconnesso. Al contrario, le estensioni vengono caricate la prima volta che il pin è connesso e lasciato caricato tramite disconnessioni e riconnessioni, a meno che una riconnessione non indichi che il set di estensioni specifico non è più supportato sul pin. Questo fatto consente a un oggetto di estensione di mantenere lo stato tra le riconnessioni, ma significa anche che un'estensione potrebbe richiedere informazioni sul fatto che il pin KS sia attualmente connesso. L'estensione può determinare queste informazioni chiamando il metodo IKsObject::KsGetObjectHandle per eseguire una query sull'handle dell'oggetto del pin KS quando l'estensione riceve una chiamata NotifyGraphChange. Quando l'estensione viene caricata per la prima volta, può presupporre che il pin sia connesso e qualsiasi notifica successiva potrebbe implicare una disconnessione o una riconnessione. Di conseguenza, la notifica si verifica dopo che si verifica la modifica effettiva, anziché le modifiche di stato, che notificano prima.

Un'estensione set è fondamentalmente un server COM che, facoltativamente, espone l'interfaccia IDistributorNotify e zero o più interfacce aggregate che possono essere usate da un client del filtro per modificare i set rappresentato dall'oggetto estensione. In una richiesta di creazione di oggetti di estensione tramite CoCreateInstance, il server viene sempre presentato un esterno IUnknown con cui creare l'oggetto COM. Questo IUnknown è un'interfaccia sull'oggetto filtro o pin che carica le estensioni del set. Il puntatore a interfaccia IUnknown può essere usato per eseguire query su informazioni o interfacce dal filtro o dal pin, ad esempio IKsControl. Tuttavia, non deve essere lasciato alcun riferimento sull'oggetto esterno, perché comporterà un conteggio di riferimenti circolari. L'uso delle interfacce senza un conteggio dei riferimenti è accettabile, perché l'estensione viene aggregata dall'oggetto esterno e, per definizione, viene eliminata definitivamente quando il conteggio dei riferimenti dell'oggetto esterno raggiunge lo zero.

Per caricare le estensioni del set, il proxy cerca il GUID di ogni set raccolto dal filtro o dal pin, determinando se ogni estensione è presente nel Registro di sistema. Il GUID per ogni set che deve avere un'estensione caricata è:

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

Se questa sottochiave è presente, il GUID del set corrisponde direttamente al GUID usato nel parametro del server COM della chiamata CoCreateInstance. Ogni sottochiave può anche avere un valore binario denominato iid che contiene la rappresentazione binaria del GUID per l'interfaccia da aggregare per questa estensione del set. Si tratta del GUID dell'interfaccia che causerà l'invio di un QueryInterface sul filtro o sul pin al server COM per questa estensione. Se questo valore denominato non è presente nella sottochiave, tutte le queryInterface sconosciute chiamate verranno instradate tramite questo oggetto di estensione, consentendo così di supportare molte interfacce per un determinato set esposto sull'oggetto sottostante. Il GUID del set può essere usato come identificatore di interfaccia impostando iid come GUID del set o non impostando un valore iid. In quest'ultimo caso, le query aggiuntive non supportate possono essere inviate all'oggetto di estensione.

Sebbene la MediaInterfaces chiave del Registro di sistema possa essere usata per indicare in modo esplicito quali interfacce (se presenti) vengono aggregate dal provider, l'intera voce non deve essere presente. L'implicazione del fatto che qualsiasi server COM può essere caricato tramite IKsAggregateControl in modo che questo server COM fornisca interfacce aggregate, indipendentemente dal fatto che il server COM sia elencato nella chiave del Registro di sistema MediaInterfaces.

Per i set supportati e che hanno già definito gestori di oggetti di estensione registrati automaticamente in fase di installazione o quando viene aggiunto un tipo specifico di dispositivo al sistema, l'installazione del driver non deve eseguire alcuna operazione aggiuntiva nell'esposizione di queste interfacce COM per il relativo filtro. Tuttavia, per esporre le interfacce COM per i set privati, sia la MediaInterfaces voce che la voce del server COM devono essere aggiunte quando viene installato il filtro.

Il proxy consente inoltre a un filtro di eseguire l'override del server COM per un set registrato in MediaInterfaces. Per eseguire l'override, creare una chiave SetAliases nella chiave del Registro di sistema dell'interfaccia Plug and Play. CLSID e FriendlyName si trovano nel percorso HKLM\...\SetAliases.

Immettere anche il valore denominato {set guid}, ovvero il formato stringa del GUID impostato, come valore binario del GUID per la sostituzione MediaInterfaces sottochiave. Pertanto, per questo filtro o qualsiasi oggetto con questo filtro, tutti i set con questo GUID useranno questo GUID alternativo per cercare un MediaInterfaces voce anziché il GUID del set stesso. La nuova voce MediaInterfaces verrà registrata come di consueto.

Per altre informazioni su IDistributorNotify, IUnknowne CoCreateInstance, vedere la documentazione di Microsoft Windows SDK.