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

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
Common/DTS.CommonCore/Interface/Communication/ICommunicationReport.cs Common/DTS.CommonCore/Interface/Communication/IDASConnectedDevice.cs Common/DTS.CommonCore/Interface/Communication/ICommunication_DASInfo.cs	2026-04-16T02:23:54.710439+00:00	Qwen/Qwen3-Coder-Next-FP8	1	c40d100ec97fea56

Communication

Purpose

This module defines core interfaces for representing communication results, connected devices in a DAS (Data Acquisition System) network, and DAS-specific metadata. It serves as the foundational abstraction layer for device discovery, status monitoring, and communication state reporting—specifically supporting the auto-discovery and monitoring of DAS-connected hardware (e.g., SLICE6 devices connected to an SLICE6DB base station). These interfaces decouple communication logic from implementation details, enabling consistent handling of device properties, communication outcomes, and DAS-level state across the system.

---

Public Interface

ICommunicationReport

• object UserState { get; set; }
  A user-defined object for associating custom state with a communication operation (e.g., tracking request context or correlation ID).
• CommunicationConstantsAndEnums.CommunicationResult Result { get; set; }
  The outcome of a communication operation (e.g., success, timeout, error). Note: CommunicationResult is defined in an external enum namespace (DTS.Common.Enums.Communication), not included here.
• byte[] Data { get; set; }
  Raw payload data received or transmitted during the communication. May be null or empty depending on the operation type and result.

IDASConnectedDevice

• HardwareTypes DeviceType { get; }
  The hardware type of the connected device (e.g., sensor, actuator), per the HardwareTypes enum (defined externally in DTS.Common.Enums.Hardware).
• int Port { get; }
  Zero-based port index on the DAS to which the device is physically connected.
• int SpotOnPort { get; }
  Zero-based position of the device on its port’s daisy chain (e.g., 0 = first device on the port).
• PhysicalAddress PhysicalAddress { get; }
  The device’s MAC address (from System.Net.NetworkInformation).
• string IPAddress { get; }
  The IPv4/IPv6 address assigned to the device (as a string).
• string SerialNumber { get; }
  Unique hardware serial number of the device.
• string Location { get; }
  Human-readable location descriptor (e.g., "Lab A, Rack 2").
• string Version { get; }
  Firmware version string of the device.

ICommunication_DASInfo

• IDASConnectedDevice[] ConnectedDevices { get; }
  Immutable array of devices currently connected to this DAS (read-only). Currently only populated for SLICE6DB.
• void SetConnectedDevices(IDASConnectedDevice[] devices)
  Updates the ConnectedDevices array. Intended for internal use by DAS implementations during discovery.
• string[] SerialNumbers { get; set; }
  Parallel array of serial numbers for connected devices (order matches ConnectedDevices).
• string[] FirmwareVersions { get; set; }
  Parallel array of firmware versions for connected devices (order matches ConnectedDevices).
• string StackSerialNumber(int devid)
  Returns the serial number of the device at index devid in the ConnectedDevices array. Behavior for invalid devid is unspecified.
• DateTime? FirstUseDate { get; set; }
  Date of the device’s first operational use. null indicates the hardware has never been used since calibration. Only valid when IsFirstUseDateSupported is true.
• bool IsFirstUseDateSupported { get; set; }
  Indicates whether the DAS hardware supports tracking first-use date (requires firmware/user-attribute storage and calibration support per ticket 15524).
• bool IsStreamingSupported { get; set; }
  Indicates whether the DAS supports streaming data (e.g., via ticket 30429, controllable via the DISABLE_STREAMING_FEATURE system attribute).

---

Invariants

• ICommunicationReport:
  • Data may be null or non-empty only if Result indicates success or partial success (implementation-dependent).
  • UserState is not interpreted by the interface; its lifecycle is managed by the caller.
• IDASConnectedDevice:
  • Port and SpotOnPort are zero-based indices.
  • PhysicalAddress is guaranteed non-null (as PhysicalAddress is a struct in .NET, but the interface implies it is initialized).
  • SerialNumber, Location, and Version are non-null strings (no explicit nullability annotation, but context implies required fields).
• ICommunication_DASInfo:
  • ConnectedDevices, SerialNumbers, and FirmwareVersions must have identical lengths when populated.
  • FirstUseDate is only meaningful when IsFirstUseDateSupported is true; otherwise, it should be ignored.
  • StackSerialNumber(devid) assumes devid is a valid index into ConnectedDevices; out-of-bounds behavior is undefined.

---

Dependencies

• External Dependencies:
  • DTS.Common.Enums.Communication.CommunicationResult (for ICommunicationReport.Result)
  • DTS.Common.Enums.Hardware.HardwareTypes (for IDASConnectedDevice.DeviceType)
  • System.Net.NetworkInformation.PhysicalAddress (for IDASConnectedDevice.PhysicalAddress)
• Internal Dependencies:
  • ICommunication_DASInfo is used by DAS implementations (e.g., SLICE6DB) to expose device metadata.
  • IDASConnectedDevice is consumed by higher-level discovery/monitoring logic (e.g., auto-discovery services).
• Consumers:
  • Likely used by DAS-specific communication layers (e.g., DASCommunicationManager) and device monitoring services.
  • ICommunicationReport is probably returned by asynchronous communication operations (e.g., SendAsync, ReceiveAsync).

---

Gotchas

• StackSerialNumber(int devid): No validation or exception behavior is specified for invalid devid (e.g., negative or ≥ ConnectedDevices.Length). Implementations may throw ArgumentOutOfRangeException or return null—behavior is implementation-defined.
• ConnectedDevices mutability: While ConnectedDevices is read-only (get only), SetConnectedDevices() allows external mutation. Callers must ensure thread-safety if used concurrently.
• FirstUseDate semantics: A null value does not imply "never calibrated"—it means "never used since calibration." A calibrated but unused device may still have FirstUseDate == null.
• IsStreamingSupported: Support is hardware/firmware-dependent and may be toggled via system attributes (e.g., DISABLE_STREAMING_FEATURE). The interface does not enforce consistency with actual runtime streaming capability.
• No error details: ICommunicationReport lacks error codes, messages, or stack traces—only a high-level Result enum. Debugging requires correlating with logs or UserState.
• Missing nullability annotations: Properties like Data, SerialNumber, and IPAddress lack ? for nullability despite potential null values in practice. This may cause confusion in nullable-enabled contexts.
• No versioning guarantees: Arrays (SerialNumbers, FirmwareVersions) are parallel to ConnectedDevices but have no explicit synchronization mechanism—out-of-sync arrays could occur if SetConnectedDevices is called without updating these arrays.