Функция 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).
Возвращаемое значение
Никакой
Замечания
В следующей таблице показаны возможные возвращаемые значения для этой функции.
| Статус | Описание |
|---|---|
| NDIS_STATUS_SUCCESS | Драйвер может вызывать NdisAllocatePacket, когда ему нужны дескрипторы пакетов, чтобы сделать указания до драйверов более высокого уровня или отправлять пакеты в драйверы нижнего уровня. |
| NDIS_STATUS_RESOURCES | Попытка выделения пула пакетов завершилась ошибкой, возможно, из-за нехватки памяти. Этот возврат не обязательно означает, что последующий вызов завершится ошибкой. Однако вызывающий объект может попытаться уменьшить NumberOfDescriptors и снова вызвать его. |
Успешный вызов 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 |