Fungsi WdfDpcCreate (wdfdpc.h)

Artikel
02/27/2024

[Hanya berlaku untuk KMDF]

Metode WdfDpcCreate membuat objek DPC kerangka kerja dan mendaftarkan fungsi panggilan balik EvtDpcFunc .

Sintaks

NTSTATUS WdfDpcCreate(
  [in]  PWDF_DPC_CONFIG        Config,
  [in]  PWDF_OBJECT_ATTRIBUTES Attributes,
  [out] WDFDPC                 *Dpc
);

Parameter

[in] Config

Penunjuk ke struktur WDF_DPC_CONFIG yang dialokasikan penelepon.

[in] Attributes

Penunjuk ke struktur WDF_OBJECT_ATTRIBUTES yang dialokasikan penelepon yang menentukan atribut untuk objek DPC baru.

[out] Dpc

Penunjuk ke lokasi yang menerima handel ke objek DPC kerangka kerja baru.

Nilai kembali

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

Menampilkan kode	Deskripsi
STATUS_INVALID_PARAMETER	Parameter yang tidak valid ditentukan.
STATUS_INSUFFICIENT_RESOURCES	Objek DPC tidak dapat dialokasikan.
STATUS_WDF_PARENT_NOT_SPECIFIED	Objek induk tidak ditentukan dalam struktur WDF_OBJECT_ATTRIBUTES .
STATUS_INVALID_DEVICE_REQUEST	Anggota ParentObject dari struktur WDF_OBJECT_ATTRIBUTES tidak mereferensikan objek perangkat kerangka kerja atau objek yang rantai induknya mengarah ke objek perangkat kerangka kerja.
STATUS_WDF_INCOMPATIBLE_EXECUTION_LEVEL	Anggota AutomaticSerialization dari struktur WDF_DPC_CONFIG diatur ke TRUE, tetapi tingkat eksekusi objek induk diatur ke WdfExecutionLevelPassive.

Untuk daftar nilai pengembalian lain yang mungkin dikembalikan oleh metode WdfDpcCreate , lihat Kesalahan Pembuatan Objek Kerangka Kerja.

Metode ini juga dapat mengembalikan nilai NTSTATUS lainnya.

Keterangan

Driver biasanya memanggil WdfDpcCreate dari dalam fungsi panggilan balik EvtDriverDeviceAdd .

Ketika driver membuat objek DPC, driver harus menentukan objek induk di anggota ParentObject dari struktur WDF_OBJECT_ATTRIBUTES . Objek induk dapat menjadi objek perangkat kerangka kerja atau objek apa pun yang rantai induknya mengarah ke objek perangkat kerangka kerja. Kerangka kerja akan menghapus objek DPC saat menghapus objek perangkat.

Memanggil WdfDpcCreate membuat objek DPC kerangka kerja dan mendaftarkan fungsi panggilan balik EvtDpcFunc . Untuk menjadwalkan eksekusi fungsi panggilan balik, driver harus memanggil WdfDpcEnqueue.

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

Untuk informasi selengkapnya tentang menggunakan objek DPC, lihat Melayani Interupsi.

Contoh

Contoh kode berikut menginisialisasi struktur WDF_DPC_CONFIG_INIT lalu membuat objek DPC.

WDF_DPC_CONFIG dpcConfig;
WDF_OBJECT_ATTRIBUTES dpcAttributes;
NTSTATUS status;

WDF_DPC_CONFIG_INIT(
                    &dpcConfig,
                    MyEvtDpcFunc
                    );
dpcConfig.AutomaticSerialization = TRUE;
WDF_OBJECT_ATTRIBUTES_INIT(&dpcAttributes);
dpcAttributes.ParentObject = pDevExt->WdfDevice;
status = WdfDpcCreate(
                      &dpcConfig,
                      &dpcAttributes,
                      &pDevExt->CompleteWriteDpc
                      );
if (!NT_SUCCESS(status)) {
    return status;
}

Persyaratan

Persyaratan	Nilai
Target Platform	Universal
Versi KMDF minimum	1,0
Header	wdfdpc.h (termasuk Wdf.h)
Pustaka	Wdf01000.sys (lihat Penerapan Versi Pustaka Kerangka Kerja.)
IRQL	<=DISPATCH_LEVEL
Aturan kepatuhan DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)