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

/// <summary>
///     Thin wire-layer abstraction over a single CIP tag. The driver holds one instance per
///     <c>(device, tag path)</c> pair; the default implementation delegates to
///     <see cref="LibplctagTagRuntime"/>. Tests swap in a fake via
///     <see cref="IAbCipTagFactory"/> so the driver's read / write / status-mapping logic can
///     be exercised without a running PLC or the native libplctag binary.
/// </summary>
public interface IAbCipTagRuntime : IDisposable
{
    /// <summary>Create the underlying native tag (equivalent to libplctag's <c>plc_tag_create</c>).</summary>
    Task InitializeAsync(CancellationToken cancellationToken);

    /// <summary>Issue a read; on completion the local buffer holds the current PLC value.</summary>
    Task ReadAsync(CancellationToken cancellationToken);

    /// <summary>Flush the local buffer to the PLC.</summary>
    Task WriteAsync(CancellationToken cancellationToken);

    /// <summary>
    ///     Raw libplctag status code — mapped to an OPC UA StatusCode via
    ///     <see cref="AbCipStatusMapper.MapLibplctagStatus"/>. Zero on success, negative on error.
    /// </summary>
    int GetStatus();

    /// <summary>
    ///     Decode the local buffer into a boxed .NET value per the tag's configured type.
    ///     <paramref name="bitIndex"/> is non-null only for BOOL-within-DINT tags captured in
    ///     the <c>.N</c> syntax at parse time.
    /// </summary>
    object? DecodeValue(AbCipDataType type, int? bitIndex);

    /// <summary>
    ///     Decode a value at an arbitrary byte offset in the local buffer. Task #194 —
    ///     whole-UDT reads perform one <see cref="ReadAsync"/> on the parent UDT tag then
    ///     call this per declared member with its computed offset, avoiding one libplctag
    ///     round-trip per member. Implementations that do not support offset-aware decoding
    ///     may fall back to <see cref="DecodeValue"/> when <paramref name="offset"/> is zero;
    ///     offsets greater than zero against an unsupporting runtime should return <c>null</c>
    ///     so the planner can skip grouping.
    /// </summary>
    object? DecodeValueAt(AbCipDataType type, int offset, int? bitIndex);

    /// <summary>
    ///     Encode <paramref name="value"/> into the local buffer per the tag's type. Callers
    ///     pair this with <see cref="WriteAsync"/>.
    /// </summary>
    void EncodeValue(AbCipDataType type, int? bitIndex, object? value);
}

/// <summary>
///     Factory for per-tag runtime handles. Instantiated once per driver, consumed per
///     <c>(device, tag path)</c> pair at the first read/write.
/// </summary>
public interface IAbCipTagFactory
{
    IAbCipTagRuntime Create(AbCipTagCreateParams createParams);
}

/// <summary>Everything libplctag needs to materialise a tag handle.</summary>
/// <param name="Gateway">Gateway IP / hostname parsed from <see cref="AbCipHostAddress.Gateway"/>.</param>
/// <param name="Port">EtherNet/IP TCP port — default 44818.</param>
/// <param name="CipPath">CIP route path, e.g. <c>1,0</c>. Empty for Micro800.</param>
/// <param name="LibplctagPlcAttribute">libplctag <c>plc=...</c> attribute, per family profile.</param>
/// <param name="TagName">Logix symbolic tag name as emitted by <see cref="AbCipTagPath.ToLibplctagName"/>.</param>
/// <param name="Timeout">libplctag operation timeout (applies to Initialize / Read / Write).</param>
/// <param name="StringMaxCapacity">Optional Logix STRINGnn DATA-array capacity (e.g. 20 / 40 / 80
///     for <c>STRING_20</c> / <c>STRING_40</c> / <c>STRING_80</c> UDTs). Threads through libplctag's
///     <c>str_max_capacity</c> attribute. <c>null</c> keeps libplctag's default 82-byte STRING
///     behaviour for back-compat.</param>
/// <param name="ElementCount">Optional libplctag <c>ElementCount</c> override — set to <c>N</c>
///     to issue a Rockwell array read covering <c>N</c> consecutive elements starting at the
///     subscripted index in <see cref="TagName"/>. Drives PR abcip-1.3 array-slice support;
///     <c>null</c> leaves libplctag's default scalar-element behaviour for back-compat.</param>
/// <param name="ConnectionSize">PR abcip-3.1 — CIP Forward Open buffer size in bytes. Threads
///     through to libplctag's <c>connection_size</c> attribute. The driver always supplies a
///     value here — either the per-device <see cref="AbCipDeviceOptions.ConnectionSize"/>
///     override or the family profile's <see cref="PlcFamilies.AbCipPlcFamilyProfile.DefaultConnectionSize"/>.
///     Bigger packets fit more tags per RTT (higher throughput); smaller packets stay compatible
///     with legacy firmware (v19-and-earlier ControlLogix caps at 504, Micro800 hard-caps at
///     488).</param>
/// <param name="AddressingMode">PR abcip-3.2 — concrete addressing mode the runtime should
///     activate for this tag handle. Always either <see cref="AddressingMode.Symbolic"/> or
///     <see cref="AddressingMode.Logical"/> at this layer (the driver resolves <c>Auto</c> +
///     family-incompatibility before building the create-params). Symbolic is the libplctag
///     default and needs no extra attribute. Logical adds the libplctag <c>use_connected_msg=1</c>
///     attribute + (when an instance ID is known via <see cref="LogicalInstanceId"/>) reaches
///     into <c>NativeTagWrapper.SetAttributeString</c> by reflection because the .NET wrapper
///     does not expose a public knob for instance-ID addressing.</param>
/// <param name="LogicalInstanceId">PR abcip-3.2 — Symbol Object instance ID the controller
///     assigned to this tag, populated by the driver after a one-time <c>@tags</c> walk for
///     Logical-mode devices. <c>null</c> for Symbolic mode + for the very first read on a
///     Logical device when the symbol-table walk has not yet completed; the runtime falls back
///     to Symbolic addressing in either case so the read still completes.</param>
public sealed record AbCipTagCreateParams(
    string Gateway,
    int Port,
    string CipPath,
    string LibplctagPlcAttribute,
    string TagName,
    TimeSpan Timeout,
    int? StringMaxCapacity = null,
    int? ElementCount = null,
    int ConnectionSize = 4002,
    AddressingMode AddressingMode = AddressingMode.Symbolic,
    uint? LogicalInstanceId = null);