функция обратного вызова FILTER_RECEIVE_NET_BUFFER_LISTS (ndis.h)

Статья
08/07/2023

NDIS вызывает функцию FilterReceiveNetBufferLists , чтобы запросить драйвер фильтра для обработки указания получения.

Примечание Функцию необходимо объявить с помощью типа FILTER_RECEIVE_NET_BUFFER_LISTS . Дополнительные сведения см. в следующем разделе Примеры.

Синтаксис

FILTER_RECEIVE_NET_BUFFER_LISTS FilterReceiveNetBufferLists;

void FilterReceiveNetBufferLists(
  [in] NDIS_HANDLE FilterModuleContext,
  [in] PNET_BUFFER_LIST NetBufferLists,
  [in] NDIS_PORT_NUMBER PortNumber,
  [in] ULONG NumberOfNetBufferLists,
  [in] ULONG ReceiveFlags
)
{...}

Параметры

[in] FilterModuleContext

Дескриптор области контекста для модуля фильтра. Драйвер фильтра создал и инициализировал эту область контекста в функции FilterAttach .

[in] NetBufferLists

Связанный список NET_BUFFER_LIST структур, выделенных базовыми драйверами. Каждая NET_BUFFER_LIST структура содержит одну NET_BUFFER структуру.

[in] PortNumber

Номер порта, идентифицирующий порт адаптера мини-порта. Номера портов адаптера мини-порта назначаются путем вызова функции NdisMAllocatePort . Нулевое значение определяет порт адаптера минипорта по умолчанию.

[in] NumberOfNetBufferLists

Количество NET_BUFFER_LIST структур, которые находятся в связанном списке структур в NetBufferLists .

[in] ReceiveFlags

Флаги, определяющие атрибуты для указания получения. Флаги можно объединить с операцией OR. Чтобы очистить все флаги, установите для этого элемента нулевое значение. Эта функция поддерживает следующие флаги:

NDIS_RECEIVE_FLAGS_DISPATCH_LEVEL

Указывает, что текущий irQL DISPATCH_LEVEL. Дополнительные сведения об этом флаге см. в разделе Dispatch IRQL Tracking.

NDIS_RECEIVE_FLAGS_RESOURCES

Указывает, что NDIS освобождает права владения NET_BUFFER_LIST структурами и любыми присоединенными NET_BUFFER структурами сразу после возврата метода FilterReceiveNetBufferLists .

NDIS_RECEIVE_FLAGS_SINGLE_ETHER_TYPE

Указывает, что все структуры NET_BUFFER_LIST в списке в NetBufferLists имеют одинаковый тип протокола (EtherType).

NDIS_RECEIVE_FLAGS_SINGLE_VLAN

Указывает, что все структуры NET_BUFFER_LIST в списке в NetBufferLists принадлежат одной виртуальной локальной сети.

NDIS_RECEIVE_FLAGS_PERFECT_FILTERED

Указывает, что все структуры NET_BUFFER_LIST в списке в NetBufferLists содержат только данные, соответствующие фильтру пакетов и списку адресов многоадресной рассылки, назначенным адаптеру мини-порта.

NDIS_RECEIVE_FLAGS_SINGLE_QUEUE

Указывает, что все структуры NET_BUFFER_LIST в списке в NetBufferLists принадлежат к одной очереди виртуальных машин. Драйвер мини-порта должен установить этот флаг для всех указаний получения в очереди, если флаг NDIS_RECEIVE_QUEUE_PARAMETERS_PER_QUEUE_RECEIVE_INDICATION установлен в элементе Flags NDIS_RECEIVE_QUEUE_PARAMETERS структуру при выделении очереди.

NDIS_RECEIVE_FLAGS_SHARED_MEMORY_INFO_VALID

Указывает, что все структуры NET_BUFFER_LIST в списке в NetBufferLists содержат допустимые сведения о общей памяти. Если этот флаг установлен для полученного NET_BUFFER_LIST, NDIS обрабатывает сведения об общей памяти как допустимые. Если этот флаг не задан, NDIS и драйверы игнорируют сведения об общей памяти. Например, промежуточные драйверы, которые изменяют данные пакета, могут использовать этот флаг для определения необходимости копирования данных. Драйверы мини-порта могут использовать флаг , чтобы определить, как освободить память, связанную с очередью виртуальных машин, при удалении очереди.

