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.
Retornar valor
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 pode retornar um dos seguintes valores:
Código de retorno | Descrição |
---|---|
|
Um parâmetro inválido foi detectado. |
|
Memória insuficiente disponível. |
|
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. |
|
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.
Um bug marcar ocorrerá se o driver fornecer 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 recebida pelo driver 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:
- Especifique o identificador da solicitação recebida para o parâmetro Request .
-
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, colocar esse identificador na estrutura WDF_MEMORY_DESCRIPTOR que o driver fornece para o parâmetro MemoryDescriptor .
-
Forneça um identificador de solicitação NULL no parâmetro Request 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.
-
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 manipula 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 wdfUsbTargetDeviceSendControlTransferSynchronously envie 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 diminui 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.
-
Fornecer um buffer local
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 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 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
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 (inclua 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_INIT_VENDOR
Comentários
https://aka.ms/ContentUserFeedback.
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulteEnviar e exibir comentários de