Fungsi WdfUsbTargetDeviceFormatRequestForString (wdfusb.h)

Artikel
02/27/2024

[Berlaku untuk KMDF dan UMDF]

Metode WdfUsbTargetDeviceFormatRequestForString membangun permintaan untuk deskriptor string USB yang terkait dengan nilai indeks string perangkat USB.

Sintaks

NTSTATUS WdfUsbTargetDeviceFormatRequestForString(
  [in]           WDFUSBDEVICE      UsbDevice,
  [in]           WDFREQUEST        Request,
  [in]           WDFMEMORY         Memory,
  [in, optional] PWDFMEMORY_OFFSET Offset,
  [in]           UCHAR             StringIndex,
  [in, optional] USHORT            LangID
);

Parameter

[in] UsbDevice

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

[in] Request

Handel ke objek permintaan kerangka kerja.

[in] Memory

Handel ke objek memori kerangka kerja.

[in, optional] Offset

Penunjuk ke struktur WDFMEMORY_OFFSET yang dialokasikan penelepon yang memasok nilai offset dan panjang byte opsional. Kerangka kerja menggunakan nilai-nilai ini untuk menentukan alamat dan panjang awal, dalam buffer output, untuk menyimpan deskriptor string. Jika pointer ini ADALAH NULL, deskriptor disimpan di awal buffer output, dan panjang string maksimum adalah panjang buffer.

[in] StringIndex

Nilai indeks yang mengidentifikasi string. Nilai indeks ini diperoleh dari struktur USB_DEVICE_DESCRIPTOR, USB_CONFIGURATION_DESCRIPTOR, atau USB_INTERFACE_DESCRIPTOR .

[in, optional] LangID

Pengidentifikasi bahasa. String akan diambil untuk bahasa yang ditentukan pengidentifikasi ini. Untuk informasi tentang mendapatkan pengidentifikasi bahasa yang didukung perangkat, lihat spesifikasi USB.

Nilai kembali

WdfUsbTargetDeviceFormatRequestForString mengembalikan STATUS_SUCCESS jika operasi berhasil. Jika tidak, metode ini dapat mengembalikan salah satu nilai berikut:

Menampilkan kode	Deskripsi
STATUS_INVALID_PARAMETER	Jumlah byte buffer bukan angka genap.
STATUS_INSUFFICIENT_RESOURCES	Memori tidak cukup.
STATUS_INTEGER_OVERFLOW	Offset yang ditentukan Offset tidak valid.

Metode ini juga dapat mengembalikan nilai NTSTATUS lainnya.

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

Keterangan

Setelah WdfUsbTargetDeviceFormatRequestForString kembali, driver harus memanggil WdfRequestSend untuk mengirim permintaan. Setelah WdfRequestSend kembali, driver dapat meneruskan handel Memori ke WdfMemoryGetBuffer untuk mendapatkan penunjuk ke buffer memori. Buffer akan berisi struktur USB_STRING_DESCRIPTOR yang menjelaskan deskriptor string.

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

Contoh

Contoh kode berikut membuat objek permintaan dan objek memori, dan meneruskan handel objek ke WdfUsbTargetDeviceFormatRequestForString. Kemudian, contoh menetapkan fungsi panggilan balik CompletionRoutine untuk permintaan dan mengirim permintaan ke target I/O.

NTSTATUS status;
PDEVICE_CONTEXT deviceContext = GetDeviceContext(device);
WDFREQUEST request;
WDFMEMORY memHandle;
WDF_OBJECT_ATTRIBUTES attributes;

WDF_OBJECT_ATTRIBUTES_INIT(&attributes);

status = WdfRequestCreate(
    &attributes,
    WdfUsbTargetDeviceGetIoTarget(deviceContext->UsbTargetDevice),
    &request);

if (!NT_SUCCESS(status)) {
    return status;
}

status = WdfMemoryCreate(
    WDF_NO_OBJECT_ATTRIBUTES,
    NonPagedPool,
    0,
    STR_DESC_STRING_SIZE,
    &memHandle,
    NULL);
if (!NT_SUCCESS(status)) {
    WdfObjectDelete(request);
    return status;
}

status = WdfUsbTargetDeviceFormatRequestForString(
    deviceContext->UsbTargetDevice,
    request,
    memHandle,
    NULL,
    deviceContext->UsbDeviceDescr.iManufacturer,
    0x0409);

if (NT_SUCCESS(status)) {
    WdfRequestSetCompletionRoutine(
        request,
        MyCompletionRoutine,
        NULL);

    if (WdfRequestSend(
            request,
            WdfUsbTargetDeviceGetIoTarget(deviceContext->UsbTargetDevice),
            NULL)) {
        status = STATUS_PENDING;
    }
    
}
else {
    WdfObjectDelete(memHandle);
    WdfObjectDelete(request);
    return status;
}

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)