Funzione WdfUsbTargetDeviceFormatRequestForString (wdfusb.h)

Articolo
08/08/2023

[Si applica a KMDF e UMDF]

Il metodo WdfUsbTargetDeviceFormatRequestForString compila una richiesta per il descrittore di stringa USB associato al valore di indice stringa di un dispositivo USB.

Sintassi

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

Parametri

[in] UsbDevice

Handle a un oggetto dispositivo USB ottenuto da una chiamata precedente a WdfUsbTargetDeviceCreateWithParameters.

[in] Request

Handle per un oggetto richiesta framework.

[in] Memory

Handle per un oggetto memoria framework.

[in, optional] Offset

Puntatore a una struttura WDFMEMORY_OFFSET allocata dal chiamante che fornisce valori facoltativi di offset e lunghezza di byte. Il framework usa questi valori per determinare l'indirizzo iniziale e la lunghezza, all'interno del buffer di output, per archiviare il descrittore stringa. Se questo puntatore è NULL, il descrittore viene archiviato all'inizio del buffer di output e la lunghezza massima della stringa è la lunghezza del buffer.

[in] StringIndex

Valore di indice che identifica la stringa. Questo valore di indice viene ottenuto da una struttura USB_DEVICE_DESCRIPTOR, USB_CONFIGURATION_DESCRIPTOR o USB_INTERFACE_DESCRIPTOR .

[in, optional] LangID

Identificatore della lingua. La stringa verrà recuperata per la lingua specificata da questo identificatore. Per informazioni sull'acquisizione degli identificatori di lingua supportati di un dispositivo, vedere la specifica USB.

Valore restituito

WdfUsbTargetDeviceFormatRequestForString restituisce STATUS_SUCCESS se l'operazione ha esito positivo. In caso contrario, questo metodo può restituire uno dei valori seguenti:

Codice restituito	Descrizione
STATUS_INVALID_PARAMETER	Il conteggio dei byte del buffer non era un numero pari.
STATUS_INSUFFICIENT_RESOURCES	Memoria insufficiente.
STATUS_INTEGER_OVERFLOW	Offset specificato da Offset non valido.

Questo metodo potrebbe restituire anche altri valori NTSTATUS.

Un controllo di bug si verifica se il driver fornisce un handle di oggetti non valido.

Commenti

Dopo che WdfUsbTargetDeviceFormatRequestForString restituisce, il driver deve chiamare WdfRequestSend per inviare la richiesta. Dopo aver restituito WdfRequestSend , il driver può passare l'handle di memoria a WdfMemoryGetBuffer per ottenere un puntatore al buffer di memoria. Il buffer conterrà una struttura USB_STRING_DESCRIPTOR che descrive il descrittore stringa.

Per altre informazioni sul metodo WdfUsbTargetDeviceFormatRequestForString e sulle destinazioni di I/O USB, vedere Destinazioni di I/O USB.

Esempio

L'esempio di codice seguente crea un oggetto request e un oggetto memory e passa gli handle degli oggetti a WdfUsbTargetDeviceFormatRequestForString. L'esempio imposta quindi una funzione di callback Di completamentoroutine per la richiesta e invia la richiesta a una destinazione di 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;
}

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
Versione KMDF minima	1,0
Versione UMDF minima	2,0
Intestazione	wdfusb.h (include Wdfusb.h)
Libreria	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
Regole di conformità DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestFormattedValid(kmdf), RequestForUrbXrb(kmdf),RequestSendAndForgetNoFormatting(kmdf), RequestSendAndForgetNoFormatting2(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)