Fungsi WdfWorkItemEnqueue (wdfworkitem.h)

[Berlaku untuk KMDF dan UMDF]

Metode WdfWorkItemEnqueue menambahkan objek item kerja kerangka kerja tertentu ke antrean item kerja sistem.

Sintaks

void WdfWorkItemEnqueue(
  [in] WDFWORKITEM WorkItem
);

Parameter

[in] WorkItem

Handel ke objek item kerja kerangka kerja yang diperoleh dari panggilan sebelumnya ke WdfWorkItemCreate.

Nilai kembali

Tidak ada

Keterangan

Pemeriksaan bug terjadi jika driver menyediakan handel objek yang tidak valid.

Setelah driver memanggil WdfWorkItemCreate untuk membuat item kerja, driver harus memanggil WdfWorkItemEnqueue untuk menambahkan item kerja ke antrean item kerja sistem. Utas pekerja sistem kemudian menghapus item kerja dari antrean dan memanggil fungsi panggilan balik EvtWorkItem item kerja. Sistem menghapus item kerja dalam urutan ditambahkan ke antrean.

Sebelum driver memanggil WdfWorkItemEnqueue, mereka biasanya menggunakan memori konteks objek item kerja untuk menyimpan informasi tentang item kerja. Fungsi panggilan balik EvtWorkItem menggunakan informasi ini untuk menentukan operasi yang harus dilakukannya.

Untuk KMDF versi 1.7 dan yang lebih baru, jika driver Anda menggunakan kembali objek item kerjanya, driver dapat memanggil WdfWorkItemEnqueue lagi untuk item kerja yang sama sebelum utas pekerja sistem telah menghapus antrean item kerja dan kemudian disebut fungsi panggilan balik EvtWorkItem driver. Namun, KMDF tidak akan menambahkan item kerja ke antrean jika sudah ada. Oleh karena itu, fungsi panggilan balik EvtWorkItem Anda harus memproses semua pekerjaan yang diantrekan setiap kali dipanggil.

Driver Anda juga dapat memanggil WdfWorkItemEnqueue saat fungsi panggilan balik EvtWorkItem sedang berjalan, untuk mengantre item kerja lain. Panggilan balik EvtWorkItem item kerja kedua bahkan mungkin berjalan sebelum yang pertama selesai.

Dalam versi KMDF sebelum versi 1.7, jika driver Anda menggunakan kembali objek item kerjanya, ia tidak boleh memanggil WdfWorkItemEnqueue lagi untuk item kerja yang sama sampai utas pekerja sistem telah menghapus antrean item kerja dan memanggil fungsi panggilan balik EvtWorkItem-nya .

Untuk informasi selengkapnya tentang item kerja, lihat Menggunakan Item Kerja Kerangka Kerja.

Contoh

Bagian ini berisi dua contoh. Contoh pertama menunjukkan cara menambahkan item kerja ke antrean untuk KMDF versi 1.7 dan yang lebih baru. Contoh kedua menunjukkan cara menambahkan item kerja ke antrean untuk versi KMDF sebelum versi 1.7

Contoh 1: KMDF versi 1.7 dan yang lebih baru

Contoh kode berikut memanggil rutinitas lokal yang mengembalikan penunjuk ke memori konteks objek item kerja. Contoh mengatur informasi dalam memori konteks objek lalu memanggil WdfWorkItemEnqueue. Fungsi panggilan balik EvtWorkItem driver nantinya akan mengambil informasi dari objek item kerja.

PMY_CONTEXT_TYPE context;

context = GetWorkItemContext(hWorkItem);
context->FdoData = FdoData;
context->Argument1 = Context1;
context->Argument2 = Context2;

WdfWorkItemEnqueue(hWorkItem);

Fungsi panggilan balik EvtWorkItem driver berisi kode berikut.

MyWorkItemCallback (
    IN WDFWORKITEM hWorkItem
    )
{
    PMY_CONTEXT_TYPE context;

    context = GetWorkItemContext(hWorkItem);

    //
    // Do work here.
    //
    ...
    //
    return;
}

Contoh 2: Versi KMDF sebelum 1.7

Contoh kode berikut memanggil rutinitas lokal yang mengembalikan penunjuk ke memori konteks objek item kerja. Contoh mengatur informasi dalam memori konteks objek, mengatur variabel status ke "sibuk", lalu memanggil WdfWorkItemEnqueue. Fungsi panggilan balik EvtWorkItem driver nantinya akan mengambil informasi dari objek item kerja.

typedef enum _WORKITEM_STATE {
    WORKITEM_STATE_FREE =0,
    WORKITEM_STATE_BUSY = 1
} WORKITEM_STATE;
...
PMY_CONTEXT_TYPE context;

context = GetWorkItemContext(hWorkItem);
context->FdoData = FdoData;
context->Argument1 = Context1;
context->Argument2 = Context2;

if (InterlockedCompareExchange(
                               (PLONG)&context->WorkItemState,
                               WORKITEM_STATE_BUSY,
                               WORKITEM_STATE_FREE
                               ) == WORKITEM_STATE_FREE) {
 WdfWorkItemEnqueue(hWorkItem);
}

Fungsi panggilan balik EvtWorkItem driver berisi kode berikut. Tepat sebelum pernyataan pengembalian , kode mengatur variabel status objek item kerja menjadi "bebas" sehingga driver dapat mengantre objek lagi.

MyWorkItemCallback (
    IN WDFWORKITEM hWorkItem
    )
{
    PMY_CONTEXT_TYPE context;
    LONG result;

    context = GetWorkItemContext(hWorkItem);

    //
    // Do work here.
    //
    ...
    //
    // Reset object state.
    //
    result = InterlockedExchange(
                                 (PLONG)&context->WorkItemState,
                                 WORKITEM_STATE_FREE
                                 );
    ASSERT(result == WORKITEM_STATE_BUSY);
    return;
}

Persyaratan

Persyaratan	Nilai
Target Platform	Universal
Versi KMDF minimum	1,0
Versi UMDF minimum	2.0
Header	wdfworkitem.h (termasuk Wdf.h)
Pustaka	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<= DISPATCH_LEVEL
Aturan kepatuhan DDI	DeferredRequestCompleted(kmdf), DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestCompleted(kmdf), RequestCompletedLocal(kmdf)

Lihat juga

EvtWorkItem

InterlockedCompareExchange

InterlockedExchange

WdfWorkItemCreate