Fungsi WdfWorkItemCreate (wdfworkitem.h)

  • Artikel

[Berlaku untuk KMDF dan UMDF]

Metode WdfWorkItemCreate membuat objek item kerja kerangka kerja, yang kemudian dapat ditambahkan ke antrean item kerja sistem.

Sintaks

NTSTATUS WdfWorkItemCreate(
  [in]  PWDF_WORKITEM_CONFIG   Config,
  [in]  PWDF_OBJECT_ATTRIBUTES Attributes,
  [out] WDFWORKITEM            *WorkItem
);

Parameter

[in] Config

Penunjuk ke struktur WDF_WORKITEM_CONFIG yang dialokasikan penelepon yang harus sudah diinisialisasi driver dengan memanggil WDF_WORKITEM_CONFIG_INIT.

[in] Attributes

Penunjuk ke struktur WDF_OBJECT_ATTRIBUTES yang dialokasikan penelepon yang menentukan atribut untuk objek item kerja.

[out] WorkItem

Penunjuk ke variabel yang menerima handel ke objek item kerja baru.

Nilai kembali

WdfWorkItemCreate mengembalikan STATUS_SUCCESS jika operasi berhasil. Jika tidak, metode ini mungkin mengembalikan salah satu nilai berikut:

Menampilkan kode Deskripsi
STATUS_INVALID_PARAMETER
 Parameter yang tidak valid disediakan.
STATUS_INVALID_DEVICE_REQUEST
 Induk objek item kerja bukan objek perangkat atau leluhur objek perangkat.
STATUS_INSUFFICIENT_RESOURCES
 Sumber daya sistem tidak cukup untuk membuat objek item kerja.
STATUS_WDF_INCOMPATIBLE_EXECUTION_LEVEL
 Anggota AutomaticSerialization dalam struktur WDF_WORKITEM_CONFIG yang ditunjuk parameter Konfigurasi adalah TRUE, tetapi tingkat eksekusi objek induk bukan WdfExecutionLevelPassive.
STATUS_WDF_PARENT_NOT_SPECIFIED
 Parameter Atribut adalah NULL, atau anggota ParentObject dari struktur WDF_OBJECT_ATTRIBUTES yang ditentukan Atribut adalah NULL.

Keterangan

Setelah driver memanggil WdfWorkItemCreate untuk membuat item kerja, biasanya menyimpan informasi khusus item dalam memori konteks objek item kerja. Fungsi panggilan balik EvtWorkItem driver, yang melakukan tugas item kerja, dapat mengakses informasi ini untuk menentukan tugas yang harus dilakukannya. (Untuk informasi selengkapnya tentang menyimpan informasi dalam memori konteks, lihat Ruang Konteks Objek Kerangka Kerja.)

Setelah menyimpan informasi item kerja, driver harus memanggil WdfWorkItemEnqueue untuk menambahkan item kerja ke antrean item kerja sistem. Saat utas pekerja sistem tersedia, utas akan menghapus item kerja dari antrean dan memanggil fungsi panggilan balik EvtWorkItem .

Ketika driver membuat objek work-item, itu harus menentukan objek induk untuk objek work-item di anggota ParentObject dari struktur WDF_OBJECT_ATTRIBUTES . Objek induk harus berupa objek perangkat kerangka kerja atau objek apa pun yang rantai induknya mengarah ke objek perangkat kerangka kerja. Kerangka kerja akan menghapus objek item kerja saat menghapus objek perangkat.

Untuk menghapus objek item kerja sebelumnya, driver dapat memanggil WdfObjectDelete, seperti yang dijelaskan dalam Menggunakan Item Kerja Kerangka Kerja.

Driver dapat mengambil objek induk item kerja dengan memanggil WdfWorkItemGetParentObject.

Jika driver Anda menyediakan fungsi panggilan balik EvtCleanupCallback atau EvtDestroyCallback untuk objek item kerja, perhatikan bahwa kerangka kerja memanggil fungsi panggilan balik ini di IRQL = PASSIVE_LEVEL.

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

Contoh

Contoh kode berikut menginisialisasi struktur WDF_OBJECT_ATTRIBUTES , menginisialisasi struktur WDF_WORKITEM_CONFIG , dan memanggil WdfWorkItemCreate.

NTSTATUS  status = STATUS_SUCCESS;
PWORKER_ITEM_CONTEXT  context;
WDF_OBJECT_ATTRIBUTES  attributes;
WDF_WORKITEM_CONFIG  workitemConfig;
WDFWORKITEM  hWorkItem;

WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
WDF_OBJECT_ATTRIBUTES_SET_CONTEXT_TYPE(
                                       &attributes,
                                       WORKER_ITEM_CONTEXT
                                       );
attributes.ParentObject = FdoData->WdfDevice;

WDF_WORKITEM_CONFIG_INIT(
                         &workitemConfig,
                         CallbackFunction
                         );

status = WdfWorkItemCreate(
                            &workitemConfig,
                            &attributes,
                            &hWorkItem
                            );
if (!NT_SUCCESS(status)) {
    return status;
}

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 DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Lihat juga

WdfWorkItemEnqueue