//******************************************************************************************************
//  CommonFrameHeader.cs - Gbtc
//
//  Copyright © 2012, Grid Protection Alliance.  All Rights Reserved.
//
//  Licensed to the Grid Protection Alliance (GPA) under one or more contributor license agreements. See
//  the NOTICE file distributed with this work for additional information regarding copyright ownership.
//  The GPA licenses this file to you under the MIT License (MIT), the "License"; you may
//  not use this file except in compliance with the License. You may obtain a copy of the License at:
//
//      http://www.opensource.org/licenses/MIT
//
//  Unless agreed to in writing, the subject software distributed under the License is distributed on an
//  "AS-IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. Refer to the
//  License for the specific language governing permissions and limitations.
//
//  Code Modification History:
//  ----------------------------------------------------------------------------------------------------
//  11/12/2004 - J. Ritchie Carroll
//       Generated original version of source code.
//  08/07/2009 - Josh L. Patterson
//       Edited Comments.
//  09/15/2009 - Stephen C. Wills
//       Added new header and license agreement.
//  12/17/2012 - Starlynn Danyelle Gilliam
//       Modified Header.
//
//******************************************************************************************************

using System;
using System.Collections.Generic;
using System.Runtime.Serialization;
using GSF.IO.Checksums;
using GSF.Parsing;

namespace GSF.PhasorProtocols.IEEE1344
{
    /// <summary>
    /// Represents the common header for all IEEE 1344 frames of data.
    /// </summary>
    [Serializable]
    public class CommonFrameHeader : ICommonHeader<FrameType>, ISerializable
    {
        #region [ Members ]

        // Constants

        /// <summary>
        /// Total fixed length of <see cref="CommonFrameHeader"/>.
        /// </summary>
        public const ushort FixedLength = 6;

        // Fields
        private FrameImageCollector m_frameImages;
        private ushort m_sampleCount;
        private ushort m_statusFlags;
        private Ticks m_timestamp;
        private IChannelParsingState m_state;

        #endregion

        #region [ Constructors ]

        /// <summary>
        /// Creates a new <see cref="CommonFrameHeader"/> from specified parameters.
        /// </summary>
        /// <param name="typeID">The IEEE 1344 specific frame type of this frame.</param>
        /// <param name="timestamp">The timestamp of this frame.</param>
        public CommonFrameHeader(FrameType typeID, Ticks timestamp)
        {
            m_timestamp = timestamp;
            TypeID = typeID;
            FrameCount = 1;
            IsFirstFrame = true;
            IsLastFrame = true;
        }

        /// <summary>
        /// Creates a new <see cref="CommonFrameHeader"/> from given <paramref name="buffer"/>.
        /// </summary>
        /// <param name="buffer">Buffer that contains data to parse.</param>
        /// <param name="startIndex">Start index into buffer where valid data begins.</param>
        public CommonFrameHeader(byte[] buffer, int startIndex)
        {
            uint secondOfCentury = BigEndian.ToUInt32(buffer, startIndex);
            m_sampleCount = BigEndian.ToUInt16(buffer, startIndex + 4);

            // We go ahead and pre-grab cell's status flags so we can determine frame length - we
            // leave start index at 6 so that cell will be able to parse flags as needed - note
            // this increases needed common frame header size by 2 (i.e., BinaryLength + 2)
            m_statusFlags = BigEndian.ToUInt16(buffer, startIndex + FixedLength);

            // NTP timestamps based on NtpTimeTag class are designed to work for dates between
            // 1968-01-20 and 2104-02-26 based on recommended bit interpretation in RFC-2030.
            NtpTimeTag timetag = new(secondOfCentury, 0);

            // Cache timestamp value
            m_timestamp = timetag.ToDateTime().Ticks;
        }

        /// <summary>
        /// Creates a new <see cref="CommonFrameHeader"/> from serialization parameters.
        /// </summary>
        /// <param name="info">The <see cref="SerializationInfo"/> with populated with data.</param>
        /// <param name="context">The source <see cref="StreamingContext"/> for this deserialization.</param>
        protected CommonFrameHeader(SerializationInfo info, StreamingContext context)
        {
            // Deserialize common frame header
            m_sampleCount = info.GetUInt16("sampleCount");
            m_statusFlags = info.GetUInt16("statusFlags");
        }

        #endregion

