Propiedades de filtro, anclar y nodo
Los controladores de audio de Microsoft Windows Driver Model (WDM) representan un dispositivo de audio como filtro KS y representan un búfer de hardware en el dispositivo como un pin en el filtro. Cuando un cliente envía una solicitud de propiedad a uno de estos objetos de filtro o anclaje, el controlador de puerto recibe la solicitud y enruta la solicitud al controlador de propiedades adecuado en el controlador de puerto o controlador de minipuerto.
Los dispositivos de audio admiten tres tipos de propiedades:
Propiedades de Filter
Una propiedad filter es una propiedad del filtro en su conjunto en lugar de una propiedad de un pin o nodo determinado dentro del filtro. Las solicitudes de propiedades de filtro especifican identificadores de filtro, pero no especifican identificadores de nodo.
Anclar propiedades
Una propiedad pin es una propiedad de una instancia de pin determinada en el filtro. Las solicitudes de estas propiedades especifican identificadores de patilla, pero no especifican identificadores de nodo.
Propiedades del nodo
Una propiedad node es una propiedad de un nodo de topología dentro del filtro. Una solicitud de una propiedad de nodo especifica un identificador de filtro o un identificador de patilla, además de un identificador de nodo.
Si una solicitud de propiedad de nodo especifica un filtro o un identificador de patilla depende de si el nodo es único para el filtro. Para obtener más información, consulte la sección Propiedades del nodo siguiente.
En la ilustración siguiente se muestran estos tres tipos de solicitud de propiedad: una solicitud de propiedad pin enviada a una instancia de pin, una solicitud de propiedad de nodo enviada a un nodo (en una instancia de filtro o pin) y una solicitud de propiedad de filtro enviada a una instancia de filtro.
Normalmente, el controlador de puerto controla la mayoría de las solicitudes de propiedades de filtro y patilla, y el controlador de miniporta controla las solicitudes de las propiedades del nodo.
El controlador de puerto proporciona sus propios controladores integrados para las propiedades de filtro y patilla que usa el controlador del sistema SysAudio (consulte KSPROPSETID_Sysaudio y KSPROPSETID_Sysaudio_Pin) y el controlador del sistema WDMAud. Un controlador de minipuerto no necesita implementar controladores para las propiedades que controla el controlador de puerto. Un controlador de minipuerto típico proporciona pocos controladores, si los hay, para las propiedades de filtro y patilla. El controlador de minipuerto proporciona los controladores para las propiedades de nodo que representan características dependientes del hardware del dispositivo de audio. Los controladores de puerto no proporcionan ningún control integrado de las propiedades del nodo, a excepción de KSPROPERTY_TOPOLOGY_NAME.
Cuando tanto el controlador de puerto como los controladores de alimentación del controlador de minipuerto para la misma propiedad, el controlador de puerto usa su propio controlador y omite el controlador del controlador de minipuerto.
Descriptores de filtro
El controlador de puerto obtiene punteros a los controladores de propiedad del controlador de minipuerto mediante una llamada al método IMiniport::GetDescription . A través de este método, el controlador de puerto recupera un puntero al descriptor de filtro del controlador de miniporte, que es una estructura de tipo PCFILTER_DESCRIPTOR. Esta estructura especifica los controladores de propiedades del controlador de minipuerto para las propiedades de filtro, patilla y nodo:
El miembro AutomationTable de la estructura PCFILTER_DESCRIPTOR apunta a la tabla de automatización del filtro. Esta tabla especifica los controladores de propiedades del controlador de minipuerto para las propiedades de filtro.
El miembro Pins de la estructura PCFILTER_DESCRIPTOR contiene las tablas de automatización de los pines. Cada tabla especifica los controladores de propiedades para las propiedades de patilla de un tipo de patilla determinado.
El miembro Nodos de la estructura PCFILTER_DESCRIPTOR contiene las tablas de automatización de los nodos de topología dentro del filtro. Cada tabla especifica los controladores de propiedades para las propiedades de nodo de un tipo de nodo determinado.
Propiedades de filtro
El controlador de puerto accede a los controladores de propiedades de filtro del controlador de miniporte a través del miembro AutomationTable de PCFILTER_DESCRIPTOR. Normalmente, esta tabla de automatización contiene pocos controladores porque el controlador de puerto proporciona sus propios controladores integrados para todas las propiedades de filtro que SysAudio y WDMAud usan para consultar y configurar dispositivos de audio.
Sin embargo, el controlador de minipuerto puede proporcionar controladores para propiedades de filtro, como KSPROPERTY_GENERAL_COMPONENTID que proporcionan información dependiente del hardware que no está disponible para el controlador de puerto. Dos de los controladores de audio de ejemplo del Kit de controladores de Microsoft Windows (WDK) controlan la propiedad KSPROPERTY_GENERAL_COMPONENTID. Para obtener más información, consulte las implementaciones del controlador de minipuerto en el controlador de ejemplo sysvad, que se describe en Controladores de audio de ejemplo.
Todos los controladores de puerto de Portcls.sys proporcionan control para los conjuntos de propiedades KSPROPSETID_Pin y KSPROPSETID_Topology . Todas las propiedades de estos conjuntos son propiedades de filtro, a excepción de KSPROPERTY_TOPOLOGY_NAME, que es una propiedad de nodo (que usa un identificador de filtro, no un identificador de patillas, para especificar el destino de la solicitud). Los controladores de puerto admiten el siguiente subconjunto de las propiedades de KSPROPSETID_Pin:
KSPROPERTY_PIN_CONSTRAINEDDATARANGES
KSPROPERTY_PIN_DATAINTERSECTION
KSPROPERTY_PIN_GLOBALCINSTANCES
KSPROPERTY_PIN_NECESSARYINSTANCES
KSPROPERTY_PIN_PHYSICALCONNECTION
KSPROPERTY_PIN_PROPOSEDATAFORMAT
KSPROPERTY_PIN_PROPOSEDATAFORMAT2
Estas propiedades proporcionan información sobre los generadores de patillas que pertenecen a un filtro. Normalmente, los clientes consultan el filtro de estas propiedades antes de crear instancias de anclaje. Los controladores de puerto admiten las cuatro propiedades de KSPROPSETID_Topology, que proporcionan información sobre la topología interna del filtro.
Además, el controlador de puerto DMus proporciona un controlador para la propiedad KSPROPERTY_SYNTH_MASTERCLOCK , que es una propiedad get-only de un filtro DirectMusic. KSPROPERTY_SYNTH_MASTERCLOCK es miembro del conjunto de propiedades KSPROPSETID_SynthClock .
Propiedades de anclaje
El controlador de puerto accede a los controladores de propiedad pin del controlador de miniporte a través del miembro Pins de PCFILTER_DESCRIPTOR. Este miembro apunta a una matriz de descriptores de anclaje y cada descriptor apunta a la tabla de automatización de un tipo de patilla (identificado por un identificador de patilla, que es simplemente el índice de matriz).
Normalmente, estas tablas de automatización contienen pocas entradas porque el controlador de puerto proporciona sus propios controladores para todas las propiedades de patilla que usa SysAudio y WDMAud. Un controlador de minipuerto tiene la opción de proporcionar controladores para una o varias propiedades de patilla que el controlador de puerto no controla, pero solo los clientes que conocen estas propiedades pueden enviar solicitudes de propiedad para ellos.
A excepción del controlador de puerto de topología, todos los controladores de puerto de Portcls.sys proporcionan controladores integrados para las siguientes propiedades de patilla:
KSPROPERTY_CONNECTION_DATAFORMAT
KSPROPERTY_CONNECTION_ALLOCATORFRAMING
KSPROPERTY_DRMAUDIOSTREAM_CONTENTID
Algunas de las propiedades de esta lista requieren información dependiente del hardware del controlador de miniport. Cuando el controlador de puerto recibe un IRP que contiene una solicitud para una de estas propiedades, no pasa el IRP al controlador de minipuerto. En su lugar, el controlador de puerto controla la propia solicitud, pero su controlador obtiene la información que necesita llamando a un punto de entrada en el controlador de minipuerto. Por ejemplo, el controlador de puerto proporciona su propio controlador de propiedades para KSPROPERTY_AUDIO_POSITION solicitudes. Este controlador simplemente llama al método GetPosition del flujo de controlador de miniport (por ejemplo, IMiniportWavePciStream::GetPosition) para obtener la posición actual.
Propiedades del nodo
El controlador de puerto accede a los controladores de propiedad de nodo del controlador de miniporte a través del miembro Nodes de PCFILTER_DESCRIPTOR. Este miembro apunta a una matriz de descriptores de nodo y cada descriptor apunta a la tabla de automatización de un tipo de nodo (identificado por un identificador de nodo, que es simplemente el índice de matriz). Normalmente, todos o la mayoría de los controladores de propiedades que pertenecen a un controlador de minipuerto residen en la matriz Nodos . Un controlador de audio representa los controles de hardware de un dispositivo de audio como nodos de topología y usa el mecanismo de propiedades para proporcionar a los clientes acceso a la configuración de control dependiente del hardware.
Como se ha descrito anteriormente, un cliente envía una solicitud de propiedad de filtro a un identificador de filtro y una solicitud de propiedad pin a un identificador de patilla. A diferencia de una instancia de filtro o anclaje, un nodo no es un objeto kernel y no tiene un identificador. Un cliente envía una solicitud de propiedad de nodo a un identificador de anclaje o a un identificador de filtro, pero la solicitud también especifica un identificador de nodo para indicar que la solicitud es para una propiedad de nodo en lugar de una propiedad de pin o filtro.
A continuación se muestran reglas generales para determinar si una propiedad de nodo debe usar un identificador de filtro o un identificador de patillas:
Si un filtro contiene varias instancias de un tipo de pin determinado y cada pin de ese tipo contiene un nodo con un identificador de nodo determinado, cada instancia de patilla contiene una instancia del nodo. En este caso, una solicitud de propiedad de nodo debe especificar un identificador de patilla (en lugar de un identificador de filtro) para distinguir entre varias instancias del mismo tipo de nodo. La combinación de identificador de anclaje y identificador de nodo identifica inequívocamente una instancia de nodo determinada como destino de la solicitud.
Si un filtro contiene solo una instancia de un nodo determinado, una solicitud de propiedad de nodo especifica un identificador de filtro. La combinación de identificadores de filtro y de nodo es suficiente para identificar inequívocamente el nodo que es el destino de la solicitud.
Sin embargo, antes de implementar un controlador para una propiedad de nodo determinada, el escritor de controladores debe hacer referencia a conjuntos de propiedades de controladores de audio para comprobar si el destino de la propiedad debe especificarse como identificador de filtro o controlador de patillas.
Actualmente, los controladores de puerto de Portcls.sys no proporcionan control integrado de las propiedades del nodo, a excepción de KSPROPERTY_TOPOLOGY_NAME.
Solicitudes de propiedades superespecificadas y infraespecificadas
Los controladores deben estar preparados para tratar las solicitudes de propiedad de los clientes que no siguen las reglas anteriores. Las solicitudes pueden ser sobreespecificadas o infraespecificadas:
Solicitudes sobreespecificadas
Si una solicitud de propiedad solo requiere un identificador de filtro, pero el cliente envía la solicitud a un identificador de patilla en su lugar, el destino de la solicitud se sobreespecificó. Sin embargo, los controladores normalmente tratan la solicitud como válida; es decir, tratan la solicitud como si se hubiera enviado al filtro que contiene el pin.
Solicitudes infraespecificadas
Si una solicitud de propiedad requiere un identificador de anclaje, pero un cliente envía la solicitud a un identificador de filtro en su lugar, se especifica el destino de la solicitud. Por ejemplo, si un filtro contiene varias instancias de patillas con el mismo tipo de nodo, y un cliente envía una solicitud para una propiedad de ese tipo de nodo a un identificador de filtro en lugar de un identificador de anclaje, el controlador no tiene forma de determinar qué instancia de nodo debe recibir la solicitud. En este caso, el comportamiento depende del controlador. En lugar de que se produzcan errores automáticamente en todas las solicitudes infraespecificadas, algunos controladores tratan una solicitud set-property infraespecificada como válida. En este caso, la interpretación es que la solicitud establece el valor predeterminado para el identificador de nodo especificado. Cuando un generador de patillas crea una nueva instancia de nodo, la propiedad que pertenece al nuevo nodo se inicializa en el valor predeterminado. Una solicitud que cambia el valor predeterminado no tiene ningún efecto en las instancias de nodo creadas antes de la solicitud. Además, los controladores no especifican uniformemente las solicitudes get-property especificadas porque el controlador no tiene ninguna manera de determinar qué instancia de nodo se va a consultar para la propiedad.
Excepciones a las reglas
Por motivos históricos, algunas propiedades de audio tienen peculiaridades de comportamiento que infringen estas reglas generales. A continuación, se muestran algunos ejemplos:
Como se describe en Aplicar Speaker-Configuration Configuración, un cliente puede cambiar la configuración del altavoz de un dispositivo de audio estableciendo la propiedad KSPROPERTY_AUDIO_CHANNEL_CONFIG de un nodo 3D (KSNODETYPE_3D_EFFECTS). La configuración del altavoz es global porque cambia la configuración del altavoz para todos los flujos que forman parte de la combinación que reproduce el dispositivo a través de los altavoces. Según la regla general, una solicitud de propiedad de nodo que afecta al filtro en su conjunto debe especificar un identificador de filtro (más un identificador de nodo). Sin embargo, esta propiedad en particular requiere un identificador de patilla en lugar de un identificador de filtro. El identificador de patilla designa la instancia de patilla que contiene el nodo 3D que es el destino de la solicitud.
KSPROPERTY_SYNTH_VOLUME y KSPROPERTY_SYNTH_MASTERCLOCK son propiedades de un nodo de synth (KSNODETYPE_SYNTHESIZER). Aunque ambos son propiedades de nodo, las solicitudes de estas propiedades no incluyen identificadores de nodo. (Tenga en cuenta que el descriptor de propiedad de la solicitud es una estructura de tipo KSPROPERTY, no KSNODEPROPERTY). Este comportamiento infringe la regla general que una propiedad de nodo requiere un identificador de nodo. A pesar de esta discrepancia, un controlador de minipuerto que admita cualquiera de las propiedades debe proporcionar el controlador de propiedades a través del miembro Nodes de PCFILTER_DESCRIPTOR (en lugar del miembro Pins ).
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de