EVT_WDF_USB_READER_COMPLETION_ROUTINE função de retorno de chamada (wdfusb.h)

[Aplica-se a KMDF e UMDF]

A função de retorno de chamada de evento EvtUsbTargetPipeReadComplete de um driver informa ao driver que um leitor contínuo concluiu com êxito uma solicitação de leitura.

Sintaxe

EVT_WDF_USB_READER_COMPLETION_ROUTINE EvtWdfUsbReaderCompletionRoutine;

void EvtWdfUsbReaderCompletionRoutine(
  [in] WDFUSBPIPE Pipe,
  [in] WDFMEMORY Buffer,
  [in] size_t NumBytesTransferred,
  [in] WDFCONTEXT Context
)
{...}

Parâmetros

[in] Pipe

Um identificador para um objeto de pipe de estrutura.

[in] Buffer

Um identificador para um objeto de memória de estrutura que representa um buffer que contém dados do dispositivo.

[in] NumBytesTransferred

O número de bytes de dados que estão no buffer de leitura.

[in] Context

Informações de contexto definidas pelo driver especificadas no membro EvtUsbTargetPipeReadCompleteContext da estrutura de WDF_USB_CONTINUOUS_READER_CONFIG do pipe.

Retornar valor

Nenhum

Comentários

Para registrar uma função de retorno de chamada EvtUsbTargetPipeReadComplete , o driver deve colocar o endereço da função em uma estrutura WDF_USB_CONTINUOUS_READER_CONFIG .

Se um driver tiver criado um leitor contínuo para um pipe USB, a estrutura chamará a função de retorno de chamada EvtUsbTargetPipeReadComplete do driver sempre que o destino de E/S do driver concluir uma solicitação de leitura com êxito. A função de retorno de chamada é chamada no IRQL no qual o destino de E/S concluiu a solicitação de leitura, que normalmente é IRQL = DISPATCH_LEVEL, mas não superior a DISPATCH_LEVEL. (Se o destino de E/S não concluir uma solicitação com êxito, a estrutura chamará a função de retorno de chamada EvtUsbTargetPipeReadersFailed do driver.)

Para acessar o buffer que contém dados que foram lidos do dispositivo, o driver pode chamar WdfMemoryGetBuffer. A estrutura grava os dados no buffer, após o cabeçalho definido pelo membro HeaderLength da estrutura WDF_USB_CONTINUOUS_READER_CONFIG . Observe que o ponteiro que WdfMemoryGetBuffer retorna aponta para o início do cabeçalho, mas o parâmetro NumBytesTransferred da função de retorno de chamada EvtUsbTargetPipeReadCompletenão inclui o comprimento do cabeçalho.

Por padrão, a estrutura exclui o objeto de memória do buffer após o retorno da função de retorno de chamada EvtUsbTargetPipeReadComplete . No entanto, talvez você queira que o objeto de memória permaneça válido depois que a função de retorno de chamada retornar. Por exemplo, talvez você queira que o driver armazene o identificador de objeto no espaço de contexto do objeto de pipe da estrutura para que o driver possa processar o conteúdo do objeto de memória após o retorno da função de retorno de chamada. Para estender o tempo de vida do objeto de memória, a função de retorno de chamada deve passar o identificador do objeto de memória para WdfObjectReference. Posteriormente, o driver deve chamar WdfObjectDereference para que a estrutura possa excluir o objeto.

A estrutura sincroniza chamadas para as funções de retorno de chamada EvtUsbTargetPipeReadComplete e EvtUsbTargetPipeReadersFailed de acordo com as seguintes regras:

• Essas funções de retorno de chamada não são executadas simultaneamente para um pipe USB individual.
• Se o driver criar vários leitores contínuos para vários pipes USB, com várias funções de retorno de chamada EvtUsbTargetPipeReadComplete e EvtUsbTargetPipeReadersFailed , as várias funções de retorno de chamada poderão ser executadas simultaneamente.
• Se o driver tiver especificado o valor padrão NumPendingReads ou um valor maior que 1 e se uma solicitação de leitura for concluída enquanto a função de retorno de chamada EvtUsbTargetPipeReadComplete estiver sendo executada, a estrutura poderá chamar a função de retorno de chamada EvtUsbTargetPipeReadComplete novamente antes que a função de retorno de chamada retorne.
• A estrutura não sincroniza essas funções de retorno de chamada com nenhuma outra função de retorno de chamada.

No membro BufferAttributes da estrutura WDF_USB_CONTINUOUS_READER_CONFIG , o driver pode especificar as funções de retorno de chamada EvtCleanupCallback e EvtDestroyCallback para o objeto de memória. Se você especificar uma função de retorno de chamada EvtCleanupCallback , a estrutura chamará essa função de retorno de chamada quando tentar excluir o objeto de memória, depois que a função de retorno de chamada EvtUsbTargetPipeReadComplete retornar. Se a função de retorno de chamada EvtUsbTargetPipeReadComplete tiver chamado WdfObjectReference, a função de retorno de chamada EvtCleanupCallback (se fornecida) não deverá chamar WdfObjectDereference.

O driver deve chamar WdfObjectDereference quando terminar de usar o objeto de memória. Em seguida, a estrutura pode chamar a função de retorno de chamada EvtDestroyCallback do driver (se fornecida) e excluir o objeto de memória.

Para obter mais informações sobre a função de retorno de chamada EvtUsbTargetPipeReadComplete e destinos de E/S USB, consulte Destinos de E/S USB.

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 Wdf.h)
IRQL	<=DISPATCH_LEVEL (consulte a seção Comentários.)

Confira também

EvtUsbTargetPipeReadersFailed

WDF_USB_CONTINUOUS_READER_CONFIG

WdfMemoryGetBuffer