Fungsi WdfIoQueueCreate (wdfio.h)

Artikel
08/08/2023

[Berlaku untuk KMDF dan UMDF]

Metode WdfIoQueueCreate membuat dan mengonfigurasi antrean I/O untuk perangkat tertentu.

Sintaks

NTSTATUS WdfIoQueueCreate(
  [in]            WDFDEVICE              Device,
  [in]            PWDF_IO_QUEUE_CONFIG   Config,
  [in, optional]  PWDF_OBJECT_ATTRIBUTES QueueAttributes,
  [out, optional] WDFQUEUE               *Queue
);

Parameter

[in] Device

Handel ke objek perangkat kerangka kerja yang akan dikaitkan dengan antrean.

[in] Config

Penunjuk ke struktur WDF_IO_QUEUE_CONFIG yang dialokasikan pemanggil.

[in, optional] QueueAttributes

Penunjuk ke struktur WDF_OBJECT_ATTRIBUTES yang dialokasikan pemanggil yang menentukan atribut objek untuk objek baru. Parameter ini bersifat opsional dan dapat WDF_NO_OBJECT_ATTRIBUTES.

[out, optional] Queue

Penunjuk ke lokasi yang menerima handel ke objek antrean kerangka kerja.

Nilai kembali

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

Menampilkan kode	Deskripsi
STATUS_INVALID_PARAMETER	Parameter input tidak valid.
STATUS_INFO_LENGTH_MISMATCH	Ukuran struktur WDF_IO_QUEUE_CONFIG salah.
STATUS_POWER_STATE_INVALID	Kerangka kerja melakukan operasi manajemen daya.
STATUS_INSUFFICIENT_RESOURCES	Jumlah memori yang tersedia terlalu rendah.
STATUS_WDF_NO_CALLBACK	Struktur WDF_IO_QUEUE_CONFIG tidak menentukan penangan permintaan apa pun, dan metode pengiriman bukan WdfIoQueueDispatchManual.
STATUS_UNSUCCESSFUL	Driver mencoba membuat antrean default saat antrean default sudah ada untuk perangkat, atau terjadi kesalahan internal.

Metode ini juga mungkin mengembalikan nilai NTSTATUS lainnya.

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

Keterangan

Setiap panggilan ke WdfIoQueueCreate membuat antrean I/O untuk perangkat. Driver Anda dapat membuat beberapa antrean I/O untuk setiap perangkat.

Parameter Config dan QueueAttributes menentukan konfigurasi antrean dan atribut objek.

Secara default, objek perangkat kerangka kerja yang ditentukan parameter Perangkat menjadi objek induk untuk objek antrean kerangka kerja baru. Jika driver menentukan objek induk dalam anggota ParentObject 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 antrean saat menghapus objek induk.

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

Untuk informasi selengkapnya tentang WdfIoQueueCreate, lihat Membuat Antrean I/O.

Contoh

Contoh kode berikut adalah bagian dari fungsi panggilan balik EvtDriverDeviceAdd yang membuat antrean I/O default perangkat. Contoh ini menginisialisasi struktur WDF_IO_QUEUE_CONFIG lalu memanggil WdfIoQueueCreate.

NTSTATUS
MyEvtDriverDeviceAdd(
    IN WDFDRIVER  Driver,
    IN PWDFDEVICE_INIT  DeviceInit
    )
{
    WDF_IO_QUEUE_CONFIG  ioQueueConfig;
    WDFQUEUE  hQueue;
...
    WDF_IO_QUEUE_CONFIG_INIT_DEFAULT_QUEUE(
                                           &ioQueueConfig,
                                           WdfIoQueueDispatchSequential
                                           );

    ioQueueConfig.EvtIoDefault = MyEvtIoDefault;

    status = WdfIoQueueCreate(
                              device,
                              &ioQueueConfig,
                              WDF_NO_OBJECT_ATTRIBUTES,
                              &hQueue
                              );
    if (!NT_SUCCESS (status)) {
        return status;
    }
...
}

Persyaratan

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