Fungsi AppendTailList (wdm.h)

Artikel
03/08/2023

Rutinitas AppendTailList menambahkan daftar struktur LIST_ENTRY yang ditautkan dua kali lipat ke ekor daftar struktur LIST_ENTRY yang ditautkan dua kali lipat.

Sintaks

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

Parameter

[in, out] ListHead

Penunjuk ke kepala daftar tempat daftar ditujukan oleh ListToAppend akan ditambahkan. Parameter ini harus berupa penunjuk non-NULL yang valid ke struktur LIST_ENTRY yang merupakan kepala daftar. Daftar ini bisa kosong.

[in, out] ListToAppend

Penunjuk ke entri pertama dalam daftar untuk ditambahkan ke daftar yang diarahkan oleh ListHead. Parameter ini harus berupa penunjuk non-NULL yang valid ke struktur LIST_ENTRY yang merupakan entri pertama dalam daftar tanpa kepala. Untuk informasi selengkapnya, lihat Keterangan.

Nilai kembali

Tidak ada

Keterangan

Rutinitas ini membuat daftar yang berisi semua entri gabungan dari daftar ListHead dan ListToAppend input. Saat rutinitas kembali, struktur LIST_ENTRY yang diarahkan oleh parameter ListHead adalah kepala daftar gabungan yang dihasilkan. Struktur LIST_ENTRY yang diacu oleh parameter ListToAppend adalah entri dalam daftar gabungan yang dihasilkan.

Penelepon mengatur parameter ListToAppend untuk menunjuk ke entri pertama dalam daftar yang akan ditambahkan. Dalam hal ini, AppendTailList tidak sesuai dengan konvensi yang diikuti oleh rutinitas daftar tertaut doubly lainnya yang menggunakan struktur LIST_ENTRY . Dalam rutinitas lain ini, parameter yang mewakili daftar menunjuk ke kepala daftar alih-alih ke entri pertama dalam daftar. Jika kode driver Anda menggunakan kepala daftar untuk mewakili daftar yang akan ditambahkan, kepala daftar harus dihapus dari daftar ini sebelum daftar diteruskan sebagai parameter ListToAppend ke AppendTailList. Untuk contoh kode yang memperlihatkan cara menghapus kepala daftar ini, lihat Contoh.

AppendTailList dapat digunakan untuk menyisipkan satu entri di ekor daftar, tetapi anggota Flink dan Blink dari struktur LIST_ENTRY yang diarahkan oleh ListToAppend harus terlebih dahulu diinisialisasi—biasanya, dengan memanggil rutinitas InitializeListHead . Sebaliknya, rutinitas InsertTailList tidak memerlukan anggota Flink dan Blink dari struktur LIST_ENTRY yang ditujukkan oleh parameter Entri untuk diinisialisasi sebelum panggilan InsertTailList . Untuk alasan ini, InsertTailList mungkin lebih nyaman digunakan untuk menyisipkan satu entri di ekor daftar.

Driver dapat mengakses anggota Flink dan Blink dari LIST_ENTRY, tetapi anggota hanya boleh diperbarui oleh rutinitas sistem yang disediakan untuk tujuan ini.

Untuk informasi tentang menggunakan rutinitas ini saat menerapkan daftar tertaut dua kali lipat, lihat Lists Tertaut Singly dan Doubly.

Pemanggil AppendTailList dapat berjalan di IRQL apa pun. Jika AppendTailList dipanggil di IRQL >= DISPATCH_LEVEL, penyimpanan untuk entri daftar harus berupa memory-resident.

Contoh

Contoh kode berikut menunjukkan cara menulis fungsi bernama MyAppendTailList yang mirip dengan AppendTailList, tetapi yang memperlakukan parameter ListToAppend sebagai penunjuk ke kepala daftar alih-alih sebagai penunjuk ke entri pertama dalam daftar (tanpa kepala). Tidak seperti AppendTailList, MyAppendTailList fungsi menghindari termasuk struktur LIST_ENTRY yang diarahkan oleh parameter ListToAppend dalam entri yang ditambahkan ke daftar yang diarahkan oleh parameter ListHead .

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);
    }
}

Fungsi MyAppendTailList dalam contoh kode ini memperlakukan parameter ListHead dan ListToAppend sebagai penunjuk ke kepala daftar. Ketika fungsi ini kembali, daftar yang ditujukan oleh ListToAppend kosong; yaitu, terdiri dari kepala daftar yang tidak memiliki entri daftar terkait. Semua entri yang awalnya ada dalam daftar ini telah ditambahkan ke daftar yang diarahkan oleh ListHead.