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

Статья
02/06/2025

Функция 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_CONTENTIDset-property передает устройству.

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

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

Замечания

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

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

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

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

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

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

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

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

Получить	Набор	Цель	Тип дескриптора свойства	Тип значения свойства
Нет	Да	Булавка	KSP_DRMAUDIOSTREAM_CONTENTID	KSDRMAUDIOSTREAM_CONTENTID

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

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

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

Код состояния	Значение
STATUS_SUCCESS	Фильтр звука KS применяет указанные права на содержимое 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 в IRQL PASSIVE_LEVEL.

Требования

Требование	Ценность
целевая платформа	Всеобщий
заголовка	drmk.h (include Drmk.h)
библиотеки	Drmk.lib
IRQL	PASSIVE_LEVEL