Connection

Documentation: `IConnection` Interface

1. Purpose

The IConnection interface defines a standardized abstraction for network connection management within the DTS system, supporting both synchronous and asynchronous send/receive operations, connection lifecycle control (including soft disconnect/reconnect semantics), and socket-level configuration. It serves as the foundational contract for all connection implementations (e.g., TCP, UDP, custom transports), enabling decoupled communication logic across the system while preserving consistent behavior for connection state, data transfer, and error handling.

2. Public Interface

Task<int> SendAsync(byte[] sendBuffer, int bufferStartOffset, int bufferSizeToSend)
Asynchronously sends data from sendBuffer, starting at bufferStartOffset, for bufferSizeToSend bytes. Returns the number of bytes sent.
bool IsSoftDisconnected { get; }
Indicates whether the connection is in a soft disconnected state—i.e., previously connected, then voluntarily disconnected with the expectation of reconnection.
void SoftDisconnect()
Voluntarily disconnects the connection without fully closing underlying resources, preserving state for later reconnection.
void SoftConnect()
Re-establishes a connection previously soft-disconnected, restoring communication capability.
System.Net.Sockets.SocketFlags Flags { get; set; }
Gets or sets the socket flags used for send/receive operations (e.g., DontRoute, OutOfBand).
event EventHandler OnDisconnected
Raised when the connection is fully disconnected (not soft-disconnected).
void KeepAliveErrorReceived()
Explicitly signals that a keep-alive timeout/error occurred (e.g., no timely response received). Implementation likely triggers disconnection or retry logic.
string ConnectString { get; }
Returns the connection string used to establish the connection (e.g., "tcp://192.168.1.10:5000").
bool Connected { get; }
Indicates whether the connection is currently active (i.e., not disconnected or soft-disconnected).
void Create(string connectString)
Initializes the connection using the provided connectString.
void Create(string connectString, string hostIPAddress)
Initializes the connection using connectString and an explicit hostIPAddress (likely for override or validation).
string GetConnectionData()
Returns diagnostic or metadata information about the current connection state (e.g., remote endpoint, protocol details).
IAsyncResult BeginConnect(AsyncCallback callback, object callbackObject)
Initiates an asynchronous connection attempt.
void EndConnect(IAsyncResult ar)
Completes an asynchronous connection attempt.
IAsyncResult BeginDisconnect(bool reuseSocket, AsyncCallback callback, object state)
Initiates an asynchronous disconnection. If reuseSocket is true, the underlying socket may be reused.
void EndDisconnect(IAsyncResult asyncResult)
Completes an asynchronous disconnection.
IAsyncResult BeginAccept(AsyncCallback callback, object state)
Initiates an asynchronous accept operation (for server-side connections).
IConnection EndAccept(IAsyncResult asyncResult)
Completes an asynchronous accept operation and returns a new IConnection representing the accepted client connection.
void Bind(int port)
Binds the connection to a local port (typically used for server-side listening).
void Listen(int backlog)
Begins listening for incoming connections with the specified backlog queue size.
IAsyncResult BeginSend(byte[] sendBuffer, int bufferStartOffset, int bufferSizeToSend, AsyncCallback callback, object callbackObject)
Initiates an asynchronous send operation.
int EndSend(IAsyncResult ar)
Completes an asynchronous send operation and returns the number of bytes sent.
IAsyncResult BeginReceive(byte[] receiveBuffer, int bufferStartOffset, int maxSizeToReceive, AsyncCallback callback, object state)
Initiates an asynchronous receive operation.
int EndReceive(IAsyncResult ar)
Completes an asynchronous receive operation and returns the number of bytes received.

Note

: Two methods—GetCurrentUploadRate() and GetCurrentDownloadRate()—are commented out and not part of the active interface.

3. Invariants

Connected must be true only when the underlying socket is actively connected (excluding soft-disconnected state).
IsSoftDisconnected must be true only after SoftDisconnect() is called and before SoftConnect() is called.
OnDisconnected must be raised only when the connection transitions to a non-recoverable (hard) disconnect state, not during soft disconnects.
SendAsync, BeginSend, EndSend, BeginReceive, EndReceive must only be invoked when Connected is true (behavior on violation is undefined per interface—implementation-dependent).
SoftConnect() must succeed only if IsSoftDisconnected is true.
Flags must be applied consistently to all socket operations (send/receive/connect/accept).
KeepAliveErrorReceived() must be called only when a keep-alive failure is detected (e.g., timeout without response).

4. Dependencies

Depends on:
- System (core types: Task, EventHandler, IAsyncResult, AsyncCallback, object)
- System.Threading.Tasks (for Task<int>)
- System.Net.Sockets (for SocketFlags)
Implemented by: Concrete connection classes (e.g., TcpConnection, UdpConnection)—not visible in this file but implied by usage.
Used by: Higher-level components requiring network communication (e.g., protocol handlers, device managers, session controllers).
No direct dependency on other DTS modules is visible in this interface, though ConnectString format and GetConnectionData() output likely conform to internal conventions.

5. Gotchas

Soft vs. Hard Disconnect: SoftDisconnect() does not raise OnDisconnected; only full disconnections do. Confusing these can lead to incorrect state management.
Connected vs. IsSoftDisconnected: Connected is false when IsSoftDisconnected is true. Code must check both states explicitly if distinguishing soft-disconnect is required.
BeginAccept/EndAccept: Returns a new IConnection instance—consumers must manage its lifecycle (including disposal).
reuseSocket in BeginDisconnect: If true, the socket may be reused; if false, it may be closed. Behavior depends on implementation.
No rate-limiting API: The commented-out GetCurrentUploadRate()/GetCurrentDownloadRate() suggest rate monitoring was considered but not implemented—do not assume rate data is available.
Create overloads: The two Create methods differ only by hostIPAddress; the purpose of the second parameter is unclear without implementation—likely for override or validation.
No timeout parameters: All async operations lack explicit timeout configuration—timeouts are likely handled internally or via KeepAliveErrorReceived().
No exception contract: The interface does not specify exceptions (e.g., ObjectDisposedException after SoftDisconnect/SoftConnect), leaving error handling implementation-defined.

None identified beyond those above.

7.6 KiB Raw Permalink Blame History