EVT_WDF_IO_QUEUE_IO_CANCELED_ON_QUEUE função de retorno de chamada (wdfio.h)
[Aplica-se a KMDF e UMDF]
A função de retorno de chamada de evento EvtIoCanceledOnQueue de um driver informa ao driver que ele deve concluir uma solicitação de E/S que a estrutura removeu de uma fila de E/S.
Sintaxe
EVT_WDF_IO_QUEUE_IO_CANCELED_ON_QUEUE EvtWdfIoQueueIoCanceledOnQueue;
void EvtWdfIoQueueIoCanceledOnQueue(
[in] WDFQUEUE Queue,
[in] WDFREQUEST Request
)
{...}
Parâmetros
[in] Queue
Um identificador para um objeto de fila de E/S.
[in] Request
Um identificador para um objeto de solicitação.
Valor de retorno
Nenhum
Observações
Um driver registra uma função de retorno de chamada EvtIoCanceledOnQueue quando chama o método WdfIoQueueCreate. Para obter mais informações sobre como chamar WdfIoQueueCreate, consulte Criando filas de E/S.
Se um driver registrar uma função de retorno de chamada EvtIoCanceledOnQueue para uma fila de E/S, a estrutura chamará a função de retorno de chamada nas seguintes situações:
- Um manipulador de solicitações recebe uma solicitação de E/S de uma fila de E/S, o driver chama WdfRequestForwardToIoQueue, WdfRequestForwardToParentDeviceIoQueueou WdfRequestRequeue para requeue a solicitação para a fila de E/S para a qual a função de retorno de chamada EvtIoCanceledOnQueue está registrada, e a operação de E/S associada é posteriormente cancelada.
- A função de retorno de chamada EvtIoInCallerContext do driver recebe uma solicitação de E/S, o driver chama WdfDeviceEnqueueRequest para passar a solicitação de volta para a estrutura, a estrutura coloca a solicitação na fila de E/S para a qual a função de retorno de chamada EvtIoCanceledOnQueue é registrada e a operação de E/S associada é cancelada posteriormente.
Normalmente, em EvtIoCanceledOnQueue, o driver conclui a solicitação de E/S com um status de conclusão de STATUS_CANCELLED.
Em alguns casos, o driver pode ter requeu uma solicitação de E/S anteriormente para uma fila manual, talvez para aguardar informações. Por exemplo, em um de seus manipuladores de solicitação , um driver pode colocar uma solicitação de E/S associada a uma transação de DMA pendente em uma fila manual. Nesse caso, o driver tenta cancelar o de transação de DMA em seu EvtIoCanceledOnQueue retorno de chamada. Dependendo dos resultados da operação de cancelamento, o driver conclui a solicitação com um status apropriado, em EvtIoCanceledOnQueue ou posterior.
A estrutura não chama a função de retorno de chamada do driver EvtIoCanceledOnQueue para solicitações de E/S que a estrutura nunca entregou ao driver.
A estrutura chama uma função de retorno de chamada EvtIoCanceledOnQueue assim que determina que uma solicitação de E/S foi cancelada, independentemente do método de expedição que o driver definiu para a fila de E/S. Portanto, a estrutura pode chamar uma função de retorno de chamada EvtIoCanceledOnQueue para:
- Uma solicitação em uma fila que usa de expedição sequencial, mesmo que o driver atualmente possua outra solicitação da fila.
- Uma solicitação em uma fila para a qual o driver definiu NumberOfPresentedRequests, mesmo que o driver possua atualmente o número máximo de solicitações.
A função de retorno de chamada EvtIoCanceledOnQueue pode ser chamada em IRQL <= DISPATCH_LEVEL, a menos que o ExecutionLevel membro da estrutura de WDF_OBJECT_ATTRIBUTES do dispositivo ou do driver esteja definido como WdfExecutionLevelPassive.
Se o IRQL for PASSIVE_LEVEL, a estrutura chamará a função de retorno de chamada em uma região crítica .
Exemplos
Para definir uma função de retorno de chamada EvtIoCanceledOnQueue, primeiro você deve fornecer uma declaração de função que identifique o tipo de função de retorno de chamada que você está definindo. O Windows fornece um conjunto de tipos de função de retorno de chamada para drivers. Declarar uma função usando os tipos de função de retorno de chamada ajuda a análise de código para drivers, SDV (Verificador de Driver Estático) e outras ferramentas de verificação encontram erros e é um requisito para gravar drivers para o sistema operacional Windows.
Para definir uma função de retorno de chamada EvtIoCanceledOnQueue, primeiro você deve fornecer uma declaração de função que o SDV e outras ferramentas de verificação exigem. O exemplo a seguir é obtido do exemplo de de Driver de Cartão Inteligente PCMCIA.
EVT_WDF_IO_QUEUE_IO_CANCELED_ON_QUEUE PscrEvtIoCanceledOnQueue;
No exemplo de de Driver de Cartão Inteligente PCMCIA, o driver usa uma fila manual para armazenar solicitações de notificação de cartão inteligente pendentes. O driver fornece uma função de retorno de chamada EvtIoCanceledOnQueue na qual o driver limpa o campo de notificação e conclui a solicitação.
_Use_decl_annotations_
VOID
PscrEvtIoCanceledOnQueue(
WDFQUEUE Queue,
WDFREQUEST Request
)
{
PDEVICE_EXTENSION DeviceExtension;
PSMARTCARD_EXTENSION smartcardExtension;
DeviceExtension = GetDeviceExtension(WdfIoQueueGetDevice(Queue));
smartcardExtension = (PSMARTCARD_EXTENSION) &DeviceExtension->SmartcardExtension;
//KdPrint(("Cancelled on queue 0x%x\n", WdfRequestWdmGetIrp(Request)));
InterlockedExchangePointer(
&(smartcardExtension->OsData->NotificationIrp),
NULL
);
WdfRequestComplete(Request, STATUS_CANCELLED);
}
O tipo de função EVT_WDF_IO_QUEUE_IO_CANCELED_ON_QUEUE é definido no arquivo de cabeçalho Wdfio.h. Para identificar erros com mais precisão ao executar as ferramentas de análise de código, adicione a anotação Use_decl_annotations à sua definição de função. A anotação Use_decl_annotations garante que as anotações aplicadas ao tipo de função EVT_WDF_IO_QUEUE_IO_CANCELED_ON_QUEUE no arquivo de cabeçalho sejam usadas. Para obter mais informações sobre os requisitos para declarações de função, consulte Declarando funções usando tipos de função de função para drivers KMDF. Para obter informações sobre Use_decl_annotations, consulte Anotando o comportamento da função.
Requisitos
| Requisito | Valor |
|---|---|
| da Plataforma de Destino | Universal |
| versão mínima do KMDF | 1.0 |
| versão mínima do UMDF | 2.0 |
| cabeçalho | wdfio.h (inclua Wdf.h) |
| IRQL | <= DISPATCH_LEVEL (consulte a seção Comentários) |