Funzione DRMForwardContentToDeviceObject (drmk.h)

Articolo
08/07/2023

La DrmForwardContentToDeviceObject funzione accetta un oggetto dispositivo che rappresenta un dispositivo a cui il chiamante intende inoltrare contenuto protetto. La funzione autentica il dispositivo e lo invia i diritti DI CONTENUTO e DRM assegnati al contenuto protetto dal sistema.

Sintassi

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

Parametri

[in] ContentId

Specifica l'ID contenuto DRM. Questo parametro identifica un flusso audio KS protetto.

[in, optional] Reserved

Riservato per utilizzi futuri. Impostare su NULL.

[in] DrmForward

Puntatore a una struttura DRMFORWARD che specifica un oggetto dispositivo e un oggetto file che identificano rispettivamente il dispositivo di destinazione e un pin audio KS nel dispositivo. La struttura contiene anche il valore di contesto che la richiesta di proprietà set-set KSPROPERTY_DRMAUDIOSTREAM_CONTENTIDpassa al dispositivo.

Valore restituito

DrmForwardContentToDeviceObject restituisce STATUS_SUCCESS se la chiamata ha esito positivo. In caso contrario, restituisce un codice di errore appropriato.

Commenti

Prima di consentire il flusso del contenuto protetto attraverso un percorso dati, il sistema verifica che il percorso dei dati sia sicuro. A tale scopo, il sistema autentica ogni modulo nel percorso dati a partire dalla fine upstream del percorso dati e lo spostamento a valle. Poiché ogni modulo viene autenticato, tale modulo fornisce le informazioni di sistema sul modulo successivo nel percorso dati in modo che possa essere autenticato anche. Per essere autenticato correttamente, il file binario di un modulo deve essere firmato come conforme a DRM.

Due moduli adiacenti nel percorso dati possono comunicare tra loro in uno dei diversi modi. Se il modulo upstream chiama il modulo downstream tramite IoCallDriver, il modulo downstream fa parte di un driver WDM. In questo caso, il modulo upstream chiama la DrmForwardContentToDeviceObject funzione per fornire al sistema l'oggetto dispositivo che rappresenta il modulo downstream. Se i due moduli comunicano tramite l'interfaccia COM del modulo downstream o i gestori di contenuto, il modulo upstream chiama invece DRMForwardContentToInterface o DrmAddContentHandlers .

Il chiamante compila i membri DeviceObject, FileObject e Context della struttura DRMFORWARD a cui punta DrmForward. DrmForwardContentToDeviceObject usa questi valori come indicato di seguito:

DeviceObject specifica l'oggetto dispositivo che rappresenta il driver (il modulo downstream). DrmForwardContentToDeviceObject usa l'oggetto dispositivo per autenticare il driver. Se ha esito positivo, la funzione imposta la proprietà KSPROPERTY_DRMAUDIOSTREAM_CONTENTID nel dispositivo inviando una richiesta di proprietà set a un pin KS nel dispositivo.
FileObject specifica il pin KS a cui DrmForwardContentToDeviceObject invia la richiesta di proprietà.
Il contesto specifica un valore di contesto che il chiamante passa al driver tramite la richiesta di proprietà. DrmForwardContentToDeviceObject copia il valore del contesto nel descrittore della proprietà della richiesta. Il valore di contesto è in genere un puntatore a un buffer contenente dati in un formato personalizzato che sia il chiamante che il driver capiscono. Per convenzione, se il modulo downstream è un filtro KS, il membro Context punta a un oggetto file che specifica il pin KS a cui la funzione invia la DrmForwardContentToDeviceObject richiesta di proprietà. In altre parole, il membro Context punta allo stesso oggetto file del membro FileObject . I driver audio USB devono impostare il parametro Context su un valore USBD_PIPE_HANDLE.

La richiesta di proprietà contiene anche l'ID contenuto DRM dal parametro ContentId e i diritti di contenuto DRM appartenenti a tale ID contenuto. DrmForwardContentToDeviceObject copia questi valori nel valore della proprietà della richiesta. DrmForwardContentToDeviceObject non usa ulteriormente l'oggetto dispositivo dopo la restituzione.

DrmForwardContentToDeviceObject esegue la stessa funzione di PcForwardContentToDeviceObject e IDrmPort2::ForwardContentToDeviceObject. Per altre informazioni, vedere Funzioni e interfacce DRM.

La proprietà KSPROPERTY_DRMAUDIOSTREAM_CONTENTID assegna l'ID contenuto DRM e i diritti di contenuto DRM a un pin audio KS.

Tabella riepilogo utilizzo

Get	Set	Destinazione	Tipo di descrittore delle proprietà	Tipo di valore della proprietà
No	Sì	Aggiungi (Blocca)	KSP_DRMAUDIOSTREAM_CONTENTID	KSDRMAUDIOSTREAM_CONTENTID

Il valore della proprietà (dati dell'operazione) è una struttura KSDRMAUDIOSTREAM_CONTENTID che specifica l'ID contenuto DRM del flusso e i diritti di contenuto DRM.

Valore restituito

Una richiesta di proprietà KSPROPERTY_DRMAUDIOSTREAM_CONTENTID restituisce un codice di stato che indica se il filtro KS può applicare i diritti di contenuto DRM specificati, come illustrato nella tabella seguente.

Codice di stato	Significato
STATUS_SUCCESS	Il filtro audio KS applica i diritti di contenuto DRM specificati.
STATUS_NOT_IMPLEMENTED	Il filtro KS non può applicare i diritti di contenuto DRM specificati.

La funzione DrmForwardContentToDeviceObject usa questa proprietà per impostare l'ID contenuto DRM e i diritti di contenuto sul flusso audio immettendo il pin KS che è la destinazione della richiesta di proprietà.

Un filtro audio KS gestisce in modo sincrono questa richiesta di proprietà. Se la richiesta restituisce STATUS_SUCCESS, tutti i nodi audio KS downstream (vedere Nodi topologia audio) del pin audio KS di destinazione sono stati configurati anche correttamente con i diritti di contenuto DRM e DRM specificati. Si noti che un nodo downstream è un sink diretto o indiretto per il contenuto audio che scorre attraverso un pin audio.

Il sistema DRM può impostare questa proprietà in qualsiasi momento durante la durata dell'oggetto file che rappresenta un pin audio KS. Se la richiesta non riesce, i diritti di contenuto DRM e DRM impostati in precedenza rimangono effettivi nel flusso audio KS.

Il gestore per la proprietà KSPROPERTY_DRMAUDIOSTREAM_CONTENTID deve verificare che l'IRP della proprietà sia originato in modalità kernel, ovvero verificare che il campo RequestorMode di IRP sia uguale a KernelMode. Se l'IRP ha origine in modalità utente, il gestore deve avere esito negativo sull'IRP e restituire il codice di stato INVALID_DEVICE_REQUEST.

DrmForwardContentToDeviceObject è un punto di ingresso nel driver di sistema DRMK, Drmk.sys. DRMK invia una richiesta di IOCTL_KS_PROPERTY per la proprietà KSPROPERTY_DRMAUDIOSTREAM_CONTENTID in IRQL PASSIVE_LEVEL.