Fungsi WdfRequestSend (wdfrequest.h)
[Berlaku untuk KMDF dan UMDF]
Metode WdfRequestSend mengirimkan permintaan I/O tertentu ke target I/O tertentu.
Sintaks
BOOLEAN WdfRequestSend(
[in] WDFREQUEST Request,
[in] WDFIOTARGET Target,
PWDF_REQUEST_SEND_OPTIONS Options
);
Parameter
[in] Request
Handel ke objek permintaan kerangka kerja.
[in] Target
Handel ke objek target I/O kerangka kerja. Untuk informasi selengkapnya tentang cara mendapatkan handel ini, lihat bagian Keterangan berikut ini.
Options
Penunjuk ke struktur WDF_REQUEST_SEND_OPTIONS yang berisi opsi permintaan yang disediakan pemanggil. Parameter ini bersifat opsional dan dapat berupa NULL jika Anda tidak ingin mengaktifkan opsi permintaan apa pun.
Nilai kembali
WdfRequestSend mengembalikan TRUE jika permintaan dikirim ke target. Jika tidak, metode ini mengembalikan FALSE, dan memanggil WdfRequestGetStatus mengembalikan status yang gagal dalam pengujian NT_SUCCESS().
Pemeriksaan bug terjadi jika driver menyediakan handel objek yang tidak valid.
Keterangan
Objek permintaan yang ditentukan driver untuk parameter Permintaan dapat berupa objek yang diterimanya atau objek yang dibuatnya dengan memanggil metode WdfRequestCreate .
Untuk mendapatkan handel ke objek target I/O, driver dapat melakukan salah satu hal berikut:
- Jika driver menggunakan target I/O umum, driver memanggil WdfDeviceGetIoTarget. Untuk informasi selengkapnya, lihat Menginisialisasi Target I/O Umum.
- Jika driver menggunakan target I/O khusus, driver memanggil satu atau beberapa metode yang ditentukan objek target khusus. Misalnya, driver untuk perangkat USB dapat memanggil WdfUsbTargetDeviceGetIoTarget atau WdfUsbTargetPipeGetIoTarget.
Jika WdfRequestSend gagal, atau jika driver Anda mengatur bendera WDF_REQUEST_SEND_OPTION_SYNCHRONOUS, driver dapat segera memanggil WdfRequestGetStatus setelah memanggil WdfRequestSend.
Jika WdfRequestSend berhasil dan driver Anda tidak mengatur bendera WDF_REQUEST_SEND_OPTION_SYNCHRONOUS, driver biasanya memanggil WdfRequestGetStatus dari dalam fungsi panggilan balik CompletionRoutine .
Jika driver mengirim permintaan secara sinkron, kami sarankan driver menetapkan nilai waktu habis dalam struktur WDF_REQUEST_SEND_OPTIONS dan bendera waktu habis di anggota Bendera struktur ini.
Jika driver menyediakan nilai waktu habis, driver harus memanggil WdfRequestAllocateTimer sebelum memanggil WdfRequestSend. Ini memastikan bahwa WdfRequestSend tidak akan gagal jika sumber daya sistem tidak mencukup untuk mengalokasikan timer.
Jika driver mengatur bendera WDF_REQUEST_SEND_OPTION_SYNCHRONOUS , driver harus memanggil WdfRequestSend di IRQL = PASSIVE_LEVEL. Jika bendera ini tidak diatur, driver harus memanggil metode ini di IRQL <= DISPATCH_LEVEL. WdfRequestSend mengirimkan permintaan di IRQL penelepon.
Driver tidak dapat memanggil WdfRequestSend untuk mengirim permintaan I/O ke pipa USB, jika driver telah mengonfigurasi pembaca berkelanjutan untuk pipa.
Saat mengirim permintaan ke driver UMDF, driver mode kernel harus mengikuti pembatasan IRQL yang diuraikan dalam Mendukung klien Kernel-Mode di Driver UMDF.
Untuk informasi selengkapnya tentang WdfRequestSend, lihat Meneruskan Permintaan I/O.
Contoh
Contoh kode berikut adalah versi singkat dari fungsi panggilan balik EvtIoWrite dari driver sampel kmdf_fx2 . Fungsi ini memvalidasi panjang buffer permintaan, mendapatkan handel ke buffer, memformat permintaan untuk target USB, dan mengirim permintaan.
VOID
OsrFxEvtIoWrite(
IN WDFQUEUE Queue,
IN WDFREQUEST Request,
IN size_t Length
)
{
WDFUSBPIPE pipe;
NTSTATUS status;
WDFMEMORY reqMemory;
PDEVICE_CONTEXT pDeviceContext;
UNREFERENCED_PARAMETER(Queue);
//
// Check if the transfer size is valid.
//
if (Length > MAX_TRANSFER_BUFFER_SIZE) {
status = STATUS_INVALID_PARAMETER;
goto Exit;
}
//
// Get driver-defined context space from
// the device object. The driver stored the
// pipe handle there.
//
pDeviceContext = GetDeviceContext(WdfIoQueueGetDevice(Queue));
pipe = pDeviceContext->BulkWritePipe;
//
// Get a handle to a memory object that represents
// the input buffer.
//
status = WdfRequestRetrieveInputMemory(Request, &reqMemory);
if (!NT_SUCCESS(status)){
goto Exit;
}
//
// Format the request so it can be sent to a USB target.
//
status = WdfUsbTargetPipeFormatRequestForWrite(
pipe,
Request,
reqMemory,
NULL // Offsets
);
if (!NT_SUCCESS(status)) {
goto Exit;
}
//
// Set a CompletionRoutine callback function.
//
WdfRequestSetCompletionRoutine(
Request,
EvtRequestReadCompletionRoutine,
pipe
);
//
// Send the request. If an error occurs, complete the request.
//
if (WdfRequestSend(
Request,
WdfUsbTargetPipeGetIoTarget(pipe),
WDF_NO_SEND_OPTIONS
) == FALSE) {
status = WdfRequestGetStatus(Request);
goto Exit;
}
Exit:
if (!NT_SUCCESS(status)) {
WdfRequestCompleteWithInformation(
Request,
status,
0
);
}
return;
}
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 | Lihat bagian Keterangan. |
| Aturan kepatuhan DDI | DeferredRequestCompleted(kmdf), DriverCreate(kmdf), InvalidReqAccess(kmdf), InvalidReqAccessLocal(kmdf), KmdfIrql(kmdf), ReqCompletionRoutine(kmdf), ReqMarkCancelableSend(kmdf), ReqSendFail(kmdf), ReqSendWhileSpinlock(kmdf), RequestCompleted(kmdf), RequestCompletedLocal(kmdf), RequestFormattedValid(kmdf), RequestGetStatusValid(kmdf), RequestSendAndForgetNoFormatting(kmdf), RequestSendAndForgetNoFormatting2(kmdf), SyncReqSend2(kmdf), WdfRequestSendSyncAtDispatch(kmdf), WdfRequestSendSyncAtDispatch2(kmdf) |