Базовые запросы поддержки для свойств звука
При указании данных для запроса set-property к фильтру, закреплению или узлу клиенту часто требуется знать допустимые диапазоны данных для значения или значений, указанных для свойства . Диапазоны могут различаться в зависимости от устройства и, возможно, даже от узла к узлу на одном устройстве.
Некоторые свойства определяются, чтобы разрешить запросам set-property указывать значения, которые находятся вне диапазона, но драйверы мини-портов автоматически зажимают эти значения в поддерживаемом диапазоне (например, см . KSPROPERTY_AUDIO_VOLUMELEVEL). Последующий запрос get для того же свойства получает фактические параметры драйвера для значения или значений, которые могут быть зажаты версии значений, указанных клиентом в запросе на установку.
Однако клиенту может потребоваться знать диапазон для значения свойства, а не просто полагаться на драйвер минипорта, чтобы автоматически зажать значение вне диапазона. Например, оконное приложение, представляющее ползунок управления громкостем для звукового устройства, может потребоваться знать диапазон громкости устройства, чтобы сопоставить этот диапазон с ползунком полной длины.
Подпрограмма обработчика драйвера для определенного свойства должна предоставлять сведения о диапазоне в ответ на запрос свойства базовой поддержки (KSPROPERTY_TYPE_BASICSUPPORT). При отправке драйвера запроса на свойство базовой поддержки клиент предоставляет буфер значений, в который обработчик свойств записывает сведения о базовой поддержке, которые состоят из KSPROPERTY_DESCRIPTION структуры, за которой могут следовать данные, относящиеся к свойству. Эти данные обычно состоят из спецификаций для одного или нескольких диапазонов параметров в зависимости от свойства .
Как правило, клиент заранее не знает, насколько велик этот буфер значений, и должен отправить один или два предварительных запроса к обработчику свойств для определения размера значения. Формат этих предварительных запросов четко определен. Клиенты ожидают, что драйверы будут следовать этим соглашениям при обработке запроса на базовую поддержку:
Если в запросе указано значение sizeof(ULONG), обработчик свойств должен записать значение элемента AccessFlags структуры KSPROPERTY_DESCRIPTION в буфер значений размера ULONG. Обработчик задает бит флага KSPROPERTY_TYPE_BASICSUPPORT, если он обеспечивает дополнительную поддержку для запросов свойств базовой поддержки.
Если в запросе указано значение sizeof(KSPROPERTY_DESCRIPTION), обработчик должен записать структуру KSPROPERTY_DESCRIPTION в буфер данных. Обработчик задает поле DescriptionSize структуры, равное размеру этой структуры, а также размеру всех дополнительных сведений, относящихся к свойству, которые обработчик может загрузить в буфер данных после структуры. Это размер буфера значений, который клиент должен выделить для хранения основных сведений о поддержке свойства.
Если в запросе указывается размер значения, достаточно большого для хранения как структуры KSPROPERTY_DESCRIPTION, так и сведений о свойствах, обработчик должен записать структуру KSPROPERTY_DESCRIPTION в начало буфера, а сведения, относящиеся к свойству, записываются в часть буфера данных, которая следует за концом структуры KSPROPERTY_DESCRIPTION. При написании структуры KSPROPERTY_DESCRIPTION обработчик должен задать для поля DescriptionSize размер этой структуры, а также размер сведений о свойстве, которые следует за структурой.
Если в запросе указано значение, которое не соответствует одному из этих трех вариантов, обработчик свойств отклоняет запрос и возвращает код состояния STATUS_BUFFER_TOO_SMALL.
Сведения о свойствах, которые обработчик записывает в буфер значений, могут включать диапазоны данных для значений свойств. Член MembersSize KSPROPERTY_MEMBERSHEADER указывает, включены ли диапазоны данных:
Параметр MembersSize равен нулю, если диапазоны не требуются. Это происходит, например, если значения свойств имеют тип BOOL.
Свойство MembersSize не равно нулю, если за KSPROPERTY_MEMBERSHEADER структурой следуют дескрипторы диапазона для одного или нескольких значений свойств.
Для значения свойства типа BOOL дескриптор диапазона не требуется, так как диапазон неявно ограничен значениями TRUE и FALSE. Однако дескрипторы диапазонов необходимы для указания диапазонов значений свойств с целочисленными типами.
Например, запрос базовой поддержки для свойства KSPROPERTY_AUDIO_VOLUMELEVEL на узле тома (KSNODETYPE_VOLUME) получает минимальные и максимальные параметры тома для этого узла. В этом случае клиенту необходимо выделить буфер значений, достаточно большой для размещения следующих структур:
Три структуры упаковываются в смежные расположения в буфере в порядке, указанном в предыдущем списке. При обработке запроса драйвер мини-порта записывает минимальный и максимальный уровни громкости в элемент Bounds структуры KSPROPERTY_STEPPING_LONG.
Пример запроса на базовую поддержку с массивом дескрипторов диапазона см. на рисунке в разделе Предоставление многоканальных узлов. Дополнительные сведения о запросах свойств базовой поддержки см. в разделе Свойства KS. Примеры кода см. в реализациях обработчика свойств в примерах аудиодрайверов в комплекте драйверов Microsoft Windows (WDK).