Função WdfUsbTargetDeviceSendControlTransferSynchronously (wdfusb.h)

[Aplica-se a KMDF e UMDF]

O método WdfUsbTargetDeviceSendControlTransferSynchronously cria uma solicitação de transferência de controle USB e a envia de forma síncrona para um destino de E/S.

Sintaxe

NTSTATUS WdfUsbTargetDeviceSendControlTransferSynchronously(
  [in]            WDFUSBDEVICE                  UsbDevice,
  [in, optional]  WDFREQUEST                    Request,
  [in, optional]  PWDF_REQUEST_SEND_OPTIONS     RequestOptions,
  [in]            PWDF_USB_CONTROL_SETUP_PACKET SetupPacket,
  [in, optional]  PWDF_MEMORY_DESCRIPTOR        MemoryDescriptor,
  [out, optional] PULONG                        BytesTransferred
);

Parâmetros

[in] UsbDevice

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

[in, optional] Request

Um identificador para um objeto de solicitação de estrutura. Esse parâmetro é opcional e pode ser NULL. Para obter mais informações, consulte a seção Comentários a seguir.

[in, optional] RequestOptions

Um ponteiro para uma estrutura de WDF_REQUEST_SEND_OPTIONS alocada pelo chamador que especifica opções para a solicitação. Esse ponteiro é opcional e pode ser NULL. Para obter mais informações, consulte a seção Comentários a seguir.

[in] SetupPacket

Um ponteiro para uma estrutura de WDF_USB_CONTROL_SETUP_PACKET alocada pelo chamador que descreve a transferência de controle.

[in, optional] MemoryDescriptor

Um ponteiro para uma estrutura de WDF_MEMORY_DESCRIPTOR alocada pelo chamador que descreve uma entrada ou um buffer de saída, dependendo do comando específico do dispositivo. Esse ponteiro é opcional e pode ser NULL. Para obter mais informações, consulte a seção Comentários a seguir.

[out, optional] BytesTransferred

Um ponteiro para um local que recebe o número de bytes transferidos. Esse parâmetro é opcional e pode ser NULL.

Valor retornado

WdfUsbTargetDeviceSendControlTransferSynchronously 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 poderá 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 estava disponível.
STATUS_INVALID_DEVICE_REQUEST
Um descritor de memória inválido foi especificado ou a solicitação de E/S especificada já estava na fila para um destino de E/S.
STATUS_IO_TIMEOUT
O driver forneceu um valor de tempo limite e a solicitação não foi concluída dentro do tempo alocado.
 

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

Ocorre uma verificação de bug se o driver fornece um identificador de objeto inválido.

Comentários

Use o método WdfUsbTargetDeviceSendControlTransferSynchronously para enviar uma solicitação de transferência de controle USB de forma síncrona. Para enviar essas solicitações de forma assíncrona, use WdfUsbTargetDeviceFormatRequestForControlTransfer, seguido por WdfRequestSend.

O método WdfUsbTargetDeviceSendControlTransferSynchronously não retorna até que a solicitação seja concluída, a menos que o driver forneça um valor de tempo limite na estrutura WDF_REQUEST_SEND_OPTIONS para a qual o parâmetro RequestOptions aponta ou a menos que um erro seja detectado.

Você pode encaminhar uma solicitação de E/S que seu driver recebeu em uma fila de E/S ou pode criar e enviar uma nova solicitação. Em ambos os casos, a estrutura requer um objeto de solicitação e, dependendo do tipo de transferência de controle, possivelmente algum espaço de buffer.

Para encaminhar uma solicitação de E/S que seu driver recebeu em uma fila de E/S:

  1. Especifique o identificador da solicitação recebida para o parâmetro De solicitação .
  2. Use o buffer de entrada ou saída da solicitação recebida para o parâmetro MemoryDescriptor .

    O driver pode chamar WdfRequestRetrieveInputMemory ou WdfRequestRetrieveOutputMemory para obter um identificador para um objeto de memória de estrutura que representa o buffer de entrada ou saída da solicitação e, em seguida, colocá-lo na estrutura WDF_MEMORY_DESCRIPTOR que o driver fornece para o parâmetro MemoryDescriptor .

