DP44/enriched-partialglm/Common/DTS.Common.ICommunication.md

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
Common/DTS.Common.ICommunication/IDASConnectedDevice.cs Common/DTS.Common.ICommunication/ICommunication.cs Common/DTS.Common.ICommunication/Communication.cs	2026-04-16T11:28:10.843855+00:00	zai-org/GLM-5-FP8	1	b573bb7d2f5d27d0

Documentation: DTS.Common.ICommunication

1. Purpose

This module provides the core communication infrastructure for interacting with DAS (Data Acquisition System) hardware. It defines the contract for DAS-connected devices via IDASConnectedDevice, encapsulates device metadata through Communication_DASInfo, and implements an asynchronous, callback-driven communication layer via the abstract Communication<T> class. The module handles connection lifecycle management, command execution with timeout handling, cancellation support, and receive buffering for networked hardware devices.

---

2. Public Interface

IDASConnectedDevice (Interface)

Namespace: DTS.DASLib.Communication

Describes a device connected to a DAS (e.g., an S6 connected to an S6DB).

Property	Type	Description
DeviceType	HardwareTypes	The device type of the connected device.
Port	int	The port on the DAS which the device is on (0-based).
SpotOnPort	int	The spot on the chain or port the device is on (0-based).
PhysicalAddress	PhysicalAddress	MAC Address or physical address.
IPAddress	string	The IP address of the device.
SerialNumber	string	The serial number of the device.
Location	string	The location of the device.
Version	string	The version of the device.

---

CanceledException (Class)

Namespace: DTS.Common.ICommunication

Marker exception class extending ApplicationException. Used to signal operation cancellation.

---

Communication_DASInfo (Class)

Namespace: DTS.Common.ICommunication

Implements ICommunication_DASInfo. Holds metadata about a DAS device.

Properties:

• FirstUseDate (DateTime?) — Date of first use; null indicates hardware has not been used since calibration. Only valid when IsFirstUseDateSupported is true.
• IsFirstUseDateSupported (bool) — Indicates hardware supports first use dates.
• IsStreamingSupported (bool) — Indicates whether streaming is supported.
• ConnectedDevices (IDASConnectedDevice[]) — Devices connected to the DAS (currently only used by SLICE6DB).

Methods:

• void SetConnectedDevices(IDASConnectedDevice[] devices) — Sets the ConnectedDevices array.
• string StackSerialNumber(int devid) — Returns a stacked serial number string. Returns "N/A" if SerialNumbers is null/empty; returns SerialNumbers[0]::SerialNumbers[devid] if devid is non-zero and valid; otherwise returns SerialNumbers[0].

Constructors:

• Communication_DASInfo() — Default constructor.
• Communication_DASInfo(string[] serials, string[] fwnums) — Constructs with cloned serial and firmware version arrays.

---

Communication<T> (Abstract Class)

Namespace: DTS.Common.ICommunication

Generic abstract base class for DAS communication. Type parameter T must implement IConnection and have a parameterless constructor.

Properties:

• ErrorInSetup (bool) — Indicates an error occurred during setup.
• ConnectString (string) — Returns sock.ConnectString.
• Connected (bool) — Returns sock.Connected.
• DASInfo (ICommunication_DASInfo) — DAS information object.
• Transport (IConnection) — Gets the underlying connection; setter throws NotSupportedException.
• ReceiveBufferSize (int) — Receive buffer size; default is 65536 (2^16).
• SerialNumber (string) — Device serial number.
• FirmwareVersion (string) — Firmware version; setter triggers FirmwareVersionUpdated().
• ProtocolVersion (byte) — Protocol version.
• MinimumProtocols (Dictionary<DFConstantsAndEnums.ProtocolLimitedCommands, byte>) — Minimum protocol versions for commands.
• FlushTimeoutMilliSec (int) — Flush timeout; default is 5ms.
• ExecuteIsBusy (bool) — Thread-safe flag indicating execution lock state.
• CancelEvent (ManualResetEvent) — Event signaling cancellation.

Methods:

• int CompareTo(ICommunication dev) — Compares connect strings (case-insensitive ordinal).
• int CompareTo(string conStr) — Compares connect string to given string.
• abstract void InitMinProto() — Must be implemented to initialize MinimumProtocols.
• bool IsCommandSupported(ProtocolLimitedCommands command) — Returns true if ProtocolVersion >= GetMinProto(command).
• byte GetMinProto(ProtocolLimitedCommands command) — Returns minimum protocol version for command; returns 0xFF if not found; throws if MinimumProtocols is null.
• void Flush(int timeoutMs) — Flushes SockDataBuffer until empty or timeout.
• byte[] SyncExecute(byte[] byteData, int cbTimeout) — Throws NotSupportedException.
• void Connect(string connectString, CommunicationCallback callback, object callbackObject, int callbackTimeout, string hostIPAddress) — Initiates asynchronous connection.
• void Disconnect(bool reuseSocket, CommunicationCallback callback, object callbackObject, int callbackTimeout) — Initiates asynchronous disconnect.
• void ForceCancel() — Sets cancel state with 250ms sleep on clear.
• void Cancel() — Sets cancel state with 500ms sleep on clear.
• bool IsCanceled() — Returns current cancel state.
• void ClearCancel() — Clears cancel state after sleeping.
• void PseudoExecute(byte[] byteData, CommunicationCallback cb, object cbObject, int cbTimeout) — For commands that only receive data (no send). Throws CanceledException if canceled, NotConnectedException if not connected.
• void Execute(byte[] byteData, CommunicationCallback cb, object cbObject, int cbTimeout) — Sends data and processes response. Throws CanceledException if canceled, NotConnectedException if not connected.
• void SetupReader() — Initializes asynchronous receive loop.
• void Close(int timeout) — Empty implementation.

