Fungsi WdfUsbTargetPipeResetSynchronously (wdfusb.h)

[Berlaku untuk KMDF dan UMDF]

Metode WdfUsbTargetPipeResetSynchronously membangun permintaan reset dan mengirimkannya secara sinkron ke pipa USB tertentu.

Sintaks

NTSTATUS WdfUsbTargetPipeResetSynchronously(
  [in]           WDFUSBPIPE                Pipe,
  [in, optional] WDFREQUEST                Request,
  [in, optional] PWDF_REQUEST_SEND_OPTIONS RequestOptions
);

Parameter

[in] Pipe

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

[in, optional] Request

Handel ke objek permintaan kerangka kerja. Parameter ini bersifat opsional dan dapat berupa NULL. Untuk informasi selengkapnya, lihat bagian Keterangan berikut ini.

[in, optional] RequestOptions

Penunjuk ke struktur WDF_REQUEST_SEND_OPTIONS yang dialokasikan pemanggil yang menentukan opsi untuk permintaan. Penunjuk ini bersifat opsional dan dapat berupa NULL. Untuk informasi selengkapnya, lihat bagian Keterangan berikut ini.

Nilai kembali

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

Menampilkan kode Deskripsi
STATUS_INFO_LENGTH_MISMATCH
Ukuran struktur WDF_REQUEST_SEND_OPTIONS yang ditentukan parameter RequestOptions salah.
STATUS_INVALID_PARAMETER
Parameter yang tidak valid terdeteksi.
STATUS_INSUFFICIENT_RESOURCES
Memori tidak cukup tersedia.
STATUS_INVALID_DEVICE_REQUEST
IRQL penelepon tidak PASSIVE_LEVEL, atau permintaan I/O bahwa parameter Permintaan yang ditentukan sudah diantrekan ke target I/O.
STATUS_IO_TIMEOUT
Driver memberikan nilai waktu habis dan permintaan tidak selesai dalam waktu yang dialokasikan.
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 metode WdfUsbTargetPipeResetSynchronously untuk mengirim permintaan reset USB secara sinkron. Untuk mengirim permintaan tersebut secara asinkron, gunakan WdfUsbTargetPipeFormatRequestForReset, diikuti oleh WdfRequestSend.

Sebelum kerangka kerja mengatur ulang pipa USB target I/O, kerangka kerja membatalkan semua permintaan I/O yang tetap berada dalam antrean target I/O. Driver tidak boleh mengirim permintaan I/O tambahan ke target I/O hingga WdfUsbTargetPipeResetSynchronously kembali.

Driver harus memanggil WdfIoTargetStop sebelum memanggil WdfUsbTargetPipeResetSynchronously. Setelah WdfUsbTargetPipeResetSynchronously kembali, driver dapat memanggil WdfIoTargetStart.

Saat driver memanggil WdfUsbTargetPipeResetSynchronously, kerangka kerja mengirimkan permintaan URB_FUNCTION_RESET_PIPE ke target I/O. Untuk informasi selengkapnya tentang mengatur ulang pipa USB, lihat spesifikasi USB.

Metode WdfUsbTargetPipeResetSynchronously tidak kembali sampai permintaan selesai, kecuali driver menyediakan nilai waktu habis dalam struktur WDF_REQUEST_SEND_OPTIONS yang ditunjuk parameter RequestOptions , atau kecuali jika kesalahan terdeteksi.

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

Untuk membuat dan mengirim permintaan baru, berikan handel permintaan NULL untuk parameter Permintaan , atau buat objek permintaan baru dan berikan handelnya:

  • Jika Anda menyediakan handel permintaan NULL , kerangka kerja menggunakan objek permintaan internal. Teknik ini mudah digunakan, tetapi driver tidak dapat membatalkan permintaan.
  • Jika Anda memanggil WdfRequestCreate untuk membuat satu atau beberapa objek permintaan, Anda dapat menggunakan kembali objek permintaan ini dengan memanggil WdfRequestReuse. Teknik ini memungkinkan fungsi panggilan balik EvtDriverDeviceAdd driver Anda untuk melakukan pra-alokasi objek permintaan untuk perangkat. Selain itu, utas driver lain dapat memanggil WdfRequestCancelSentRequest untuk membatalkan permintaan, jika perlu.
Driver Anda dapat menentukan parameter RequestOptionsnon-NULL, baik driver menyediakan parameter permintaannon-NULL atau NULL. Anda dapat, misalnya, menggunakan parameter RequestOptions untuk menentukan nilai waktu habis.

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

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

Contoh

Contoh kode berikut mengirimkan permintaan reset ke pipa perangkat USB.

NTSTATUS  status;

status = WdfUsbTargetPipeResetSynchronously(
                                            Pipe, 
                                            WDF_NO_HANDLE,
                                            NULL
                                            );

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 PASSIVE_LEVEL
Aturan kepatuhan DDI DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestForUrbXrb(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)

Lihat juga

WdfObjectDereference

WdfRequestCancelSentRequest

WdfRequestSend

WdfUsbTargetPipeAbortSynchronously