47 lines
3.8 KiB
Markdown
47 lines
3.8 KiB
Markdown
|
---
|
||
|
|
source_files:
|
||
|
|
- Common/DTS.CommonCore/Enums/Communication/CommunicationConstantsAndEnums.cs
|
||
|
|
generated_at: "2026-04-16T02:44:19.261971+00:00"
|
||
|
|
model: "Qwen/Qwen3-Coder-Next-FP8"
|
||
|
|
schema_version: 1
|
||
|
|
sha256: "fb3a2f656d5788aa"
|
||
|
|
---
|
||
|
|
|
||
|
|
# Communication
|
||
|
|
|
||
|
|
## 1. Purpose
|
||
|
|
This module defines core enumerations and delegates used for representing the outcomes and callback mechanisms of communication operations within the DTS system. It serves as a shared contract between communication implementations (e.g., network, serial, or custom transport layers) and higher-level consumers, enabling consistent reporting of connection, disconnection, send, receive, and cancellation states. The `CommunicationResult` enum standardizes status reporting, while the `CommunicationCallback` delegate provides a standardized way to handle asynchronous or event-driven communication reports.
|
||
|
|
|
||
|
|
## 2. Public Interface
|
||
|
|
|
||
|
|
### `CommunicationResult` enum
|
||
|
|
A set of named constants representing the possible outcomes of communication operations:
|
||
|
|
- `ConnectOK`, `ConnectFailed`, `ConnectTimeout` — outcomes for connection attempts
|
||
|
|
- `DisconnectOK`, `DisconnectFailed`, `DisconnectTimeout` — outcomes for disconnection attempts
|
||
|
|
- `SendOK`, `SendFailed`, `SendTimeout` — outcomes for send operations
|
||
|
|
- `ReceiveOK`, `ReceiveFailed`, `ReceiveTimeout` — outcomes for receive operations
|
||
|
|
- `Canceled` — indicates an operation was canceled (e.g., via cancellation token)
|
||
|
|
|
||
|
|
### `CommunicationCallback` delegate
|
||
|
|
```csharp
|
||
|
|
public delegate bool CommunicationCallback(ICommunicationReport report);
|
||
|
|
```
|
||
|
|
A callback function type used to process `ICommunicationReport` instances. It returns `true` to indicate the callback handled the report successfully or wishes to continue processing, and `false` to signal termination or failure. The actual behavior of the callback (e.g., logging, UI update, state transition) is implementation-defined, but the delegate contract requires a boolean return value.
|
||
|
|
|
||
|
|
## 3. Invariants
|
||
|
|
- The `CommunicationResult` enum values are exhaustive for the categories of operations: connect, disconnect, send, receive, and cancellation. No other result codes are defined in this module.
|
||
|
|
- The `CommunicationCallback` delegate must accept an `ICommunicationReport` parameter (from `DTS.Common.Interface.Communication`) and return a `bool`. The semantics of the return value are *not* defined in this file and must be inferred from usage or documentation of the calling code.
|
||
|
|
- No runtime validation or enforcement is performed on the enum values or callback invocations within this module — it is purely a definition layer.
|
||
|
|
|
||
|
|
## 4. Dependencies
|
||
|
|
- **Depends on**:
|
||
|
|
- `DTS.Common.Interface.Communication` namespace (specifically for `ICommunicationReport` used in `CommunicationCallback`).
|
||
|
|
- **Used by**:
|
||
|
|
- Any module implementing or consuming communication operations (e.g., transport layer implementations, communication managers, UI components).
|
||
|
|
- The `ICommunicationReport` interface (from the `DTS.Common.Interface.Communication` namespace) must be defined elsewhere; this module assumes its existence and contract.
|
||
|
|
|
||
|
|
## 5. Gotchas
|
||
|
|
- The `CommunicationCallback` return value semantics (`true`/`false`) are not specified in this file — callers and implementers must coordinate on interpretation (e.g., `false` may mean “stop processing” or “retry failed” depending on context).
|
||
|
|
- The `Canceled` result is distinct from timeout/failure modes but does not imply *why* it was canceled (e.g., user action, timeout, resource exhaustion).
|
||
|
|
- No constants (e.g., timeout durations, buffer sizes) are defined in this file despite the class name `CommunicationConstantsAndEnums` — only the `CommunicationResult` enum and `CommunicationCallback` delegate are present.
|
||
|
|
- None identified from source alone.
|