Para criar e enviar uma nova solicitação:
  1. Forneça um identificador de solicitação NULL no parâmetro Solicitação ou crie um novo objeto de solicitação e forneça seu identificador:
    • Se você fornecer um identificador de solicitação NULL, a estrutura usará um objeto de solicitação interno. Essa técnica é simples de usar, mas o driver não pode cancelar a solicitação.
    • Se você chamar WdfRequestCreate para criar um ou mais objetos de solicitação, poderá reutilizar esses objetos de solicitação chamando WdfRequestReuse. Essa técnica habilita a função de retorno de chamada EvtDriverDeviceAdd do driver para pré-alocar objetos de solicitação para um dispositivo. Além disso, outro thread de driver pode chamar WdfRequestCancelSentRequest para cancelar a solicitação, se necessário.

    O driver pode especificar um parâmetro RequestOptions não NULL, independentemente de o driver fornecer um parâmetro não NULL ou de solicitaçãoNULL. Você pode, por exemplo, usar o parâmetro RequestOptions para especificar um valor de tempo limite.

  2. Forneça espaço de buffer para o parâmetro MemoryDescriptor do método WdfUsbTargetDeviceSendControlTransferSynchronously.

    Seu driver pode especificar esse espaço de buffer como um buffer alocado localmente, como um identificador WDFMEMORY ou como um MDL. Você pode usar qualquer método mais conveniente.

    Se necessário, a estrutura converte a descrição do buffer em uma que esteja correta para o método do destino de E/S para acessar buffers de dados.

    As seguintes técnicas estão disponíveis:

    • Fornecer um buffer local

      Como o WdfUsbTargetDeviceSendControlTransferSynchronously lida com solicitações de E/S de forma síncrona, o driver pode criar buffers de solicitação locais para a rotina de chamada, conforme mostrado no exemplo de código a seguir.

      WDF_MEMORY_DESCRIPTOR  memoryDescriptor;
      MY_BUFFER_TYPE  myBuffer;
      WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(&memoryDescriptor,
                                        (PVOID) &myBuffer,
                                        sizeof(myBuffer));
      
    • Fornecer um identificador WDFMEMORY

      Chame WdfMemoryCreate ou WdfMemoryCreatePreallocated para obter um identificador para memória gerenciada por estrutura, conforme mostrado no exemplo de código a seguir.

      WDF_MEMORY_DESCRIPTOR  memoryDescriptor;
      WDFMEMORY  memoryHandle = NULL;
      status = WdfMemoryCreate(NULL,
                               NonPagedPool,
                               POOL_TAG,
                               MY_BUFFER_SIZE,
                               &memoryHandle,
                               NULL);
      WDF_MEMORY_DESCRIPTOR_INIT_HANDLE(&memoryDescriptor,
                                        memoryHandle,
                                        NULL);
      

      Como alternativa, o driver pode chamar WdfRequestRetrieveInputMemory ou WdfRequestRetrieveOutputMemory para obter um identificador para um objeto de memória de estrutura que representa um buffer de solicitação de E/S recebido, se você quiser que o driver passe o conteúdo desse buffer para o destino de E/S. O driver não deve concluir a solicitação de E/S recebida até que a nova solicitação que wdfUsbTargetDeviceSendControlTransferSynchronly envia para o destino de E/S tenha sido excluída, reutilizado ou reformatado. (WdfUsbTargetDeviceSendControlTransferSynchronously incrementa a contagem de referência do objeto de memória. Excluir, reutilizar ou reformatar um objeto de solicitação decrementa a contagem de referência do objeto de memória.)

    • Fornecer um MDL

      Os drivers podem obter MDLs associadas a uma solicitação de E/S recebida chamando WdfRequestRetrieveInputWdmMdl ou WdfRequestRetrieveOutputWdmMdl.

A estrutura define o sinalizador USBD_SHORT_TRANSFER_OK em sua URB interna. Definir esse sinalizador permite que o último pacote de uma transferência de dados seja menor que o tamanho máximo do pacote.

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

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

Exemplos

O exemplo de código a seguir inicializa uma estrutura WDF_USB_CONTROL_SETUP_PACKET e, em seguida, chama WdfUsbTargetDeviceSendControlTransferSynchronously para enviar uma transferência de controle específica do fornecedor.

WDF_USB_CONTROL_SETUP_PACKET  controlSetupPacket;

WDF_USB_CONTROL_SETUP_PACKET_INIT_VENDOR(
                                         &controlSetupPacket,
                                         BmRequestHostToDevice,
                                         BmRequestToDevice,
                                         USBFX2LK_REENUMERATE,
                                         0,
                                         0
                                         );

status = WdfUsbTargetDeviceSendControlTransferSynchronously(
                                         UsbDevice,
                                         WDF_NO_HANDLE,
                                         NULL,
                                         &controlSetupPacket,
                                         NULL,
                                         NULL
                                         );
return status;

Requisitos

   
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 PASSIVE_LEVEL
Regras de conformidade de DDI DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestForUrbXrb(kmdf), SyncReqSend(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)

Confira também

WDF_USB_CONTROL_SETUP_PACKET

WDF_USB_CONTROL_SETUP_PACKET_INIT_VENDOR

WdfRequestCancelSentRequest

WdfUsbTargetDeviceFormatRequestForControlTransfer

WdfUsbTargetDeviceSendUrbSynchronously