AppendTailList 函式 (wdm.h)

發行項
02/27/2024

AppendTailList 例程會將LIST_ENTRY結構的雙連結清單附加至另一個LIST_ENTRY結構之多任務連結清單的結尾。

語法

void AppendTailList(
  [in, out] PLIST_ENTRY ListHead,
  [in, out] PLIST_ENTRY ListToAppend
);

參數

[in, out] ListHead

要附加 ListToAppend 所指向清單之清單前端的指標。這個參數必須是清單前端之LIST_ENTRY 結構的有效非NULL指標。此清單可以是空的。

[in, out] ListToAppend

清單中第一個專案的指標，要附加至 ListHead 所指向的清單。此參數必須是無外設清單中第一個專案之LIST_ENTRY 結構的有效非 NULL 指標。如需詳細資訊，請參閱＜備註＞。

傳回值

無

備註

此例程會建構清單，其中包含來自輸入 ListHead 和 ListToAppend 清單的所有合併專案。當例程傳回時，ListHead 參數所指向的LIST_ENTRY結構是結果合併清單的前端。 ListToAppend 參數所指向的LIST_ENTRY結構是結果組合清單中的專案。

呼叫端會將 ListToAppend 參數設定為指向要附加之清單中的第一個專案。在此方面， AppendTailList 不符合慣例，後面接著使用 LIST_ENTRY 結構的其他多任務連結清單例程。在這些其他例程中，代表清單的參數會指向清單前端，而不是指向清單中的第一個專案。如果您的驅動程式程式代碼使用清單標頭來代表要附加的清單，則必須先從此清單中移除清單標頭，才能將清單當做 ListToAppend 參數傳遞至 AppendTailList。如需示範如何移除此列表前端的程式代碼範例，請參閱範例。

AppendTailList 可用來在清單結尾插入單一專案，但必須先初始化 ListToAppend 所指向之LIST_ENTRY結構的 Flink 和 Blink 成員，通常是藉由呼叫 InitializeListHead 例程。相反地，InsertTailList 例程不需要在 InsertTailList 呼叫之前初始化 Entry 參數所指向之LIST_ENTRY結構的 Flink 和 Blink 成員。基於這個理由， InsertTailList 可能更方便用來在清單結尾插入單一專案。

驅動程式可以存取LIST_ENTRY的 Flink 和 Blink 成員，但成員只能由基於此目的提供的系統例程更新。

如需實作雙連結清單時使用此例程的相關信息，請參閱 Singly 和 Doubly Linked 清單。

AppendTailList 的呼叫端可以在任何 IRQL 上執行。如果在 IRQL >= DISPATCH_LEVEL呼叫 AppendTailList，清單專案的記憶體必須是記憶體駐留的。

範例

下列程式代碼範例示範如何撰寫與 AppendTailList 類似的函MyAppendTailList式，但會將 ListToAppend 參數視為清單標頭的指標，而不是當做 (無外設) 列表中第一個專案的指標。不同於 AppendTailList，函MyAppendTailList式會避免在 ListHead 參數所指向清單中附加至清單的專案中包含 ListToAppend 參數所指向的LIST_ENTRY結構。

VOID MyAppendTailList(
    _Inout_  PLIST_ENTRY ListHead,
    _Inout_  PLIST_ENTRY ListToAppend
    )
{
    PLIST_ENTRY entry = ListToAppend->Flink;

    if (!IsListEmpty(ListToAppend))
    {
        RemoveEntryList(ListToAppend);
        InitializeListHead(ListToAppend);
        AppendTailList(ListHead, entry);
    }
}

此程式代碼範例中的函 MyAppendTailList 式會將 ListHead 和 ListToAppend 參數視為清單頭的指標。當此函式傳回時， ListToAppend 所指向的清單是空的;也就是說，它是由沒有相關聯清單專案的清單標頭所組成。一開始在此清單中的所有專案都已附加至 ListHead 所指向的清單。