EVT_WDF_OBJECT_CONTEXT_CLEANUP função de retorno de chamada (wdfobject.h)
[Aplica-se a KMDF e UMDF]
A função de retorno de chamada de evento EvtCleanupCallback de um driver remove as referências do driver em um objeto para que o objeto possa ser excluído.
Sintaxe
EVT_WDF_OBJECT_CONTEXT_CLEANUP EvtWdfObjectContextCleanup;
void EvtWdfObjectContextCleanup(
[in] WDFOBJECT Object
)
{...}
Parâmetros
[in] Object
Um identificador para um objeto de estrutura.
Retornar valor
Nenhum
Comentários
O driver pode especificar uma função de retorno de chamada EvtCleanupCallback em uma estrutura WDF_OBJECT_ATTRIBUTES . Essa estrutura é usada como entrada para todos os métodos de estrutura que criam objetos de estrutura, como WdfDeviceCreate.
A estrutura chama a função de retorno de chamada quando a estrutura ou um driver tenta excluir o objeto.
Se o driver tiver chamado WdfObjectReference para aumentar a contagem de referência de um objeto, o driver deverá fornecer uma função de retorno de chamada EvtCleanupCallback que chama WdfObjectDereference. Essa chamada garante que a contagem de referência do objeto seja decrementada para zero e, como resultado, a estrutura pode chamar a função de retorno de chamada EvtDestroyCallback do driver e, em seguida, excluir o objeto.
Se um driver fornecer uma função de retorno de chamada EvtCleanupCallback e uma função de retorno de chamada EvtDestroyCallback para um objeto , a estrutura chamará a função de retorno de chamada EvtCleanupCallback primeiro.
Depois que a estrutura chama a função de retorno de chamada EvtCleanupCallback de um objeto, o driver pode acessar o objeto somente de sua função de retorno de chamada EvtDestroyCallback . No entanto, um driver não deve tentar chamar métodos em um objeto de seu EvtDestroyCallback.
Quando um driver cria um objeto, às vezes aloca buffers de memória específicos do objeto e armazena os ponteiros de buffer no espaço de contexto do objeto. A função de retorno de chamada EvtCleanupCallback ou EvtDestroyCallback do driver pode desalocar esses buffers de memória.
Normalmente, se o driver não chamar WdfObjectReference para um objeto, a função de retorno de chamada EvtCleanupCallback do objeto poderá desalocar alocações de contexto de objeto. Nesse caso, o driver não precisa de uma função de retorno de chamada EvtDestroyCallback para o objeto .
Quando um objeto é excluído, a estrutura também exclui os filhos do objeto. Com uma exceção, a estrutura chama as rotinas EvtCleanupCallback de objetos filho antes de chamar os de seus objetos pai, portanto, os drivers têm a garantia de que o objeto pai ainda existe quando a rotina EvtCleanupCallback de um filho é executada.
A exceção a essa ordenação garantida se aplica a solicitações de E/S que o driver conclui em DISPATCH_LEVEL. Se esse objeto de solicitação de E/S tiver um ou mais filhos cujas rotinas EvtCleanupCallback devem ser chamadas em PASSIVE_LEVEL, a solicitação pai poderá ser excluída antes de um ou mais de seus filhos. Um objeto requer limpeza em PASSIVE_LEVEL se precisar aguardar a conclusão de algo ou se acessar a memória paginada.
Se o driver tentar excluir esse objeto (ou o pai de tal objeto) enquanto ele estiver em execução no DISPATCH_LEVEL, a estrutura enfileira o EvtCleanupCallback em um item de trabalho para processamento posterior em PASSIVE_LEVEL e, em seguida, chama o retorno de chamada de limpeza para o objeto pai sem determinar se os retornos de chamada para os filhos foram executados.
Para evitar problemas que possam resultar desse comportamento, os drivers não devem definir o objeto de solicitação como o pai de qualquer objeto que exija limpeza em PASSIVE_LEVEL. Por padrão, o pai da maioria dos objetos é WDFDEVICE, portanto, os drivers devem apenas aceitar o padrão. Geralmente, se o objeto WDFDEVICE for passado como um parâmetro (diretamente ou como parte de uma estrutura) para o método que cria o objeto , o WDFDEVICE será o pai padrão. Para obter uma lista completa dos pais padrão, consulte Resumo de objetos de estrutura.
Se a exceção acima não se aplicar, a estrutura chamará as funções de retorno de chamada EvtCleanupCallback do objeto filho antes de chamar a função de retorno de chamada EvtCleanupCallback do objeto pai. Em seguida, se a contagem de referência do filho for zero, a estrutura chamará a função de retorno de chamada EvtDestroyCallback do objeto filho. Por fim, se a contagem de referência do pai for zero, a estrutura chamará a função de retorno de chamada EvtDestroyCallback do objeto pai.
Para obter mais informações sobre como excluir objetos de estrutura, consulte Ciclo de vida do objeto Framework.
Normalmente, a estrutura chama a função de retorno de chamada EvtCleanupCallback em IRQL <= DISPATCH_LEVEL. No entanto, a estrutura chama a função de retorno de chamada em IRQL = PASSIVE_LEVEL nas seguintes situações:
- O tipo de identificador do objeto é WDFDEVICE, WDFDRIVER, WDFDPC, WDFINTERRUPT, WDFIOTARGET, WDFQUEUE, WDFSTRING, WDFTIMER ou WDFWORKITEM.
- O tipo de identificador do objeto é WDFMEMORY ou WDFLOOKASIDE e o driver especificou PagedPool para o parâmetro PoolType para WdfMemoryCreate ou WdfLookasideListCreate.
Da mesma forma, quando um objeto de temporizador é excluído, explicitamente ou porque o objeto pai do temporizador está sendo excluído, antes de chamar a função de retorno de chamada EvtCleanupCallback do temporizador, a estrutura aguarda até que todas as instâncias da função de retorno de chamada de evento EvtTimerFunc do temporizador tenham retornado.
A partir da versão 1.9 da estrutura, o arquivo de cabeçalho wdfroletypes.h contém alguns tipos de função alternativos, específicos do tipo de objeto, para a função de retorno de chamada EvtCleanupCallback . Esses tipos alternativos ajudam as ferramentas de verificação a determinar se o driver está usando corretamente a função de retorno de chamada. Use a tabela a seguir para determinar qual tipo de função usar.
| Tipo de objeto | Tipo de função |
|---|---|
| Objeto de dispositivo | EVT_WDF_DEVICE_CONTEXT_CLEANUP |
| Objeto de fila de E/S | EVT_WDF_IO_QUEUE_CONTEXT_CLEANUP_CALLBACK |
| Objeto de arquivo | EVT_WDF_FILE_CONTEXT_CLEANUP_CALLBACK |
| Todos os outros objetos | EVT_WDF_OBJECT_CONTEXT_CLEANUP |
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 | wdfobject.h (inclua Wdf.h) |
| IRQL | Consulte a seção Observações. |