Interface IKsAggregateControl (ksproxy.h)

L’interface IKsAggregateControl fournit des méthodes qui ajoutent et suppriment des serveurs COM en tant que fournisseurs d’agrégation sur des 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éthode

L’interface IKsAggregateControl a ces méthodes.

Remarques

Toutes les propriétés, méthodes et ensembles 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 du jeu. Une extension set est un serveur COM inscrit, qui est chargé via CoCreateInstance par le filtre ou l’épingle KS 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 un ensemble 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, et ainsi de suite. L’inscription d’un gestionnaire d’ensemble permet d’indiquer une interface spécifique qui doit être agrégée ou qu’une liste non nommée d’interfaces sera exposée. Dans le premier cas, seules les requêtes appropriées sont envoyées à l’objet, et dans ces dernières, 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 tous les changements 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 pin pour indiquer que l’instance de broche KS vient de se fermer. Cette méthode est utilisée uniquement pour les extensions d’interface de broche 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.

La notification sur les modifications de connexion de broche 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 laissée chargée via des déconnexions et reconnectes, sauf si une reconnexion indique que le jeu d’extensions particulier n’est plus pris en charge sur la broche. Ce fait permet à un objet d’extension de conserver l’état entre les reconnexions, mais cela signifie également qu’une extension peut nécessiter des informations sur la connexion de la broche KS. L’extension peut déterminer ces informations en appelant la méthode IKsObject ::KsGetObjectHandle pour interroger le handle d’objet de l’épingle KS lorsque l’extension reçoit un appel NotifyGraphChange. Lorsque l’extension est chargée pour la première fois, elle peut supposer que l’épingle est connectée et que 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 modifications 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 est toujours présenté un IUnknown externe avec lequel créer l’objet COM. Cette IUnknown est une interface sur l’objet de filtre ou d’épingle qui charge les extensions définies. 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 elle 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 jeu collecté à partir du filtre ou de l’épingle, déterminant si chacun est présent dans le Registre. Le GUID de chaque jeu qui doit avoir une extension chargée est :

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

Si cette sous-clé est présente, le GUID du jeu correspond directement au GUID utilisé dans le paramètre 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 set. Il s’agit du GUID d’interface qui entraîne l’envoi d’un QueryInterface sur le filtre ou l’épingle 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 routés via cet objet d’extension, ce qui lui permet de prendre en charge de nombreuses interfaces pour un ensemble 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 les MediaInterfaces clé de Registre puissent être utilisées pour indiquer explicitement l’interface (le cas échéant) les agrégats du fournisseur, l’entrée entière n’a pas besoin d’être présente. L’implication que n’importe quel serveur COM peut être chargé via IKsAggregateControl afin que ce serveur COM fournit des interfaces agrégées, que le serveur COM soit répertorié sous la MediaInterfaces clé de Registre.

Pour les ensembles 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 des interfaces COM pour des jeux privés, l’entrée MediaInterfaces et l’entrée de serveur COM doivent être ajoutées lorsque le filtre est installé.

Le proxy permet également à un filtre de remplacer le serveur COM d’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 {définir le guid}, qui est le format de chaîne du GUID de jeu, en tant que valeur binaire du GUID pour le remplacement MediaInterfaces sous-clé. Ainsi, pour ce filtre ou tout objet sous ce filtre, tous les ensembles avec ce GUID utilisent ce GUID de remplacement pour rechercher une entrée MediaInterfaces plutôt que le GUID du jeu lui-même. La nouvelle entrée MediaInterfaces serait inscrite comme d’habitude.

Pour plus d’informations sur IDistributorNotify, IUnknownet CoCreateInstance, consultez la documentation du Kit de développement logiciel (SDK) Microsoft Windows.

Exigences

Voir aussi

IKsControl

IKsObject ::KsGetObjectHandle

KsAddAggregate

KsRemoveAggregate