DP44/enriched-qwen3-coder-next/Common/DTS.CommonCore/Utils.md

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
Common/DTS.CommonCore/Utils/XMLUtils.cs Common/DTS.CommonCore/Utils/EnumUtils.cs Common/DTS.CommonCore/Utils/ImageButton.cs Common/DTS.CommonCore/Utils/PNGImageUtil.cs Common/DTS.CommonCore/Utils/MouseUtils.cs Common/DTS.CommonCore/Utils/StopWatch.cs Common/DTS.CommonCore/Utils/SerializableDictionary.cs Common/DTS.CommonCore/Utils/TestUtils.cs Common/DTS.CommonCore/Utils/SecureQueue.cs Common/DTS.CommonCore/Utils/ByteConverter.cs Common/DTS.CommonCore/Utils/NetworkUtils.cs Common/DTS.CommonCore/Utils/BusyWaitAnimation.cs	2026-04-16T02:13:53.536236+00:00	Qwen/Qwen3-Coder-Next-FP8	1	0a10ccd507cef203

DTS.Common.Utils Module Documentation

1. Purpose

This module provides a collection of utility classes and static helper methods for common operations across the DTS (Data Acquisition and Test System) codebase. It serves as a foundational layer supporting UI components (ImageButton, BusyWaitAnimation), data serialization (SerializableDictionary), low-level binary operations (ByteConvertor), network diagnostics (NetworkUtils), timing and profiling (StopWatchQueue), enumeration handling (EnumUtil), image rendering (PNGImageUtil), mouse coordinate translation (MouseUtilities), and test-specific utilities (TestUtils). The module consolidates cross-cutting concerns to avoid duplication and promote consistency across the system.

2. Public Interface

EnumUtil (static class)

• GetValues<T>()
  Returns an IEnumerable<T> of all enum values of type T using Enum.GetValues.
• GetValuesList<T>()
  Returns an ItemCollection (from Xceed.Wpf.Toolkit.PropertyGrid.Attributes) containing key-value pairs of enum values and their names.

ImageButton (class, inherits Button)

• Constructor ImageButton()
  Initializes a StackPanel-based button with an Image and TextBlock arranged vertically.
• Source (property, ImageSource)
  Gets/sets the image displayed in the button.
• ImageText (property, string)
  Gets/sets the text displayed below the image.

PNGImageUtil (static class)

• SaveImage(FrameworkElement view, string fileName)
  Renders the given WPF FrameworkElement to a PNG file at fileName using RenderTargetBitmap and PngBitmapEncoder.

MouseUtilities (class)

• GetMousePosition(Visual relativeTo)
  Returns the current mouse cursor position as a Point, transformed to be relative to the specified Visual. Uses Win32 API (GetCursorPos, ScreenToClient) and WPF transform logic. Includes scaling correction based on CompositionTarget.TransformToDevice.

StopWatchQueue (class)

• Constructor StopWatchQueue(string name)
  Initializes a queue with a name and internal Stopwatch and Queue<long> (capacity 5000).
• Start()
  Starts the internal Stopwatch.
• Stop()
  Stops the Stopwatch, enqueues the elapsed ticks, and resets the Stopwatch.
• DumpData()
  Writes timing statistics (count, max, min, average, standard deviation) and all recorded values (in milliseconds) to a timestamped CSV file named <name><filetime>.csv.
• Finalizer ~StopWatchQueue()
  Calls DumpData() on disposal (via finalization).

SerializableDictionary<TKey, TValue> (class, implements IXmlSerializable)

• Constructor
  Inherits from Dictionary<TKey, TValue> and implements IXmlSerializable.
• GetSchema()
  Returns null.
• ReadXml(XmlReader reader)
  Deserializes a dictionary from XML with <items><item><key>...</key><value>...</value></item>...</items> structure.
• WriteXml(XmlWriter writer)
  Serializes the dictionary to the same XML structure.

TestModuleTimeStamp (class)

• TriggerTimestampSec (int)
  Seconds component of a timestamp.
• TriggerTimestampNanoSec (int)
  Nanoseconds component of a timestamp.

TestUtils (static class)

• MinUnixTime(IEnumerable<TestModuleTimeStamp> basemodules)
  Returns a Tuple<double, double> of (TriggerTimestampSec, TriggerTimestampNanoSec) for the earliest timestamp that satisfies:
  moduleTime > utcAverage - utcStandardDeviation,
  where moduleTime = sec + nano / NANOS_PER_SECOND.
  If no modules or invalid input, returns null.
  Note: Logic appears to select the earliest timestamp within one standard deviation below the mean.
• ParseROISuffix(string test)
  Extracts ROI suffix from a colon-separated test string. Tries two strategies:
  1. If ≥4 segments, returns last segment.
  2. If contains EventNumber, returns suffix after last underscore in that segment (prefixed with _).
     Returns string.Empty if no match.

SecureQueue<T> (class, implements IDisposable)

