Функция DrmForwardContentToDeviceObject (drmk.h)

Статья
08/07/2023

Функция DrmForwardContentToDeviceObject принимает объект устройства, представляющий устройство, на которое вызывающий объект намерен пересылать защищенное содержимое. Функция проверяет подлинность устройства и отправляет ему идентификатор содержимого и права DRM, назначенные системой защищенному содержимому.

Синтаксис

NTSTATUS DrmForwardContentToDeviceObject(
  [in]           ULONG        ContentId,
  [in, optional] PVOID        Reserved,
  [in]           PCDRMFORWARD DrmForward
);

Параметры

[in] ContentId

Указывает идентификатор содержимого DRM. Этот параметр определяет защищенный аудиопоток KS.

[in, optional] Reserved

Зарезервировано для последующего использования. Задайте значение NULL.

[in] DrmForward

Указатель на структуру DRMFORWARD , указывающую объект устройства и файловый объект, которые идентифицируют целевое устройство и звуковой пин-код KS на этом устройстве соответственно. Структура также содержит значение контекста, которое KSPROPERTY_DRMAUDIOSTREAM_CONTENTIDзапрос set-property передает устройству.

Возвращаемое значение

DrmForwardContentToDeviceObject возвращает STATUS_SUCCESS, если вызов был успешным. В противном случае возвращается соответствующий код ошибки.

Прежде чем разрешить защищенному содержимому проходить через путь к данным, система проверяет, является ли путь к данным безопасным. Для этого система проверяет подлинность каждого модуля в пути к данным, начиная с вышестоящий конца пути к данным и перемещаясь вниз. По мере проверки подлинности каждого модуля этот модуль предоставляет системные сведения о следующем модуле в пути к данным, чтобы он также можно было пройти проверку подлинности. Для успешной проверки подлинности двоичный файл модуля должен быть подписан как совместимый с DRM.

Два смежных модуля в пути к данным могут взаимодействовать друг с другом одним из нескольких способов. Если модуль вышестоящий вызывает подчиненный модуль через IoCallDriver, то подчиненный модуль является частью драйвера WDM. В этом случае модуль вышестоящий вызывает функцию DrmForwardContentToDeviceObject , чтобы предоставить системе объект устройства, представляющий подчиненный модуль. (Если два модуля взаимодействуют через COM-интерфейс или обработчики содержимого нижестоящего модуля, модуль вышестоящий вызывает DrmForwardContentToInterface или DrmAddContentHandlers.)

Вызывающий объект заполняет элементы DeviceObject, FileObject и Context структуры DRMFORWARD , на которую указывает параметр DrmForward . DrmForwardContentToDeviceObject эти значения используются следующим образом:

DeviceObject указывает объект устройства, представляющий драйвер (подчиненный модуль). DrmForwardContentToDeviceObject использует объект устройства для проверки подлинности драйвера. В случае успешного выполнения функция задает свойство KSPROPERTY_DRMAUDIOSTREAM_CONTENTID на устройстве, отправляя запрос set-property на закрепление KS на устройстве.
FileObject указывает пин-код KS, в который DrmForwardContentToDeviceObject отправляется запрос на свойство.
Context указывает значение контекста, которое вызывающий объект передает драйверу через запрос свойства. DrmForwardContentToDeviceObject копирует значение контекста в дескриптор свойства запроса. Значение контекста обычно является указателем на буфер, содержащий данные в некотором пользовательском формате, понятном как вызывающей стороне, так и драйверу. По соглашению, если подчиненный модуль является фильтром KS, член Context указывает на объект файла, указывающий маркер KS, в который DrmForwardContentToDeviceObject функция отправляет запрос на свойство. Иными словами, элемент Context указывает на тот же объект файла, что и элемент FileObject . Аудиодрайверы USB должны задать для параметра Context значение USBD_PIPE_HANDLE.

Запрос свойства также содержит идентификатор содержимого DRM из параметра ContentId и права на содержимое DRM, принадлежащие данному идентификатору содержимого. DrmForwardContentToDeviceObject копирует эти значения в значение свойства запроса. DrmForwardContentToDeviceObject не использует объект устройства после возврата.

DrmForwardContentToDeviceObject выполняет ту же функцию, что и PcForwardContentToDeviceObject и IDrmPort2::ForwardContentToDeviceObject. Дополнительные сведения см. в разделе Функции и интерфейсы DRM.

Свойство KSPROPERTY_DRMAUDIOSTREAM_CONTENTID назначает идентификатор содержимого DRM и права на содержимое DRM звуковому контакту KS.

Сводная таблица использования

Get	Set	целевого объекта	Тип дескриптора свойства	Тип значения свойства
Нет	Да	Pin	KSP_DRMAUDIOSTREAM_CONTENTID	KSDRMAUDIOSTREAM_CONTENTID

Значение свойства (данные операции) представляет собой KSDRMAUDIOSTREAM_CONTENTID структуру, которая указывает идентификатор содержимого DRM потока и права на содержимое DRM.

Возвращаемое значение

Запрос свойства KSPROPERTY_DRMAUDIOSTREAM_CONTENTID возвращает код состояния, указывающий, может ли фильтр KS принудительно применять указанные права на содержимое DRM, как показано в следующей таблице.

Код состояния	Значение
STATUS_SUCCESS	Фильтр ks audio применяет указанные права на содержимое DRM.
STATUS_NOT_IMPLEMENTED	Фильтр KS не может принудительно применить указанные права на содержимое DRM.

Функция DrmForwardContentToDeviceObject использует это свойство для задания идентификатора содержимого DRM и прав на содержимое в аудиопотоке, входящем в пин-код KS, который является целевым объектом запроса свойства.

Фильтр звука KS обрабатывает этот запрос свойства синхронно. Если запрос возвращает STATUS_SUCCESS, все подчиненные звуковые узлы KS (см. раздел Узлы топологии звука) целевого звукового контакта KS также были успешно настроены с указанным идентификатором содержимого DRM и правами на содержимое DRM. (Обратите внимание, что подчиненный узел является прямым или косвенным приемником для звукового содержимого, протекающего через звуковой контакт.)

Система DRM может задать это свойство в любое время в течение времени существования файлового объекта, представляющего звуковой пин-код KS. Если запрос не выполнен, заданные ранее идентификатор содержимого DRM и права содержимого DRM остаются в силе в аудиопотоке KS.

Обработчик свойства KSPROPERTY_DRMAUDIOSTREAM_CONTENTID должен убедиться, что IRP запроса на свойство создается в режиме ядра (то есть убедитесь, что поле RequestorMode IRP равно KernelMode). Если IRP создается в пользовательском режиме, обработчик должен сбой IRP и возвратить код состояния INVALID_DEVICE_REQUEST.

DrmForwardContentToDeviceObject — это точка входа в системном драйвере DRMK, Drmk.sys. DRMK отправляет запрос IOCTL_KS_PROPERTY для свойства KSPROPERTY_DRMAUDIOSTREAM_CONTENTID на PASSIVE_LEVEL IRQL.

Требования

Требование	Значение
Целевая платформа	Универсальное
Верхняя часть	drmk.h (включая Drmk.h)
Библиотека	Drmk.lib
IRQL	PASSIVE_LEVEL