lmxopcua/src/Core/ZB.MOM.WW.OtOpcUa.Core.Abstractions/IReadable.cs

namespace ZB.MOM.WW.OtOpcUa.Core.Abstractions;

/// <summary>
///     Driver capability for on-demand reads. Required for any driver whose nodes are
///     readable from OPC UA clients (essentially all of them — every committed v2 driver
///     implements this).
/// </summary>
/// <remarks>
///     Reads are idempotent — Polly retry pipelines can safely retry on transient failures
///     (per <c>docs/v2/plan.md</c> decisions #34 and #44).
/// </remarks>
public interface IReadable
{
    /// <summary>
    ///     Read a batch of attributes by their full driver-side reference.
    ///     Returns one snapshot per requested reference, in the same order.
    /// </summary>
    /// <remarks>
    ///     Per-reference failures should be reported via the snapshot's <see cref="DataValueSnapshot.StatusCode"/>
    ///     (Bad-coded), not as exceptions. The whole call should throw only if the driver itself is unreachable.
    /// </remarks>
    /// <param name="fullReferences">The list of full driver-side references to read.</param>
    /// <param name="cancellationToken">A cancellation token for the operation.</param>
    /// <returns>A task that returns a read-only list of data value snapshots, one per requested reference in the same order.</returns>
    Task<IReadOnlyList<DataValueSnapshot>> ReadAsync(
        IReadOnlyList<string> fullReferences,
        CancellationToken cancellationToken);
}