EVT_ACX_CIRCUIT_POWER_DOWN コールバック関数 (acxcircuit.h)

  • [アーティクル]

EVT_ACX_CIRCUIT_POWER_DOWN コールバックは、ACXCIRCUIT オブジェクトの電源ダウン パスに機能を追加するためにドライバーによって使用されます。

構文

EVT_ACX_CIRCUIT_POWER_DOWN EvtAcxCircuitPowerDown;

NTSTATUS EvtAcxCircuitPowerDown(
  WDFDEVICE Device,
  ACXCIRCUIT Circuit,
  WDF_POWER_DEVICE_STATE TargetState
)
{...}

パラメーター

Device

指定した ACXCIRCUIT に関連付けられた WDFDEVICE オブジェクト (WDF - フレームワーク オブジェクトの概要に関するページで説明)。

Circuit

ACXCIRCUIT オブジェクト ( ACX オブジェクトの概要で説明) の電源がオフになっています。

TargetState

WDF_POWER_DEVICE_STATE入力しようとしているデバイスの電源状態を識別する型指定された列挙子。

戻り値

STATUS_SUCCESS呼び出しが成功した場合は を返します。 それ以外の場合は、適切なエラー コードを返します。 詳細については、「 NTSTATUS 値の使用」を参照してください。

注釈

EvtAcxCircuitPrepareHardware コールバック関数を登録するには、ドライバーが AcxCircuitInitSetAcxCircuitPnpPowerCallbacks を呼び出す必要があります。

ドライバーが EvtCircuitPowerDown コールバック関数を登録している場合、ACX フレームワークは、ドライバーのデバイスの 1 つが動作 (D0) 状態を離れるたびに関数を呼び出します。 次のいずれかが発生すると、デバイスは D0 状態を残します。

  • システムとそのすべてのデバイスは、動作状態を残し、低電力状態に入りようとしています。
  • デバイスが低電力アイドルをサポートしている場合、デバイスはアイドル状態であるため、低電力状態に入りそうになっています。
  • プラグ アンド プレイ マネージャーは、システムのハードウェア リソースを再配布しようとしています。
  • ユーザーは、通常、アプリケーションのユーザー インターフェイスを使用して、デバイスを削除することを示しています。
  • また、デバイスが予期せず (突然削除された) 後に、フレームワークによって EvtCircuitPowerDown コールバック関数が呼び出されます。

フレームワークがこのコールバック関数を呼び出すタイミングの詳細については、「PnP と Power Management のシナリオ」を参照してください。

デバイスが突然削除されていない限り、ACX フレームワークは、デバイスの割り込みを無効にした直後に、デバイスの電源が D0 から減る前、および WDF が関連付けられているデバイスでドライバーの EvtDeviceD0Exit コールバックを呼び出す前に、このコールバック関数を呼び出します。 TargetState パラメーターは、デバイスが入力しようとしているデバイスの電源状態を識別します。

EvtCircuitPowerDown コールバック関数は、ACXCIRCUT のハードウェアが指定された低電力状態になる前に必要な操作を実行する必要があります。たとえば、ACXCIRCUIT のハードウェアを D0 電源状態に復元するためにドライバーが後で必要とする情報を保存するなどです。

TargetState が WdfPowerDeviceD3Final の場合は、システムがオフになっているか、関連付けられているデバイスが削除されようとしているか、リソースの再調整が進行中であると想定する必要があります。 ドライバーが情報を保存する必要がある場合は、ディスクまたはその他の永続的な記憶域メディアに書き込む必要があります。

このコールバック関数を提供するドライバーの詳細については、「 Function Driver での PnP と Power Management のサポート」を参照してください。

例

使用例を次に示します。 この例では、回線の電源が切れたときに、テスト コードで一部のタイマー インスタンスを停止する方法を示します。

EVT_ACX_CIRCUIT_POWER_DOWN          CodecR_EvtCircuitPowerDown;

NTSTATUS
CreateCircuit()
{
    ...
    ACX_CIRCUIT_PNPPOWER_CALLBACKS_INIT(&powerCallbacks);
    powerCallbacks.EvtAcxCircuitPowerUp = CodecR_EvtCircuitPowerUp;
    powerCallbacks.EvtAcxCircuitPowerDown = CodecR_EvtCircuitPowerDown;
    AcxCircuitInitSetAcxCircuitPnpPowerCallbacks(circuitInit, &powerCallbacks);
    ...
}

NTSTATUS
CodecR_EvtCircuitPowerDown (
    _In_ WDFDEVICE  Device,
    _In_ ACXCIRCUIT Circuit,
    _In_ WDF_POWER_DEVICE_STATE TargetState
    )
{
    UNREFERENCED_PARAMETER(Device);
    UNREFERENCED_PARAMETER(TargetState);
    
    CODEC_RENDER_CIRCUIT_CONTEXT *  circuitCtx;
    CODEC_MUTE_ELEMENT_CONTEXT *    muteCtx;
    CODEC_VOLUME_ELEMENT_CONTEXT *  volumeCtx;

    PAGED_CODE();
    
    // for testing.
    circuitCtx = GetRenderCircuitContext(Circuit);
    ASSERT(circuitCtx);

    ASSERT(circuitCtx->MuteElement);
    muteCtx = GetCodecMuteElementContext(circuitCtx->MuteElement);
    ASSERT(muteCtx);
    
    ASSERT(muteCtx->Timer);
    WdfTimerStop(muteCtx->Timer, TRUE);

    ASSERT(circuitCtx->VolumeElement);
    volumeCtx = GetCodecVolumeElementContext(circuitCtx->VolumeElement);
    ASSERT(volumeCtx);

    ASSERT(volumeCtx->Timer);
    WdfTimerStop(volumeCtx->Timer, TRUE);

    return STATUS_SUCCESS;
}

ACX の要件

最小 ACX バージョン: 1.0

ACX バージョンの詳細については、「 ACX バージョンの概要」を参照してください。

要件

要件 値
Header acxcircuit.h
IRQL PASSIVE_LEVEL

こちらもご覧ください