RtlInsertElementGenericTableAvl 函式 (ntddk.h)
RtlInsertElementGenericTableAvl 例程會將新專案新增至泛型數據表。
語法
NTSYSAPI PVOID RtlInsertElementGenericTableAvl(
[in] PRTL_AVL_TABLE Table,
[in] PVOID Buffer,
[in] CLONG BufferSize,
[out, optional] PBOOLEAN NewElement
);
參數
[in] Table
一般 Adelson-Velsky/Landis (AVL) 數據表的指標， (RTL_AVL_TABLE) ，由呼叫 RtlInitializeGenericTableAvl 初始化。
[in] Buffer
呼叫端配置的緩衝區，其中包含要複製到新元素的用戶數據。 如需詳細資訊，請參閱 RtlInitializeGenericTableAvl。
[in] BufferSize
緩衝區中的數據位元組大小 。
[out, optional] NewElement
在輸出時，值為 TRUE 表示在泛型數據表中插入新元素成功。 FALSE 值表示插入失敗。
傳回值
RtlInsertElementGenericTableAvl 會針對新插入的專案傳回用戶數據的指標，或針對已在泛型數據表中的相符專案傳回用戶數據。 如果找不到相符的專案，但 RtlInsertElementGenericTableAvl 無法插入新的專案 (例如，因為 AllocateRoutine 失敗) ，RtlInsertElementGenericTableAvl 會傳回 NULL。
備註
若要插入專案，RtlInsertElementGenericTableAvl 會呼叫由 RtlInitializeGenericTableAvl 初始化泛型數據表時所註冊的 CompareRoutine 和 AllocateRoutine。 插入新項目之後， RtlInsertElementGenericTableAvl 會重新平衡 AVL 連結樹狀結構。
當新專案插入數據表時，其數據會從 Buffer 複製到新專案。 因此 ，RtlInsertElementGenericTableAvl 所傳回的指標絕不等於 Buffer。
如果呼叫端的 CompareRoutine 傳回 GenericEqual，則會假設 Buffer 上的數據會複製泛型數據表中現有項目的數據。 在此情況下， RtlInsertElementGenericTableAvl 不會新增專案 (，因此不會呼叫 AllocateRoutine) ，因為泛型數據表不能有重複的專案。
如果泛型數據表中已經有相符的專案， RtlInsertElementGenericTableAvl 會傳回現有項目數據的指標，並將 NewElement 設定為 FALSE。
如果數據表中還沒有相符的專案，RtlInsertElementGenericTableAvl 例程會為新專案的用戶數據配置足夠的空間， (BufferSize) 加上與新專案相關聯的連結。 因此，位元組總數至少會是 BufferSize + sizeof (RTL_BALANCED_LINKS) 。 呼叫端不應使用 AllocateRoutine配置之內存的第一個 sizeof (RTL_BALANCED_LINKS) 位元組。
Rtl 的呼叫端。GenericTableAvl 例程負責獨佔同步處理泛型數據表的存取。 獨佔快速 Mutex 是用於此用途的最有效率同步處理機制。
根據預設，操作系統會使用splay樹狀架構來實作一般數據表，但 RtlInsertElementGenericTableAvl 例程只適用於 Adelson-Velsky/Landis (AVL) 樹狀結構。 若要將泛型數據表例程設定為使用AVL樹狀結構，而不是驅動程式中的splay樹狀結構，請在包含 Ntddk.h之前，先在通用頭檔中插入下列 define 語句：
#define RTL_USE_AVL_TABLES 0
如果未定義RTL_USE_AVL_TABLES，您必須使用泛型數據表例程的AVL格式。 例如，使用 RtlInsertElementGenericTableAvl 例程，而不是 RtlInsertElementGenericTable。 在 對 RtlInsertElementGenericTableAvl 的呼叫中，呼叫端必須傳遞 RTL_AVL_TABLE 數據表結構，而不是 RTL_GENERIC_TABLE。
如果符合下列任一條件， 則 RtlInsertElementGenericTableAvl 的呼叫端必須在 IRQL < DISPATCH_LEVEL上執行：
- 數據表或 Buffer 的呼叫端配置記憶體是可分頁的。
- 呼叫端提供的 CompareRoutine 或 AllocateRoutine 包含可分頁程式代碼。
規格需求
| 需求 | 值 |
|---|---|
| 最低支援的用戶端 | 從 Windows XP 開始提供。 |
| 目標平台 | Universal |
| 標頭 | ntddk.h (包含 Ntddk.h、Ntifs.h) |
| 程式庫 | NtosKrnl.lib |
| Dll | NtosKrnl.exe |
| IRQL | < DISPATCH_LEVEL (请参阅一节) |