Fungsi WdfUsbTargetDeviceFormatRequestForControlTransfer (wdfusb.h)

  • Artikel

[Berlaku untuk KMDF dan UMDF]

Metode WdfUsbTargetDeviceFormatRequestForControlTransfer membangun permintaan transfer kontrol USB, tetapi tidak mengirim permintaan.

Sintaks

NTSTATUS WdfUsbTargetDeviceFormatRequestForControlTransfer(
  [in]           WDFUSBDEVICE                  UsbDevice,
  [in]           WDFREQUEST                    Request,
  [in]           PWDF_USB_CONTROL_SETUP_PACKET SetupPacket,
  [in, optional] WDFMEMORY                     TransferMemory,
  [in, optional] PWDFMEMORY_OFFSET             TransferOffset
);

Parameter

[in] UsbDevice

Handel ke objek perangkat USB yang diperoleh dari panggilan sebelumnya ke WdfUsbTargetDeviceCreateWithParameters.

[in] Request

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

[in] SetupPacket

Penunjuk ke struktur WDF_USB_CONTROL_SETUP_PACKET yang dialokasikan penelepon yang menjelaskan transfer kontrol.

[in, optional] TransferMemory

Handel ke objek memori kerangka kerja yang menjelaskan buffer input atau output, tergantung pada perintah khusus perangkat. Penunjuk ini bersifat opsional dan dapat berupa NULL. Untuk informasi selengkapnya, lihat bagian Keterangan berikut ini.

[in, optional] TransferOffset

Penunjuk ke struktur WDFMEMORY_OFFSET yang dialokasikan penelepon yang memasok offset byte opsional dan nilai panjang. Kerangka kerja menggunakan nilai-nilai ini untuk menentukan alamat dan panjang awal, dalam buffer yang ditentukan TransferMemory . Jika pointer ini NULL, kerangka kerja menggunakan seluruh buffer.

Nilai kembali

WdfUsbTargetDeviceFormatRequestForControlTransfer mengembalikan STATUS_SUCCESS 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_INVALID_DEVICE_REQUEST
 Deskriptor memori yang tidak valid ditentukan, atau permintaan I/O yang ditentukan sudah diantrekan ke target I/O.
 

Metode ini juga mungkin mengembalikan nilai NTSTATUS lainnya.

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

Keterangan

Gunakan WdfUsbTargetDeviceFormatRequestForControlTransfer, diikuti oleh WdfRequestSend, untuk mengirim permintaan transfer kontrol USB baik secara sinkron atau asinkron. Atau, gunakan metode WdfUsbTargetDeviceSendControlTransferSynchronously untuk mengirim permintaan secara sinkron.

Anda dapat meneruskan permintaan I/O yang diterima driver Anda dalam antrean I/O, atau Anda dapat membuat dan mengirim permintaan baru. Dalam kedua kasus, kerangka kerja memerlukan objek permintaan dan, tergantung pada jenis transfer kontrol, mungkin beberapa ruang buffer.

Untuk meneruskan permintaan I/O yang diterima driver Anda dalam antrean I/O:

  1. Tentukan handel permintaan yang diterima untuk parameter Permintaan metode WdfUsbTargetDeviceFormatRequestForControlTransfer.
  2. Gunakan buffer input atau output permintaan yang diterima untuk parameter TransferMemory .

    Driver harus memanggil WdfRequestRetrieveInputMemory atau WdfRequestRetrieveOutputMemory untuk mendapatkan handel ke objek memori kerangka kerja yang mewakili buffer input atau output permintaan, dan menggunakan handel tersebut sebagai nilai untuk TransferMemory.

