структура KSFILTER_DESCRIPTOR (ks.h)

Статья
03/09/2023

Структура KSFILTER_DESCRIPTOR описывает характеристики фильтра, созданного заданной фабрикой фильтров.

Синтаксис

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;

Члены

Dispatch

Указатель на структуру KSFILTER_DISPATCH для этого типа фильтра. Этот член является необязательным и должен предоставляться только клиентами, которые хотят получать уведомления о создании, удалении фильтров и т. д. Драйверы, заинтересованные в обработке данных (преобразованиях), обычно предоставляют эту таблицу диспетчеризации и функцию обработки. Предоставление функции обработки фильтров вместо отдельных функций обработки пин-кода делает драйвер ориентированным на фильтрацию, а не на закрепление.

AutomationTable

Указатель на структуру KSAUTOMATION_TABLE для этого типа фильтра. В таблице автоматизации описываются свойства, методы и события, поддерживаемые этим фильтром. Эта таблица автоматизации объединяется с таблицей автоматизации, предоставляемой AVStream для всех фильтров. Если клиент предоставляет свойство, метод или обработчик событий, уже реализованный AVStream, реализация клиента заменяет avStream.

Version

Этот член задает версию дескриптора фильтра. Для этого элемента должно быть задано значение KSFILTER_DESCRIPTOR_VERSION.

Flags

Флаги, описывающие поведение фильтра. Укажите флаги с помощью побитового ИЛИ, за исключением KSFILTER_FLAG_CRITICAL_PROCESSING и KSFILTER_FLAG_HYPERCRITICAL_PROCESSING, которые являются взаимоисключающими:

Flag	Описание
KSFILTER_FLAG_DISPATCH_LEVEL_PROCESSING	Указывает, что процессы фильтрации в IRQL DISPATCH_LEVEL, а не PASSIVE_LEVEL. Это относится к обратному вызову процесса фильтрации, как описано в KSFILTER_DISPATCH.
KSFILTER_FLAG_CRITICAL_PROCESSING	Если указана асинхронная обработка или система выполняется в PASSIVE_LEVEL и вызов процесса поступает в DISPATCH_LEVEL, обработка выполняется в рабочем элементе, помещенном в очередь. Этот флаг указывает, что рабочий элемент должен размещаться в критической рабочей очереди, а не в отложенной очереди.
KSFILTER_FLAG_RECEIVE_ZERO_LENGTH_SAMPLES	Установите этот флаг, если фильтр, ориентированный на фильтр, должен получать образцы нулевой длины (заголовки потоков с флагами, но без данных). Если этот флаг не задан, примеры нулевой длины передаются подчиненным контактам с автоматическим распространением необходимых флагов. Обратите внимание, что это поведение идентично по умолчанию в DX8 и предыдущих версиях. В этом случае эти примеры обходят мини-диск. Установите флаг Завершить в KSPROCESSPIN , чтобы отключить этот флаг. См. также раздел Фильтрация обработки.
KSFILTER_FLAG_DENY_USERMODE_ACCESS	Этот флаг запрещает доступ в пользовательском режиме к определенному фильтру и всем контактам, созданным в этом фильтре.
KSFILTER_FLAG_HYPERCRITICAL_PROCESSING	Если указана асинхронная обработка или система выполняется в PASSIVE_LEVEL и вызов процесса поступает в DISPATCH_LEVEL, AVStream обрабатывает рабочий элемент в очереди. Этот флаг указывает, что рабочий элемент должен размещаться в гиперкритической рабочей очереди, а не в отложенной или критической рабочей очереди.

ReferenceGuid

Указатель на GUID, который является двоичным представлением строки ссылки Юникода, определяющей этот тип фильтра. Если существует несколько фабрик фильтров, каждая из них должна иметь уникальный GUID. Также обратите внимание, что другие методы предоставления ссылочной строки требуют регистрации дескриптора фильтра с помощью KsCreateFilterFactory. Значение, указанное в ReferenceGuid, должно соответствовать идентификатору GUID ссылки фильтра в INF-файле драйвера. См. раздел Инициализация avStream Minidriver.

PinDescriptorsCount

Этот элемент указывает количество дескрипторов контактов, которые предоставляются для этого типа фильтра в элементе PinDescriptors . В Windows XP и более поздних версиях PinDescriptorsCount может иметь нулевое значение, если драйвер создает контакты динамически.

PinDescriptorSize

