WdfUsbTargetDeviceFormatRequestForString-Funktion (wdfusb.h)

Artikel
02/07/2025

[Gilt für KMDF und UMDF]

Die WdfUsbTargetDeviceFormatRequestForString Methode erstellt eine Anforderung für den USB-Zeichenfolgendeskriptor, der dem Zeichenfolgenindexwert eines USB-Geräts zugeordnet ist.

Syntax

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

Ein Handle für ein USB-Geräteobjekt, das aus einem vorherigen Aufruf von WdfUsbTargetDeviceCreateWithParametersabgerufen wurde.

[in] Request

Ein Handle zu einem Framework-Anforderungsobjekt.

[in] Memory

Ein Handle für ein Framework-Speicherobjekt.

[in, optional] Offset

Ein Zeiger auf eine vom Aufrufer zugewiesene WDFMEMORY_OFFSET Struktur, die optionale Byteoffset- und Längenwerte bereitstellt. Das Framework verwendet diese Werte, um die Anfangsadresse und -länge innerhalb des Ausgabepuffers zum Speichern des Zeichenfolgendeskriptors zu bestimmen. Wenn dieser Zeiger NULL-ist, wird der Deskriptor am Anfang des Ausgabepuffers gespeichert, und die maximale Zeichenfolgenlänge ist die Pufferlänge.

[in] StringIndex

Ein Indexwert, der die Zeichenfolge identifiziert. Dieser Indexwert wird aus einer USB_DEVICE_DESCRIPTOR, USB_CONFIGURATION_DESCRIPTORoder USB_INTERFACE_DESCRIPTOR Struktur abgerufen.

[in, optional] LangID

Ein Sprachbezeichner. Die Zeichenfolge wird für die Sprache abgerufen, die dieser Bezeichner angibt. Informationen zum Abrufen der unterstützten Sprach-IDs eines Geräts finden Sie in der USB-Spezifikation.

Rückgabewert

WdfUsbTargetDeviceFormatRequestForString gibt STATUS_SUCCESS zurück, wenn der Vorgang erfolgreich ist. Andernfalls kann diese Methode einen der folgenden Werte zurückgeben:

Rückgabecode	Beschreibung
STATUS_INVALID_PARAMETER	Die Byteanzahl des Puffers war keine gerade Zahl.
STATUS_INSUFFICIENT_RESOURCES	Nicht genügend Arbeitsspeicher vorhanden.
STATUS_INTEGER_OVERFLOW	Der Offset, der Offset- angibt, war ungültig.

Diese Methode kann auch andere NTSTATUS-Wertezurückgeben.

Wenn der Treiber ein ungültiges Objekthandle bereitstellt, tritt eine Fehlerüberprüfung auf.

Bemerkungen

Nachdem WdfUsbTargetDeviceFormatRequestForString zurückgegeben wurde, muss der Treiber WdfRequestSend- aufrufen, um die Anforderung zu senden. Nachdem WdfRequestSend zurückgegeben wurde, kann der Treiber das Memory Handle an WdfMemoryGetBuffer- übergeben, um einen Zeiger auf den Speicherpuffer abzurufen. Der Puffer enthält eine USB_STRING_DESCRIPTOR Struktur, die den Zeichenfolgendeskriptor beschreibt.

Weitere Informationen zur WdfUsbTargetDeviceFormatRequestForString Methode und USB-E/A-Zielen finden Sie unter USB I/O Targets.

Beispiele

Im folgenden Codebeispiel wird ein Anforderungsobjekt und ein Speicherobjekt erstellt und die Objekthandles an WdfUsbTargetDeviceFormatRequestForStringübergeben. Anschließend legt das Beispiel eine CompletionRoutine Rückruffunktion für die Anforderung fest und sendet die Anforderung an ein E/A-Ziel.

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;
}

Anforderungen

Anforderung	Wert
Zielplattform-	Universal
Minimale KMDF-Version	1.0
Mindest-UMDF-Version	2.0
Header-	wdfusb.h (include Wdfusb.h)
Library	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL-	<=DISPATCH_LEVEL
DDI-Complianceregeln	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestFormattedValid(kmdf), RequestForUrbXrb(kmdf), RequestSendAndForgetNoFormatting(kmdf), RequestSendAndForgetNoFormatting2(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)