namespace RioJoy.Core.Serial;

/// <summary>
/// A bidirectional byte transport to the RIO board. Abstracts the physical COM
/// port so <see cref="RioSerialLink"/> can be driven against an in-memory fake
/// in tests. Disposing the transport releases the underlying port — which is how
/// RIOJoy yields the COM port to a native game (see docs/PLAN.md §Profiles).
/// </summary>
public interface IRioTransport : IDisposable
{
    /// <summary>Human-readable description (e.g. "COM3 @ 9600 8N1").</summary>
    string Description { get; }

    /// <summary>
    /// Read available bytes into <paramref name="buffer"/>. Returns the number of
    /// bytes read; a return of 0 indicates the transport has closed.
    /// </summary>
    /// <remarks>
    /// Plain <c>byte[]</c>/<see cref="Task"/> rather than Memory/ValueTask: the
    /// link runs at 9600 baud, and the net40 (Windows XP) flavor has neither
    /// System.Memory nor ValueTask (see docs/PLAN.md §Phase 8).
    /// </remarks>
    Task<int> ReadAsync(byte[] buffer, CancellationToken cancellationToken);

    /// <summary>Write all of <paramref name="data"/> to the transport.</summary>
    Task WriteAsync(byte[] data, CancellationToken cancellationToken);
}
