EVT_WDF_OBJECT_CONTEXT_CLEANUP回呼函式 (wdfobject.h)

發行項
02/27/2024

[適用於 KMDF 和 UMDF]

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

語法

EVT_WDF_OBJECT_CONTEXT_CLEANUP EvtWdfObjectContextCleanup;

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

參數

[in] Object

架構物件的句柄。

傳回值

無

備註

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

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

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

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

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

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

一般而言，如果您的驅動程式未呼叫物件的 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 指定為 WdfMemoryCreate 或 WdfLopoolsideListCreate。

刪除工作項目物件時，明確或因為工作專案的父物件遭到刪除，然後在呼叫工作專案的 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