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

namespace Tango.Telemetry
{
    /// <summary>
    /// Represents a telemetry source that provides historical telemetry data.
    /// </summary>
    public interface ITelemetryHistorySource : ITelemetrySource
    {
        /// <summary>
        /// Gets the direction in which historical telemetry data should be published — either from oldest to newest, or vice versa.
        ///
        /// When the direction is set to <see cref="TelemetryHistorySourceDirection.Descending"/>, 
        /// only past data will be published. New data will not be published unless streamed from another source.
        ///
        /// When an <see cref="ITelemetryPublisher"/> calls <see cref="ITelemetryHistorySource.CanRequestHistory(DateTime)"/> or 
        /// <see cref="ITelemetryHistorySource.RequestHistory(DateTime)"/> for the first time and no checkpoints have been saved:
        /// <list type="bullet">
        /// <item><see cref="DateTime.MinValue"/> will be used if the direction is <see cref="TelemetryHistorySourceDirection.Ascending"/>.</item>
        /// <item><see cref="DateTime.MaxValue"/> will be used if the direction is <see cref="TelemetryHistorySourceDirection.Descending"/>.</item>
        /// </list>
        /// </summary>
        TelemetryHistorySourceDirection Direction { get; }

        /// <summary>
        /// Determines whether historical telemetry data can be requested starting from the specified timestamp.
        /// </summary>
        /// <param name="from">The start time for the historical data request.</param>
        /// <returns>
        /// A task that represents the asynchronous operation. 
        /// The task result contains true if history can be requested from the given time; otherwise, false.
        /// </returns>
        Task<bool> CanRequestHistory(DateTime from);

        /// <summary>
        /// Requests historical telemetry data starting from the specified timestamp.
        /// </summary>
        /// <param name="from">The start time for the telemetry history request.</param>
        /// <returns>
        /// A task that represents the asynchronous operation. 
        /// The task result contains a collection of historical telemetry records.
        /// </returns>
        Task<IEnumerable<ITelemetry>> RequestHistory(DateTime from);
    }
}