DP44/enriched-qwen3-coder-next/DataPRO/IService/StateMachine/StatusAndParameters/Download.md

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
DataPRO/IService/StateMachine/StatusAndParameters/Download/DownloadParameters.cs DataPRO/IService/StateMachine/StatusAndParameters/Download/DownloadStatusInformation.cs	2026-04-16T04:02:01.449211+00:00	Qwen/Qwen3-Coder-Next-FP8	1	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.