Untuk membuat permintaan I/O baru dan buffer baru:
  1. Buat objek permintaan baru dan berikan handelnya untuk parameter Permintaan metode WdfUsbTargetDeviceFormatRequestForControlTransfer.

    Panggil WdfRequestCreate untuk melakukan pra-alokasi satu atau beberapa objek permintaan. Anda dapat menggunakan kembali objek permintaan ini dengan memanggil WdfRequestReuse. Fungsi panggilan balik EvtDriverDeviceAdd driver Anda dapat melakukan pra-alokasi objek permintaan untuk perangkat.

  2. Sediakan ruang buffer, dan berikan handel buffer untuk parameter TransferMemory metode WdfUsbTargetDeviceFormatRequestForControlTransfer.

    Driver Anda harus menentukan ruang buffer ini sebagai handel WDFMEMORY ke memori yang dikelola kerangka kerja. Driver Anda dapat melakukan salah satu hal berikut:

    Perhatikan bahwa jika driver Anda memanggil WdfRequestRetrieveInputMemory atau WdfRequestRetrieveOutputMemory dan meneruskan handel memori ke WdfUsbTargetDeviceFormatRequestForControlTransfer, driver tidak boleh menyelesaikan permintaan I/O yang diterima sampai setelah driver menghapus, menggunakan kembali, atau memformat ulang objek permintaan baru yang dibuat driver. (WdfUsbTargetDeviceFormatRequestForControlTransfer menaikkan jumlah referensi objek memori. Menghapus, menggunakan kembali, atau memformat ulang objek permintaan mengurangi jumlah referensi objek memori.)
Setelah memanggil WdfUsbTargetDeviceFormatRequestForControlTransfer untuk memformat permintaan I/O, driver harus memanggil WdfRequestSend untuk mengirim permintaan (baik secara sinkron atau asinkron) ke target I/O.

Beberapa panggilan ke WdfUsbTargetDeviceFormatRequestForControlTransfer 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), reformat (panggil WdfUsbTargetDeviceFormatRequestForControlTransfer), dan mengirim ulang (panggil WdfRequestSend) setiap objek permintaan tanpa mempertaruhkan nilai pengembalian STATUS_INSUFFICIENT_RESOURCES dari panggilan selanjutnya ke WdfRequestCreate. Semua panggilan berikutnya ke WdfUsbTargetDeviceFormatRequestForControlTransfer 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.)

Kerangka kerja menetapkan bendera USBD_SHORT_TRANSFER_OK di URB internalnya. Mengatur bendera ini memungkinkan paket terakhir transfer data menjadi kurang dari ukuran paket maksimum.

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

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

Contoh

Contoh kode berikut membuat objek permintaan dan objek memori, lalu menginisialisasi struktur WDF_USB_CONTROL_SETUP_PACKET untuk transfer kontrol "dapatkan status". Selanjutnya, contoh memanggil WdfUsbTargetDeviceFormatRequestForControlTransfer untuk memformat permintaan. Kemudian, contoh menetapkan fungsi panggilan balik CompletionRoutine dan mengirim permintaan ke target I/O.

WDF_USB_CONTROL_SETUP_PACKET packet;
NTSTATUS status;
WDF_OBJECT_ATTRIBUTES attributes;
WDFMEMORY memHandle;

WDF_OBJECT_ATTRIBUTES_INIT(&attributes);

status = WdfRequestCreate(
                          &attributes,
                          WdfUsbTargetDeviceGetIoTarget(
                              UsbTargetDevice,
                              &request
                              )
                          );
if (!NT_SUCCESS(status)){
    return status;
}

WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
attributes.ParentObject = request;
status = WdfMemoryCreate(
                         &attributes,
                         NonPagedPool,
                         0,
                         sizeof(USHORT),
                         &memHandle,
                         NULL
                         );
if (!NT_SUCCESS(status)){
    return status;
}

WDF_USB_CONTROL_SETUP_PACKET_INIT_GET_STATUS(
                                             &packet,
                                             BmRequestToDevice,
                                             0
                                             );
status = WdfUsbTargetDeviceFormatRequestForControlTransfer(
                         UsbTargetDevice,
                         request,
                         &packet,
                         memHandle,
                         NULL
                         );
if (!NT_SUCCESS(status)){
    return status;
}
WdfRequestSetCompletionRoutine(
                               request,
                               MyCompletionRoutine,
                               NULL
                               );
if (WdfRequestSend(
                   request,
                   WdfUsbTargetDeviceGetIoTarget(UsbTargetDevice),
                   NULL
                   ) == FALSE) {
    status = WdfRequestGetStatus(request);
}

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

WDF_USB_CONTROL_SETUP_PACKET

WDF_USB_CONTROL_SETUP_PACKET_INIT_GET_STATUS

WdfUsbTargetDeviceSendControlTransferSynchronously