using System;
using System.Threading;
using System.Threading.Tasks;

namespace ZB.MOM.WW.OtOpcUa.Host.Domain
{
    /// <summary>
    ///     Abstraction over MXAccess COM client for tag read/write/subscribe operations.
    ///     (MXA-001 through MXA-009, OPC-007, OPC-008, OPC-009)
    /// </summary>
    public interface IMxAccessClient : IDisposable
    {
        /// <summary>
        ///     Gets the current runtime connectivity state for the bridge.
        /// </summary>
        ConnectionState State { get; }

        /// <summary>
        ///     Gets the number of active runtime subscriptions currently being mirrored into OPC UA.
        /// </summary>
        int ActiveSubscriptionCount { get; }

        /// <summary>
        ///     Gets the number of reconnect cycles attempted since the client was created.
        /// </summary>
        int ReconnectCount { get; }

        /// <summary>
        ///     Occurs when the MXAccess session changes state so the host can update diagnostics and retry logic.
        /// </summary>
        event EventHandler<ConnectionStateChangedEventArgs>? ConnectionStateChanged;

        /// <summary>
        ///     Occurs when a subscribed Galaxy attribute publishes a new runtime value.
        /// </summary>
        event Action<string, Vtq>? OnTagValueChanged;

        /// <summary>
        ///     Opens the MXAccess session required for runtime reads, writes, and subscriptions.
        /// </summary>
        /// <param name="ct">A token that cancels the connection attempt.</param>
        Task ConnectAsync(CancellationToken ct = default);

        /// <summary>
        ///     Closes the MXAccess session and releases runtime resources.
        /// </summary>
        Task DisconnectAsync();

        /// <summary>
        ///     Starts monitoring a Galaxy attribute so value changes can be pushed to OPC UA subscribers.
        /// </summary>
        /// <param name="fullTagReference">The fully qualified MXAccess reference for the target attribute.</param>
        /// <param name="callback">The callback to invoke when the runtime publishes a new value for the attribute.</param>
        Task SubscribeAsync(string fullTagReference, Action<string, Vtq> callback);

        /// <summary>
        ///     Stops monitoring a Galaxy attribute when it is no longer needed by the OPC UA layer.
        /// </summary>
        /// <param name="fullTagReference">The fully qualified MXAccess reference for the target attribute.</param>
        Task UnsubscribeAsync(string fullTagReference);

        /// <summary>
        ///     Reads the current runtime value for a Galaxy attribute.
        /// </summary>
        /// <param name="fullTagReference">The fully qualified MXAccess reference for the target attribute.</param>
        /// <param name="ct">A token that cancels the read.</param>
        /// <returns>The value, timestamp, and quality returned by the runtime.</returns>
        Task<Vtq> ReadAsync(string fullTagReference, CancellationToken ct = default);

        /// <summary>
        ///     Writes a new runtime value to a writable Galaxy attribute.
        /// </summary>
        /// <param name="fullTagReference">The fully qualified MXAccess reference for the target attribute.</param>
        /// <param name="value">The value to write to the runtime.</param>
        /// <param name="ct">A token that cancels the write.</param>
        /// <returns><see langword="true" /> when the write is accepted by the runtime; otherwise, <see langword="false" />.</returns>
        Task<bool> WriteAsync(string fullTagReference, object value, CancellationToken ct = default);
    }
}