WdfUsbTargetDeviceFormatRequestForString-Funktion (wdfusb.h)

Artikel
02/29/2024

[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 von einem vorherigen Aufruf von WdfUsbTargetDeviceCreateWithParameters abgerufen wurde.

[in] Request

Ein Handle für ein Frameworkanforderungsobjekt.

[in] Memory

Ein Handle für ein Frameworkspeicherobjekt.

[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 der Zeichenfolgenbeschreibung 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_DESCRIPTOR- oder 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 Sprachbezeichner 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	Es war nicht genügend Arbeitsspeicher vorhanden.
STATUS_INTEGER_OVERFLOW	Der Offset, den Offset angibt, war ungültig.

Diese Methode kann auch andere NTSTATUS-Werte zurückgeben.

Eine Fehlerüberprüfung tritt auf, wenn der Treiber ein ungültiges Objekthandle bereitstellt.

Hinweise

Nachdem WdfUsbTargetDeviceFormatRequestForString zurückgegeben wurde, muss der Treiber WdfRequestSend aufrufen, um die Anforderung zu senden. Nachdem WdfRequestSend zurückgegeben wurde, kann der Treiber das Speicherhandle 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-E/A-Ziele.

Beispiele

Im folgenden Codebeispiel werden 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	Universell
KMDF-Mindestversion	1.0
UMDF-Mindestversion	2.0
Kopfzeile	wdfusb.h (einschließlich Wdfusb.h)
Bibliothek	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)