lmxopcua/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.AbCip/AbCipTemplateCache.cs

using System.Collections.Concurrent;

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

/// <summary>
///     Cache of UDT shape descriptors keyed by <c>(deviceHostAddress, templateInstanceId)</c>.
///     Populated on demand during discovery + whole-UDT reads; flushed via
///     <see cref="AbCipDriver.FlushOptionalCachesAsync"/> and on device
///     <c>ReinitializeAsync</c>.
/// </summary>
/// <remarks>
///     Templates are decoded by <see cref="CipTemplateObjectDecoder"/> (CIP Template Object
///     class 0x6C, <c>GetAttributeList</c> + <c>Read Template</c>); the live reader is
///     <see cref="LibplctagTemplateReader"/>, and <see cref="AbCipDriver.FetchUdtShapeAsync"/>
///     populates this cache on first fetch.
/// </remarks>
public sealed class AbCipTemplateCache
{
    private readonly ConcurrentDictionary<(string device, uint instanceId), AbCipUdtShape> _shapes = new();

    /// <summary>
    ///     Retrieve a cached UDT shape, or <c>null</c> if not yet read.
    /// </summary>
    /// <param name="deviceHostAddress">The device host address and port.</param>
    /// <param name="templateInstanceId">The template instance ID.</param>
    /// <returns>The cached UDT shape, or <c>null</c> if not yet read.</returns>
    public AbCipUdtShape? TryGet(string deviceHostAddress, uint templateInstanceId) =>
        _shapes.TryGetValue((deviceHostAddress, templateInstanceId), out var shape) ? shape : null;

    /// <summary>Store a freshly-decoded UDT shape.</summary>
    /// <param name="deviceHostAddress">The device host address and port.</param>
    /// <param name="templateInstanceId">The template instance ID.</param>
    /// <param name="shape">The UDT shape to cache.</param>
    public void Put(string deviceHostAddress, uint templateInstanceId, AbCipUdtShape shape) =>
        _shapes[(deviceHostAddress, templateInstanceId)] = shape;

    /// <summary>Drop every cached shape — called on <see cref="AbCipDriver.FlushOptionalCachesAsync"/>.</summary>
    public void Clear() => _shapes.Clear();

    /// <summary>Count of cached shapes — exposed for diagnostics + tests.</summary>
    public int Count => _shapes.Count;
}

/// <summary>
///     Decoded shape of one Logix UDT — member list + each member's offset + type. Populated
///     by <see cref="CipTemplateObjectDecoder.Decode"/> from a Template Object response buffer
///     read via <see cref="LibplctagTemplateReader"/>.
/// </summary>
/// <param name="TypeName">UDT name as reported by the Template Object.</param>
/// <param name="TotalSize">Bytes the UDT occupies in a whole-UDT read buffer.</param>
/// <param name="Members">Ordered list of members, each with its byte offset + type.</param>
public sealed record AbCipUdtShape(
    string TypeName,
    int TotalSize,
    IReadOnlyList<AbCipUdtMember> Members);

/// <summary>One member of a Logix UDT.</summary>
/// <param name="Name">Member name as reported by the Template Object.</param>
/// <param name="Offset">Byte offset of the member from the struct start.</param>
/// <param name="DataType">Decoded member data type (<see cref="AbCipDataType.Structure"/> for a nested UDT).</param>
/// <param name="ArrayLength">Element count (1 for a scalar member).</param>
/// <param name="NestedTemplateId">For a nested-struct member, the nested UDT's CIP template instance id
///     (low 12 bits of the member info, same encoding as the Symbol Object) so the nested shape can be
///     fetched via <see cref="AbCipDriver.FetchUdtShapeAsync"/>; <c>null</c> for a scalar member.</param>
public sealed record AbCipUdtMember(
    string Name,
    int Offset,
    AbCipDataType DataType,
    int ArrayLength,
    uint? NestedTemplateId = null);