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

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
DataPRO/IService/Classes/Download/UARTDownloadRequest.cs DataPRO/IService/Classes/Download/DownloadRequest.cs DataPRO/IService/Classes/Download/DownloadReport.cs	2026-04-16T03:58:36.838770+00:00	Qwen/Qwen3-Coder-Next-FP8	1	6a51104a1281b13a

Documentation: Download Request and Report Classes

1. Purpose

This module provides data structures and static utility methods to configure and persist download requests and event metadata for a DAS (Data Acquisition System). It defines concrete implementations (UARTDownloadRequest, DownloadRequest, DownloadReport) of their corresponding interfaces (IUARTDownloadRequest, IDownloadRequest, IDownloadReport) used to specify what data to download from the DAS device and which events are present/already downloaded. The SetWhatToDownload and SetEvent* static methods in these classes synchronize request/report state with both the DAS communication layer (IDASCommunication) and a backing database via DASFactoryDb.Download functions.

2. Public Interface

UARTDownloadRequest class

• EventNumber (ushort): Gets or sets the event number from which to download UART data.

• TotalByteCount (ulong): Gets or sets the total number of bytes in the UART stream.

• TriggerByteCount (ulong): Gets or sets the byte offset within the stream where the trigger occurred.

• FaultByteCount (ulong): Gets or sets the byte offset within the stream where a fault occurred.

• StartTimestamp (ulong): Gets or sets the start timestamp of the UART stream.

• EndTimestamp (ulong): Gets or sets the end timestamp of the UART stream.

• BaudRate (int): Gets or sets the baud rate used during UART recording.

• SetWhatToDownload(IDASCommunication das, IUARTDownloadRequest request, bool bSetInDb) (static void):
  Assigns the provided request to das.WhatUARTToDownload (if das implements IUARTDownload). If bSetInDb is true and the database is connected, clears existing UART download requests for das.RecordId, then inserts the new request (or does nothing if request is null). Exceptions during DB insertion are logged via APILogger.Log.

DownloadRequest class

• ALL_CHANNELS (const byte): Value 0xFF; indicates all channels should be downloaded. Currently the only supported value.

• EventNumber (ushort): Gets or sets the event number to download.

• DASChannelNumber (byte): Gets or sets the channel number; must be ALL_CHANNELS (0xFF) per current implementation.

• StartSample (ulong, virtual): Gets or sets the first sample index to download.

• EndSample (ulong, virtual): Gets or sets the last sample index to download.

• SamplesToSkip (ulong): Gets or sets subsampling factor. 0 or 1 means no subsampling; n > 1 means every nth sample. Invariant: (EndSample - StartSample + 1) must be divisible by SamplesToSkip.

• StartRecordTimestampSec (double): Gets or sets the integer seconds portion of the record start timestamp.

• TriggerTimestampSec (double): Gets or sets the integer seconds portion of the trigger timestamp.

• StartRecordTimestampNanoSec (double): Gets or sets the nanoseconds portion of the record start timestamp.

• TriggerTimestampNanoSec (double): Gets or sets the nanoseconds portion of the trigger timestamp.

• PTPMasterSync (bool): Gets or sets whether PTP master synchronization was used.

• SetWhatToDownload(IDASCommunication das, IDownloadRequest request, bool bSetInDb) (static void):
  Assigns request to das.WhatToDownload. Logs the request details if non-null. If bSetInDb is true and the database is connected, clears existing download requests for das.RecordId, then inserts the new request (or does nothing if request is null). Exceptions during DB insertion are logged via APILogger.Log.

DownloadReport class

Nested Types

• EventInfo (class, implements IEventInfo):
  Represents metadata for a single event/test.

  • Modules (IDASModule[]): Array of modules involved in the event, indexed by ModuleArrayIndex.
  • EventNumber (int): Event number.
  • TestGUID (Guid): Event GUID.
  • FaultFlags (ushort): Fault flags.
  • FaultFlagsEx (ushort): Extended fault flags.
  • ArmAttempts (byte): Number of arm attempts.
  • TestTime (DateTime): Timestamp of the event.
  • TestID (string): Event ID string.
  • Description (string): Event description.
  • HasBeenDownloaded (bool): Whether the event has been downloaded.
  • WasTriggered (bool): Whether the event received a trigger.
  • ClearFaults() (void): Resets FaultFlags and FaultFlagsEx to 0.
  • EventInfo(EventInfo copy) (constructor): Copies all fields from another EventInfo.

• UARTEventInfo (class, implements IUARTEventInfo):
  Represents metadata for a single UART event.

  • EventNumber (ushort): Event number.
  • DataPresent (bool): Whether UART data exists for this event.
  • DataDownloaded (bool): Whether UART data has been downloaded.
  • TotalByteCount (ulong): Total bytes of UART data.
  • TriggerByteCount (ulong): Byte offset of trigger.
  • FaultByteCount (ulong): Byte offset of fault.
  • StartTimestamp (ulong): UART stream start timestamp.
  • EndTimestamp (ulong): UART stream end timestamp.
  • BaudRate (uint): Baud rate during recording.

Instance Properties

