Interface IKsAggregateControl (ksproxy.h)

Article
02/29/2024

L’interface IKsAggregateControl fournit des méthodes qui ajoutent et suppriment des serveurs COM en tant que fournisseurs d’agrégation sur les objets KS qui prennent en charge l’interface.

L’identificateur d’interface (IID) de cette interface est IID_IKsAggregateControl.

Héritage

L’interface IKsAggregateControl hérite de l’interface IUnknown.

Méthodes

L’interface IKsAggregateControl a ces méthodes.


IKsAggregateControl ::KsAddAggregate La méthode KsAddAggregate ajoute un serveur COM en tant que fournisseur d’agrégation à la liste des fournisseurs d’interface pour l’objet KS qui expose l’interface IKsAggregateControl.
IKsAggregateControl ::KsRemoveAggregate La méthode KsRemoveAggregate supprime un fournisseur d’agrégation de serveurs COM précédemment ajouté de la liste des fournisseurs d’interface pour l’objet KS qui expose l’interface IKsAggregateControl.

Remarques

Tous les jeux de propriétés, de méthodes et d’événements pris en charge par un filtre ou une broche KS peuvent être représentés sur la représentation proxy DirectShow de l’objet de filtre ou d’épingle par zéro ou plusieurs interfaces agrégées, dialogues, etc. Ces interfaces agrégées clientes sont des extensions définies qui peuvent ensuite être utilisées pour communiquer avec l’objet KS sous-jacent afin de représenter les fonctionnalités de l’ensemble. Une extension définie est un serveur COM inscrit, qui est chargé via CoCreateInstance par le filtre KS ou l’épingle au moment de la création du handle.

L’objectif principal des extensions set est d’autoriser l’agrégation d’interfaces afin de prendre en charge certains ensembles via une ou plusieurs interfaces COM. Toutefois, une implémentation peut également inclure la prise en charge des dialogues, le traitement asynchrone dans les threads, etc. L’inscription d’un gestionnaire de jeu permet d’indiquer une interface spécifique qui doit être agrégée ou qu’une liste d’interfaces sans nom sera exposée. Dans le premier cas, seules les requêtes appropriées sont envoyées à l’objet, et dans le second, toutes les requêtes qui ne correspondent pas à une interface déjà prise en charge sont envoyées à cet objet d’extension.

Une extension peut également recevoir des notifications de modifications d’état en prenant en charge l’interface IDistributorNotify . Si l’objet d’extension prend en charge cette interface, il est averti de toutes les modifications d’état de démarrage, d’arrêt et de pause avant que le filtre lui-même traite ces modifications. En outre, la méthode IDistributorNotify ::NotifyGraphChange est utilisée sur les extensions d’objet de broche pour indiquer que la broche KS instance vient de se fermer. Cette méthode est utilisée uniquement pour les extensions d’interface d’épingle et est appelée sur un objet d’extension chaque fois que l’épingle est déconnectée ou reconnectée, tandis que l’objet d’extension est toujours chargé et agrégé par l’objet pin.

Une notification sur les modifications de connexion d’épingle est requise, car les extensions ne sont pas déchargées lorsqu’une broche est déconnectée. Au lieu de cela, les extensions sont chargées la première fois que la broche est connectée et sont chargées via des déconnexions et des reconnexions, sauf si une reconnexion indique que le jeu d’extensions particulier n’est plus pris en charge sur la broche. Cela permet à un objet d’extension de conserver l’état entre les reconnexions, mais cela signifie également qu’une extension peut nécessiter des informations indiquant si la broche KS est actuellement connectée. L’extension peut déterminer ces informations en appelant la méthode IKsObject ::KsGetObjectHandle pour interroger le handle d’objet de la broche KS lorsque l’extension reçoit un appel NotifyGraphChange . Lorsque l’extension est chargée pour la première fois, elle peut supposer que la broche est connectée et toute notification ultérieure peut impliquer une déconnexion ou une reconnexion. Par conséquent, la notification se produit après la modification réelle, par opposition aux changements d’état, qui notifient avant.

