DP44/enriched-qwen3-coder-next/Common/DTS.Common.IConnection/EthernetConnection.md

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
Common/DTS.Common.IConnection/EthernetConnection/RESTConnection.cs Common/DTS.Common.IConnection/EthernetConnection/EthernetConnection.cs	2026-04-16T02:09:04.702798+00:00	Qwen/Qwen3-Coder-Next-FP8	1	21dfcca726b35e5d

Documentation: RESTConnection and EthernetConnection Classes

1. Purpose

This module provides two concrete implementations of the IConnection interface for network communication: RESTConnection, a stub implementation that simulates connection operations without actual network activity (intended for REST-based or mock scenarios), and EthernetConnection, a full-featured implementation using System.Net.Sockets.Socket for real-time Ethernet communication with hardware devices. RESTConnection exists to satisfy interface contracts in environments where actual socket communication is unnecessary or undesirable (e.g., testing, REST API interactions), while EthernetConnection handles real socket operations including connection establishment, data transfer, keep-alive configuration, and soft disconnect/reconnect workflows for embedded hardware.

2. Public Interface

RESTConnection (namespace DTS.DASLib.Connection)

• bool IConnection.IsSoftDisconnected => false
  Always returns false; does not support soft disconnect semantics.

• SocketFlags IConnection.Flags { get; set; }
  Gets/sets socket flags (unused; always SocketFlags.None).

• string IConnection.ConnectString => _ConnectString
  Returns the stored connection string (e.g., "host:port"), set via Create.

• bool IConnection.Connected => _bConnected
  Returns internal _bConnected state (set to true on BeginConnect, false on BeginDisconnect).

• event EventHandler OnDisconnected
  Declared but never raised (no invocation in source).

• void IConnection.Create(string connectString)
  Stores connectString in _ConnectString.

• void IConnection.Create(string connectString, string hostIPAddress)
  Stores connectString and hostIPAddress in respective fields.

• IAsyncResult IConnection.BeginConnect(AsyncCallback callback, object callbackObject)
  Sets _bConnected = true and returns a synchronously completed IAsyncResult via GetAlreadyCompleted.

• IAsyncResult IConnection.BeginDisconnect(bool reuseSocket, AsyncCallback callback, object state)
  Sets _bConnected = false and returns a synchronously completed IAsyncResult.

• IAsyncResult IConnection.BeginSend(...) / BeginReceive(...) / BeginAccept(...)
  All return synchronously completed IAsyncResult instances; no actual I/O.

• void IConnection.EndConnect(...) / EndDisconnect(...) / EndSend(...) / EndReceive(...) / EndAccept(...)
  No-op implementations. EndSend/EndReceive return 0. EndAccept returns this.

• void IConnection.Bind(int port)
  Stub; no-op.

• void IConnection.Listen(int backlog)
  Stub; no-op.

• void IConnection.KeepAliveErrorReceived()
  Stub; no-op.

• string IConnection.GetConnectionData()
  Returns "{_ConnectString} - {_hostIPAddress}".

• Task<int> IConnection.SendAsync(...)
  Wraps BeginSend/EndSend using Task.Factory.FromAsync; returns a completed task with result 0.

• void IConnection.SoftConnect() / SoftDisconnect()
  Stubs; no-op.

• void Dispose() / ~RESTConnection()
  Implements IDisposable; marks _disposed = true but performs no socket cleanup.

EthernetConnection (namespace DTS.Common)

• bool IsSoftDisconnected { get; private set; }
  Tracks soft-disconnect state; true after successful SoftDisconnect().

• bool Connected => Sock != null && Sock.Connected
  Reflects underlying socket state.

• string ConnectString => Connect_String
  Returns stored connection string.

• SocketFlags Flags { get; set; }
  Gets/sets socket flags used in BeginSend/BeginReceive.

• Socket Sock
  Public field holding the underlying Socket instance.

• event EventHandler OnDisconnected
  Raised in KeepAliveErrorReceived().

• void Create(string connectString, string hostIPAddress)
  Stores connectString and hostIPAddress, then calls CreateSock to initialize Sock.

• Socket CreateSock(string connectString, string hostIPAddress)
  Creates and configures a Socket with:

  • NoDelay = true (Nagle disabled)
  • KeepAlive = true
  • Buffer sizes from DFConstantsAndEnums.SendBufferSizeBytes / ReceiveBufferSizeBytes
  • Custom keep-alive parameters from DFConstantsAndEnums.LocalKeepAliveTimeOutMS / LocalKeepAliveRetryIntervalMS
  • Optional binding to hostIPAddress if provided.

• void SoftDisconnect()
  If HardwareConstants.AllowSoftDisconnects is true and socket is connected:

  • Disconnects and disposes Sock
  • Sets IsSoftDisconnected = true
  • Logs action.

• void SoftConnect()
  If AllowSoftDisconnects is true and socket is not connected:

  • Parses Connect_String as "host:port".
  • If RequiresKeepAliveReset is true, connects to port 8200, sends <60,5,4>, receives response, then disconnects.
  • Retries up to 3 times to connect to host:port (1s delay between attempts).
  • Sets IsSoftDisconnected = false, logs success.

• void KeepAliveErrorReceived()
  Shuts down, closes, and disposes Sock, sets Sock = null, and raises OnDisconnected.

• string GetConnectionData()
  Returns "local: {LocalEndPoint}, Remote: {RemoteEndPoint}" or "" on error.

