IKsAggregateControl-Schnittstelle (ksproxy.h)

Artikel
02/07/2025

Die IKsAggregateControl Schnittstelle stellt Methoden bereit, mit denen COM-Server als Aggregatanbieter für KS-Objekte hinzugefügt und entfernt werden, die die Schnittstelle unterstützen.

Der Schnittstellenbezeichner (IID) für diese Schnittstelle ist IID_IKsAggregateControl.

Erbschaft

Die IKsAggregateControl Schnittstelle erbt von der IUnknown--Schnittstelle.

Methodik

Die IKsAggregateControl--Schnittstelle verfügt über diese Methoden.


IKsAggregateControl::KsAddAggregate Die KsAddAggregate-Methode fügt einen COM-Server als Aggregatanbieter zur Liste der Schnittstellenanbieter für das KS-Objekt hinzu, das die IKsAggregateControl-Schnittstelle verfügbar macht.
IKsAggregateControl::KsRemoveAggregate Die KsRemoveAggregate-Methode entfernt einen zuvor hinzugefügten COM-Serveraggregatanbieter aus der Liste der Schnittstellenanbieter für das KS-Objekt, das die IKsAggregateControl-Schnittstelle verfügbar macht.

Bemerkungen

Alle Eigenschaften, Methoden und Ereignissätze, die ein KS-Filter oder Pin unterstützt, können in der DirectShow-Proxydarstellung des Filter- oder Pinobjekts durch null oder mehr aggregierte Schnittstellen, Dialogfelder usw. dargestellt werden. Diese aggregierten Clientschnittstellen sind festgelegte Erweiterungen, die dann für die Kommunikation mit dem zugrunde liegenden KS-Objekt verwendet werden können, um die Funktionalität des Satzes darzustellen. Eine Set-Erweiterung ist ein registrierter COM-Server, der über CoCreateInstance durch den KS-Filter oder pin zur Verarbeitungszeit geladen wird.

Der Hauptzweck von Seterweiterungen besteht darin, die Aggregation von Schnittstellen zu ermöglichen, um einige Sätze über eine oder mehrere COM-Schnittstellen zu unterstützen. Eine Implementierung kann jedoch auch unterstützung von Dialogfeldern, asynchroner Verarbeitung in Threads usw. enthalten. Die Registrierung eines Satzhandlers ermöglicht es einem, entweder eine bestimmte Schnittstelle anzugeben, die aggregiert werden soll oder dass eine nicht benannte Liste von Schnittstellen verfügbar gemacht wird. Im ersten Fall werden nur geeignete Abfragen an das Objekt gesendet, und in letzterer werden alle Abfragen, die keiner bereits unterstützten Schnittstelle entsprechen, an dieses Erweiterungsobjekt gesendet.

Eine Erweiterung kann auch Benachrichtigungen über Zustandsänderungen erhalten, indem die IDistributorNotify Schnittstelle unterstützt wird. Wenn das Erweiterungsobjekt diese Schnittstelle unterstützt, wird es über alle Änderungen des Start-, Stopp- und Pausenzustands benachrichtigt, bevor der Filter selbst diese Änderungen verarbeitet. Darüber hinaus wird die IDistributorNotify::NotifyGraphChange-Methode für Pinobjekterweiterungen verwendet, um anzugeben, dass die KS-Pininstanz gerade geschlossen wurde. Diese Methode wird nur für Pinschnittstellenerweiterungen verwendet und jedes Mal aufgerufen, wenn der Pin getrennt oder erneut verbunden wird, während das Erweiterungsobjekt weiterhin vom Pinobjekt geladen und aggregiert wird.

Benachrichtigung bei Pinverbindungsänderungen ist erforderlich, da die Erweiterungen nicht entladen werden, wenn eine Pin getrennt wird. Stattdessen werden Erweiterungen geladen, wenn der Pin zum ersten Mal verbunden ist und durch Trennen und erneute Verbindungen geladen wird, es sei denn, eine erneute Verbindung gibt an, dass der jeweilige Erweiterungssatz für den Pin nicht mehr unterstützt wird. Diese Tatsache ermöglicht es einem Erweiterungsobjekt, den Zustand zwischen erneuten Verbindungen beizubehalten, bedeutet aber auch, dass eine Erweiterung möglicherweise Informationen darüber erfordert, ob der KS-Pin derzeit verbunden ist. Die Erweiterung kann diese Informationen ermitteln, indem die IKsObject::KsGetObjectHandle- Methode aufgerufen wird, um das Objekthandle des KS-Pins abzufragen, wenn die Erweiterung einen NotifyGraphChange Aufruf empfängt. Wenn die Erweiterung zum ersten Mal geladen wird, kann davon ausgegangen werden, dass der Pin verbunden ist, und jede nachfolgende Benachrichtigung kann eine Verbindung impliziert oder eine erneute Verbindung herstellen. Daher tritt die Benachrichtigung auf, nachdem die tatsächliche Änderung erfolgt, im Gegensatz zu Zustandsänderungen, die vorher benachrichtigt werden.

