DrmForwardContentToDeviceObject-Funktion (drmk.h)

Artikel
02/26/2024

Die DrmForwardContentToDeviceObject Funktion akzeptiert ein Geräteobjekt, das ein Gerät darstellt, an das der Aufrufer geschützte Inhalte weiterleiten möchte. Die Funktion authentifiziert das Gerät und sendet ihm die Inhalts-ID und die DRM-Rechte, die das System dem geschützten Inhalt zugewiesen hat.

Syntax

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

Parameter

[in] ContentId

Gibt die DRM-Inhalts-ID an. Dieser Parameter identifiziert einen geschützten KS-Audiostream.

[in, optional] Reserved

Für die zukünftige Verwendung reserviert. Auf NULL festgelegt.

[in] DrmForward

Zeiger auf eine DRMFORWARD-Struktur , die ein Geräteobjekt und ein Dateiobjekt angibt, die das Zielgerät bzw. einen KS-Audionadel auf diesem Gerät identifizieren. Die Struktur enthält auch den Kontextwert, den die KSPROPERTY_DRMAUDIOSTREAM_CONTENTIDSet-Property-Anforderung an das Gerät übergibt.

Rückgabewert

DrmForwardContentToDeviceObject gibt STATUS_SUCCESS zurück, wenn der Aufruf erfolgreich war. Andernfalls wird ein entsprechender Fehlercode zurückgegeben.

Hinweise

Bevor geschützte Inhalte einen Datenpfad durchlaufen können, überprüft das System, ob der Datenpfad sicher ist. Hierzu authentifiziert das System jedes Modul im Datenpfad ab dem Upstream Ende des Datenpfads und bewegt sich nach unten. Wenn jedes Modul authentifiziert wird, gibt dieses Modul dem System Informationen zum nächsten Modul im Datenpfad, sodass es auch authentifiziert werden kann. Um erfolgreich authentifiziert zu werden, muss die Binärdatei eines Moduls als DRM-konform signiert werden.

Zwei benachbarte Module im Datenpfad können auf verschiedene Weise miteinander kommunizieren. Wenn das Upstream-Modul das Downstreammodul über IoCallDriver aufruft, ist das Downstreammodul Teil eines WDM-Treibers. In diesem Fall ruft das modul Upstream die DrmForwardContentToDeviceObject Funktion auf, um dem System das Geräteobjekt bereitzustellen, das das downstream-Modul darstellt. (Wenn die beiden Module über die COM-Schnittstelle oder Die Inhaltshandler des nachgeschalteten Moduls kommunizieren, ruft das Upstream Modul stattdessen DrmForwardContentToInterface oder DrmAddContentHandlers auf.)

Der Aufrufer füllt die Member DeviceObject, FileObject und Context der DRMFORWARD-Struktur aus, auf die der Parameter DrmForward zeigt. DrmForwardContentToDeviceObject verwendet die folgenden Werte wie folgt:

DeviceObject gibt das Geräteobjekt an, das den Treiber (das Downstreammodul) darstellt. DrmForwardContentToDeviceObject verwendet das Geräteobjekt, um den Treiber zu authentifizieren. Bei erfolgreicher Ausführung legt die Funktion die KSPROPERTY_DRMAUDIOSTREAM_CONTENTID-Eigenschaft auf dem Gerät fest, indem eine Set-Eigenschaftsanforderung an einen KS-Pin auf dem Gerät gesendet wird.
FileObject gibt den KS-Pin an, an den DrmForwardContentToDeviceObject die Eigenschaftsanforderung gesendet wird.
Context gibt einen Kontextwert an, den der Aufrufer über die Eigenschaftsanforderung an den Treiber übergibt. DrmForwardContentToDeviceObject kopiert den Kontextwert in die Eigenschaftsbeschreibung der Anforderung. Der Kontextwert ist in der Regel ein Zeiger auf einen Puffer, der Daten in einem benutzerdefinierten Format enthält, die sowohl der Aufrufer als auch der Treiber verstehen. Wenn es sich bei dem nachgeschalteten Modul um einen KS-Filter handelt, zeigt das Context-Element gemäß der Konvention auf ein Dateiobjekt, das den KS-Pin angibt, an den die DrmForwardContentToDeviceObject Funktion die Eigenschaftsanforderung sendet. Anders ausgedrückt: Das Context-Element verweist auf dasselbe Dateiobjekt wie das FileObject-Element . USB-Audiotreiber müssen den Context-Parameter auf einen USBD_PIPE_HANDLE-Wert festlegen.

