Функция NdisAllocatePacketPoolEx (ndis.h)

  • Статья

Примечание NDIS 5. X является нерекомендуемым и заменен NDIS 6. x. Сведения о разработке новых драйверов NDIS см. в статье Сетевые драйверы, начиная с Windows Vista. Сведения о переносе NDIS 5. x драйверы для NDIS 6. x, см. раздел Перенос драйверов NDIS 5.x в NDIS 6.0.

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

Синтаксис

void NdisAllocatePacketPoolEx(
  [out] PNDIS_STATUS Status,
  [out] PNDIS_HANDLE PoolHandle,
  [in]  UINT         NumberOfDescriptors,
  [in]  UINT         NumberOfOverflowDescriptors,
  [in]  UINT         ProtocolReservedLength
);

Параметры

[out] Status

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

[out] PoolHandle

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

[in] NumberOfDescriptors

Указывает количество дескрипторов пакетов, которые пул должен содержать для ожидаемого нормального использования. Максимальное значение NumberOfDescriptors , которое может быть выделено, равно 0xFFFF. Если предпринята попытка выделить больше, NdisAllocatePacketPoolEx возвращает состояние NDIS_STATUS_RESOURCES.

[in] NumberOfOverflowDescriptors

Указывает количество дескрипторов пакетов, зарезервированных для ситуации переполнения, то есть при использовании всех дескрипторов, указанных в NumberOfDescriptors . Если сумма этого параметра и NumberOfDescriptors превышает 0xFFFF, NdisAllocatePacketPoolEx уменьшает значение, указанное в качестве этого параметра, так что общее значение NumberOfDescriptors и NumberOfOverflowDescriptors равно 0xFFFF.

[in] ProtocolReservedLength

Указывает количество байтов, выделяемых для массива ProtocolReserved каждого дескриптора пакетов. Для дескрипторов пакетов, используемых в обозначениях получения, этот параметр имеет размер 4*(PVOID).

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

None

Remarks

В следующей таблице показаны возможные возвращаемые значения для этой функции.

Состояние Описание
NDIS_STATUS_SUCCESS Драйвер может выполнять вызовы к NdisAllocatePacket , когда ему требуются дескрипторы пакетов для указания до драйверов более высокого уровня или для отправки пакетов в драйверы более низкого уровня.
NDIS_STATUS_RESOURCES Попытка выделить пул пакетов завершилась сбоем, возможно, из-за нехватки памяти. Это не обязательно означает, что последующий вызов завершится ошибкой. Однако вызывающий объект может попытаться уменьшить числоDescriptors и немедленно вызвать его снова.

Успешный вызов NdisAllocatePacketPoolEx возвращает дескриптор пулу пакетов, который вызывающий объект должен сохранить. Обычно драйвер вызывает NdisAllocatePacket один или несколько раз с этим дескриптором, чтобы выделить набор дескрипторов пакетов.

NdisAllocatePacketPoolEx статически выделяет достаточно памяти для размещения количества дескрипторов пакетов, указанного в NumberOfDescriptors. Общее количество дескрипторов пакетов, которые могут быть выделены из пула с помощью вызовов NdisAllocatePacket , является меньшим из 0xFFFF или суммой дескрипторов NumberOfDescriptors и NumberOfOverflowDescriptors , изначально переданных в NdisAllocatePacketPoolEx. Дескрипторы переполнения выделяются динамически только в ситуации переполнения, то есть когда указанные дескрипторы NumberOfDescriptors уже выделены и все еще используются.

Сумма значений NumberOfDescriptors и NumberOfOverflowDescriptors — это эффективное ограничение на количество вызовов NdisAllocatePacket , прежде чем он должен вызвать NdisFreePacket , чтобы вернуть дескриптор пакета в свободный список для пула пакетов. Если дескриптор переполнения еще не выделен, NdisFreePacket возвращает дескриптор пакета в статически выделенный пул. Если один или несколько дескрипторов переполнения уже выделены, NdisFreePacket возвращает дескриптор пакетов в системную память, а не в пул.

Вызывающий объект NdisAllocatePacketPoolEx должен задать для NumberOfDescriptors количество дескрипторов пакетов, необходимое для ожидаемых нормальных нагрузок. Драйвер должен задать для NumberOfOverflowDescriptors число дополнительных дескрипторов, необходимых для обработки ожидаемых пиковых нагрузок. Если из пула выделено общее возможное количество дескрипторов пакетов (NumberOfDescriptors плюс NumberOfOverflowDescriptors), вызов NdisAllocatePacket возвращает NDIS_STATUS_RESOURCES.

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

Если драйверу больше не нужны дескрипторы пакетов, он вызывает [(nf-ndis-ndisfreepacketpool.md), чтобы освободить хранилище, выделенное с помощью NdisAllocatePacketPoolEx.

Версии ОС: Windows CE .NET 4.0 и более поздних версий.

Требования

Требование Значение
Заголовок ndis.h
Библиотека Ndis.lib
IRQL IRQL <= DISPATCH_LEVEL

См. также раздел