DP44/enriched-partialglm/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-16T12:01:02.629774+00:00	zai-org/GLM-5-FP8	1	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<T> GetValues<T>() — Returns all values of enum type T as an enumerable.
• ItemCollection GetValuesList<T>() — 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<TKey, TValue> (extends Dictionary<TKey, TValue>, implements IXmlSerializable)

• XmlSchema GetSchema() — Returns null.
• void ReadXml(XmlReader reader) — Deserializes the dictionary from XML format with <items>, <item>, <key>, and <value> elements.
• void WriteXml(XmlWriter writer) — Serializes the dictionary to XML format.

XmlDictionary

• SerializableDictionary<string, object> 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<double, double> MinUnixTime(IEnumerable<TestModuleTimeStamp> 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<T> (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<HostInfo> 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 <items><item><key>...</key><value>...</value></item>...</items> 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<T>() 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).