DP44/enriched-qwen3-coder-next/Common/DTS.Common/Interface/DASFactory/Download.md

---
source_files:
  - Common/DTS.Common/Interface/DASFactory/Download/IDownloadReport.cs
  - Common/DTS.Common/Interface/DASFactory/Download/IEventInfoAggregate.cs
  - Common/DTS.Common/Interface/DASFactory/Download/IUARTDownload.cs
  - Common/DTS.Common/Interface/DASFactory/Download/IUARTDownloadRequest.cs
  - Common/DTS.Common/Interface/DASFactory/Download/IUARTEventInfo.cs
  - Common/DTS.Common/Interface/DASFactory/Download/IDownloadRequest.cs
  - Common/DTS.Common/Interface/DASFactory/Download/IEventInfo.cs
  - Common/DTS.Common/Interface/DASFactory/Download/IDownload.cs
generated_at: "2026-04-16T03:10:59.435560+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "eb0f522ba1432603"
---

# Documentation: DASFactory Download Interfaces

## 1. Purpose

This module defines a set of interfaces that collectively model the data structures and contracts required for downloading event data (both analog/digital channel data and UART stream data) from a DAS (Data Acquisition System). It serves as the contract layer between the DAS hardware/firmware and the DASFactory application, enabling structured querying, reporting, and state tracking of event downloads. The interfaces standardize how event metadata (e.g., timestamps, fault flags, GUIDs), download requests (e.g., sample ranges, sub-sampling), and UART-specific data descriptors are represented and exchanged.

## 2. Public Interface

### Interfaces

#### `IDownloadReport`
- **`IEventInfo[] Events { get; set; }`**  
  Gets or sets an array of all standard (non-UART) event metadata stored on the DAS. Index corresponds to event number (0-based or 1-based depending on system convention).
- **`IUARTEventInfo[] UARTEvents { get; set; }`**  
  Gets or sets an array of UART-specific event metadata. Each entry corresponds to a UART event, indexed by event number.

#### `IEventInfoAggregate`
- **`string EventId { get; set; }`**  
  Unique identifier for the event (e.g., user-assigned or auto-generated).
- **`string EventDescription { get; set; }`**  
  Human-readable description of the event.
- **`double DurationSeconds { get; set; }`**  
  Total duration of the event in seconds.
- **`string GUID { get; set; }`**  
  Globally unique identifier for the event.
- **`bool HasBeenDownloaded { get; set; }`**  
  Indicates whether this event has been successfully downloaded.
- **`bool WasTriggered { get; set; }`**  
  Indicates whether the event was triggered (as opposed to being a pre-trigger buffer).
- **`int NumberOfChannels { get; set; }`**  
  Number of channels included in the event.
- **`ulong NumberOfSamples { get; set; }`**  
  Total number of samples across all channels.
- **`ulong NumberOfBytes { get; set; }`**  
  Total size of raw data (in bytes) for the event.
- **`bool Faulted { get; set; }`**  
  Indicates whether the event completed with faults.
- **`int EventNumber { get; set; }`**  
  Sequential event number assigned by the DAS.
- **`void Add(IEventInfo newEvent)`**  
  Aggregates additional `IEventInfo` data into this aggregate (e.g., for multi-part events).

#### `IUARTDownload`
- **`uint BaudRate { get; }`**  
  Current UART baud rate (read-only, populated by DASFactory).
- **`uint DataBits { get; }`**  
  UART data bits configuration.
- **`StopBits StopBits { get; }`**  
  UART stop bits configuration (from `System.IO.Ports`).
- **`Parity Parity { get; }`**  
  UART parity configuration.
- **`Handshake FlowControl { get; }`**  
  UART flow control setting.
- **`UartDataFormat DataFormat { get; }`**  
  UART data format (e.g., ASCII, binary).
- **`IUARTDownloadRequest WhatUARTToDownload { get; set; }`**  
  Request specifying which UART event and data range to download.
- **`void SetWhatUARTToDownload(IUARTDownloadRequest request, bool bSetInDb = true)`**  
  Sets the UART download request; optionally persists to database.

#### `IUARTDownloadRequest`
- **`ushort EventNumber { get; set; }`**  
  Event number of the UART event to download.
- **`ulong TotalByteCount { get; set; }`**  
  Total number of bytes in the UART stream for the event.
- **`ulong TriggerByteCount { get; set; }`**  
  Byte offset where the trigger occurred in the UART stream.
- **`ulong FaultByteCount { get; set; }`**  
  Byte offset where the first fault occurred (if any).
- **`ulong StartTimestamp { get; set; }`**  
  Start time of the UART stream (in ticks or system time units).
- **`ulong EndTimestamp { get; set; }`**  
  End time of the UART stream.
- **`int BaudRate { get; set; }`**  
  Baud rate used during UART recording.

#### `IUARTEventInfo`
- **`ushort EventNumber { get; set; }`**  
  Event number of the UART event.
- **`bool DataPresent { get; set; }`**  
  Indicates whether UART data exists for this event.
- **`bool DataDownloaded { get; set; }`**  
  Indicates whether UART data has been successfully downloaded.
- **`ulong TotalByteCount { get; set; }`**  
  Total bytes of UART data.
- **`ulong TriggerByteCount { get; set; }`**  
  Byte offset of the trigger in the UART stream.
- **`ulong FaultByteCount { get; set; }`**  
  Byte offset of the first fault in the UART stream.
- **`ulong StartTimestamp { get; set; }`**  
  Start timestamp of the UART stream.
- **`ulong EndTimestamp { get; set; }`**  
  End timestamp of the UART stream.
- **`uint BaudRate { get; set; }`**  
  Baud rate during UART recording.

#### `IDownloadRequest`
- **`ushort EventNumber { get; set; }`**  
  Event number to download.
- **`byte DASChannelNumber { get; set; }`**  
  Channel number to download; `ALL_CHANNELS` (value not shown, assumed constant) for all.
- **`ulong StartSample { get; set; }`**  
  First sample index to include.
- **`ulong EndSample { get; set; }`**  
  Last sample index to include.
- **`ulong SamplesToSkip { get; set; }`**  
  Sub-sampling factor: `0` or `1` = no sub-sampling; `n > 1` = keep every *n*-th sample.  
  *Constraint:* `(EndSample - StartSample + 1)` must be divisible by `SamplesToSkip`.
- **`double StartRecordTimestampSec { get; set; }`**  
  Start time of recording in seconds (integer part).
- **`double TriggerTimestampSec { get; set; }`**  
  Trigger time in seconds (integer part).
- **`double StartRecordTimestampNanoSec { get; set; }`**  
  Fractional (nanosecond) part of start time.
- **`double TriggerTimestampNanoSec { get; set; }`**  
  Fractional (nanosecond) part of trigger time.
- **`bool PTPMasterSync { get; set; }`**  
  Indicates whether PTP (Precision Time Protocol) master synchronization was used.

#### `IDownload`
- **`IDownloadRequest WhatToDownload { get; set; }`**  
  Request specifying which event/channel/sample range to download.
- **`void SetWhatToDownload(IDownloadRequest request, bool bSetInDb = true)`**  
  Sets the download request; optionally persists to database.
- **`IDownloadReport EventInfo { get; set; }`**  
  Report containing all event metadata retrieved from the DAS.
- **`void SetEventInfo(IDownloadReport eventInfo, bool bSetInDb = true)`**  
  Sets the event metadata report; optionally persists to database.
- **`bool[] EventDownloadedStatus { get; set; }`**  
  Array (indexed by event number) indicating whether each event has been downloaded.
- **`void SetEventDownloadStatus(bool[] status, bool storeInDb = true)`**  
  Sets the downloaded status array.
- **`Guid[] EventGuids { get; set; }`**  
  Array (indexed by event number) of GUIDs for events.
- **`void SetEventGuids(Guid[] guids, bool storeInDb = true)`**  
  Sets the event GUIDs array.
- **`ushort[] FaultFlags { get; set; }`**  
  Array (indexed by event number) of fault flags.
- **`void SetEventFaultFlags(ushort[] flags, bool storeInDb = true)`**  
  Sets the fault flags array.
- **`uint[] ExtendedFaultFlags1 { get; set; }`**  
  Array of extended fault flags (1 of 4).
- **`uint[] ExtendedFaultFlags2 { get; set; }`**  
  Array of extended fault flags (2 of 4).
- **`uint[] ExtendedFaultFlags3 { get; set; }`**  
  Array of extended fault flags (3 of 4).
- **`uint[] ExtendedFaultFlags4 { get; set; }`**  
  Array of extended fault flags (4 of 4).
- **`void SetExtendedFaultFlags(uint[][] flags)`**  
  Populates all four `ExtendedFaultFlags*` arrays from a jagged array (first dimension = events, second = up to 4 flags per event).
- **`byte[] ArmAttempts { get; set; }`**  
  Array (indexed by event number) of arm attempt counts.
- **`void SetEventArmAttemps(byte[] armAttempts, bool storeInDb = true)`**  
  Sets the arm attempts array.

#### `IDownloadPathAware`
- **`string EventPath { get; set; }`**  
  Filesystem or logical path where event data is stored.

#### `DownloadExtendedFaultFunctions` (static helper class)
- **`static void SetExtendedFaultFlags(uint[][] flags, IDownload download)`**  
  Helper to populate `ExtendedFaultFlags1–4` arrays from a jagged array. If `flags` is null or empty, calls `ClearExtendedFaultFlags`.
- **`static void ClearExtendedFaultFlags(IDownload download)`**  
  Sets all `ExtendedFaultFlags*` arrays to `null`.

