HC_APTBS/Services/IUnlockService.cs

using System;
using System.Threading;
using System.Threading.Tasks;
using HC_APTBS.Models;

namespace HC_APTBS.Services
{
    /// <summary>
    /// Manages the immobilizer unlock sequence required by certain pump ECUs
    /// (e.g. Ford VP44 models) before they respond to test commands.
    /// </summary>
    public interface IUnlockService
    {
        /// <summary>Raised with progress text during the unlock sequence.</summary>
        event Action<string>? StatusChanged;

        /// <summary>Raised when the unlock sequence completes. Argument is true if successful.</summary>
        event Action<bool>? UnlockCompleted;

        /// <summary>
        /// Raised by the background observer on each lock→unlock transition. Unlike
        /// <see cref="UnlockCompleted"/>, this fires as soon as the CAN TestUnlock
        /// parameter confirms unlocked — regardless of whether the transition was
        /// caused by this service, an external manual unlock, or a fast-unlock
        /// completing early. Subscribers must marshal to the UI thread themselves.
        /// </summary>
        event Action? PumpUnlocked;

        /// <summary>
        /// Raised by the background observer on each unlock→lock transition —
        /// the symmetric counterpart to <see cref="PumpUnlocked"/>. Fires whenever
        /// the CAN TestUnlock parameter transitions from an unlocked state to a
        /// locked state (e.g. physical pump swap, power instability). Subscribers
        /// must marshal to the UI thread themselves.
        /// </summary>
        event Action? PumpRelocked;

        /// <summary>
        /// Latched state from the background observer. True when the observer has
        /// verified the pump is unlocked; false when the observer is not running
        /// or the pump is currently locked. Use alongside <see cref="PumpUnlocked"/>
        /// to race-guard "was the event already fired?".
        /// </summary>
        bool IsPumpUnlocked { get; }

        /// <summary>
        /// Starts a 1-second polling observer that watches the CAN TestUnlock
        /// parameter and raises <see cref="PumpUnlocked"/> on each lock→unlock
        /// transition. Idempotent: stops any prior observer before starting the
        /// new one. No-op when <see cref="PumpDefinition.UnlockType"/> is 0.
        /// </summary>
        void StartObserver(PumpDefinition pump);

        /// <summary>
        /// Stops the polling observer. Safe to call when no observer is active.
        /// Also resets <see cref="IsPumpUnlocked"/> to false.
        /// </summary>
        void StopObserver();

        /// <summary>
        /// Runs the immobilizer unlock sequence for the given pump.
        /// Returns immediately if <see cref="PumpDefinition.UnlockType"/> is 0 (no unlock needed).
        /// The persistent CAN senders remain active after this method returns;
        /// call <see cref="StopSenders"/> when the pump is deselected.
        /// </summary>
        /// <param name="pump">Pump definition with unlock type and CAN parameters.</param>
        /// <param name="ct">Cancellation token to abort the unlock sequence.</param>
        Task UnlockAsync(PumpDefinition pump, CancellationToken ct);

        /// <summary>
        /// Stops the persistent CAN unlock senders. Call this when the pump is
        /// deselected or the application is shutting down. Safe to call when no
        /// senders are active.
        /// </summary>
        void StopSenders();
    }
}