KSFILTER_DESCRIPTOR structure (ks.h)

Article
06/01/2023

La structure KSFILTER_DESCRIPTOR décrit les caractéristiques d’un filtre créé par une fabrique de filtres donnée.

Syntaxe

typedef struct _KSFILTER_DESCRIPTOR {
  const KSFILTER_DISPATCH     *Dispatch;
  const KSAUTOMATION_TABLE    *AutomationTable;
  ULONG                       Version;
  ULONG                       Flags;
  const GUID                  *ReferenceGuid;
  ULONG                       PinDescriptorsCount;
  ULONG                       PinDescriptorSize;
  const KSPIN_DESCRIPTOR_EX   *PinDescriptors;
  ULONG                       CategoriesCount;
  const GUID                  *Categories;
  ULONG                       NodeDescriptorsCount;
  ULONG                       NodeDescriptorSize;
  const KSNODE_DESCRIPTOR     *NodeDescriptors;
  ULONG                       ConnectionsCount;
  const KSTOPOLOGY_CONNECTION *Connections;
  const KSCOMPONENTID         *ComponentId;
} KSFILTER_DESCRIPTOR, *PKSFILTER_DESCRIPTOR;

Membres

Dispatch

Pointeur vers une structure KSFILTER_DISPATCH pour ce type de filtre. Ce membre est facultatif et doit uniquement être fourni par les clients qui souhaitent recevoir des notifications sur les créations de filtres, les suppressions, etc. Les pilotes qui s’intéressent au traitement des données (transformations) fournissent généralement cette table de répartition et une fonction de traitement. La fourniture d’une fonction de traitement de filtre au lieu de fonctions de traitement des broches individuelles est ce qui rend un pilote centré sur le filtre plutôt que sur les broches.

AutomationTable

Pointeur vers une structure KSAUTOMATION_TABLE pour ce type de filtre. La table Automation décrit les propriétés, méthodes et événements pris en charge par ce filtre. Cette table Automation est fusionnée avec la table Automation fournie par AVStream pour tous les filtres. Si le client fournit une propriété, une méthode ou un gestionnaire d’événements déjà implémenté par AVStream, l’implémentation du client remplace celle d’AVStream.

Version

Ce membre spécifie la version du descripteur de filtre. Ce membre doit être défini sur KSFILTER_DESCRIPTOR_VERSION.

Flags

Indicateurs décrivant le comportement du filtre. Spécifiez des indicateurs à l’aide d’un OR au niveau du bit, à l’exception des KSFILTER_FLAG_CRITICAL_PROCESSING et KSFILTER_FLAG_HYPERCRITICAL_PROCESSING, qui s’excluent mutuellement :

Indicateur	Description
KSFILTER_FLAG_DISPATCH_LEVEL_PROCESSING	Indique que le filtre traite au niveau de l’IRQL DISPATCH_LEVEL par opposition à PASSIVE_LEVEL. Cela s’applique au rappel du processus de filtre, comme décrit dans KSFILTER_DISPATCH.
KSFILTER_FLAG_CRITICAL_PROCESSING	Si un traitement asynchrone a été spécifié ou si le système s’exécute à PASSIVE_LEVEL et qu’un appel de processus arrive à DISPATCH_LEVEL, le traitement est effectué dans un élément de travail mis en file d’attente. Cet indicateur indique que l’élément de travail doit être placé dans la file d’attente de travail critique par opposition à la file d’attente de travail retardée.
KSFILTER_FLAG_RECEIVE_ZERO_LENGTH_SAMPLES	Définissez cet indicateur si un filtre centré sur les filtres doit recevoir des exemples de longueur nulle (en-têtes de flux avec des indicateurs mais pas de données). Si cet indicateur n’est pas défini, les échantillons de longueur nulle sont transmis aux broches en aval, avec propagation automatique des indicateurs nécessaires. Notez que ce comportement est identique à celui par défaut dans DX8 et les versions antérieures. Dans ce cas, ces exemples contournent le minidriver. Définissez l’indicateur Terminate dans KSPROCESSPIN pour « désactiver » cet indicateur. Consultez également Traitement centré sur les filtres.
KSFILTER_FLAG_DENY_USERMODE_ACCESS	Cet indicateur empêche l’accès en mode utilisateur à un filtre spécifique et toutes les épingles instanciées sur ce filtre.
KSFILTER_FLAG_HYPERCRITICAL_PROCESSING	Si le traitement asynchrone a été spécifié ou si le système s’exécute à PASSIVE_LEVEL et qu’un appel de processus arrive à DISPATCH_LEVEL, AVStream traite un élément de travail mis en file d’attente. Cet indicateur indique que l’élément de travail doit être placé dans la file d’attente de travail hypercritique, par opposition à la file d’attente de travail retardée ou à la file d’attente de travail critique.

ReferenceGuid

Pointeur vers un GUID qui est la représentation binaire de la chaîne de référence Unicode identifiant ce type de filtre. S’il existe plusieurs fabriques de filtres, chacune doit avoir un GUID unique. Notez également que d’autres méthodes de fourniture d’une chaîne de référence nécessitent que le descripteur de filtre soit inscrit à l’aide de KsCreateFilterFactory. La valeur spécifiée dans ReferenceGuid doit correspondre au GUID de référence spécifique au filtre dans le fichier INF du pilote. Consultez Initialisation d’un minidriver AVStream.

