Fungsi RtlInsertElementGenericTableAvl (ntddk.h)
Rutinitas RtlInsertElementGenericTableAvl menambahkan entri baru ke tabel generik.
Sintaks
NTSYSAPI PVOID RtlInsertElementGenericTableAvl(
[in] PRTL_AVL_TABLE Table,
[in] PVOID Buffer,
[in] CLONG BufferSize,
[out, optional] PBOOLEAN NewElement
);
Parameter
[in] Table
Penunjuk ke tabel Adelson-Velsky/Landis (AVL) generik (RTL_AVL_TABLE) yang diinisialisasi oleh panggilan ke RtlInitializeGenericTableAvl.
[in] Buffer
Buffer yang dialokasikan penelepon yang berisi data pengguna untuk disalin ke elemen baru. Untuk informasi selengkapnya, lihat RtlInitializeGenericTableAvl.
[in] BufferSize
Ukuran dalam byte data di Buffer.
[out, optional] NewElement
Pada output, nilai TRUE berarti penyisipan elemen baru dalam tabel generik berhasil. Nilai FALSE berarti penyisipan gagal.
Nilai kembali
RtlInsertElementGenericTableAvl mengembalikan penunjuk ke data pengguna untuk entri yang baru disisipkan, atau data pengguna untuk entri yang cocok yang sudah ada dalam tabel generik. Jika tidak ada entri yang cocok ditemukan, tetapi RtlInsertElementGenericTableAvl tidak dapat menyisipkan entri baru (misalnya, karena AllocateRoutine gagal), RtlInsertElementGenericTableAvl mengembalikan NULL.
Keterangan
Untuk menyisipkan entri, RtlInsertElementGenericTableAvl memanggil CompareRoutine dan AllocateRoutine yang terdaftar ketika tabel generik diinisialisasi oleh RtlInitializeGenericTableAvl. Setelah menyisipkan entri baru, RtlInsertElementGenericTableAvl menyeimbangkan kembali pohon tautan AVL.
Saat entri baru disisipkan ke dalam tabel, datanya disalin dari Buffer ke entri baru. Dengan demikian pointer yang dikembalikan oleh RtlInsertElementGenericTableAvl tidak pernah sama dengan Buffer.
Jika CompareRoutine penelepon mengembalikan GenericEqual, data di Buffer diasumsikan untuk menduplikasi data untuk entri yang ada dalam tabel generik. Dalam hal ini, RtlInsertElementGenericTableAvl tidak menambahkan entri baru (dan dengan demikian tidak memanggil AllocateRoutine), karena tabel generik tidak dapat memiliki entri duplikat.
Jika entri yang cocok sudah ada dalam tabel generik, RtlInsertElementGenericTableAvl mengembalikan penunjuk ke data entri yang ada dan mengatur NewElement ke FALSE.
Jika tidak ada entri yang cocok dalam tabel, rutinitas RtlInsertElementGenericTableAvl mengalokasikan ruang yang cukup untuk data pengguna entri baru (BufferSize) ditambah tautan yang terkait dengan entri baru. Dengan demikian jumlah total byte akan setidaknya bufferSize + sizeof(RTL_BALANCED_LINKS). Pemanggil tidak boleh menggunakan ukuranof (RTL_BALANCED_LINKS) pertama dari memori yang dialokasikan AllocateRoutine.
Penelepon Rtl.. Rutinitas GenericTableAvl 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, tetapi rutinitas RtlInsertElementGenericTableAvl hanya berfungsi dengan pohon Adelson-Velsky/Landis (AVL). Untuk 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 RtlInsertElementGenericTableAvl harus berjalan di IRQL < DISPATCH_LEVEL jika salah satu kondisi berikut 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 |
|---|---|
| Klien minimum yang didukung | Tersedia dimulai dengan Windows XP. |
| Target Platform | Universal |
| Header | ntddk.h (termasuk Ntddk.h, Ntifs.h) |
| Pustaka | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | < DISPATCH_LEVEL (lihat bagian Keterangan) |