Функция FwpsStreamInjectAsync0 (fwpsk.h)

Статья
08/07/2023

Функция FwpsStreamInjectAsync0 внедряет сегменты данных TCP в поток данных TCP.

ПримечаниеFwpsStreamInjectAsync0 — это определенная версия FwpsStreamInjectAsync. Дополнительные сведения см. в разделах Имена Version-Independent и Выбор конкретных версий Windows .

Синтаксис

NTSTATUS FwpsStreamInjectAsync0(
  [in]           HANDLE                injectionHandle,
  [in, optional] HANDLE                injectionContext,
  [in]           UINT32                flags,
  [in]           UINT64                flowId,
  [in]           UINT32                calloutId,
  [in]           UINT16                layerId,
  [in]           UINT32                streamFlags,
  [in, out]      NET_BUFFER_LIST       *netBufferList,
  [in]           SIZE_T                dataLength,
  [in]           FWPS_INJECT_COMPLETE0 completionFn,
  [in, optional] HANDLE                completionContext
);

Параметры

[in] injectionHandle

Дескриптор внедрения, созданный ранее при вызовеФункция FwpsInjectionHandleCreate0.

[in, optional] injectionContext

Необязательный дескриптор контекста внедрения.

[in] flags

Зарезервировано. Драйверы выносок должны задать для этого параметра нулевое значение.

[in] flowId

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

[in] calloutId

Идентификатор времени выполнения для выноски в подсистеме фильтров. Этот идентификатор возвращался, когда драйвер выноски вызывал функции FwpsCalloutRegister0 или FwpsCalloutRegister1 для регистрации выноски в подсистеме фильтров.

[in] layerId

Идентификатор времени выполнения для уровня фильтрации, на котором обрабатывается поток данных. Это значение должно быть FWPS_LAYER_STREAM_V4 или FWPS_LAYER_STREAM_V6. Идентификатор времени выполнения для слоя, на котором обрабатывается поток данных, предоставляется выноске в элементе layerIdструктуры FWPS_INCOMING_VALUES0 , переданной подсистемой фильтров функции callout classifyFn драйвера выноски.

[in] streamFlags

Флаги, указывающие характеристики потока данных, в который необходимо внедрить данные.

При внедрении данных в поток входящих данных драйвер выноски задает один или несколько из следующих флагов:

FWPS_STREAM_FLAG_RECEIVE

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

FWPS_STREAM_FLAG_RECEIVE_DISCONNECT

Указывает, что флаг FIN должен быть установлен в заголовке TCP для данных, внедряемых в поток входящих данных.

Примечание Если этот флаг установлен, необходимо также задать флаг FWPS_STREAM_FLAG_RECEIVE , иначе будет возвращена STATUS_FWP_INVALID_PARAMETER .

FWPS_STREAM_FLAG_RECEIVE_EXPEDITED

Указывает, что данные, внедряемые во входящий поток данных, являются высокоприоритетными, внеполосными данными.

FWPS_STREAM_FLAG_RECEIVE_PUSH

Указывает, что входящие данные поступили с флагом PUSH, установленным в заголовке TCP, который указывает, что отправитель запрашивает немедленную передачу данных. Если этот флаг не установлен, могут возникнуть нежелательные задержки при передаче данных. Этот флаг доступен начиная с Windows Vista с пакетом обновления 1 (SP1).

При внедрении данных в исходящий поток данных драйвер выноски задает один или несколько из следующих флагов:

FWPS_STREAM_FLAG_SEND

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

FWPS_STREAM_FLAG_SEND_EXPEDITED

Указывает, что данные, внедряемые в исходящий поток данных, являются высокоприоритетными, внеполосными данными.

FWPS_STREAM_FLAG_SEND_NODELAY

Указывает, что драйвер выноски запрашивает отсутствие буферизации данных, внедряемых в поток исходящих данных.

FWPS_STREAM_FLAG_SEND_DISCONNECT

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

Примечание Если этот флаг установлен, необходимо также задать флаг FWPS_STREAM_FLAG_SEND , иначе будет возвращена STATUS_FWP_INVALID_PARAMETER .

[in, out] netBufferList