• NullPolicy enum
  DenyNull, SkipNull, AllowNull — behavior when Enqueue receives null or zero-length array.
• Constructor SecureQueue(NullPolicy policy, string name)
  Initializes queue with policy, name, and internal locking/event mechanisms.
• ResetEvent()
  Resets the internal ManualResetEvent.
• Enqueue(T[] newData)
  Thread-safe enqueue with null-checking per policy. Logs via APILogger if ExtraCommunicationLogging is enabled.
• WaitForData(int timeoutMillisec)
  Blocks up to timeoutMillisec for data; returns true if data arrived, false on timeout.
• QueueWaitHandle (property)
  Exposes the internal ManualResetEvent as a WaitHandle.
• Dequeue(bool resetEvent)
  Thread-safe dequeue: concatenates all queued arrays into one large array. Resets internal event. Returns empty array if queue empty.
• Flush()
  Clears the queue and resets the event.
• IsEmpty()
  Returns true if queue count is zero.
• Dispose()
  No-op (empty implementation).

ByteConvertor (class)

• Convert(byte[] input, int offset, out T value)
  Reads from input at offset and deserializes to T (supports byte, ushort, short, uint, int, ulong, long, float, double, string).
  Note: Integer types are read in big-endian (network) order (e.g., ushort uses input[offset+0] << 8 | input[offset+1]).
  float/double use BitConverter (host-endian).
  string reads until null terminator.
• ToByteArray(T value)
  Serializes T to a byte array in big-endian (network) order (e.g., ToByteArray(ushort) writes high byte first).
  float/double use BitConverter.GetBytes (host-endian).
  string writes characters + null terminator.

NetworkUtils (static class)

• IsNetworkInterfaceUp(IPAddress ip)
  Returns true if the given IP is assigned to an active, non-loopback, IPv4-enabled, multicast-capable network interface. Skips 169.254.x.x (link-local) addresses.
• GetAvailableNetworkInterfaces(long minimumSpeed = 10000000)
  Returns list of NetworkInterfaces that are non-loopback, non-virtual, non-Bluetooth, non-modem, and meet minimum speed. Excludes Npcap interfaces.
• GetAvailableHosts(bool supportMulticastOnly = false)
  Returns List<HostInfo> (custom type, not shown) with IP, network ID, MAC, and start/end addresses for each valid unicast IPv4 interface. Skips 169.254.x.x and Npcap interfaces.
• GetStartAndEndAddress(IPAddress ip, IPAddress mask, out string startAddress, out string endAddress)
  Computes network start (AND of IP and mask) and broadcast end (OR of IP and inverted mask) addresses. Returns empty strings on error.
• TryParseConnectionString(string connectionString, out string ipAddress)
  Attempts to extract an IP address from a connection string (supports URI or colon-separated format). Returns true if successful and IP is valid.

BusyWaitAnimation (class)

• StylePresets enum
  MacOsx, Firefox, Ie7, Custom.
• Properties
  Color, BgColor, OuterCircleRadius, InnerCircleRadius, NumberSpoke, Active, SpokeThickness, RotationSpeed, StylePreset.
• Constructor BusyWaitAnimation()
  Initializes timer, appearance, and drawing resources.
• SetCircleAppearance(int numberSpoke, int spokeThickness, int innerCircleRadius, int outerCircleRadius)
  Updates appearance parameters and invalidates.
• GDIGraphics (property)
  Exposes internal Graphics object.
• hDC (property)
  Gets/sets the device context handle and initializes Graphics.
• SetDrawArea(Rectangle rect)
  Sets drawing bounds and initializes backing bitmap and graphics.

3. Invariants

• ByteConvertor.Convert for integers: Always interprets multi-byte values in big-endian (network byte order), regardless of host architecture.
• ByteConvertor.ToByteArray for integers: Always outputs in big-endian (network byte order).
• PNGImageUtil.SaveImage: Requires view.ActualWidth and view.ActualHeight to be positive and non-zero; otherwise, RenderTargetBitmap may fail or produce invalid output.
• StopWatchQueue: Records elapsed ticks in Stop(); values are converted to milliseconds using Stopwatch.Frequency during DumpData().
• SecureQueue<T>:
  • Dequeue() concatenates all queued arrays into a single array — not a FIFO of arrays.
  • Dequeue() always resets the internal ManualResetEvent, even if the queue was empty.
  • Thread-safety is ensured via lock(ByteQueueLock).
• TestUtils.MinUnixTime:
  • Uses Common.Constants.NANOS_PER_SECOND and Common.Constants.TEN_MILLIS_IN_SEC (not defined in this module).
  • Selects the first module satisfying the condition in iteration order, not necessarily the globally earliest valid timestamp.
• TestUtils.ParseROISuffix:
  • Relies on DTS.Common.Constants.EventNumber (not defined here).
  • Returns _ + last segment only if the last segment does not contain the event number string.
