DrmForwardContentToDeviceObject, fonction (drmk.h)

Article
02/29/2024

La DrmForwardContentToDeviceObject fonction accepte un objet d’appareil représentant un appareil vers lequel l’appelant a l’intention de transférer du contenu protégé. La fonction authentifie l’appareil et lui envoie l’ID de contenu et les droits DRM que le système a attribués au contenu protégé.

Syntaxe

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

Paramètres

[in] ContentId

Spécifie l’ID de contenu DRM. Ce paramètre identifie un flux audio KS protégé.

[in, optional] Reserved

Réservé pour un usage futur. Défini sur NULL.

[in] DrmForward

Pointeur vers une structure DRMFORWARD spécifiant un objet d’appareil et un objet de fichier qui identifient l’appareil cible et une broche audio KS sur cet appareil, respectivement. La structure contient également la valeur de contexte que le KSPROPERTY_DRMAUDIOSTREAM_CONTENTIDdemande set-property transmet à l’appareil.

Valeur retournée

DrmForwardContentToDeviceObject retourne STATUS_SUCCESS si l’appel a réussi. Sinon, il retourne un code d’erreur approprié.

Remarques

Avant d’autoriser le flux de contenu protégé dans un chemin de données, le système vérifie que le chemin d’accès aux données est sécurisé. Pour ce faire, le système authentifie chaque module dans le chemin de données en commençant à l’amont fin du chemin de données et en se déplaçant en aval. Comme chaque module est authentifié, ce module fournit au système des informations sur le module suivant dans le chemin des données afin qu’il puisse également être authentifié. Pour être correctement authentifié, le fichier binaire d’un module doit être signé en tant que conforme DRM.

Deux modules adjacents dans le chemin de données peuvent communiquer entre eux de plusieurs manières. Si le module amont appelle le module en aval via IoCallDriver, le module en aval fait partie d’un pilote WDM. Dans ce cas, le module amont appelle la DrmForwardContentToDeviceObject fonction pour fournir au système l’objet d’appareil représentant le module en aval. (Si les deux modules communiquent via l’interface COM ou les gestionnaires de contenu du module en aval, le module amont appelle DrmForwardContentToInterface ou DrmAddContentHandlers à la place.)

L’appelant remplit les membres DeviceObject, FileObject et Context de la structure DRMFORWARD vers laquelle pointe le paramètre DrmForward . DrmForwardContentToDeviceObject utilise ces valeurs comme suit :

DeviceObject spécifie l’objet d’appareil qui représente le pilote (module en aval). DrmForwardContentToDeviceObject utilise l’objet d’appareil pour authentifier le pilote. Si elle réussit, la fonction définit la propriété KSPROPERTY_DRMAUDIOSTREAM_CONTENTID sur l’appareil en envoyant une requête set-property à une broche KS sur l’appareil.
FileObject spécifie la broche KS à laquelle DrmForwardContentToDeviceObject envoie la demande de propriété.
Context spécifie une valeur de contexte que l’appelant transmet au pilote via la demande de propriété. DrmForwardContentToDeviceObject copie la valeur de contexte dans le descripteur de propriété de la demande. La valeur de contexte est généralement un pointeur vers une mémoire tampon contenant des données dans un format personnalisé que l’appelant et le pilote comprennent. Par convention, si le module en aval est un filtre KS, le membre Context pointe vers un objet de fichier qui spécifie la broche KS à laquelle la DrmForwardContentToDeviceObject fonction envoie la demande de propriété. En d’autres termes, le membre Context pointe vers le même objet de fichier que le membre FileObject . Les pilotes audio USB doivent définir le paramètre Context sur une valeur USBD_PIPE_HANDLE.

La demande de propriété contient également l’ID de contenu DRM du paramètre ContentId et les droits de contenu DRM appartenant à cet ID de contenu. DrmForwardContentToDeviceObject copie ces valeurs dans la valeur de propriété de la demande. DrmForwardContentToDeviceObject n’utilise plus l’objet d’appareil après le retour.

DrmForwardContentToDeviceObject exécute la même fonction que PcForwardContentToDeviceObject et IDrmPort2 ::ForwardContentToDeviceObject. Pour plus d’informations, consultez Fonctions et interfaces DRM.

La propriété KSPROPERTY_DRMAUDIOSTREAM_CONTENTID affecte l’ID de contenu DRM et les droits de contenu DRM à une broche audio KS.

Tableau récapitulatif de l’utilisation

Get	Set	Cible	Type de descripteur de propriété	Type de valeur de propriété
Non	Oui	Épingle	KSP_DRMAUDIOSTREAM_CONTENTID	KSDRMAUDIOSTREAM_CONTENTID

La valeur de propriété (données d’opération) est une structure KSDRMAUDIOSTREAM_CONTENTID qui spécifie l’ID de contenu DRM et les droits de contenu DRM du flux.

Valeur de retour

Une demande de propriété KSPROPERTY_DRMAUDIOSTREAM_CONTENTID retourne un code status qui indique si le filtre KS peut appliquer les droits de contenu DRM spécifiés, comme indiqué dans le tableau suivant.

Code d’état	Signification
STATUS_SUCCESS	Le filtre audio KS applique les droits de contenu DRM spécifiés.
STATUS_NOT_IMPLEMENTED	Le filtre KS ne peut pas appliquer les droits de contenu DRM spécifiés.

La fonction DrmForwardContentToDeviceObject utilise cette propriété pour définir l’ID de contenu DRM et les droits de contenu sur le flux audio entrant la broche KS qui est la cible de la demande de propriété.

Un filtre audio KS gère cette requête de propriété de manière synchrone. Si la requête retourne STATUS_SUCCESS, tous les nœuds audio KS en aval (voir Nœuds de topologie audio) de la broche audio KS cible ont également été correctement configurés avec l’ID de contenu DRM et les droits de contenu DRM spécifiés. (Notez qu’un nœud en aval est un récepteur direct ou indirect pour le contenu audio transitant par une broche audio.)

Le système DRM peut définir cette propriété à tout moment pendant la durée de vie de l’objet fichier qui représente une broche audio KS. Si la demande échoue, l’ID de contenu DRM et les droits de contenu DRM définis précédemment restent en vigueur sur le flux audio KS.

Le gestionnaire de la propriété KSPROPERTY_DRMAUDIOSTREAM_CONTENTID doit vérifier que l’IRP de la demande de propriété provient du mode noyau (autrement dit, vérifiez que le champ RequestorMode de l’IRP est égal à KernelMode). Si l’IRP provient du mode utilisateur, le gestionnaire doit échouer l’IRP et retourner status code INVALID_DEVICE_REQUEST.

DrmForwardContentToDeviceObject est un point d’entrée dans le pilote système DRMK, Drmk.sys. DRMK envoie une demande de IOCTL_KS_PROPERTY pour la propriété KSPROPERTY_DRMAUDIOSTREAM_CONTENTID à l’PASSIVE_LEVEL IRQL.