KSFILTER_DESCRIPTOR struttura (ks.h)

Articolo
03/17/2023

La struttura KSFILTER_DESCRIPTOR descrive le caratteristiche di un filtro creato da una determinata factory di filtro.

Sintassi

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;

Members

Dispatch

Puntatore a una struttura KSFILTER_DISPATCH per questo tipo di filtro. Questo membro è facoltativo e deve essere fornito solo dai client che desiderano ricevere notifiche sulle creazioni di filtro, le eliminazioni e così via. I driver interessati all'elaborazione dei dati (trasformazioni) in genere forniscono questa tabella di invio e una funzione di elaborazione. La fornitura di una funzione di elaborazione dei filtri anziché di singole funzioni di elaborazione dei pin è ciò che rende un filtro incentrato sul driver anziché incentrato sui pin.

AutomationTable

Puntatore a una struttura KSAUTOMATION_TABLE per questo tipo di filtro. La tabella di automazione descrive le proprietà, i metodi e gli eventi supportati da questo filtro. Questa tabella di automazione viene unita alla tabella di automazione fornita da AVStream per tutti i filtri. Se il client fornisce una proprietà, un metodo o un gestore eventi già implementato da AVStream, l'implementazione del client sostituisce avStream.

Version

Questo membro specifica la versione del descrittore di filtro. Questo membro deve essere impostato su KSFILTER_DESCRIPTOR_VERSION.

Flags

Flag che descrivono il comportamento del filtro. Specificare i flag usando un OR bit per bit, ad eccezione di KSFILTER_FLAG_CRITICAL_PROCESSING e KSFILTER_FLAG_HYPERCRITICAL_PROCESSING, che si escludono a vicenda:

Flag	Descrizione
KSFILTER_FLAG_DISPATCH_LEVEL_PROCESSING	Indica che i processi di filtro in IRQL DISPATCH_LEVEL anziché PASSIVE_LEVEL. Questo vale per il callback del processo di filtro, come descritto in KSFILTER_DISPATCH.
KSFILTER_FLAG_CRITICAL_PROCESSING	Se l'elaborazione asincrona è stata specificata o se il sistema è in esecuzione in PASSIVE_LEVEL e una chiamata di processo viene eseguita in DISPATCH_LEVEL, l'elaborazione viene eseguita in un elemento di lavoro in coda. Questo flag indica che l'elemento di lavoro deve essere inserito nella coda di lavoro critica anziché nella coda di lavoro ritardata.
KSFILTER_FLAG_RECEIVE_ZERO_LENGTH_SAMPLES	Impostare questo flag se un filtro incentrato su filtro deve ricevere esempi di lunghezza zero (intestazioni di flusso con flag ma senza dati). Se questo flag non è impostato, gli esempi di lunghezza zero vengono passati ai pin downstream, con propagazione automatica dei flag necessari. Si noti che questo comportamento è identico al comportamento predefinito in DX8 e precedente. In questo caso, questi esempi ignorano il minidriver. Impostare il flag Termina in KSPROCESSPIN su "disattiva" questo flag. Vedere Anche l'elaborazione incentrata sui filtri.
KSFILTER_FLAG_DENY_USERMODE_ACCESS	Questo flag impedisce l'accesso in modalità utente a un filtro specifico e a tutti i pin generati su questo filtro.
KSFILTER_FLAG_HYPERCRITICAL_PROCESSING	Se l'elaborazione asincrona è stata specificata o se il sistema è in esecuzione in PASSIVE_LEVEL e una chiamata di processo viene eseguita in DISPATCH_LEVEL, AVStream elabora un elemento di lavoro in coda. Questo flag indica che l'elemento di lavoro deve essere inserito nella coda di lavoro ipercritica anziché nella coda di lavoro ritardata o nella coda di lavoro critica.

ReferenceGuid

Puntatore a un GUID che rappresenta la rappresentazione binaria della stringa di riferimento Unicode che identifica questo tipo di filtro. Se esistono più factory di filtri, ognuna deve avere un GUID univoco. Si noti anche che altri metodi di fornitura di una stringa di riferimento richiedono che il descrittore di filtro venga registrato usando KsCreateFilterFactory. Il valore specificato in ReferenceGuid deve corrispondere al GUID di riferimento specifico del filtro nel file INF del driver. Vedere Inizializzazione di un minidriver AVStream.

PinDescriptorsCount

Questo membro specifica il numero di descrittori di pin forniti per questo tipo di filtro nel membro PinDescriptors . In Windows XP e versioni successive, PinDescriptorsCount può essere zero se il driver crea pin in modo dinamico.

PinDescriptorSize