PinDescriptorsCount

Ce membre spécifie le nombre de descripteurs d’épingle fournis pour ce type de filtre dans le membre PinDescriptors . Sur Windows XP et versions ultérieures, PinDescriptorsCount peut être égal à zéro si le pilote crée des broches de manière dynamique.

PinDescriptorSize

Ce membre spécifie la taille de chaque descripteur individuel dans la table de descripteur. Cette valeur doit être un multiple de huit et avoir au moins la taille de (KSPIN_DESCRIPTOR_EX). Des valeurs plus grandes permettent d’ajouter des informations de descripteur spécifiques au client aux descripteurs d’épingle. Pour plus d’informations, consultez Remarques.

PinDescriptors

Pointeur vers un tableau de structures KSPIN_DESCRIPTOR_EX qui décrivent les broches prises en charge par ce type de filtre. Si PinDescriptorsCount est égal à zéro, définissez ce membre sur NULL..

CategoriesCount

Ce membre spécifie le nombre de GUID de catégorie fournis dans le membre Catégories pour ce type de filtre. Zéro est une valeur légale pour ce membre.

Categories

Pointeur vers un tableau de GUID de catégorie pour ce type de filtre. Si nécessaire, une interface d’appareil est inscrite pour chaque catégorie. Ce membre peut être null si et uniquement si CategoriesCount est égal à zéro.

NodeDescriptorsCount

Ce membre spécifie le nombre de descripteurs de nœud de topologie fournis dans NodeDescriptors. Zéro est une valeur légale pour ce membre.

NodeDescriptorSize

Ce membre spécifie la taille en octets de chaque descripteur individuel dans la table de descripteur. Cette valeur doit être un multiple de huit et au moins sizeof(KSNODE_DESCRIPTOR). Des valeurs plus grandes permettent d’ajouter des informations de descripteur spécifiques au client aux descripteurs de nœud. Pour plus d’informations, consultez Remarques.

NodeDescriptors

Pointeur vers un tableau de structures KSNODE_DESCRIPTOR décrivant les nœuds de topologie pour ce type de filtre. Ce membre peut être null si et uniquement si NodeDescriptorsCount est égal à zéro.

ConnectionsCount

Ce membre spécifie le nombre de connexions de topologie présentes dans Connections. Ce membre peut être égal à zéro, ce qui indique que le jeu de connexions par défaut est utilisé. L’utilisation de connexions par défaut signifie que la topologie du filtre est décrite avec un nœud de topologie unique où chaque broche sur le filtre est connectée à l’ID correspondant sur le nœud de topologie. La direction de chaque connexion est déterminée par le flux de données d’épingle.

Connections

Pointeur vers un tableau de structures KSTOPOLOGY_CONNECTION présentes dans ce type de filtre. Ce membre est facultatif ; elle peut être NULL si et uniquement si ConnectionsCount est égal à zéro (auquel cas, la topologie par défaut est utilisée).

ComponentId

Pointeur vers la structure KSCOMPONENTID pour ce type de filtre. Il est utilisé pour la propriété d’ID de composant qui fournit des informations d’identification. Ce membre est facultatif.

Remarques

Lors de la disposition du descripteur de filtre, il existe un certain nombre de macros que l’appelant peut trouver utiles. Au lieu de spécifier le nombre, la taille et une table pour les descripteurs d’épingle, les catégories, les descripteurs de nœuds et les connexions, il existe un certain nombre de macros utiles :

Macro	Description
DEFINE_KSFILTER_PIN_DESCRIPTORS(Table)	Insère automatiquement le nombre d’éléments du tableau, la taille de chaque élément de la table et la table des descripteurs d’épingles elle-même dans le descripteur de filtre.
DEFINE_KSFILTER_CATEGORIES(Table)	Insère automatiquement le nombre de catégories dans la table et la table elle-même dans le descripteur de filtre.
DEFINE_KSFILTER_CATEGORIES_NULL	Renseigne automatiquement les membres de catégorie pour un filtre qui ne définit aucune catégorie.
DEFINE_KSFILTER_NODE_DESCRIPTORS(Table)	Insère automatiquement le nombre d’éléments de la table, la taille de chaque élément de la table et la table des descripteurs de nœuds elle-même dans le descripteur de filtre.
DEFINE_KSFILTER_NODE_DESCRIPTORS_NULL	Remplit automatiquement les membres de descripteur de nœud pour un filtre qui ne définit aucun nœud de topologie.
DEFINE_KSFILTER_CONNECTIONS(Table)	Insère automatiquement le nombre de connexions dans la table et la table elle-même dans le descripteur de filtre.
DEFINE_KSFILTER_DEFAULT_CONNECTIONS	Remplit automatiquement la table connections pour un filtre qui ne définit aucune connexion explicite.

Si vous n’utilisez pas DEFINE_KS_FILTER_PIN_DESCRIPTORS pour définir PinDescriptorSize, vous devez définir PinDescriptorSize sur sizeof(KSPIN_DESCRIPTOR_EX).

De même, si vous n’utilisez pas DEFINE_KS_FILTER_NODE_DESCRIPTORS pour définir NodeDescriptorSize, vous devez définir NodeDescriptorSize sur sizeof(KSNODE_DESCRIPTOR).