Scanning Service Reference for Dragon Guard Handheld WMS

namespace Handheld.Services.Scanning;

public interface IScanCaptureService
{
    // ── State ──────────────────────────────────────────────────────────────────
    ScanMode CurrentMode           { get; }
    bool     IsSessionActive       { get; }
    bool     CanUseRfid            { get; }
    bool     CanOperateWithoutRfid { get; }
    string   RfidHardwareStatus    { get; }

    // ── Events ─────────────────────────────────────────────────────────────────
    event EventHandler<CodeScannedEventArgs>?        CodeScanned;
    event EventHandler<TagObservedEventArgs>?         TagObserved;
    event EventHandler<ScanSessionEventArgs>?         SessionStarted;
    event EventHandler<ScanSessionEventArgs>?         SessionStopped;
    event EventHandler<TriggerStateChangedEventArgs>? TriggerStateChanged;
    event EventHandler<ScanErrorEventArgs>?           ErrorOccurred;

    // ── Policy ─────────────────────────────────────────────────────────────────
    void ApplyRfidPolicy(bool canUseRfid, bool canOperateWithoutRfid, string rfidHardwareStatus);

    // ── Lifecycle ──────────────────────────────────────────────────────────────
    Task InitializeAsync(CancellationToken ct = default);
    Task SetModeAsync(ScanMode mode, CancellationToken ct = default);
    Task StartSessionAsync(ScanSessionRequest request, CancellationToken ct = default);
    Task StopSessionAsync(CancellationToken ct = default);
    Task HandleKeyboardInputAsync(string? value, CancellationToken ct = default);
}

InitializeAsync()
    └─► registers broadcast receivers, enables UHF module

StartSessionAsync(ScanSessionRequest)
    ├── Mode = Barcode  →  IsSessionActive = true, fires SessionStarted
    ├── Mode = Rfid*, CanUseRfid = false, CanOperateWithoutRfid = true
    │       →  fires ErrorOccurred, falls back to Barcode
    ├── Mode = Rfid*, CanUseRfid = false, CanOperateWithoutRfid = false
    │       →  fires ErrorOccurred, session NOT started
    └── Mode = Rfid*  →  delegates to VendorRfidScanAdapter (Android only)

StopSessionAsync()
    ├── Mode = Barcode  →  IsSessionActive = false, fires SessionStopped
    └── Mode = Rfid*   →  delegates to VendorRfidScanAdapter, fires SessionStopped

HandleKeyboardInputAsync(string?)
    └── Only active when Mode = Barcode or Hybrid
        fires CodeScanned with ScanType = "BARCODE"

public sealed record ScanSessionRequest(ScanMode Mode, string? Reason = null);

public enum ScanMode
{
    Barcode      = 0,   // 2D / 1D barcode via keyboard-wedge
    RfidSingle   = 1,   // UHF RFID, stops after the first unique EPC
    RfidInventory = 2,  // UHF RFID, continuous reads until StopSessionAsync
    Hybrid       = 3    // Barcode via keyboard-wedge, RFID reads forwarded as tags
}

public sealed class ScanResult
{
    public Guid     Id              { get; init; }   // Unique per read; defaults to Guid.NewGuid()
    public string   ScanType        { get; init; }   // "BARCODE" | "RFID"
    public ScanMode Mode            { get; init; }   // Mode that produced this result
    public string   RawValue        { get; init; }   // Unmodified data from the hardware
    public string   NormalizedValue { get; init; }   // Trimmed / uppercased value
    public string?  Epc             { get; init; }   // Set for RFID reads; null for barcode
    public string?  Barcode         { get; init; }   // Set for barcode reads; null for RFID
    public string?  Symbology       { get; init; }   // e.g. "KEYBOARD_WEDGE", "com.rscja.scanner.uhf"
    public int?     Rssi            { get; init; }   // Signal strength (RFID only)
    public string?  Antenna         { get; init; }   // Antenna identifier (RFID only)
    public int      SeenCount       { get; init; }   // Observation count; defaults to 1
    public string?  DeviceId        { get; init; }   // Source device identifier
    public DateTime TimestampUtc    { get; init; }   // UTC capture time; defaults to DateTime.UtcNow
    public string?  MetadataJson    { get; init; }   // Arbitrary adapter-specific metadata

    // ── Computed display helpers ──────────────────────────────────────────────
    public string DisplayValue { get; }   // Epc if set, otherwise NormalizedValue
    public string DisplayRssi  { get; }   // Rssi.ToString() or "-" when null
}

public sealed class CodeScannedEventArgs : EventArgs
{
    public CodeScannedEventArgs(ScanResult result);
    public ScanResult Result { get; }
}

public sealed class TagObservedEventArgs : EventArgs
{
    public TagObservedEventArgs(ScanResult result);
    public ScanResult Result { get; }
}

public sealed class ScanSessionEventArgs : EventArgs
{
    public ScanSessionEventArgs(ScanMode mode, string message, bool isActive);
    public ScanMode Mode     { get; }   // Mode that started or stopped
    public string   Message  { get; }   // Human-readable status message
    public bool     IsActive { get; }   // true for SessionStarted, false for SessionStopped
}

public sealed class TriggerStateChangedEventArgs : EventArgs
{
    public TriggerStateChangedEventArgs(bool isPressed, ScanMode mode);
    public bool     IsPressed { get; }   // true = trigger pressed, false = released
    public ScanMode Mode      { get; }
}

public sealed class ScanErrorEventArgs : EventArgs
{
    public ScanErrorEventArgs(string message, Exception? exception = null);
    public string     Message   { get; }   // Human-readable description (Spanish on handheld)
    public Exception? Exception { get; }   // Inner exception if available; null for policy errors
}

public sealed class ScanCaptureService : IScanCaptureService, IDisposable
{
    public ScanCaptureService();

    // Additional methods not on the interface (called by the RFID context service)
    public void ConfigureDeviceProfile(RfidEffectiveDeviceProfileContextDto? profile);
    public void ConfigurePolicy(RfidEffectivePolicyContextDto? policy);

    public void Dispose();  // Unregisters broadcast receivers and keyboard-wedge events
}

public sealed class KeyboardWedgeScanAdapter
{
    // Returns null if value is null or whitespace
    public ScanResult? CreateResult(string? value, ScanMode mode);
}

// Android-only: Platforms/Android/Scanning/VendorRfidScanAdapter.cs
public sealed class VendorRfidScanAdapter : IDisposable
{
    public bool     IsSessionActive { get; }
    public ScanMode CurrentMode     { get; }
    public string?  LastError       { get; }

    public event EventHandler<TagObservedEventArgs>?         TagObserved;
    public event EventHandler<ScanSessionEventArgs>?         SessionStarted;
    public event EventHandler<ScanSessionEventArgs>?         SessionStopped;
    public event EventHandler<TriggerStateChangedEventArgs>? TriggerStateChanged;
    public event EventHandler<ScanErrorEventArgs>?           ErrorOccurred;

    public void ConfigureProfile(RfidEffectiveDeviceProfileContextDto? profile);
    public void ConfigurePolicy(RfidEffectivePolicyContextDto? policy);

    public Task InitializeAsync(CancellationToken ct = default);
    public Task SetModeAsync(ScanMode mode, CancellationToken ct = default);
    public async Task StartSessionAsync(ScanSessionRequest request, CancellationToken ct = default);
    public Task StopSessionAsync(CancellationToken ct = default);

    public void Dispose();
}