estructura KSFILTER_DESCRIPTOR (ks.h)

Artículo
03/09/2023

La estructura de KSFILTER_DESCRIPTOR describe las características de un filtro creado por un generador de filtros determinado.

Sintaxis

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;

Miembros

Dispatch

Puntero a una estructura de KSFILTER_DISPATCH para este tipo de filtro. Este miembro es opcional y solo los clientes que desean recibir notificaciones sobre las creaciones de filtros, eliminaciones, etc. Los controladores interesados en el procesamiento de datos (transformaciones) normalmente proporcionan esta tabla de distribución y una función de procesamiento. Proporcionar una función de procesamiento de filtros en lugar de funciones de procesamiento de patillas individuales es lo que hace que un filtro de controlador se centra en el filtro en lugar de centrado en el anclaje.

AutomationTable

Puntero a una estructura de KSAUTOMATION_TABLE para este tipo de filtro. La tabla de automatización es lo que describe las propiedades, los métodos y los eventos admitidos por este filtro. Esta tabla de automatización se combina con la tabla de automatización proporcionada por AVStream para todos los filtros. Si el cliente proporciona una propiedad, un método o un controlador de eventos ya implementado por AVStream, la implementación del cliente reemplaza a AVStream.

Version

Este miembro especifica la versión del descriptor de filtro. Este miembro debe establecerse en KSFILTER_DESCRIPTOR_VERSION.

Flags

Marcas que describen el comportamiento del filtro. Especifique marcas con un OR bit a bit, con la excepción de KSFILTER_FLAG_CRITICAL_PROCESSING y KSFILTER_FLAG_HYPERCRITICAL_PROCESSING, que son mutuamente excluyentes:

Marca	Descripción
KSFILTER_FLAG_DISPATCH_LEVEL_PROCESSING	Indica que los procesos de filtro en IRQL DISPATCH_LEVEL en lugar de PASSIVE_LEVEL. Esto se aplica a la devolución de llamada del proceso de filtro como se describe en KSFILTER_DISPATCH.
KSFILTER_FLAG_CRITICAL_PROCESSING	Si se ha especificado el procesamiento asincrónico o si el sistema se ejecuta en PASSIVE_LEVEL y una llamada de proceso entra en DISPATCH_LEVEL, el procesamiento se realiza en un elemento de trabajo en cola. Esta marca indica que el elemento de trabajo debe colocarse en la cola de trabajo crítica en lugar de la cola de trabajo retrasada.
KSFILTER_FLAG_RECEIVE_ZERO_LENGTH_SAMPLES	Establezca esta marca si un filtro centrado en filtros necesita recibir muestras de longitud cero (encabezados de secuencia con marcas pero sin datos). Si no se establece esta marca, las muestras de longitud cero se pasan a las patillas descendentes, con propagación automática de marcas necesarias. Tenga en cuenta que esto es idéntico al comportamiento predeterminado en DX8 y anterior. Si esto sucede, estos ejemplos omiten el minidriver. Establezca la marca Terminate (Finalizar ) en KSPROCESSPIN en "desactivar" esta marca. Consulte también Procesamiento centrado en filtros.
KSFILTER_FLAG_DENY_USERMODE_ACCESS	Esta marca impide el acceso en modo de usuario a un filtro específico y a todas las patillas que se crean instancias en este filtro.
KSFILTER_FLAG_HYPERCRITICAL_PROCESSING	Si se ha especificado el procesamiento asincrónico o si el sistema se ejecuta en PASSIVE_LEVEL y una llamada de proceso entra en DISPATCH_LEVEL, AVStream procesa un elemento de trabajo en cola. Esta marca indica que el elemento de trabajo debe colocarse en la cola de trabajo hipercrítica en lugar de la cola de trabajo retrasada o en la cola de trabajo crítica.

ReferenceGuid

Puntero a un GUID que es la representación binaria de la cadena de referencia Unicode que identifica este tipo de filtro. Si existen varios generadores de filtros, cada uno debe tener un GUID único. Tenga en cuenta también que otros métodos para proporcionar una cadena de referencia requieren que el descriptor de filtro se registre mediante KsCreateFilterFactory. El valor especificado en ReferenceGuid debe coincidir con el GUID de referencia específico del filtro en el archivo INF del controlador. Consulte Inicialización de un minidriver AVStream.

PinDescriptorsCount

Este miembro especifica el número de descriptores de anclaje que se proporcionan para este tipo de filtro en el miembro PinDescriptors . En Windows XP y versiones posteriores, PinDescriptorsCount puede ser cero si el controlador crea patillas dinámicamente.

