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

---
source_files:
  - DataPRO/IService/Classes/Download/UARTDownloadRequest.cs
  - DataPRO/IService/Classes/Download/DownloadRequest.cs
  - DataPRO/IService/Classes/Download/DownloadReport.cs
generated_at: "2026-04-16T03:58:36.838770+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "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 *n*th 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.