共用方式為


EVT_WDF_OBJECT_CONTEXT_CLEANUP回呼函式 (wdfobject.h)

[適用於 KMDF 和 UMDF]

驅動程式的 EvtCleanupCallback 事件回呼函式會移除物件上的驅動程序參考,以便刪除物件。

語法

EVT_WDF_OBJECT_CONTEXT_CLEANUP EvtWdfObjectContextCleanup;

void EvtWdfObjectContextCleanup(
  [in] WDFOBJECT Object
)
{...}

參數

[in] Object

架構物件的句柄。

傳回值

備註

驅動程式可以在WDF_OBJECT_ATTRIBUTES結構中指定 EvtCleanupCallback 回呼函式。 這個結構可用來做為建立架構物件之所有架構方法的輸入,例如 WdfDeviceCreate

當架構或驅動程式嘗試刪除物件時,架構會呼叫回呼函式。

如果驅動程式已呼叫 WdfObjectReference 以增加對象的參考計數,驅動程式必須提供呼叫 WdfObjectDereferenceEvtCleanupCallback 回呼函式。 此呼叫可確保對象的參考計數遞減為零,因此,架構可以呼叫驅動程式的 EvtDestroyCallback 回 呼函式,然後刪除物件。

如果驅動程式同時提供 EvtCleanupCallback 回 呼函式和物件的 EvtDestroyCallback 回 呼函式,架構會先呼叫 EvtCleanupCallback 回 呼函式。

在架構呼叫物件的 EvtCleanupCallback 回 呼函式之後,驅動程式只能從其 EvtDestroyCallback 回 呼函式存取物件。 不過,驅動程式不應該嘗試從其 EvtDestroyCallback 呼叫物件上的方法。

當驅動程式建立物件時,有時會配置物件特定的記憶體緩衝區,並將緩衝區指標儲存在對象 的內容空間中。 驅動程式的 EvtCleanupCallbackEvtDestroyCallback 回 呼函式可以解除分配這些記憶體緩衝區。

一般而言,如果您的驅動程式未呼叫物件的 WdfObjectReference ,則物件的 EvtCleanupCallback 回 呼函式可以解除分配對象內容配置。 在此情況下,驅動程式不需要物件的 EvtDestroyCallback 回 呼函式。

刪除物件時,架構也會刪除物件的子系。 但有一個例外狀況,架構會先呼叫子物件的 EvtCleanupCallback 例程,再呼叫其父物件,因此驅動程序保證子系 的 EvtCleanupCallback 例程執行時仍存在。

此保證排序的例外狀況適用於驅動程式在 DISPATCH_LEVEL 完成的 I/O 要求。 如果這類 I/O 要求物件有一或多個子系,其 EvtCleanupCallback 例程必須在PASSIVE_LEVEL呼叫,則父要求可能會在一或多個子系之前刪除。 如果對象必須等候某個專案完成,或存取分頁記憶體,則物件需要清除PASSIVE_LEVEL。

如果驅動程式在DISPATCH_LEVEL執行時嘗試刪除這類物件 (或這類物件的父代) ,架構會將 EvtCleanupCallback 排入工作專案,以供稍後在PASSIVE_LEVEL進行處理,然後呼叫父物件的清除回呼,而不需要判斷子系的回呼是否已執行。

若要避免因此行為而產生的任何問題,驅動程式不應該將要求物件設定為需要清除PASSIVE_LEVEL之任何物件的父代。 根據預設,大部分物件的父系是WDFDEVICE,因此驅動程序應該只接受預設值。 一般而言,如果將 WDFDEVICE 對象當做參數傳遞, (直接或做為結構) 的一部分傳遞給建立物件的方法,則 WDFDEVICE 是預設父代。 如需預設父代的完整清單,請參閱 Framework 物件的摘要

如果上述例外狀況不適用,架構會先呼叫子物件的 EvtCleanupCallback 回 呼函式,再呼叫父物件的 EvtCleanupCallback 回 呼函式。 接下來,如果子系的參考計數為零,架構會呼叫子物件的 EvtDestroyCallback 回 呼函式。 最後,如果父系的參考計數為零,架構會呼叫父物件的 EvtDestroyCallback 回 呼函式。

如需刪除架構對象的詳細資訊,請參閱 Framework 物件生命週期

一般而言,架構會在 IRQL <= DISPATCH_LEVEL呼叫 EvtCleanupCallback 回呼函式。 不過,架構會在下列情況下呼叫 IRQL = PASSIVE_LEVEL的回呼函式:

  • 物件的句柄類型為 WDFDEVICE、WDFDRIVER、WDFDPC、WDFINTERRUPT、WDFIOTARGET、WDFQUEUE、WDFSTRING、WDFTIMER 或 WDFWORKITEM。
  • 物件的句柄類型為 WDFMEMORY 或 WDFLOGANSIDE,而驅動程式已將 PoolType 參數的 PagedPool 指定為 WdfMemoryCreateWdfLopoolsideListCreate
刪除工作項目物件時,明確或因為工作專案的父物件遭到刪除,然後在呼叫工作專案的 EvtCleanupCallback 回 呼函式之前,架構會等到工作專案 EvtWorkItem 回呼函式的所有實例傳回為止。 如需詳細資訊,請參閱 WdfWorkItemEnqueue

同樣地,刪除定時器物件時,明確或因為定時器的父物件遭到刪除,然後在呼叫定時器的 EvtCleanupCallback 回 呼函式之前,架構會等到定時器 EvtTimerFunc 事件回呼函式的所有實例傳回為止。

從架構 1.9 版開始, wdfroletypes.h 頭檔包含 EvtCleanupCallback 回 呼函式的一些替代物件類型特定函式類型。 這些替代類型可協助驗證工具判斷驅動程式是否使用回呼函式正確。 使用下表來判斷要使用的函式類型。

物件類型 函數類型
裝置物件 EVT_WDF_DEVICE_CONTEXT_CLEANUP
I/O 佇列物件 EVT_WDF_IO_QUEUE_CONTEXT_CLEANUP_CALLBACK
File 物件 EVT_WDF_FILE_CONTEXT_CLEANUP_CALLBACK
所有其他物件 EVT_WDF_OBJECT_CONTEXT_CLEANUP

規格需求

需求
目標平台 Universal
最小 KMDF 版本 1.0
最低UMDF版本 2.0
標頭 wdfobject.h (包含 Wdf.h)
IRQL 請參閱一節。

另請參閱

EvtDestroyCallback

WDF_OBJECT_ATTRIBUTES

WdfObjectDereference

WdfObjectReference

WdfWorkItemFlush