• IAsyncResult BeginConnect(AsyncCallback, object)
  Validates Sock, Connect_String, and port format; delegates to Sock.BeginConnect.

• void EndConnect(IAsyncResult)
  Calls Sock.EndConnect, logs connection details.

• IAsyncResult BeginDisconnect(bool, AsyncCallback, object)
  Validates Sock; throws if socket is null or not connected (SocketException WSAEISCONN); delegates to Sock.BeginDisconnect.

• void EndDisconnect(IAsyncResult)
  Calls Sock.EndDisconnect.

• IAsyncResult BeginAccept(AsyncCallback, object)
  Validates Sock; delegates to Sock.BeginAccept.

• IConnection EndAccept(IAsyncResult)
  Calls Sock.EndAccept, wraps result in a new EthernetConnection instance.

• void Bind(int port)
  Validates Sock; binds to first DNS-resolved IP address on port.

• void Listen(int backlog)
  Validates Sock; calls Sock.Listen.

• IAsyncResult BeginSend(byte[], int, int, AsyncCallback, object)
  Validates Sock, callback, and connection state; throws if not connected; delegates to Sock.BeginSend.

• int EndSend(IAsyncResult)
  Calls Sock.EndSend; sets Sock = null on exception.

• Task<int> SendAsync(...)
  Wraps BeginSend/EndSend via Task.Factory.FromAsync.

• IAsyncResult BeginReceive(byte[], int, int, AsyncCallback, object)
  Validates Sock and callback; delegates to Sock.BeginReceive.

• int EndReceive(IAsyncResult)
  Calls Sock.EndReceive.

• void Dispose() / ~EthernetConnection()
  Implements IDisposable; safely shuts down/disposes Sock in Dispose(bool).

3. Invariants

• RESTConnection:

  • _bConnected is the sole source of truth for connection state; never updated by external I/O.
  • All Begin*/End* operations are synchronous and return immediately; no async state is maintained.
  • IsSoftDisconnected is always false; soft disconnect logic is absent.
  • Connected reflects _bConnected, which is manually toggled by BeginConnect/BeginDisconnect.

• EthernetConnection:

  • Connected depends on Sock != null && Sock.Connected; Sock may be null after errors or disposal.
  • SoftDisconnect() and SoftConnect() only execute if HardwareConstants.AllowSoftDisconnects is true.
  • SoftConnect() requires Connect_String to be in "host:port" format; port must be parseable as int.
  • BeginDisconnect throws SocketException if socket is not connected (per WSAEISCONN).
  • BeginSend/BeginReceive throw if socket is not connected or callback is null.
  • KeepAliveErrorReceived() guarantees Sock is null after execution (disposal path).

4. Dependencies

RESTConnection:

• Imports:
  • DTS.Common.Interface.Connection (for IConnection)
  • DTS.Common.Utilities.Logging (for APILogger, but not used in this file)
  • Standard .NET libraries (System.Net.Sockets, System.Threading, etc.)
• Depended on by: Any code requiring an IConnection instance where network activity is unnecessary (e.g., unit tests, REST-based workflows).

EthernetConnection:

• Imports:
  • DTS.Common.Interface.Connection (IConnection)
  • DTS.Common.DASResource (for Strings.EthernetConnection_*_Err* exception messages)
  • DTS.Common.Enums.DASFactory (for HardwareConstants.AllowSoftDisconnects)
  • DTS.Common.Utilities.Logging (for APILogger)
  • DFConstantsAndEnums (for buffer sizes, keep-alive timeouts, WSAEISCONN)
• Depended on by: Higher-level connection management logic (e.g., device initialization, data acquisition pipelines) requiring real Ethernet communication.

5. Gotchas

• RESTConnection:

  • IsSoftDisconnected is hardcoded to false; callers expecting soft-disconnect behavior will be misled.
  • OnDisconnected is declared but never raised; event subscriptions have no effect.
  • Begin*/End* methods are synchronous stubs; using them in async contexts may cause deadlocks or incorrect assumptions about I/O latency.
  • EndSend/EndReceive always return 0—no actual bytes sent/received.
  • SoftConnect/SoftDisconnect are no-ops despite being part of IConnection.

• EthernetConnection:

  • SoftConnect() uses Thread.Sleep (50ms/100ms/1000ms) for timing; this is blocking and may cause issues in high-throughput or UI contexts.
  • SoftConnect() sends <60,5,4> to port 8200 for keep-alive setup; this is a hardcoded protocol-specific command (device-dependent).
  • BeginDisconnect throws SocketException if socket is not connected—not an error condition per se, but callers must handle this exception to avoid crashes.
  • EndSend sets Sock = null on exception; this may cause subsequent operations to fail unexpectedly.
  • Bind uses the first DNS-resolved IP address (AddressList[0]), which may be non-deterministic or IPv6 in some environments.
  • CreateSock uses IOControlCode.KeepAliveValues with hardcoded KeepAliveOn = 1; this may conflict with system-wide settings.
  • IsSoftDisconnected is not reset to false in SoftConnect if AllowSoftDisconnects is false—only if soft disconnect logic runs.

• Both:

  • Neither class validates connectString format in Create(string) alone (only in Create(string, string) or BeginConnect).
  • RESTConnection and EthernetConnection share the same IConnection interface but have wildly different semantics; callers must know which implementation they hold.
  • RESTConnection’s GetConnectionData() returns a string with _hostIPAddress, but _hostIPAddress is never used in RESTConnection beyond storage—no binding or resolution occurs.

None identified beyond those above.