Patillas KS

El minidriver proporciona una estructura KSPIN_DESCRIPTOR para cada tipo de pin que se va a instanciar. Una estructura de descriptor de pines es conocida como una fábrica de pines. Cada fábrica de pines puede crear una o varias instancias de una clase particular de pin. Una fábrica de pines contiene varias matrices que describen el tipo de pin que este descriptor instancia.

El minidriver especifica una o varias categorías KS a las que pertenecen los pines creados por este descriptor en el miembro Categories de KSPIN_DESCRIPTOR. KS utiliza categorías para conectar instancias de pin al construir un gráfico de filtros. La propiedad KSPROPERTY_TOPOLOGY_CATEGORIES consulta la matriz de categorías funcionales que admite un controlador.

Un minidriver proporciona un archivo INF que registra uno o varios nombres de dispositivo de anclaje. En la instalación, el sistema operativo carga los nombres y las categorías correspondientes en el registro del sistema. A continuación, los clientes pueden hacer llamadas de creación de ficheros con estos nombres de dispositivo para instanciar patillas.

Los clientes en modo de usuario llaman a la función CreateFile win32 con el nombre del dispositivo. Por ejemplo, "\\.\filters\audio\default renderer" podría ser un vínculo al dispositivo de audio configurado para la salida predeterminada. Los clientes en modo kernel llaman a ZwCreateFile desde el modo kernel. Una vez que la rutina create-file devuelve un identificador de archivo, los clientes de KS se comunican con instancias de pin a través de Propiedades de KS.

En las estructuras del descriptor de pines, el minidriver establece matrices de estructuras KSPIN_INTERFACE y KSPIN_MEDIUM que especifican las interfaces y los medios admitidos por esa fábrica de pines. KSPIN_DESCRIPTOR es también donde el minidriver especifica los intervalos válidos de datos para los pines creados por esa factoría. Para ello, proporciona un puntero a una matriz de estructuras KSDATARANGE . El minidriver también especifica la dirección del flujo de datos y comunicación para los nuevos pines creados por esta fábrica de pines.

Un minidriver permite la detección en tiempo de ejecución de fábricas de pines al soportar el conjunto de propiedades KSPROPSETID_Pin.

Para crear una conexión de pin, llame a la rutina KsCreatePin. En esta llamada, el minidriver pasa un puntero a una estructura de tipo KSPIN_CONNECT que describe la conexión solicitada. Cuando se crea un pin, el filtro ve el nuevo pin como un objeto de archivo subordinado al objeto de archivo para ese filtro.

El minidriver llama a KsValidateConnectRequest con las estructuras de descriptores proporcionadas en el IRP_MJ_CREATE resultante. Esta rutina valida estas estructuras y devuelve un puntero a la estructura de conexión y al objeto de archivo raíz.

Los minidrivers usan los miembros DataFlow y Communication de las estructuras KSPIN_DESCRIPTOR para definir los siguientes detalles de patilla:

• Patilla de origen IRP frente a patilla de sumidero IRP

  Un pin de origen de IRP emite IRPs; un pin receptor de IRP los recibe. Un cliente en modo de usuario envía solicitudes de E/S directamente a un receptor IRP a través del identificador de archivo correspondiente. Los clientes usan KSPROPERTY_PIN_COMMUNICATION para comprobar si los datos fluyen hacia o desde un tipo de pin.

• Pin del origen de datos frente al pin receptor de datos

  Un pin de origen de datos es un pin de salida en un filtro; un pin receptor de datos es un pin de entrada. La propiedad de ser un origen de datos o receptor es independiente de ser un origen o receptor de IRP. Por ejemplo, el cliente puede conectar un origen de datos, un pin de receptor de IRP, a un receptor de datos, un pin de origen IRP. Los clientes usan KSPROPERTY_PIN_DATAFLOW para comprobar si los datos fluyen hacia o desde un tipo de pin.

Al finalizar una conexión, el identificador del pin de origen debe cerrarse antes de que se destruya el objeto de archivo subyacente. Si el pin de origen se basa en los recursos proporcionados por el pin de destino, es responsabilidad del pin de destino notificar al origen cuando finaliza la conexión.

Un cliente interactúa con un pin de streaming de kernel llamando a la rutina DeviceIoControl (que se describe en la documentación del SDK de Microsoft Windows) con IRP_MJ_DEVICE_CONTROL. El autor de la llamada identifica su solicitud por el código de control de E/S que coloca en Parameters.DeviceIoControl.IoControlCode en la estructura de ubicación de la pila de E/S.

Para admitir solicitudes, el minidriver proporciona un puntero a una estructura KSDISPATCH_TABLE en una llamada a KsAllocateObjectHeader.

Las solicitudes de escritura contienen un puntero a una matriz de estructuras de KSSTREAM_HEADER que, a su vez, contienen punteros para transmitir datos. Las solicitudes de lectura contienen un puntero a una matriz de estructuras de encabezado vacías donde se deben devolver los datos de lectura.