Consultas de soporte técnico básicas para propiedades de audio
Al especificar los datos de una solicitud set-property en un filtro, anclaje o nodo, el cliente suele tener que conocer los intervalos de datos válidos para el valor o los valores que especifica para la propiedad . Los intervalos pueden variar de un dispositivo a otro, e incluso de nodo a nodo dentro del mismo dispositivo.
Algunas propiedades se definen para permitir que las solicitudes set-property especifiquen valores que están fuera del intervalo, pero los controladores de minipuerto sujetan de forma silenciosa esos valores al intervalo admitido (por ejemplo, vea KSPROPERTY_AUDIO_VOLUMELEVEL). Una solicitud get posterior para la misma propiedad recupera la configuración real del controlador para el valor o los valores, que podrían ser versiones comprimidas de los valores especificados por el cliente en la solicitud set.
Sin embargo, es posible que un cliente necesite conocer el intervalo de un valor de propiedad en lugar de simplemente confiar en el controlador de miniporte para fijar automáticamente un valor fuera del intervalo. Por ejemplo, una aplicación con ventanas que presenta un control deslizante de control de volumen para un dispositivo de audio podría necesitar conocer el intervalo de volúmenes del dispositivo para asignar ese intervalo a la longitud completa del control deslizante.
La rutina de controlador de una propiedad determinada debe ser capaz de proporcionar información de intervalo en respuesta a una solicitud de propiedad de soporte básico (KSPROPERTY_TYPE_BASICSUPPORT). Al enviar una solicitud de propiedad de soporte técnico básico a un controlador, un cliente proporciona un búfer de valor en el que el controlador de propiedades escribe la información de soporte técnico básico, que consta de una estructura de KSPROPERTY_DESCRIPTION que podría ir seguida de datos específicos de la propiedad. Estos datos normalmente constan de especificaciones para uno o varios intervalos de parámetros, en función de la propiedad .
En general, el cliente no sabe con antelación qué tamaño debe ser este búfer de valor y debe enviar una o dos solicitudes preliminares al controlador de propiedades para determinar el tamaño del valor. El formato de estas solicitudes preliminares está bien definido. Los clientes esperan que los controladores sigan estas convenciones al controlar una solicitud de soporte técnico básica:
Si la solicitud especifica el tamaño del valor como sizeof(ULONG), el controlador de propiedades debe escribir el valor del miembro AccessFlags de la estructura de KSPROPERTY_DESCRIPTION en el búfer de valores de tamaño ULONG. El controlador establece el bit de marca KSPROPERTY_TYPE_BASICSUPPORT si proporciona compatibilidad adicional con las solicitudes de propiedades de soporte básico.
Si la solicitud especifica el tamaño del valor como sizeof(KSPROPERTY_DESCRIPTION), el controlador debe escribir una estructura de KSPROPERTY_DESCRIPTION en el búfer de datos. El controlador establece el campo DescriptionSize de la estructura igual al tamaño de esa estructura más el tamaño de toda la información adicional específica de la propiedad que el controlador tiene disponible para cargar en el búfer de datos después de la estructura. Este es el tamaño del búfer de valores que el cliente debe asignar para contener la información de soporte técnico básico de la propiedad.
Si la solicitud especifica un tamaño de valor lo suficientemente grande como para contener la estructura de KSPROPERTY_DESCRIPTION y la información específica de la propiedad, el controlador debe escribir la estructura KSPROPERTY_DESCRIPTION en el inicio del búfer y debe escribir la información específica de la propiedad en la parte del búfer de datos que sigue al final de la estructura de KSPROPERTY_DESCRIPTION. Al escribir la estructura de KSPROPERTY_DESCRIPTION, el controlador debe establecer el campo DescriptionSize en el tamaño de esa estructura más el tamaño de la información específica de la propiedad que sigue a la estructura.
Si la solicitud especifica un tamaño de valor que no coincide con uno de estos tres casos, el controlador de propiedades rechaza la solicitud y devuelve el código de estado STATUS_BUFFER_TOO_SMALL.
La información específica de la propiedad que escribe el controlador en el búfer de valores puede incluir intervalos de datos para los valores de propiedad. El miembro MembersSize de KSPROPERTY_MEMBERSHEADER indica si se incluyen intervalos de datos:
MembersSize es cero si no se necesitan intervalos. Este es el caso, por ejemplo, si los valores de propiedad son de tipo BOOL.
MembersSize es distinto de cero si la estructura de KSPROPERTY_MEMBERSHEADER va seguida de descriptores de intervalo para uno o varios valores de propiedad.
Para un valor de propiedad de tipo BOOL, no se necesita ningún descriptor de intervalo porque el intervalo se limita implícitamente a los valores TRUE y FALSE. Sin embargo, se necesitan descriptores de intervalo para especificar los intervalos de valores de propiedad con tipos enteros.
Por ejemplo, la solicitud de soporte técnico básico para una propiedad de KSPROPERTY_AUDIO_VOLUMELEVEL en un nodo de volumen (KSNODETYPE_VOLUME) recupera la configuración de volumen mínima y máxima para ese nodo. En este caso, el cliente debe asignar un búfer de valores lo suficientemente grande como para contener las siguientes estructuras:
Las tres estructuras se empaquetan en ubicaciones adyacentes en el búfer en el orden que se muestra en la lista anterior. Al controlar la solicitud, el controlador de minipuerto escribe los niveles de volumen mínimo y máximo en el miembro Bounds de la estructura KSPROPERTY_STEPPING_LONG.
Para obtener un ejemplo de una solicitud de soporte técnico básico con una matriz de descriptores de intervalo, consulte la figura de Exposición de nodos multicanal. Para obtener más información sobre las solicitudes de propiedades de soporte básico, vea Propiedades de KS. Para obtener ejemplos de código, consulte las implementaciones del controlador de propiedades en los controladores de audio de ejemplo del Kit de controladores de Microsoft Windows (WDK).