DP44/enriched-qwen3-coder-next/DataPRO/DbAPI/Sensors.md

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
DataPRO/DbAPI/Sensors/ISensors.cs	2026-04-16T04:25:20.635650+00:00	Qwen/Qwen3-Coder-Next-FP8	1	c1fec90650918e9b

Documentation: ISensors Interface (DbAPI.Sensors.ISensors)

---

1. Purpose

The ISensors interface defines the contract for sensor-related data access operations in the DbAPI.Sensors module. It provides a unified set of methods to query, insert, update, and delete various sensor types—including analog sensors, digital inputs/outputs, squibs, UARTs, CAN, thermocouples, and input/output streams—as well as associated diagnostic runs, calibrations, and usage metadata. This interface abstracts database interactions for sensor data, enabling consistent CRUD operations across the system while enforcing user context (IUserDbRecord) and connection context (IConnectionDetails) for security and multi-tenancy.

---

2. Public Interface

All methods return ulong, where 0 (ERROR_SUCCESS) indicates success and non-zero values indicate error codes.

Query Methods

Method	Signature	Description
SensorsAnalogDiagnosticsGet	ulong SensorsAnalogDiagnosticsGet(IUserDbRecord user, IConnectionDetails connection, long? Id, long? diagnosticRunId, int? sensorId, string sensorSerialNumber, out IDiagnosticEntry[] records)	Retrieves analog diagnostic records matching optional filters (Id, diagnosticRunId, sensorId, sensorSerialNumber). Returns all matching IDiagnosticEntry records.
SensorsAnalogDiagnosticRunGet	ulong SensorsAnalogDiagnosticRunGet(IUserDbRecord user, IConnectionDetails connection, long? Id, int? testId, string testName, out IDiagnosticRun[] records)	Retrieves diagnostic run records matching optional filters (Id, testId, testName).
SensorsInputStreamGet	ulong SensorsInputStreamGet(IUserDbRecord user, IConnectionDetails connection, int? Id, string SerialNumber, out IStreamInputRecord[] records)	Retrieves input stream records matching Id or SerialNumber.
SensorsOutputStreamGet	ulong SensorsOutputStreamGet(IUserDbRecord user, IConnectionDetails connection, int? Id, string SerialNumber, out IStreamOutputRecord[] records)	Retrieves output stream records matching Id or SerialNumber.
SensorsThermocouplerGet	ulong SensorsThermocouplerGet(IUserDbRecord user, IConnectionDetails connection, int clientDbVersion, int? Id, string SerialNumber, out IThermocouplerRecord[] records)	Retrieves thermocouple records matching Id or SerialNumber. Includes clientDbVersion parameter—likely for schema/version compatibility.
SensorsUARTGet	ulong SensorsUARTGet(IUserDbRecord user, IConnectionDetails connection, int? Id, string SerialNumber, out IUARTRecord[] records)	Retrieves UART configuration records matching Id or SerialNumber.
SensorsCanGet	ulong SensorsCanGet(IUserDbRecord user, IConnectionDetails connection, int? Id, string SerialNumber, out ICANRecord[] records)	Retrieves CAN configuration records matching Id or SerialNumber.
SensorsDigitalOutGet	ulong SensorsDigitalOutGet(IUserDbRecord user, IConnectionDetails connection, int? Id, string serialNumber, out IDigitalOutDbRecord[] records)	Retrieves digital output settings matching Id or serialNumber.
SensorsDigitalInGet	ulong SensorsDigitalInGet(IUserDbRecord user, IConnectionDetails connection, int? id, string serialNumber, string eId, out IDigitalInDbRecord[] records)	Retrieves digital input settings matching id, serialNumber, or eId (electronic ID).
SensorsSquibGet	ulong SensorsSquibGet(IUserDbRecord user, IConnectionDetails connection, int? Id, string serialNumber, string eId, out ISquibDbRecord[] records)	Retrieves squib settings matching Id, serialNumber, or eId.
SensorsAnalogBridgeResistanceGet	ulong SensorsAnalogBridgeResistanceGet(IUserDbRecord user, IConnectionDetails connection, string serialNumber, out double bridgeResistance)	Retrieves the bridge resistance (in ohms) for the analog sensor identified by serialNumber.
SensorCalibrationsGet	ulong SensorCalibrationsGet(IUserDbRecord user, IConnectionDetails connection, int? sensorId, string serialNumber, out ISensorCalDbRecord[] calibrations)	Retrieves calibration records matching sensorId or serialNumber.
SensorsAnalogGet	ulong SensorsAnalogGet(IUserDbRecord user, IConnectionDetails connection, int? sensorId, string serialNumber, string eId, out IAnalogDbRecord[] sensors)	Retrieves analog sensor records matching sensorId, serialNumber, or eId (DALLAS/TEDS ID).
SensorsGet	ulong SensorsGet(IUserDbRecord user, IConnectionDetails connection, string serialNumber, out ISensorDbRecord[] sensors)	Retrieves generic sensor records (base type ISensorDbRecord) matching serialNumber.

Insert/Update Methods

Method	Signature	Description
SensorsAnalogDiagnosticUpdateInsert	ulong SensorsAnalogDiagnosticUpdateInsert(IUserDbRecord user, IConnectionDetails connection, ref IDiagnosticEntry entry)	Inserts or updates a single IDiagnosticEntry. Note: Parameter is ref, implying the record may be mutated (e.g., to populate Id on insert).
SensorsAnalogDiagnosticRunUpdateInsert	ulong SensorsAnalogDiagnosticRunUpdateInsert(IUserDbRecord user, IConnectionDetails connection, ref IDiagnosticRun run)	Inserts or updates a diagnostic run (IDiagnosticRun). ref parameter allows mutation of Id on insert.
SensorsInputStreamUpdateInsert	ulong SensorsInputStreamUpdateInsert(IUserDbRecord user, IConnectionDetails connection, ref IStreamInputRecord record)	Inserts or updates an input stream record. ref parameter allows mutation of Id on insert.
SensorsOutputStreamUpdateInsert	ulong SensorsOutputStreamUpdateInsert(IUserDbRecord user, IConnectionDetails connection, ref IStreamOutputRecord record)	Inserts or updates an output stream record. ref parameter allows mutation of Id on insert.
SensorsUARTUpdateInsert	ulong SensorsUARTUpdateInsert(IUserDbRecord user, IConnectionDetails connection, ref IUARTRecord record)	Inserts or updates a UART record. ref parameter allows mutation of Id on insert.
SensorsCanUpdateInsert	ulong SensorsCanUpdateInsert(IUserDbRecord user, IConnectionDetails connection, ref ICANRecord record)	Inserts or updates a CAN record. ref parameter allows mutation of Id on insert.
SensorsDigitalOutUpdateInsert	ulong SensorsDigitalOutUpdateInsert(IUserDbRecord user, IConnectionDetails connection, IDigitalOutDbRecord record)	Inserts or updates a digital output record. Note: Parameter is not ref; record is passed by value. Mutation of Id on insert is not possible unless IDigitalOutDbRecord is a mutable reference type.
SensorsDigitalInUpdateInsert	ulong SensorsDigitalInUpdateInsert(IUserDbRecord user, IConnectionDetails connection, IDigitalInDbRecord record)	Inserts or updates a digital input record. Not ref—same caveats as SensorsDigitalOutUpdateInsert.
SensorsSquibUpdateInsert	ulong SensorsSquibUpdateInsert(IUserDbRecord user, IConnectionDetails connection, ISquibDbRecord record)	Inserts or updates a squib record. Not ref—same caveats.
SensorsAnalogUpdateInsert	ulong SensorsAnalogUpdateInsert(IUserDbRecord user, IConnectionDetails connection, IAnalogDbRecord record)	Commits an analog sensor record. Not ref—same caveats.
SensorCalibrationsInsert	ulong SensorCalibrationsInsert(IUserDbRecord user, IConnectionDetails connection, ISensorCalDbRecord cal, int sensorType, bool setCalibrationId)	Inserts a calibration record. setCalibrationId likely controls whether the inserted record’s Id is populated.

Delete Methods

Method	Signature	Description
SensorsDeleteAll	ulong SensorsDeleteAll(IUserDbRecord user, IConnectionDetails connection)	Deletes all sensor records in the database.
SensorCalibrationsDelete	ulong SensorCalibrationsDelete(IUserDbRecord user, IConnectionDetails connection, string sensorSerialNumber, DateTime? calibrationDate, DateTime? modifyDate)	Deletes calibration records matching optional filters. null parameters act as wildcards.
SensorsDelete	ulong SensorsDelete(IUserDbRecord user, IConnectionDetails connection, int sensorId, int sensorType)	Deletes sensors matching sensorId and sensorType. sensorType values: 0 = analog, 1 = digital in, 2 = digital out, 3 = squib, 4 = UART.

Usage Count Update Methods

