///
/// Copyright (c) 2020 Sensus Slovensko a.s.
///
using System;

namespace DataStreamInterface
{
    public interface IDataStreamMeter
    {
        /// <summary>
        /// Returns count of water meters supported by the data stream component
        /// </summary>
        /// <returns>Water meters count</returns>
        int GetMetersCount();

        /// <summary>
        /// Get state of the connected data stream meter
        /// </summary>
        /// <param name="meterIx">Index of the meter in range 0 .. (GetMetersCount() - 1)</param>
        /// <param name="state">Current state of the meter</param>
        /// <param name="parameter">Current extra parameter of the meter</param>
        /// <returns>true when successful</returns>
        bool GetState(int meterIx, out int state, out string parameter);

        /// <summary>
        /// Set state of the connected data stream meter
        /// </summary>
        /// <param name="meterIx">Index of the meter in range 0 .. (GetMetersCount() - 1)</param>
        /// <param name="state">Required state of the meter</param>
        /// <param name="parameter">Required extra parameter of the meter</param>
        /// <returns>true when successful</returns>
        bool SetState(int meterIx, int state, string parameter);

        bool SetStateAll(int state, string parameter);

        /// <summary>
        /// Establish connection with a data stream meter
        /// </summary>
        /// <param name="meterIx">Index of the meter in range 0 .. (GetMetersCount() - 1)</param>
        /// <param name="connectionParameters">Connection parameters</param>
        /// <param name="meterId">Meter ID (e.g. serial number)</param>
        /// <returns>true when successful</returns>
        bool OpenConnection(int meterIx, string connectionParameters, out string meterId);

        /// <summary>
        /// Stars saving measurement results into internal data structures of the component.
        /// Each data frame obtains a unique ID.
        /// The very first data fraim obrains ID = 0.
        /// </summary>
        /// <param name="meterIx">Index of the meter in range 0 .. (GetMetersCount() - 1)</param>
        /// <returns>true when successful</returns>
        bool StartMeasurement(int meterIx);

        bool StartMeasurementAll();

        /// <summary>
        /// Stops saving measurement results into internal data structures of the component.
        /// Updates ID of the last date frame received from the meter.
        /// </summary>
        /// <param name="meterIx">Index of the meter in range 0 .. (GetMetersCount() - 1)</param>
        /// <param name="storedFramesCount">Number of stored date frames</param>
        /// <returns>true when successful</returns>
        bool StopMeasurement(int meterIx, out Int64 storedFramesCount);

        bool StopMeasurementAll(out Int64[] storedFramesCounts);

        /// <summary>
        /// Closes connection with the data stream meter
        /// </summary>
        /// <param name="meterIx">Index of the meter in range 0 .. (GetMetersCount() - 1)</param>
        /// <returns>true when successful</returns>
        bool CloseConnection(int meterIx);

        bool CloseConnectionAll();

        /// <summary>
        /// This function is called when TBF program is shutting down.
        /// </summary>
        /// <returns>true when successful</returns>
        bool Shutdown();

        ///------------------------------------------------
        /// Units of time, volume and optional quantities
        ///------------------------------------------------

        /// <summary>
        /// Returns time units (s, ms, ...)
        /// </summary>
        Unit GetTimeUnits();

        /// <summary>
        /// Returns units of volume (ml, l, ...)
        /// </summary>
        Unit GetVolumeUnits();

        ///-----------------------------------------------
        /// Optional quantities: count, units, captions
        ///-----------------------------------------------

        /// <summary>
        /// Returns count of optional quantities in each data frame
        /// </summary>
        /// <returns>Count of optional quantities</returns>
        int GetQuantitiesCount();

        /// <summary>
        /// Returns units of the specified quantity
        /// </summary>
        /// <param name="quanityNr">Zero based quantity number 0 .. quantites count-1</param>
        Unit GetQuantityUnits(int quantityNr);

        /// <summary>
        /// Returns caption of the specified quantity
        /// </summary>
        /// <param name="quanityNr">Zero based quantity number 0 .. quantites count-1</param>
        string GetQuantityCaption(int quantityNr);

        ///---------------------------
        /// Datastream data exchange
        ///---------------------------

        /// <summary>
        /// Retuns 'count' data frames starting with data frame with ID = 'id' 
        /// </summary>
        /// <param name="meterIx">Index of the meter in range 0 .. (GetMetersCount() - 1)</param>
        /// <param name="id">First frame ID</param>
        /// <param name="count">Frames count</param>
        /// <returns>Selected data frames</returns>
        DataFrame[] GetFrames(int meterIx, Int64 id, int count);

        /// <summary>
        /// Returns ID of the data frame where time equals or exceeds the specified time.
        /// When time of the first frame (ID=0) is larger then specified time, function returns 0.
        /// </summary>
        /// <param name="meterIx">Index of the meter in range 0 .. (GetMetersCount() - 1)</param>
        /// <param name="time">Time</param>
        /// <returns>ID of the data frame at or after the pecified time</returns>
        Int64 GetID(int meterIx, double time);
    }
}