KSFILTER_DESCRIPTOR Struktur (ks.h)

Artikel
02/26/2024

Die KSFILTER_DESCRIPTOR-Struktur beschreibt die Eigenschaften eines Filters, der von einer bestimmten Filterfactory erstellt wurde.

Syntax

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;

Member

Dispatch

Ein Zeiger auf eine KSFILTER_DISPATCH Struktur für diesen Filtertyp. Dieser Member ist optional und muss nur von Clients bereitgestellt werden, die Benachrichtigungen über Filtererstellungen, Löschungen usw. erhalten möchten. Treiber, die sich für die Verarbeitung von Daten (Transformationen) interessieren, stellen in der Regel diese Dispatchtabelle und eine Verarbeitungsfunktion bereit. Die Bereitstellung einer Filterverarbeitungsfunktion anstelle einzelner Pinverarbeitungsfunktionen macht einen Treiber filterzentriert statt pinzentriert.

AutomationTable

Ein Zeiger auf eine KSAUTOMATION_TABLE Struktur für diesen Filtertyp. Die Automatisierungstabelle beschreibt die Eigenschaften, Methoden und Ereignisse, die von diesem Filter unterstützt werden. Diese Automatisierungstabelle wird mit der automatisierungstabelle zusammengeführt, die von AVStream für alle Filter bereitgestellt wird. Sollte der Client eine Eigenschaft, Methode oder einen Ereignishandler bereitstellen, der bereits von AVStream implementiert wurde, ersetzt die Implementierung des Clients die von AVStream.

Version

Dieses Element gibt die Version des Filterdeskriptors an. Dieses Element sollte auf KSFILTER_DESCRIPTOR_VERSION festgelegt werden.

Flags

Flags, die das Verhalten des Filters beschreiben. Geben Sie Flags mithilfe eines bitweisen OR an, mit Ausnahme von KSFILTER_FLAG_CRITICAL_PROCESSING und KSFILTER_FLAG_HYPERCRITICAL_PROCESSING, die sich gegenseitig ausschließen:

Flag	Beschreibung
KSFILTER_FLAG_DISPATCH_LEVEL_PROCESSING	Gibt an, dass der Filter im IRQL-DISPATCH_LEVEL im Gegensatz zu PASSIVE_LEVEL verarbeitet. Dies gilt für den Rückruf des Filterprozesses, wie in KSFILTER_DISPATCH beschrieben.
KSFILTER_FLAG_CRITICAL_PROCESSING	Wenn die asynchrone Verarbeitung angegeben wurde oder das System bei PASSIVE_LEVEL ausgeführt wird und ein Prozessaufruf bei DISPATCH_LEVEL erfolgt, erfolgt die Verarbeitung in einer Warteschlange. Dieses Flag gibt an, dass das Arbeitselement in der kritischen Arbeitswarteschlange und nicht in der verzögerten Arbeitswarteschlange platziert werden soll.
KSFILTER_FLAG_RECEIVE_ZERO_LENGTH_SAMPLES	Legen Sie dieses Flag fest, wenn ein filterorientierter Filter Stichproben der Länge null empfangen muss (Streamheader mit Flags, aber keine Daten). Wenn dieses Flag nicht festgelegt ist, werden Nulllängenbeispiele an nachgeschaltete Pins mit automatischer Weitergabe der erforderlichen Flags übergeben. Beachten Sie, dass dies mit dem Standardverhalten in DX8 und früher identisch ist. In diesem Fall umgehen diese Beispiele den Minitreiber. Legen Sie das Flag Beenden in KSPROCESSPIN so fest, dass dieses Flag "deaktiviert" wird. Weitere Informationen finden Sie unter Filter-Centric Processing.
KSFILTER_FLAG_DENY_USERMODE_ACCESS	Dieses Flag verhindert den Zugriff des Benutzermodus auf einen bestimmten Filter und alle für diesen Filter instanziierten Pins.
KSFILTER_FLAG_HYPERCRITICAL_PROCESSING	Wenn die asynchrone Verarbeitung angegeben wurde oder das System bei PASSIVE_LEVEL ausgeführt wird und bei DISPATCH_LEVEL ein Prozessaufruf eingeht, verarbeitet AVStream ein Arbeitselement in der Warteschlange. Dieses Flag gibt an, dass das Arbeitselement in der hyperkritischen Arbeitswarteschlange platziert werden soll, im Gegensatz zur verzögerten Arbeitswarteschlange oder der kritischen Arbeitswarteschlange.

ReferenceGuid

Ein Zeiger auf eine GUID, die die binäre Darstellung der Unicode-Verweiszeichenfolge darstellt, die diesen Filtertyp identifiziert. Wenn mehrere Filterfabriken vorhanden sind, muss jede über eine eindeutige GUID verfügen. Beachten Sie auch, dass andere Methoden zum Bereitstellen einer Verweiszeichenfolge erfordern, dass der Filterdeskriptor mit KsCreateFilterFactory registriert wird. Der in ReferenceGuid angegebene Wert muss mit der filterspezifischen Referenz-GUID in der INF-Datei des Treibers übereinstimmen. Weitere Informationen finden Sie unter Initialisieren eines AVStream Minidrivers.

PinDescriptorsCount

Dieses Element gibt die Anzahl der Pindeskriptoren an, die für diesen Filtertyp im PinDescriptors-Member bereitgestellt werden. Unter Windows XP und höher kann PinDescriptorsCount 0 sein, wenn der Treiber dynamisch Pins erstellt.

PinDescriptorSize

