Interfaccia IKsAggregateControl (ksproxy.h)

Articolo
08/07/2023

L'interfaccia IKsAggregateControl fornisce metodi che aggiungono e rimuoveno server COM come provider di aggregazioni negli oggetti KS che supportano l'interfaccia.

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

Ereditarietà

L'interfaccia IKsAggregateControl eredita dall'interfaccia IUnknown .

Metodi

L'interfaccia IKsAggregateControl include questi metodi.


IKsAggregateControl::KsAddAggregate Il metodo KsAddAggregate aggiunge un server COM come provider di aggregazioni all'elenco di provider di interfacce 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 di provider di interfacce per l'oggetto KS che espone l'interfaccia IKsAggregateControl.

Commenti

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.

Lo scopo principale delle estensioni del 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, elaborazione asincrona nei thread e così via. La registrazione di un gestore set consente a uno di indicare un'interfaccia specifica che deve essere aggregata o che verrà esposto un elenco senza nome delle interfacce. Nel primo caso, vengono inviate solo 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 dello stato supportando l'interfaccia IDistributorNotify . Se l'oggetto extension supporta questa interfaccia, verrà notificata 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 nelle 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 extension è ancora caricato e aggregato dall'oggetto pin.

La notifica sulle modifiche alla connessione pin è necessaria perché le estensioni non vengono caricate quando un pin viene disconnesso. Le estensioni vengono invece caricate la prima volta che il pin è connesso e lasciato caricato tramite disconnessioni e riconnessioni, a meno che una riconnessione indica che il set di estensione specifico non è supportato più nel 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 su se il pin KS è attualmente connesso. L'estensione può determinare queste informazioni chiamando il metodo IKsObject::KsGetObjectHandle per eseguire query sull'handle dell'oggetto del pin KS quando l'estensione riceve una chiamata NotifyGraphChange . Quando l'estensione viene prima caricata, può presupporre che il pin sia connesso e qualsiasi notifica successiva può implicare una disconnessione o riconnessione. Pertanto, la notifica si verifica dopo che si verifica la modifica effettiva, anziché le modifiche dello stato, che notificano prima.

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

Per caricare le estensioni del set, il proxy cerca il GUID di ogni set raccolto dal filtro o dal pin, determinando se ogni oggetto è 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ò avere anche un valore binario denominato iid che contiene la rappresentazione binaria del GUID per l'interfaccia da aggregare per questa estensione set. Si tratta del GUID dell'interfaccia che causerà l'invio di un oggetto QueryInterface nel filtro o nel pin al server COM per questa estensione. Se questo valore denominato non è presente nella sottochiave, tutte le chiamate QueryInterface sconosciute verranno indirizzate 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 dell'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 extension.

Anche se la chiave del Registro di sistema MediaInterfaces può essere usata in modo esplicito per indicare in modo esplicito quale interfaccia (se presente) l'intera voce non deve essere presente. L'implicazione è che qualsiasi server COM può essere caricato tramite IKsAggregateControl in modo che questo server COM fornisca interfacce aggregate, se il server COM è elencato sotto la chiave del Registro di sistema MediaInterfaces .

Per i set supportati e che hanno già definito gestori di oggetti di estensione registrati automaticamente al momento dell'installazione o quando viene aggiunto un tipo specifico di dispositivo al sistema, l'installazione del driver non deve eseguire alcun lavoro aggiuntivo nell'esporre queste interfacce COM per il filtro. Tuttavia, per esporre interfacce COM per set privati, è necessario aggiungere sia la voce MediaInterfaces che la voce del server COM quando il filtro è installato.

Il proxy consente anche 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 sottochiave MediaInterfaces sostitutiva . Pertanto, per questo filtro o qualsiasi oggetto in questo filtro, tutti i set con questo GUID useranno questo GUID alternativo per cercare una voce MediaInterfaces anziché il GUID del set stesso. La nuova voce MediaInterfaces verrà registrata come di consueto.

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