Funzione NdisAllocatePacketPoolEx (ndis.h)
Nota NDIS 5. x è stato deprecato e sostituito da NDIS 6. x. Per i nuovi driver NDIS, vedere Driver di rete a partire da Windows Vista. Per informazioni sulla conversione di NDIS 5. driver x a NDIS 6. x, vedere Porting NDIS 5.x Drivers to NDIS 6.0.
Questa funzione alloca e inizializza un blocco di archiviazione per un pool di descrittori di pacchetti.
Sintassi
void NdisAllocatePacketPoolEx(
[out] PNDIS_STATUS Status,
[out] PNDIS_HANDLE PoolHandle,
[in] UINT NumberOfDescriptors,
[in] UINT NumberOfOverflowDescriptors,
[in] UINT ProtocolReservedLength
);
Parametri
[out] Status
Punta a una variabile fornita dal chiamante in cui questa funzione restituisce lo stato dell'allocazione del pool di pacchetti.
[out] PoolHandle
Punta a una variabile fornita dal chiamante in cui questa funzione restituisce un handle al pool di pacchetti. Questo handle è un parametro obbligatorio per le funzioni di NdisXXXPacket chiamate successivamente dal driver.
[in] NumberOfDescriptors
Specifica il numero di descrittori di pacchetti che il pool deve contenere per un uso normale previsto. Il numero massimo di NumberOfDescriptor che può essere allocato è 0xFFFF. Se si tenta di allocare più di questo valore, NdisAllocatePacketPoolEx restituisce un stato di NDIS_STATUS_RESOURCES.
[in] NumberOfOverflowDescriptors
Specifica il numero di descrittori di pacchetti riservati per una situazione di overflow, ovvero quando sono in uso tutti i descrittori specificati da NumberOfDescriptors. Se la somma di questo parametro e NumberOfDescriptors supera 0xFFFF, NdisAllocatePacketPoolEx riduce il valore fornito come parametro in modo che il totale NumberOfDescriptors e NumberOfOverflowDescriptors sia uguale a 0xFFFF.
[in] ProtocolReservedLength
Specifica il numero di byte da allocare per la matrice di ProtocolReserved di ogni descrittore di pacchetti. Per i descrittori di pacchetti da usare nelle indicazioni di ricezione, questo parametro è pari a 4*dimensioni (PVOID).
Valore restituito
Nessuno
Osservazioni
Nella tabella seguente vengono illustrati i possibili valori restituiti per questa funzione.
| Stato | Descrizione |
|---|---|
| NDIS_STATUS_SUCCESS | Il driver può effettuare chiamate a NdisAllocatePacket quando necessita di descrittori di pacchetti per fornire indicazioni fino a driver di livello superiore o per inviare pacchetti a driver di livello inferiore. |
| NDIS_STATUS_RESOURCES | Il tentativo di allocare il pool di pacchetti non è riuscito, probabilmente a causa di una carenza di memoria. Questa restituzione non significa necessariamente che una chiamata successiva avrà esito negativo. Tuttavia, il chiamante potrebbe tentare di ridurre i NumberOfDescriptor e chiamare di nuovo immediatamente. |
Una chiamata riuscita a NdisAllocatePacketPoolEx restituisce un handle al pool di pacchetti, che il chiamante deve salvare. In genere, il driver chiama NdisAllocatePacket una o più volte con questo handle per allocare un set di descrittori di pacchetti.
NdisAllocatePacketPoolEx alloca in modo statico solo memoria sufficiente per contenere il numero di descrittori di pacchetti specificati da NumberOfDescriptors. Il numero totale di descrittori di pacchetti che possono essere allocati dal pool con chiamate a NdisAllocatePacket è minore di 0xFFFF o la somma di NumberOfDescriptors e NumberOfOverflowDescriptors originariamente passato a NdisAllocatePacketPoolEx. I descrittori di overflow vengono allocati in modo dinamico solo durante una situazione di overflow, ovvero quando i NumberOfDescriptor specificati sono già stati allocati e sono ancora in uso.
La somma di NumberOfDescriptors e NumberOfOverflowDescriptors è il limite effettivo sul numero di volte in cui il driver può chiamare NdisAllocatePacket prima di chiamare NdisFreePacket per restituire un descrittore di pacchetti all'elenco gratuito per il pool di pacchetti. Quando non è ancora stato allocato alcun descrittore di overflow, NdisFreePacket restituisce il descrittore di pacchetti al pool allocato in modo statico. Se uno o più descrittori di overflow sono già stati allocati, NdisFreePacket restituisce il descrittore di pacchetti alla memoria di sistema, non al pool.
Il chiamante di NdisAllocatePacketPoolEx deve impostare NumberOfDescriptors sul numero di descrittori di pacchetti necessari per i carichi normali previsti. Il driver deve impostare NumberOfOverflowDescriptor sul numero di descrittori aggiuntivi necessari per supportare i carichi di picco previsti. Se il numero totale possibile di descrittori di pacchetti (NumberOfDescriptors più NumberOfOverflowDescriptors) è stata allocata dal pool, una chiamata a NdisAllocatePacket restituisce NDIS_STATUS_RESOURCES.
Quando i pacchetti inviati o indicati vengono restituiti al driver di allocazione, possono riutilizzare ogni descrittore di pacchetti dopo aver chiamato NdisReinitializePacket e impostarlo nuovamente con una catena di descrittori di buffer oppure il driver può chiamare NdisFreePacket per restituire tale pacchetto all'elenco gratuito. La reinizializzazione e il riutilizzo dei pacchetti allocati dal pool di pacchetti è molto più veloce rispetto alla liberazione e, quindi, dover riallocarli nuovamente. Prima che un driver chiami NdisReinitializePacket con un descrittore di pacchetto, deve salvare i puntatori nei descrittori del buffer concatenati al descrittore di pacchetti, perché NdisReinitializePacket imposta l'head della catena di buffer su NULL.
Quando un driver non richiede più descrittori di pacchetti, chiama [(nf-ndis-ndisfreepacketpool.md) per rilasciare lo spazio di archiviazione allocato con NdisAllocatePacketPoolEx.
versioni del sistema operativo: Windows CE .NET 4.0 e versioni successive.
Fabbisogno
| Requisito | Valore |
|---|---|
| intestazione | ndis.h |
| libreria | Ndis.lib |
| IRQL | IRQL <= DISPATCH_LEVEL |