Questo membro specifica le dimensioni di ogni singolo descrittore nella tabella descrittore. Questo valore deve essere un multiplo di otto e deve essere almeno sizeof (KSPIN_DESCRIPTOR_EX). I valori più grandi consentono l'aggiunta delle informazioni del descrittore specifico del client ai descrittori pin. Vedere altre informazioni nelle osservazioni.

PinDescriptors

Puntatore a una matrice di strutture KSPIN_DESCRIPTOR_EX che descrivono i pin supportati da questo tipo di filtro. Se PinDescriptorsCount è zero, impostare questo membro su NULL..

CategoriesCount

Questo membro specifica il numero di GUID di categoria forniti nel membro Categorie per questo tipo di filtro. Zero è un valore legale per questo membro.

Categories

Puntatore a una matrice di GUID di categoria per questo tipo di filtro. Se necessario, un'interfaccia del dispositivo viene registrata per ogni categoria. Questo membro può essere null se e solo se CategoriesCount è zero.

NodeDescriptorsCount

Questo membro specifica il numero di descrittori del nodo della topologia forniti in NodeDescriptors. Zero è un valore legale per questo membro.

NodeDescriptorSize

Questo membro specifica le dimensioni in byte di ogni singolo descrittore nella tabella descrittore. Questo valore deve essere un multiplo di otto e almeno dimensioniof(KSNODE_DESCRIPTOR). I valori più grandi consentono l'aggiunta delle informazioni del descrittore specifico del client ai descrittori di nodo. Vedere altre informazioni nelle osservazioni.

NodeDescriptors

Puntatore a una matrice di strutture KSNODE_DESCRIPTOR che descrivono i nodi della topologia per questo tipo di filtro. Questo membro può essere null se e solo se NodeDescriptorsCount è zero.

ConnectionsCount

Questo membro specifica il numero di connessioni della topologia presenti in Connections. Questo membro può essere zero che indica che viene usato il set di connessione predefinito. L'uso delle connessioni predefinite significa che la topologia del filtro viene descritta con un singolo nodo della topologia in cui ogni pin del filtro è connesso all'ID corrispondente nel nodo della topologia. La direzione di ogni connessione è determinata dal flusso di dati pin.

Connections

Puntatore a una matrice di strutture KSTOPOLOGY_CONNECTION presenti in questo tipo di filtro. Questo membro è facoltativo; può essere NULL se e solo se ConnectionsCount è zero (in questo caso viene usata la topologia predefinita).

ComponentId

Puntatore alla struttura KSCOMPONENTID per questo tipo di filtro. Viene usato per la proprietà ID componente che fornisce informazioni di identificazione. Questo membro è facoltativo.

Commenti

Nel definire il descrittore di filtro, esistono numerose macro che il chiamante può trovare utile. Anziché specificare conteggio, dimensioni e una tabella per descrittori pin, categorie, descrittori di nodi e connessioni, sono disponibili diverse macro utili:

Macro	Descrizione
DEFINE_KSFILTER_PIN_DESCRIPTORS(tabella)	Inserisce automaticamente il numero di elementi nella tabella, le dimensioni di ogni elemento della tabella e la tabella dei descrittori pin stessi nel descrittore del filtro.
DEFINE_KSFILTER_CATEGORIES(tabella)	Inserisce automaticamente il numero di categorie nella tabella e la tabella stessa nel descrittore di filtro.
DEFINE_KSFILTER_CATEGORIES_NULL	Compila automaticamente i membri della categoria per un filtro che non definisce categorie.
DEFINE_KSFILTER_NODE_DESCRIPTORS(tabella)	Inserisce automaticamente il numero di elementi nella tabella, le dimensioni di ogni elemento della tabella e la tabella dei descrittori del nodo stesso nel descrittore del filtro.
DEFINE_KSFILTER_NODE_DESCRIPTORS_NULL	Riempie automaticamente i membri del descrittore del nodo per un filtro che non definisce nodi di topologia.
DEFINE_KSFILTER_CONNECTIONS(tabella)	Inserisce automaticamente il numero di connessioni nella tabella e la tabella stessa nel descrittore del filtro.
DEFINE_KSFILTER_DEFAULT_CONNECTIONS	Compila automaticamente la tabella connessioni per un filtro che non definisce connessioni esplicite.

Se non si usa DEFINE_KS_FILTER_PIN_DESCRIPTORS per impostare PinDescriptorSize, è necessario impostare PinDescriptorSize su sizeof(KSPIN_DESCRIPTOR_EX).

Analogamente, se non si usa DEFINE_KS_FILTER_NODE_DESCRIPTORS per impostare NodeDescriptorSize, è necessario impostare NodeDescriptorSize su sizeof(KSNODE_DESCRIPTOR).