Fungsi RtlInsertElementGenericTableFullAvl (ntddk.h)
Rutinitas RtlInsertElementGenericTableFullAvl menambahkan entri baru ke tabel generik.
Sintaks
NTSYSAPI PVOID RtlInsertElementGenericTableFullAvl(
[in] PRTL_AVL_TABLE Table,
[in] PVOID Buffer,
[in] CLONG BufferSize,
[out, optional] PBOOLEAN NewElement,
[in] PVOID NodeOrParent,
[in] TABLE_SEARCH_RESULT SearchResult
);
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.
[in] NodeOrParent
Hasil pencarian dari panggilan sebelumnya ke RtlLookupElementGenericTableFullAvl. Nilai ini menunjukkan rutinitas RtlInsertElementGenericTableFullAvl apakah pohon saat ini kosong, atau jika tidak kosong, apakah akan menyisipkan entri baru ke kiri atau kanan entri induk. Parameter SearchResult dapat memiliki salah satu nilai berikut:
TableEmptyTree
Pohonnya kosong. Isi NodeOrParentbelum diubah.
TableFoundNode
Rutinitas RtlInsertElementGenericTableFullAvl menemukan entri tabel yang kuncinya cocok dengan data di Buffer. NodeOrParent berisi penunjuk ke entri yang cocok.
TableInsertAsLeft
Rutinitas RtlInsertElementGenericTableFullAvltidak menemukan entri tabel yang kuncinya cocok dengan data di Buffer. Jika entri yang dicari RtlInsertElementGenericTableFullAvl berada dalam tabel, itu akan menjadi anak kiri dari entri yang ditunjuk NodeOrParent .
TableInsertAsRight
Rutinitas RtlInsertElementGenericTableFullAvltidak menemukan entri tabel yang kuncinya cocok dengan data di Buffer. Jika entri yang dicari RtlInsertElementGenericTableFullAvl berada dalam tabel, itu akan menjadi turunan kanan dari entri yang ditunjuk NodeOrParent .
[in] SearchResult
Penunjuk ke entri tabel. Jika rutinitas RtlInsertElementGenericTableFullAvl cocok dengan entri, NodeOrParent menunjuk ke entri yang cocok. Jika rutinitas RtlInsertElementGenericTableFullAvl gagal menemukan kecocokan, NodeOrParent menunjuk ke entri yang akan menjadi induk entri yang dicari oleh rutinitas RtlInsertElementGenericTableFullAvl .
Nilai kembali
RtlInsertElementGenericTableFullAvl 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 yang ditemukan, tetapi RtlInsertElementGenericTableFullAvl tidak dapat menyisipkan entri baru (misalnya, karena AllocateRoutine gagal), RtlInsertElementGenericTableFullAvl mengembalikan NULL.
Keterangan
Untuk menyisipkan entri, RtlInsertElementGenericTableFullAvl memanggil CompareRoutine dan AllocateRoutine yang didaftarkan ketika tabel generik diinisialisasi oleh RtlInitializeGenericTableAvl. Setelah menyisipkan entri baru, RtlInsertElementGenericTableFullAvl 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 RtlInsertElementGenericTableFullAvl 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, RtlInsertElementGenericTableFullAvl 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, RtlInsertElementGenericTableFullAvl mengembalikan penunjuk ke data entri yang ada dan mengatur NewElement ke FALSE.
Jika tidak ada entri yang cocok dalam tabel sudah,RtlInsertElementGenericTableFullAvl rutin 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(BALANCED_LINKS). Pemanggil tidak boleh menggunakan byte ukuranof(BALANCED_LINKS) pertama dari memori yang dialokasikan AllocateRoutine.
PeneleponRtl.. 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 RtlInsertElementGenericTableFullAvl 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 RtlInsertElementGenericTableFullAvl alih-alihRtlInsertElementGenericTableFull. Dalam panggilan ke RtlInsertElementGenericTableFullAvl, pemanggil harus melewati struktur tabel RTL_AVL_TABLE daripada RTL_GENERIC_TABLE.
Penelepon RtlInsertElementGenericTableFullAvl 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 di Windows XP dan versi yang lebih baru dari sistem operasi Windows. |
| Target Platform | Universal |
| Header | ntddk.h (termasuk Ntddk.h, Ntifs.h) |
| Pustaka | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | < DISPATCH_LEVEL (lihat bagian Keterangan) |