Свойства фильтра, закрепления и узла
Аудиодрайверы модели WDM (Microsoft Windows Driver Model) представляют звуковое устройство в виде фильтра KS и аппаратный буфер на устройстве в виде закрепления на фильтре. Когда клиент отправляет запрос свойства одному из этих объектов фильтра или закрепления, драйвер порта получает запрос и направляет запрос соответствующему обработчику свойств в драйвере порта или драйвере мини-порта.
Звуковые устройства поддерживают три типа свойств:
Свойства фильтра
Свойство фильтра — это свойство фильтра в целом, а не свойство конкретного контакта или узла в фильтре. Запросы свойств фильтра указывают дескрипторы фильтра, но не указывают идентификаторы узлов.
Свойства закрепления
Свойство pin — это свойство конкретного экземпляра закрепления в фильтре. Запросы этих свойств указывают маркеры закрепления, но не указывают идентификаторы узлов.
Свойства узла
Свойство node — это свойство узла топологии в фильтре. Запрос свойства узла указывает дескриптор фильтра или маркер закрепления, а также идентификатор узла.
Указывает ли запрос на свойство узла дескриптор фильтра или закрепления, зависит от того, является ли узел уникальным для фильтра. Дополнительные сведения см. в следующем разделе Свойства узла.
На следующем рисунке показаны три типа запроса свойств: запрос на закрепление свойства, отправляемый экземпляру пин-кода, запрос свойства узла, отправляемый на узел (в экземпляре фильтра или закрепления), и запрос свойства фильтра, отправляемый экземпляру фильтра.
Как правило, драйвер порта обрабатывает большинство запросов на свойства фильтра и закрепления, а драйвер miniport обрабатывает запросы свойств узла.
Драйвер порта предоставляет собственные встроенные обработчики для свойств фильтра и закрепления, которые используются системным драйвером SysAudio (см. KSPROPSETID_Sysaudio и KSPROPSETID_Sysaudio_Pin) и системным драйвером WDMAud. Драйверу мини-порта не нужно реализовывать обработчики свойств, обрабатываемых драйвером порта. Типичный драйвер мини-порта предоставляет несколько обработчиков для свойств фильтра и закрепления, если таковые есть. Драйвер мини-порта предоставляет обработчики свойств узла, которые представляют аппаратные функции звукового устройства. Драйверы портов не предоставляют встроенной обработки свойств узла, за исключением KSPROPERTY_TOPOLOGY_NAME.
Когда драйвер порта и драйвер мини-порта предоставляют обработчики для одного свойства, драйвер порта использует собственный обработчик и игнорирует обработчик драйвера мини-порта.
Дескрипторы фильтра
Драйвер порта получает указатели на обработчики свойств драйвера мини-порта, вызывая метод IMiniport::GetDescription . С помощью этого метода драйвер порта извлекает указатель на дескриптор фильтра драйвера мини-порта, который представляет собой структуру типа PCFILTER_DESCRIPTOR. Эта структура задает обработчики свойств драйвера мини-порта для свойств фильтра, закрепления и узла:
Элемент AutomationTable структуры PCFILTER_DESCRIPTOR указывает на таблицу автоматизации для фильтра. В этой таблице указаны обработчики свойств драйвера мини-порта для свойств фильтра.
Элемент Pins структуры PCFILTER_DESCRIPTOR содержит таблицы автоматизации для контактов. В каждой таблице указываются обработчики свойств для свойств закрепления определенного типа закрепления.
Элемент Nodes структуры PCFILTER_DESCRIPTOR содержит таблицы автоматизации для узлов топологии внутри фильтра. В каждой таблице указываются обработчики свойств для свойств узла определенного типа.
Свойства фильтра
Драйвер порта обращается к обработчикам свойств фильтра драйвера минипорта через элемент AutomationTable PCFILTER_DESCRIPTOR. Как правило, эта таблица автоматизации содержит несколько обработчиков, так как драйвер порта предоставляет собственные встроенные обработчики для всех свойств фильтров, которые SysAudio и WDMAud используют для запроса и настройки звуковых устройств.
Однако драйвер мини-порта может предоставлять обработчики для свойств фильтра, таких как KSPROPERTY_GENERAL_COMPONENTID , которые предоставляют зависимые от оборудования сведения, недоступные драйверу порта. Два примера аудиодрайверов в комплекте драйверов Microsoft Windows (WDK) обрабатывают свойство KSPROPERTY_GENERAL_COMPONENTID. Дополнительные сведения см. в описании реализаций драйверов miniport в примере драйвера Sysvad, который рассматривается в разделе Примеры аудиодрайверов.
Все драйверы портов в Portcls.sys обеспечивают обработку наборов свойств KSPROPSETID_Pin и KSPROPSETID_Topology . Все свойства в этих наборах являются свойствами фильтра, за исключением KSPROPERTY_TOPOLOGY_NAME, которое является свойством узла (которое использует дескриптор фильтра, а не маркер закрепления, чтобы указать целевой объект для запроса). Драйверы портов поддерживают следующее подмножество свойств KSPROPSETID_Pin:
KSPROPERTY_PIN_CONSTRAINEDDATARANGES
KSPROPERTY_PIN_DATAINTERSECTION
KSPROPERTY_PIN_GLOBALCINSTANCES
KSPROPERTY_PIN_NECESSARYINSTANCES
KSPROPERTY_PIN_PHYSICALCONNECTION
KSPROPERTY_PIN_PROPOSEDATAFORMAT
KSPROPERTY_PIN_PROPOSEDATAFORMAT2
Эти свойства предоставляют сведения о фабриках контактов, принадлежащих фильтру. Как правило, клиенты запрашивают фильтр для этих свойств перед созданием экземпляров закреплений. Драйверы портов поддерживают все четыре свойства KSPROPSETID_Topology, которые предоставляют сведения о внутренней топологии фильтра.
Кроме того, драйвер порта DMus предоставляет обработчик для свойства KSPROPERTY_SYNTH_MASTERCLOCK , которое является свойством только для получения фильтра DirectMusic. KSPROPERTY_SYNTH_MASTERCLOCK является членом набора свойств KSPROPSETID_SynthClock .
Свойства закрепления
Драйвер порта обращается к обработчикам свойств pin-property драйвера минипорта через элемент Pins PCFILTER_DESCRIPTOR. Этот элемент указывает на массив дескрипторов контактов, а каждый дескриптор указывает на таблицу автоматизации для типа закрепления (определяется идентификатором контакта, который является просто индексом массива).
Как правило, эти таблицы автоматизации содержат мало записей, так как драйвер порта предоставляет собственные обработчики для всех свойств контактов, используемых SysAudio и WDMAud. Драйвер мини-порта может предоставлять обработчики для одного или нескольких свойств закрепления, которые драйвер порта не обрабатывает, но только клиенты, которые знают об этих свойствах, могут отправлять запросы свойств для них.
За исключением драйвера порта топологии, все драйверы портов в Portcls.sys предоставляют встроенные обработчики для следующих свойств закрепления:
KSPROPERTY_CONNECTION_DATAFORMAT
KSPROPERTY_CONNECTION_ALLOCATORFRAMING
KSPROPERTY_DRMAUDIOSTREAM_CONTENTID
Для некоторых свойств в этом списке требуется информация, зависящая от оборудования, из драйвера мини-порта. Когда драйвер порта получает IRP, содержащий запрос на одно из этих свойств, он не передает IRP драйверу мини-порта. Вместо этого драйвер порта обрабатывает запрос сам, но его обработчик получает необходимые сведения, вызывая точку входа в драйвере мини-порта. Например, драйвер порта предоставляет собственный обработчик свойств для запросов KSPROPERTY_AUDIO_POSITION. Этот обработчик просто вызывает метод GetPosition потока драйвера miniport (например, IMiniportWavePciStream::GetPosition), чтобы получить текущую позицию.
Свойства узла
Драйвер порта обращается к обработчикам свойств node-property драйвера мини-порта через элемент Nodes PCFILTER_DESCRIPTOR. Этот член указывает на массив дескрипторов узлов, а каждый дескриптор указывает на таблицу автоматизации для типа узла (определяется идентификатором узла, который является просто индексом массива). Как правило, все или большинство обработчиков свойств, принадлежащих драйверу мини-порта, находятся в массиве Nodes . Аудиодрайвер представляет аппаратные элементы управления в звуковом устройстве в качестве узлов топологии и использует механизм свойств для предоставления клиентам доступа к параметрам управления, зависящим от оборудования.
Как описано ранее, клиент отправляет запрос свойства фильтра дескриптору фильтра, а запрос на закрепление свойства — в дескриптор закрепления. В отличие от экземпляра фильтра или закрепления узел не является объектом ядра и не имеет дескриптора. Клиент отправляет запрос свойства узла дескриптору закрепления или дескриптору фильтра, но запрос также указывает идентификатор узла, чтобы указать, что запрос относится к свойству узла, а не к свойству pin или filter.
Ниже приведены общие правила для определения того, должно ли свойство узла использовать дескриптор фильтра или маркер закрепления.
Если фильтр содержит несколько экземпляров определенного типа закрепления, а каждый контакт этого типа содержит узел с определенным идентификатором узла, то каждый экземпляр закрепления содержит экземпляр узла. В этом случае в запросе свойства узла должен быть указан маркер закрепления (а не просто дескриптор фильтра), чтобы различать несколько экземпляров одного типа узла. Сочетание маркера закрепления и идентификатора узла однозначно определяет конкретный экземпляр узла в качестве целевого объекта для запроса.
Если фильтр содержит только один экземпляр определенного узла, запрос свойства узла указывает дескриптор фильтра. Сочетания дескриптора фильтра и идентификатора узла достаточно, чтобы однозначно определить узел, который является целевым объектом для запроса.
Однако перед реализацией обработчика для определенного свойства узла модуль записи драйверов должен ссылаться на наборы свойств аудиодрайверов, чтобы проверка, следует ли указать целевой объект для свойства в качестве дескриптора фильтра или маркера.
Драйверы портов в Portcls.sys в настоящее время не обеспечивают встроенную обработку свойств узла, за исключением KSPROPERTY_TOPOLOGY_NAME.
Запросы на чрезмерное и неуказаемое свойство
Драйверы должны быть готовы к обработке запросов свойств от клиентов, которые не соответствуют приведенным выше правилам. Запросы могут быть либо переопределенными, либо недоуказанными:
Переопределенные запросы
Если для запроса свойства требуется только дескриптор фильтра, но клиент отправляет запрос маркеру, целевой объект для запроса переопределен. Однако драйверы обычно обрабатывают запрос как допустимый; то есть они обрабатывают запрос так, как если бы он был отправлен фильтру, содержащему закрепление.
Неуказаные запросы
Если для запроса свойства требуется дескриптор закрепления, но клиент отправляет запрос дескриптору фильтра, целевой объект для запроса не указан. Например, если фильтр содержит несколько экземпляров закреплений с одинаковым типом узла, а клиент отправляет запрос на свойство этого типа узла дескриптору фильтра, а не маркеру закрепления, драйвер не может определить, какой экземпляр узла должен получить запрос. В этом случае поведение зависит от драйвера. Вместо того, чтобы автоматически завершаться сбоем всех недоуказаемых запросов, некоторые драйверы считают недоуказанным запрос set-property допустимым. В этом случае интерпретация заключается в том, что запрос задает значение по умолчанию для указанного идентификатора узла. Когда фабрика контактов создает новый экземпляр узла, свойство, принадлежащее новому узлу, инициализируется значением по умолчанию. Запрос, изменяющий значение по умолчанию, не влияет на экземпляры узла, созданные до запроса. Кроме того, драйверы равномерно завершаются сбоем недоопределенных запросов get-property, так как обработчик не может определить, к какому экземпляру узла следует обращаться к свойству.
Исключения из правил
По историческим причинам некоторые свойства звука имеют поведенческие причуды, которые нарушают эти общие правила. Ниже приведены примеры.
Как описано в разделе Применение параметров Speaker-Configuration, клиент может изменить конфигурацию динамиков звукового устройства, задав свойство KSPROPERTY_AUDIO_CHANNEL_CONFIG трехмерного узла (KSNODETYPE_3D_EFFECTS). Параметр конфигурации говорящего является глобальным, так как он изменяет конфигурацию динамиков для всех потоков, входящих в состав набора, который устройство воспроизводит через динамики. Согласно общему правилу, запрос свойства узла, который влияет на фильтр в целом, должен указывать дескриптор фильтра (а также идентификатор узла). Однако для этого конкретного свойства требуется маркер pin вместо дескриптора фильтра. Дескриптор закрепления обозначает экземпляр контакта, содержащий трехмерный узел, который является целевым объектом для запроса.
KSPROPERTY_SYNTH_VOLUME и KSPROPERTY_SYNTH_MASTERCLOCK являются свойствами узла синтезатора (KSNODETYPE_SYNTHESIZER). Хотя оба свойства являются свойствами узла, запросы на эти свойства не включают идентификаторы узлов. (Обратите внимание, что дескриптор свойства для запроса является структурой типа KSPROPERTY, а не KSNODEPROPERTY.) Это поведение нарушает общее правило, которое требует идентификатора узла для свойства узла. Несмотря на это несоответствие, драйвер miniport, поддерживающий любое свойство, должен предоставлять обработчик свойств через элемент Nodes PCFILTER_DESCRIPTOR (а не элемент Pins ).