lmxopcua/src/ZB.MOM.WW.LmxOpcUa.Host/Domain/Vtq.cs

using System;

namespace ZB.MOM.WW.LmxOpcUa.Host.Domain
{
    /// <summary>
    ///     Value-Timestamp-Quality triplet for tag data. (MXA-003, OPC-007)
    /// </summary>
    public readonly struct Vtq : IEquatable<Vtq>
    {
        /// <summary>
        ///     Gets the runtime value returned for the Galaxy attribute.
        /// </summary>
        public object? Value { get; }

        /// <summary>
        ///     Gets the timestamp associated with the runtime value.
        /// </summary>
        public DateTime Timestamp { get; }

        /// <summary>
        ///     Gets the quality classification that tells OPC UA clients whether the value is usable.
        /// </summary>
        public Quality Quality { get; }

        /// <summary>
        ///     Initializes a new instance of the <see cref="Vtq" /> struct for a Galaxy attribute value.
        /// </summary>
        /// <param name="value">The runtime value returned by MXAccess.</param>
        /// <param name="timestamp">The timestamp assigned to the runtime value.</param>
        /// <param name="quality">The quality classification for the runtime value.</param>
        public Vtq(object? value, DateTime timestamp, Quality quality)
        {
            Value = value;
            Timestamp = timestamp;
            Quality = quality;
        }

        /// <summary>
        ///     Creates a good-quality VTQ snapshot for a successfully read or subscribed attribute value.
        /// </summary>
        /// <param name="value">The runtime value to wrap.</param>
        /// <returns>A VTQ carrying the provided value with the current UTC timestamp and good quality.</returns>
        public static Vtq Good(object? value)
        {
            return new Vtq(value, DateTime.UtcNow, Quality.Good);
        }

        /// <summary>
        ///     Creates a bad-quality VTQ snapshot when no usable runtime value is available.
        /// </summary>
        /// <param name="quality">The specific bad quality reason to expose to clients.</param>
        /// <returns>A VTQ with no value, the current UTC timestamp, and the requested bad quality.</returns>
        public static Vtq Bad(Quality quality = Quality.Bad)
        {
            return new Vtq(null, DateTime.UtcNow, quality);
        }

        /// <summary>
        ///     Creates an uncertain VTQ snapshot when the runtime value exists but should be treated cautiously.
        /// </summary>
        /// <param name="value">The runtime value to wrap.</param>
        /// <returns>A VTQ carrying the provided value with the current UTC timestamp and uncertain quality.</returns>
        public static Vtq Uncertain(object? value)
        {
            return new Vtq(value, DateTime.UtcNow, Quality.Uncertain);
        }

        /// <summary>
        ///     Compares two VTQ snapshots for exact value, timestamp, and quality equality.
        /// </summary>
        /// <param name="other">The other VTQ snapshot to compare.</param>
        /// <returns><see langword="true" /> when all fields match; otherwise, <see langword="false" />.</returns>
        public bool Equals(Vtq other)
        {
            return Equals(Value, other.Value) && Timestamp == other.Timestamp && Quality == other.Quality;
        }

        /// <inheritdoc />
        public override bool Equals(object? obj)
        {
            return obj is Vtq other && Equals(other);
        }

        /// <inheritdoc />
        public override int GetHashCode()
        {
            return HashCode.Combine(Value, Timestamp, Quality);
        }

        /// <inheritdoc />
        public override string ToString()
        {
            return $"Vtq({Value}, {Timestamp:O}, {Quality})";
        }
    }
}