namespace ZB.MOM.WW.OtOpcUa.Driver.S7.SymbolImport;

/// <summary>
///     PR-S7-D2 — one named member of an <see cref="S7UdtDefinition"/>. Mirrors the
///     STEP 7 / TIA Portal UDT layout: each member sits at a fixed byte offset relative
///     to the UDT's base, has a primitive S7 type (or another UDT for nested STRUCTs),
///     and may be a 1-D array.
/// </summary>
/// <param name="Name">Member name; concatenated with the parent tag's name via dot-separator at fan-out.</param>
/// <param name="Offset">Byte offset within the parent UDT. Must be ascending and non-overlapping across the member list.</param>
/// <param name="DataType">Primitive S7 type. Ignored when <paramref name="UdtName"/> is set (nested-UDT case).</param>
/// <param name="ArrayDim">Optional 1-D array length. <c>null</c> / <c>1</c> = scalar; <c>&gt; 1</c> emits indexed sub-tags <c>Member[0]</c>, <c>Member[1]</c>, ...</param>
/// <param name="UdtName">When set, this member is itself a UDT — the fan-out recurses into the named UDT's layout. Mutually exclusive with the primitive interpretation of <paramref name="DataType"/>.</param>
public sealed record S7UdtMember(
    string Name,
    int Offset,
    S7DataType DataType,
    int? ArrayDim = null,
    string? UdtName = null);

/// <summary>
///     PR-S7-D2 — declarative description of a Siemens UDT (User-Defined Type) /
///     STRUCT layout. Tags whose <see cref="S7TagDefinition.UdtName"/> matches
///     <see cref="Name"/> get fanned-out into one scalar leaf tag per recursive
///     member at <see cref="S7Driver.InitializeAsync"/> time, so the rest of the
///     read/write/subscribe pipeline never has to know about UDTs.
/// </summary>
/// <param name="Name">UDT name. Case-insensitively matched against <see cref="S7TagDefinition.UdtName"/> and against nested members' <see cref="S7UdtMember.UdtName"/>.</param>
/// <param name="Members">Ordered member list. Members must have ascending non-overlapping offsets; offsets that re-use bytes are rejected at fan-out time.</param>
/// <param name="SizeBytes">Total UDT byte size, used as a sanity bound for the last member's offset + width.</param>
/// <remarks>
///     <para>
///         <b>Optimized block access</b>: TIA Portal can mark a DB or UDT as
///         "Optimized block access" which lets the runtime reorder members for
///         memory alignment. The static-offset model used here REQUIRES "Optimized
///         block access" turned OFF on the parent DB; otherwise the declared
///         offsets won't match the runtime layout. Same constraint applies to
///         general absolute-offset DB addressing (see <c>docs/v2/s7.md</c>).
///     </para>
///     <para>
///         <b>Nesting depth</b>: nested UDT-of-UDT is supported up to 4 levels.
///         The fan-out throws <see cref="InvalidOperationException"/> on the 5th
///         level — picked as a generous-but-still-bounded ceiling that catches
///         pathological / accidentally-recursive declarations early.
///     </para>
/// </remarks>
public sealed record S7UdtDefinition(
    string Name,
    IReadOnlyList<S7UdtMember> Members,
    int SizeBytes);