using ZB.MOM.WW.ScadaBridge.Commons.Types.Alarms;

namespace ZB.MOM.WW.ScadaBridge.Commons.Interfaces.Protocol;

/// <summary>Callback invoked when a native alarm transition (incl. snapshot replay) arrives.</summary>
/// <param name="transition">The protocol-neutral transition emitted by the adapter.</param>
public delegate void AlarmTransitionCallback(NativeAlarmTransition transition);

/// <summary>
/// Optional capability for an <see cref="IDataConnection"/> implementation that
/// can mirror a source's native alarms (OPC UA Alarms &amp; Conditions, MxAccess
/// Gateway StreamAlarms). Mirrors the <see cref="IBrowsableDataConnection"/>
/// capability-interface pattern; consumed by the DataConnectionActor only.
/// </summary>
public interface IAlarmSubscribableConnection
{
    /// <summary>
    /// Subscribes to native alarm transitions for the conditions under
    /// <paramref name="sourceReference"/>. The adapter replays a snapshot of
    /// currently-active conditions (Snapshot…SnapshotComplete) on every
    /// (re)subscribe. Returns a subscription id for <see cref="UnsubscribeAlarmsAsync"/>.
    /// </summary>
    /// <param name="sourceReference">The source object reference to subscribe alarms for.</param>
    /// <param name="conditionFilter">Optional condition name filter; <c>null</c> subscribes to all conditions.</param>
    /// <param name="callback">Delegate invoked on each incoming alarm transition.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>A task that resolves to the subscription id for use with <see cref="UnsubscribeAlarmsAsync"/>.</returns>
    Task<string> SubscribeAlarmsAsync(string sourceReference, string? conditionFilter,
        AlarmTransitionCallback callback, CancellationToken cancellationToken = default);

    /// <summary>Cancels an active alarm subscription by its id.</summary>
    /// <param name="subscriptionId">The subscription id returned by <see cref="SubscribeAlarmsAsync"/>.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>A task that represents the asynchronous operation.</returns>
    Task UnsubscribeAlarmsAsync(string subscriptionId, CancellationToken cancellationToken = default);
}
