Função DrmForwardContentToDeviceObject (drmk.h)

Artigo
08/07/2023

A DrmForwardContentToDeviceObject função aceita um objeto de dispositivo que representa um dispositivo para o qual o chamador pretende encaminhar conteúdo protegido. A função autentica o dispositivo e envia a ele a ID de conteúdo e os direitos de DRM que o sistema atribuiu ao conteúdo protegido.

Sintaxe

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

Parâmetros

[in] ContentId

Especifica a ID de conteúdo do DRM. Esse parâmetro identifica um fluxo de áudio KS protegido.

[in, optional] Reserved

Reservado para uso futuro. Defina como NULL.

[in] DrmForward

Ponteiro para uma estrutura DRMFORWARD especificando um objeto de dispositivo e um objeto de arquivo que identificam o dispositivo de destino e um pino de áudio KS nesse dispositivo, respectivamente. A estrutura também contém o valor de contexto que o KSPROPERTY_DRMAUDIOSTREAM_CONTENTIDsolicitação set-property passa para o dispositivo.

Retornar valor

DrmForwardContentToDeviceObject retornará STATUS_SUCCESS se a chamada tiver sido bem-sucedida. Caso contrário, ele retornará um código de erro apropriado.

Comentários

Antes de permitir que o conteúdo protegido flua por um caminho de dados, o sistema verifica se o caminho de dados é seguro. Para fazer isso, o sistema autentica cada módulo no caminho de dados começando no final upstream do caminho de dados e movendo-se downstream. À medida que cada módulo é autenticado, esse módulo fornece ao sistema informações sobre o próximo módulo no caminho de dados para que ele também possa ser autenticado. Para ser autenticado com êxito, o arquivo binário de um módulo deve ser assinado como compatível com DRM.

Dois módulos adjacentes no caminho de dados podem se comunicar entre si de várias maneiras. Se o módulo upstream chamar o módulo downstream por meio do IoCallDriver, o módulo downstream faz parte de um driver WDM. Nesse caso, o módulo upstream chama a DrmForwardContentToDeviceObject função para fornecer ao sistema o objeto de dispositivo que representa o módulo downstream. (Se os dois módulos se comunicarem por meio da interface COM ou dos manipuladores de conteúdo do módulo downstream, o módulo upstream chamará DrmForwardContentToInterface ou DrmAddContentHandlers.)

O chamador preenche os membros DeviceObject, FileObject e Context da estrutura DRMFORWARD para a qual o parâmetro DrmForward aponta. DrmForwardContentToDeviceObject usa esses valores da seguinte maneira:

DeviceObject especifica o objeto de dispositivo que representa o driver (o módulo downstream). DrmForwardContentToDeviceObject usa o objeto de dispositivo para autenticar o driver. Se tiver êxito, a função definirá a propriedade KSPROPERTY_DRMAUDIOSTREAM_CONTENTID no dispositivo enviando uma solicitação set-property para um pino KS no dispositivo.
FileObject especifica o pino KS para o qual DrmForwardContentToDeviceObject envia a solicitação de propriedade.
O contexto especifica um valor de contexto que o chamador passa para o driver por meio da solicitação de propriedade. DrmForwardContentToDeviceObject copia o valor de contexto para o descritor de propriedade da solicitação. O valor de contexto normalmente é um ponteiro para um buffer que contém dados em algum formato personalizado que o chamador e o driver entendem. Por convenção, se o módulo downstream for um filtro KS, o membro Context apontará para um objeto de arquivo que especifica o pino KS para o qual a DrmForwardContentToDeviceObject função envia a solicitação de propriedade. Em outras palavras, o membro Context aponta para o mesmo objeto de arquivo que o membro FileObject . Os drivers de áudio USB devem definir o parâmetro Context como um valor USBD_PIPE_HANDLE.

A solicitação de propriedade também contém a ID de conteúdo DRM do parâmetro ContentId e os direitos de conteúdo DRM que pertencem a essa ID de conteúdo. DrmForwardContentToDeviceObject copia esses valores para o valor da propriedade da solicitação. DrmForwardContentToDeviceObject não faz mais uso do objeto de dispositivo depois de retornar.

DrmForwardContentToDeviceObject executa a mesma função que PcForwardContentToDeviceObject e IDrmPort2::ForwardContentToDeviceObject. Para obter mais informações, consulte Funções e interfaces drm.

A propriedade KSPROPERTY_DRMAUDIOSTREAM_CONTENTID atribui a ID de conteúdo drm e os direitos de conteúdo DRM a um pino de áudio KS.

Tabela de Resumo de Uso

Get	Set	Destino	Tipo de descritor de propriedade	Tipo de valor da propriedade
No	Yes	Pin	KSP_DRMAUDIOSTREAM_CONTENTID	KSDRMAUDIOSTREAM_CONTENTID

O valor da propriedade (dados de operação) é uma estrutura KSDRMAUDIOSTREAM_CONTENTID que especifica a ID de conteúdo drm do fluxo e os direitos de conteúdo DRM.

Valor retornado

Uma solicitação de propriedade KSPROPERTY_DRMAUDIOSTREAM_CONTENTID retorna um código status que indica se o filtro KS pode impor os direitos de conteúdo DRM especificados, conforme mostrado na tabela a seguir.

Código de status	Significado
STATUS_SUCCESS	O filtro de áudio KS impõe os direitos de conteúdo drm especificados.
STATUS_NOT_IMPLEMENTED	O filtro KS não pode impor os direitos de conteúdo drm especificados.

A função DrmForwardContentToDeviceObject usa essa propriedade para definir a ID de conteúdo drm e os direitos de conteúdo no fluxo de áudio inserindo o pino KS que é o destino da solicitação de propriedade.

Um filtro de áudio KS manipula essa solicitação de propriedade de forma síncrona. Se a solicitação retornar STATUS_SUCCESS, todos os nós de áudio KS downstream (consulte Nós de Topologia de Áudio) do pino de áudio KS de destino também foram configurados com êxito com a ID de conteúdo drm especificada e os direitos de conteúdo DRM. (Observe que um nó downstream é um coletor direto ou indireto para o conteúdo de áudio que flui por meio de um pino de áudio.)

O sistema DRM pode definir essa propriedade a qualquer momento durante o tempo de vida do objeto de arquivo que representa um pino de áudio KS. Se a solicitação não for bem-sucedida, os direitos de conteúdo DRM e ID de conteúdo DRM definidos anteriormente permanecerão em vigor no fluxo de áudio do KS.

O manipulador da propriedade KSPROPERTY_DRMAUDIOSTREAM_CONTENTID deve verificar se o IRP de solicitação de propriedade se origina no modo kernel (ou seja, confirmar se o campo RequestorMode do IRP é igual a KernelMode). Se o IRP for originado no modo de usuário, o manipulador deverá falhar no IRP e retornar status código INVALID_DEVICE_REQUEST.

DrmForwardContentToDeviceObject é um ponto de entrada no driver do sistema DRMK, Drmk.sys. O DRMK envia uma solicitação de IOCTL_KS_PROPERTY para a propriedade KSPROPERTY_DRMAUDIOSTREAM_CONTENTID no PASSIVE_LEVEL IRQL.