• Events (IEventInfo[]): Array of all events on the DAS.
• UARTEvents (IUARTEventInfo[]): Array of all UART events on the DAS.

Static Methods

• SetEventDownloadStatus(IDASCommunication das, bool[] status, bool bStoreInDb) (static void):
  Sets das.EventDownloadedStatus to status. If bStoreInDb and DB connected, clears and re-inserts status entries for das.RecordId. Logs exceptions.

• SetEventArmAttempts(IDASCommunication das, byte[] armAttempts, bool storeInDb) (static void):
  Sets das.ArmAttempts to armAttempts. Persists to DB if applicable.

• SetEventFaultFlags(IDASCommunication das, ushort[] faultFlags, bool storeInDb) (static void):
  Sets das.FaultFlags to faultFlags. Persists to DB if applicable.

• SetEventInfo(IDASCommunication das, IDownloadReport eventInfo, bool storeInDB) (static void):
  Sets das.EventInfo to eventInfo. Persists each IEventInfo in eventInfo.Events to DB by serializing Modules to XML and calling Download.InsertEventInfo. Logs exceptions.

• SetEventGuids(IDASCommunication das, Guid[] guids, bool storeInDb) (static void):
  Sets das.EventGuids to guids. Persists to DB if applicable.

3. Invariants

• DownloadRequest.DASChannelNumber must be ALL_CHANNELS (0xFF). Other values are unsupported per the class documentation.
• DownloadRequest.SamplesToSkip must divide (EndSample - StartSample + 1) exactly. The code does not enforce this at runtime; violation would likely cause downstream errors.
• DownloadRequest.SetWhatToDownload and UARTDownloadRequest.SetWhatToDownload:
  • If bSetInDb is false or DASFactoryDb.DbWrapper.Connected is false, no DB operations occur.
  • DB operations always clear all existing requests for das.RecordId before inserting the new one (or none if request is null).
• DownloadReport.SetEventInfo serializes eventInfo.Modules to XML using XmlWriter with ConformanceLevel.Document. If any IDASModule.WriteXml implementation fails, the entire operation fails and is logged.
• DownloadReport.EventInfo.ClearFaults() unconditionally sets both FaultFlags and FaultFlagsEx to 0.

4. Dependencies

Internal Dependencies (from source)

• DASFactoryDb.Download: Provides DB functions:
  • ClearExistingUARTDownloadRequests, UARTDownloadRequestInsert
  • ClearExistingDownloadRequests, DownloadRequestInsert
  • ClearExistingEventDownloadStatus, InsertEventDownloadStatus
  • ClearExistingEventArmAttempts, InsertEventArmAttempts
  • ClearExistingFaultFlags, InsertEventFaultFlags
  • ClearExistingDownloadReports, InsertEventInfo
  • ClearExistingEventGuids, EventGuidInsert
• DASFactoryDb.DbWrapper: Provides Connected property and is used to gate DB operations.
• DTS.Common.Interface.DASFactory: Defines IDASCommunication, IDownloadRequest, IUARTDownloadRequest, IDownloadReport, IEventInfo, IUARTEventInfo.
• DTS.Common.Interface.DASFactory.Download: Defines IUARTDownload (used in UARTDownloadRequest.SetWhatToDownload to cast das).
• DTS.Common.Interface.DownloadEvent: Defines IEventInfo (used in DownloadReport.EventInfo).
• DTS.Common.Utilities.Logging: Provides APILogger for exception logging.

External Dependencies (inferred)

• Database: SQL Server (via System.Data.SqlClient and SqlTypes imports in DownloadReport.cs).
• XML serialization: Uses System.Xml for IDASModule.WriteXml serialization.

5. Gotchas

• DownloadRequest.SamplesToSkip validation is not enforced: The code comments state (EndSample - StartSample + 1) must be a multiple of SamplesToSkip, but no runtime check exists. Invalid values may cause errors downstream.
• UARTDownloadRequest.SetWhatToDownload silently ignores non-IUARTDownload instances: If das does not implement IUARTDownload, the method returns early without setting WhatUARTToDownload or logging.
• DownloadReport.EventInfo copy constructor performs shallow copy: Modules = copy.Modules copies the array reference, not the elements. Modifying the array or its contents via one instance affects the other.
• DownloadReport.SetEventInfo serializes Modules to XML: If any IDASModule.WriteXml implementation is buggy or writes invalid XML, the entire operation fails and is logged. No partial persistence occurs.
• DownloadRequest.SetWhatToDownload logs only when request is non-null: If request is null, no log entry is made, even though das.WhatToDownload is set to null.
• DownloadReport.UARTEventInfo.BaudRate is uint, but UARTDownloadRequest.BaudRate is int: Mismatched types may require conversion when copying data between them.
• DB operations are all-or-nothing per call: Each SetEvent* method clears all existing DB records for its respective field before inserting new ones. This is not incremental and may cause data loss if called with incomplete arrays.
• DownloadReport.SetEventDownloadStatus, SetEventArmAttempts, SetEventFaultFlags, SetEventGuids do not validate array length: Passing an array of incorrect length (e.g., mismatched with number of events) may cause DB inconsistencies or downstream errors.