Функция NdisAllocateNetBufferAndNetBufferList (ndis/nblapi.h)

Статья
08/07/2023

Вызовите функцию NdisAllocateNetBufferAndNetBufferList , чтобы выделить и инициализировать структуру NET_BUFFER_LIST , которая инициализирована с предварительно выделенным NET_BUFFER структурой.

Синтаксис

NDIS_EXPORTED_ROUTINE NET_BUFFER_LIST * NdisAllocateNetBufferAndNetBufferList(
  [in]           NDIS_HANDLE          PoolHandle,
  [in]           USHORT               ContextSize,
  [in]           USHORT               ContextBackFill,
  [in, optional] __drv_aliasesMem MDL *MdlChain,
  [in]           ULONG                DataOffset,
  [in]           SIZE_T               DataLength
);

Параметры

[in] PoolHandle

Дескриптор пула структуры NET_BUFFER_LIST, который ранее был возвращен из Функция NdisAllocateNetBufferListPool . Элемент fAllocateNetBufferструктуры NET_BUFFER_LIST_POOL_PARAMETERS , который вызывающий объект передал в NdisAllocateNetBufferListPool , должен иметь значение TRUE , а для элемента DataSize — нулевое значение.

[in] ContextSize

Объем используемого пространства данных в структуре NET_BUFFER_LIST_CONTEXT для резервирования для вызывающего объекта. ContextSize должен быть кратным значению, определенному MEMORY_ALLOCATION_ALIGNMENT.

[in] ContextBackFill

Объем неиспользуемого пространства данных (пространства обратного заполнения), необходимого вызывающей стороне. NDIS добавляет это значение в ContextSize и выделяет дополнительное пространство. ContextBackFill должен быть кратным значению, определенному MEMORY_ALLOCATION_ALIGNMENT.

[in, optional] MdlChain

Указатель на цепочку MDL, используемую NDIS для инициализации предварительно размещенной структуры NET_BUFFER. MdlChain может иметь значение NULL.

[in] DataOffset

Начальное смещение в байтах от начала буфера до начала используемого пространства данных в цепочке MDL. Пространство данных перед этим смещением — это неиспользуемое пространство данных. Таким образом, это значение также представляет начальный объем доступного пространства обратного заполнения в цепочке MDL. Если MdlChain имеет значение NULL, DataOffset должен иметь значение 0.

[in] DataLength

Длина (в байтах) используемого пространства данных в цепочке MDL. Если MdlChain имеет значение NULL, DataLength должно иметь значение 0.

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

NdisAllocateNetBufferAndNetBufferList возвращает указатель на выделенную NET_BUFFER_LIST структуру. Структура NET_BUFFER_LIST включает структуру NET_BUFFER. Если выделение не удалось выполнить, этот указатель имеет значение NULL.

Структуры, которые выделяет функция NdisAllocateNetBufferAndNetBufferList , должны поступать из пула, включающего NET_BUFFER_LIST структуры, которые связаны с предварительно выделенными NET_BUFFER структурами. Чтобы создать такой пул, необходимо вызвать Функция NdisAllocateNetBufferListPool с элементом fAllocateNetBufferструктуры NET_BUFFER_LIST_POOL_PARAMETERSзначением TRUE, а элемент DataSize — равным нулю.

Обратите вниманиеNET_BUFFER и NET_BUFFER_LIST структуры должны быть выделены из буферного пула NDIS. Драйвер не должен выделять и инициализировать NET_BUFFER_LIST или NET_BUFFER структуру из частного пула памяти или стека.

Вызовите функцию NdisFreeNetBufferList , чтобы освободить структуру NET_BUFFER_LIST .

Предварительно размещенный NET_BUFFER можно использовать повторно, повторно инициализировав его в другой цепочке MDL, когда она владеет NET_BUFFER, но поля DataOffset, DataLength, CurrentMdl и CurrentMdlOffset в NET_BUFFER должны соответствовать новой цепочке MDL.

Например, если исходная цепочка MDL содержит XDataLength и YDataOffset, а CurrentMdl начинается со второго MDL (M) в исходной цепочке MDL, CurrentMdlOffset имеет значение Z. Затем поле MdlChain в NET_BUFFER_DATA должно указывать на новую цепочку MDL, содержащую X'DataLength и Y'DataOffset. Если CurrentMdl начинается с третьего MDL (M') в новой цепочке MDL, CurrentMdlOffset имеет значение Z', и для задания полей в NET_BUFFER необходимо использовать следующие макросы:

NET_BUFFER_FIRST_MDL(_NB) = New MDL chain;
NET_BUFFER_DATA_LENGTH(_NB) = X';
NET_BUFFER_DATA_OFFSET(_NB) = Y';
NET_BUFFER_CURRENT_MDL(_NB) = M';
NET_BUFFER_CURRENT_MDL_OFFSET(_NB) = Z';

Требования

Требование	Значение
Минимальная версия клиента	Поддерживается в NDIS 6.0 и более поздних версиях.
Целевая платформа	Универсальное
Верхняя часть	ndis/nblapi.h (включая ndis.h)
Библиотека	Ndis.lib
IRQL	<= DISPATCH_LEVEL
Правила соответствия DDI	Irql_NetBuffer_Function(ndis), NdisAllocateNetBufferList(ndis), NdisAllocateNetBufferList_InitFail(ndis)