NdisAllocatePacketPoolEx-Funktion (ndis.h)

Artikel
08/07/2023

Hinweis NDIS 5. x ist veraltet und wird durch NDIS 6 ersetzt. x. Informationen zur Entwicklung neuer NDIS-Treiber finden Sie unter Netzwerktreiber ab Windows Vista. Informationen zum Portieren von NDIS 5. x Treiber für NDIS 6. x, siehe Portieren von NDIS 5.x-Treibern zu NDIS 6.0.

Diese Funktion weist einen Speicherblock für einen Pool von Paketdeskriptoren zu und initialisiert diesen.

Syntax

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

Parameter

[out] Status

Verweist auf eine vom Aufrufer bereitgestellte Variable, in der diese Funktion den status der Paketpoolzuordnung zurückgibt.

[out] PoolHandle

Verweist auf eine vom Aufrufer bereitgestellte Variable, in der diese Funktion ein Handle an den Paketpool zurückgibt. Dieses Handle ist ein erforderlicher Parameter für die NdisXXX-Paketfunktionen, die der Treiber anschließend aufruft.

[in] NumberOfDescriptors

Gibt die Anzahl der Paketdeskriptoren an, die der Pool für die erwartete normale Verwendung enthalten soll. Die maximalen NumberOfDescriptors , die zugeordnet werden können, sind 0xFFFF. Wenn versucht wird, mehr zuzuweisen, gibt NdisAllocatePacketPoolEx den Status NDIS_STATUS_RESOURCES zurück.

[in] NumberOfOverflowDescriptors

Gibt die Anzahl von Paketdeskriptoren an, die für eine Überlaufsituation reserviert sind, d. h. wenn alle von NumberOfDescriptors angegebenen Deskriptoren verwendet werden. Wenn die Summe dieses Parameters und numberOfDescriptors 0xFFFF überschreitet, reduziert NdisAllocatePacketPoolEx den als diesen Parameter angegebenen Wert, sodass die Gesamtanzahl von NumberOfDescriptors und NumberOfOverflowDescriptors gleich 0xFFFF.

[in] ProtocolReservedLength

Gibt die Anzahl der Bytes an, die für das ProtocolReserved-Array der einzelnen Paketdeskriptoren zugewiesen werden sollen. Für Paketdeskriptoren, die in Empfangsanzeigen verwendet werden sollen, ist dieser Parameter 4*Size of (PVOID).

Rückgabewert

Keine

Bemerkungen

Die folgende Tabelle zeigt die möglichen Rückgabewerte für diese Funktion.

Status	BESCHREIBUNG
NDIS_STATUS_SUCCESS	Der Treiber kann Aufrufe an NdisAllocatePacket tätigen, wenn paketdeskriptoren benötigt werden, um Hinweise auf höhere Treiber zu machen oder Pakete an Treiber niedrigerer Ebene zu senden.
NDIS_STATUS_RESOURCES	Der Versuch, den Paketpool zuzuweisen, ist möglicherweise aufgrund eines Mangels an Arbeitsspeicher fehlgeschlagen. Diese Rückgabe bedeutet nicht unbedingt, dass bei einem nachfolgenden Aufruf ein Fehler auftritt. Der Aufrufer versucht jedoch möglicherweise, die NumberOfDescriptors zu verringern und sofort erneut aufzurufen.

Ein erfolgreicher Aufruf von NdisAllocatePacketPoolEx gibt ein Handle an den Paketpool zurück, den der Aufrufer speichern soll. In der Regel ruft der Treiber als Nächstes NdisAllocatePacket ein oder mehrere Male mit diesem Handle auf, um eine Reihe von Paketdeskriptoren zuzuweisen.

NdisAllocatePacketPoolEx weist statisch nur genügend Arbeitsspeicher zu, um die Von NumberOfDescriptors angegebene Anzahl von Paketdeskriptoren aufzunehmen. Die Gesamtanzahl der Paketdeskriptoren, die aus dem Pool mit Aufrufen von NdisAllocatePacket zugeordnet werden können, ist die geringere Anzahl von 0xFFFF oder die Summe von NumberOfDescriptors und NumberOfOverflowDescriptors , die ursprünglich an NdisAllocatePacketPoolEx übergeben wurden. Überlaufdeskriptoren werden nur während einer Überlaufsituation dynamisch zugeordnet, d. h. wenn die angegebenen NumberOfDescriptors bereits zugewiesen wurden und weiterhin verwendet werden.

Die Summe von NumberOfDescriptors und NumberOfOverflowDescriptors ist das effektive Limit dafür, wie oft der Treiber NdisAllocatePacket aufrufen kann, bevor er NdisFreePacket aufrufen muss, um einen Paketdeskriptor in die freie Liste für den Paketpool zurückzugeben. Wenn noch kein Überlaufdeskriptor zugewiesen wurde, gibt NdisFreePacket den Paketdeskriptor an den statisch zugeordneten Pool zurück. Wenn mindestens ein Überlaufdeskriptor bereits zugewiesen wurde, gibt NdisFreePacket den Paketdeskriptor an den Systemspeicher zurück , nicht an den Pool.

Der Aufrufer von NdisAllocatePacketPoolEx sollte NumberOfDescriptors auf die Anzahl der Paketdeskriptoren festlegen, die für erwartete normale Ladevorgänge erforderlich sind. Der Treiber sollte NumberOfOverflowDescriptors auf die Anzahl zusätzlicher Deskriptoren festlegen, die erforderlich sind, um erwartete Spitzenlasten zu bewältigen. Wenn die gesamt mögliche Anzahl von Paketdeskriptoren (NumberOfDescriptors und NumberOfOverflowDescriptors) aus dem Pool zugewiesen wurde, gibt ein Aufruf von NdisAllocatePacket NDIS_STATUS_RESOURCES zurück.

Wenn gesendete oder angegebene Pakete an den Zuweisungstreiber zurückgegeben werden, kann jeder Paketdeskriptor wiederverwendet werden, nachdem NdisReinitializePacket aufgerufen und mit einer Kette von Pufferdeskriptoren erneut eingerichtet wurde, oder der Treiber kann NdisFreePacket aufrufen, um dieses Paket in die free-Liste zurückzugeben. Das erneute Initialisieren und Wiederverwenden von Paketen, die aus dem Paketpool zugewiesen wurden, ist viel schneller als das Freigeben und anschließende erneute Zuordnen dieser Pakete. Bevor ein Treiber NdisReinitializePacket mit einem Paketdeskriptor aufruft, muss er die Zeiger auf Pufferdeskriptoren speichern, die mit dem Paketdeskriptor verkettet sind, da NdisReinitializePacket den Kopf der Pufferkette auf NULL festlegt.

Wenn ein Treiber keine Paketdeskriptoren mehr benötigt, ruft er [(nf-ndis-ndisfreepacketpool.md) auf, um den Speicher freizugeben, den er NdisAllocatePacketPoolEx zugeordnet hat.

Betriebssystemversionen: Windows CE .NET 4.0 und höher.

Anforderungen

Anforderung	Wert
Header	ndis.h
Bibliothek	Ndis.lib
IRQL	IRQL <= DISPATCH_LEVEL

Freigeben über