84 lines
7.0 KiB
Markdown
84 lines
7.0 KiB
Markdown
---
|
||
source_files:
|
||
- DataPRO/CanFDApiProxy/Requests/SerialRequest.cs
|
||
- DataPRO/CanFDApiProxy/Requests/CanPostRequest.cs
|
||
- DataPRO/CanFDApiProxy/Requests/FileRequest.cs
|
||
- DataPRO/CanFDApiProxy/Requests/ClocksRequest.cs
|
||
- DataPRO/CanFDApiProxy/Requests/NetworkRequest.cs
|
||
- DataPRO/CanFDApiProxy/Requests/LEDsRequest.cs
|
||
- DataPRO/CanFDApiProxy/Requests/CANConfigRequest.cs
|
||
- DataPRO/CanFDApiProxy/Requests/CanConfigItem.cs
|
||
generated_at: "2026-04-16T04:02:28.102963+00:00"
|
||
model: "Qwen/Qwen3-Coder-Next-FP8"
|
||
schema_version: 1
|
||
sha256: "b4b7d8b4fcb0bb80"
|
||
---
|
||
|
||
# Requests
|
||
|
||
## Documentation: `CANFDApiProxy.Requests` Module
|
||
|
||
---
|
||
|
||
### 1. **Purpose**
|
||
|
||
This module defines a set of request classes used to serialize configuration and control commands for a CAN FD device API proxy layer. Each class corresponds to a specific type of operation (e.g., network configuration, LED control, CAN bus configuration, file operations, clock synchronization), and is intended for use in constructing JSON payloads sent to a backend service or embedded device. The module serves as a data contract layer—encapsulating structured input for remote API endpoints—without implementing business logic or I/O operations itself.
|
||
|
||
---
|
||
|
||
### 2. **Public Interface**
|
||
|
||
All classes and enums are declared in the `CANFDApiProxy.Requests` namespace.
|
||
|
||
| Name | Type | Signature & Description |
|
||
|------|------|-------------------------|
|
||
| `SerialRequest` | class | `public class SerialRequest { public string serial { get; set; } }`<br>• Represents a request to perform an operation using a device serial number. |
|
||
| `NetworkRequest` | class | `public class NetworkRequest { public bool dhcp { get; set; } public string set_address { get; set; } }`<br>• Configures network settings: `dhcp` enables/disables DHCP; `set_address` specifies a static IP address (format unspecified). |
|
||
| `LEDsRequest` | class | `public class LEDsRequest { public string led { get; set; } public string cmd { get; set; } public string color { get; set; } }`<br>• Controls an LED: `led` identifies the LED (via `LedName`), `cmd` is `"on"`/`"off"`, `color` is `"red"`, `"green"`, or `"blue"` (via `LedColor`). |
|
||
| `LedColor` | enum | `public enum LedColor { red, green, blue }`<br>• Valid LED colors. |
|
||
| `LedCmd` | enum | `public enum LedCmd { on, off }`<br>• Valid LED commands. |
|
||
| `LedName` | enum | `public enum LedName { can1, can2, can3, can4, pwr, sts, status }`<br>• Valid LED identifiers. |
|
||
| `CANConfigRequest` | class | `public class CANConfigRequest { public config config { get; set; } public string Status { get; set; } }`<br>• Top-level request for CAN bus configuration. Contains a `config` object and an optional `Status` string (e.g., `"success"`). |
|
||
| `config` | class | `public class config { public CanConfigItem can1 { get; set; } public CanConfigItem can2 { get; set; } public CanConfigItem can3 { get; set; } public CanConfigItem can4 { get; set; } }`<br>• Holds per-CAN-channel configuration (up to 4 channels). |
|
||
| `CanConfigItem` | class | `public class CanConfigItem(int base_or_arb_bitrate, int base_or_arb_sjw, int data_bitrate, int data_sjw, string filetype, bool included, bool is_fd)`<br>• Constructor initializes all properties.<br>• Properties:<br> - `base_or_arb_bitrate`: int — Bitrate for arbitration/base phase (e.g., 500000).<br> - `base_or_arb_sjw`: int — Synchronization jump width for arbitration/base phase.<br> - `data_bitrate`: int — Bitrate for data phase (used only if `is_fd == true`).<br> - `data_sjw`: int — SJW for data phase.<br> - `filetype`: string — File type identifier (e.g., `"bin"`, `"hex"`).<br> - `included`: bool — Whether this channel’s config is active.<br> - `is_fd`: bool — Whether CAN FD mode is enabled.<br>• Includes `ToString()` overrides for debugging. |
|
||
|
||
> **Note**: `CanConfigItem` has no parameterless constructor. All instances must be created via the explicit constructor.
|
||
|
||
---
|
||
|
||
### 3. **Invariants**
|
||
|
||
- `SerialRequest.serial` and `NetworkRequest.set_address` are expected to be non-null and non-empty when used, though not enforced in the class itself.
|
||
- `LEDsRequest.led`, `cmd`, and `color` are expected to match values from `LedName`, `LedCmd`, and `LedColor` respectively—**but no runtime validation is performed**; mismatches may cause downstream errors.
|
||
- `CanConfigItem` instances must be constructed with all 7 parameters; partial initialization is impossible due to lack of a parameterless constructor.
|
||
- `config` object expects exactly 4 `CanConfigItem` properties (`can1`–`can4`), but they may be `null` unless explicitly set.
|
||
- `CANConfigRequest.Status` is a string field with no defined format or allowed values in this module.
|
||
|
||
---
|
||
|
||
### 4. **Dependencies**
|
||
|
||
- **Internal usage**: `CANConfigRequest` references `config`, which is defined in the same namespace (`CANFDApiProxy.Requests`).
|
||
- **External usage**: `CANConfigRequest` imports `using CANFDApiProxy.Messages;`, indicating a dependency on the `CANFDApiProxy.Messages` namespace (not provided in source). This suggests `config` or related types may be shared or extended there.
|
||
- **Consumers**: These request classes are likely used by higher-level API client classes (e.g., in `CANFDApiProxy.Client` or similar) to serialize requests to JSON for HTTP or serial transport.
|
||
- **No external libraries** are imported beyond the standard `System` (implied by C# syntax).
|
||
|
||
---
|
||
|
||
### 5. **Gotchas**
|
||
|
||
- **No validation**: None of the request classes perform input validation (e.g., checking `serial` is non-empty, `set_address` is a valid IP, or `led`/`cmd`/`color` match expected enums). Validation must be handled externally.
|
||
- **Enum mismatch risk**: `LEDsRequest` uses `string` properties (`led`, `cmd`, `color`) instead of the strongly-typed `LedName`, `LedCmd`, and `LedColor` enums. This invites typos (e.g., `"Red"` vs `"red"`) and runtime errors.
|
||
- **`CanConfigItem` constructor is mandatory**: Since there is no parameterless constructor, deserialization frameworks (e.g., `System.Text.Json`) may fail unless custom converters or `JsonConstructor` attributes are applied.
|
||
- **Ambiguous field semantics**:
|
||
- `NetworkRequest.set_address`’s format (e.g., CIDR notation, `"192.168.1.10"`) is unspecified.
|
||
- `FileRequest.path` and `ClocksRequest.time` are defined but no usage context is provided in this module.
|
||
- `CANConfigRequest.Status` is present in the request type, suggesting it may be used for client-to-server feedback—unusual for a request object.
|
||
- **Inconsistent visibility**: `SerialRequest` and `NetworkRequest` are `public`, while `CanPostRequest`, `FileRequest`, and `ClocksRequest` are `internal`. This implies only a subset of request types are part of the public API surface.
|
||
- **No documentation on `filetype`**: Its purpose (e.g., firmware image type, config file format) is unclear from the source.
|
||
|
||
> **None identified from source alone** for `CanPostRequest`, `FileRequest`, and `ClocksRequest` beyond visibility and field names—behavior is entirely inferred from field names and naming conventions.
|
||
|
||
---
|
||
|
||
*End of documentation.* |