Die Eigenschaftsanforderung enthält auch die DRM-Inhalts-ID aus dem Parameter ContentId und die DRM-Inhaltsrechte, die dieser Inhalts-ID gehören. DrmForwardContentToDeviceObject kopiert diese Werte in den Eigenschaftswert der Anforderung. DrmForwardContentToDeviceObject verwendet das Geräteobjekt nach der Rückgabe nicht weiter.

DrmForwardContentToDeviceObject führt dieselbe Funktion wie PcForwardContentToDeviceObject und IDrmPort2::ForwardContentToDeviceObject aus. Weitere Informationen finden Sie unter DRM-Funktionen und -Schnittstellen.

Die KSPROPERTY_DRMAUDIOSTREAM_CONTENTID-Eigenschaft weist einem KS-Audionadel die DRM-Inhalts-ID und DRM-Inhaltsrechte zu.

Nutzungszusammenfassungstabelle

Herunterladen	Set	Ziel	Eigenschaftsdeskriptortyp	Eigenschaftswerttyp
Nein	Ja	Pin	KSP_DRMAUDIOSTREAM_CONTENTID	KSDRMAUDIOSTREAM_CONTENTID

Der Eigenschaftswert (Vorgangsdaten) ist eine KSDRMAUDIOSTREAM_CONTENTID Struktur, die die DRM-Inhalts-ID und DRM-Inhaltsrechte des Datenstroms angibt.

Rückgabewert

Eine KSPROPERTY_DRMAUDIOSTREAM_CONTENTID-Eigenschaftsanforderung gibt einen status Code zurück, der angibt, ob der KS-Filter die angegebenen DRM-Inhaltsrechte erzwingen kann, wie in der folgenden Tabelle gezeigt.

Statuscode	Bedeutung
STATUS_SUCCESS	Der KS-Audiofilter erzwingt die angegebenen DRM-Inhaltsrechte.
STATUS_NOT_IMPLEMENTED	Der KS-Filter kann die angegebenen DRM-Inhaltsrechte nicht erzwingen.

Die DrmForwardContentToDeviceObject-Funktion verwendet diese Eigenschaft, um die DRM-Inhalts-ID und die Inhaltsrechte für den Audiodatenstrom festzulegen, der den KS-Pin eingeben, der das Ziel der Eigenschaftsanforderung ist.

Ein KS-Audiofilter verarbeitet diese Eigenschaftsanforderung synchron. Wenn die Anforderung STATUS_SUCCESS zurückgibt, wurden auch alle nachgeschalteten KS-Audioknoten (siehe Audiotopologieknoten) des Ziel-KS-Audionadels erfolgreich mit den angegebenen DRM-Inhalts-ID und DRM-Inhaltsrechten konfiguriert. (Beachten Sie, dass ein Downstreamknoten eine direkte oder indirekte Senke für den Audioinhalt ist, der über eine Audionadel fließt.)

Das DRM-System kann diese Eigenschaft jederzeit während der Lebensdauer des Dateiobjekts festlegen, das einen KS-Audionadel darstellt. Wenn die Anforderung nicht erfolgreich ist, bleiben die zuvor festgelegten DRM-Inhalts-ID- und DRM-Inhaltsrechte für den KS-Audiostream gültig.

Der Handler für die KSPROPERTY_DRMAUDIOSTREAM_CONTENTID-Eigenschaft muss überprüfen, ob das Eigenschaftsanforderungs-IRP aus dem Kernelmodus stammt (d. h. überprüfen Sie, ob das RequestorMode-Feld des IRP dem KernelMode entspricht). Wenn die IRP aus dem Benutzermodus stammt, muss der Handler das IRP fehlschlagen und status Code INVALID_DEVICE_REQUEST zurückgeben.

DrmForwardContentToDeviceObject ist ein Einstiegspunkt im DRMK-Systemtreiber, Drmk.sys. DRMK sendet eine IOCTL_KS_PROPERTY Anforderung für die KSPROPERTY_DRMAUDIOSTREAM_CONTENTID-Eigenschaft am IRQL-PASSIVE_LEVEL.