IKsAggregateControl-Schnittstelle (ksproxy.h)

Artikel
03/05/2024

Die IKsAggregateControl-Schnittstelle stellt Methoden bereit, die COM-Server als Aggregatanbieter für KS-Objekte hinzufügen und entfernen, die die Schnittstelle unterstützen.

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

Vererbung

Die IKsAggregateControl-Schnittstelle erbt von der IUnknown-Schnittstelle .

Methoden

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


IKsAggregateControl::KsAddAggregate Die KsAddAggregate-Methode fügt der Liste der Schnittstellenanbieter für das KS-Objekt, das die IKsAggregateControl-Schnittstelle verfügbar macht, einen COM-Server als Aggregatanbieter hinzu.
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.

Hinweise

Alle Eigenschaften-, Methoden- und Ereignissätze, die von einem KS-Filter oder Pin unterstützt werden, können in der DirectShow-Proxydarstellung des Filter- oder Anheftobjekts durch 0 oder mehr aggregierte Schnittstellen, Dialoge usw. dargestellt werden. Diese clientaggregatierten Schnittstellen sind Seterweiterungen, die dann verwendet werden können, um mit dem zugrunde liegenden KS-Objekt zu kommunizieren, um die Funktionalität des Satzes darzustellen. Eine Set-Erweiterung ist ein registrierter COM-Server, der über CoCreateInstance durch den KS-Filter oder den Pin zum Zeitpunkt der Handleerstellung 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 die Unterstützung von Dialogen, die asynchrone Verarbeitung in Threads usw. umfassen. Die Registrierung eines Set-Handlers ermöglicht es, entweder eine bestimmte Schnittstelle anzugeben, die aggregiert werden soll, oder dass eine unbenannte Liste von Schnittstellen verfügbar gemacht wird. Im ersten Fall werden nur geeignete Abfragen an das Objekt gesendet, und im letzteren werden alle Abfragen, die nicht mit einer bereits unterstützten Schnittstelle übereinstimmen, an dieses Erweiterungsobjekt gesendet.

Eine Erweiterung kann auch Benachrichtigungen über Zustandsänderungen erhalten, indem sie die IDistributorNotify-Schnittstelle unterstützt. Wenn das Erweiterungsobjekt diese Schnittstelle unterstützt, wird es über alle Statusänderungen zum Starten, Beenden und Anhalten benachrichtigt, bevor der Filter selbst diese Änderungen verarbeitet. Darüber hinaus wird die IDistributorNotify::NotifyGraphChange-Methode für Pinobjekterweiterungen verwendet, um anzugeben, dass der KS-Pin instance gerade geschlossen wurde. Diese Methode wird nur für Pinschnittstellenerweiterungen verwendet und bei jedem Trennen oder erneuten Verbinden des Pins für ein Erweiterungsobjekt aufgerufen, während das Erweiterungsobjekt weiterhin vom Pinobjekt geladen und aggregiert wird.

Benachrichtigungen bei Änderungen an der Pinverbindung sind erforderlich, da die Erweiterungen nicht entladen werden, wenn eine Stecknadel getrennt wird. Stattdessen werden Erweiterungen geladen, wenn der Pin zum ersten Mal verbunden wird, und die Verbindung wird über getrennt und erneut geladen, es sei denn, eine erneute Verbindung weist darauf hin, dass der bestimmte Erweiterungssatz auf dem Pin nicht mehr unterstützt wird. Diese Tatsache ermöglicht es einem Erweiterungsobjekt, den Zustand zwischen erneuten Verbindungen beizubehalten, aber es bedeutet auch, dass eine Erweiterung Möglicherweise Informationen dazu benötigt, ob der KS-Pin gerade verbunden ist. Die Erweiterung kann diese Informationen ermitteln, indem sie die IKsObject::KsGetObjectHandle-Methode aufruft, 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 Trennung oder eine erneute Verbindung bedeuten. Daher erfolgt die Benachrichtigung nach der tatsächlichen Änderung, im Gegensatz zu Zustandsänderungen, die vorher benachrichtigt werden.

Eine Set-Erweiterung ist im Grunde genommen ein COM-Server, der optional die IDistributorNotify-Schnittstelle und 0 oder mehr andere aggregierte Schnittstellen verfügbar macht, die von einem Client des Filters verwendet werden können, um Sätze zu bearbeiten, die das Erweiterungsobjekt darstellt. Bei einer Anforderung zur Erstellung von Erweiterungsobjekten über CoCreateInstance wird dem Server immer ein äußeres IUnknown angezeigt, mit dem das COM-Objekt erstellt werden soll. Dieser 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 dies zu einer kreisförmigen Verweisanzahl führt. Die Verwendung der Schnittstellen ohne Verweisanzahl ist akzeptabel, da die Erweiterung vom äußeren Objekt aggregiert und per Definition zerstört wird, wenn die Verweisanzahl des äußeren Objekts Null erreicht.

Um Seterweiterungen zu laden, sucht der Proxy die GUID jedes Satzes, der vom Filter oder pin erfasst wurde, und bestimmt, ob diese in der Registrierung vorhanden sind. 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 über einen benannten binärwert iid verfügen, 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 bewirkt, dass eine QueryInterface für den Filter oder die 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ützen kann, der für das zugrunde liegende Objekt verfügbar gemacht wird. Die GUID des Satzes kann als Schnittstellenbezeichner verwendet werden, indem entweder iid als GUID des Satzes festgelegt wird, oder indem kein iid-Wert festgelegt wird. Im letzteren Fall werden möglicherweise zusätzliche Abfragen, die nicht unterstützt werden, an das Erweiterungsobjekt gesendet.

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

Für Sätze, die unterstützt werden und bereits über definierte Erweiterungsobjekthandler verfügen, die bei der Installation automatisch 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 Sätze verfügbar zu machen, müssen sowohl der MediaInterfaces-Eintrag als auch der COM-Servereintrag hinzugefügt werden, wenn der Filter installiert wird.

Der Proxy ermöglicht auch, dass ein Filter den COM-Server für eine gruppe überschreibt, die unter MediaInterfaces registriert ist. Erstellen Sie zum Überschreiben einen SetAliases-Schlüssel unter dem Registrierungsschlüssel der Plug & Play Schnittstelle. CLSID und FriendlyName befinden sich im Pfad HKLM\...\SetAliases.

Geben Sie außerdem den benannten Wert {set guid}, der das Zeichenfolgenformat der set GUID ist, als binärwert der GUID für den Ersatz-Unterschlüssel MediaInterfaces ein. Daher verwenden alle Sätze mit dieser GUID für diesen Filter oder ein beliebiges Objekt unter diesem Filter diese alternative GUID, um nach einem MediaInterfaces-Eintrag und nicht nach der GUID des Satzes selbst zu suchen. Der neue Eintrag MediaInterfaces wird wie gewohnt registriert.

Weitere Informationen zu IDistributorNotify, IUnknown und CoCreateInstance finden Sie in der dokumentation zu Microsoft Windows SDK.