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.

Retornar valor

Nenhum

Comentários

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ção recebe uma solicitação de E/S de uma fila de E/S, o driver chama WdfRequestForwardToIoQueue, WdfRequestForwardToParentDeviceIoQueue ou WdfRequestRequeue para redirecionar a solicitação para a 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.
• 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.

Depois que a estrutura chama a função de retorno de chamada EvtIoCanceledOnQueue, o driver é proprietário do objeto de solicitação e deve concluir a solicitação com um código de status apropriado, seja em EvtIoCanceledOnQueue ou posterior. Quando a estrutura chama EvtIoCanceledOnQueue, a solicitação ainda está associada à fila de E/S, mas o driver não pode redirecionar a solicitação. A propriedade da solicitação permanece com o driver mesmo que o driver não conclua a solicitação em EvtIoCanceledOnQueue. Se o driver concluir a solicitação depois que EvtIoCanceledOnQueue retornar, ele não poderá chamar WdfIoQueueFindRequest e WdfIoQueueRetrieveFoundRequest para requisitar a propriedade da solicitação porque o driver já tem a propriedade da solicitação.

Normalmente, em EvtIoCanceledOnQueue, o driver conclui a solicitação de E/S com uma status de conclusão de STATUS_CANCELLED.

Em alguns casos, o driver pode ter enfileirado anteriormente uma solicitação de E/S 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 a transação de DMA em seu retorno de chamada EvtIoCanceledOnQueue . Dependendo dos resultados da operação de cancelamento, o driver conclui a solicitação com uma status apropriada, no EvtIoCanceledOnQueue ou posterior.

A estrutura não chama a função de retorno de chamada EvtIoCanceledOnQueue do driver 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 expedição sequencial, mesmo que atualmente o driver possua outra solicitação da fila.
• Uma solicitação em uma fila para a qual o driver definiu NumberOfPresentedRequests, mesmo que atualmente o driver possua o número máximo de solicitações.

Para obter mais informações sobre a função de retorno de chamada EvtIoCanceledOnQueue , consulte Cancelando solicitações de E/S.

A função de retorno de chamada EvtIoCanceledOnQueue pode ser chamada em IRQL <= DISPATCH_LEVEL, a menos que o membro ExecutionLevel da estrutura de WDF_OBJECT_ATTRIBUTES do dispositivo ou 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 a encontrar erros e é um requisito para escrever 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 Driver de Cartão Inteligente PCMCIA .

EVT_WDF_IO_QUEUE_IO_CANCELED_ON_QUEUE PscrEvtIoCanceledOnQueue;

No exemplo de Driver de Cartão Inteligente PCMCIA, o driver usa uma fila manual para armazenar solicitações de notificação de cartão inteligentes 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 para drivers KMDF. Para obter informações sobre Use_decl_annotations, consulte Anotando o comportamento da função.

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

Confira também

WdfIoQueueCreate

WdfRequestForwardToIoQueue