ACX WDF 驅動程式存留期管理

發行項
03/08/2024

本主題提供 ACX WDF 驅動程式存留期管理和適當記憶體清除的摘要。如需 ACX 的一般概觀，請參閱 ACX 音訊類別延伸模組概觀。

注意

ACX 標頭和連結庫不包含在 WDK 10.0.22621.2428 中（2023 年 10 月 24 日發行），但可在舊版中取得，以及 WDK 的最新（25000 系列組建） Insider Preview。如需 WDK 預覽版本的詳細資訊，請參閱安裝 Windows 驅動程式套件（WDK）的預覽版本。

ACX WDF 初始化和啟動

必須進行適當的 ACX 初始化，才能正確清除 ACX、WDF 和記憶體資源。如需這裡摘要說明之裝置列舉主要階段的詳細數據，請參閱 ACX 裝置列舉。

WDM 驅動程序專案
WDF 裝置新增
WDF 準備硬體
WDF 裝置 D0 專案
ACX 線路建立程式（ACX 針腳和 Jacks 物件與線路相關聯）
ACX 串流建立程式

ACX WDF 物件清除

本主題描述依此順序清除 ACX WDF 物件。

ACX 資料流關閉程式
ACX 線路移除程式
WDF 裝置發行硬體
WDF 驅動程式卸除

建立和清除 WDF 和 ACX 物件有多個有效方法，本主題涵蓋管理 ACX/WDF 物件存留期的一些重要元素。

PnP Power 事件和對象解構

PnP Power 事件可能會導致物件建立和破壞。如需 PnP 電源事件的詳細資訊，請參閱 ACX 電源管理和 WDF PnP 和電源管理回呼序列。

WDF 對象參考存留期管理

WDF 會使用參考計數來協助追蹤物件的存留期。清除回呼函式中可能適合取值對象參考。架構會呼叫此清除回呼函式，如此一來，如果驅動程式先前已針對正在刪除的物件呼叫 WdfObjectReference，則可以呼叫 WdfObjectDereference。如需詳細資訊，請參閱 WdfObjectReference 和 WdfObjectDereference。

Surface Team 驅動程式開發最佳做法

如需使用記憶體和物件存留期管理在驅動程式程式代碼中發生的常見錯誤描述，請參閱 Surface Team 驅動程式開發最佳做法中的這些章節。

ACX 資料流關閉程式

當用戶端關閉數據流時，驅動程式必須能夠關閉並清除與數據流相關聯的資源。如需詳細資訊，請參閱 ACX 串流 - 串流關閉程式。請務必讓驅動程式不會清除支持數據流的資源，而且清除程式會留意對客戶端的影響。

ACX 線路移除程式

ACX 可以視需要建立動態線路。若要這樣做，驅動程式會呼叫 WdfPdoInitAllocate 來配置WDFDEVICE_INIT結構。然後，驅動程式會指定它想要接收並建立裝置的任何 PnP/電源回呼。驅動程式會叫用 AcxDeviceRemoveCircuitDevice ，以從裝置清單中移除音訊裝置。

如需詳細資訊，請參閱 ACX 線路中的 ACX 線路動態移除。

WDF 裝置發行硬體

EVT_WDF_DEVICE_RELEASE_HARDWARE回呼函式用於驅動程式的 EvtDeviceReleaseHardware 事件回呼函式，以執行無法再存取裝置時所需的作業。

WDF 裝置內容清除

AudioCodec 範例中的這個程式代碼示範如何使用 WDF_OBJECT_ATTRIBUTES 結構來設定 EvtCleanupCallback。

    WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(&attributes, CODEC_DEVICE_CONTEXT);
    attributes.EvtCleanupCallback = Codec_EvtDeviceContextCleanup;

這個範例回呼會指定 WdfDevice 清除裝置內容。

VOID
Codec_EvtDeviceContextCleanup(
    _In_ WDFOBJECT      WdfDevice
)

{
    WDFDEVICE               device;
    PCODEC_DEVICE_CONTEXT   devCtx;

    device = (WDFDEVICE)WdfDevice;
    devCtx = GetCodecDeviceContext(device);
    ASSERT(devCtx != nullptr);

    if (devCtx->Capture)
    {
        CodecC_CircuitCleanup(devCtx->Capture);
    }
}

WDF 驅動程式卸除

卸除驅動程式時，應該釋放所有剩餘的資源。如需詳細資訊，請參閱釋放驅動程式配置的資源。

驅動程式會在呼叫 WdfDriverCreate 時註冊 EvtDriverUnload 回呼函式。 EvtDriverUnload 回呼函式必須解除分配驅動程式 DriverEntry 例程配置的任何非裝置特定系統資源。如需詳細資訊，請參閱 EVT_WDF_DRIVER_UNLOAD回呼函式。

AudioCodec 範例中的這個程式代碼會顯示驅動程式卸除回呼的結構。

EVT_WDF_DRIVER_UNLOAD               AudioCodecDriverUnload;

void AudioCodecDriverUnload(
    _In_ WDFDRIVER Driver
)
{
    PAGED_CODE();

    if (!Driver)
    {
        ASSERT(FALSE);
        return;
    }

    WPP_CLEANUP(WdfDriverWdmGetDriverObject(Driver));

// Here is where you would cleanup any allocated resources associated with the driver.

    return;
}