Função WdfUsbTargetDeviceFormatRequestForString (wdfusb.h)

Artigo
08/08/2023

[Aplica-se a KMDF e UMDF]

O método WdfUsbTargetDeviceFormatRequestForString cria uma solicitação para o descritor de cadeia de caracteres USB associado ao valor de índice de cadeia de caracteres de um dispositivo USB.

Sintaxe

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

Parâmetros

[in] UsbDevice

Um identificador para um objeto de dispositivo USB que foi obtido de uma chamada anterior para WdfUsbTargetDeviceCreateWithParameters.

[in] Request

Um identificador para um objeto de solicitação de estrutura.

[in] Memory

Um identificador para um objeto de memória de estrutura.

[in, optional] Offset

Um ponteiro para uma estrutura de WDFMEMORY_OFFSET alocada pelo chamador que fornece valores opcionais de deslocamento e comprimento de bytes. A estrutura usa esses valores para determinar o endereço inicial e o comprimento, dentro do buffer de saída, para armazenar o descritor de cadeia de caracteres. Se esse ponteiro for NULL, o descritor será armazenado no início do buffer de saída e o comprimento máximo da cadeia de caracteres será o comprimento do buffer.

[in] StringIndex

Um valor de índice que identifica a cadeia de caracteres. Esse valor de índice é obtido de uma estrutura de USB_DEVICE_DESCRIPTOR, USB_CONFIGURATION_DESCRIPTOR ou USB_INTERFACE_DESCRIPTOR .

[in, optional] LangID

Um identificador de idioma. A cadeia de caracteres será recuperada para o idioma especificado por esse identificador. Para obter informações sobre como obter os identificadores de idioma com suporte de um dispositivo, consulte a especificação USB.

Retornar valor

WdfUsbTargetDeviceFormatRequestForString retornará STATUS_SUCCESS se a operação for bem-sucedida. Caso contrário, esse método pode retornar um dos seguintes valores:

Código de retorno	Descrição
STATUS_INVALID_PARAMETER	A contagem de bytes do buffer não era um número par.
STATUS_INSUFFICIENT_RESOURCES	Não havia memória suficiente.
STATUS_INTEGER_OVERFLOW	O deslocamento especificado pelo Offset era inválido.

Esse método também pode retornar outros valores NTSTATUS.

Um bug marcar ocorrerá se o driver fornecer um identificador de objeto inválido.

Comentários

Depois que WdfUsbTargetDeviceFormatRequestForString retornar, o driver deverá chamar WdfRequestSend para enviar a solicitação. Depois que WdfRequestSend retornar, o driver poderá passar o identificador de Memória para WdfMemoryGetBuffer para obter um ponteiro para o buffer de memória. O buffer conterá uma estrutura USB_STRING_DESCRIPTOR que descreve o descritor de cadeia de caracteres.

Para obter mais informações sobre o método WdfUsbTargetDeviceFormatRequestForString e destinos de E/S USB, consulte Destinos de E/S USB.

Exemplos

O exemplo de código a seguir cria um objeto de solicitação e um objeto de memória e passa os identificadores de objeto para WdfUsbTargetDeviceFormatRequestForString. Em seguida, o exemplo define uma função de retorno de chamada CompletionRoutine para a solicitação e envia a solicitação para um destino de E/S.

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

Requisitos

Requisito	Valor
Plataforma de Destino	Universal
Versão mínima do KMDF	1.0
Versão mínima do UMDF	2,0
Cabeçalho	wdfusb.h (include Wdfusb.h)
Biblioteca	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
Regras de conformidade da DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestFormattedValid(kmdf), RequestForUrbXrb(kmdf), RequestSendAndForgetNoFormatting(kmdf), RequestSendAndForgetNoFormatting2(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)