RtlInsertElementGenericTable 函式 (ntddk.h)
RtlInsertElementGenericTable 例程會將新元素新增至泛型數據表。
語法
NTSYSAPI PVOID RtlInsertElementGenericTable(
[in] PRTL_GENERIC_TABLE Table,
[in] PVOID Buffer,
[in] CLONG BufferSize,
[out, optional] PBOOLEAN NewElement
);
參數
[in] Table
泛型數據表的指標 (RTL_GENERIC_TABLE) 。 數據表必須已藉由呼叫 RtlInitializeGenericTable 來初始化。
[in] Buffer
呼叫端配置的緩衝區指標，其中包含要複製到新元素的數據。 如需詳細資訊，請參閱 RtlInitializeGenericTable 的描述。
[in] BufferSize
插入新專案時，要配置給呼叫端提供數據的位元元組數目。
[out, optional] NewElement
如果位於 Buffer 的新專案插入泛型數據表中，則為接收 TRUE 之變數的指標;如果未插入新專案，則為 FALSE。
傳回值
RtlInsertElementGenericTable 會傳回新插入之元素相關聯數據的指標，如果泛型數據表中已經有相符的專案，則會傳回現有元素數據的指標。 如果找不到相符的專案，但無法插入新元素 (，例如，因為 AllocateRoutine 失敗 ) ，RtlInsertElementGenericTable 會傳回 NULL。
備註
若要插入專案，RtlInsertElementGenericTable 會呼叫由 RtlInitializeGenericTable 初始化泛型數據表時所註冊的 CompareRoutine 和 AllocateRoutine。 插入新元素之後， RtlInsertElementGenericTable 會重新平衡 splay 鏈接樹狀結構。
當新元素插入數據表時，其數據會從 Buffer 複製到新元素。 因此 ，RtlInsertElementGenericTable 傳回的指標絕不等於 Buffer。
如果呼叫端的 CompareRoutine 傳回 GenericEqual，則會假設 Buffer 中的數據會複製泛型數據表中現有元素的數據。 在此情況下， RtlInsertElementGenericTable 不會加入新元素 (，因此不會呼叫 AllocateRoutine) ，因為泛型數據表不能有重複的專案。
如果泛型數據表中已經有相符的專案， RtlInsertElementGenericTable 會傳回現有元素數據的指標，並將 NewElement 設定為 FALSE。
Rtl.的呼叫端。GenericTable 例程負責獨佔同步處理泛型數據表的存取權。 獨佔快速 Mutex 是用於此用途的最有效率同步處理機制。
根據預設，操作系統會使用splay樹狀結構來實作泛型數據表。 在某些情況下，Splay 樹狀結構上的作業會讓樹狀結構深窄，甚至可能會變成直線。 非常深的樹狀結構會降低搜尋的效能。 您可以使用 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。
如果下列任一條件保留， RtlInsertElementGenericTable 的呼叫端必須在 IRQL < DISPATCH_LEVEL執行：
- 數據表 或Buffer 的呼叫端配置記憶體是可分頁的。
- 呼叫端提供的 CompareRoutine 或 AllocateRoutine 包含可分頁的程式代碼。
規格需求
| 需求 | 值 |
|---|---|
| 目標平台 | Universal |
| 標頭 | ntddk.h (包含 Ntddk.h、Ntifs.h) |
| 程式庫 | NtosKrnl.lib |
| Dll | NtosKrnl.exe |
| IRQL | < DISPATCH_LEVEL (请参阅一节) |