DrmForwardContentToDeviceObject function

The DrmForwardContentToDeviceObject function accepts a device object representing a device to which the caller intends to forward protected content. The function authenticates the device and sends it the content ID and DRM rights that the system has assigned to the protected content.

Syntax


NTSTATUS DrmForwardContentToDeviceObject(
  _In_     ULONG        ContentId,
  _In_opt_ PVOID        Reserved,
  _In_     PCDRMFORWARD DrmForward
);

Parameters

ContentId [in]

Specifies the DRM content ID. This parameter identifies a protected KS audio stream.

Reserved [in, optional]

Reserved for future use. Set to NULL.

DrmForward [in]

Pointer to a DRMFORWARD structure specifying a device object and file object that identify the target device and a KS audio pin on that device, respectively. The structure also contains the context value that the KSPROPERTY_DRMAUDIOSTREAM_CONTENTIDset-property request passes to the device.

Return value

DrmForwardContentToDeviceObject returns STATUS_SUCCESS if the call was successful. Otherwise, it returns an appropriate error code.

Remarks

Before allowing protected content to flow through a data path, the system verifies that the data path is secure. To do so, the system authenticates each module in the data path beginning at the upstream end of the data path and moving downstream. As each module is authenticated, that module gives the system information about the next module in the data path so that it can also be authenticated. To be successfully authenticated, a module's binary file must be signed as DRM-compliant.

Two adjacent modules in the data path can communicate with each other in one of several ways. If the upstream module calls the downstream module through IoCallDriver, the downstream module is part of a WDM driver. In this case, the upstream module calls the DrmForwardContentToDeviceObject function to provide the system with the device object representing the downstream module. (If the two modules communicate through the downstream module's COM interface or content handlers, the upstream module calls DrmForwardContentToInterface or DrmAddContentHandlers instead.)

The caller fills in the DeviceObject, FileObject, and Context members of the DRMFORWARD structure that parameter DrmForward points to. DrmForwardContentToDeviceObject uses these values as follows:

  • DeviceObject specifies the device object that represents the driver (the downstream module). DrmForwardContentToDeviceObject uses the device object to authenticate the driver. If successful, the function sets the KSPROPERTY_DRMAUDIOSTREAM_CONTENTID property on the device by sending a set-property request to a KS pin on the device.

  • FileObject specifies the KS pin to which DrmForwardContentToDeviceObject sends the property request.

  • Context specifies a context value that the caller passes to the driver through the property request. DrmForwardContentToDeviceObject copies the context value into the request's property descriptor. The context value is typically a pointer to a buffer containing data in some custom format that both the caller and driver understand. By convention, if the downstream module is a KS filter, the Context member points to a file object that specifies the KS pin to which the DrmForwardContentToDeviceObject function sends the property request. In other words, the Context member points to the same file object as the FileObject member. USB audio drivers must set the Context parameter to a USBD_PIPE_HANDLE value.

The property request also contains the DRM content ID from parameter ContentId and the DRM content rights belonging to that content ID. DrmForwardContentToDeviceObject copies these values into the request's property value. DrmForwardContentToDeviceObject makes no further use of the device object after returning.

DrmForwardContentToDeviceObject performs the same function as PcForwardContentToDeviceObject and IDrmPort2::ForwardContentToDeviceObject. For more information, see DRM Functions and Interfaces.

Requirements

Target platform

Universal

Header

Drmk.h (include Drmk.h)

Library

Drmk.lib

IRQL

PASSIVE_LEVEL

See also

DRMFORWARD
IoCallDriver
DrmForwardContentToInterface
DrmAddContentHandlers
KSPROPERTY_DRMAUDIOSTREAM_CONTENTID
PcForwardContentToDeviceObject
IDrmPort2::ForwardContentToDeviceObject

 

 

Send comments about this topic to Microsoft

Show: