EVT_ACX_CIRCUIT_POWER_DOWN fonction de rappel (acxcircuit.h)

Article
10/28/2023

Le rappel EVT_ACX_CIRCUIT_POWER_DOWN est utilisé par le pilote pour ajouter des fonctionnalités dans le chemin d’arrêt 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

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

TargetState

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

Valeur retournée

Retourne STATUS_SUCCESS si l’appel a réussi. Sinon, il retourne un code d’erreur approprié. Pour plus d’informations, consultez Utilisation de valeurs NTSTATUS.

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 lorsque l’un des éléments suivants se produit :

Le système et tous ses appareils sont sur le point de quitter leurs états de fonctionnement et d’entrer dans un état de faible consommation d’énergie.
L’appareil est sur le point d’entrer dans un état de faible consommation d’énergie, car il est inactif, si l’appareil prend en charge l’inactivité à faible consommation d’énergie.
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 souhaitait supprimer l’appareil.
L’infrastructure appelle également la fonction de rappel EvtCircuitPowerDown après la suppression inattendue d’un appareil (suppression surprise).

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

À moins que l’appareil n’ait été supprimé par surprise, l’infrastructure ACX appelle cette fonction de rappel immédiatement après avoir désactivé les interruptions de l’appareil, mais avant que l’alimentation de l’appareil soit réduite à partir 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 de l’ACXCIRCUT n’entre dans l’état de faible consommation spécifié, comme 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 les é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 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 du 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 d’ACX

Version minimale d’ACX : 1.0

Pour plus d’informations sur les versions d’ACX, consultez Vue d’ensemble des versions d’ACX.

Configuration requise

Condition requise	Valeur
En-tête	acxcircuit.h
IRQL	PASSIVE_LEVEL

Partager via