Broches KS

Le minidriver fournit une structure KSPIN_DESCRIPTOR pour chaque type d'épingle à instancier. Une structure de descripteur de broche est appelée usine de broches. Chaque fabrique d’épingles peut instancier une ou plusieurs instances de broche d’un type particulier. Une fabrique de broches contient plusieurs tableaux qui décrivent le type de broche instancié par ce descripteur.

Le minidriver spécifie une ou plusieurs catégories KS auxquelles appartiennent les broches créées par ce descripteur dans le membre Categories de KSPIN_DESCRIPTOR. KS utilise des catégories pour connecter des instances de broches lors de la création d'un graphe de filtrage. La propriété KSPROPERTY_TOPOLOGY_CATEGORIES interroge pour le tableau des catégories fonctionnelles que le pilote prend en charge.

Un minidriver fournit un fichier INF qui inscrit un ou plusieurs noms d’appareils pin. Lors de l’installation, le système d’exploitation charge les noms et les catégories correspondantes dans le registre système. Les clients peuvent ensuite effectuer des appels de création de fichier avec ces noms d’appareils pour instancier des broches.

Les clients en mode utilisateur appellent la fonction Win32 CreateFile avec le nom de l’appareil. Par exemple, « \\.\filters\audio\default renderer » peut être un lien vers l’appareil audio configuré pour la sortie par défaut. Les clients en mode noyau appellent ZwCreateFile à partir du mode noyau. Une fois que la routine de création de fichier retourne un handle de fichier, les clients KS communiquent avec des instances de pin au moyen de KS Properties.

Dans les structures de descripteur de broche, le minidriver présente des tableaux de structures KSPIN_INTERFACE et KSPIN_MEDIUM qui spécifient les interfaces et les supports pris en charge par cette usine de broches. KSPIN_DESCRIPTOR est également l’endroit où le minidriver spécifie les plages de données valides pour les broches créées par cette fabrique. Pour ce faire, il fournit un pointeur vers un tableau de structures KSDATARANGE . Le minidriver spécifie également les directions du flux de données et de communication pour les nouvelles broches créées par cette fabrique de broches.

Un minidriver permet la découverte au moment de l'exécution des fabrications de broches en prenant en charge le jeu de propriétés KSPROPSETID_Pin.

Pour créer une connexion de broche, appelez la routine KsCreatePin. Dans cet appel, le minidriver transmet un pointeur à une structure de type KSPIN_CONNECT qui décrit la connexion demandée. Lorsqu'une broche est créée, le filtre voit la nouvelle broche comme un objet de fichier subordonné à l'objet de fichier de ce filtre.

Le minidriver appelle KsValidateConnectRequest avec les structures de descripteur fournies dans le IRP_MJ_CREATE résultant. Cette routine valide ces structures et retourne un pointeur vers la structure de connexion et l’objet de fichier racine.

Les minidrivers utilisent les membres DataFlow et Communication dans les structures KSPIN_DESCRIPTOR pour définir les spécificités des pins suivantes :

• Broche source IRP contre broche récepteur IRP

  Une broche source IRP émet des IRP ; une broche IRP de réception les reçoit. Un client en mode utilisateur envoie des requêtes d’E/S directement à une épingle de réception IRP via le handle de fichier approprié. Les clients utilisent KSPROPERTY_PIN_COMMUNICATION pour vérifier si les données circulent dans ou hors d’un type de pin.

• Broche de source de données versus broche de récepteur de données

  Une broche de source de données est une broche de sortie sur un filtre ; une broche de récepteur de données est une broche d’entrée. La propriété d’être une source de données ou un récepteur est indépendante d’être une source ou un récepteur IRP. Par exemple, le client peut connecter une source de données, une broche de récepteur IRP à un récepteur de données, une broche source IRP. Les clients utilisent KSPROPERTY_PIN_DATAFLOW pour vérifier si les données transitent vers ou depuis un type de broche.

Lorsqu'on met fin à une connexion, le handle de la broche source doit être fermé avant la destruction de l'objet de fichier sous-jacent. Si la broche source s’appuie sur les ressources fournies par la broche du récepteur, il incombe à la broche du récepteur de notifier la source lorsque la connexion est terminée.

Un client interagit avec une broche de diffusion en continu du noyau en appelant la routine DeviceIoControl (décrite dans la documentation du Kit de développement logiciel (SDK) Microsoft Windows) avec IRP_MJ_DEVICE_CONTROL. L’appelant identifie sa requête par le code de contrôle d’E/S qu’il place sur Parameters.DeviceIoControl.IoControlCode dans la structure d’emplacement de la pile d’E/S.

Pour prendre en charge les demandes, le minidriver fournit un pointeur vers une structure KSDISPATCH_TABLE dans un appel à KsAllocateObjectHeader.

Les requêtes d’écriture contiennent un pointeur vers un tableau de structures KSSTREAM_HEADER, qui, à leur tour, contiennent des pointeurs vers des données de flux. Les demandes de lecture contiennent un pointeur vers un tableau de structures d’en-tête vides où les données de lecture doivent être retournées.