DP44/enriched-qwen3-coder-next/Common/DTS.Common/Interface/Communication.md

---
source_files:
  - Common/DTS.Common/Interface/Communication/ICommunicationReport.cs
  - Common/DTS.Common/Interface/Communication/IDASConnectedDevice.cs
  - Common/DTS.Common/Interface/Communication/ICommunication_DASInfo.cs
generated_at: "2026-04-16T03:03:06.051623+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "d690cf8a777399d3"
---

# Communication

### **Purpose**  
This module defines core interfaces for representing communication state and device metadata within the DTS (Data Acquisition System) framework. Specifically, it standardizes how communication results, data payloads, and device information (including device topology, identity, and capabilities) are exposed across the system—particularly for auto-discovery and status monitoring of DAS-connected hardware (e.g., S6 devices on an S6DB). These interfaces serve as contracts for implementations handling device communication, status reporting, and metadata management.

---

### **Public Interface**  

#### `ICommunicationReport`  
Represents the outcome and associated data of a communication operation.  
- **`object UserState { get; set; }`**  
  Arbitrary user-defined state object, typically used to correlate asynchronous operations or pass context through callbacks.  
- **`CommunicationConstantsAndEnums.CommunicationResult Result { get; set; }`**  
  The result status of the communication operation (e.g., success, timeout, error). *Note: `CommunicationResult` is defined in an external enum namespace.*  
- **`byte[] Data { get; set; }`**  
  Raw byte payload returned or sent during the communication. May be `null` if no data is applicable (e.g., for command-only operations or failures).  

#### `IDASConnectedDevice`  
Describes a single device physically connected to a DAS (e.g., S6 on S6DB), including its location, identity, and network properties.  
- **`HardwareTypes DeviceType { get; }`**  
  The enumerated type of the device (e.g., `S6`, `S6DB`). *Defined in `DTS.Common.Enums.Hardware`.*  
- **`int Port { get; }`**  
  Zero-based port index on the DAS to which the device is connected.  
- **`int SpotOnPort { get; }`**  
  Zero-based position of the device along the chain or daisy chain on the given port.  
- **`PhysicalAddress PhysicalAddress { get; }`**  
  MAC address of the device (from `System.Net.NetworkInformation`).  
- **`string IPAddress { get; }`**  
  IPv4/IPv6 address string assigned to the device.  
- **`string SerialNumber { get; }`**  
  Unique hardware serial number.  
- **`string Location { get; }`**  
  Human-readable location identifier (e.g., "Lab A, Rack 2").  
- **`string Version { get; }`**  
  Firmware or software version string.  

#### `ICommunication_DASInfo`  
Encapsulates metadata about a DAS unit and its connected devices.  
- **`IDASConnectedDevice[] ConnectedDevices { get; }`**  
  Immutable array of devices currently connected to this DAS. *Currently only populated for SLICE6DB.*  
- **`void SetConnectedDevices(IDASConnectedDevice[] devices)`**  
  Mutator to populate `ConnectedDevices`. Intended for internal use during device enumeration/discovery.  
- **`string[] SerialNumbers { get; set; }`**  
  Parallel array of serial numbers for connected devices (index-aligned with `ConnectedDevices`).  
- **`string[] FirmwareVersions { get; set; }`**  
  Parallel array of firmware versions for connected devices (index-aligned with `ConnectedDevices`).  
- **`string StackSerialNumber(int devid)`**  
  Returns the serial number of the device at the specified `devid` index (0-based). *Assumes `devid` is valid for the current `ConnectedDevices` array.*  
- **`DateTime? FirstUseDate { get; set; }`**  
  Date of first operational use. `null` indicates the device has not been used since last calibration (or calibration is unsupported). Valid only when `IsFirstUseDateSupported` is `true`.  
- **`bool IsFirstUseDateSupported { get; set; }`**  
  Indicates whether the hardware supports tracking first-use date (requires firmware/user-attribute storage and calibration support per issue #15524).  
- **`bool IsStreamingSupported { get; set; }`**  
  Indicates whether the hardware supports streaming data (e.g., via system attribute `DISABLE_STREAMING_FEATURE` per issue #30429).  

---

### **Invariants**  
- **`ConnectedDevices` alignment**: `SerialNumbers[i]` and `FirmwareVersions[i]` must correspond to `ConnectedDevices[i]` for all valid indices `i`.  
- **`StackSerialNumber` contract**: Must return the serial number at index `devid` in `ConnectedDevices`; behavior is undefined if `devid` is out of bounds.  
- **`FirstUseDate` validity**: `FirstUseDate.HasValue` is only meaningful when `IsFirstUseDateSupported == true`; otherwise, it should be ignored.  
- **`Result` semantics**: The `Result` field in `ICommunicationReport` must accurately reflect the outcome of the operation; `Data` may be non-null only for successful or partial-success results (implementation-dependent).  

---

### **Dependencies**  
- **Depends on**:  
  - `DTS.Common.Enums.Communication.CommunicationResult` (external enum)  
  - `DTS.Common.Enums.Hardware.HardwareTypes` (external enum)  
  - `System.Net.NetworkInformation.PhysicalAddress` (BCL type)  
- **Depended on by**:  
  - Components implementing auto-discovery and device monitoring (e.g., DAS status monitors, network scanners).  
  - Code handling device metadata aggregation (e.g., configuration managers, diagnostic tools).  
  - Likely consumed by higher-level communication layers (e.g., `ICommunicationService`, `DASController`).  

---

### **Gotchas**  
- **`ConnectedDevices` is currently only populated for SLICE6DB**: Other DAS types may return an empty or uninitialized array. Do not assume it is universally populated.  
- **`SetConnectedDevices` is a setter, not an adder**: It replaces the entire array; incremental updates require manual reconstruction.  
- **`StackSerialNumber` uses `devid` as an array index**: No bounds checking is specified; callers must ensure `0 ≤ devid < ConnectedDevices.Length`.  
- **`FirstUseDate` semantics are conditional**: A `null` value does *not* necessarily mean "never used"—it may also indicate lack of hardware support.  
- **`IsStreamingSupported` is hardware- and firmware-dependent**: Support may be toggled via system attributes (e.g., `DISABLE_STREAMING_FEATURE`), so runtime checks may be necessary beyond this flag.  
- **No validation rules specified**: Interfaces do not enforce non-null constraints (e.g., `IPAddress` or `SerialNumber` could be `null` or empty strings). Consumers must handle missing data defensively.  
- **No thread-safety guarantees**: Interfaces are passive data contracts; thread-safety must be handled by implementations.  

*None of the interfaces define event handlers, async methods, or lifecycle management—these are handled elsewhere.*