• NetworkUtils.IsNetworkInterfaceUp: Skips interfaces with no IPv4 properties or link-local (169.254.x.x) addresses.

4. Dependencies

Internal Dependencies (from source)

• DTS.Common.Interface (via TestUtils.cs)
• DTS.Common.Utilities.Logging (via SecureQueue.cs, NetworkUtils.cs)
• DTS.DASLib.Utility (namespace for SerializableDictionary in SerializableDictionary.cs)
• DTS.Common.Constants (referenced but not defined in this module — used in TestUtils.cs)
• Xceed.Wpf.Toolkit.PropertyGrid.Attributes (for ItemCollection in EnumUtil.cs)

External Dependencies (via using)

• System: System.Collections.Generic, System.Diagnostics, System.IO, System.Linq, System.Text, System.Threading, System.Threading.Tasks, System.Windows, System.Windows.Media, System.Windows.Media.Imaging, System.Windows.Threading, System.Windows.Forms, System.Drawing, System.Drawing.Drawing2D, System.Runtime.InteropServices, System.Xml, System.Xml.Serialization, System.Net, System.Net.NetworkInformation, System.Net.Sockets
• Windows Presentation Foundation (WPF): System.Windows.Controls, System.Windows.Interop, System.Windows.Media.Imaging
• Windows Forms: System.Windows.Forms
• GDI+: System.Drawing, System.Drawing.Drawing2D
• Win32 API: user32.dll (for GetCursorPos, GetPhysicalCursorPos, ScreenToClient)

Inferred Consumers

• UI components (ImageButton, BusyWaitAnimation) likely used in WPF/WinForms UI layers.
• ByteConvertor, SecureQueue, StopWatchQueue used in low-level data acquisition or networking modules.
• NetworkUtils, PNGImageUtil, TestUtils used in test automation, diagnostics, or reporting modules.
• SerializableDictionary used for XML persistence of dictionaries.

5. Gotchas

• ByteConvertor integer conversions: Despite the class summary claiming "network order", float and double use BitConverter (host-endian), which may cause inconsistencies if expecting consistent endianness across all types.
• StopWatchQueue.DumpData(): Writes CSV with header "All values in milli seconds" — but values are computed as ticks / Frequency * 1000, which is correct for milliseconds. Ensure Stopwatch.Frequency is consistent across platforms.
• SecureQueue.Dequeue(): Returns a flattened array of all queued arrays, not the first queued array. This is likely intentional for streaming but may be surprising.
• MouseUtilities.GetMousePosition(): Uses a non-standard scaling correction (factor = 2D - M22) and conditional Y-offset adjustment. This may be fragile under DPI scaling changes or high-DPI scenarios.
• TestUtils.MinUnixTime():
  • Uses basemodules.First() as initial minUnixTime, then compares only if module.TriggerTimestampSec <= minUnixTime.Item1 && module.TriggerTimestampNanoSec < minUnixTime.Item2. This logic may skip valid candidates if seconds are equal but nanoseconds are greater.
  • The standard deviation cap (TEN_MILLIS_IN_SEC) is applied after computing deviation, but the comparison uses >, not >=.
  • No validation that basemodules is non-null before calling .Count() (though .Count() on null throws).
• TestUtils.ParseROISuffix():
  • Uses test.Split(":".ToCharArray(), ...) — string split with char array is inefficient; Split(':') would be simpler.
  • Relies on DTS.Common.Constants.EventNumber — if undefined or changed, behavior breaks silently.
• NetworkUtils.GetAvailableHosts(): Skips 169.254.x.x addresses but does not skip other link-local ranges (e.g., IPv6). Also filters Npcap interfaces by description — may miss other packet-capture tools.
• BusyWaitAnimation:
  • Uses Graphics.FromHdc — requires valid hDC to be set before drawing; otherwise, FromHdc may throw.
  • Invalidate() uses _backgroundImage, but _backgroundImage is only initialized in SetDrawArea() — calling Invalidate() before SetDrawArea() will cause NullReferenceException.
  • Timer interval is set via TimeSpan.FromMilliseconds(value) where value is Ticks — this is incorrect; Ticks is not milliseconds. Should use TimeSpan.FromMilliseconds(value) with value in milliseconds, or TimeSpan.FromTicks(value) if value is ticks. The property RotationSpeed returns _timer.Interval.Ticks, but setting it expects milliseconds — this mismatch is a bug.
• SerializableDictionary:
  • Uses XmlSerializer for keys and values — requires TKey and TValue to be serializable by XmlSerializer.
  • Does not handle duplicate keys during deserialization (would throw ArgumentException from Dictionary.Add).
  • ReadXml assumes XML structure <items><item>...</item>...</items> — any deviation (e.g., whitespace, attributes) may cause parsing errors.
• EnumUtil.GetValuesList<T>(): Uses ItemCollection from Xceed toolkit — may not be available in all environments or may require specific toolkit version.