        #region [ Properties ]

        /// <summary>
        /// Gets the timestamp of this frame in NTP format.
        /// </summary>
        public NtpTimeTag TimeTag => new(m_timestamp);

        /// <summary>
        /// Gets or sets timestamp of this <see cref="CommonFrameHeader"/>.
        /// </summary>
        public Ticks Timestamp
        {
            get => m_timestamp;
            set => m_timestamp = value;
        }

        /// <summary>
        /// Gets or sets the IEEE 1344 specific frame type of this frame.
        /// </summary>
        /// <remarks>
        /// <para>
        /// This returns the protocol specific frame classification which uniquely identifies the frame type.
        /// </para>
        /// <para>
        /// This is the <see cref="ICommonHeader{TTypeIdentifier}.TypeID"/> implementation.
        /// </para>
        /// </remarks>
        public FrameType TypeID
        {
            get => (FrameType)(m_sampleCount & Common.FrameTypeMask);
            set => m_sampleCount = (ushort)((m_sampleCount & ~Common.FrameTypeMask) | (ushort)value);
        }

        /// <summary>
        /// Gets or sets flag from that determines if this is the first frame image in a series of images representing an entire frame.
        /// </summary>
        public bool IsFirstFrame
        {
            get => (m_sampleCount & (ushort)Bits.Bit12) == 0;
            set
            {
                if (value)
                    m_sampleCount = (ushort)(m_sampleCount & ~(ushort)Bits.Bit12);
                else
                    m_sampleCount = (ushort)(m_sampleCount | (ushort)Bits.Bit12);
            }
        }

        /// <summary>
        /// Gets or sets flag that determines if this is the last frame image in a series of images representing an entire frame.
        /// </summary>
        public bool IsLastFrame
        {
            get => (m_sampleCount & (ushort)Bits.Bit11) == 0;
            set
            {
                if (value)
                    m_sampleCount = (ushort)(m_sampleCount & ~(ushort)Bits.Bit11);
                else
                    m_sampleCount = (ushort)(m_sampleCount | (ushort)Bits.Bit11);
            }
        }

        /// <summary>
        /// Gets or sets the total frame count.
        /// </summary>
        public ushort FrameCount
        {
            get => (ushort)(m_sampleCount & Common.FrameCountMask);
            set
            {
                if (value > Common.MaximumFrameCount)
                    throw new OverflowException($"Frame count value cannot exceed {Common.MaximumFrameCount}");

                m_sampleCount = (ushort)((m_sampleCount & ~Common.FrameCountMask) | value);
            }
        }

        /// <summary>
        /// Gets or sets the parsing state for the <see cref="CommonFrameHeader"/> object.
        /// </summary>
        public IChannelParsingState State
        {
            get => m_state;
            set => m_state = value;
        }

        // Gets or sets any additional state information - satisfies ICommonHeader<FrameType>.State interface property
        object ICommonHeader<FrameType>.State
        {
            get => m_state;
            set => m_state = value as IChannelParsingState;
        }

        /// <summary>
        /// Gets the fundamental frame type of this frame.
        /// </summary>
        /// <remarks>
        /// Frames are generally classified as data, configuration or header frames. This returns the general frame classification.
        /// </remarks>
        public FundamentalFrameType FrameType
        {
            get
            {
                // Translate IEEE 1344 specific frame type to fundamental frame type
                return TypeID switch
                {
                    IEEE1344.FrameType.DataFrame => FundamentalFrameType.DataFrame,
                    IEEE1344.FrameType.ConfigurationFrame => FundamentalFrameType.ConfigurationFrame,
                    IEEE1344.FrameType.HeaderFrame => FundamentalFrameType.HeaderFrame,
                    _ => FundamentalFrameType.Undetermined,
                };
            }
        }

        /// <summary>
        /// Gets or sets reference to a <see cref="FrameImageCollector"/> associated the IEEE 1344 frame, if any.
        /// </summary>
        public FrameImageCollector FrameImages
        {
            get => m_frameImages;
            set => m_frameImages = value;
        }

        /// <summary>
        /// Gets or sets the entire length of the IEEE 1344 frame.
        /// </summary>
        public ushort FrameLength
        {
            get => (ushort)(m_statusFlags & Common.FrameLengthMask);
            set
            {
                if (value > Common.MaximumFrameLength)
                    throw new OverflowException($"Frame length value cannot exceed {Common.MaximumFrameLength}");

                m_statusFlags = (ushort)((m_statusFlags & ~Common.FrameLengthMask) | value);
            }
        }

