Files
lmxopcua/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/TwinCATTemporalCodec.cs
T
Joseph Doherty 826312befe docs: fill missing XML docs and strip tracking IDs from src comments
Clears CommentChecker findings in src/ (3,280 -> 209, the remainder being false
positives like PLC-5/IEEE-754/M0.0) by adding missing summaries/params/returns,
normalising inheritdoc usage, and removing Gitea/review tracking IDs while keeping
the rationale they annotated. Comment-only: comment-stripped sources are identical
to the parent commit.
2026-10-15 06:14:58 -04:00

85 lines
4.4 KiB
C#

namespace ZB.MOM.WW.OtOpcUa.Driver.TwinCAT;
/// <summary>
/// Converts the IEC 61131-3 temporal types between their 32-bit unsigned (UDINT) wire counters and the
/// values the driver publishes. TIME and TOD surface as a <see cref="double"/> of
/// milliseconds (OPC UA <c>Double</c>; no new <c>DriverDataType</c> member — see
/// <c>docs/drivers/TwinCAT.md</c>); DATE and DT surface as a UTC <see cref="DateTime"/>.
/// </summary>
internal static class TwinCATTemporalCodec
{
private static readonly DateTime Epoch = new(1970, 1, 1, 0, 0, 0, DateTimeKind.Utc);
/// <summary>True for TIME / DATE / DT / TOD.</summary>
/// <param name="type">The data type to test.</param>
/// <returns><see langword="true"/> when <paramref name="type"/> is a temporal type.</returns>
public static bool IsTemporal(TwinCATDataType type) =>
type is TwinCATDataType.Time or TwinCATDataType.Date
or TwinCATDataType.DateTime or TwinCATDataType.TimeOfDay;
/// <summary>Decodes a raw UDINT counter into the published value for <paramref name="type"/>.</summary>
/// <param name="type">The temporal data type.</param>
/// <param name="raw">The raw UDINT counter read from the PLC.</param>
/// <returns>A <see cref="double"/> of milliseconds for TIME/TOD, or a UTC <see cref="DateTime"/> for DATE/DT.</returns>
public static object Decode(TwinCATDataType type, uint raw) => type switch
{
TwinCATDataType.Time or TwinCATDataType.TimeOfDay => (double)raw,
TwinCATDataType.Date or TwinCATDataType.DateTime => Epoch.AddSeconds(raw),
_ => throw new ArgumentOutOfRangeException(nameof(type), type, "not a temporal type"),
};
/// <summary>
/// Encodes a published/written value into the UDINT counter. Accepts the native shape
/// (<see cref="double"/> ms / <see cref="DateTime"/> / <see cref="TimeSpan"/>) and any other
/// numeric as the raw counter, so a client writing an integer keeps working.
/// </summary>
/// <param name="type">The temporal data type.</param>
/// <param name="value">The value to encode.</param>
/// <returns>The UDINT counter to write to the PLC.</returns>
/// <exception cref="OverflowException">Out of the UDINT range, negative, or NaN/infinite.</exception>
/// <exception cref="InvalidCastException">A value of no accepted shape.</exception>
public static uint Encode(TwinCATDataType type, object? value)
{
switch (type)
{
case TwinCATDataType.Time or TwinCATDataType.TimeOfDay:
var ms = value switch
{
TimeSpan ts => ToUInt(ts.TotalMilliseconds),
DateTime => throw new InvalidCastException($"{type} takes a duration in milliseconds, not a DateTime"),
double d => ToUInt(d),
float f => ToUInt(f),
_ => Convert.ToUInt32(value),
};
// TOD is a time of day: a full day or more is not representable.
if (type == TwinCATDataType.TimeOfDay && ms >= 86_400_000u)
throw new OverflowException($"{ms} ms is not a time of day (< 86 400 000)");
return ms;
case TwinCATDataType.Date or TwinCATDataType.DateTime:
if (value is DateTime dt)
{
var utc = dt.Kind == DateTimeKind.Local ? dt.ToUniversalTime() : dt;
var secs = ToUInt(Math.Floor((utc - Epoch).TotalSeconds));
// DATE is a whole-day counter.
return type == TwinCATDataType.Date ? secs - secs % 86400u : secs;
}
if (value is TimeSpan) throw new InvalidCastException($"{type} takes a DateTime, not a duration");
return value switch
{
double d => ToUInt(d),
float f => ToUInt(f),
_ => Convert.ToUInt32(value),
};
default:
throw new ArgumentOutOfRangeException(nameof(type), type, "not a temporal type");
}
}
private static uint ToUInt(double v)
{
if (double.IsNaN(v) || double.IsInfinity(v) || v < 0 || v > uint.MaxValue)
throw new OverflowException($"{v} is outside the 32-bit unsigned range of an IEC temporal value");
return (uint)Math.Round(v, MidpointRounding.AwayFromZero);
}
}