Fungsi WdfUsbTargetPipeFormatRequestForAbort (wdfusb.h)

Artikel
08/08/2023

[Berlaku untuk KMDF dan UMDF]

Metode WdfUsbTargetPipeFormatRequestForAbort membangun permintaan pembatalan untuk pipa USB tertentu, tetapi tidak mengirim permintaan.

Sintaks

NTSTATUS WdfUsbTargetPipeFormatRequestForAbort(
  [in] WDFUSBPIPE Pipe,
  [in] WDFREQUEST Request
);

Parameter

[in] Pipe

Handel ke objek pipa kerangka kerja yang diperoleh dengan memanggil WdfUsbInterfaceGetConfiguredPipe.

[in] Request

Handel ke objek permintaan kerangka kerja. Untuk informasi selengkapnya, lihat bagian Keterangan berikut ini.

Nilai kembali

WdfUsbTargetPipeFormatRequestForAbort mengembalikan nilai status penyelesaian target I/O jika operasi berhasil. Jika tidak, metode ini dapat mengembalikan salah satu nilai berikut:

Menampilkan kode	Deskripsi
STATUS_INVALID_PARAMETER	Parameter yang tidak valid terdeteksi.
STATUS_INSUFFICIENT_RESOURCES	Memori tidak cukup tersedia.
STATUS_REQUEST_NOT_ACCEPTED	Paket permintaan I/O (IRP) yang diwakili parameter Permintaan tidak menyediakan struktur IO_STACK_LOCATION yang cukup untuk memungkinkan driver meneruskan permintaan.

Metode ini juga mungkin mengembalikan nilai NTSTATUS lainnya.

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

Keterangan

Gunakan WdfUsbTargetPipeFormatRequestForAbort, diikuti oleh WdfRequestSend, untuk mengirim permintaan pembatalan USB baik secara sinkron atau asinkron. Atau, gunakan metode WdfUsbTargetPipeAbortSynchronously untuk mengirim permintaan secara sinkron.

Permintaan pembatalan USB menyebabkan target I/O driver membatalkan semua permintaan I/O yang telah dikirim ke pipa. Ketika driver memanggil WdfRequestSend, kerangka kerja mengirimkan permintaan URB_FUNCTION_ABORT_PIPE ke target I/O. Untuk informasi selengkapnya tentang membatalkan operasi pada pipa USB (juga disebut "membatalkan pipa"), lihat spesifikasi USB.

Anda dapat meneruskan permintaan I/O yang diterima driver Anda dalam antrean I/O, atau Anda dapat membuat dan mengirim permintaan baru.

Untuk meneruskan permintaan I/O yang diterima driver Anda dalam antrean I/O, tentukan handel permintaan yang diterima untuk parameter Permintaan metode WdfUsbTargetPipeFormatRequestForAbort.

Untuk membuat permintaan I/O baru, panggil WdfRequestCreate untuk melakukan pra-alokasi objek permintaan. Berikan handel permintaan untuk parameter Permintaan metode WdfUsbTargetPipeFormatRequestForAbort. Anda dapat menggunakan kembali objek permintaan dengan memanggil WdfRequestReuse. Fungsi panggilan balik EvtDriverDeviceAdd driver Anda dapat melakukan pra-alokasi objek permintaan untuk perangkat.

Setelah memanggil WdfUsbTargetPipeFormatRequestForAbort untuk memformat permintaan I/O, driver harus memanggil WdfRequestSend untuk mengirim permintaan (baik secara sinkron atau asinkron) ke target I/O.

Beberapa panggilan ke WdfUsbTargetPipeFormatRequestForAbort yang menggunakan permintaan yang sama tidak menyebabkan alokasi sumber daya tambahan. Oleh karena itu, untuk mengurangi kemungkinan WdfRequestCreate akan mengembalikan STATUS_INSUFFICIENT_RESOURCES, fungsi panggilan balik EvtDriverDeviceAdd driver Anda dapat memanggil WdfRequestCreate untuk melakukan pra-alokasi satu atau beberapa objek permintaan untuk perangkat. Driver kemudian dapat menggunakan kembali (panggil WdfRequestReuse), format ulang (panggil WdfUsbTargetPipeFormatRequestForAbort), dan mengirim ulang (panggil WdfRequestSend) setiap objek permintaan tanpa mempertaruhkan nilai pengembalian STATUS_INSUFFICIENT_RESOURCES dari panggilan selanjutnya ke WdfRequestCreate. Semua panggilan berikutnya ke WdfUsbTargetPipeFormatRequestForAbort untuk objek permintaan yang digunakan kembali akan mengembalikan STATUS_SUCCESS, jika nilai parameter tidak berubah. (Jika driver tidak memanggil metode pemformatan permintaan yang sama setiap kali, sumber daya tambahan mungkin dialokasikan.)

Untuk informasi tentang mendapatkan informasi status setelah permintaan I/O selesai, lihat Mendapatkan Informasi Penyelesaian.

Untuk informasi selengkapnya tentang metode WdfUsbTargetPipeFormatRequestForAbort dan target I/O USB, lihat Target I/O USB.

Contoh

Contoh kode berikut memformat permintaan pembatalan untuk pipa USB, mendaftarkan fungsi panggilan balik CompletionRoutine , dan mengirim permintaan.

status = WdfUsbTargetPipeFormatRequestForAbort(
                                               pipe,
                                               Request
                                               );
if (!NT_SUCCESS(status)) {
    goto Exit;
}

WdfRequestSetCompletionRoutine(
                               Request,
                               AbortCompletionRoutine,
                               pipe
                               );

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	wdfusb.h (termasuk Wdfusb.h)
Pustaka	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
Aturan kepatuhan DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestFormattedValid(kmdf), RequestForUrbXrb(kmdf), RequestSendAndForgetNoFormatting(kmdf), RequestSendAndForgetNoFormatting2(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)

Lihat juga

WdfUsbInterfaceGetConfiguredPipe

Bagikan melalui