Dieses Element gibt die Größe jedes einzelnen Deskriptors in der Deskriptortabelle an. Dieser Wert muss ein Vielfaches von acht sein und mindestens sizeof (KSPIN_DESCRIPTOR_EX) sein. Größere Werte ermöglichen das Anheften von clientspezifischen Deskriptorinformationen. Weitere Informationen finden Sie unter Hinweise.

PinDescriptors

Ein Zeiger auf ein Array von KSPIN_DESCRIPTOR_EX Strukturen, die die von diesem Filtertyp unterstützten Pins beschreiben. Wenn PinDescriptorsCount 0 ist, legen Sie dieses Element auf NULL fest.

CategoriesCount

Dieses Member gibt die Anzahl der Kategorie-GUIDs an, die im Member Kategorien für diesen Filtertyp bereitgestellt werden. Null ist ein gesetzlicher Wert für dieses Element.

Categories

Ein Zeiger auf ein Array von Kategorien-GUIDs für diesen Filtertyp. Bei Bedarf wird für jede Kategorie eine Geräteschnittstelle registriert. Dieser Member kann nur null sein, wenn CategoriesCount 0 ist.

NodeDescriptorsCount

Dieses Element gibt die Anzahl der Topologieknotendeskriptoren an, die in NodeDescriptors bereitgestellt werden. Null ist ein gesetzlicher Wert für dieses Element.

NodeDescriptorSize

Dieses Element gibt die Größe jedes einzelnen Deskriptors in Byte in der Deskriptortabelle an. Dieser Wert muss ein Vielfaches von acht und mindestens sizeof(KSNODE_DESCRIPTOR)sein. Größere Werte ermöglichen das Anfügen clientspezifischer Deskriptorinformationen an Knotendeskriptoren. Weitere Informationen finden Sie unter Hinweise.

NodeDescriptors

Ein Zeiger auf ein Array von KSNODE_DESCRIPTOR Strukturen, die die Topologieknoten für diesen Filtertyp beschreiben. Dieser Member kann nur null sein, wenn NodeDescriptorsCount 0 ist.

ConnectionsCount

Dieses Element gibt die Anzahl der Topologieverbindungen an, die in Connections vorhanden sind. Dieser Member kann null sein, was angibt, dass der Standardverbindungssatz verwendet wird. Die Verwendung von Standardverbindungen bedeutet, dass die Topologie des Filters mit einem einzelnen Topologieknoten beschrieben wird, bei dem jeder Pin am Filter mit der entsprechenden ID auf dem Topologieknoten verbunden ist. Die Richtung jeder Verbindung wird durch den Pindatenfluss bestimmt.

Connections

Ein Zeiger auf ein Array von KSTOPOLOGY_CONNECTION Strukturen, die in diesem Filtertyp vorhanden sind. Dieses Element ist optional; Es kann nur NULL sein, wenn ConnectionsCount null ist (in diesem Fall wird die Standardtopologie verwendet).

ComponentId

Ein Zeiger auf die KSCOMPONENTID-Struktur für diesen Filtertyp. Dies wird für die Komponenten-ID-Eigenschaft verwendet, die Identifikationsinformationen bereitstellt. Dieses Member ist optional.

Hinweise

Beim Festlegen des Filterdeskriptors gibt es eine Reihe von Makros, die der Aufrufer möglicherweise als nützlich empfindet. Anstatt Anzahl, Größe und eine Tabelle für Anheftdeskriptoren, Kategorien, Knotendeskriptoren und Verbindungen anzugeben, gibt es eine Reihe nützlicher Makros:

Makro	Beschreibung
DEFINE_KSFILTER_PIN_DESCRIPTORS(Tabelle)	Fügt automatisch die Anzahl der Elemente in der Tabelle, die Größe jedes Elements in der Tabelle und die Tabelle der Anheftdeskriptoren selbst in den Filterdeskriptor ein.
DEFINE_KSFILTER_CATEGORIES(Tabelle)	Fügt automatisch die Anzahl der Kategorien in der Tabelle und die Tabelle selbst in den Filterdeskriptor ein.
DEFINE_KSFILTER_CATEGORIES_NULL	Füllt automatisch die Kategoriemitglieder für einen Filter aus, der keine Kategorien definiert.
DEFINE_KSFILTER_NODE_DESCRIPTORS(Tabelle)	Fügt automatisch die Anzahl der Elemente in der Tabelle, die Größe jedes Elements in der Tabelle und die Tabelle der Knotendeskriptoren selbst in den Filterdeskriptor ein.
DEFINE_KSFILTER_NODE_DESCRIPTORS_NULL	Füllt automatisch die Knotendeskriptorelemente für einen Filter aus, der keine Topologieknoten definiert.
DEFINE_KSFILTER_CONNECTIONS(Tabelle)	Fügt automatisch die Anzahl der Verbindungen in der Tabelle und der Tabelle selbst in den Filterdeskriptor ein.
DEFINE_KSFILTER_DEFAULT_CONNECTIONS	Füllt automatisch die Verbindungstabelle für einen Filter aus, der keine expliziten Verbindungen definiert.

Wenn Sie pinDescriptorSize nicht mit DEFINE_KS_FILTER_PIN_DESCRIPTORS festlegen, müssen Sie PinDescriptorSize auf sizeof(KSPIN_DESCRIPTOR_EX) festlegen.

Wenn Sie DEFINE_KS_FILTER_NODE_DESCRIPTORS nicht zum Festlegen von NodeDescriptorSize verwenden, müssen Sie NodeDescriptorSize auf sizeof(KSNODE_DESCRIPTOR) festlegen.