Função KsStreamIo (ks.h)

Artigo
02/07/2025

A função KsStreamIo executa uma leitura ou gravação de fluxo no objeto de arquivo especificado. A função tenta usar FastIoDispatch, se possível, ou gera uma solicitação de leitura ou gravação no objeto do dispositivo.

Sintaxe

KSDDKAPI NTSTATUS KsStreamIo(
  [in]           PFILE_OBJECT            FileObject,
  [in, optional] PKEVENT                 Event,
  [in, optional] PVOID                   PortContext,
  [in, optional] PIO_COMPLETION_ROUTINE  CompletionRoutine,
  [in, optional] PVOID                   CompletionContext,
  [in, optional] KSCOMPLETION_INVOCATION CompletionInvocationFlags,
  [out]          PIO_STATUS_BLOCK        IoStatusBlock,
  [in, out]      PVOID                   StreamHeaders,
  [in]           ULONG                   Length,
  [in]           ULONG                   Flags,
  [in]           KPROCESSOR_MODE         RequestorMode
);

Parâmetros

[in] FileObject

Especifica o objeto de arquivo no qual executar a E/S.

[in, optional] Event

Opcionalmente, contém o evento a ser usado na E/S. Se nenhum for passado, a chamada será considerada em um objeto de arquivo síncrono ou o chamador está aguardando o evento do objeto de arquivo ou então ele pode ser concluído de forma assíncrona. Se usado e o sinalizador KSSTREAM_SYNCHRONOUS não estiver definido, esse deve ser um evento alocado pelo gerenciador de objetos. Se o chamador estiver executando E/S assíncrona, ele deverá aguardar o evento do objeto de arquivo ou passar um evento nesse parâmetro e aguardá-lo. Se isso não for feito, não haverá como o chamador saber quando o IoStatusBlock foi atualizado pela chamada.

[in, optional] PortContext

Opcionalmente, contém informações de contexto para uma porta de conclusão.

[in, optional] CompletionRoutine

Opcionalmente, aponta para uma rotina de conclusão para este IRP.

[in, optional] CompletionContext

Se de CompletionRoutine for especificado, isso fornecerá um ponteiro de contexto no retorno de chamada de rotina de conclusão.

[in, optional] CompletionInvocationFlags

Especifica os sinalizadores de invocação que especificam quando a rotina de conclusão é invocada. Consulte a tabela a seguir para obter os valores usados.

[out] IoStatusBlock

Local para retornar as informações de status. Isso sempre é considerado um endereço válido, independentemente do modo solicitante. O valor deve permanecer válido até que a chamada tenha atualizado o status. O chamador deve executar E/S síncrona ou aguardar o evento do objeto de arquivo ou um evento passado no parâmetro Event antes de permitir que esse endereço se torne inválido.

[in, out] StreamHeaders

Especifica a lista de cabeçalhos de fluxo. Supõe-se que esse endereço, bem como os endereços dos buffers de dados, tenham sido investigados quanto ao acesso apropriado. Os clientes do modo kernel que enviarem cabeçalhos de streaming devem alocar os cabeçalhos da memória NonPagedPool.

[in] Length

Especifica o tamanho do streamHeaders passado.

[in] Flags

Especifica vários sinalizadores para a E/S. Consulte a tabela a seguir para obter os valores usados.

[in] RequestorMode

Indica o modo de processador a ser colocado no IRP se for necessário gerar um. Essa variável também determina se uma chamada de E/S rápida pode ser executada. Se o modo solicitante não for o modo kernel, mas o modo anterior for, a E/S rápida não poderá ser usada.

Valor de retorno

A função KsStreamIo retornará STATUS_SUCCESS se tiver êxito, STATUS_PENDING se a ação estiver pendente ou se não tiver êxito, retornará um erro de E/S.

Observações

Os seguintes valores enumerados são usados para a variável CompletionInvocationFlags e são do tipo KSCOMPLETION_INVOCATION:

CompletionInvocationFlags	Descrição
KsInvokeOnSuccess	Invoca a rotina de conclusão com êxito.
KsInvokeOnError	Invoca a rotina de conclusão por erro.
KsInvokeOnCancel	Invoca a rotina de conclusão no cancelamento.

Os seguintes valores definidos são usados para a variável sinalizadores de:

sinalizadores	Descrição
KSSTREAM_READ	Especifica que um IRP IOCTL_KS_STREAMREAD deve ser criado. Esse é o padrão.
KSSTREAM_WRITE	Especifica que um IRP IOCTL_KS_STREAMWRITE deve ser criado.
KSSTREAM_PAGED_DATA	Especifica que os dados podem ser pagináveis. Esse é o padrão e pode ser usado o tempo todo.
KSSTREAM_NONPAGED_DATA	Especifica que os dados não sãopagados e podem ser usados como um aprimoramento de desempenho.
KSSTREAM_SYNCHRONOUS	Especifica que o IRP é síncrono. Isso significa que, se o parâmetro Event for passado, ele não será tratado como um evento do gerenciador de objetos e não será referenciado ou desreferenciado.

KSSTREAM_READ é equivalente a KSPROBE_STREAMREAD.

Da mesma forma, KSSTREAM_WRITE é equivalente a KSPROBE_STREAMWRITE.

Requisitos

Requisito	Valor
da Plataforma de Destino	Universal
cabeçalho	ks.h (incluir Ks.h)
biblioteca	Ks.lib

Partilhar via