Указатель на структуру NET_BUFFER_LIST , описывающую данные, которые внедряются в поток данных. Драйвер выноски выделяет структуру NET_BUFFER_LIST для внедрения данных в поток данных путем вызова Функции FwpsAllocateCloneNetBufferList0, FwpsAllocateNetBufferAndNetBufferList0 или FwpsCloneStreamData0 . Структура NET_BUFFER_LIST может описывать цепочку списков сетевых буферов. Если параметр streamFlags имеет значение FWPS_STREAM_FLAG_RECEIVE_DISCONNECT или FWPS_STREAM_FLAG_SEND_DISCONNECT, netBufferList может иметь значение NULL.

[in] dataLength

Количество байтов данных, внедряемых в поток данных.

[in] completionFn

Указатель на функцию выноски завершенияFn , предоставляемую драйвером выноски. Модуль фильтров вызывает эту функцию после внедрения в сетевой стек данных пакетов, описанных параметром netBufferList .

Если параметр netBufferList описывает цепочку NET_BUFFER_LIST , метод completionFn будет вызываться один раз для каждого NET_BUFFER_LIST в цепочке.

Если параметр netBufferList имеет значение NULL , а параметр streamFlags имеет значение FWPS_STREAM_FLAG_RECEIVE_DISCONNECT или FWPS_STREAM_FLAG_SEND_DISCONNECT задан, функция completionFn вызываться не будет.

Этот параметр является обязательным и не может иметь значение NULL. Если значение равно NULL, возвращается STATUS_FWP_NULL_POINTER .

[in, optional] completionContext

Указатель на предоставленный драйвером выноски контекст, который передается в функцию выноски, на которую указывает параметр completionFn . Этот параметр является необязательным и может иметь значение NULL.

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

FwpsStreamInjectAsync0 выполняет код NTSTATUS, например один из следующих.

Код возврата	Описание
STATUS_SUCCESS	Внедрение в поток данных было успешно инициировано. Модуль фильтрации вызовет функцию завершения, указанную при выделении структуры NET_BUFFER_LIST после завершения внедрения данных в поток данных подсистемой фильтров.
STATUS_FWP_TCPIP_NOT_READY	Сетевой стек TCP/IP не готов принимать потоковые данные.
STATUS_FWP_INJECT_HANDLE_CLOSING	Маркер внедрения закрывается.
Другие коды состояния	Произошла ошибка.

Драйвер выноски вызывает функцию FwpsStreamInjectAsync0 из функции выноски classifyFn выноски для внедрения новых или клонированных данных в поток данных, который обрабатывается в данный момент. Драйвер выноски может вызывать функцию FwpsStreamInjectAsync0, только если обрабатывает поток данных на уровне потока.

Драйвер выноски также может вызывать функцию FwpsStreamInjectAsync0 извне функции выноски classifyFn выноски для внедрения данных в отложенный поток данных. Поток данных откладывается, когда функция выноски classifyFn в выноске задает член streamAction объекта FWPS_STREAM_CALLOUT_IO_PACKET0 структуру для FWPS_STREAM_ACTION_DEFER.

Кроме того, драйвер выноски может вызывать функцию FwpsStreamInjectAsync0 извне функции выноски classifyFn выноски, чтобы внедрить данные в поток данных после того, как будет выполнено указание FIN.

Кроме того, драйвер выноски может вызывать функцию FwpsStreamInjectAsync0 из контекста произвольного потока за пределами функции callout classifyFn выноски, если драйвер выноски клонирует и блокирует все данные, указанные для внеполосной обработки. Драйвер выноски, который перенаправляет все указанные данные в пользовательский режим для обработки, может вызвать функцию FwpsStreamInjectAsync0 таким образом.

Выноска может создать сегмент данных, сначала клонировав его с помощью вызова функции FwpsCloneStreamData0 , а затем блокируя сегмент данных, задав FWP_ACTION_BLOCK в элементе actionType структуры FWPS_CLASSIFY_OUT0 .

Внедренные потоковые данные не будут повторно использоваться в выноске, но будут доступны для потоковых выносок из подслоев с более низким весом.

Если возвращаемое значение не STATUS_SUCCESS, функция завершения вызываться не будет. В этом случае список сетевых буферов, на который указывает netBufferList , должен быть освобожден вызовом FwpsFreeNetBufferList0 или FwpsFreeCloneNetBufferList0.

Требования

Требование	Значение
Минимальная версия клиента	Доступно начиная с Windows Vista.
Целевая платформа	Универсальное
Верхняя часть	fwpsk.h (включая Fwpsk.h)
Библиотека	Fwpkclnt.lib
IRQL	<= DISPATCH_LEVEL