Controladores de propiedades de audio
Un controlador de minipuerto almacena información sobre cada propiedad que admite en una estructura PCPROPERTY_ITEM . Esta estructura contiene la siguiente información sobre la propiedad :
Guid del conjunto de propiedades e identificador de propiedad (o índice)
Puntero de función a la rutina del controlador para la propiedad
Marcas que especifican las operaciones de propiedad que admite el controlador
El controlador de minipuerto proporciona una tabla de automatización (especificada por una estructura PCAUTOMATION_TABLE ) para el filtro. El controlador proporciona tablas de automatización adicionales para los tipos de anclaje y los tipos de nodo del filtro: cada tipo de patilla o nodo tiene su propia tabla. Cada tabla de automatización contiene una matriz (posiblemente vacía) de estructuras de PCPROPERTY_ITEM, y cada una de estas estructuras describe una propiedad del filtro, el anclaje o el nodo. Cuando un cliente envía una solicitud de propiedad a un filtro, un pin o un nodo, el controlador de puerto enruta la solicitud a través de la tabla de automatización al controlador de propiedades adecuado.
Un controlador de minipuerto puede especificar una rutina de controlador de propiedades única para cada propiedad. Sin embargo, si un controlador controla varias propiedades similares, a veces se pueden consolidar en una sola rutina de controlador para mayor comodidad. Si se debe proporcionar un controlador único para cada propiedad o consolidar varias propiedades en un solo controlador es una decisión de implementación que el escritor de controladores debe tomar y debe ser transparente para los clientes que envían solicitudes de propiedad.
Un cliente en modo de usuario puede enviar una solicitud de propiedad get, set o basic-support llamando a la función DeviceIoControl de Microsoft Win32 con el parámetro de llamada dwIoControlCode establecido en IOCTL_KS_PROPERTY. El sistema operativo convierte esta llamada a un IRP, que envía al controlador de clase. Para obtener más información, vea Propiedades de KS.
Cuando un cliente envía una solicitud de propiedad KS (es decir, un IRP de control de E/S de IOCTL_KS_PROPERTY) a un identificador de filtro o controlador de patillas, el controlador del sistema KS (Ks.sys) entrega la solicitud al controlador de puerto para el objeto de filtro o el objeto pin. Si el controlador de minipuerto proporciona un controlador para la propiedad , el controlador de puerto reenvía la solicitud al controlador. Antes de reenviar la solicitud, el controlador de puerto convierte la información de la solicitud de propiedad en el formato especificado por la estructura PCPROPERTY_REQUEST . El controlador de puerto pasa esta estructura al controlador del controlador de miniporte.
El miembro MajorTarget de PCPROPERTY_REQUEST apunta a la interfaz del controlador de miniport principal para el dispositivo de audio. Por ejemplo, para un dispositivo WavePci, se trata de un puntero a la interfaz IMiniportWavePci del objeto del controlador de miniport.
En el caso de una solicitud de propiedad KS enviada a un identificador de filtro, el miembro MinorTarget de PCPROPERTY_REQUEST es NULL. En el caso de una solicitud enviada a un identificador de patilla, MinorTarget apunta a la interfaz de secuencia del pin. Por ejemplo, para un dispositivo WavePci, se trata de un puntero a la interfaz IMiniportWavePciStream del objeto de secuencia.
Los miembros Instance y Value de PCPROPERTY_REQUEST apuntan a los búferes de entrada y salida, respectivamente, de la solicitud de propiedad KS. (Los búferes se especifican mediante los parámetros lpInBuffer y lpOutBuffer de la función DeviceIoControl ). Estos búferes contienen el descriptor de propiedad (datos de instancia) y el valor de propiedad (datos de operación), respectivamente, como se describe en Conjuntos de propiedades de controladores de audio. El miembro Value apunta al inicio del búfer de salida, pero el puntero instancia se desplaza desde el inicio del búfer de entrada.
El búfer de entrada comienza con una estructura KSPROPERTY o KSNODEPROPERTY . El controlador de puerto copia la información de esta estructura en los miembros Node, PropertyItem y Verb de la estructura PCPROPERTY_REQUEST. Si algún dato sigue la estructura KSPROPERTY o KSNODEPROPERTY en el búfer, el controlador de puerto carga el miembro instance con un puntero a estos datos. De lo contrario, establece Instance en NULL.
Si el búfer de entrada comienza con una estructura KSPROPERTY, que no contiene información de nodo, el controlador de puerto establece el miembro Node de la estructura PCPROPERTY_REQUEST en ULONG(-1). En este caso, el controlador de puerto llama al controlador adecuado desde la tabla de automatización del controlador de miniporte para el filtro o el pin, dependiendo de si un controlador de filtro o un controlador de patillas especifica el destino de la solicitud de propiedad. (Si la tabla no especifica un controlador para la propiedad , el controlador de puerto controla la solicitud en su lugar).
Si el búfer de entrada comienza con una estructura KSNODEPROPERTY, el controlador de puerto copia el identificador de nodo de esta estructura en el miembro Node de la estructura PCPROPERTY_REQUEST y llama al controlador adecuado desde la tabla de automatización del controlador de miniporte para el nodo. (De nuevo, si la tabla no especifica un controlador para la propiedad , el controlador de puerto controla la solicitud en su lugar).
El controlador de puerto comprueba el bit KSPROPERTY_TYPE_TOPOLOGY en las marcas de operación de la solicitud de propiedad para determinar cuál de las dos estructuras, KSPROPERTY o KSNODEPROPERTY, reside al principio del búfer de entrada:
Si se establece este bit, la solicitud es para una propiedad de nodo y el búfer de entrada comienza con una estructura KSNODEPROPERTY.
De lo contrario, el búfer de entrada comienza con una estructura KSPROPERTY.
Para obtener más información sobre KSPROPERTY_TYPE_TOPOLOGY, consulte KSPROPERTY.
Los miembros InstanceSize y ValueSize de la estructura PCPROPERTY_REQUEST especifican los tamaños de los búferes a los que apuntan los miembros Instance y Value . ValueSize es igual al tamaño del búfer de salida de la solicitud de propiedad, pero InstanceSize es el tamaño de los datos que siguen a la estructura KSPROPERTY o KSNODEPROPERTY en el búfer de entrada. Es decir, InstanceSize es el tamaño del búfer de entrada menos el tamaño de la estructura KSPROPERTY o KSNODEPROPERTY. Si ningún dato adicional sigue esta estructura, el controlador de puerto establece InstanceSize en cero (e Instancia en NULL).
Por ejemplo, si el cliente especifica una estructura de KSNODEPROPERTY_AUDIO_CHANNEL como los datos de instancia en el búfer de entrada, el controlador de puerto pasa al controlador una estructura de PCPROPERTY_REQUEST cuyo miembro Instance apunta al miembro Channel de la estructura KSNODEPROPERTY_AUDIO_CHANNEL y cuyo miembro InstanceSize contiene el valor.
sizeof(KSNODEPROPERTY_AUDIO_CHANNEL): sizeof(KSNODEPROPERTY)
Antes de enviar una solicitud get-property para recuperar un valor de propiedad, el cliente debe asignar un búfer de salida en el que el controlador de propiedades del controlador de miniporte puede escribir el valor de propiedad. Para algunas propiedades, el tamaño del búfer de salida depende del dispositivo y el cliente debe consultar el controlador de propiedades para el tamaño de búfer necesario. En estos casos, el cliente envía una solicitud de propiedad inicial con un puntero de búfer de salida de nullptr y una longitud de búfer de salida de cero. El controlador responde devolviendo el tamaño de búfer necesario junto con el código de estado STATUS_BUFFER_OVERFLOW. A continuación, el cliente recupera el valor de la propiedad asignando un búfer de salida del tamaño especificado y enviando este búfer en una segunda solicitud get-property.
Si el tamaño del búfer especificado es demasiado pequeño para recibir alguna de las informaciones solicitadas, el método devuelve STATUS_BUFFER_TOO_SMALL.
En algunos casos, los controladores de puerto portCls devuelven STATUS_BUFFER_TOO_SMALL en lugar de STATUS_BUFFER_OVERFLOW en respuesta a una solicitud de propiedad con una dirección y tamaño de búfer de salida distinto de cero. El tamaño de búfer requerido no se devuelve en estos casos.
Para obtener más información, consulte Uso de valores NTSTATUS y estas entradas de blog: