Documentation: DTS.Common.SerialConnection.SerialConnection

1. Purpose

The SerialConnection class provides a wrapper around System.IO.Ports.SerialPort to implement the IConnection interface. Its primary role is to abstract serial port communication behind an asynchronous, socket-like API (APM pattern). This allows serial devices to be handled uniformly within a system designed around generic connection interfaces, mimicking the behavior of network sockets for operations like connecting, sending, and receiving data.

2. Public Interface

Class: SerialConnection (implements IConnection)

Properties:

bool Connected { get; }: Returns the connection state. Note: Currently hardcoded to return false.
bool IsSoftDisconnected { get; }: Returns true if the unit is soft disconnected.
string ConnectString { get; }: Returns the stored port name (_PortName).
System.Net.Sockets.SocketFlags Flags { get; set; }: Gets or sets socket flags.

Events:

EventHandler OnDisconnected: Event raised upon disconnection.

Methods:

void Create(string PortName): Instantiates the internal SerialPort object.
void Create(string connectString, string hostIPAddress): Overload that currently performs no operation.
void SoftConnect(): Intended to connect the unit; currently empty.
void SoftDisconnect(): Intended to disconnect the unit; currently empty.
string GetConnectionData(): Returns an empty string.
double GetCurrentDownloadRate(): Returns 0.0.
double GetCurrentUploadRate(): Returns 0.0.

Connection Lifecycle (APM Pattern):

IAsyncResult BeginConnect(AsyncCallback cb, object state): Opens the serial port. Throws Exception if Port is null or _PortName is empty. Returns null.
void EndConnect(IAsyncResult ar): Validates Port exists. Throws Exception if null.

Data Transfer (APM Pattern):

IAsyncResult BeginSend(byte[] buffer, int offset, int size, AsyncCallback cb, object state): Begins an asynchronous write to the serial port. Throws Exception if Port or cb is null.
int EndSend(IAsyncResult ar): Completes the asynchronous write. Returns Port.BytesToWrite.
Task<int> SendAsync(byte[] sendBuffer, int bufferStartOffset, int bufferSizeToSend): Task-based async wrapper for BeginSend/EndSend.
IAsyncResult BeginReceive(byte[] buffer, int offset, int size, AsyncCallback cb, object state): Begins an asynchronous read from the serial port. Throws Exception if Port or cb is null.
int EndReceive(IAsyncResult ar): Completes the asynchronous read. Returns the number of bytes read.

Server/Socket Mimicry Methods:

IAsyncResult BeginAccept(AsyncCallback callback, Object state): Returns null. Throws if Port is null.
IConnection EndAccept(IAsyncResult asyncResult): Returns a new instance of SerialConnection. Throws if Port is null.
void Bind(int port): No-op. Throws if Port is null.
void Listen(int backlog): No-op. Throws if Port is null.
IAsyncResult BeginDisconnect(bool reuseSocket, AsyncCallback cb, Object state): Returns null. Throws if Port is null.
void EndDisconnect(IAsyncResult asyncResult): No-op. Throws if Port is null.

IDisposable:

void Dispose(): Disposes the SerialPort and suppresses finalization.

3. Invariants

Null Checks: Nearly all public methods (except Create overloads and disposal methods) throw a System.Exception if the protected Port field is null.
Callback Validation: BeginSend and BeginReceive throw a System.Exception if the provided AsyncCallback is null.
Connection String: BeginConnect throws a System.Exception if _PortName is null or empty.
Disposal: Once Dispose(bool disposing) runs, the Port is closed and set to null; subsequent calls return immediately.

4. Dependencies

Dependencies (Imports):
- DTS.Common.Interface.Connection: Defines the IConnection interface this class implements.
- System.IO.Ports: Provides the underlying SerialPort functionality.
- System: Basic system types, exceptions, and async patterns.
- System.Threading.Tasks: Used for Task-based async operations (SendAsync).
Dependents: Unknown from source alone (consumers of IConnection).

5. Gotchas

Critical Bug in Create(string PortName): The method assigns _PortName after attempting to initialize Port.
```
Port = new SerialPort(_PortName); // _PortName is likely null or stale here
_PortName = PortName;             // Assigned too late
```
This results in the SerialPort being instantiated with an incorrect or empty port name, likely causing connection failures.
Hardcoded Connected Property: The Connected property is hardcoded to return false and is never updated by BeginConnect or EndConnect. Code relying on this property to verify connectivity will fail.
APM Return Values: BeginConnect, BeginDisconnect, and BeginAccept return null instead of a valid IAsyncResult. This may break callers expecting a valid state object from standard APM implementations.
EndSend Return Value: EndSend returns Port.BytesToWrite (the number of bytes waiting in the send buffer), not the number of bytes successfully written (which is the standard behavior for socket EndSend).
Soft Disconnect Implementation: SoftConnect and SoftDisconnect are empty methods. The IsSoftDisconnected property is initialized to false but is never set by any method in the class.
No-op Methods: Bind, Listen, and KeepAliveErrorReceived perform no actions but throw exceptions if Port is null, making them effectively validation checks with no side effects.

5.9 KiB Raw Permalink Blame History