lmxopcua/src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/ITwinCATClient.cs

namespace ZB.MOM.WW.OtOpcUa.Driver.TwinCAT;

/// <summary>
///     Wire-layer abstraction over one connection to a TwinCAT AMS target. One instance per
///     <see cref="TwinCATAmsAddress"/>; reused across reads / writes / probes for the device.
///     Tests swap in a fake via <see cref="ITwinCATClientFactory"/>.
/// </summary>
/// <remarks>
///     Unlike libplctag-backed drivers where one native handle exists per tag, TwinCAT's
///     AdsClient is one connection per target with symbolic reads / writes issued against it.
///     The abstraction reflects that — single <see cref="ConnectAsync"/>, many
///     <see cref="ReadValueAsync"/> / <see cref="WriteValueAsync"/> calls.
/// </remarks>
public interface ITwinCATClient : IDisposable
{
    /// <summary>Establish the AMS connection. Idempotent — subsequent calls are no-ops when already connected.</summary>
    Task ConnectAsync(TwinCATAmsAddress address, TimeSpan timeout, CancellationToken cancellationToken);

    /// <summary>True when the AMS router + target both accept commands.</summary>
    bool IsConnected { get; }

    /// <summary>
    ///     Read a symbolic value. Returns a boxed .NET value matching the requested
    ///     <paramref name="type"/>, or <c>null</c> when the read produced no data; the
    ///     <c>status</c> tuple member carries the mapped OPC UA status (0 = Good). When
    ///     <paramref name="arrayDimensions"/> is non-null + non-empty, the symbol is treated
    ///     as a whole-array read and the boxed value is a flat 1-D CLR
    ///     <see cref="Array"/> sized to <c>product(arrayDimensions)</c>.
    /// </summary>
    Task<(object? value, uint status)> ReadValueAsync(
        string symbolPath,
        TwinCATDataType type,
        int? bitIndex,
        int[]? arrayDimensions,
        CancellationToken cancellationToken);

    /// <summary>
    ///     Write a symbolic value. Returns the mapped OPC UA status for the operation
    ///     (0 = Good, non-zero = error mapped via <see cref="TwinCATStatusMapper"/>).
    ///     <paramref name="arrayDimensions"/> mirrors <see cref="ReadValueAsync"/>; PR-1.4
    ///     ships read-only whole-array support so writers may surface <c>BadNotSupported</c>.
    /// </summary>
    Task<uint> WriteValueAsync(
        string symbolPath,
        TwinCATDataType type,
        int? bitIndex,
        int[]? arrayDimensions,
        object? value,
        CancellationToken cancellationToken);

    /// <summary>
    ///     Cheap health probe — returns <c>true</c> when the target's AMS state is reachable.
    ///     Used by <see cref="Core.Abstractions.IHostConnectivityProbe"/>'s probe loop.
    /// </summary>
    Task<bool> ProbeAsync(CancellationToken cancellationToken);

    /// <summary>
    ///     Register a cyclic / on-change ADS notification for a symbol. Returns a handle whose
    ///     <see cref="IDisposable.Dispose"/> tears the notification down. Callback fires on the
    ///     thread libplctag / AdsClient uses for notifications — consumers should marshal to
    ///     their own scheduler before doing work of any size.
    /// </summary>
    /// <param name="symbolPath">ADS symbol path (e.g. <c>MAIN.bStart</c>).</param>
    /// <param name="type">Declared type; drives the native layout + callback value boxing.</param>
    /// <param name="bitIndex">For BOOL-within-word tags — the bit to extract from the parent word.</param>
    /// <param name="cycleTime">Minimum interval between change notifications (native-floor depends on target).</param>
    /// <param name="onChange">Invoked with <c>(symbolPath, boxedValue)</c> per notification.</param>
    /// <param name="cancellationToken">Cancels the initial registration; does not tear down an established notification.</param>
    Task<ITwinCATNotificationHandle> AddNotificationAsync(
        string symbolPath,
        TwinCATDataType type,
        int? bitIndex,
        TimeSpan cycleTime,
        Action<string, object?> onChange,
        CancellationToken cancellationToken);

    /// <summary>
    ///     Walk the target's symbol table via the TwinCAT <c>SymbolLoaderFactory</c> (flat mode).
    ///     Yields each top-level symbol the PLC exposes — global variables, program-scope locals,
    ///     function-block instance fields. Filters for our atomic type surface; structured /
    ///     UDT / function-block typed symbols surface with <c>DataType = null</c> so callers can
    ///     decide whether to drill in via their own walker.
    /// </summary>
    IAsyncEnumerable<TwinCATDiscoveredSymbol> BrowseSymbolsAsync(CancellationToken cancellationToken);
}

/// <summary>Opaque handle for a registered ADS notification. <see cref="IDisposable.Dispose"/> tears it down.</summary>
public interface ITwinCATNotificationHandle : IDisposable { }

/// <summary>
///     One symbol yielded by <see cref="ITwinCATClient.BrowseSymbolsAsync"/> — full instance
///     path + detected <see cref="TwinCATDataType"/> + read-only flag.
/// </summary>
/// <param name="InstancePath">Full dotted symbol path (e.g. <c>MAIN.bStart</c>, <c>GVL.Counter</c>).</param>
/// <param name="DataType">Mapped <see cref="TwinCATDataType"/>; <c>null</c> when the symbol's type
///     doesn't map onto our supported atomic surface (UDTs, pointers, function blocks).</param>
/// <param name="ReadOnly"><c>true</c> when the symbol's AccessRights flag forbids writes.</param>
public sealed record TwinCATDiscoveredSymbol(
    string InstancePath,
    TwinCATDataType? DataType,
    bool ReadOnly);

/// <summary>Factory for <see cref="ITwinCATClient"/>s. One client per device.</summary>
public interface ITwinCATClientFactory
{
    ITwinCATClient Create();
}