NDIS_RECEIVE_FLAGS_MORE_NBLS

Зарезервировано.

NDIS_RECEIVE_FLAGS_SWITCH_SINGLE_SOURCE

Если этот флаг установлен, все пакеты в связанном списке NET_BUFFER_LIST структур поступили из одного порта источника расширяемого коммутатора Hyper-V.

Дополнительные сведения см. в статье Флаги отправки и получения расширяемого коммутатора Hyper-V.

Примечание Если каждый пакет в связанном списке NET_BUFFER_LIST структур использует один и тот же исходный порт, расширение должно установить флаг NDIS_RETURN_FLAGS_SWITCH_SINGLE_SOURCE в параметре ReturnFlagsобъекта FilterReturnNetBufferLists по завершении запроса на получение. Расширение должно установить этот флаг в параметре ReturnFlags , если оно вызывает NdisFReturnNetBufferLists для возврата пакетов, которые не были получены или клонироваться.

NDIS_RECEIVE_FLAGS_SWITCH_DESTINATION_GROUP

Если этот флаг установлен, все пакеты в связанном списке NET_BUFFER_LIST структур будут перенаправляются на один и тот же порт назначения расширяемого коммутатора.

Дополнительные сведения см. в статье Флаги отправки и получения расширяемого коммутатора Hyper-V.

Примечание Если каждый пакет в связанном списке NET_BUFFER_LIST структур использует одни и те же порты назначения, расширение должно установить флаг NDIS_RECEIVE_FLAGS_SWITCH_DESTINATION_GROUP в параметре ReturnFlagsобъекта FilterReturnNetBufferLists по завершении запроса на получение. Расширение должно установить этот флаг в параметре ReturnFlags , если оно вызывает NdisFReturnNetBufferLists для возврата пакетов, которые не были получены или клонироваться.

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

None

Remarks

FilterReceiveNetBufferLists — это необязательная функция. Если драйвер фильтра не фильтрует признаки получения, он может задать точку входа для этой функции значение NULL при вызове Функция NdisFRegisterFilterDriver .

Примечание Драйвер фильтра, предоставляющий функцию FilterReceiveNetBufferLists , должен предоставлять функцию FilterStatus .

Драйвер фильтра может вызывать функцию NdisSetOptionalHandlers из функции FilterSetModuleOptions , чтобы указать функцию FilterReceiveNetBufferLists для модуля фильтра.

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

Если драйвер фильтра не указал функцию FilterReceiveNetBufferLists , NDIS вызывает следующий драйвер фильтра более высокого уровня в стеке, который указал функцию FilterReceiveNetBufferLists . Если такого драйвера фильтра нет, NDIS вызывает слишком скользяучий драйвер Функция ProtocolReceiveNetBufferLists .

Если флаг NDIS_RECEIVE_FLAGS_RESOURCES в параметре ReceiveFlags не задан, драйвер фильтра сохраняет право собственности на структуры NET_BUFFER_LIST , пока не вызовет Функция NdisFReturnNetBufferLists .

Если флаг NDIS_RECEIVE_FLAGS_RESOURCES в параметре ReceiveFlags установлен, драйвер фильтра не может сохранить NET_BUFFER_LIST структуру и связанные ресурсы, выделенные базовым драйвером. Этот флаг может указывать на то, что базовый драйвер работает с нехваткой ресурсов получения. Функция FilterReceiveNetBufferLists должна возвращать как можно быстрее. Перед возвратом функция FilterReceiveNetBufferLists может скопировать полученные данные в хранилище, выделенное драйвером фильтра, или передать буфер, вызвав Функция NdisFIndicateReceiveNetBufferLists .

Примечание Если установлен флаг NDIS_RECEIVE_FLAGS_RESOURCES , драйвер фильтра должен сохранить исходный набор NET_BUFFER_LIST структур в связанном списке. Например, если этот флаг установлен, драйвер может обработать структуры и указать их в стеке по одному, но перед возвратом функции ему необходимо восстановить исходный связанный список.

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

