TekH
a6694bfce7
Introduced endpoints for embedding attachments in PDFs and converting between standard PDFs and PDF/A formats. Added `PdfAttachmentController` and `PdfConversionController` with multipart/form-data and Base64-based support. Implemented commands, handlers, and validators for these operations. Extended `IPdfProcessor` with methods for adding attachments and PDF/A conversion. Partially implemented functionality in `DevExpressPdfProcessor`, including `ConvertFromPdfAAsync`. Added `attachment.xml` and `withoutAttachment.pdf` as resources for testing. Marked endpoints as `[Obsolete]` to indicate incomplete implementation. Improved validation and error handling for commands.
191 lines
10 KiB
C#
191 lines
10 KiB
C#
using DocumentOperator.Application.Common.DTOs;
|
|
|
|
namespace DocumentOperator.Application.Common.Interfaces;
|
|
|
|
public interface IPdfProcessor
|
|
{
|
|
/// <summary>
|
|
/// Validates a PDF and extracts metadata.
|
|
/// </summary>
|
|
/// <param name="pdfStream">
|
|
/// PDF document stream. Must be readable and positioned at the beginning (Position = 0).
|
|
/// Non-seekable streams are supported. Caller is responsible for disposal.
|
|
/// </param>
|
|
/// <returns>PDF metadata (page count, size, version, attachments)</returns>
|
|
/// <exception cref="Domain.Common.Exceptions.BadRequestException">
|
|
/// Thrown when stream is empty, invalid, or not positioned at the beginning
|
|
/// </exception>
|
|
Task<PdfMetadata> ValidateAsync(Stream pdfStream);
|
|
|
|
/// <summary>
|
|
/// Validates a PDF/A document and checks conformance level.
|
|
/// </summary>
|
|
/// <param name="pdfStream">
|
|
/// PDF document stream. Must be readable and positioned at the beginning (Position = 0).
|
|
/// Non-seekable streams are supported. Caller is responsible for disposal.
|
|
/// </param>
|
|
/// <returns>PDF/A metadata including conformance level and validation errors/warnings</returns>
|
|
/// <exception cref="Domain.Common.Exceptions.BadRequestException">
|
|
/// Thrown when stream is empty, invalid, or not positioned at the beginning
|
|
/// </exception>
|
|
Task<PdfAMetadata> ValidatePdfAAsync(Stream pdfStream);
|
|
|
|
/// <summary>
|
|
/// Checks for embedded files (attachments) in a PDF document and returns detailed metadata.
|
|
/// </summary>
|
|
/// <param name="pdfStream">
|
|
/// PDF document stream. Must be readable and positioned at the beginning (Position = 0).
|
|
/// Non-seekable streams are supported. Caller is responsible for disposal.
|
|
/// </param>
|
|
/// <returns>Attachment information (count, file names, MIME types, sizes)</returns>
|
|
/// <exception cref="Domain.Common.Exceptions.BadRequestException">
|
|
/// Thrown when stream is empty, invalid, or not positioned at the beginning
|
|
/// </exception>
|
|
Task<AttachmentInfo> CheckAttachmentsAsync(Stream pdfStream);
|
|
|
|
/// <summary>
|
|
/// Extracts all embedded files from a PDF document and returns them as a ZIP archive.
|
|
/// </summary>
|
|
/// <param name="pdfStream">
|
|
/// PDF document stream. Must be readable and positioned at the beginning (Position = 0).
|
|
/// Non-seekable streams are supported. Caller is responsible for disposal.
|
|
/// </param>
|
|
/// <returns>ZIP archive containing all extracted attachments as byte array</returns>
|
|
/// <exception cref="Domain.Common.Exceptions.BadRequestException">
|
|
/// Thrown when stream is empty, invalid, or not positioned at the beginning
|
|
/// </exception>
|
|
/// <exception cref="Domain.Common.Exceptions.NotFoundException">
|
|
/// Thrown when PDF contains no attachments
|
|
/// </exception>
|
|
Task<byte[]> ExtractAttachmentsAsync(Stream pdfStream);
|
|
|
|
/// <summary>
|
|
/// Merges multiple PDF documents into a single PDF.
|
|
/// </summary>
|
|
/// <param name="pdfStreams">
|
|
/// PDF streams to merge (minimum 2 required). Each stream must be readable and positioned
|
|
/// at the beginning (Position = 0). Caller is responsible for disposal.
|
|
/// </param>
|
|
/// <param name="pageRanges">
|
|
/// Optional page ranges per PDF (null = all pages). Format: "1-3,5" means pages 1, 2, 3, and 5.
|
|
/// If null or empty for a PDF, all pages are included. Array length must match pdfStreams length if provided.
|
|
/// </param>
|
|
/// <returns>Merged PDF as byte array</returns>
|
|
/// <exception cref="Domain.Common.Exceptions.BadRequestException">
|
|
/// Thrown when fewer than 2 PDFs provided, any stream is empty/invalid/not at Position=0,
|
|
/// or page range format is invalid
|
|
/// </exception>
|
|
Task<byte[]> MergePdfsAsync(IReadOnlyList<Stream> pdfStreams, IReadOnlyList<string?>? pageRanges = null);
|
|
|
|
/// <summary>
|
|
/// Adds an annotation to a PDF document at the specified page and rectangle.
|
|
/// </summary>
|
|
/// <param name="pdfStream">
|
|
/// PDF document stream. Must be readable and positioned at the beginning (Position = 0).
|
|
/// Non-seekable streams are supported. Caller is responsible for disposal.
|
|
/// </param>
|
|
/// <param name="annotationType">Type of annotation to add (TextMarkup, FreeText, StickyNote, Circle, Square)</param>
|
|
/// <param name="pageNumber">Page number (1-based) where annotation should be added</param>
|
|
/// <param name="rectangle">Annotation bounding rectangle (X1, Y1, X2, Y2)</param>
|
|
/// <param name="content">Annotation content/comment text (required for FreeText and StickyNote)</param>
|
|
/// <param name="author">Optional author name</param>
|
|
/// <param name="color">Optional annotation color in RGB format (hex string like "FF0000" for red)</param>
|
|
/// <param name="textMarkupStyle">Text markup style (Highlight, Underline, Strikeout) - only for TextMarkup type</param>
|
|
/// <param name="origin">Coordinate origin (BottomLeft = PDF native, TopLeft = UI-friendly). Default: BottomLeft</param>
|
|
/// <returns>Annotated PDF as byte array</returns>
|
|
/// <exception cref="Domain.Common.Exceptions.BadRequestException">
|
|
/// Thrown when stream is empty/invalid/not at Position=0, page number out of range,
|
|
/// rectangle invalid, or content missing for types that require it
|
|
/// </exception>
|
|
Task<byte[]> AddAnnotationAsync(
|
|
Stream pdfStream,
|
|
Domain.Models.ValueObjects.AnnotationType annotationType,
|
|
int pageNumber,
|
|
(double X1, double Y1, double X2, double Y2) rectangle,
|
|
string? content = null,
|
|
string? author = null,
|
|
string? color = null,
|
|
Domain.Models.ValueObjects.TextMarkupStyle? textMarkupStyle = null,
|
|
Domain.Models.ValueObjects.AnnotationOrigin origin = Domain.Models.ValueObjects.AnnotationOrigin.BottomLeft);
|
|
|
|
/// <summary>
|
|
/// Adds a stamp (text, image, or predefined) to specified pages of a PDF document.
|
|
/// </summary>
|
|
/// <param name="pdfStream">Input PDF stream (must support reading and seeking)</param>
|
|
/// <param name="stampType">Type of stamp (Text, Image, or Predefined)</param>
|
|
/// <param name="pageNumbers">Target page numbers (1-based). Null = all pages.</param>
|
|
/// <param name="position">Stamp position (X, Y coordinates)</param>
|
|
/// <param name="size">Stamp size (Width, Height). Null = auto-size for images.</param>
|
|
/// <param name="origin">Coordinate origin (BottomLeft or TopLeft)</param>
|
|
/// <param name="text">Text content (required for Text stamps)</param>
|
|
/// <param name="fontName">Font name (default: Arial)</param>
|
|
/// <param name="fontSize">Font size in points (default: 12)</param>
|
|
/// <param name="color">Hex color without # (e.g., "FF0000" for red, default: "000000")</param>
|
|
/// <param name="opacity">Opacity 0.0 (transparent) to 1.0 (opaque, default: 0.5)</param>
|
|
/// <param name="rotation">Rotation angle in degrees 0-360 (default: 0)</param>
|
|
/// <param name="placement">Foreground (on top) or Background (behind content)</param>
|
|
/// <param name="imageBytes">Image data (required for Image stamps, PNG/JPEG)</param>
|
|
/// <param name="predefinedType">Predefined stamp type (required for Predefined stamps)</param>
|
|
/// <returns>Stamped PDF as byte array</returns>
|
|
/// <exception cref="BadRequestException">Invalid parameters (missing text/image, invalid page numbers, invalid opacity/rotation)</exception>
|
|
/// <exception cref="PdfProcessingException">DevExpress processing error</exception>
|
|
Task<byte[]> AddStampAsync(
|
|
Stream pdfStream,
|
|
Domain.Models.ValueObjects.StampType stampType,
|
|
int[]? pageNumbers,
|
|
(double X, double Y) position,
|
|
(double Width, double Height)? size = null,
|
|
Domain.Models.ValueObjects.AnnotationOrigin origin = Domain.Models.ValueObjects.AnnotationOrigin.BottomLeft,
|
|
string? text = null,
|
|
string? fontName = null,
|
|
double? fontSize = null,
|
|
string? color = null,
|
|
double? opacity = null,
|
|
double? rotation = null,
|
|
Domain.Models.ValueObjects.StampPlacement placement = Domain.Models.ValueObjects.StampPlacement.Foreground,
|
|
byte[]? imageBytes = null,
|
|
Domain.Models.ValueObjects.PredefinedStampType? predefinedType = null);
|
|
|
|
/// <summary>
|
|
/// Embeds one or more files as attachments in a PDF document (supports PDF/A-3).
|
|
/// </summary>
|
|
/// <param name="pdfStream">
|
|
/// PDF document stream. Must be readable and positioned at the beginning (Position = 0).
|
|
/// Non-seekable streams are supported. Caller is responsible for disposal.
|
|
/// </param>
|
|
/// <param name="attachments">List of files to embed (filename, content, optional MIME type)</param>
|
|
/// <returns>PDF with embedded attachments as byte array</returns>
|
|
/// <exception cref="Domain.Common.Exceptions.BadRequestException">
|
|
/// Thrown when stream is empty/invalid, or attachments list is empty
|
|
/// </exception>
|
|
Task<byte[]> AddAttachmentsAsync(
|
|
Stream pdfStream,
|
|
IReadOnlyList<(string FileName, byte[] Content, string? MimeType)> attachments);
|
|
|
|
/// <summary>
|
|
/// Converts a standard PDF to PDF/A format.
|
|
/// </summary>
|
|
/// <param name="pdfStream">
|
|
/// PDF document stream. Must be readable and positioned at the beginning (Position = 0).
|
|
/// Non-seekable streams are supported. Caller is responsible for disposal.
|
|
/// </param>
|
|
/// <param name="pdfALevel">Target PDF/A level (e.g., "PDF/A-1b", "PDF/A-2b", "PDF/A-3b")</param>
|
|
/// <returns>PDF/A compliant document as byte array</returns>
|
|
/// <exception cref="Domain.Common.Exceptions.BadRequestException">
|
|
/// Thrown when stream is empty/invalid or PDF/A level is unsupported
|
|
/// </exception>
|
|
Task<byte[]> ConvertToPdfAAsync(Stream pdfStream, string pdfALevel);
|
|
|
|
/// <summary>
|
|
/// Converts a PDF/A document to a standard PDF (removes PDF/A restrictions).
|
|
/// </summary>
|
|
/// <param name="pdfStream">
|
|
/// PDF/A document stream. Must be readable and positioned at the beginning (Position = 0).
|
|
/// Non-seekable streams are supported. Caller is responsible for disposal.
|
|
/// </param>
|
|
/// <returns>Standard PDF document as byte array</returns>
|
|
/// <exception cref="Domain.Common.Exceptions.BadRequestException">
|
|
/// Thrown when stream is empty/invalid
|
|
/// </exception>
|
|
Task<byte[]> ConvertFromPdfAAsync(Stream pdfStream);
|
|
} |