Этот элемент задает размер каждого отдельного дескриптора в таблице дескрипторов. Это значение должно быть кратным восьми и иметь по крайней мере размер (KSPIN_DESCRIPTOR_EX). Более крупные значения позволяют добавлять сведения о дескрипторе для конкретного клиента в дескрипторы контактов. Дополнительные сведения см. в разделе Примечания.

PinDescriptors

Указатель на массив KSPIN_DESCRIPTOR_EX структур, описывающих контакты, поддерживаемые этим типом фильтра. Если PinDescriptorsCount равно нулю, присвойте этому члену значение NULL.

CategoriesCount

Этот элемент указывает количество идентификаторов GUID категории, которые предоставляются в элементе Categories для этого типа фильтра. Ноль является юридическим значением для этого элемента.

Categories

Указатель на массив идентификаторов GUID категории для этого типа фильтра. При необходимости интерфейс устройства регистрируется для каждой категории. Этот член может иметь значение NULL , если и только в том случае, если CategoriesCount равно нулю.

NodeDescriptorsCount

Этот член указывает количество дескрипторов узла топологии, предоставляемых в NodeDescriptors. Ноль является юридическим значением для этого элемента.

NodeDescriptorSize

Этот член задает размер в байтах каждого отдельного дескриптора в таблице дескрипторов. Это значение должно быть кратным восьми и не менее sizeof(KSNODE_DESCRIPTOR). Большие значения позволяют добавлять сведения о дескрипторе для конкретного клиента в дескрипторы узла. Дополнительные сведения см. в разделе Примечания.

NodeDescriptors

Указатель на массив KSNODE_DESCRIPTOR структур, описывающих узлы топологии для этого типа фильтра. Этот член может иметь значение NULL только в том случае, если NodeDescriptorsCount равно нулю.

ConnectionsCount

Этот член указывает количество подключений топологии, присутствующих в Connections. Этот элемент может иметь нулевое значение, указывающее, что используется набор подключений по умолчанию. Использование подключений по умолчанию означает, что топология фильтра описывается с одним узлом топологии, где каждый контакт на фильтре подключен к соответствующему идентификатору на узле топологии. Направление каждого подключения определяется потоком данных для закрепления.

Connections

Указатель на массив KSTOPOLOGY_CONNECTION структур, присутствующих в этом типе фильтра. Этот элемент является необязательным; Значение может иметь значение NULL , если и только в том случае, если ConnectionsCount равно нулю (в этом случае используется топология по умолчанию).

ComponentId

Указатель на структуру KSCOMPONENTID для этого типа фильтра. Используется для свойства идентификатора компонента, предоставляющего идентификационные сведения. Этот член является необязательным.

При создании дескриптора фильтра существует ряд макросов, которые могут оказаться полезными для вызывающего объекта. Вместо указания количества, размера и таблицы для дескрипторов, категорий, дескрипторов узлов и подключений существует ряд полезных макросов:

Макрос	Описание
DEFINE_KSFILTER_PIN_DESCRIPTORS(Таблица)	Автоматически вставляет в дескриптор фильтра количество элементов в таблице, размер каждого элемента в таблице и таблицу дескрипторов контактов.
DEFINE_KSFILTER_CATEGORIES(таблица)	Автоматически вставляет количество категорий в таблице и саму таблицу в дескриптор фильтра.
DEFINE_KSFILTER_CATEGORIES_NULL	Автоматически заполняет элементы категории для фильтра, который не определяет категории.
DEFINE_KSFILTER_NODE_DESCRIPTORS(Таблица)	Автоматически вставляет количество элементов в таблице, размер каждого элемента в таблице и таблицу дескрипторов узлов в дескриптор фильтра.
DEFINE_KSFILTER_NODE_DESCRIPTORS_NULL	Автоматически заполняет члены дескриптора узла для фильтра, который не определяет узлы топологии.
DEFINE_KSFILTER_CONNECTIONS(Таблица)	Автоматически вставляет количество подключений в таблицу и саму таблицу в дескриптор фильтра.
DEFINE_KSFILTER_DEFAULT_CONNECTIONS	Автоматически заполняет таблицу подключений для фильтра, который не определяет явных соединений.

Если вы не используете DEFINE_KS_FILTER_PIN_DESCRIPTORS для задания PinDescriptorSize, необходимо задать для Параметра PinDescriptorSizeзначение sizeof(KSPIN_DESCRIPTOR_EX).

Аналогичным образом, если вы не используете DEFINE_KS_FILTER_NODE_DESCRIPTORS для задания NodeDescriptorSize, необходимо задать для NodeDescriptorSizeзначение sizeof(KSNODE_DESCRIPTOR).