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.

Valor retornado

Nenhum

Comentários

O driver pode especificar uma função de retorno de chamada EvtCleanupCallback em uma estrutura de 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 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 chamar a função de retorno de chamada EvtCleanupCallback de um objeto, o driver poderá 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, ele à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 uma criança é executada.

A exceção a essa ordenação garantida se aplica às 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 paged.

Se o driver tentar excluir esse objeto (ou o pai de tal objeto) enquanto ele estiver em execução no DISPATCH_LEVEL, a estrutura colocará o EvtCleanupCallback em um item de trabalho para processamento posterior em PASSIVE_LEVEL e, em seguida, chamará 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 simplesmente aceitar o padrão. Em geral, 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 de pais padrão, consulte Resumo de Objetos da 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 o 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 no 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.
Quando um objeto de item de trabalho é excluído, explicitamente ou porque o objeto pai do item de trabalho está sendo excluído, antes de chamar a função de retorno de chamada EvtCleanupCallback do item de trabalho, a estrutura aguarda até que todas as instâncias da função de retorno de chamada EvtWorkItem do item de trabalho tenham retornado. Para obter mais informações, consulte WdfWorkItemEnqueue.

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 a verificar as ferramentas para 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

   
Plataforma de Destino Universal
Versão mínima do KMDF 1,0
Versão mínima do UMDF 2,0
Cabeçalho wdfobject.h (include Wdf.h)
IRQL Consulte a seção Observações.

Confira também

EvtDestroyCallback

WDF_OBJECT_ATTRIBUTES

WdfObjectDereference

WdfObjectReference

WdfWorkItemFlush