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

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
Common/DTS.Common/Utils/XMLUtils.cs Common/DTS.Common/Utils/EnumUtils.cs Common/DTS.Common/Utils/ValueStopWatch.cs Common/DTS.Common/Utils/ImageButton.cs Common/DTS.Common/Utils/PNGImageUtil.cs Common/DTS.Common/Utils/MouseUtils.cs Common/DTS.Common/Utils/StopWatch.cs Common/DTS.Common/Utils/SerializableDictionary.cs Common/DTS.Common/Utils/TestUtils.cs Common/DTS.Common/Utils/IPUtils.cs Common/DTS.Common/Utils/SecureQueue.cs Common/DTS.Common/Utils/ByteConverter.cs Common/DTS.Common/Utils/NetworkUtils.cs Common/DTS.Common/Utils/BusyWaitAnimation.cs	2026-04-16T02:53:58.796981+00:00	Qwen/Qwen3-Coder-Next-FP8	1	95511667ddecb834

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 system. It serves as a foundational layer for low-level functionality including time measurement (ValueStopwatch, StopWatchQueue), data serialization/deserialization (SerializableDictionary, ByteConvertor), UI components (ImageButton, BusyWaitAnimation), network operations (NetworkUtils, IPUtils), and test/data processing (TestUtils, EnumUtil). The module exists to centralize reusable logic, reduce code duplication, and provide consistent behavior for cross-cutting concerns such as timing, byte-order conversion, IP address handling, and UI feedback mechanisms.

2. Public Interface

EnumUtil (static class)

• public static IEnumerable<T> GetValues<T>()
  Returns all enum values of type T using Enum.GetValues.
• public static ItemCollection GetValuesList<T>()
  Returns an ItemCollection (from Xceed.Wpf.Toolkit) containing enum values and their names, suitable for binding to property grids.

ValueStopwatch (readonly struct)

• public static ValueStopwatch StartNew()
  Creates and starts a new ValueStopwatch instance.
• public TimeSpan GetElapsedTime()
  Returns the elapsed time since the stopwatch was started, computed using Stopwatch.GetTimestamp() and Stopwatch.Frequency.

ImageButton (class)

• Inherits from System.Windows.Controls.Button.
• public ImageSource Source { get; set; }
  Gets/sets the image displayed in the button.
• public string ImageText { get; set; }
  Gets/sets the text displayed below the image in the button.
• Internally uses a StackPanel with vertical orientation to arrange an Image and TextBlock.

PNGImageUtil (static class)

• public static void SaveImage(FrameworkElement view, string fileName)
  Renders the given FrameworkElement as a PNG image to the specified file path using RenderTargetBitmap and PngBitmapEncoder.

MouseUtilities (class)

• public static Point GetMousePosition(Visual relativeTo)
  Returns the current mouse cursor position relative to a given WPF Visual. Uses Win32 API (GetCursorPos, ScreenToClient) and WPF transform logic to compute coordinates.

StopWatchQueue (class)

• public StopWatchQueue(string name)
  Constructor; initializes a queue for storing elapsed tick values (max ~5000 entries).
• public void Start()
  Starts the internal Stopwatch.
• public void Stop()
  Stops the Stopwatch, enqueues the elapsed ticks, and resets the Stopwatch.
• public void DumpData()
  Writes timing statistics (count, min, max, avg, stddev) and all recorded values (in milliseconds) to a CSV file named <name><FileTime>.csv.
• Finalizer calls DumpData() on disposal.

SerializableDictionary<TKey, TValue> (class)

• Inherits Dictionary<TKey, TValue> and implements IXmlSerializable.
• public void ReadXml(XmlReader reader)
  Deserializes XML into the dictionary; expects <items><item><key>...</key><value>...</value></item>...</items> structure.
• public void WriteXml(XmlWriter writer)
  Serializes the dictionary to XML in the same structure.
• Uses XmlSerializer for key and value types.

TestUtils (static class)

• public static Tuple<double, double> MinUnixTime(IEnumerable<TestModuleTimeStamp> basemodules)
  Returns the earliest valid timestamp (as (sec, nanosec)) from a collection of TestModuleTimeStamp objects, filtering out outliers beyond utcAverage - utcStandardDeviation and clamping stddev to ≤10ms. Returns null if input is null/empty.