PinDescriptorSize

Este miembro especifica el tamaño de cada descriptor individual de la tabla descriptor. Este valor debe ser un múltiplo de ocho y debe ser al menos sizeof (KSPIN_DESCRIPTOR_EX). Los valores más grandes permiten anexar información de descriptores específicos del cliente a descriptores de anclaje. Vea información adicional en Comentarios.

PinDescriptors

Puntero a una matriz de estructuras de KSPIN_DESCRIPTOR_EX que describen los pines admitidos por este tipo de filtro. Si PinDescriptorsCount es cero, establezca este miembro en NULL..

CategoriesCount

Este miembro especifica el número de GUID de categoría que se proporcionan en el miembro Categories para este tipo de filtro. Cero es un valor legal para este miembro.

Categories

Puntero a una matriz de GUID de categoría para este tipo de filtro. Si es necesario, se registra una interfaz de dispositivo para cada categoría. Este miembro puede ser null si y solo si CategoriesCount es cero.

NodeDescriptorsCount

Este miembro especifica el número de descriptores de nodo de topología proporcionados en NodeDescriptors. Cero es un valor legal para este miembro.

NodeDescriptorSize

Este miembro especifica el tamaño en bytes de cada descriptor individual de la tabla descriptor. Este valor debe ser un múltiplo de ocho y al menos sizeof(KSNODE_DESCRIPTOR). Los valores más grandes permiten anexar información de descriptores específicos del cliente a descriptores de nodo. Vea información adicional en Comentarios.

NodeDescriptors

Puntero a una matriz de estructuras de KSNODE_DESCRIPTOR que describen los nodos de topología para este tipo de filtro. Este miembro puede ser null si y solo si NodeDescriptorsCount es cero.

ConnectionsCount

Este miembro especifica el número de conexiones de topología presentes en Connections. Este miembro puede ser cero que indica que se usa el conjunto de conexiones predeterminado. El uso de conexiones predeterminadas significa que la topología del filtro se describe con un único nodo de topología donde cada pin del filtro está conectado al identificador correspondiente en el nodo de topología. La dirección de cada conexión viene determinada por el flujo de datos anclado.

Connections

Puntero a una matriz de estructuras de KSTOPOLOGY_CONNECTION presentes en este tipo de filtro. Este miembro es opcional; puede ser NULL si y solo si ConnectionsCount es cero (en cuyo caso se usa la topología predeterminada).

ComponentId

Puntero a la estructura KSCOMPONENTID para este tipo de filtro. Se usa para la propiedad id. de componente que proporciona información de identificación. Este miembro es opcional.

Comentarios

Al diseñar el descriptor de filtro, hay una serie de macros que el autor de la llamada puede encontrar útiles. En lugar de especificar count, size y una tabla para descriptores de pin, categorías, descriptores de nodo y conexiones, hay una serie de macros útiles:

Macro	Descripción
DEFINE_KSFILTER_PIN_DESCRIPTORS(Table)	Inserta automáticamente el número de elementos de la tabla, el tamaño de cada elemento de la tabla y la tabla de descriptores de anclaje en el descriptor de filtro.
DEFINE_KSFILTER_CATEGORIES(Table)	Inserta automáticamente el número de categorías de la tabla y la propia tabla en el descriptor de filtro.
DEFINE_KSFILTER_CATEGORIES_NULL	Rellena automáticamente los miembros de categoría de un filtro que no define ninguna categoría.
DEFINE_KSFILTER_NODE_DESCRIPTORS(Table)	Inserta automáticamente el número de elementos de la tabla, el tamaño de cada elemento de la tabla y la tabla de descriptores de nodo en el descriptor de filtro.
DEFINE_KSFILTER_NODE_DESCRIPTORS_NULL	Rellena automáticamente los miembros del descriptor de nodo para un filtro que no define nodos de topología.
DEFINE_KSFILTER_CONNECTIONS(Table)	Inserta automáticamente el número de conexiones en la tabla y la propia tabla en el descriptor de filtro.
DEFINE_KSFILTER_DEFAULT_CONNECTIONS	Rellena automáticamente la tabla de conexiones para un filtro que no define conexiones explícitas.

Si no usa DEFINE_KS_FILTER_PIN_DESCRIPTORS para establecer PinDescriptorSize, debe establecer PinDescriptorSize en sizeof(KSPIN_DESCRIPTOR_EX).

Del mismo modo, si no usa DEFINE_KS_FILTER_NODE_DESCRIPTORS para establecer NodeDescriptorSize, debe establecer NodeDescriptorSize en sizeof(KSNODE_DESCRIPTOR) .