Fungsi RtlInsertElementGenericTable (ntddk.h)
Rutinitas RtlInsertElementGenericTable menambahkan elemen baru ke tabel generik.
Sintaks
NTSYSAPI PVOID RtlInsertElementGenericTable(
[in] PRTL_GENERIC_TABLE Table,
[in] PVOID Buffer,
[in] CLONG BufferSize,
[out, optional] PBOOLEAN NewElement
);
Parameter
[in] Table
Penunjuk ke tabel generik (RTL_GENERIC_TABLE). Tabel harus diinisialisasi dengan memanggil RtlInitializeGenericTable.
[in] Buffer
Penunjuk ke buffer yang dialokasikan penelepon yang berisi data yang akan disalin ke elemen baru. Untuk informasi selengkapnya, lihat deskripsi RtlInitializeGenericTable.
[in] BufferSize
Jumlah byte yang akan dialokasikan untuk data yang disediakan pemanggil saat elemen baru disisipkan.
[out, optional] NewElement
Penunjuk ke variabel yang menerima TRUE jika elemen baru dengan data di Buffer disisipkan dalam tabel generik; atau FALSE jika elemen baru tidak disisipkan.
Nilai kembali
RtlInsertElementGenericTable mengembalikan penunjuk ke data terkait elemen yang baru disisipkan, atau mengembalikan penunjuk ke data elemen yang ada jika elemen yang cocok sudah ada dalam tabel generik. Jika tidak ada elemen yang cocok yang ditemukan, tetapi elemen baru tidak dapat dimasukkan (misalnya, karena AllocateRoutine gagal), RtlInsertElementGenericTable mengembalikan NULL.
Keterangan
Untuk menyisipkan elemen, RtlInsertElementGenericTable memanggil CompareRoutine dan AllocateRoutine yang didaftarkan ketika tabel generik diinisialisasi oleh RtlInitializeGenericTable. Setelah menyisipkan elemen baru, RtlInsertElementGenericTable menyeimbangkan kembali pohon tautan splay.
Saat elemen baru disisipkan ke dalam tabel, datanya disalin dari Buffer ke elemen baru. Dengan demikian pointer yang dikembalikan oleh RtlInsertElementGenericTable tidak pernah sama dengan Buffer.
Jika CompareRoutine penelepon mengembalikan GenericEqual, data di Buffer diasumsikan untuk menduplikasi data untuk elemen yang ada dalam tabel generik. Dalam hal ini, RtlInsertElementGenericTable tidak menambahkan elemen baru (dan dengan demikian tidak memanggil AllocateRoutine), karena tabel generik tidak dapat memiliki elemen duplikat.
Jika elemen yang cocok sudah ada dalam tabel generik, RtlInsertElementGenericTable mengembalikan penunjuk ke data elemen yang ada dan mengatur NewElement ke FALSE.
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.
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 yang lebih seimbang dan dangkal dari tabel generik 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 RTL_USE_AVL_TABLES tidak ditentukan, Anda harus menggunakan bentuk AVL dari rutinitas tabel generik. Misalnya, gunakan rutinitas RtlInsertElementGenericTableAvl alih-alih RtlInsertElementGenericTable. Dalam panggilan ke RtlInsertElementGenericTableAvl, pemanggil harus melewati struktur tabel RTL_AVL_TABLE daripada RTL_GENERIC_TABLE.
Pemanggil RtlInsertElementGenericTable harus berjalan di IRQL < DISPATCH_LEVEL jika salah satu kondisi berikut ini berlaku:
- Memori yang dialokasikan penelepon di Tabel atau di Buffer dapat di-pageable.
- CompareRoutine atau AllocateRoutine yang disediakan penelepon berisi kode yang dapat dipaginasi.
Persyaratan
| Persyaratan | Nilai |
|---|---|
| Target Platform | Universal |
| Header | ntddk.h (termasuk Ntddk.h, Ntifs.h) |
| Pustaka | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | < DISPATCH_LEVEL (lihat bagian Keterangan) |