• public static string ParseROISuffix(string test)
  Extracts ROI suffix from a colon-separated test string. Tries multiple heuristics based on DTS.Common.Constants.EventNumber.

IPUtils (namespace)

• public class IPRange
  Holds a start and end IPAddressIntForm representing an IP range.
• public class IPAddressIntForm
  Represents an IPv4 address as four byte components (ByteOne–ByteFour).
  • public static bool TryParse(string input, out IPAddressIntForm output)
    Parses a dotted-decimal IP string into an IPAddressIntForm.
  • public static string[] GetAllIPs(IPAddressIntForm a, IPAddressIntForm b)
    Returns all IPs between a and b (inclusive), regardless of input order.
  • internal class IPComparer : IComparer<IPAddressIntForm>
    Lexicographic comparison of IP addresses by byte components.

SecureQueue<T> (class)

• Generic thread-safe queue with configurable null-handling policy (NullPolicy enum: DenyNull, SkipNull, AllowNull).
• public void Enqueue(T[] newData)
  Adds a byte array to the queue; enforces null policy and logs if enabled.
• public bool WaitForData(int timeoutMillisec)
  Blocks for up to timeoutMillisec ms waiting for data.
• public T[] Dequeue(bool resetEvent)
  Dequeues and concatenates all queued arrays into a single array; resets internal event.
• public void Flush()
  Clears the queue and resets the event.
• public bool IsEmpty()
  Returns true if queue is empty.
• public WaitHandle QueueWaitHandle => ByteQueueEvent
  Exposes the internal ManualResetEvent for external wait operations.

ByteConvertor (class)

• Static class for converting between integral types and byte arrays in network byte order (big-endian).
• public static void Convert(byte[] input, int offset, out T value)
  Reads a value of type T (e.g., ushort, int, long, float, double, string) from input at offset, interpreting bytes in big-endian order.
• public static byte[] ToByteArray(T value)
  Converts value to a big-endian byte array (e.g., ToByteArray(ushort) returns 2 bytes, ToByteArray(int) returns 4 bytes, ToByteArray(string) appends null terminator).

NetworkUtils (static class)

• public static bool IsNetworkInterfaceUp(IPAddress ip)
  Checks if a network interface with the given IP is active, supports multicast, and is not loopback or internal-only (unless AllowInternalNICIPs is true).
• public static List<HostInfo> GetAvailableHosts(bool supportMulticastOnly = false)
  Returns a list of HostInfo objects for all available IPv4 network interfaces (filters out loopback, virtual, low-speed, and Npcap interfaces).
• public static bool TryParseConnectionString(string connectionString, out string ipAddress)
  Attempts to extract an IP address from a DAS connection string (supports URI or colon-separated formats). Returns false for non-IP (e.g., USB) strings.
• public static bool AllowInternalNICIPs { get; set; }
  Controls whether 169.254.x.x (link-local) addresses are included in interface filtering.

BusyWaitAnimation (class)

• WPF/WinForms-compatible busy indicator (spinning circle).
• public bool Active { get; set; }
  Starts/stops the animation timer.
• public StylePresets StylePreset { get; set; }
  Sets appearance to presets: MacOsx, Firefox, Ie7, or Custom.
• public Color Color { get; set; }
  Base color for the spinning spokes.
• public int OuterCircleRadius, InnerCircleRadius, NumberSpoke, SpokeThickness, RotationSpeed
  Properties to customize appearance and behavior.
• Requires SetDrawArea(Rectangle) and hDC setter for rendering; uses GDI+ for drawing.

3. Invariants

• ByteConvertor: All multi-byte conversions use big-endian (network) order. Little-endian host systems must convert appropriately.
• ValueStopwatch: Elapsed time is computed using Stopwatch.Frequency and TimeSpan.TicksPerSecond; precision is limited to Stopwatch resolution.
• StopWatchQueue: Stores up to ~5000 tick values; older values are overwritten only when the queue is full (not explicitly implemented—queue grows until DumpData() is called).
• SerializableDictionary: Keys and values must be serializable via XmlSerializer; no validation of key uniqueness or type compatibility is performed during deserialization.
• SecureQueue<T>:
  • Dequeue() always concatenates all queued arrays into a single array (not one per enqueue).
  • Dequeue() and Flush() reset the internal ManualResetEvent, breaking existing waiters.
  • Null/empty arrays are handled per NullPolicy; Clone() is used for enqueue to prevent external mutation.
