structure KSFILTER_DESCRIPTOR (ks.h)

La structure KSFILTER_DESCRIPTOR décrit les caractéristiques d’un filtre créé par une fabrique de filtre 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 filtre, les suppressions, et ainsi de suite. Les pilotes intéressés par le traitement des données (transformations) fournissent généralement cette table de distribution 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 filtre de pilote centré sur le filtre plutôt que sur l’axe des broches.

AutomationTable

Pointeur vers une structure KSAUTOMATION_TABLE pour ce type de filtre. La table Automation décrit les propriétés, les méthodes et les é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 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’une or au niveau du bit, à l’exception de KSFILTER_FLAG_CRITICAL_PROCESSING et de KSFILTER_FLAG_HYPERCRITICAL_PROCESSING, qui sont mutuellement exclusifs :

Indicateur Description
KSFILTER_FLAG_DISPATCH_LEVEL_PROCESSING Indique que les processus de filtre à 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 le traitement asynchrone a été spécifié ou si le système s’exécute à PASSIVE_LEVEL et qu’un appel de processus se trouve à DISPATCH_LEVEL, le traitement est effectué dans un élément de travail en file d’attente. Cet indicateur indique que l’élément de travail doit être placé sur 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 le filtre 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 la propagation automatique des indicateurs nécessaires. Notez qu’il s’agit d’un comportement identique au comportement par défaut dans DX8 et antérieur. Si cela se produit, ces exemples contournent le minidriver. Définissez l’indicateur d’arrêt dans KSPROCESSPIN pour « désactiver » cet indicateur. Consultez également le traitement centré sur le filtre.
KSFILTER_FLAG_DENY_USERMODE_ACCESS Cet indicateur empêche l’accès en mode utilisateur à un filtre spécifique et toutes les broches 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 se trouve à DISPATCH_LEVEL, AVStream traite un élément de travail en file d’attente. Cet indicateur indique que l’élément de travail doit être placé sur 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. Si plusieurs fabriques de filtre existent, 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 de broche fournis pour ce type de filtre dans le membre PinDescriptors . Sur Windows XP et versions ultérieures, PinDescriptorsCount peut être zéro si le pilote crée des broches dynamiquement.

PinDescriptorSize

Ce membre spécifie la taille de chaque descripteur individuel dans la table de descripteur. Cette valeur doit être multiple de huit et doit avoir au moins la taille (KSPIN_DESCRIPTOR_EX). Les valeurs plus grandes permettent aux informations de descripteur spécifiques au client d’être ajoutées aux descripteurs pin. Consultez des informations supplémentaires dans les 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 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 de 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 plusieurs de huit et au moins de taille (KSNODE_DESCRIPTOR). Les valeurs plus grandes permettent aux informations de descripteur spécifiques au client d’être ajoutées aux descripteurs de nœud. Consultez des informations supplémentaires dans les 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 Connexions. Ce membre peut être zéro indiquant 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 seul nœud de topologie où chaque épingle du 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 pin.

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 zéro (dans ce cas, la topologie par défaut est utilisée).

ComponentId

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

Remarques

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

Macro Description
DEFINE_KSFILTER_PIN_DESCRIPTORS(Table) Insère automatiquement le nombre d’éléments dans la table, la taille de chaque élément du tableau et la table des descripteurs d’épingle lui-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 dans la table, la taille de chaque élément dans la table et la table des descripteurs de nœud lui-même dans le descripteur de filtre.
DEFINE_KSFILTER_NODE_DESCRIPTORS_NULL Renseigne automatiquement les membres du 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 Renseigne automatiquement la table connexions 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).

Configuration requise

   
Client minimal pris en charge Disponible dans Microsoft Windows XP et les systèmes d’exploitation ultérieurs et dans Microsoft DirectX 8.0 et versions ultérieures.
En-tête ks.h (inclure Ks.h)

Voir aussi

KSCOMPONENTID

KSFILTER_DISPATCH

KSNODE_DESCRIPTOR

KSPIN_DESCRIPTOR_EX

KSTOPOLOGY_CONNECTION

KsCreateFilterFactory