Events:

• OnDisconnected (EventHandler) — Raised when the underlying connection disconnects.

Protected Methods:

• void Lock() — Empty implementation.
• void Release() — Empty implementation.
• virtual void FirmwareVersionUpdated() — Called when FirmwareVersion is set.

---

Communication.ActionData (Nested Abstract Class)

Base class for async operation tracking with timeout support.

Constructor: ActionData(CommunicationCallback cb, object obj, int to)

Methods:

• void StartTimer() — Starts timeout timer.
• void KillTimer() — Stops and disposes timer.
• bool ReportCanceled() — Invokes callback with CommunicationResult.Canceled.
• abstract bool ReportFailure() — Must implement failure reporting.
• abstract bool ReportSuccess() — Must implement success reporting.
• abstract CommunicationResult GetTimeoutResult() — Must return result for timeout.

Properties:

• TimerExpired (bool) — Returns whether timer has fired.

---

Communication.ExecuteActionData (Nested Class)

Extends ActionData for execute operations.

Additional Methods:

• bool ReportReadSuccess(byte[] data) — Reports successful read with data.
• bool ReportReadTimeout() — Reports read timeout.
• bool ReportReadDisconnected() — Reports disconnection during read.

---

CommunicationReport (Class)

Namespace: DTS.Common.ICommunication

Implements ICommunicationReport.

Properties:

• UserState (object) — User-provided state object.
• Result (CommunicationResult) — Result of the operation.
• Data (byte[]) — Received data (for read operations).

Constructor: CommunicationReport(object state, CommunicationResult res)

---

Communication.PseudoAsyncResult (Nested Class)

Implements IAsyncResult for PseudoExecute. IsCompleted and CompletedSynchronously return true. AsyncWaitHandle throws NotImplementedException.

---

3. Invariants

1. Connection State Checks: Connect() throws if sock is null or already connected. Disconnect() throws if sock is null.
2. Execute Pre-conditions: Both Execute() and PseudoExecute() throw CanceledException if IsCanceled() returns true, and NotConnectedException if Connected is false.
3. ExecuteIsBusy Thread Safety: The ExecuteIsBusy property uses locking (_executeBusyMtLock) and asserts on re-entry or extra unlock attempts.
4. Transport Immutability: The Transport property setter always throws NotSupportedException.
5. MinimumProtocols Requirement: GetMinProto() throws NotSupportedException if MinimumProtocols is null.
6. SyncExecute Unavailable: SyncExecute() always throws NotSupportedException.
7. Clone Behavior: Communication_DASInfo constructor clones input arrays for SerialNumbers and FirmwareVersions.
8. Port/Spot Indexing: Port and SpotOnPort in IDASConnectedDevice are explicitly 0-based.

---

4. Dependencies

This module depends on:

• DTS.Common.Enums.Hardware — HardwareTypes enum
• DTS.Common.Enums.Communication — CommunicationResult, CommunicationConstantsAndEnums
• DTS.Common.Enums.DASFactory — DFConstantsAndEnums
• DTS.Common.Interface.Communication — ICommunication_DASInfo, CommunicationCallback delegate
• DTS.Common.Interface.Connection — IConnection
• DTS.Common.Classes.Connection — (referenced but implementation not shown)
• DTS.Common.Utilities.Logging — APILogger
• DTS.Common.Utilities — SecureQueue<T>
• DTS.Common.Utils — WaitWithCondition
• System.Net.NetworkInformation — PhysicalAddress
• System.Net.Sockets — SocketException
• System.Threading, System.Threading.Tasks — Async primitives

What depends on this module:

• Cannot be definitively determined from source alone, but Communication_DASInfo.ConnectedDevices references IDASConnectedDevice, suggesting SLICE6DB implementations depend on this interface.

---

5. Gotchas

1. Empty Lock/Release Methods: Lock() and Release() are defined but have empty implementations. Their intended purpose is unclear from source alone.

2. Close() is a No-Op: The Close(int timeout) method has an empty body. Callers should not rely on it for cleanup.

3. Cancel Sleep Behavior: ClearCancel() sleeps for either 250ms (after ForceCancel()) or 500ms (after Cancel()) before clearing the cancel state. This blocking delay may be unexpected in time-sensitive contexts.

4. Thread ID Check in Receive Callbacks: Both ProcessReceivedData and SRRecvCallback check if Thread.CurrentThread.ManagedThreadId changes during WaitWithCondition.Wait(), logging and returning early if it does. This suggests a historical threading issue.

5. Transport Setter Always Throws: Attempting to set Transport throws NotSupportedException with message "Communication::Transport Can't replace socket".

6. PseudoAsyncResult.AsyncWaitHandle Throws: Accessing AsyncWaitHandle on PseudoAsyncResult throws NotImplementedException.

7. ConnectedDevices Default is Empty Array: Communication_DASInfo.ConnectedDevices initializes to an empty array, not null. Code checking for null will not behave as expected.

8. StackSerialNumber Index Logic: StackSerialNumber(int devid) returns the stacked format only when devid != 0 && devid < SerialNumbers.Length. A devid of 0 returns just SerialNumbers[0], not a stacked string.