Fungsi WdfRequestCreateFromIrp (wdfrequest.h)

Artikel
02/29/2024

[Hanya berlaku untuk KMDF]

Metode WdfRequestCreateFromIrp membuat objek permintaan kerangka kerja dari IRP WDM tertentu.

Sintaks

NTSTATUS WdfRequestCreateFromIrp(
  [in, optional] PWDF_OBJECT_ATTRIBUTES RequestAttributes,
  [in]           PIRP                   Irp,
  [in]           BOOLEAN                RequestFreesIrp,
  [out]          WDFREQUEST             *Request
);

Parameter

[in, optional] RequestAttributes

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

[in] Irp

Penunjuk ke struktur IRP yang berisi paket permintaan I/O WDM.

[in] RequestFreesIrp

Nilai Boolean yang, jika TRUE, menunjukkan bahwa kerangka kerja menghapus IRP saat handel permintaan dihancurkan. Jika FALSE, driver harus memanggil IoFreeIrp untuk menghapus IRP, menggunakan langkah-langkah yang ditunjukkan bagian Contoh berikut.

[out] Request

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

Mengembalikan nilai

WdfRequestCreateFromIrp mengembalikan STATUS_SUCCESS jika operasi berhasil. Untuk daftar nilai pengembalian tambahan, lihat Kesalahan Pembuatan Objek Kerangka Kerja.

Metode ini mungkin juga mengembalikan nilai NTSTATUS lainnya.

Keterangan

Biasanya, driver berbasis kerangka kerja memanggil WdfRequestCreateFromIrp hanya jika mereka menerima runtime integrasi WDM dalam rutinitas pengiriman WDM dan kemudian meneruskan permintaan ke target I/O kerangka kerja.

Jika driver memanggil WdfRequestCreateFromIrp untuk membuat objek permintaan, driver tidak boleh memanggil WdfRequestComplete untuk objek permintaan. Sebagai gantinya, driver harus memanggil WdfObjectDelete setelah selesai menggunakan objek permintaan.

Selain itu, driver tidak boleh memanggil WdfRequestRetrieveOutputMemory, WdfRequestRetrieveOutputBuffer, WdfRequestRetrieveInputBuffer, atau WdfRequestRetrieveInputMemory dengan objek permintaan baru.

Secara default, induk objek permintaan baru adalah objek driver kerangka kerja yang dibuat metode WdfDriverCreate . Anda dapat menggunakan anggota ParentObject dari struktur WDF_OBJECT_ATTRIBUTES untuk menentukan induk yang berbeda. Kerangka kerja menghapus objek permintaan saat menghapus objek induk. Jika driver Anda tidak mengubah induk default, driver harus menghapus objek permintaan setelah selesai menggunakan objek ; jika tidak, objek permintaan akan tetap ada sampai manajer I/O membongkar driver Anda.

Untuk informasi selengkapnya tentang membuat objek permintaan kerangka kerja, lihat Membuat Objek Permintaan Kerangka Kerja.

Driver berbasis kerangka kerja tidak boleh menggunakan anggota Tail.Overlay.DriverContext dari struktur IRP , karena kerangka kerja menggunakan anggota ini.

Contoh

Contoh 1

Contoh kode berikut membuat objek permintaan kerangka kerja dari IRP WDM tertentu lalu menghapusnya. Contoh ini mengatur parameter RequestFreesIrp ke TRUE, sehingga kerangka kerja menghapus IRP saat handel permintaan dihancurkan.

WDFREQUEST request;
PIRP irp;

//Creation
status = WdfRequestCreateFromIrp(
                                 WDF_NO_OBJECT_ATTRIBUTES,
                                 irp,
                                 TRUE,
                                 &request
                                 );
...
//Deletion
WdfObjectDelete(request);

Contoh 2

Contoh kode berikut juga membuat objek permintaan kerangka kerja dari IRP WDM tertentu lalu menghapusnya. Contoh ini mengatur parameter RequestFreesIrp ke FALSE, sehingga driver harus memanggil IoFreeIrp untuk menghapus IRP. Semua panggilan fungsi dalam contoh diperlukan.

WDF_REQUEST_REUSE_PARAMS params;
WDFREQUEST request;
PIRP irp;

//Creation
status = WdfRequestCreateFromIrp(
                                 WDF_NO_OBJECT_ATTRIBUTES,
                                 irp,
                                 FALSE,
                                 &request
                                 );
...
//Deletion
WDF_REQUEST_REUSE_PARAMS_INIT(
                              &params,
                              WDF_REQUEST_REUSE_NO_FLAGS,
                              STATUS_SUCCESS
                              );
WDF_REQUEST_REUSE_PARAMS_SET_NEW_IRP(
                                     &params,
                                     NULL
                                     );
status = WdfRequestReuse(
                         request,
                         &params
                         );
ASSERT(NT_SUCCESS(status));
IoFreeIrp(irp);
WdfObjectDelete(request);

Persyaratan

Persyaratan	Nilai
Target Platform	Universal
Versi KMDF minimum	1,0
Header	wdfrequest.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)