Função KsProbeStreamIrp (ks.h)

  • Artigo

A função KsProbeStreamIrp faz as modificações especificadas nos buffers de entrada e saída do IRP fornecido com base nos sinalizadores passados e valida o cabeçalho de fluxo. Isso é útil ao localizar o tratamento de exceções ou executar trabalhos assíncronos em um IRP. O IRP resultante está essencialmente no formato METHOD_OUT_DIRECT ou METHOD_IN_DIRECT, com a exceção de que o acesso ao buffer de dados pode ser IoModifyAccess, dependendo dos sinalizadores passados para essa função ou os sinalizadores no cabeçalho do fluxo.

Sintaxe

KSDDKAPI NTSTATUS KsProbeStreamIrp(
  [in, out]      PIRP  Irp,
  [in]           ULONG ProbeFlags,
  [in, optional] ULONG HeaderSize
);

Parâmetros

[in, out] Irp

Especifica o IRP cujos buffers de entrada e saída devem ser mapeados. O modo solicitante do IRP é usado ao investigar os buffers.

[in] ProbeFlags

Especifica sinalizadores que especificam como investigar o IRP de streaming; os sinalizadores são listados na tabela a seguir.

[in, optional] HeaderSize

Especifica o tamanho para validar cada cabeçalho em relação ao passado para esse cliente ou zero se nenhuma validação for feita. Se usado, supõe-se que todo o buffer passado seja um múltiplo desse tamanho de cabeçalho, a menos que o buffer contenha um único cabeçalho de alteração de formato.

Retornar valor

A função KsProbeStreamIrp retornará STATUS_SUCCESS se tiver êxito ou retornará um erro de memória ou acesso.

Comentários

Se a função for usada apenas para alocar MDL e não para investigar e bloquear os endereços, o chamador deverá ter uma rotina de conclusão para limpo os MDL. Por exemplo, um mecanismo de bloqueio just-in-time pode alocar a lista de MDL, mas apenas bloquear a memória conforme necessário. O cliente deve fornecer código de limpeza para remover a lista de MDL parcialmente bloqueada antes que o IRP seja concluído, presumivelmente em uma rotina de conclusão.

Se os cabeçalhos parecerem já ter sido copiados para um buffer do sistema, ele não será validado novamente. Em geral, chamar a função KsProbeStreamIrp várias vezes com um IRP não é prejudicial. Depois de chamar a função, os cabeçalhos de fluxo estão disponíveis no PIRP. AssociatedIrp.SystemBuffer. Se os MDLs do buffer de fluxo tiverem sido alocados, eles estarão disponíveis por meio do PIRP. MdlAddress.

As seguintes definições são usadas para a variável ProbeFlags :

ProbeFlags Valor Descrição
KSPROBE_READ Indica que a operação é um fluxo lido no dispositivo. Esse é o padrão.
KSPROBE_WRITE Indica que a operação é uma gravação de fluxo no dispositivo.
KSPROBE_ALLOCATEMDL Indica que os MDLs devem ser alocados para os buffers de fluxo se ainda não tiverem sido alocados. Se nenhum buffer de fluxo estiver presente, o sinalizador será ignorado. Se KSPROBE_PROBEANDLOCK não for especificado ao mesmo tempo que esse sinalizador, o chamador deverá ter uma rotina de conclusão para limpo qualquer MDL se nem todos os MDLs foram investigados e bloqueados com êxito.
KSPROBE_PROBEANDLOCK Se o KSPROBE_ALLOCATEMDL estiver definido, indicará que a memória referenciada pelos MDLs para os buffers de fluxo deve ser investigada e bloqueada. Se o sinalizador de alocação MDL não estiver definido, esse sinalizador será ignorado mesmo que a alocação de MDL tenha ocorrido anteriormente. O método de investigação é determinado pelo tipo de IRP que está sendo passado. Para uma operação de gravação, IoReadAccess é usado. Para uma operação de leitura, IoWriteAccess é usado. Se o cliente que enviou os dados estiver usando o pool nãopagado, os MDLs apropriados serão inicializados em vez de investigação e bloqueio.
KSPROBE_SYSTEMADDRESS Recupera um endereço do sistema para cada MDL na cadeia para que o chamador não precise fazer isso em uma etapa separada. Isso será ignorado se o sinalizador de investigação e bloqueio não estiver definido, mesmo que os MDLs tenham sido investigados anteriormente.
KSPROBE_ALLOWFORMATCHANGE Para uma gravação Stream, permite que o sinalizador KSSTREAM_HEADER_OPTIONSF_TYPECHANGED seja definido no cabeçalho do fluxo. Isso implica que o cabeçalho do fluxo não tem comprimento estendido, mesmo que um tamanho de cabeçalho estendido tenha sido indicado. Além disso, pode haver apenas um cabeçalho de fluxo contido no IRP nesse caso. O buffer associado a esse cabeçalho contém o novo formato de dados. Para fluxos de dados de memória do sistema, o buffer não deve ter sido adquirido do alocador negociado, pois não faz parte do fluxo de dados.

Requisitos

Requisito Valor
Plataforma de Destino Universal
Cabeçalho ks.h (inclua Ks.h)
Biblioteca Ks.lib