init

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

@@ -0,0 +1,207 @@
+---
+source_files:
+  - 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
+generated_at: "2026-04-16T02:53:58.796981+00:00"
+model: "Qwen/Qwen3-Coder-Next-FP8"
+schema_version: 1
+sha256: "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.