Функция KsStreamIo (ks.h)

Функция KsStreamIo выполняет потоковое чтение или запись для указанного объекта файла. Функция пытается использовать FastIoDispatch , если это возможно, или создает запрос на чтение или запись к объекту устройства.

Синтаксис

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
);

Параметры

[in] FileObject

Указывает объект файла для выполнения операций ввода-вывода.

[in, optional] Event

При необходимости содержит событие для использования в вводе-выводе. Если ни один из них не передается, предполагается, что вызов выполняется в синхронном объекте файла, или вызывающий объект ожидает события файлового объекта, иначе он может быть выполнен асинхронно. Если используется и флаг KSSTREAM_SYNCHRONOUS не установлен, это должно быть событие, выделенное диспетчером объектов. Если вызывающий объект выполняет асинхронные операции ввода-вывода, ему необходимо либо дождаться события объекта файла, либо передать событие в этом параметре и дождаться его. Если этого не сделать, вызывающий объект не сможет узнать, когда ioStatusBlock был обновлен вызовом.

[in, optional] PortContext

При необходимости содержит сведения о контексте для порта завершения.

[in, optional] CompletionRoutine

При необходимости указывает на подпрограмму завершения для этого IRP.

[in, optional] CompletionContext

Если указан параметр CompletionRoutine , он предоставляет указатель контекста в обратном вызове процедуры завершения.

[in, optional] CompletionInvocationFlags

Задает флаги вызова, указывающие, когда вызывается подпрограмма завершения. Используемые значения см. в следующей таблице.

[out] IoStatusBlock

Расположение для возврата сведений о состоянии. Это всегда считается допустимым адресом, независимо от режима инициатора запроса. Значение должно оставаться действительным до тех пор, пока вызов не обновит состояние. Вызывающий объект должен выполнять синхронный ввод-вывод или ожидать события объекта файла или события, переданного в параметре Event, прежде чем разрешить этому адресу стать недействительным.

[in, out] StreamHeaders

Указывает список заголовков потоков. Предполагается, что этот адрес, а также адреса буферов данных были проверены на наличие соответствующего доступа. Клиенты режима ядра, отправляющие заголовки потоковой передачи, должны выделять заголовки из памяти NonPagedPool.

[in] Length

Указывает размер передаваемых объектов StreamHeaders .

[in] Flags

Задает различные флаги для ввода-вывода. Используемые значения см. в следующей таблице.

[in] RequestorMode

Указывает режим процессора для размещения в IRP, если его необходимо создать. Эта переменная также определяет, можно ли выполнить быстрый вызов ввода-вывода. Если режим инициатора запроса не является режимом ядра, но предыдущий режим — , то использовать быстрый ввод-вывод нельзя.

Возвращаемое значение

Функция KsStreamIo возвращает STATUS_SUCCESS в случае успешного выполнения, STATUS_PENDING, если действие находится в состоянии ожидания, или при неудачном выполнении возвращает ошибку ввода-вывода.

Комментарии

Следующие перечисленные значения используются для переменной CompletionInvocationFlags и имеют тип KSCOMPLETION_INVOCATION:

CompletionInvocationFlags	Описание
KsInvokeOnSuccess	Вызывает подпрограмму завершения при успешном выполнении.
KsInvokeOnError	Вызывает подпрограмму завершения при ошибке.
KsInvokeOnCancel	Вызывает подпрограмму завершения при отмене.

Для переменной Flags используются следующие определенные значения:

Flags	Описание
KSSTREAM_READ	Указывает, что требуется создать IOCTL_KS_STREAMREAD IRP. Это значение по умолчанию.
KSSTREAM_WRITE	Указывает, что требуется создать IOCTL_KS_STREAMWRITE IRP.
KSSTREAM_PAGED_DATA	Указывает, что данные доступны для страниц. Это значение по умолчанию, и его можно использовать в любое время.
KSSTREAM_NONPAGED_DATA	Указывает, что данные являются непагированные и могут использоваться в качестве повышения производительности.
KSSTREAM_SYNCHRONOUS	Указывает, что IRP является синхронным. Это означает, что если параметр Event передается, он не обрабатывается как событие диспетчера объектов и не ссылается или разыменовывается.

KSSTREAM_READ эквивалентен KSPROBE_STREAMREAD.

Аналогичным образом KSSTREAM_WRITE эквивалентна KSPROBE_STREAMWRITE.

Требования

Требование	Значение
Целевая платформа	Универсальное
Верхняя часть	ks.h (включая Ks.h)
Библиотека	Ks.lib