--- source_files: - 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 generated_at: "2026-04-16T12:01:02.629774+00:00" model: "zai-org/GLM-5-FP8" schema_version: 1 sha256: "0a10ccd507cef203" --- # DTS.CommonCore.Utils Documentation ## 1. Purpose This module provides a collection of utility classes and helper methods for the DTS system, including thread-safe data structures (`SecureQueue`), byte manipulation with network byte order conversion (`ByteConvertor`), WPF UI components (`ImageButton`, `BusyWaitAnimation`), network interface utilities (`NetworkUtils`), XML serialization helpers (`SerializableDictionary`), performance profiling (`StopWatchQueue`), and various other utility functions for enums, timestamps, mouse positioning, and image rendering. --- ## 2. Public Interface ### `EnumUtil` (static class) - `IEnumerable GetValues()` — Returns all values of enum type `T` as an enumerable. - `ItemCollection GetValuesList()` — Returns an `ItemCollection` populated with enum values and their names, suitable for use with Xceed WPF Toolkit PropertyGrid. ### `ImageButton` (extends `Button`) - `ImageSource Source` — Gets or sets the image source displayed on the button. - `string ImageText` — Gets or sets the text displayed below the image. ### `PNGImageUtil` (static class) - `void SaveImage(FrameworkElement view, string fileName)` — Renders a `FrameworkElement` to a PNG file at the specified path. Uses 96 DPI and `Pbgra32` pixel format. ### `MouseUtilities` - `static Point GetMousePosition(Visual relativeTo)` — Returns the mouse cursor position relative to the specified `Visual`, using Win32 API calls (`GetCursorPos`, `ScreenToClient`). ### `StopWatchQueue` - `StopWatchQueue(string name)` — Constructor accepting a name used for output file naming. - `void Start()` — Starts the internal stopwatch. - `void Stop()` — Stops the stopwatch, records elapsed ticks to an internal queue, and resets the stopwatch. - `void DumpData()` — Writes all recorded timing data to a CSV file with statistics (max, min, average, standard deviation in milliseconds). ### `SerializableDictionary` (extends `Dictionary`, implements `IXmlSerializable`) - `XmlSchema GetSchema()` — Returns `null`. - `void ReadXml(XmlReader reader)` — Deserializes the dictionary from XML format with ``, ``, ``, and `` elements. - `void WriteXml(XmlWriter writer)` — Serializes the dictionary to XML format. ### `XmlDictionary` - `SerializableDictionary Dictionary` — A pre-configured serializable dictionary for string-to-object mappings. ### `TestModuleTimeStamp` - `int TriggerTimestampSec` — Seconds component of timestamp. - `int TriggerTimestampNanoSec` — Nanoseconds component of timestamp. ### `TestUtils` (static class) - `Tuple MinUnixTime(IEnumerable basemodules)` — Calculates the minimum Unix timestamp from a collection, using statistical filtering (average minus standard deviation, capped at 10ms). Returns `null` if input is null or empty. - `string ParseROISuffix(string test)` — Parses a test string to extract an ROI suffix based on event number markers. ### `SecureQueue` (implements `IDisposable`, constrained to `new()`) - `enum NullPolicy` — `DenyNull`, `SkipNull`, `AllowNull`. - `SecureQueue(NullPolicy policy, string name)` — Constructor. - `void ResetEvent()` — Resets the internal `ManualResetEvent`. - `void Enqueue(T[] newData)` — Thread-safe enqueue; behavior depends on `NullPolicy`. Clones data before storing. - `bool WaitForData(int timeoutMillisec)` — Blocks until data arrives or timeout; returns `true` if data available. - `WaitHandle QueueWaitHandle` — Exposes the internal wait handle. - `T[] Dequeue(bool resetEvent)` — Thread-safe dequeue; concatenates all queued arrays into a single array if multiple entries exist. - `void Flush()` — Clears the queue and resets the event. - `bool IsEmpty()` — Returns `true` if queue is empty. - `void Dispose()` — Implementation of `IDisposable` (currently empty). ### `ByteConvertor` (static class) - `void Convert(byte[] input, int offset, out byte/ushort/short/uint/int/ulong/long/float/double/string value)` — Converts bytes at offset to the specified type. Multi-byte integers are interpreted in **big-endian (network) byte order**. Strings are null-terminated. - `byte[] ToByteArray(byte/ushort/short/uint/int/ulong/float/double/string input)` — Converts the specified type to a byte array. Multi-byte integers are output in **big-endian (network) byte order**. Strings are null-terminated. ### `NetworkUtils` (static class) - `bool IsNetworkInterfaceUp(IPAddress ip)` — Returns `true` if the network interface for the given IP is up and operational. - `List GetAvailableHosts(bool supportMulticastOnly = false)` — Returns a list of available network hosts with IP, MAC, and address range information. Filters out VPN, virtual adapters, loopback, and Npcap interfaces. - `bool TryParseConnectionString(string connectionString, out string ipAddress)` — Attempts to extract an IP address from a connection string; returns `false` for USB connections. ### `BusyWaitAnimation` - `Color Color` — Gets or sets the spoke color. - `Color BgColor` — Gets or sets the background color. - `int OuterCircleRadius` — Gets or sets the outer circle radius. - `int InnerCircleRadius` — Gets or sets the inner circle radius. - `int NumberSpoke` — Gets or sets the number of spokes. - `bool Active` — Gets or sets whether the animation is running. - `int SpokeThickness` — Gets or sets the spoke thickness. - `long RotationSpeed` — Gets or sets the rotation speed (higher = slower). - `StylePresets StylePreset` — Gets or sets a preset style (`MacOsx`, `Firefox`, `Ie7`, `Custom`). - `Graphics GDIGraphics` — Gets the internal GDI+ graphics object. - `int hDC` — Gets or sets the device context handle. - `void SetDrawArea(Rectangle rect)` — Sets the drawing area and initializes internal bitmaps. - `void SetCircleAppearance(int numberSpoke, int spokeThickness, int innerCircleRadius, int outerCircleRadius)` — Configures the circle appearance. ### `XMLUtils` - Empty class — **No public members defined.** --- ## 3. Invariants - **ByteConvertor**: All multi-byte integer conversions use big-endian (network) byte order. The `Convert` methods assume the input byte array is sufficiently sized for the requested type at the given offset. - **SecureQueue**: The queue is thread-safe; all operations use locking on `ByteQueueLock`. When `NullPolicy.DenyNull` is set, enqueuing null or empty arrays throws `ArgumentException`. - **SerializableDictionary**: XML structure must follow `.........` format. - **StopWatchQueue**: `Stop()` records elapsed ticks since the last `Start()` call and resets the stopwatch; calling `Stop()` without `Start()` will record whatever the stopwatch state is (including zero if never started). - **PNGImageUtil.SaveImage**: Requires the `FrameworkElement` to have valid `ActualWidth` and `ActualHeight` (must be rendered/measured). Uses `FileMode.CreateNew` — will throw if file already exists. - **TestUtils.MinUnixTime**: Returns `null` if input collection is null or empty. Standard deviation is capped at `Common.Constants.TEN_MILLIS_IN_SEC`. - **BusyWaitAnimation**: Requires `SetDrawArea()` and `hDC` to be set before animation can render. --- ## 4. Dependencies ### External Dependencies (from imports) - **Xceed.Wpf.Toolkit.PropertyGrid.Attributes** — `EnumUtil.GetValuesList()` returns `ItemCollection`. - **System.Windows.Forms** — Used in `SecureQueue` (though not directly referenced in visible code, imported). - **System.Drawing** — Used in `BusyWaitAnimation` for GDI+ graphics. - **System.Windows.Threading** — `BusyWaitAnimation` uses `DispatcherTimer`. ### Internal Dependencies - `DTS.Common.Utilities.Logging.APILogger` — Used by `SecureQueue` for logging. - `DTS.Common.Interface` — Imported in `TestUtils` (usage unclear from source alone). - `DTS.Common.Constants` — Constants `NANOS_PER_SECOND`, `TEN_MILLIS_IN_SEC`, `EventNumber` referenced in `TestUtils`. - `Enums.DASFactory.DFConstantsAndEnums.ExtraCommunicationLogging` — Used in `SecureQueue.Enqueue`. ### Namespace Inconsistency - `SerializableDictionary` and `XmlDictionary` are in namespace `DTS.DASLib.Utility`, while all other utilities are in `DTS.Common.Utils`. --- ## 5. Gotchas 1. **ByteConvertor float/double conversions**: Unlike integer types, `Convert` methods for `float` and `double` use `BitConverter.ToSingle/ToDouble`, which respects system endianness — inconsistent with the big-endian behavior of integer conversions. 2. **PNGImageUtil.SaveImage file mode**: Uses `FileMode.CreateNew`, which will throw an exception if the file already exists. Caller must ensure the file does not exist or handle the exception. 3. **SecureQueue.Dequeue event handling**: The method creates a **new** `ManualResetEvent(false)` on every call, which may cause issues if multiple consumers are waiting on the original event handle. 4. **SecureQueue.Dispose**: The `Dispose()` method is empty and does not release the `ManualResetEvent` or other resources. 5. **MouseUtilities.GetMousePosition DPI handling**: The calculation `var factor = 2D - presentationSource.CompositionTarget.TransformToDevice.M22` is non-obvious and may produce incorrect results for certain DPI configurations. 6. **StopWatchQueue finalizer**: The destructor `~StopWatchQueue()` calls `DumpData()`, which writes a file to disk. This could cause unexpected file I/O during garbage collection. 7. **BusyWaitAnimation static field**: Contains `static int _xxx = 0;` that is incremented in the constructor but never used — appears to be debug/legacy code. 8. **XMLUtils**: The class is entirely empty — unclear if this is placeholder or deprecated code. 9. **SerializableDictionary.ReadXml**: Creates new `XmlSerializer` instances for each key and value type on every call, which could cause performance issues and memory leaks (XmlSerializer caching issues).