Fungsi WdfRequestCompleteWithInformation (wdfrequest.h)

Artikel
08/08/2023

[Berlaku untuk KMDF dan UMDF]

Metode WdfRequestCompleteWithInformation menyimpan informasi penyelesaian lalu menyelesaikan permintaan I/O tertentu dengan status penyelesaian yang disediakan.

Sintaks

void WdfRequestCompleteWithInformation(
  [in] WDFREQUEST Request,
  [in] NTSTATUS   Status,
  [in] ULONG_PTR  Information
);

Parameter

[in] Request

Handel ke objek permintaan.

[in] Status

Nilai NTSTATUS yang mewakili status penyelesaian permintaan. Nilai status yang valid termasuk, tetapi tidak terbatas pada, berikut ini:

STATUS_SUCCESS

Driver berhasil menyelesaikan permintaan.

STATUS_CANCELLED

Driver membatalkan permintaan.

STATUS_UNSUCCESSFUL

Driver mengalami kesalahan saat memproses permintaan.

[in] Information

ULONG_PTR yang diatur ke nilai yang bergantung pada permintaan. Misalnya, setelah berhasil menyelesaikan permintaan transfer, ini diatur ke jumlah byte yang ditransfer. Bidang ini tidak dapat diperluas oleh pengemudi.

Nilai kembali

Tidak ada

Keterangan

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

Untuk permintaan baca, tulis, dan IOCTL, driver perlu memanggil WdfRequestCompleteWithInformation

Untuk permintaan transfer non-data, memanggil WdfRequestComplete sebagai gantinya adalah opsi.

Memanggil WdfRequestCompleteWithInformation setara dengan memanggil WdfRequestSetInformation lalu memanggil WdfRequestComplete.

Setelah panggilan ke WdfRequestCompleteWithInformation kembali, handel permintaan tidak lagi valid kecuali driver telah memanggil WdfObjectReference untuk menambahkan satu atau beberapa jumlah referensi tambahan ke objek permintaan. Perhatikan bahwa setelah WdfRequestCompleteWithInformation kembali, driver tidak boleh mencoba mengakses struktur IRP WDM terkait, bahkan jika telah disebut WdfObjectReference.

Ketika driver Anda memanggil WdfRequestCompleteWithInformation, kerangka kerja menyediakan nilai default yang digunakan sistem untuk meningkatkan prioritas run-time utas yang meminta operasi I/O. Untuk informasi tentang nilai peningkatan prioritas default, lihat Menentukan Peningkatan Prioritas Saat Menyelesaikan Permintaan I/O. Driver Anda dapat memanggil WdfRequestCompleteWithPriorityBoost untuk mengambil alih nilai peningkatan prioritas default.

Untuk informasi selengkapnya tentang memanggil WdfRequestCompleteWithInformation, lihat Menyelesaikan Permintaan I/O.

Untuk contoh kode yang menunjukkan cara menggunakan WdfRequestCompleteWithInformation untuk mengambil jumlah byte yang disalin, lihat sampel driver VirtualSerial2.

Contoh

Contoh kode berikut menunjukkan bagaimana driver untuk perangkat USB mungkin memanggil WdfRequestCompleteWithInformation dalam fungsi panggilan balik CompletionRoutine .

VOID
EvtRequestReadCompletionRoutine(
    IN WDFREQUEST  Request,
    IN WDFIOTARGET  Target,
    PWDF_REQUEST_COMPLETION_PARAMS  CompletionParams,
    IN WDFCONTEXT  Context
    )
{    
    NTSTATUS  status;
    size_t  bytesRead = 0;
    PWDF_USB_REQUEST_COMPLETION_PARAMS  usbCompletionParams;

    UNREFERENCED_PARAMETER(Target);
    UNREFERENCED_PARAMETER(Context);

    status = CompletionParams->IoStatus.Status;
    usbCompletionParams = CompletionParams->Parameters.Usb.Completion;
    bytesRead =  usbCompletionParams->Parameters.PipeRead.Length;
 
    if (NT_SUCCESS(status)){
        TraceEvents(
                    TRACE_LEVEL_INFORMATION,
                    DBG_READ,
                    "Number of bytes read: %I64d\n",
                    (INT64)bytesRead
                    );
    } else {
        TraceEvents(
                    TRACE_LEVEL_ERROR,
                    DBG_READ,
                    "Read failed - request status 0x%x UsbdStatus 0x%x\n",
                    status,
                    usbCompletionParams->UsbdStatus
                    );
    }
    WdfRequestCompleteWithInformation(
                                      Request,
                                      status,
                                      bytesRead
                                      );
    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	<=DISPATCH_LEVEL
Aturan kepatuhan DDI	BufAfterReqCompletedIntIoctl(kmdf), BufAfterReqCompletedIntIoctlA(kmdf), BufAfterReqCompletedIoctl(kmdf), BufAfterReqCompletedIoctlA(kmdf), BufAfterReqCompletedRead(kmdf), BufAfterReqCompletedReadA(kmdf), BufAfterReqCompletedWrite(kmdf), BufAfterReqCompletedWriteA(kmdf), CompleteCanceledReq(kmdf), DeferredRequestCompleted(kmdf), DoubleCompletion(kmdf), DoubleCompletionLocal(kmdf), DriverCreate(kmdf), EvtIoStopCancel(kmdf), EvtIoStopCompleteOrStopAck(kmdf), EvtSurpriseRemoveNoRequestComplete(kmdf), InvalidReqAccess(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), MarkCancOnCancReqLocal(kmdf), MdlAfterReqCompletedIntIoctl(kmdf), MdlAfterReqCompletedIntIoctlA(kmdf), MdlAfterReqCompletedIoctl(kmdf), MdlAfterReqCompletedIoctlA(kmdf), MdlAfterReqCompletedRead(kmdf), MdlAfterReqCompletedReadA(kmdf), MdlAfterReqCompletedWrite(kmdf), MdlAfterReqCompletedWriteA(kmdf), MemAfterReqCompletedIntIoctl(kmdf), MemAfterReqCompletedIntIoctlA(kmdf), MemAfterReqCompletedIoctl(kmdf), MemAfterReqCompletedIoctlA(kmdf), MemAfterReqCompletedRead(kmdf), MemAfterReqCompletedReadA(kmdf), MemAfterReqCompletedWrite(kmdf), MemAfterReqCompletedWriteA(kmdf), NoCancelFromEvtSurpriseRemove(kmdf), ReqDelete(kmdf), ReqIsCancOnCancReq(kmdf), ReqNotCanceledLocal(kmdf), ReqSendFail(kmdf), RequestCompleted(kmdf), RequestCompletedLocal(kmdf)