#region Copyright (c) 2011-2023 Technosoftware GmbH. All rights reserved
//-----------------------------------------------------------------------------
// Copyright (c) 2011-2023 Technosoftware GmbH. All rights reserved
// Web: https://www.technosoftware.com 
// 
// The source code in this file is covered under a dual-license scenario:
//   - Owner of a purchased license: SCLA 1.0
//   - GPL V3: everybody else
//
// SCLA license terms accompanied with this source code.
// See SCLA 1.0: https://technosoftware.com/license/Source_Code_License_Agreement.pdf
//
// GNU General Public License as published by the Free Software Foundation;
// version 3 of the License are accompanied with this source code.
// See https://technosoftware.com/license/GPLv3License.txt
//
// This source code is distributed in the hope that it will be useful, but
// WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
// or FITNESS FOR A PARTICULAR PURPOSE.
//-----------------------------------------------------------------------------
#endregion Copyright (c) 2011-2023 Technosoftware GmbH. All rights reserved

#region Using Directives
using System;
#endregion

namespace Technosoftware.DaAeHdaClient.Da
{
    /// <summary>
    /// Describes the state of a subscription.
    /// </summary>
    [Serializable]
    public class TsCDaSubscriptionState : ICloneable
    {
        #region Fields
        private bool active_ = true;
        private int updateRate_ = 500;
        private float deadband_;
        #endregion

        #region Properties
        /// <summary>
        /// A unique name for the subscription controlled by the client.
        /// </summary>
        public string Name { get; set; }

        /// <summary>
        /// A unique identifier for the subscription assigned by the client.
        /// </summary>
        public object ClientHandle { get; set; }

        /// <summary>
        /// A unique subscription identifier assigned by the server.
        /// </summary>
        public object ServerHandle { get; set; }

        /// <summary>
        /// The locale used for any error messages or results returned to the client.
        /// </summary>
        public string Locale { get; set; }

        /// <summary>
        /// Whether the subscription is scanning for updates to send to the client.
        /// </summary>
        public bool Active
        {
            get => active_;
            set => active_ = value;
        }

        /// <summary>
        /// The rate in milliseconds at which the server checks of updates to send to the
        /// client.
        /// </summary>
        /// <remarks>
        ///     Client Specifies the fastest rate at which data changes may be sent to the
        ///     <see cref="TsCDaDataChangedEventHandler">DataChangedHandler</see>
        ///     for items in this subscription. This also indicates the desired accuracy of Cached
        ///     Data. This is intended only to control the behavior of the interface. How the
        ///     server deals with the update rate and how often it actually polls the hardware
        ///     internally is an implementation detail. Passing 0 indicates the server should use
        ///     the fastest practical rate.
        /// </remarks>
        public int UpdateRate
        {
            get => updateRate_;
            set => updateRate_ = value;
        }

        /// <summary><para>The maximum period in milliseconds between updates sent to the client.</para></summary>
        /// <remarks>
        /// 	<para>Clients can set the keep-alive time for a subscription to cause the server to
        ///     provide client callbacks on the subscription when there are no new events to
        ///     report. Clients can then be assured of the health of the server and subscription
        ///     without resorting to pinging the server with calls to GetStatus().</para>
        /// 	<para>Using this facility, a client can expect a callback (data or keep-alive)
        ///     within the specified keep-alive time.</para>
        /// 	<para>Servers shall reset their keep-alive timers when real data is sent (i.e. it
        ///     is not acceptable to constantly send the keep-alive callback at a fixed period
        ///     equal to the keep-alive time irrespective of data callbacks).</para>
        /// 	<para>
        ///         The keep-alive callback consists of a call to the
        ///         <see cref="TsCDaDataChangedEventHandler">DataChangedEventHandler</see>
        ///         with an empty value list.
        ///     </para>
        /// 	<para>
        ///         Keep-alive callbacks will not occur when the subscription is inactive.
        ///         Keep-alive callbacks do not affect the value of the
        ///         <see cref="OpcServerStatus.LastUpdateTime">LastUpdateTime</see> returned by
        ///         <see cref="TsCDaServer.GetServerStatus">GetServerStatus()</see> .
        ///     </para>
        /// 	<para><strong>Available only for OPC Data Access 3.0 and OPC XML-DA
        ///     servers.</strong></para>
        /// </remarks>
        public int KeepAlive { get; set; }

        /// <summary>
        /// The minimum percentage change from 0.0 to 100.0 required to trigger a data update
        /// for an item.
        /// </summary>
        /// <remarks>
        /// 	<para>The range of the Deadband is from 0.0 to 100.0 Percent. Deadband will only
        ///     apply to items in the subscription that have a dwEUType of Analog available. If the
        ///     EU Type is Analog, then the EU Low and EU High values for the item can be used to
        ///     calculate the range for the item. This range will be multiplied with the Deadband
        ///     to generate an exception limit. An exception is determined as follows:</para>
        /// 	<blockquote dir="ltr" style="MARGIN-RIGHT: 0px">
        /// 		<para>Exception if (absolute value of (last cached value - current value) &gt;
        ///         (pPercentDeadband/100.0) * (EU High - EU Low) )</para>
        /// 	</blockquote>
        /// 	<para>The PercentDeadband can be set when CreateSubscription is called, allowing
        ///     the same PercentDeadband to be used for all items within that particular
        ///     subscription. However, with OPC DA 3.0, it is allowable to set the PercentDeadband
        ///     on a per item basis. This means that each item can potentially override the
        ///     PercentDeadband set for the subscription it resides within.</para>
        /// 	<para>If the exception limit is exceeded, then the last cached value is updated
        ///     with the new value and a notification will be sent to the client’s callback (if
        ///     any). The PercentDeadband is an optional behavior for the server. If the client
        ///     does not specify this value on a server that does support the behavior, the default
        ///     value of 0 (zero) will be assumed, and all value changes will update the CACHE.
        ///     Note that the timestamp will be updated regardless of whether the cached value is
        ///     updated. A server which does not support deadband should return an error
        ///     (OPC_E_DEADBANDNOTSUPPORTED) if the client requests a deadband other than
        ///     0.0.</para>
        /// 	<para>The UpdateRate for a subscription or the sampling rate of the item, if set,
        ///     determines time between when a value is checked to see if the exception limit has
        ///     been exceeded. The PercentDeadband is used to keep noisy signals from updating the
        ///     client unnecessarily.</para>
        /// </remarks>
        public float Deadband
        {
            get => deadband_;
            set => deadband_ = value;
        }

        /// <summary>
        /// TimeZone Bias of Group (in minutes).
        /// </summary>
        public int TimeBias { get; set; }
        #endregion

        #region ICloneable Members
        /// <summary>
        /// Creates a shallow copy of the object.
        /// </summary>
        public virtual object Clone()
        {
            return MemberwiseClone();
        }
        #endregion
    }
}