Fungsi RtlInitializeGenericTable (ntddk.h)
Rutinitas RtlInitializeGenericTable menginisialisasi tabel generik.
Sintaks
NTSYSAPI VOID RtlInitializeGenericTable(
[out] PRTL_GENERIC_TABLE Table,
[in] PRTL_GENERIC_COMPARE_ROUTINE CompareRoutine,
[in] PRTL_GENERIC_ALLOCATE_ROUTINE AllocateRoutine,
[in] PRTL_GENERIC_FREE_ROUTINE FreeRoutine,
[in, optional] PVOID TableContext
);
Parameter
[out] Table
Penunjuk ke buffer yang dialokasikan pemanggil, yang harus berukuran setidaknya byte ukuranof(RTL_GENERIC_TABLE), untuk berisi struktur tabel generik yang diinisialisasi.
[in] CompareRoutine
Titik masuk dari rutinitas panggilan balik perbandingan, dinyatakan sebagai berikut:
RTL_GENERIC_COMPARE_RESULTS
(*PRTL_GENERIC_COMPARE_ROUTINE) (
__in struct _RTL_GENERIC_TABLE *Table,
__in PVOID FirstStruct,
__in PVOID SecondStruct
);
Parameter CompareRoutine adalah sebagai berikut:
Tabel (CompareRoutine)
Penunjuk ke tabel generik.
FirstStruct
Penunjuk ke item pertama yang akan dibandingkan.
SecondStruct
Penunjuk ke item kedua yang akan dibandingkan.
CompareRoutine harus benar-benar melacak urutan semua elemen dalam tabel generik sehingga dapat mengidentifikasi elemen tertentu. Struktur yang ditentukan pemanggil untuk data elemen biasanya mencakup anggota yang nilainya unik dan dapat digunakan sebagai kunci pengurutan. Semua Rtl... Rutinitas GenericTable yang memanggil CompareRoutine mengambil penunjuk buffer sebagai parameter, yang diteruskan pada gilirannya ke CompareRoutine. Buffer berisi nilai kunci yang disediakan penelepon untuk dicocokkan dengan CompareRoutine dengan kunci elemen yang sedang dicari.
Mengingat dua nilai kunci tersebut, CompareRoutine mengembalikan GenericLessThan, GenericGreaterThan, atau GenericEqual.
[in] AllocateRoutine
Titik masuk dari rutinitas panggilan balik alokasi, dinyatakan sebagai berikut:
PVOID
(*PRTL_GENERIC_ALLOCATE_ROUTINE) (
__in struct _RTL_GENERIC_TABLE *Table,
__in CLONG ByteSize
);
Parameter AllocateRoutine adalah sebagai berikut:
Tabel (AllocateRoutine)
Penunjuk ke tabel generik.
Ukuran Byte
Jumlah byte yang akan dialokasikan.
Untuk setiap elemen baru, AllocateRoutine dipanggil untuk mengalokasikan memori untuk data yang disediakan penelepon ditambah beberapa memori tambahan untuk digunakan oleh Rtl... Rutinitas GenericTable . Perhatikan bahwa karena rutinitas yang disediakan pemanggil "memori tambahan", tidak boleh mengakses byte (sizeof(RTL_SPLAY_LINKS) + sizeof(LIST_ENTRY)) pertama dari elemen apa pun dalam tabel generik.
[in] FreeRoutine
Titik masuk dari rutinitas panggilan balik dealokasi, dinyatakan sebagai berikut:
VOID
(*PRTL_GENERIC_FREE_ROUTINE) (
__in struct _RTL_GENERIC_TABLE *Table,
__in PVOID Buffer
);
Parameter FreeRoutine adalah sebagai berikut:
Tabel (FreeRoutine)
Penunjuk ke tabel generik.
Buffer
Penunjuk ke elemen yang sedang dihapus.
Rtl... Rutinitas GenericTable memanggil FreeRoutine untuk membatalkan alokasi memori untuk elemen yang akan dihapus dari tabel generik. FreeRoutine adalah kebalikan dari AllocateRoutine.
[in, optional] TableContext
Penunjuk opsional ke konteks yang disediakan penelepon untuk tabel generik. Parameter ini bisa NULL.
Nilai kembali
Tidak ada
Keterangan
Sistem file memanggil RtlInitializeGenericTable untuk menginisialisasi tabel generik untuk menyimpan data khusus sistem file, seperti informasi pencarian nama untuk file yang saat ini terbuka. Urutan pengurutan, struktur, dan konten elemen ditentukan pemanggil.
Sistem file harus memanggil RtlInitializeGenericTable untuk menginisialisasi tabel generik sebelum menggunakan Rtl lainnya... Rutinitas GenericTable pada tabel generik baru. Struktur tabel generik yang diinisialisasi harus dianggap buram.
Penelepon Rtl... Rutinitas GenericTable bertanggung jawab untuk menyinkronkan akses secara eksklusif ke tabel generik. Mutex cepat eksklusif adalah mekanisme sinkronisasi yang paling efisien untuk digunakan untuk tujuan ini.
CompareRoutine yang disediakan penelepon dipanggil sebelum AllocateRoutine untuk menemukan lokasi yang sesuai di mana elemen baru harus dimasukkan. CompareRoutine juga dipanggil sebelum FreeRoutine untuk menemukan elemen yang akan dihapus.
Secara default, sistem operasi menggunakan pohon splay untuk mengimplementasikan tabel generik. Dalam beberapa keadaan, operasi pada pohon splay akan membuat pohon dalam dan sempit dan bahkan mungkin mengubahnya menjadi garis lurus. Pohon yang sangat dalam menurunkan performa pencarian. Anda dapat memastikan implementasi pohon tabel generik yang lebih seimbang dan dangkal dengan menggunakan pohon Adelson-Velsky/Landis (AVL). Jika Anda ingin mengonfigurasi rutinitas tabel generik untuk menggunakan pohon AVL alih-alih pohon splay di driver Anda, masukkan pernyataan definisi berikut dalam file header umum sebelum menyertakan Ntddk.h:
`#define RTL_USE_AVL_TABLES 0`
Jika Anda ingin menggunakan tabel AVL dan jika RTL_USE_AVL_TABLES tidak ditentukan, Anda harus menggunakan formulir AVL dari rutinitas tabel generik. Misalnya, gunakan rutinitas RtlInitializeGenericTableAvl alih-alih RtlInitializeGenericTable. RtlInitializeGenericTableAvl mengembalikan struktur tabel RTL_AVL_TABLE yang diinisialisasi dalam buffer tempat parameter Tabel menunjuk. Dalam panggilan ke RtlInitializeGenericTableAvl, penelepon harus melewati rutinitas panggilan balik perbandingan yang ditik PRTL_AVL_COMPARE_ROUTINE, rutinitas panggilan balik alokasi PRTL_AVL_ALLOCATE_ROUTINE-ketik, dan rutinitas panggilan balik dealokasi jenis PRTL_AVL_FREE_ROUTINE daripada rutinitas serupa PRTL_GENERIC_Xxx-typed.
Penelepon RtlInitializeGenericTable harus berjalan di IRQL <= DISPATCH_LEVEL. Perhatikan bahwa jika Rtl... Rutinitas GenericTable akan digunakan di IRQL DISPATCH_LEVEL, CompareRoutine, AllocateRoutine, dan FreeRoutine semuanya harus berupa kode yang tidak dapat dihapus, dan AllocateRoutine harus mengalokasikan memori dari kumpulan yang tidak di-patahkan.
Persyaratan
| Persyaratan | Nilai |
|---|---|
| Target Platform | Universal |
| Header | ntddk.h (termasuk Ntddk.h, Ntifs.h, Fltkernel.h) |
| Pustaka | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | IRQL <= DISPATCH_LEVEL (lihat bagian Keterangan) |