Une extension set est essentiellement un serveur COM qui expose éventuellement l’interface IDistributorNotify et zéro ou plusieurs autres interfaces agrégées qui peuvent être utilisées par un client du filtre pour manipuler les jeux que l’objet d’extension représente. Sur une demande de création d’objet d’extension via CoCreateInstance, le serveur reçoit toujours un IUnknown externe avec lequel créer l’objet COM. Cet IUnknown est une interface sur l’objet de filtre ou d’épingle qui charge des extensions de jeu. Le pointeur d’interface IUnknown peut être utilisé pour interroger des informations ou des interfaces à partir du filtre ou de l’épingle, par exemple IKsControl. Toutefois, aucune référence ne doit être laissée sur l’objet externe, car cela entraîne un nombre de références circulaires. L’utilisation des interfaces sans nombre de références est acceptable, car l’extension est agrégée par l’objet externe et, par définition, est détruite lorsque le nombre de références de l’objet externe atteint zéro.

Pour charger les extensions de jeu, le proxy recherche le GUID de chaque ensemble collecté à partir du filtre ou de la broche, en déterminant si chacun est présent dans le Registre. Le GUID de chaque jeu qui doit avoir une extension chargée est le suivant :

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

Si cette sous-clé est présente, le GUID de l’ensemble correspond directement au GUID utilisé dans le paramètre de serveur COM de l’appel CoCreateInstance . Chaque sous-clé peut également avoir une valeur binaire nommée iid qui contient la représentation binaire du GUID pour l’interface à agréger pour cette extension de jeu. Il s’agit du GUID d’interface qui entraîne l’envoi d’un QueryInterface sur le filtre ou la broche au serveur COM pour cette extension. Si cette valeur nommée n’est pas présente sous la sous-clé, tous les appels QueryInterface inconnus sont acheminés via cet objet d’extension, ce qui lui permet de prendre en charge de nombreuses interfaces pour un jeu particulier exposé sur l’objet sous-jacent. Le GUID du jeu peut être utilisé comme identificateur d’interface en définissant iid comme GUID du jeu ou en ne définissant pas de valeur iid. Dans ce dernier cas, des requêtes supplémentaires non prises en charge peuvent être envoyées à l’objet d’extension.

Bien que la clé de Registre MediaInterfaces puisse être utilisée pour indiquer explicitement quelle interface (le cas échéant) le fournisseur agrège, l’entrée entière n’a pas besoin d’être présente. L’implication étant que n’importe quel serveur COM peut être chargé via IKsAggregateControl afin que ce serveur COM fournisse des interfaces agrégées, que le serveur COM soit répertorié sous la clé de Registre MediaInterfaces .

Pour les ensembles qui sont pris en charge et qui ont déjà défini des gestionnaires d’objets d’extension qui sont automatiquement inscrits au moment de l’installation ou lorsqu’un type spécifique d’appareil est ajouté au système, l’installation du pilote n’a pas besoin d’effectuer de travail supplémentaire pour exposer ces interfaces COM pour leur filtre. Toutefois, pour exposer les interfaces COM pour les jeux privés, l’entrée MediaInterfaces et l’entrée serveur COM doivent être ajoutées lors de l’installation du filtre.

Le proxy permet également à un filtre de remplacer le serveur COM pour un jeu inscrit sous MediaInterfaces. Pour remplacer, créez une clé SetAliases sous la clé de Registre de l’interface Plug-and-Play. CLSID et FriendlyName se trouvent dans le chemin HKLM\...\SetAliases.

Entrez également la valeur nommée {set guid}, qui est le format de chaîne du GUID de jeu, comme valeur binaire du GUID pour la sous-clé MediaInterfaces de remplacement. Par conséquent, pour ce filtre ou tout objet sous ce filtre, tous les ensembles avec ce GUID utilisent ce GUID alternatif pour rechercher une entrée MediaInterfaces plutôt que le GUID de l’ensemble lui-même. La nouvelle entrée MediaInterfaces est inscrite comme d’habitude.

Pour plus d’informations sur IDistributorNotify, IUnknown et CoCreateInstance, consultez la documentation Microsoft Windows SDK.