DP44/enriched-partialglm/Common/DTS.CommonCore/Interface/Connection.md

---
source_files:
  - Common/DTS.CommonCore/Interface/Connection/IConnection.cs
generated_at: "2026-04-16T12:12:24.920785+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "a6aead5143a016b8"
---

# Documentation: IConnection Interface

## 1. Purpose

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
```csharp
public interface IConnection : 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). |
| `Flags` | `System.Net.Sockets.SocketFlags Flags { get; set; }` | Gets or sets socket flags for send/receive operations. |
| `ConnectString` | `string ConnectString { get; }` | Returns the connection string associated with this connection. |
| `Connected` | `bool Connected { get; }` | Returns the current connection state. |

### Events

| Event | Signature | Description |
|-------|-----------|-------------|
| `OnDisconnected` | `event EventHandler OnDisconnected` | Raised when the connection is disconnected. |

### Methods - Connection Lifecycle

| Method | Signature | Description |
|--------|-----------|-------------|
| `Create` | `void Create(string connectString)` | Initializes the connection using the specified connection string. |
| `Create` | `void Create(string connectString, string hostIPAddress)` | Initializes the connection using the specified connection string and host IP address. |
| `SoftDisconnect` | `void SoftDisconnect()` | Performs a voluntary disconnect with the intention of reconnecting later. |
| `SoftConnect` | `void SoftConnect()` | Reconnects a soft disconnected unit. |
| `KeepAliveErrorReceived` | `void KeepAliveErrorReceived()` | Indicates that the device has not received a timely response to keep-alive. |
| `GetConnectionData` | `string GetConnectionData()` | Returns connection data as a string. |

### Methods - Server Operations

| Method | Signature | Description |
|--------|-----------|-------------|
| `Bind` | `void Bind(int port)` | Binds the connection to a specific port. |
| `Listen` | `void Listen(int backlog)` | Starts listening for incoming connections with the specified backlog. |
| `BeginAccept` | `IAsyncResult BeginAccept(AsyncCallback callback, object state)` | Begins an asynchronous operation to accept an incoming connection. |
| `EndAccept` | `IConnection EndAccept(IAsyncResult asyncResult)` | Completes the asynchronous accept operation and returns the accepted `IConnection`. |

### Methods - Client Connection Operations

| Method | Signature | Description |
|--------|-----------|-------------|
| `BeginConnect` | `IAsyncResult BeginConnect(AsyncCallback callback, object callbackObject)` | Begins an asynchronous connection attempt. |
| `EndConnect` | `void EndConnect(IAsyncResult ar)` | Completes the asynchronous connect operation. |
| `BeginDisconnect` | `IAsyncResult BeginDisconnect(bool reuseSocket, AsyncCallback callback, object state)` | Begins an asynchronous disconnect operation. |
| `EndDisconnect` | `void EndDisconnect(IAsyncResult asyncResult)` | Completes the asynchronous disconnect operation. |

### Methods - Data Transfer

| Method | Signature | Description |
|--------|-----------|-------------|
| `SendAsync` | `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`)
- `System.Threading.Tasks` - `Task<T>` for `SendAsync`
- `System.Net.Sockets.SocketFlags` - Socket configuration flags

### Dependents
- Unknown from this source file alone. Implementations of this interface and consumers would be defined elsewhere in the codebase.

## 5. Gotchas

1. **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.

2. **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).

3. **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.

4. **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.

5. **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.