The IConnection interface defines a comprehensive abstraction for network socket connections within the DTS system. It provides a unified API for both client and server-side connection management, supporting connection lifecycle operations (create, connect, disconnect, dispose), bidirectional data transfer, and a "soft disconnect" mechanism for temporarily releasing connections with the expectation of reconnecting. The interface implements the Asynchronous Programming Model (APM) pattern for most operations, with one Task-based async method (SendAsync), and includes keep-alive monitoring capabilities.
2. Public Interface
Interface Declaration
publicinterfaceIConnection:IDisposable
Properties
Property
Signature
Description
IsSoftDisconnected
bool IsSoftDisconnected { get; }
Returns true if the unit is soft disconnected (connected then voluntarily disconnected with expectation of reconnecting).
Task<int> SendAsync(byte[] sendBuffer, int bufferStartOffset, int bufferSizeToSend)
Asynchronously sends data and returns the number of bytes sent. Uses TAP pattern.
BeginSend
IAsyncResult BeginSend(byte[] sendBuffer, int bufferStartOffset, int bufferSizeToSend, AsyncCallback callback, object callbackObject)
Begins an asynchronous send operation. Uses APM pattern.
EndSend
int EndSend(IAsyncResult ar)
Completes the asynchronous send operation and returns the number of bytes sent.
BeginReceive
IAsyncResult BeginReceive(byte[] receiveBuffer, int bufferStartOffset, int maxSizeToReceive, AsyncCallback callback, object callbackObject)
Begins an asynchronous receive operation.
EndReceive
int EndReceive(IAsyncResult ar)
Completes the asynchronous receive operation and returns the number of bytes received.
3. Invariants
Disposable Contract: All implementations must properly implement IDisposable, ensuring resources (sockets, buffers, etc.) are released when disposed.
APM Pattern Pairing: Every Begin* method must have a corresponding End* call to complete the operation and retrieve results. Calling End* without a preceding Begin*, or calling End* multiple times on the same IAsyncResult, is undefined behavior.
Soft Disconnect State Consistency: IsSoftDisconnected should only return true after SoftDisconnect() has been called and before SoftConnect() is called. The soft disconnect state implies a prior successful connection.
Connection State Before Operations: Data transfer methods (SendAsync, BeginSend, BeginReceive) require an active connection; behavior is undefined if called on a disconnected unit.
Create Before Use: Create() must be called before connection operations (BeginConnect, Bind, etc.).
4. Dependencies
External Dependencies (from imports)
System - Core .NET types (IAsyncResult, AsyncCallback, EventHandler, IDisposable)
Unknown from this source file alone. Implementations of this interface and consumers would be defined elsewhere in the codebase.
5. Gotchas
Mixed Async Patterns: The interface uses both APM (Begin*/End* methods) and TAP (SendAsync returning Task<int>) patterns. This inconsistency may cause confusion when choosing which method to use. Note that SendAsync is the only TAP-style method; all other async operations use APM.
Server and Client Methods in One Interface: The interface combines server-side methods (Bind, Listen, BeginAccept, EndAccept) with client-side methods (BeginConnect, EndConnect). Implementations may need to handle scenarios where inappropriate methods are called (e.g., calling Listen on a client connection).
Commented-Out Rate Methods: The source contains commented-out methods GetCurrentUploadRate() and GetCurrentDownloadRate(), suggesting bandwidth monitoring was planned or removed. Do not assume these exist.
Soft Disconnect vs. Regular Disconnect: The interface provides SoftDisconnect()/SoftConnect() alongside BeginDisconnect()/EndDisconnect(). The relationship between these two disconnect mechanisms is not specified—whether BeginDisconnect affects IsSoftDisconnected state is unclear from the source alone.
KeepAliveErrorReceived is a Method, Not an Event: Despite the naming convention suggesting an event handler, KeepAliveErrorReceived() is a void method. Its intended usage (called by whom, when, and what it should do) is not specified in the source.