#### `IEventInfo`
- **`IDASModule[] Modules { get; set; }`**  
  Array of module info objects, indexed by `ModuleArrayIndex`.
- **`int EventNumber { get; set; }`**  
  Event number.
- **`Guid TestGUID { get; set; }`**  
  GUID of the event.
- **`ushort FaultFlags { get; set; }`**  
  Primary fault flags.
- **`ushort FaultFlagsEx { get; set; }`**  
  Extended fault flags (legacy, separate from `ExtendedFaultFlags*` arrays).
- **`byte ArmAttempts { get; set; }`**  
  Number of arm attempts.
- **`DateTime TestTime { get; set; }`**  
  Timestamp of the event.
- **`string TestID { get; set; }`**  
  Event ID string.
- **`string Description { get; set; }`**  
  Event description.
- **`bool HasBeenDownloaded { get; set; }`**  
  Download status.
- **`bool WasTriggered { get; set; }`**  
  Trigger status.
- **`void ClearFaults()`**  
  Clears fault flags (implementation-specific).

## 3. Invariants

- **Event indexing**: Arrays like `Events`, `UARTEvents`, `EventDownloadedStatus`, `EventGuids`, `FaultFlags`, `ExtendedFaultFlags*`, and `ArmAttempts` are indexed by event number. The exact mapping (0-based vs. 1-based) is not specified and must be inferred from usage.
- **Sample range constraint**: For `IDownloadRequest.SamplesToSkip`, `(EndSample - StartSample + 1)` must be divisible by `SamplesToSkip`. This is enforced by the caller.
- **UART event data consistency**: In `IUARTEventInfo` and `IUARTDownloadRequest`, `TriggerByteCount` and `FaultByteCount` are byte offsets within the UART stream (`TotalByteCount`), and `StartTimestamp` ≤ `EndTimestamp`.
- **Extended fault flags**: Exactly 4 extended fault flag arrays exist (`ExtendedFaultFlags1`–`4`), and `SetExtendedFaultFlags` expects each inner array to have at most 4 elements.
- **Download atomicity**: Downloads are performed one event at a time (per comments on `ExtendedFaultFlags*`), though metadata may be batched.

## 4. Dependencies

### Dependencies *of* this module:
- **`DTS.Common.Interface.DownloadEvent`** (via `IDownloadReport`): Defines `IEventInfo` and `IUARTEventInfo` interfaces (not included here, but referenced).
- **`DTS.Common.Enums`** (via `IUARTDownload`): Defines `UartDataFormat`, `StopBits`, `Parity`, `Handshake` enums.
- **`System.IO.Ports`** (via `IUARTDownload`): For `StopBits`, `Parity`, `Handshake`.
- **`DTS.Common.Interface.DASFactory.Config`** (via `IEventInfo`): Defines `IDASModule` interface (not included here).

### Dependencies *on* this module:
- DASFactory application logic (e.g., download workflows, UI, persistence).
- Any module implementing `IDownload`, `IDownloadRequest`, `IDownloadReport`, etc., to interact with DAS hardware or storage.

## 5. Gotchas

- **`SamplesToSkip` validation is caller responsibility**: The interface does not enforce divisibility of `(EndSample - StartSample + 1)` by `SamplesToSkip`; violation may cause runtime errors.
- **`EventNumber` indexing ambiguity**: Arrays are indexed by event number, but whether event numbers start at `0` or `1` is not specified. This is a common source of off-by-one bugs.
- **`FaultFlagsEx` vs. `ExtendedFaultFlags*`**: `IEventInfo.FaultFlagsEx` is a single `ushort`, while `IDownload` exposes four `uint[]` arrays (`ExtendedFaultFlags1–4`). These are likely related but not directly synchronized—caution is needed when updating one without the other.
- **`DownloadExtendedFaultFunctions` is static**: Its methods operate on an `IDownload` instance but do not modify the `IDownload` interface itself; callers must ensure the instance is valid before calling.
- **`bSetInDb` parameter semantics**: Many `Set*` methods include `bSetInDb`/`storeInDb` parameters. Their behavior (e.g., whether they overwrite or merge) is not documented.
- **UART and analog event separation**: `IDownloadReport` separates `Events` (analog/digital) and `UARTEvents` (serial), but there is no explicit link between them (e.g., same `EventNumber` may appear in both). This could lead to inconsistencies if not managed carefully.
- **Timestamp units**: `StartTimestamp`/`EndTimestamp` in UART interfaces are `ulong`, but their unit (e.g., ticks, nanoseconds, microseconds) is not specified. Similarly, `StartRecordTimestampSec` and `StartRecordTimestampNanoSec` are split—ensure correct reconstruction of full timestamps.
- **Missing `ALL_CHANNELS` constant**: The `DASChannelNumber` comment references `ALL_CHANNELS`, but its value is not defined in the provided source.

None identified beyond those above.