Função WdfUsbTargetDeviceFormatRequestForControlTransfer (wdfusb.h)
[Aplica-se a KMDF e UMDF]
O método WdfUsbTargetDeviceFormatRequestForControlTransfer cria uma solicitação de transferência de controle USB, mas não envia a solicitação.
Sintaxe
NTSTATUS WdfUsbTargetDeviceFormatRequestForControlTransfer(
[in] WDFUSBDEVICE UsbDevice,
[in] WDFREQUEST Request,
[in] PWDF_USB_CONTROL_SETUP_PACKET SetupPacket,
[in, optional] WDFMEMORY TransferMemory,
[in, optional] PWDFMEMORY_OFFSET TransferOffset
);
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] SetupPacket
Um ponteiro para uma estrutura de WDF_USB_CONTROL_SETUP_PACKET alocada pelo chamador que descreve a transferência de controle.
[in, optional] TransferMemory
Um identificador para um objeto de memória de estrutura 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.
[in, optional] TransferOffset
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 especificado por TransferMemory . Se esse ponteiro for NULL, a estrutura usará todo o buffer.
Retornar valor
WdfUsbTargetDeviceFormatRequestForControlTransfer 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 |
|---|---|
|
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. |
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 WdfUsbTargetDeviceFormatRequestForControlTransfer, 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 WdfUsbTargetDeviceSendControlTransferSynchronously 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. 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 do método WdfUsbTargetDeviceFormatRequestForControlTransfer.
-
Use o buffer de entrada ou saída da solicitação recebida para o parâmetro TransferMemory .
O driver deve 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 usar esse identificador como o valor de TransferMemory.
-
Crie um novo objeto de solicitação e forneça seu identificador para o parâmetro Request do método WdfUsbTargetDeviceFormatRequestForControlTransfer.
Chame WdfRequestCreate para pré-alocar um ou mais objetos de solicitação. Você pode reutilizar esses objetos 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.
-
Forneça espaço em buffer e forneça o identificador do buffer para o parâmetro TransferMemory do método WdfUsbTargetDeviceFormatRequestForControlTransfer.
Seu driver deve especificar esse espaço de buffer como um identificador WDFMEMORY para memória gerenciada por estrutura. O driver pode fazer um dos seguintes procedimentos:
- Chame WdfMemoryCreate ou WdfMemoryCreatePreallocated para criar um novo buffer de memória, se você quiser que o driver passe um novo buffer para o destino de E/S.
- Chame WdfRequestRetrieveInputMemory ou WdfRequestRetrieveOutputMemory para obter um identificador para o objeto de memória que representa o buffer de uma solicitação de E/S recebida, se você quiser que o driver passe o conteúdo desse buffer para o destino de E/S.
Várias chamadas para WdfUsbTargetDeviceFormatRequestForControlTransfer 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 posteriormente (chamar WdfRequestReuse), reformat (chamar WdfUsbTargetDeviceFormatRequestForControlTransfer) e reenviar (chamar WdfRequestSend) cada objeto de solicitação sem arriscar um valor de retorno STATUS_INSUFFICIENT_RESOURCES de uma chamada posterior para WdfRequestCreate. Todas as chamadas subsequentes para WdfUsbTargetDeviceFormatRequestForControlTransfer 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 todas as vezes, recursos adicionais poderão ser alocados.)
A estrutura define o sinalizador USBD_SHORT_TRANSFER_OK em seu URB interno. 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 Obtendo informações de conclusão.
Para obter mais informações sobre o método WdfUsbTargetDeviceFormatRequestForControlTransfer 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 inicializa uma estrutura WDF_USB_CONTROL_SETUP_PACKET para uma transferência de controle "obter status". Em seguida, o exemplo chama WdfUsbTargetDeviceFormatRequestForControlTransfer para formatar a solicitação. Em seguida, o exemplo define uma função de retorno de chamada CompletionRoutine e envia a solicitação para um destino de E/S.
WDF_USB_CONTROL_SETUP_PACKET packet;
NTSTATUS status;
WDF_OBJECT_ATTRIBUTES attributes;
WDFMEMORY memHandle;
WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
status = WdfRequestCreate(
&attributes,
WdfUsbTargetDeviceGetIoTarget(
UsbTargetDevice,
&request
)
);
if (!NT_SUCCESS(status)){
return status;
}
WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
attributes.ParentObject = request;
status = WdfMemoryCreate(
&attributes,
NonPagedPool,
0,
sizeof(USHORT),
&memHandle,
NULL
);
if (!NT_SUCCESS(status)){
return status;
}
WDF_USB_CONTROL_SETUP_PACKET_INIT_GET_STATUS(
&packet,
BmRequestToDevice,
0
);
status = WdfUsbTargetDeviceFormatRequestForControlTransfer(
UsbTargetDevice,
request,
&packet,
memHandle,
NULL
);
if (!NT_SUCCESS(status)){
return status;
}
WdfRequestSetCompletionRoutine(
request,
MyCompletionRoutine,
NULL
);
if (WdfRequestSend(
request,
WdfUsbTargetDeviceGetIoTarget(UsbTargetDevice),
NULL
) == FALSE) {
status = WdfRequestGetStatus(request);
}
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 | <=DISPATCH_LEVEL |
| Regras de conformidade de DDI | DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestFormattedValid(kmdf), RequestForUrbXrb(kmdf), RequestSendAndForgetNoFormatting(kmdf), RequestSendAndForgetNoFormatting2(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf) |