DrmForwardContentToDeviceObject-Funktion (drmk.h)

Artikel
02/06/2025

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 es die Inhalts-ID und 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-Audiodatenstrom.

[in, optional] Reserved

Reserviert für die zukünftige Verwendung. Wird auf NULL-festgelegt.

[in] DrmForward

Zeigen Sie auf eine DRMFORWARD- Struktur, die ein Geräteobjekt und ein Dateiobjekt angibt, das das Zielgerät bzw. einen KS-Audio-Pin auf diesem Gerät identifiziert. 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 Anruf erfolgreich war. Andernfalls wird ein entsprechender Fehlercode zurückgegeben.

Bemerkungen

Bevor geschützte Inhalte über einen Datenpfad fließen können, überprüft das System, ob der Datenpfad sicher ist. Dazu authentifiziert das System jedes Modul im Datenpfad beginnend am vorgelagerten Ende des Datenpfads und bewegt sich nach unten. Da jedes Modul authentifiziert ist, gibt dieses Modul dem System Informationen zum nächsten Modul im Datenpfad, damit es auch authentifiziert werden kann. Um erfolgreich authentifiziert zu werden, muss die Binärdatei eines Moduls als DRM-kompatibel signiert werden.

Zwei benachbarte Module im Datenpfad können auf eine von mehreren Arten miteinander kommunizieren. Wenn das Upstreammodul das downstream-Modul über IoCallDriver-aufruft, ist das downstream-Modul Teil eines WDM-Treibers. In diesem Fall ruft das upstream-Modul die DrmForwardContentToDeviceObject-Funktion auf, um das System mit dem Geräteobjekt bereitzustellen, das das nachgeschaltete Modul darstellt. (Wenn die beiden Module über die COM-Schnittstelle oder Inhaltshandler des nachgeschalteten Moduls kommunizieren, ruft das upstream-Modul stattdessen DrmForwardContentToInterface oder DrmAddContentHandlers auf.)

Der Aufrufer füllt die elemente DeviceObject, FileObjectund Context Member der DRMFORWARD Struktur, auf die der Parameter DrmForward verweist. DrmForwardContentToDeviceObject verwendet diese Werte wie folgt:

DeviceObject- gibt das Geräteobjekt an, das den Treiber (das nachgeschaltete Modul) 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-Property-Anforderung an einen KS-Pin auf dem Gerät gesendet wird.
FileObject- gibt den KS-Pin an, an den DrmForwardContentToDeviceObject die Eigenschaftsanforderung sendet.
Context gibt einen Kontextwert an, den der Aufrufer über die Eigenschaftsanforderung an den Treiber übergibt. DrmForwardContentToDeviceObject kopiert den Kontextwert in den Eigenschaftsdeskriptor der Anforderung. Der Kontextwert ist in der Regel ein Zeiger auf einen Puffer, der Daten in einem benutzerdefinierten Format enthält, das sowohl der Aufrufer als auch der Treiber verstehen. Wenn das nachgeschaltete Modul ein KS-Filter ist, verweist das Context Member auf ein Dateiobjekt, das den KS-Pin angibt, an den die DrmForwardContentToDeviceObject-Funktion die Eigenschaftsanforderung sendet. Mit anderen Worten verweist das Context Member auf dasselbe Dateiobjekt wie das FileObject Member. USB-Audiotreiber müssen den Parameter Context auf einen USBD_PIPE_HANDLE-Wert festlegen.

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

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

Die eigenschaft KSPROPERTY_DRMAUDIOSTREAM_CONTENTID weist der KS-Audio-Pin die DRM-Inhalts-ID und DRM-Inhaltsrechte zu.

Zusammenfassungstabelle für die Verwendung

Erhalten	Garnitur	Ziel	Eigenschaftendeskriptortyp	Eigenschaftswerttyp
Nein	Ja	Stecknadel	KSP_DRMAUDIOSTREAM_CONTENTID	KSDRMAUDIOSTREAM_CONTENTID

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

Rückgabewert

Eine KSPROPERTY_DRMAUDIOSTREAM_CONTENTID-Eigenschaftsanforderung gibt einen Statuscode 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 eingibt, der das Ziel der Eigenschaftsanforderung ist.

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

Das DRM-System kann diese Eigenschaft jederzeit während der Lebensdauer des Dateiobjekts festlegen, das eine KS-Audio-Pin darstellt. Wenn die Anforderung nicht erfolgreich ist, bleiben die zuvor festgelegten DRM-Inhalts-ID und DRM-Inhaltsrechte für den KS-Audiodatenstrom wirksam.

Der Handler für die KSPROPERTY_DRMAUDIOSTREAM_CONTENTID-Eigenschaft muss überprüfen, ob das IRP der Eigenschaftsanforderung im Kernelmodus stammt (d. h. bestätigen Sie, dass das RequestorMode-Feld des IRPKernelMode-ist). Wenn das IRP aus dem Benutzermodus stammt, muss der Handler den IRP-Code nicht ausführen und statuscode 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 bei IRQL-PASSIVE_LEVEL.