/*
 * IDownloadEnabled.cs
 * 
 * Copyright © 2010
 * Diversified Technical Systems, Inc.
 * All Rights Reserved.
 */

using System;
using DTS.Utilities;

/// <DevelopmentNote Developer="Paul Hrissikopoulos">
/// It may make sense to refactor this namespace to be DTS.DAS.Concepts.Tsr and rename the TSR-specific
/// event to "Event" so that the fully qualified name of the class is "DTS.DAS.Concepts.Tsr.Event", but
/// then maybe keep the IDownloadEnabled and other generic interfaces outside of the "Tsr"-specific
/// namespace...?  No, should probably stay with Event, since it has an "Event" type referenced in the
/// interface.
/// </DevelopmentNote>

namespace DTS.DAS.Concepts
{   ///
    /// <summary>
    /// Representation of data and metadata associated with a TSR event.
    /// </summary>
    /// 
    public abstract class TsrEvent : Exceptional, ICloneable
    {
        /// <summary>
        /// The 1-based <see cref="UInt64"/> identifier for this event.
        /// </summary>
        public virtual UInt64 EventId           { get; protected set; }

        /// <summary>
        /// The <see cref="System.DateTime"/> containing the date and time of this event.
        /// </summary>
        public virtual DateTime TimeStamp       { get; protected set; }

        /// <summary>
        /// The <see cref="string"/> serial number of the hardware that captured this event.
        /// </summary>
        public virtual string SerialNumber      { get; protected set; }

        /// <summary>
        /// The <see cref="string"/> alternate serial number of the hardware that captured the event.
        /// </summary>
        public virtual string AlternateSerialNumber { get; protected set; }

        /// <summary>
        /// The <see cref="double"/> duration in seconds of this event.
        /// </summary>
        public virtual double DurationSeconds   { get; protected set; }

        /// <summary>
        /// The <see cref="double"/> maximum sample rate for this event.
        /// </summary>
        public virtual double MaxSampleRate     { get; protected set; }   // note this is the "highest" sample rate

        /// <summary>
        /// The <see cref="float"/> temperature (in C).
        /// </summary>
        public virtual float TemperatureC       { get; protected set; }

        /// <summary>
        /// The <see cref="double"/> number of pre-trigger seconds.
        /// </summary>
        public virtual double PreTriggerSeconds { get; protected set; }

        ///
        /// <summary>
        /// Generate a shallow copy of this object.
        /// </summary>
        /// <returns>A shallow copy of this <see cref="object"/>.</returns>
        /// 
        public abstract object Clone();
    }

    ///
    /// <summary>
    /// Representation of the ability to download from this object.
    /// </summary>
    /// 
    public interface IDownloadEnabled
    {   //
        // TODO: Determine whether or not these things should be in here.  Maybe the implementing
        // object should just ask for them in the constructor and keep them private?  I don't think
        // these are universally applicable to something "download enabled"... are they?
        //
        //public uint MaximumStoredEventSizeSeconds { get; }
        //public ushort DownloadIncrementSamples    { get; }
        //public string[] ChannelDescription        { get; }
        //public int TimeOffsetMilliseconds         { get; }
        
        /// <summary>
        /// A list of download <see cref="DTS.DAS.Concepts.TsrEvent"/>s available for download.
        /// </summary>
        TsrEvent[] EventList {get;}

        ///
        /// <summary>
        /// Get the event data for the specified sample.
        /// </summary>
        /// <param name="Event">The <see cref="DTS.DAS.Concepts.TsrEvent"/> to have it's data extracted.</param>
        /// <param name="FirstSample">The <see cref="UInt64"/> index of the first sample to be downloaded.</param>
        /// <param name="LastSample">The <see cref="UInt64"/> index of the last sample to be downloaded.</param>
        /// <returns>An array of <see cref="double"/> data arrays for each channel.</returns>
        /// 
        double [][] GetEventData( TsrEvent Event, UInt64 FirstSample, UInt64 LastSample ); // Any reason to do data as an out parameter rather than a return value?
        // Have a subclassed channel class that has a data array, just so that 2-d array isn't so ambiguous?

        /// <summary>
        /// Determine whether or not the data on this download-enabled entity has been downloaded.
        /// </summary>
        bool DataHasBeenDownloaded { get; } 
    }
}