Fungsi WdfRequestSend (wdfrequest.h)

Artikel
06/20/2023

[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.

Secara default, WdfRequestSend mengirimkan permintaan ke target secara asinkron, yang berarti segera kembali tanpa menunggu permintaan selesai. Secara opsional, permintaan dapat dikirimkan secara sinkron, yang berarti WdfRequestSend tidak kembali sampai driver menyelesaikan permintaan. Untuk mengirim permintaan secara sinkron, driver harus mengatur bendera WDF_REQUEST_SEND_OPTION_SYNCHRONOUS dalam struktur WDF_REQUEST_SEND_OPTIONS .

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)