Função WdfUsbTargetPipeFormatRequestForUrb (wdfusb.h)

Artigo
08/08/2023

[Aplica-se somente ao KMDF]

O método WdfUsbTargetPipeFormatRequestForUrb cria uma solicitação USB para um pipe USB especificado, usando parâmetros de solicitação que um URB especificado descreve, mas não envia a solicitação.

Sintaxe

NTSTATUS WdfUsbTargetPipeFormatRequestForUrb(
                 WDFUSBPIPE        PIPE,
  [in]           WDFREQUEST        Request,
  [in]           WDFMEMORY         UrbMemory,
  [in, optional] PWDFMEMORY_OFFSET UrbMemoryOffset
);

Parâmetros

PIPE

Um identificador para um objeto de pipe de estrutura que foi obtido chamando WdfUsbInterfaceGetConfiguredPipe.

[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 .

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.

[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

WdfUsbTargetPipeFormatRequestForUrb retorna o valor de status de conclusão do destino de E/S 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	Memória insuficiente disponível.
STATUS_INTEGER_OVERFLOW	O deslocamento que o parâmetro UsbMemoryOffset especificou era inválido.
STATUS_REQUEST_NOT_ACCEPTED	O IRP (pacote de solicitação de E/S) que o parâmetro Request representa não fornece estruturas de IO_STACK_LOCATION suficientes para permitir que o driver encaminhe a solicitação.

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 WdfUsbTargetPipeFormatRequestForUrb, seguido por WdfRequestSend, para enviar uma solicitação USB de forma síncrona ou assíncrona. Como alternativa, use o método WdfUsbTargetPipeSendUrbSynchronously para enviar uma solicitação de forma síncrona.

A estrutura não examina a solicitação USB. Se a solicitação alterar o estado do pipe USB, a estrutura não estará ciente da alteração.

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 WdfUsbTargetPipeFormatRequestForUrb.

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 WdfUsbTargetPipeFormatRequestForUrb. Você pode reutilizar o objeto de solicitação chamando WdfRequestReuse para que a função de retorno de chamada EvtDriverDeviceAdd do driver possa pré-alocar objetos de solicitação para um dispositivo.

Depois de chamar WdfUsbTargetPipeFormatRequestForUrb 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.

Várias chamadas para WdfUsbTargetPipeFormatRequestForUrb 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 WdfUsbTargetPipeFormatRequestForUrb) 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 WdfUsbTargetPipeFormatRequestForUrb 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 WdfUsbTargetPipeFormatRequestForUrb 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 que representa um URB. Em seguida, o exemplo inicializa o URB, formata uma solicitação USB que contém o URB, registra uma função de retorno de chamada CompletionRoutine e envia a solicitação.

URB  urb;
PURB  pUrb = NULL;
WDFMEMORY  urbMemory
NTSTATUS status;

status = WdfMemoryCreate(
                         WDF_NO_OBJECT_ATTRIBUTES,
                         NonPagedPool,
                         0,
                         sizeof(struct _URB_GET_CURRENT_FRAME_NUMBER),
                         &urbMemory,
                         NULL
                         );
if (!NT_SUCCESS(status)){
    return status;
}

pUrb = WdfMemoryGetBuffer(
                          urbMemory,
                          NULL
                          );

pUrb->UrbHeader.Length = (USHORT) sizeof(struct _URB_GET_CURRENT_FRAME_NUMBER);
pUrb->UrbHeader.Function = URB_FUNCTION_GET_CURRENT_FRAME_NUMBER;
pUrb->UrbGetCurrentFrameNumber.FrameNumber = 0; 

status = WdfUsbTargetPipeFormatRequestForUrb(
                                             pipe,
                                             Request,
                                             urbMemory,
                                             NULL
                                             );
if (!NT_SUCCESS(status)) {
    goto Exit;
}
WdfRequestSetCompletionRoutine(
                               Request,
                               UrbCompletionRoutine,
                               pipe
                               );
if (WdfRequestSend(
                   Request,
                   WdfUsbTargetPipeGetIoTarget(pipe),
                   WDF_NO_SEND_OPTIONS
                   ) == FALSE) {
    status = WdfRequestGetStatus(Request);
    goto Exit;
}
Exit:
if (!NT_SUCCESS(status)) {
    WdfRequestCompleteWithInformation(
                                      Request,
                                      status,
                                      0
                                      );
}
return;

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)