using System;
using System.Collections.Generic;
using System.Threading;
using System.Threading.Tasks;

namespace ZB.MOM.WW.OtOpcUa.Driver.Historian.Wonderware.Backend
{
    /// <summary>
    ///     OPC-UA-free surface for the Wonderware Historian subsystem inside the historian
    ///     sidecar process. Implementations read via the aahClient* SDK; the .NET 10
    ///     <c>WonderwareHistorianClient</c> on the other side of the named-pipe IPC maps
    ///     returned samples to OPC UA <c>DataValue</c>. The v1 Galaxy.Host / Proxy hosts
    ///     this lived in retired in PR 7.2.
    /// </summary>
    public interface IHistorianDataSource : IDisposable
    {
        /// <summary>Reads raw historical samples asynchronously.</summary>
        /// <param name="tagName">The tag name to read from.</param>
        /// <param name="startTime">The start time of the time range.</param>
        /// <param name="endTime">The end time of the time range.</param>
        /// <param name="maxValues">The maximum number of values to return.</param>
        /// <param name="ct">The cancellation token.</param>
        /// <returns>A task representing the asynchronous operation that returns a list of historian samples.</returns>
        Task<List<HistorianSample>> ReadRawAsync(
            string tagName, DateTime startTime, DateTime endTime, int maxValues,
            CancellationToken ct = default);

        /// <summary>Reads aggregate historical samples asynchronously.</summary>
        /// <param name="tagName">The tag name to read from.</param>
        /// <param name="startTime">The start time of the time range.</param>
        /// <param name="endTime">The end time of the time range.</param>
        /// <param name="intervalMs">The interval in milliseconds for aggregation.</param>
        /// <param name="aggregateColumn">The column to aggregate.</param>
        /// <param name="ct">The cancellation token.</param>
        /// <returns>A task representing the asynchronous operation that returns a list of aggregate samples.</returns>
        Task<List<HistorianAggregateSample>> ReadAggregateAsync(
            string tagName, DateTime startTime, DateTime endTime,
            double intervalMs, string aggregateColumn,
            CancellationToken ct = default);

        /// <summary>Reads historical samples at specific times asynchronously.</summary>
        /// <param name="tagName">The tag name to read from.</param>
        /// <param name="timestamps">The array of timestamps at which to read values.</param>
        /// <param name="ct">The cancellation token.</param>
        /// <returns>A task representing the asynchronous operation that returns a list of historian samples.</returns>
        Task<List<HistorianSample>> ReadAtTimeAsync(
            string tagName, DateTime[] timestamps,
            CancellationToken ct = default);

        /// <summary>Reads historical events asynchronously.</summary>
        /// <param name="sourceName">The source name to filter events, or null for all sources.</param>
        /// <param name="startTime">The start time of the time range.</param>
        /// <param name="endTime">The end time of the time range.</param>
        /// <param name="maxEvents">The maximum number of events to return.</param>
        /// <param name="ct">The cancellation token.</param>
        /// <returns>A task representing the asynchronous operation that returns a list of historian events.</returns>
        Task<List<HistorianEventDto>> ReadEventsAsync(
            string? sourceName, DateTime startTime, DateTime endTime, int maxEvents,
            CancellationToken ct = default);

        /// <summary>Gets a health snapshot of the data source.</summary>
        /// <returns>A HistorianHealthSnapshot containing the current health information.</returns>
        HistorianHealthSnapshot GetHealthSnapshot();
    }
}