Função DrmForwardContentToDeviceObject (drmk.h)

Artigo
02/06/2025

A função DrmForwardContentToDeviceObject 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 atribuídos pelo sistema 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 drm. Esse parâmetro identifica um fluxo de áudio KS protegido.

[in, optional] Reserved

Reservado para uso futuro. Definir 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 a solicitação KSPROPERTY_DRMAUDIOSTREAM_CONTENTIDset-property passa para o dispositivo.

Valor de retorno

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

Observações

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 para baixo. À 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 IoCallDriver, o módulo downstream faz parte de um driver WDM. Nesse caso, o módulo upstream chama a função DrmForwardContentToDeviceObject para fornecer ao sistema o objeto do dispositivo que representa o módulo downstream. (Se os dois módulos se comunicarem por meio da interface COM do módulo downstream ou manipuladores de conteúdo, o módulo upstream chamará DrmForwardContentToInterface ou DrmAddContentHandlers em vez disso.)

O chamador preenche os membros DeviceObject, FileObjecte Context membros da estrutura DRMFORWARD que o parâmetro DrmForward aponta. DrmForwardContentToDeviceObject usa esses valores da seguinte maneira:

DeviceObject especifica o objeto do dispositivo que representa o driver (o módulo downstream). DrmForwardContentToDeviceObject usa o objeto do dispositivo para autenticar o driver. Se bem-sucedida, a função define a propriedade KSPROPERTY_DRMAUDIOSTREAM_CONTENTID no dispositivo enviando uma solicitação set-property para um pino KS no dispositivo.
FileObject especifica o pino KS ao qual DrmForwardContentToDeviceObject envia a solicitação de propriedade.
Context 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 no 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 ao qual a função DrmForwardContentToDeviceObject 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 de Contexto 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 do dispositivo após o retorno.

DrmForwardContentToDeviceObject executa a mesma função que pcForwardContentToDeviceObject e IDrmPort2::ForwardContentToDeviceObject. Para obter mais informações, consulte de funções e interfaces do DRM.

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

Tabela de Resumo de Uso do

Obter	Pôr	Alvo	Tipo de descritor de propriedade	Tipo de valor de propriedade
Não	Sim	Alfinete	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 de 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 de DRM especificados.
STATUS_NOT_IMPLEMENTED	O filtro KS não pode impor os direitos de conteúdo de 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 que insere 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 pin de áudio.)

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

O manipulador da propriedade KSPROPERTY_DRMAUDIOSTREAM_CONTENTID deve verificar se o IRP de solicitação de propriedade tem origem no modo kernel (ou seja, confirmar que 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 o código de status INVALID_DEVICE_REQUEST.

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