Fungsi WdfRequestCreate (wdfrequest.h)

Artikel
08/08/2023

[Berlaku untuk KMDF dan UMDF]

Metode WdfRequestCreate membuat objek permintaan kerangka kerja kosong.

Sintaks

NTSTATUS WdfRequestCreate(
  [in, optional] PWDF_OBJECT_ATTRIBUTES RequestAttributes,
  [in, optional] WDFIOTARGET            IoTarget,
  [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, optional] IoTarget

Handel ke objek target I/O kerangka kerja. Parameter ini bersifat opsional dan dapat berupa NULL. Jika non-NULL, WdfRequestCreate memverifikasi bahwa driver akhirnya dapat mengirim permintaan ke target I/O yang ditentukan.

[out] Request

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

Nilai kembali

WdfRequestCreate 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_INSUFFICIENT_RESOURCES	Sumber daya sistem tidak cukup untuk menyelesaikan operasi.
STATUS_REQUEST_NOT_ACCEPTED	Array permintaan lokasi tumpukan I/O tidak cukup besar untuk memungkinkan driver mengirim permintaan ke target I/O yang ditentukan.

Untuk daftar nilai pengembalian tambahan, lihat Kesalahan Pembuatan Objek Kerangka Kerja.

Metode ini mungkin juga mengembalikan nilai NTSTATUS lainnya.

Keterangan

Driver berbasis kerangka kerja dapat memanggil WdfRequestCreate untuk membuat permintaan baru yang kemudian diteruskan driver ke fungsi kerangka kerja lain untuk inisialisasi. Misalnya, driver untuk perangkat USB mungkin memanggil WdfUsbTargetPipeFormatRequestForRead untuk memformat permintaan baca baru.

Driver berbasis kerangka kerja yang berkomunikasi dengan driver WDM mungkin menentukan konten permintaan dengan memanggil WdfRequestCreateFromIrp.

Jika driver memanggil WdfRequestCreate untuk membuat objek permintaan, driver tidak boleh memanggil WdfRequestComplete untuk objek permintaan. Sebagai gantinya, driver harus memanggil WdfObjectDelete setelah selesai menggunakan objek permintaan. Untuk informasi selengkapnya, lihat Menyelesaikan Permintaan I/O.

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 memanggil WdfRequestCreate, lihat Membuat Objek Permintaan Kerangka Kerja.

Contoh

Contoh kode berikut membuat objek target I/O, menginisialisasi struktur WDF_OBJECT_ATTRIBUTES , dan memanggil WdfRequestCreate. Induk objek permintaan baru adalah objek target I/O.

WDF_OBJECT_ATTRIBUTES  attributes;
WDFREQUEST newRequest;
WDFIOTARGET ioTarget;
...
status = WdfIoTargetCreate(
                           Device,
                           WDF_NO_OBJECT_ATTRIBUTES,
                           &ioTarget
                           );
  ...
WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
attributes.ParentObject = ioTarget;

status = WdfRequestCreate(
                          &attributes,
                          ioTarget,
                          &newRequest
                          );

if (!NT_SUCCESS(status)) {
    return status;
}

Persyaratan

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