Method	Signature	Description
UpdateAssemblySensorUsageCount	ulong UpdateAssemblySensorUsageCount(IUserDbRecord user, IConnectionDetails connection, string assemblyName, int newUsageCount)	Updates the usage count for a named assembly.
UpdateSensorUsageCount	ulong UpdateSensorUsageCount(IUserDbRecord user, IConnectionDetails connection, ISensorData sd)	Updates the total usage count for a sensor (type ISensorData).
UpdateSensorCalibrationUsageCount	ulong UpdateSensorCalibrationUsageCount(IUserDbRecord user, IConnectionDetails connection, int sensorId, int sensorCalibrationId, int newUsageCount)	Updates the usage count for a specific calibration of a sensor.

---

3. Invariants

• User & Connection Context: All methods require IUserDbRecord user and IConnectionDetails connection. These are mandatory and must be non-null (enforced by caller).
• Return Value Semantics: All methods return ulong; 0 means success. Non-zero values are error codes (specific codes not defined in this interface).
• Wildcard Filtering: For all Get methods, null parameters act as wildcards (match all). For SensorsUARTGet, null or empty SerialNumber matches all.
• Insert Behavior: For methods with ref parameters (e.g., SensorsAnalogDiagnosticUpdateInsert, SensorsInputStreamUpdateInsert), the record passed in may be mutated to include the newly assigned database Id upon successful insert.
• Sensor Type Constants: SensorsDelete uses integer sensor types defined as:
  0 = analog, 1 = digital in, 2 = digital out, 3 = squib, 4 = UART.
  (Note: These are documented in the XML comment for SensorsDelete, but no constants are defined in this interface.)
• Calibration Insert Specifics: SensorCalibrationsInsert requires sensorType and setCalibrationId—the latter likely controls whether the inserted record’s Id is populated.

---

4. Dependencies

Imports / Dependencies of ISensors:

• DbAPI.Connections → IConnectionDetails
• DTS.Common.Interface.Database → IUserDbRecord
• DTS.Common.Interface.Sensors → ISensorDbRecord, ISensorData, ISensorCalDbRecord, IAnalogDbRecord, IDigitalInDbRecord, IDigitalOutDbRecord, ISquibDbRecord, IUARTRecord, ICANRecord
• DTS.Common.Interface.Sensors.AnalogDiagnostics → IDiagnosticEntry, IDiagnosticRun
• System → DateTime, ulong

Implemented By:

• Not visible in this file. Presumably implemented by a concrete class (e.g., Sensors in the same namespace or a derived layer like DbAPI.Sensors.Sensors).

Used By:

• Any module requiring sensor data access, likely including:
  • UI layers (e.g., WPF/WinForms)
  • Business logic layers (e.g., service classes)
  • Import/export utilities
  • Diagnostic or test execution modules

---

5. Gotchas

• Inconsistent ref usage:
  • Methods like SensorsAnalogDiagnosticUpdateInsert, SensorsInputStreamUpdateInsert, etc., use ref for the record parameter, implying the record may be mutated (e.g., to populate Id on insert).
  • Others (e.g., SensorsDigitalOutUpdateInsert, SensorsAnalogUpdateInsert, SensorCalibrationsInsert) pass records by value (no ref). If IDigitalOutDbRecord, IAnalogDbRecord, etc., are mutable reference types, the implementation may still mutate them—but this is not guaranteed by the interface and may lead to confusion or bugs if callers expect Id to be updated.
• clientDbVersion in SensorsThermocouplerGet:
  The int clientDbVersion parameter is present but not documented beyond its presence. Its purpose (e.g., schema versioning, backward compatibility) is unclear from this interface alone.
• SensorsGet vs SensorsAnalogGet:
  SensorsGet returns ISensorDbRecord[], while SensorsAnalogGet returns IAnalogDbRecord[]. The relationship between these types is not defined here—ISensorDbRecord may be a base interface, but callers must be cautious about casting.
• SensorsDeleteAll is dangerous:
  No filtering is possible—this deletes all sensors. Use with extreme caution.
• SensorsAnalogBridgeResistanceGet returns double:
  No unit is specified in the interface, though the XML comment says “bridge resistance of sensor.” Assumed to be ohms, but not guaranteed.
• sensorType is magic-numbered:
  Sensor types are documented inline (0 = analog, etc.), but no enum or constants are defined in this interface. Callers must hardcode or define their own constants.
• setCalibrationId in SensorCalibrationsInsert:
  Purpose is unclear from signature alone—likely controls whether the inserted record’s Id is set, but behavior is not documented.
• No async methods:
  All methods are synchronous. In modern codebases, this may indicate legacy design or require wrapping for async compatibility.

None identified from source alone for other potential gotchas (e.g., concurrency, transaction semantics), as those are not exposed in this interface.

---

End of Documentation