using System;
using System.Threading.Tasks;

namespace Plane.Communication
{
    /// <summary>
    /// 定义与远程主机通信的方法。
    /// </summary>
    public interface IConnection
    {
        /// <summary>
        /// 在不宜抛出的异常发生时引发的事件。
        /// </summary>
        event EventHandler<ExceptionThrownEventArgs> ExceptionThrown;

        /// <summary>
        /// 获取一个值，指示通信是否已开启。
        /// </summary>
        bool IsOpen { get; }

        /// <summary>
        /// 关闭通信。
        /// </summary>
        void Close();

        /// <summary>
        /// 开启通信。
        /// </summary>
        /// <returns>表示此异步操作的 <see cref="Task"/> 实例。</returns>
        Task OpenAsync();

        /// <summary>
        /// 异步读取数据。顺利完成时将正好读取 <paramref name="count"/> 个字节。
        /// </summary>
        /// <param name="buffer">存放数据的缓冲区。</param>
        /// <param name="offset">起始下标。</param>
        /// <param name="count">要读取的字节数。</param>
        /// <returns>包含成功读取的字节数的 <see cref="Task{TResult}"/> 实例。此数目在操作顺利完成时保证与 <paramref name="count"/> 等，否则为 0。</returns>
        Task<int> ReadAsync(byte[] buffer, int offset, int count);

        /// <summary>
        /// 异步写入数据。会抛异常。
        /// </summary>
        /// <param name="buffer">存放数据的缓冲区。</param>
        /// <param name="offset">起始下标。</param>
        /// <param name="count">要写入的字节数。</param>
        /// <returns>表示此异步操作的 <see cref="Task"/> 实例。</returns>
        Task WriteAsync(byte[] buffer, int offset, int count);
    }
}