Função WdfUsbTargetDeviceFormatRequestForUrb (wdfusb.h)

Artigo
08/08/2023

[Aplica-se somente ao KMDF]

O método WdfUsbTargetDeviceFormatRequestForUrb cria uma solicitação USB para um dispositivo USB especificado, usando parâmetros de solicitação descritos por um URB, mas não envia a solicitação.

Sintaxe

NTSTATUS WdfUsbTargetDeviceFormatRequestForUrb(
  [in]           WDFUSBDEVICE      UsbDevice,
  [in]           WDFREQUEST        Request,
  [in]           WDFMEMORY         UrbMemory,
  [in, optional] PWDFMEMORY_OFFSET UrbMemoryOffset
);

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. Para obter mais informações, consulte a seção Comentários a seguir.

[in] UrbMemory

Um identificador para um objeto de memória de estrutura que contém uma estrutura URB ou um dos membros da união da estrutura. (Todos os membros da união da estrutura URB contêm a estrutura _URB_HEADER .)

Se o driver anteriormente chamado WdfUsbTargetDeviceCreateWithParameters criar UsbDevice, o driver deverá usar WdfUsbTargetDeviceCreateUrb ou WdfUsbTargetDeviceCreateIsochUrb para criar o URB contido nesse objeto de memória. Caso contrário, ocorrerá um bug marcar.

[in, optional] UrbMemoryOffset

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 do URB na memória especificada por UrbMemory . Se esse ponteiro for NULL, o URB estará localizado no início da memória UrbMemory .

Retornar valor

WdfUsbTargetDeviceFormatRequestForUrb 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	Um parâmetro inválido foi detectado.
STATUS_INSUFFICIENT_RESOURCES	Não havia memória suficiente.
STATUS_INTEGER_OVERFLOW	O deslocamento que o parâmetro UsbMemoryOffset especificou 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

Use WdfUsbTargetDeviceFormatRequestForUrb, seguido por WdfRequestSend, para enviar uma solicitação de transferência de controle USB de forma síncrona ou assíncrona. Como alternativa, use o método WdfUsbTargetDeviceSendUrbSynchronously para enviar uma solicitação de forma síncrona.

Você pode encaminhar uma solicitação de E/S recebida pelo driver em uma fila de E/S ou pode criar e enviar uma nova solicitação.

Para encaminhar uma solicitação de E/S recebida pelo driver em uma fila de E/S, especifique o identificador da solicitação recebida para o parâmetro Request do método WdfUsbTargetDeviceFormatRequestForUrb.

Para criar uma nova solicitação de E/S, chame WdfRequestCreate para pré-alocar um objeto de solicitação. Forneça o identificador de solicitação para o parâmetro Request do método WdfUsbTargetDeviceFormatRequestForUrb. Você pode reutilizar o objeto de solicitação chamando WdfRequestReuse. A função de retorno de chamada EvtDriverDeviceAdd do driver pode pré-alocar objetos de solicitação para um dispositivo.

Depois de chamar WdfUsbTargetDeviceFormatRequestForUrb para formatar uma solicitação de E/S, o driver deve chamar WdfRequestSend para enviar a solicitação (de forma síncrona ou assíncrona) para um destino de E/S. Não use a opção enviar e esquecer para enviar a solicitação.

Várias chamadas para WdfUsbTargetDeviceFormatRequestForUrb que usam a mesma solicitação não causam alocações de recursos adicionais. Portanto, para reduzir a chance de WdfRequestCreate retornar STATUS_INSUFFICIENT_RESOURCES, a função de retorno de chamada EvtDriverDeviceAdd do driver pode chamar WdfRequestCreate para pré-alocar um ou mais objetos de solicitação para um dispositivo. O driver pode reutilizar (chamar WdfRequestReuse), reformatar (chamar WdfUsbTargetDeviceFormatRequestForUrb) e reenviar (chamar WdfRequestSend) cada objeto de solicitação sem arriscar um valor retornado STATUS_INSUFFICIENT_RESOURCES de uma chamada posterior para WdfRequestCreate. Todas as chamadas subsequentes para WdfUsbTargetDeviceFormatRequestForUrb para o objeto de solicitação reutilizado retornarão STATUS_SUCCESS, se os valores de parâmetro não forem alterados. (Se o driver não chamar o mesmo método de formatação de solicitação a cada vez, recursos adicionais poderão ser alocados.)

Para obter informações sobre como obter informações de status após a conclusão de uma solicitação de E/S, consulte Obtendo informações de conclusão.

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

Exemplos

O exemplo de código a seguir cria um objeto de memória para manter uma estrutura URB, inicializa a estrutura URB e chama WdfUsbTargetDeviceFormatRequestForUrb para formatar uma solicitação que usa o conteúdo da estrutura URB. Em seguida, o exemplo registra uma função de retorno de chamada CompletionRoutine e envia a solicitação para um destino de E/S.

WDFMEMORY urbMemory;
URB *urbBuffer;

status = WdfMemoryCreate(
                         WDF_NO_OBJECT_ATTRIBUTES,
                         NonPagedPool,
                         0,
                         sizeof(struct _URB_CONTROL_GET_CONFIGURATION_REQUEST),
                         &urbMemory,
                         NULL
                         );

if (!NT_SUCCESS(status)){
    return status;
}
urbBuffer = (PURB) WdfMemoryGetBuffer(
                                      urbMemory,
                                      NULL
                                      );
urbBuffer->UrbHeader.Function =  URB_FUNCTION_GET_CONFIGURATION;
urbBuffer->UrbHeader.Length = sizeof(struct _URB_CONTROL_GET_CONFIGURATION_REQUEST);
urbBuffer->UrbControlGetConfigurationRequest.TransferBufferLength = 1 ;
urbBuffer->UrbControlGetConfigurationRequest.TransferBufferMDL = NULL;
urbBuffer->UrbControlGetConfigurationRequest.TransferBuffer = outBuffer;
urbBuffer->UrbControlGetConfigurationRequest.UrbLink = NULL;

status = WdfUsbTargetDeviceFormatRequestForUrb(
                                               deviceContext->WdfUsbTargetDevice,
                                               request,
                                               urbMemory,
                                               NULL
                                               );
WdfRequestSetCompletionRoutine(
                              request,
                              MyCompletionRoutine,
                              NULL);

if (WdfRequestSend(
                   request,
                   WdfUsbTargetDeviceGetIoTarget(UsbDevice),
                   NULL
                   ) == FALSE) {
    status = WdfRequestGetStatus(request);
}

Requisitos

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