Обработчики свойств audio
Драйвер мини-порта хранит сведения о каждом свойстве, которое он поддерживает, в PCPROPERTY_ITEM структуре. Эта структура содержит следующие сведения о свойстве :
GUID набора свойств и идентификатор свойства (или индекс)
Указатель функции на подпрограмму обработчика для свойства
Флаги, указывающие операции свойств, поддерживаемые обработчиком
Драйвер мини-порта предоставляет таблицу автоматизации (указанную структурой PCAUTOMATION_TABLE ) для фильтра. Драйвер предоставляет дополнительные таблицы автоматизации для типов контактов и узлов фильтра. Каждый тип контактов или узлов имеет собственную таблицу. Каждая таблица автоматизации содержит (возможно, пустой) массив PCPROPERTY_ITEM структур, и каждая из этих структур описывает одно свойство фильтра, закрепления или узла. Когда клиент отправляет запрос на свойство фильтру, закреплению или узлу, драйвер порта направляет запрос через таблицу автоматизации в соответствующий обработчик свойств.
Драйвер мини-порта может указать уникальную подпрограмму обработчика свойств для каждого свойства. Однако если драйвер обрабатывает несколько похожих свойств, их иногда можно объединить в одну подпрограмму обработчика для удобства. Предоставление уникального обработчика для каждого свойства или консолидация нескольких свойств в одном обработчике — это решение о реализации, которое должно быть принято модулем записи драйвера и должно быть прозрачным для клиентов, отправляющих запросы на свойства.
Клиент в пользовательском режиме может отправлять запрос на получение, набор или базовую поддержку, вызывая функцию Microsoft Win32 DeviceIoControl с параметром вызова dwIoControlCode , равным IOCTL_KS_PROPERTY. Операционная система преобразует этот вызов в IRP, который отправляется драйверу класса. Дополнительные сведения см. в разделе Свойства KS.
Когда клиент отправляет запрос свойства KS (т. е. IRP IOCTL_KS_PROPERTY I/O-control IRP) в дескриптор фильтра или маркер, системный драйвер KS (Ks.sys) доставляет запрос драйверу порта для объекта фильтра или объекта pin. Если драйвер мини-порта предоставляет обработчик для свойства , драйвер порта перенаправит запрос обработчику. Перед перенаправлением запроса драйвер порта преобразует сведения из запроса свойства в формат, заданный структурой PCPROPERTY_REQUEST . Драйвер порта передает эту структуру обработчику драйвера мини-порта.
Элемент MajorTarget PCPROPERTY_REQUEST указывает на основной интерфейс драйвера мини-порта для звукового устройства. Например, для устройства WavePci это указатель на интерфейс IMiniportWavePci объекта драйвера мини-порта.
В случае запроса свойства KS, отправленного дескриптору фильтра, член MinorTarget PCPROPERTY_REQUEST имеет значение NULL. В случае запроса, отправленного дескриптору закрепления, MinorTarget указывает на интерфейс потока для закрепления. Например, для устройства WavePci это указатель на интерфейс IMiniportWavePciStream объекта потока.
Элементы Instance и Value PCPROPERTY_REQUEST указывают на входной и выходной буферы запроса свойства KS соответственно. (Буферы задаются параметрами lpInBuffer и lpOutBuffer функции DeviceIoControl .) Эти буферы содержат дескриптор свойства (данные экземпляра) и значение свойства (данные операции), соответственно, как описано в разделе Наборы свойств драйверов аудио. Элемент Value указывает на начало выходного буфера, но указатель экземпляра смещается от начала входного буфера.
Входной буфер начинается со структуры KSPROPERTY или KSNODEPROPERTY . Драйвер порта копирует сведения из этой структуры в элементы Node, PropertyItem и Verb структуры PCPROPERTY_REQUEST. Если какие-либо данные следуют за структурой KSPROPERTY или KSNODEPROPERTY в буфере, драйвер порта загружает член Экземпляра с указателем на эти данные. В противном случае экземпляру присваивается значение NULL.
Если входной буфер начинается со структуры KSPROPERTY, которая не содержит сведений об узле, драйвер порта задает элемент Node структуры PCPROPERTY_REQUEST значение ULONG(-1). В этом случае драйвер порта вызывает соответствующий обработчик из таблицы автоматизации драйвера мини-порта для фильтра или закрепления в зависимости от того, указан ли целевой объект для запроса свойства дескриптором фильтра или маркером закрепления. (Если в таблице не указан обработчик для свойства, драйвер порта обрабатывает запрос.)
Если входной буфер начинается со структуры KSNODEPROPERTY, драйвер порта копирует идентификатор узла из этой структуры в элемент Node структуры PCPROPERTY_REQUEST и вызывает соответствующий обработчик из таблицы автоматизации драйвера мини-порта для узла. (Опять же, если в таблице не указан обработчик для свойства, драйвер порта обрабатывает запрос.)
Драйвер порта проверяет KSPROPERTY_TYPE_TOPOLOGY бит в флагах операций запроса на свойство, чтобы определить, какая из двух структур, KSPROPERTY или KSNODEPROPERTY, находится в начале входного буфера:
Если этот бит задан, запрос выполняется для свойства узла, а входной буфер начинается со структуры KSNODEPROPERTY.
В противном случае входной буфер начинается со структуры KSPROPERTY.
Дополнительные сведения о KSPROPERTY_TYPE_TOPOLOGY см. в разделе KSPROPERTY.
Члены InstanceSize и ValueSize структуры PCPROPERTY_REQUEST указывают размеры буферов, на которые указывают члены Instance и Value . ValueSize равно размеру выходного буфера запроса на свойство, но InstanceSize — это размер данных, следующих за структурой KSPROPERTY или KSNODEPROPERTY во входном буфере. То есть InstanceSize — это размер входного буфера за вычетом размера структуры KSPROPERTY или KSNODEPROPERTY. Если эта структура не соответствует дополнительным данным, драйвер порта задает значение InstanceSize равным нулю (а экземпляр — значение NULL).
Например, если клиент указывает структуру KSNODEPROPERTY_AUDIO_CHANNEL в качестве данных экземпляра во входном буфере, драйвер порта передает обработчику структуру PCPROPERTY_REQUEST, член экземпляра которой указывает на элемент channel структуры KSNODEPROPERTY_AUDIO_CHANNEL, а член InstanceSize содержит значение.
sizeof(KSNODEPROPERTY_AUDIO_CHANNEL) - sizeof(KSNODEPROPERTY)
Перед отправкой запроса get-property для получения значения свойства клиент должен выделить выходной буфер, в который обработчик свойств драйвера мини-порта может записать значение свойства. Для некоторых свойств размер выходного буфера зависит от устройства, и клиент должен запросить у обработчика свойств требуемый размер буфера. В таких случаях клиент отправляет исходный запрос на свойство с указателем на выходной буфер nullptr и длиной выходного буфера нулевой. Обработчик отвечает, возвращая требуемый размер буфера вместе с кодом состояния STATUS_BUFFER_OVERFLOW. Затем клиент получает значение свойства, выделяя выходной буфер указанного размера и отправляя этот буфер во второй запрос get-property.
Если указанный размер буфера слишком мал для получения любой из запрошенных сведений, метод возвращает STATUS_BUFFER_TOO_SMALL.
В некоторых случаях драйверы портов PortCls возвращают STATUS_BUFFER_TOO_SMALL вместо STATUS_BUFFER_OVERFLOW в ответ на запрос свойства с ненулевым адресом и размером выходного буфера. Требуемый размер буфера в таких случаях не возвращается.
Дополнительные сведения см. в статье Использование значений NTSTATUS и в следующих записях блога: