Fungsi NdisAllocatePacketPoolEx (ndis.h)

Artikel
03/10/2023

Catatan NDIS 5. x telah ditolak dan digantikan oleh NDIS 6. x. Untuk pengembangan driver NDIS baru, lihat Driver Jaringan Yang Dimulai dengan Windows Vista. Untuk informasi tentang port NDIS 5. x driver ke NDIS 6. x, lihat Memindahkan Driver NDIS 5.x ke NDIS 6.0.

Fungsi ini mengalokasikan dan menginisialisasi blok penyimpanan untuk kumpulan deskriptor paket.

Sintaks

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

Parameter

[out] Status

Menunjuk ke variabel yang disediakan penelepon di mana fungsi ini mengembalikan status alokasi kumpulan paket.

[out] PoolHandle

Menunjuk ke variabel yang disediakan penelepon di mana fungsi ini mengembalikan handel ke kumpulan paket. Handel ini adalah parameter yang diperlukan untuk fungsi Paket NdisXXX yang kemudian dipanggil driver.

[in] NumberOfDescriptors

Menentukan jumlah deskriptor paket yang harus dikandung kumpulan untuk penggunaan normal yang diantisipasi. NumberOfDescriptor maksimum yang dapat dialokasikan adalah 0xFFFF. Jika upaya dilakukan untuk mengalokasikan lebih dari ini, NdisAllocatePacketPoolEx mengembalikan Status NDIS_STATUS_RESOURCES.

[in] NumberOfOverflowDescriptors

Menentukan jumlah deskriptor paket yang disediakan untuk situasi luapan, yaitu, ketika semua deskriptor yang ditentukan oleh NumberOfDescriptors sedang digunakan. Jika jumlah parameter ini dan NumberOfDescriptors melebihi 0xFFFF, NdisAllocatePacketPoolEx mengurangi nilai yang disediakan sebagai parameter ini sehingga total NumberOfDescriptors dan NumberOfOverflowDescriptors sama dengan 0xFFFF.

[in] ProtocolReservedLength

Menentukan jumlah byte yang akan dialokasikan untuk array ProtocolReserved dari setiap deskriptor paket. Agar deskriptor paket digunakan dalam indikasi terima, parameter ini berukuran 4*(PVOID).

Nilai kembali

Tidak ada

Keterangan

Tabel berikut ini memperlihatkan kemungkinan nilai pengembalian untuk fungsi ini.

Status	Deskripsi
NDIS_STATUS_SUCCESS	Driver dapat melakukan panggilan ke NdisAllocatePacket ketika membutuhkan deskriptor paket untuk membuat indikasi hingga driver tingkat yang lebih tinggi atau untuk mengirim paket ke driver tingkat bawah.
NDIS_STATUS_RESOURCES	Upaya untuk mengalokasikan kumpulan paket gagal, mungkin karena kekurangan memori. Pengembalian ini tidak selalu berarti bahwa panggilan berikutnya akan gagal. Namun, penelepon mungkin mencoba mengurangi NumberOfDescriptors dan segera memanggil lagi.

Panggilan yang berhasil ke NdisAllocatePacketPoolEx mengembalikan handel ke kumpulan paket, yang harus disimpan pemanggil. Biasanya, driver berikutnya memanggil NdisAllocatePacket satu atau beberapa kali dengan handel ini untuk mengalokasikan satu set deskriptor paket.

NdisAllocatePacketPoolEx secara statis hanya mengalokasikan memori yang cukup untuk mengakomodasi jumlah deskriptor paket yang ditentukan oleh NumberOfDescriptors. Jumlah total deskriptor paket yang dapat dialokasikan dari kumpulan dengan panggilan ke NdisAllocatePacket adalah lebih sedikit 0xFFFF atau jumlah NumberOfDescriptors dan NumberOfOverflowDescriptors yang awalnya diteruskan ke NdisAllocatePacketPoolEx. Deskriptor luapan dialokasikan secara dinamis hanya selama situasi luapan — yaitu, ketika NumberOfDescriptor yang diberikan telah dialokasikan dan masih digunakan.

Jumlah NumberOfDescriptors dan NumberOfOverflowDescriptors adalah batas efektif berapa kali driver dapat memanggil NdisAllocatePacket sebelum harus memanggil NdisFreePacket untuk mengembalikan deskriptor paket ke daftar gratis untuk kumpulan paket. Ketika belum ada deskriptor luapan yang dialokasikan, NdisFreePacket mengembalikan deskriptor paket ke kumpulan yang dialokasikan secara statis. Jika satu atau beberapa deskriptor luapan telah dialokasikan, NdisFreePacket mengembalikan deskriptor paket ke memori sistem — bukan ke kumpulan.

Pemanggil NdisAllocatePacketPoolEx harus mengatur NumberOfDescriptors ke jumlah deskriptor paket yang diperlukan untuk beban normal yang diantisipasi. Driver harus mengatur NumberOfOverflowDescriptors ke jumlah deskriptor tambahan yang diperlukan untuk mengakomodasi beban puncak yang diantisipasi. Jika jumlah total deskriptor paket yang mungkin (NumberOfDescriptors plus NumberOfOverflowDescriptors) telah dialokasikan dari kumpulan, panggilan ke NdisAllocatePacket mengembalikan NDIS_STATUS_RESOURCES.

Saat paket dikirim atau ditunjukkan dikembalikan ke driver alokasi, paket dapat menggunakan kembali setiap deskriptor paket setelah memanggil NdisReinitializePacket dan mengaturnya lagi dengan rantai deskriptor buffer, atau driver dapat memanggil NdisFreePacket untuk mengembalikan paket tersebut ke daftar gratis. Menginisialisasi ulang dan menggunakan kembali paket yang dialokasikan dari kumpulan paket jauh lebih cepat daripada membebaskan dan, kemudian, harus merealokasinya lagi. Sebelum driver memanggil NdisReinitializePacket dengan deskriptor paket, driver harus menyimpan pointer ke deskriptor buffer yang dirangkai ke deskriptor paket, karena NdisReinitializePacket mengatur kepala rantai buffer ke NULL.

Ketika driver tidak lagi membutuhkan deskriptor paket, driver memanggil [(nf-ndis-ndisfreepacketpool.md) untuk merilis penyimpanan yang dialokasikannya dengan NdisAllocatePacketPoolEx.

Versi OS: Windows CE .NET 4.0 dan yang lebih baru.

Persyaratan

Persyaratan	Nilai
Header	ndis.h
Pustaka	Ndis.lib
IRQL	IRQL <= DISPATCH_LEVEL

Share via