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

---
source_files:
  - DataPRO/DbAPI/Sensors/ISensors.cs
generated_at: "2026-04-16T04:25:20.635650+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "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*