• TestUtils.MinUnixTime:
  • Uses Common.Constants.NANOS_PER_SECOND and Common.Constants.TEN_MILLIS_IN_SEC (not defined in this module).
  • Filters out timestamps where moduleTime ≤ utcAverage - utcStandardDeviation.
  • Returns the first module satisfying the filter, not necessarily the absolute earliest.
• NetworkUtils.IsNetworkInterfaceUp: Skips interfaces with 169.254.x.x addresses unless AllowInternalNICIPs is true.
• IPUtils.IPAddressIntForm.GetAllIPs: Iterates over all bytes in lexicographic order; may produce invalid IPs (e.g., 256.x.x.x) if input bytes exceed 0–255.

4. Dependencies

Internal Dependencies (within DTS.Common)

• DTS.Common.Interface (for TestModuleTimeStamp and TestUtils)
• DTS.Common.Utilities.Logging (for APILogger)
• DTS.Common.Constants (referenced by TestUtils and NetworkUtils)
• DTS.Common.Utilities (referenced by SecureQueue)

External Dependencies

• .NET Framework: System, System.Collections.Generic, System.Diagnostics, System.IO, System.Linq, System.Net, System.Net.NetworkInformation, System.Net.Sockets, System.Runtime.InteropServices, System.Threading, System.Windows, System.Windows.Media, System.Windows.Media.Imaging, System.Windows.Threading, System.Xml, System.Xml.Serialization
• WPF Toolkit: Xceed.Wpf.Toolkit.PropertyGrid.Attributes (for ItemCollection)
• Win32 API: user32.dll (GetCursorPos, GetPhysicalCursorPos, ScreenToClient)
• Windows Forms: System.Windows.Forms, System.Drawing, System.Drawing.Drawing2D (for BusyWaitAnimation)

Dependencies on This Module

• DTS.Common.Interface (via TestUtils)
• Networking modules (via NetworkUtils, IPUtils)
• UI components (via ImageButton, BusyWaitAnimation)
• Data processing pipelines (via ByteConvertor, SerializableDictionary, SecureQueue)

5. Gotchas

• ByteConvertor: The Convert methods for float/double use BitConverter (host-endian), not network byte order. Only integer/string conversions are big-endian.
• StopWatchQueue:
  • Finalizer calls DumpData() but does not prevent multiple calls (e.g., explicit DumpData() + finalizer).
  • DumpData() dequeues all values, leaving the queue empty.
  • No explicit disposal pattern; ~StopWatchQueue() is the only cleanup.
• SecureQueue<T>:
  • Dequeue() concatenates all queued arrays into one—this may be unexpected if callers expect per-enqueue chunks.
  • Dequeue() and Flush() reset the ManualResetEvent, invalidating any pending WaitOne() calls.
  • ByteQueueEvent is recreated on each Dequeue()/Flush(), breaking external references to the WaitHandle.
• TestUtils.MinUnixTime:
  • Uses Common.Constants.NANOS_PER_SECOND and TEN_MILLIS_IN_SEC—these must be defined elsewhere.
  • The filtering logic (moduleTime > utcAverage - utcStandardDeviation) may exclude valid early timestamps if they are statistical outliers.
• NetworkUtils.GetAvailableHosts:
  • Filters out interfaces with 169.254.x.x addresses by default (configurable via AllowInternalNICIPs).
  • Skips interfaces with "Npcap" in description (Wireshark).
• IPUtils.IPAddressIntForm.GetAllIPs:
  • Iterates over all byte combinations (e.g., 256.0.0.0 if ByteOne=256), which may produce invalid IPs.
  • No validation that start ≤ end in IP order (handled via IPComparer).
• BusyWaitAnimation:
  • Requires manual setup: SetDrawArea() and hDC setter must be called before rendering.
  • Uses GDI+ (Graphics.FromHdc), which is not thread-safe and requires a valid HDC.
• ImageButton:
  • Uses StackPanel with fixed Margin=10; not configurable.
  • No support for horizontal layout or custom content beyond image + text.
• PNGImageUtil.SaveImage:
  • Uses view.ActualWidth/ActualHeight, which may be zero if the element is not rendered.
  • Does not handle DPI scaling beyond hardcoded 96 DPI.
• EnumUtil.GetValuesList<T>:
  • Returns ItemCollection (WPF Toolkit type), which may not be available in non-WPF contexts.