DP44/enriched-qwen3-coder-next/Common/DTS.Common.SerializationPlus.md

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
Common/DTS.Common.SerializationPlus/EventInfoAggregate.cs	2026-04-16T14:13:19.550350+00:00	zai-org/GLM-5-FP8	1	342395eec4a038a1

Documentation: EventInfoAggregate

1. Purpose

EventInfoAggregate is an aggregate data structure that consolidates event information from multiple Data Acquisition System (DAS) devices/modules into a single unified view. It implements IEventInfoAggregate and serves as a central repository for event metadata during download operations, tracking properties like event identification, duration, channel counts, sample counts, and fault status across multiple hardware units that recorded the same event.

---

2. Public Interface

Properties

Property	Type	Description
EventId	string	Identifier for the test/event.
EventDescription	string	Human-readable description of the event.
DurationSeconds	double	Total event duration in seconds (PreTriggerSeconds + PostTriggerSeconds).
GUID	string	Globally unique identifier for the test.
HasBeenDownloaded	bool	Indicates whether the event data has been downloaded.
WasTriggered	bool	Indicates whether the event was triggered.
NumberOfChannels	int	Total number of channels across all modules.
NumberOfSamples	ulong	Number of samples per channel.
NumberOfBytes	ulong	Calculated total bytes: NumberOfSamples * NumberOfChannels * 2.
Faulted	bool	Indicates if any module reported a fault condition.
EventNumber	int	Sequential event number identifier.

Methods

EventInfoAggregate(DownloadReport.EventInfo newEvent)

Constructor that initializes the aggregate from a single DownloadReport.EventInfo. Populates all properties and adds the first DAS module to the internal _eventIndices dictionary.

void Add(IEventInfo newEvent)

Merges additional event information from another module into this aggregate. Accumulates channel counts, recalculates NumberOfBytes, updates Faulted status, and adds the DAS to _eventIndices. Logs warnings for mismatched fields but does not throw exceptions.

Slice.Control.Event GetEvent()

Returns a lazily-instantiated Slice.Control.Event object, creating it if necessary.

Slice.Control.Event GetEvent(bool bClear)

Returns the Slice.Control.Event object. If bClear is true, resets the cached _event to null before returning (forcing recreation on next call).

int GetEventIndex(IDASCommunication idas)

Returns the event index for a specific DAS device. Returns -1 and logs an error if the DAS is not found in _eventIndices.

List<IDASCommunication> GetDasList()

Returns a lazily-instantiated list of all DAS devices associated with this event. The list is cached after first creation.

---

3. Invariants

• Empty Modules Handling: When Modules collection is empty, DurationSeconds and NumberOfSamples are set to 0 rather than throwing an exception.
• Byte Calculation: NumberOfBytes is always calculated as 2 * NumberOfChannels * NumberOfSamples (assumes 2 bytes per sample per channel).
• Fault Detection: An event is considered faulted if FaultFlags != 0 OR FaultFlagsEx != 0 on any constituent module.
• Event Index Dictionary: _eventIndices is always initialized (readonly field) and maps IDASCommunication instances to their event numbers.
• Minimum Value Resolution: When merging events with mismatched DurationSeconds or NumberOfSamples, the minimum value is retained.

---

4. Dependencies

This module depends on:

• System, System.Collections.Generic, System.Linq (BCL)
• DTS.Common.Interface.DASFactory — provides IDASCommunication
• DTS.Common.Interface.DASFactory.Download — provides DownloadReport.EventInfo, IEventInfo, DASModule
• DTS.Common.Utilities.Logging — provides APILogger
• DTS.DASLib.Service — namespace import (specific usage unclear from source)
• Slice.Control.Event — external type instantiated in GetEvent() (assembly/source not specified in imports)

What depends on this module:

• Not determinable from source alone. The IEventInfoAggregate interface suggests consumers depend on the interface rather than concrete implementation.

---

5. Gotchas

1. Silent Mismatch Handling: The Add() method logs warnings for mismatched TestID, Description, GUID, HasBeenDownloaded, WasTriggered, and EventNumber values but continues processing. Callers are not notified of data integrity issues beyond log entries.

2. Minimum Value Strategy: When DurationSeconds or NumberOfSamples differ between modules being aggregated, the code silently takes the minimum value. This may result in data loss if larger values are correct.

3. Empty Modules Edge Case: The constructor guards against empty Modules collections (added per case 15575), but the Add() method does not — it accesses newEvent.Modules[0] without null/empty checks, which will throw ArgumentOutOfRangeException if Modules is empty.

4. Lazy Initialization Side Effects: GetDasList() and GetEvent() cache their results. The _das list is not invalidated when Add() is called, potentially returning stale data if GetDasList() was called before all Add() operations completed.

5. Index Assignment for Duplicates: _eventIndices uses indexer assignment (_eventIndices[...] = value) rather than .Add() to silently overwrite duplicate keys. This was added per case 44357 but means duplicate DAS entries are not detected or logged.

6. Error Return Convention: GetEventIndex() returns -1 for missing keys rather than throwing an exception. Callers must check for this sentinel value.