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

Статья
08/07/2023

Процессы функции ProtocolReceiveNetBufferLists получают указания от базовых драйверов.

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

Синтаксис

PROTOCOL_RECEIVE_NET_BUFFER_LISTS ProtocolReceiveNetBufferLists;

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

Параметры

[in] ProtocolBindingContext

Дескриптор области контекста, выделенной драйвером протокола для хранения сведений о состоянии привязки. Этот дескриптор был передан в NDIS в предыдущем вызове функции NdisOpenAdapterEx .

[in] NetBufferLists

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

[in] PortNumber

Номер порта, идентифицирующий порт адаптера мини-порта. Номер порта адаптера мини-порта по умолчанию равен нулю. Драйверы протокола, которые не используют порты адаптера miniport, должны игнорировать этот параметр.

[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 структуры сразу после возврата вызова ProtocolReceiveNetBufferLists .

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

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

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

None

Remarks

ProtocolReceiveNetBufferLists — это обязательная функция для драйверов протокола. NDIS вызывает ProtocolReceiveNetBufferLists после вызова связанного драйвера мини-порта Функция NdisMIndicateReceiveNetBufferLists . Вызов ProtocolReceiveNetBufferLists также может произойти в результате замыкания на себя.

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

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

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

В многопроцессорной системе эта функция может выполняться одновременно на нескольких процессорах. Применение защиты (например, использование спин-блокировок) к критически важным структурам данных, к которым обращается ProtocolReceiveNetBufferLists.

NDIS вызывает ProtocolReceiveNetBufferLists по адресу IRQL<= DISPATCH_LEVEL.

Примеры

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

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

PROTOCOL_RECEIVE_NET_BUFFER_LISTS MyReceiveNetBufferLists;

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

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

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

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

Требования

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