Передайте буфер следующему драйверу с превышением, вызвав Функция NdisFIndicateReceiveNetBufferLists .
Драйвер может изменить содержимое буфера перед вызовом NdisFIndicateReceiveNetBufferLists.

Драйвер может изменить параметр флага NDIS_RECEIVE_FLAGS_RESOURCES , переданный NDIS в FilterReceiveNetBufferLists , или просто передать его в NdisFIndicateReceiveNetBufferLists.
Удалите буфер. Если NDIS очистил флаг NDIS_RECEIVE_FLAGS_RESOURCES , вызовите функцию NdisFReturnNetBufferLists , чтобы удалить буфер. Если NDIS задает флаг NDIS_RECEIVE_FLAGS_RESOURCES , не предпринимать никаких действий и возвращаться из FilterReceiveNetBufferLists , чтобы удалить буфер.
Помещайте буфер в локальную структуру данных для последующей обработки. Если NDIS задает флаг NDIS_RECEIVE_FLAGS_RESOURCESFilterReceiveNetBufferLists, драйвер фильтра должен создать копию перед возвратом из FilterReceiveNetBufferLists.
Скопируйте буфер и создайте указание получения с копией. Указание получения похоже на индикатор получения, инициированный драйвером фильтра. В этом случае драйвер должен вернуть исходный буфер в базовый драйвер.

Если драйвер фильтра вызвал NdisFIndicateReceiveNetBufferLists и не установил флаг NDIS_RECEIVE_FLAGS_RESOURCES , NDIS вызывает Функция FilterReturnNetBufferLists для модуля фильтра. В функции FilterReturnNetBufferLists драйвер фильтра отменяет операции, выполненные с буфером в пути указания получения.

Если модуль фильтра находится в состоянии Приостановлено , драйвер фильтра не должен указывать на получение для этого модуля фильтра. Драйвер фильтра не должен передавать созданные буферы в NdisFIndicateReceiveNetBufferLists. Однако драйвер может передать сигнал получения от базового драйвера.

NDIS вызывает FilterReceiveNetBufferLists в IRQL <= DISPATCH_LEVEL.

Примеры

Чтобы определить функцию FilterReceiveNetBufferLists , необходимо сначала предоставить объявление функции, определяющее тип определяемой функции. Windows предоставляет набор типов функций для драйверов. Объявление функции с помощью типов функций помогает анализу кода для драйверов, средству проверки статических драйверов (SDV) и другим средствам проверки находить ошибки, и это требование для написания драйверов для операционной системы Windows.

Например, чтобы определить функцию FilterReceiveNetBufferLists с именем MyReceiveNetBufferLists, используйте тип FILTER_RECEIVE_NET_BUFFER_LISTS , как показано в следующем примере кода:

FILTER_RECEIVE_NET_BUFFER_LISTS MyReceiveNetBufferLists;

Затем реализуйте функцию следующим образом:

_Use_decl_annotations_
VOID
 MyReceiveNetBufferLists(
    NDIS_HANDLE  FilterModuleContext,
    PNET_BUFFER_LIST  NetBufferLists,
    NDIS_PORT_NUMBER  PortNumber,
    ULONG  NumberOfNetBufferLists,
    ULONG  ReceiveFlags
    )
  {...}

Тип функции FILTER_RECEIVE_NET_BUFFER_LISTS определен в файле заголовка Ndis.h. Чтобы более точно определить ошибки при запуске средств анализа кода, не забудьте добавить заметку Use_decl_annotations в определение функции. Заметка Use_decl_annotations гарантирует использование заметок, применяемых к типу функции FILTER_RECEIVE_NET_BUFFER_LISTS в файле заголовка. Дополнительные сведения о требованиях к объявлениям функций см. в статье Объявление функций с помощью типов ролей функций для драйверов NDIS.

Сведения о Use_decl_annotations см. в статье Поведение функции с заметками.

Требования

Требование	Значение
Минимальная версия клиента	Поддерживается в NDIS 6.0 и более поздних версиях.
Целевая платформа	Windows
Header	ndis.h (включая Ndis.h)
IRQL	<= DISPATCH_LEVEL