fonction de rappel EVT_ACX_CIRCUIT_POWER_DOWN (acxcircuit.h)

Article
02/06/2025

Le rappel EVT_ACX_CIRCUIT_POWER_DOWN est utilisé par le pilote pour ajouter des fonctionnalités dans le chemin d’arrêt de l’alimentation d’un objet ACXCIRCUIT.

Syntaxe

EVT_ACX_CIRCUIT_POWER_DOWN EvtAcxCircuitPowerDown;

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

Paramètres

Device

Objet WDFDEVICE (décrit dans WDF - Résumé des objets framework) associé à l’ACXCIRCUIT spécifié.

Circuit

Objet ACXCIRCUIT (décrit dans Résumé des objets ACX) mis hors tension.

TargetState

Énumérateur WDF_POWER_DEVICE_STATE typé qui identifie l’état d’alimentation de l’appareil que l’appareil est sur le point d’entrer.

Valeur de retour

Retourne STATUS_SUCCESS si l’appel a réussi. Sinon, elle retourne un code d’erreur approprié. Pour plus d’informations, consultez Using NTSTATUS Values.

Remarques

Pour inscrire une fonction de rappel EvtAcxCircuitPrepareHardware, un pilote doit appeler AcxCircuitInitSetAcxCircuitPnpPowerCallbacks.

Si le pilote a inscrit une fonction de rappel EvtCircuitPowerDown, l’infrastructure ACX appelle la fonction chaque fois que l’un des appareils du pilote quitte son état de fonctionnement (D0). Un appareil quitte l’état D0 lorsqu’un des éléments suivants se produit :

Le système et tous ses appareils sont sur le point de quitter leurs états de travail et d’entrer dans un état de faible puissance.
L’appareil est sur le point d’entrer un état de faible alimentation, car il est inactif, si l’appareil prend en charge l’inactivité à faible alimentation.
Le gestionnaire Plug-and-Play tente de redistribuer les ressources matérielles du système.
Un utilisateur a indiqué, généralement au moyen de l’interface utilisateur d’une application, qu’il souhaite supprimer l’appareil.
L’infrastructure appelle également la fonction de rappel EvtCircuitPowerDown une fois qu’un appareil a été supprimé de façon inattendue (supprimé par surprise).

Pour plus d’informations sur le moment où l’infrastructure appelle cette fonction de rappel, consultez PnP et Scénarios de gestion de l’alimentation.

Sauf si l’appareil a été supprimé par surprise, l’infrastructure ACX appelle cette fonction de rappel immédiatement après qu’elle désactive les interruptions de l’appareil, mais avant que la puissance de l’appareil soit réduite de D0 et avant que WDF appelle le rappel EvtDeviceD0Exit du pilote sur les appareils associés. Le paramètre TargetState identifie l’état d’alimentation de l’appareil que l’appareil est sur le point d’entrer.

La fonction de rappel EvtCircuitPowerDown doit effectuer toutes les opérations nécessaires avant que le matériel d’ACXCIRCUT entre dans l’état de faible alimentation spécifié, par exemple l’enregistrement des informations dont le pilote aura besoin ultérieurement pour restaurer le matériel d’ACXCIRCUIT à son état d’alimentation D0.

Si TargetState est WdfPowerDeviceD3Final, vous devez supposer que le système est désactivé, que l’appareil associé est sur le point d’être supprimé ou qu’un rééquilibrage des ressources est en cours. Si votre pilote doit enregistrer des informations, il doit l’écrire sur le disque ou sur un autre support de stockage permanent.

Pour plus d’informations sur les pilotes qui fournissent cette fonction de rappel, consultez Prise en charge de PnP et de gestion de l’alimentation dans le pilote de fonction.

Exemple

L’exemple d’utilisation est illustré ci-dessous. Cet exemple montre l’arrêt de certaines instances de minuteur dans le code de test lorsque le circuit est hors tension.

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;
}

Configuration requise pour ACX

version minimale d’ACX : 1.0

Pour plus d’informations sur les versions ACX, consultez vue d’ensemble de la version ACX.

Exigences

Exigence	Valeur
d’en-tête	acxcircuit.h
IRQL	PASSIVE_LEVEL

Voir aussi

en-tête acxcircuit.h
prise en charge de PnP et de gestion de l’alimentation dans le du pilote de fonction

Partager via