Fungsi RtlInitializeGenericTableAvl (ntddk.h)

Artikel
03/08/2023

Rutinitas RtlInitializeGenericTableAvl menginisialisasi tabel generik menggunakan pohon Adelson-Velsky/Landis (AVL).

Sintaks

NTSYSAPI VOID RtlInitializeGenericTableAvl(
  [out]          PRTL_AVL_TABLE            Table,
  [in]           PRTL_AVL_COMPARE_ROUTINE  CompareRoutine,
  [in]           PRTL_AVL_ALLOCATE_ROUTINE AllocateRoutine,
  [in]           PRTL_AVL_FREE_ROUTINE     FreeRoutine,
  [in, optional] PVOID                     TableContext
);

Parameter

[out] Table

Penunjuk ke buffer yang dialokasikan penelepon, yang harus berukuran setidaknya sizeof(RTL_AVL_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_AVL_COMPARE_ROUTINE) (
    __in struct _RTL_AVL_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 penelepon untuk data elemen biasanya mencakup anggota yang nilainya unik dan dapat digunakan sebagai kunci pengurutan. Semua Rtl... Rutinitas GenericTableAvl 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_AVL_ALLOCATE_ROUTINE) (
    __in struct _RTL_AVL_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 pemanggil ditambah beberapa memori tambahan untuk digunakan oleh Rtl... Rutinitas GenericTableAvl . Perhatikan bahwa karena rutinitas "memori tambahan", yang disediakan pemanggil ini tidak boleh mengakses byte sizeof(RTL_BALANCED_LINKS) pertama dari elemen apa pun dalam tabel generik.

[in] FreeRoutine

Titik masuk dari rutinitas panggilan balik dealokasi, dinyatakan sebagai berikut:

VOID
(*PRTL_AVL_FREE_ROUTINE) (
    __in struct _RTL_AVL_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 GenericTableAvl memanggil FreeRoutine untuk membatalkan alokasi memori agar elemen 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 RtlInitializeGenericTableAvl 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 RtlInitializeGenericTableAvl untuk menginisialisasi tabel generik sebelum menggunakan Rtl lainnya... Rutinitas GenericTableAvl pada tabel generik baru. Struktur tabel generik yang diinisialisasi harus dianggap buram.

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.

CompareRoutine yang disediakan penelepon dipanggil sebelum AllocateRoutine untuk menemukan lokasi yang sesuai di mana elemen baru harus disisipkan. CompareRoutine juga dipanggil sebelum FreeRoutine untuk menemukan elemen yang akan dihapus.

Rutinitas RtlInitializeGenericTableAvl secara eksplisit mengalokasikan tabel generik yang menggunakan pohon AVL. Penggunaan rutinitas ini dan Rtl lainnya ... Rutinitas GenericTableAvl diperlukan ketika tabel berbasis pohon AVL diinginkan dan RTL_USE_AVL_TABLES tidak ditentukan sebelumnya termasuk Ntddk.h.

Jika Anda ingin mengonfigurasi rutinitas tabel generik, Rtl... GenericTable, untuk menggunakan pohon AVL alih-alih pohon splay di driver Anda, sisipkan pernyataan definisi berikut dalam file header umum sebelum menyertakan Ntddk.h:

`#define RTL_USE_AVL_TABLES 0`

Pemanggil RtlInitializeGenericTableAvl harus berjalan di IRQL <= DISPATCH_LEVEL. Perhatikan bahwa jika Rtl... Rutinitas GenericTableAvl 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 dipagasi.

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)