238 lines
12 KiB
Markdown
238 lines
12 KiB
Markdown
---
|
|
source_files:
|
|
- DataPRO/IService/StateMachine/StatusAndParameters/Download/DownloadParameters.cs
|
|
- DataPRO/IService/StateMachine/StatusAndParameters/Download/DownloadStatusInformation.cs
|
|
generated_at: "2026-04-16T04:02:01.449211+00:00"
|
|
model: "Qwen/Qwen3-Coder-Next-FP8"
|
|
schema_version: 1
|
|
sha256: "f0aeebaaaf645cc5"
|
|
---
|
|
|
|
# Documentation: Download Parameters and Status Module
|
|
|
|
## 1. Purpose
|
|
|
|
This module provides the data structures and execution logic for managing and executing data downloads from DAS (Data Acquisition System) units within a state machine workflow. It consists of two core types: `DownloadParameters`, which holds configuration and runtime state for a download operation, and `DownloadStatusInformation`, which orchestrates the asynchronous download process, handles status reporting, cancellation, and directory management—including special handling for ROI (Region of Interest), Recovery, and folder copying scenarios. The module integrates with the broader state machine (via `States.Instance.DownloadStart`) and depends on DAS communication interfaces and logging utilities.
|
|
|
|
## 2. Public Interface
|
|
|
|
### `DownloadParameters`
|
|
|
|
- **`bool ProceedWhenDone { get; set; } = false;`**
|
|
Controls whether the state machine should proceed to the next state after the download completes.
|
|
|
|
- **`bool RequireAllDASFinish { get; set; } = false;`**
|
|
Indicates whether *all* DAS units in `DASList` must successfully finish downloading for the operation to be considered complete.
|
|
|
|
- **`string DefaultDownloadFolder { get; set; } = string.Empty;`**
|
|
Holds the configured base download folder path from the application config file.
|
|
|
|
- **`bool DefaultUploadBinaries { get; set; } = false;`**
|
|
Config flag indicating whether binary data should be uploaded after download.
|
|
|
|
- **`bool DefaultUploadExports { get; set; } = false;`**
|
|
Config flag for uploading exports.
|
|
|
|
- **`bool DefaultUploadLogs { get; set; } = false;`**
|
|
Config flag for uploading logs.
|
|
|
|
- **`bool DefaultUploadReports { get; set; } = false;`**
|
|
Config flag for uploading reports.
|
|
|
|
- **`bool DefaultUploadSetups { get; set; } = false;`**
|
|
Config flag for uploading setup files (e.g., `SETUP`, `DASConfigs`).
|
|
|
|
- **`IDASCommunication[] DASList { get; set; } = new IDASCommunication[0];`**
|
|
Array of DAS units to download data from. Must be non-null and populated before download.
|
|
|
|
- **`string CurrentTestTestId { get; set; } = string.Empty;`**
|
|
Test ID string for the current test session.
|
|
|
|
- **`string CurrentTestTestIdNode { get; set; } = string.Empty;`**
|
|
Test ID node (e.g., folder name) used in the file path hierarchy.
|
|
|
|
- **`string CurrentTestTestDirectory { get; set; } = string.Empty;`**
|
|
Full path to the current test directory.
|
|
|
|
- **`string CurrentTestOriginalTestDirectory { get; set; } = string.Empty;`**
|
|
Full path to the original test directory (used in recovery scenarios).
|
|
|
|
- **`bool ROI { get; set; } = false;`**
|
|
Indicates whether the current download is in ROI mode.
|
|
|
|
- **`bool Recovery { get; set; } = false;`**
|
|
Indicates whether the current download is a recovery operation.
|
|
|
|
- **`bool FoldersCopied { get; set; }`**
|
|
Flag to prevent redundant copying of `DASConfigs`, `SETUP`, `Logs`, `Reports` folders during recovery or re-runs.
|
|
|
|
- **`ErrorCallback ErrorCallback { get; set; }`**
|
|
Callback delegate invoked for user prompts or error notifications (e.g., missing hardware, existing files).
|
|
|
|
- **`void Reset()`**
|
|
Resets all properties to their default values (e.g., empty `DASList`, `false` for all flags, `null` for `ErrorCallback`).
|
|
*Note:* Does *not* reset `ROI`, `Recovery`, or `FoldersCopied` to defaults—only explicitly listed properties in the method body.
|
|
|
|
- **`string ToString()`**
|
|
Returns an empty string (no-op implementation).
|
|
|
|
### `DownloadStatusInformation`
|
|
|
|
- **`enum StatusValues`**
|
|
Defines all possible status messages that can be sent via `StatusAction`:
|
|
- `Preparing`, `Downloading`, `CaptureAttributes`, `Failed`, `ROIFailed`, `Completed`, `Cancelling`, `Cancelled`, `CancelledPartial`, `DownloadDirectory`, `MissingHardware`, `NoDataToDownload`, `NotAllChannelsDownloaded`, `ExistingFiles`, `CleaningUp`, `QueryEventData`.
|
|
|
|
- **`ManualResetEvent CancelEvent = new ManualResetEvent(false);`**
|
|
Signaled to request cancellation of the download.
|
|
|
|
- **`ManualResetEvent DoneEvent = new ManualResetEvent(false);`**
|
|
Signaled when the download task completes (successfully, cancelled, or failed).
|
|
|
|
- **`ActionCompleteDelegate CompleteAction { get; set; }`**
|
|
Callback invoked upon successful completion of the download task.
|
|
|
|
- **`SetProgressValueDelegate ProgressAction { get; set; }`**
|
|
Callback to report progress (currently unused in `Download()`).
|
|
|
|
- **`StatusIntDelegate StatusAction { get; set; }`**
|
|
Callback to report status updates (takes `int` cast of `StatusValues`).
|
|
|
|
- **`StatusExIntDelegate StatusExAction { get; set; }`**
|
|
Callback for extended status (e.g., `NoDataToDownload` passes array of DAS with missing config).
|
|
|
|
- **`bool AllDASFinished { get; set; } = false;`**
|
|
Set to `true` if *all* DAS in `param.DASList` have finished downloading (only checked if `RequireAllDASFinish` is true).
|
|
|
|
- **`void Reset()`**
|
|
Clears all delegate references and resets `AllDASFinished` to `false`.
|
|
|
|
- **`void Download()`**
|
|
Starts the download process asynchronously on a background thread. Key behaviors:
|
|
- Invokes `StatusAction(StatusValues.Preparing)` at start.
|
|
- Validates DAS availability against `DASFactory.GetDASList()`, calls `ErrorCallback(StatusValues.MissingHardware)` if missing.
|
|
- Fails if `DASList` is empty or any DAS lacks `ConfigData`.
|
|
- Retrieves event info via `GetOneEvent()`; fails if no event found.
|
|
- Constructs download directory:
|
|
`<DownloadFolder>/<EventId>/<CurrentTestTestId>/Binary/<ROI|ALL>`.
|
|
- In **Recovery mode**, reuses the original `CurrentTestTestIdNode` path if test ID changed, and copies folders (`DASConfigs`, `Logs`, `Reports`, `SETUP`) from original test directory if needed (unless `FoldersCopied` is true).
|
|
- Uses a `ManualResetEvent` (`mre`) that waits indefinitely—**no actual download logic is implemented**; the task exits after setting `CompleteAction` and `StatusAction(Completed)`.
|
|
- Sets `DoneEvent` upon completion.
|
|
|
|
- **`Task Cancel()`**
|
|
Asynchronously cancels the download:
|
|
- Sets `CancelEvent`.
|
|
- Reports `StatusValues.Cancelling`.
|
|
- Waits 100ms (simulated delay).
|
|
- Waits for `DoneEvent`.
|
|
- Reports `StatusValues.Cancelled`.
|
|
|
|
- **`bool DirectoryCopy(...)`**
|
|
Copies files from `sourceDirName` to `destDirName`, with filtering based on upload flags (`DefaultUpload*`).
|
|
- Overwrites existing files (uses `File.Copy(..., true)`).
|
|
- Skips files if corresponding upload flag is `false` (e.g., skips `Binary` if `DefaultUploadBinaries` is `false`).
|
|
- Prompts user via `ErrorCallback(StatusValues.ExistingFiles)` if destination files exist.
|
|
- Logs success/failure via `APILogger`.
|
|
- Returns `true` only if *uploading data* (`uploadingData == true`) and copy succeeds; otherwise `false`.
|
|
|
|
- **`private static string GetHash(DownloadReport.EventInfo)`**
|
|
Helper: returns `"TestID_EventNumber"` formatted as uppercase (e.g., `"T123_05"`).
|
|
|
|
- **`private IEventInfoAggregate GetOneEvent(List<IDASCommunication>)`**
|
|
Helper: aggregates event info from DAS units.
|
|
- Collects unique events by hash (`TestID_EventNumber`).
|
|
- Returns the first aggregated event (or `null` if none found).
|
|
*Note:* The `TODO` comment indicates incomplete event aggregation logic.
|
|
|
|
## 3. Invariants
|
|
|
|
- **`DASList` must be non-null and populated before calling `Download()`**
|
|
The method checks for empty `dasList` and fails if `!dasList.Any()`.
|
|
|
|
- **Each DAS in `DASList` must have non-null `ConfigData`**
|
|
Checked via `das.ConfigData == null`; triggers `StatusExAction(StatusValues.NoDataToDownload)`.
|
|
|
|
- **At least one DAS must have valid `EventInfo` with events**
|
|
`GetOneEvent()` must return non-null; otherwise, `StatusAction(StatusValues.Failed)` is invoked.
|
|
|
|
- **Download directory must be creatable**
|
|
If `Directory.CreateDirectory(directory)` throws, `StatusAction(StatusValues.Failed)` is invoked.
|
|
|
|
- **`StatusAction` must be assigned for status reporting**
|
|
All status updates are conditional on `StatusAction?.Invoke(...)`.
|
|
|
|
- **`ErrorCallback` must handle user prompts synchronously**
|
|
The code calls `errorCallback?.Invoke(...)` and expects a `DialogResult` return.
|
|
|
|
- **Recovery mode path reuse**
|
|
When `Recovery == true` and `CurrentTestTestId != CurrentTestTestIdNode`, the download directory reuses `currentTestTestIdNode` (original test ID node) to avoid duplicating folders.
|
|
|
|
- **`FoldersCopied` prevents redundant copying**
|
|
Folder copying only occurs if `Recovery && (!foldersCopied)`.
|
|
|
|
## 4. Dependencies
|
|
|
|
### Imports/References
|
|
- **`DTS.Common.Interface.DASFactory`**
|
|
Provides `IDASCommunication`, `IDASFactory`, and `IEventInfoAggregate`.
|
|
- **`DTS.Common.Interface.StatusAndProgressBar`**
|
|
Provides `IStatusParameters`, `IStatusInfo`, `ErrorCallback`, `ActionCompleteDelegate`, `SetProgressValueDelegate`, `StatusIntDelegate`, `StatusExIntDelegate`.
|
|
- **`DTS.Common.Utilities.Logging`**
|
|
Provides `APILogger`.
|
|
- **`System.Windows.Forms`**
|
|
Used for `DialogResult` (e.g., `DialogResult.OK` in `ErrorCallback` usage).
|
|
- **`System.IO`**
|
|
For `Directory`, `DirectoryInfo`, `File`, `Path`, `Uri`.
|
|
|
|
### Internal Dependencies
|
|
- **`States.Instance.DownloadStart`**
|
|
Accessed to retrieve:
|
|
- `Status.DownloadParams` (`DownloadParameters`)
|
|
- `Status.GlobalStatusParameters`
|
|
- `DASFactory` (`IDASFactory`)
|
|
|
|
- **`Common.Constants`**
|
|
Used for folder names: `DAS_CONFIGS`, `REPORT_DIR_NAME` (values not visible in source).
|
|
|
|
- **`Resources.UploadData_Files_Exist`**
|
|
String resource used in `DirectoryCopy` for existing files prompt.
|
|
|
|
## 5. Gotchas
|
|
|
|
- **`DirectoryCopy` does not actually upload data**
|
|
Despite the name and upload-related flags, it only copies files *within the local filesystem*. The `uploadingData` parameter controls filtering but not network upload.
|
|
|
|
- **No actual download logic in `Download()`**
|
|
The method sets up directories and runs validation, but the core download loop is missing—`mre.WaitOne()` blocks indefinitely, and the task exits without performing I/O. This suggests incomplete implementation or placeholder logic.
|
|
|
|
- **`DirectoryCopy` has confusing return semantics**
|
|
Returns `true` *only* if `uploadingData == true` and copy succeeds; otherwise returns `false`. This makes it unsuitable for generic copying.
|
|
|
|
- **`DirectoryCopy` uses `Uri` for relative path calculation**
|
|
Builds URIs with `"file:\\\\"` prefix and uses `MakeRelativeUri`—non-standard and potentially fragile for Windows paths.
|
|
|
|
- **`GetOneEvent` is incomplete**
|
|
The `TODO` comment and missing `IEventInfoAggregate` constructor call (`new IEventInfoAggregate(...)`) indicate the event aggregation logic is not implemented.
|
|
|
|
- **`Reset()` does not reset `ROI`, `Recovery`, or `FoldersCopied`**
|
|
Only resets explicitly listed properties—these flags retain their values unless manually cleared.
|
|
|
|
- **`ToString()` is a no-op**
|
|
Returns empty string; no debugging value.
|
|
|
|
- **`DirectoryCopy` may throw if `sourceDirName`/`destDirName` are invalid**
|
|
`Uri` construction and `DirectoryInfo` access lack explicit error handling beyond the outer `try-catch`.
|
|
|
|
- **Hardcoded folder names**
|
|
`"Binary"`, `"ROI"`, `"ALL"`, `"Logs"`, `"SETUP"`, `"Reports"`, `"DASConfigs"` are used directly—should be constants.
|
|
|
|
- **`Thread.Sleep(100)` and `Thread.Sleep(10)` in async path**
|
|
Blocking calls in cancellation and upload paths may cause UI freezes or delays.
|
|
|
|
- **Missing `NotAllChannelsDownloaded` handling**
|
|
Status value exists but is never invoked in `Download()`.
|
|
|
|
- **`ExistingFiles` prompt may show multiple times**
|
|
`DirectoryCopy` is called per folder (e.g., `DASConfigs`, `Logs`, etc.), and each may prompt for existing files.
|
|
|
|
- **No validation of `CurrentTest*` path components**
|
|
Invalid characters or null values could cause path construction errors. |