функция обратного вызова EVT_ACX_CIRCUIT_POWER_DOWN (acxcircuit.h)

Статья
02/06/2025

Обратный вызов EVT_ACX_CIRCUIT_POWER_DOWN используется драйвером для добавления функциональных возможностей в путь вниз объекта ACXCIRCUIT.

Синтаксис

EVT_ACX_CIRCUIT_POWER_DOWN EvtAcxCircuitPowerDown;

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

Параметры

Device

Объект WDFDEVICE (описанный в WDF — сводка объектов платформы), связанный с указанным ACXCIRCUIT.

Circuit

Объект ACXCIRCUIT (описанный в сводке объектов ACX) отключен.

TargetState

WDF_POWER_DEVICE_STATE типизированный перечислитель, определяющий состояние питания устройства, которое устройство будет вводить.

Возвращаемое значение

Возвращает STATUS_SUCCESS, если вызов выполнен успешно. В противном случае возвращается соответствующий код ошибки. Дополнительные сведения см. в использовании значений NTSTATUS.

Замечания

Чтобы зарегистрировать функцию обратного вызова EvtAcxCircuitPrepareHardware, драйвер должен вызвать AcxCircuitInitSetAcxCircuitPnpPowerCallbacks.

Если драйвер зарегистрировал функцию обратного вызова EvtCircuitPowerDown, платформа ACX вызывает функцию каждый раз, когда один из устройств драйвера покидает рабочее состояние (D0). Устройство покидает состояние D0, когда происходит одно из следующих действий:

Система и все его устройства собираются оставить свои рабочие состояния и ввести низкое состояние питания.
Устройство будет входить в состояние низкой мощности, так как оно неактивно, если устройство поддерживает простой с низкой мощностью.
Диспетчер Plug and Play пытается распространить аппаратные ресурсы системы.
Пользователь указал, как правило, с помощью пользовательского интерфейса приложения, что он или она хочет удалить устройство.
Платформа также вызывает функцию обратного вызова EvtCircuitPowerDown после неожиданного удаления устройства (неожиданное удаление).

Дополнительные сведения о том, когда платформа вызывает эту функцию обратного вызова, см. в сценариях управления питанием и PnP.

Если устройство не было неожиданно удалено, платформа ACX вызывает эту функцию обратного вызова сразу после отключения прерываний устройства, но до уменьшения мощности устройства от D0 и до вызова WDF обратного вызова драйвера EvtDeviceD0Exit на связанных устройствах. Параметр TargetState определяет состояние питания устройства, которое устройство будет входить.

Функция обратного вызова EvtCircuitPowerDown должна выполнять любые операции, необходимые до того, как оборудование ACXCIRCUT входит в указанное состояние низкой мощности, например сохранение сведений, необходимых драйверу позже для восстановления оборудования ACXCIRCUIT в его состоянии питания D0.

Если TargetState — WdfPowerDeviceD3Final, следует предположить, что система отключена, связанное устройство будет удалено или выполняется перебалансация ресурсов. Если драйвер должен сохранить сведения, он должен записать его на диск или другой постоянный носитель хранилища.

Дополнительные сведения о драйверах, предоставляющих эту функцию обратного вызова, см. в поддержки PnP и управления питанием в драйвере функций.

Пример

Ниже показан пример использования. В этом примере показано, как остановить некоторые экземпляры таймера в тестовом коде при отключении канала.

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.

Требования

Требование	Ценность
заголовка	acxcircuit.h
IRQL	PASSIVE_LEVEL

См. также

заголовка acxcircuit.h
поддержки PnP и управления питанием в драйвера функций

Поделиться через