EVT_ACX_CIRCUIT_PREPARE_HARDWARE回呼函式 (acxcircuit.h)

當 ACXCIRCUIT 處於準備硬體階段時，驅動程式會使用 EVT_ACX_CIRCUIT_PREPARE_HARDWARE 回呼來新增功能。

語法

EVT_ACX_CIRCUIT_PREPARE_HARDWARE EvtAcxCircuitPrepareHardware;

NTSTATUS EvtAcxCircuitPrepareHardware(
  WDFDEVICE Device,
  ACXCIRCUIT Circuit,
  WDFCMRESLIST ResourcesRaw,
  WDFCMRESLIST ResourcesTranslated
)
{...}

參數

Device

WDFDEVICE 物件 (WDF - 與 指定 ACXCIRCUIT 相關聯的架構物件摘要) 。

Circuit

ACXCIRCUIT 物件 (在準備硬體階段的 ACX 物件 摘要) 中所述。

ResourcesRaw

架構資源清單物件的句柄，識別 隨插即用 管理員指派給裝置的原始硬體資源。 如需原始資源的詳細資訊，請參閱 原始和翻譯的資源。

ResourcesTranslated

架構資源清單物件的句柄，可識別 隨插即用 管理員指派給裝置的已轉譯硬體資源。

傳回值

如果呼叫成功，則傳 STATUS_SUCCESS 回 。 否則，它會傳回適當的錯誤碼。 如需詳細資訊，請參閱 使用NTSTATUS值。

備註

若要註冊 EvtAcxCircuitPrepareHardware 回呼函式，驅動程式必須呼叫 AcxCircuitInitSetAcxCircuitPnpPowerCallbacks 方法。

如果驅動程式已註冊 ACXCIRCUIT 的 EvtAcxCircuitPrepareHardware 回呼函式，則 ACX 架構會在 WDF 架構呼叫驅動程式的 EvtDevicePrepareHardware 回呼函式之後呼叫函式。

EvtAcxCircuitPrepareHardware 回呼函式會使用其收到的 ResourcesRaw 和 ResourcesTranslated 句柄來存取裝置的原始和翻譯硬體資源。 回呼函式可以呼叫 WdfCmResourceListGetCount 和 WdfCmResourceListGetDescriptor 來周遊資源清單。 此回呼函式無法修改資源清單。

如需資源清單和資源出現順序的詳細資訊，請參閱 原始和翻譯的資源。

一般而言，驅動程式的 EvtAcxCircuitPrepareHardware 回呼函式會視需要執行下列動作：

• 將實體記憶體位址對應至 ACXCIRCUIT 的虛擬位址，讓驅動程式可以存取指派給裝置的記憶體。
• 或者，驅動程式的 EvtAcxCircuitPrepareHardware 回呼函式可能會將工作專案排入佇列，以完成任何其他需要大量時間的設定工作。 針對這類作業使用工作專案有助於確保裝置的啟動時間不會增加系統開機時間。 如需詳細資訊，請參閱使用 Framework 工作專案。
• 一般而言，所有其他硬體初始化作業，包括載入韌體，都應該在裝置進入其工作 (D0) 狀態時發生，因此應該在驅動程式的 EvtDeviceD0Entry 回呼函式中執行。

ResourcesRaw 和 ResourcesTranslated 處理 EvtAcxCircuitPrepareHardware/EvtDevicePrepareHardware 回呼函式會維持有效狀態，直到驅動程式的 EvtDeviceReleaseHardware 回呼函式傳回為止。

如果驅動程式失敗 EvtAcxCircuitPrepareHardware 回呼，ACXCIRCUIT 物件會置於刪除擱置狀態，並關閉相關聯的 ACXSTREAMS。

如需硬體資源的詳細資訊，請參閱 硬體資源簡介。

如需 ACX 和 WDF 架構何時呼叫這些回呼函式的詳細資訊，請參閱 PnP 和電源管理案例。

如需提供此回呼函式之驅動程式的詳細資訊，請參閱 函式驅動程式中的支援 PnP 和電源管理。

範例

範例使用方式如下所示。

NTSTATUS
EvtCircuitPrepareHardware(
    _In_ WDFDEVICE      Device,
    _In_ ACXCIRCUIT     Circuit,
    _In_ WDFCMRESLIST   ResourcesRaw,
    _In_ WDFCMRESLIST   ResourcesTranslated
    )
{
    NTSTATUS            status      = STATUS_SUCCESS;
    PCIRCUIT_CONTEXT    circuitCtx  = GetCircuitContext(Circuit);
    CIpcEventReader *   eventReader = circuitCtx->EventReader;

    PASSIVE_CODE();

    UNREFERENCED_PARAMETER(Device);
    UNREFERENCED_PARAMETER(ResourcesRaw);
    UNREFERENCED_PARAMETER(ResourcesTranslated);

    //
    // Enable 'remote' circuit notifications.
    //
    ASSERT(eventReader);
    status = eventReader->EnableEvents();
    if (!NT_SUCCESS(status))
    {
        DrvLogError(g_RecorderLog, FLAG_INIT,
                    "ACXCIRCUIT %p, CIpcEventReader::EnableEvents failed, %!STATUS!",
                    Circuit, status);
        goto exit;
    }

    status = STATUS_SUCCESS;

exit:
    return status;
}

ACX 需求

最低 ACX 版本： 1.0

如需 ACX 版本的詳細資訊，請參閱 ACX 版本概觀。

規格需求

另請參閱

• acxcircuit.h 標頭