Eine Seterweiterung ist im Grunde ein COM-Server, der optional die IDistributorNotify Schnittstelle und null oder mehr andere aggregierte Schnittstellen verfügbar macht, die von einem Client des Filters zum Bearbeiten von Sätzen verwendet werden können, die das Erweiterungsobjekt darstellt. Bei einer Erweiterungsobjekterstellungsanforderung über CoCreateInstancewird der Server immer eine äußere IUnknown- angezeigt, mit der das COM-Objekt erstellt werden soll. Diese IUnknown ist eine Schnittstelle für das Filter- oder Pinobjekt, das Seterweiterungen lädt. Der IUnknown Schnittstellenzeiger kann verwendet werden, um Informationen oder Schnittstellen aus dem Filter oder Pin abzufragen, z. B. IKsControl. Es sollte jedoch kein Verweis auf das äußere Objekt verbleiben, da er zu einer Kreisbezugsanzahl führt. Die Verwendung der Schnittstellen ohne Referenzanzahl ist akzeptabel, da die Erweiterung vom äußeren Objekt aggregiert und per Definition zerstört wird, wenn die Referenzanzahl des äußeren Objekts null erreicht.

Um Seterweiterungen zu laden, sucht der Proxy die GUID der einzelnen vom Filter oder Pin erfassten Sätze, um festzustellen, ob jede in der Registrierung vorhanden ist. Die GUID für jeden Satz, für den eine Erweiterung geladen werden soll, lautet:

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

Wenn dieser Unterschlüssel vorhanden ist, entspricht die GUID des Satzes direkt der GUID, die im COM-Serverparameter des CoCreateInstance Aufrufs verwendet wird. Jeder Unterschlüssel kann auch einen benannten binärwert iid haben, der die binäre Darstellung der GUID für die Schnittstelle enthält, die für diese Seterweiterung aggregiert werden soll. Dies ist die Schnittstellen-GUID, die dazu führt, dass ein QueryInterface- auf dem Filter oder pin an den COM-Server für diese Erweiterung gesendet wird. Wenn dieser benannte Wert nicht unter dem Unterschlüssel vorhanden ist, werden alle unbekannten QueryInterface- Aufrufe über dieses Erweiterungsobjekt weitergeleitet, sodass es viele Schnittstellen für einen bestimmten Satz unterstützt, der für das zugrunde liegende Objekt verfügbar gemacht wird. Die GUID des Satzes kann als Schnittstellenbezeichner verwendet werden, indem entweder die GUID des Satzes festgelegt oder kein iid-Wert festgelegt wird. In letzterem Fall werden möglicherweise keine zusätzlichen Abfragen an das Erweiterungsobjekt gesendet.

Obwohl der MediaInterfaces Registrierungsschlüssel verwendet werden kann, um explizit anzugeben, welche Schnittstelle (falls vorhanden) der Anbieter aggregiert, muss der gesamte Eintrag nicht vorhanden sein. Die Auswirkung darauf, dass jeder COM-Server über IKsAggregateControl- geladen werden kann, sodass dieser COM-Server aggregierte Schnittstellen bereitstellt, ob der COM-Server unter dem MediaInterfaces Registrierungsschlüssel aufgeführt ist.

Für Sätze, die unterstützt werden und bereits erweiterungsobjekthandler definiert wurden, die automatisch zur Installationszeit registriert werden oder wenn ein bestimmter Gerätetyp dem System hinzugefügt wird, muss die Treiberinstallation keine zusätzlichen Aufgaben ausführen, um diese COM-Schnittstellen für ihren Filter verfügbar zu machen. Um jedoch COM-Schnittstellen für private Sets verfügbar zu machen, müssen sowohl die MediaInterfaces Eintrag als auch der COM-Servereintrag hinzugefügt werden, wenn der Filter installiert wird.

Der Proxy ermöglicht es einem Filter auch, den COM-Server für einen Satz außer Kraft zu setzen, der unter MediaInterfacesregistriert ist. Erstellen Sie zum Überschreiben einen SetAliases- Schlüssel unter dem Registrierungsschlüssel "Plug and Play interface". CLSID und FriendlyName befinden sich im Pfad HKLM\...\SetAliases.

Geben Sie außerdem den benannten Wert {set guid}ein, bei dem es sich um das Zeichenfolgenformat der festgelegten GUID handelt, als Binärer Wert der GUID für den Ersatz MediaInterfaces Unterschlüssel. Daher verwendet für diesen Filter oder jedes Objekt unter diesem Filter alle Sätze mit dieser GUID diese alternative GUID, um nach einem MediaInterfaces Eintrag und nicht nach der GUID des Satzes selbst zu suchen. Der neue MediaInterfaces Eintrag wird wie gewohnt registriert.

Weitere Informationen zu IDistributorNotify, IUnknownund CoCreateInstancefinden Sie in der Microsoft Windows SDK-Dokumentation.