using System;
using System.IO;
using XP.Common.PdfViewer.Exceptions;

namespace XP.Common.PdfViewer.Interfaces
{
    /// <summary>
    /// PDF 查看服务接口 | PDF viewer service interface
    /// 提供 PDF 文件加载和阅读器窗口管理功能 | Provides PDF file loading and viewer window management
    /// </summary>
    public interface IPdfViewerService : IDisposable
    {
        /// <summary>
        /// 通过文件路径打开 PDF 阅读器窗口 | Open PDF viewer window by file path
        /// </summary>
        /// <param name="filePath">PDF 文件路径 | PDF file path</param>
        /// <exception cref="FileNotFoundException">文件不存在 | File not found</exception>
        /// <exception cref="PdfLoadException">PDF 格式无效 | Invalid PDF format</exception>
        void OpenViewer(string filePath);

        /// <summary>
        /// 通过文件流打开 PDF 阅读器窗口 | Open PDF viewer window by stream
        /// </summary>
        /// <param name="stream">PDF 文件流 | PDF file stream</param>
        /// <param name="title">窗口标题（可选）| Window title (optional)</param>
        /// <exception cref="ArgumentNullException">流为 null | Stream is null</exception>
        /// <exception cref="PdfLoadException">PDF 格式无效 | Invalid PDF format</exception>
        void OpenViewer(Stream stream, string? title = null);
    }
}