        /// <summary>
        /// Gets or sets the length of the data in the IEEE 1344 frame (i.e., the <see cref="FrameLength"/> minus the header length and checksum: <see cref="FrameLength"/> - 8).
        /// </summary>
        public ushort DataLength
        {
            get =>
                // Data length will be frame length minus common header length minus crc16
                (ushort)(FrameLength - FixedLength - 2);
            set
            {
                if (value > Common.MaximumDataLength)
                    throw new OverflowException($"Data length value cannot exceed {Common.MaximumDataLength}");

                FrameLength = (ushort)(value + FixedLength + 2);
            }
        }

        /// <summary>
        /// Gets or sets the sample number (i.e., frame count) of this frame.
        /// </summary>
        public ushort SampleCount
        {
            get => (ushort)(m_sampleCount & ~Common.FrameTypeMask);
            set
            {
                if (value > Common.MaximumSampleCount)
                    throw new OverflowException($"Sample count value cannot exceed {Common.MaximumSampleCount}");

                m_sampleCount = (ushort)((m_sampleCount & Common.FrameTypeMask) | value);
            }
        }

        /// <summary>
        /// Gets the binary image of the common header portion of this frame.
        /// </summary>
        public byte[] BinaryImage
        {
            get
            {
                byte[] buffer = new byte[FixedLength];

                // Make sure frame length gets included in status flags for generated binary image
                FrameLength = FixedLength;

                BigEndian.CopyBytes((uint)TimeTag.Value, buffer, 0);
                BigEndian.CopyBytes(m_sampleCount, buffer, 4);

                return buffer;
            }
        }

        #endregion

        #region [ Methods ]

        /// <summary>
        /// Appends header specific attributes to <paramref name="attributes"/> dictionary.
        /// </summary>
        /// <param name="attributes">Dictionary to append header specific attributes to.</param>
        internal void AppendHeaderAttributes(Dictionary<string, string> attributes)
        {
            attributes.Add("Frame Type", $"{(ushort)TypeID}: {TypeID}");

            if (FrameImages is null)
            {
                attributes.Add("Frame Length", FrameLength.ToString());
                attributes.Add("Frame Images", "0");
            }
            else
            {
                attributes.Add("Frame Length", FrameImages.BinaryLength.ToString());
                attributes.Add("Frame Images", FrameImages.Count.ToString());
            }

            attributes.Add("Frame Count", FrameCount.ToString());
            attributes.Add("Sample Count", m_sampleCount.ToString());
            attributes.Add("Status Flags", m_statusFlags.ToString());
            attributes.Add("Is First Frame", IsFirstFrame.ToString());
            attributes.Add("Is Last Frame", IsLastFrame.ToString());
        }

        /// <summary>
        /// Populates a <see cref="SerializationInfo"/> with the data needed to serialize the target object.
        /// </summary>
        /// <param name="info">The <see cref="SerializationInfo"/> to populate with data.</param>
        /// <param name="context">The destination <see cref="StreamingContext"/> for this serialization.</param>
        public virtual void GetObjectData(SerializationInfo info, StreamingContext context)
        {
            // Serialize unique common frame header values
            info.AddValue("sampleCount", m_sampleCount);
            info.AddValue("statusFlags", m_statusFlags);
        }

        #endregion

        #region [ Static ]

        // Static Methods

        /// <summary>
        /// Validates the CRC-CCITT for the specified IEEE 1344 buffer.
        /// </summary>
        /// <returns>A <see cref="bool"/> indicating whether the checksum is valid.</returns>
        /// <param name="buffer">A <see cref="byte"/> array buffer.</param>
        /// <param name="length">An <see cref="int"/> value as the number of bytes to read for the checksum.</param>
        /// <param name="startIndex">An <see cref="int"/> value as the start index into being reading the value at.</param>
        public static bool ChecksumIsValid(byte[] buffer, int startIndex, int length)
        {
            int sumLength = length - 2;
            return BigEndian.ToUInt16(buffer, startIndex + sumLength) == buffer.CrcCCITTChecksum(startIndex, sumLength);
        }

        #endregion
    }
}