diff --git a/_config.yml b/_config.yml index ed840bfe..49139e36 100644 --- a/_config.yml +++ b/_config.yml @@ -49,7 +49,7 @@ navigation: title: Troubleshooting position: 99 common-information: - title: Common Information + title: Common position: 98 security: title: Security diff --git a/common-information/fileformatdetector.md b/common-information/fileformatdetector.md new file mode 100644 index 00000000..cdb6155b --- /dev/null +++ b/common-information/fileformatdetector.md @@ -0,0 +1,57 @@ +--- +title: FileFormatDetector +description: Detect file formats automatically using the FileFormatDetector of the Telerik Document Processing libraries. +page_title: FileFormatDetector +slug: fileformatdetector +position: 1 +published: True +tags: file, format, detection, detector, pdf, docx, xlsx, zip, doc, xls, xlsm, txt, document, processing, libraries +--- + +# FileFormatDetector + +The **FileFormatDetector** API provides automatic file format detection capabilities for various document types supported by Telerik Document Processing libraries. This utility enables you to programmatically identify the format of a document stream before attempting to process it, making it easier to handle documents of unknown types and providing better error handling in your applications. + +The detector analyzes file signatures, headers, and content patterns to accurately identify document formats including PDF, DOCX, XLSX, RTF, and other supported formats. This is particularly useful when working with user-uploaded files or when processing documents from external sources where the file format might not be immediately known. + +## Key Features + +* **Automatic Format Detection**: Identifies document formats from a stream without requiring file extensions +* **Multiple Format Support**: Detects PDF, DOCX, XLSX, PPTX, RTF, and other document formats +* **Stream-Based**: Works directly with streams, making it compatible with various input sources +* **Error Handling**: Provides detailed error messages when detection fails +* **Lightweight**: Minimal overhead with efficient signature and header analysis + +## API + +**Namespace:** Telerik.Documents.Utilities.Detectors.FileFormat + +### FileFormatDetector + +The main class for detecting file formats. + +| Member | Type | Description | +|--------|------|-------------| +| **Detect(Stream stream)** | Method | Detects the format of a file from a stream. Returns a **FileFormatDetectionResult** containing the detection outcome. | + +### FileFormatDetectionResult + +Represents the result of a file format detection operation. + +| Member | Type | Description | +|--------|------|-------------| +| **IsSuccessful** | Property (bool) | Gets a value indicating whether a specific file format was successfully detected. Returns false if the format is unknown or detection failed. | +| **Format** | Property (DocumentFormatType) | Gets the detected document format type. Returns **DocumentFormatType.Unknown** if detection was unsuccessful. | +| **ErrorMessage** | Property (string) | Gets the error message if detection failed, or null if successful. | + +## Using FileFormatDetector + +The following example demonstrates how to detect the format of a document from a file stream: + + + +## See Also + +* [RadPdfProcessing Overview]({%slug radpdfprocessing-overview%}) +* [RadWordsProcessing Overview]({%slug radwordsprocessing-overview%}) +* [RadSpreadProcessing Overview]({%slug radspreadprocessing-overview%}) diff --git a/libraries/radpdfprocessing/concepts/comply-with-pdfa-standard.md b/libraries/radpdfprocessing/concepts/comply-with-pdfa-standard.md index c71e19eb..dc3fb5cf 100644 --- a/libraries/radpdfprocessing/concepts/comply-with-pdfa-standard.md +++ b/libraries/radpdfprocessing/concepts/comply-with-pdfa-standard.md @@ -67,6 +67,16 @@ This ensures that the exported PDF document is properly tagged, which is essenti >important The PDF/A standard requires all fonts used in a document to be embedded. Prior to **Q3 2025**, the [14 standard fonts]({%slug radpdfprocessing-concepts-fonts%}#standard-fonts) were not embedded in the file, which caused the document to be non-compliant. As of **Q3 2025**, these standard fonts are automatically embedded when PDF/A compliance is enabled. More information about font embedding is available in the [Fonts]({%slug radpdfprocessing-concepts-fonts%}) article. +### Setting Fallback Fonts for Standard Fonts + +When working with PDF/A-compliant documents, you can specify fallback fonts for the standard fonts to ensure proper rendering when the standard font is unavailable or needs to be replaced: + + + +If you need to remove all configured fallback fonts, you can use the __ClearStandardFontFallbacks()__ method: + + + ## See Also * [Using PdfFormatProvider]({%slug radpdfprocessing-formats-and-conversion-pdf-pdfformatprovider%}) diff --git a/libraries/radpdfprocessing/concepts/fonts.md b/libraries/radpdfprocessing/concepts/fonts.md index 662b1ec7..0466f3ae 100644 --- a/libraries/radpdfprocessing/concepts/fonts.md +++ b/libraries/radpdfprocessing/concepts/fonts.md @@ -79,8 +79,6 @@ There are 14 *Type 1* fonts, known as the standard 14 fonts, that are not embedd | Symbol| | ZapfDingbats| - - >tip These fonts, or their font metrics and suitable substitution fonts, must be available to the consumer application. @@ -92,6 +90,18 @@ FontsRepository will replace the provided standard font with the passed font dat +#### Set a Fallback Font + +You can configure fallback fonts for the standard fonts to ensure proper rendering when a standard font needs to be substituted with another font. + +The following exmaple demonstrates how to set a fallback font for a specific standard font: + + + +To remove all configured fallback fonts, use the __ClearStandardFontFallbacks()__ method: + + + ## Embedded Fonts All fonts, which are not included in the 14 standard ones, should be **embedded** in the PDF document. Otherwise, the result may be unpredictable when the document is rendered. In __RadPdfProcessing__ you have the ability to embed fonts following the approaches described below. diff --git a/libraries/radpdfprocessing/features/digital-signature/getting-started.md b/libraries/radpdfprocessing/features/digital-signature/getting-started.md index eac22f41..47f6d6a6 100644 --- a/libraries/radpdfprocessing/features/digital-signature/getting-started.md +++ b/libraries/radpdfprocessing/features/digital-signature/getting-started.md @@ -43,9 +43,17 @@ The following example shows a full code snippet for a simple signing of a newly The **SignatureSettings** class (*introduced in Q4 2025*) provides configurable options for producing digital signatures in PDF documents. It allows developers to specify the digest (hash) algorithm used during certificate-based signing. The SignatureSettings are accessed by the Signature.**Settings** public property and it offers the following settings to be specified: -* **DigestAlgorithm**: Gets or sets the digest (hash) algorithm used when producing the CMS (PKCS#7) signature. The default is *DigestAlgorithmType.Sha256* to provide a modern, interoperable baseline (SHA-256). The supported digest (hash) algorithms for producing CMS (PKCS#7) PDF signature values are:
  • **Sha256**: SHA-256 (256-bit). Recommended default: strong, widely supported, and efficient.
  • **Sha384**: SHA-384 (384-bit). Use when organizational policy or key size (e.g. P-384) mandates higher strength.
  • **Sha512**: SHA-512 (512-bit). Use for highest SHA-2 family strength or long‑term archival policies; may have slightly higher computational cost.
+* **DigestAlgorithm**—Gets or sets the digest (hash) algorithm used when producing the CMS (PKCS#7) signature. The default is *DigestAlgorithmType.Sha256* to provide a modern, interoperable baseline (SHA-256). The supported digest (hash) algorithms for producing CMS (PKCS#7) PDF signature values are:
  • **Sha256**—SHA-256 (256-bit). Recommended default: strong, widely supported, and efficient.
  • **Sha384**—SHA-384 (384-bit). Use when organizational policy or key size (e.g. P-384) mandates higher strength.
  • **Sha512**—SHA-512 (512-bit). Use for highest SHA-2 family strength or long‑term archival policies; may have slightly higher computational cost.
-* **TimeStampServer**: Gets or sets the [timestamp server]({%slug pdf-sign-timestamp-server%}) settings used to obtain a trusted timestamp for the signature. +* **TimeStampServer**—Gets or sets the [timestamp server]({%slug pdf-sign-timestamp-server%}) settings used to obtain a trusted timestamp for the signature. + +* **CertificateChainIncludeOption**—Gets or sets the option that determines which certificates are included in the certificate chain when exporting or processing certificates. Use this property to specify whether only the end-entity certificate, the entire chain, or a partial chain should be included. The selected option may affect compatibility with external systems and the ability to validate the certificate. [*Introduced in Q1 2026*] + + The available options are: + * **None**—No certificate chain information is included. + * **ExcludeRoot**—The entire certificate chain is included except for the root certificate. + * **EndCertOnly**—Only the end certificate is included in the certificate chain information. + * **WholeChain**—The entire certificate chain is included. ## Signature Encodings diff --git a/libraries/radpdfprocessing/features/embedded-file-streams/embedded-file-streams.md b/libraries/radpdfprocessing/features/embedded-file-streams/embedded-file-streams.md index 5bbe2ef3..a99c7ea2 100644 --- a/libraries/radpdfprocessing/features/embedded-file-streams/embedded-file-streams.md +++ b/libraries/radpdfprocessing/features/embedded-file-streams/embedded-file-streams.md @@ -12,10 +12,16 @@ As of **2024 Q1** RadPdfProcessing allows embedding file streams into the docume ## The EmbeddedFile Class -RadFixedDocument stores the integrated files in an **EmbeddedFilesCollection** accessed by the **EmbeddedFiles** property. Each **EmbeddedFile** contains **Name** (string) and **Data** (byte[]) properties. The specified Name should be unique and it represents the textual description of the embedded file, which can be displayed in the user interface of a viewer application. The Data stores the byte[] of the file stream. +RadFixedDocument stores the integrated files in an **EmbeddedFilesCollection** accessed by the **EmbeddedFiles** property. Each **EmbeddedFile** requires **Name** (string) and **Data** (byte[]) properties. The specified Name should be unique and it represents the textual description of the embedded file, which can be displayed in the user interface of a viewer application. The Data stores the byte[] of the file stream. >important The Name for the EmbeddedFile should contain the file extension as well, e.g. *MySampleTextFile.txt*. +|Property|Description| +|----|----| +|**Name**|Gets or sets the attachment's display file name (including extension) shown in viewer UIs.| +|**Data**|Represents the file data as a byte array.| +|**MimeType**|Gets or sets the MIME type of the embedded file. The MIME type string (e.g., "application/xml", "text/xml", etc.). If not specified, the default value of "application/octet-stream" will be used. (*introduced in Q1 2026*) | + >note [PdfProcessing Embedding File Streams Demo](https://demos.telerik.com/document-processing/pdfprocessing/embed_file_streams) ### Creating an Embedded File Stream @@ -27,8 +33,18 @@ RadFixedDocument stores the integrated files in an **EmbeddedFilesCollection** a >important **DuplicatedEmbeddedFileNameException** is thrown when adding an embedded file with a name that is already added to the collection. #### Attachments section in Adobe + ![Embedded Files in a PDF document](images/embedded_files_0.png) +### Specifying the MIME Type + +|Minimum Version|Q1 2026| +|----|----| + +RadPdfProcessing allows you to explicitly set the correct MIME type when embedding the file into the PDF. This is especially important for standards like PDF/A-3 and Factur-X, which require strict metadata and MIME type declarations for embedded files. + + + ### Creating an Embedded Electronic (ZUGFeRD) Invoice RadPdfProcessing provides support for embedding [ZUGFeRD invoices]({%slug radpdfprocessing-embedded-file-streams-zugferd-invoices%}). diff --git a/libraries/radpdfprocessing/features/handling-document-exceptions.md b/libraries/radpdfprocessing/features/handling-document-exceptions.md index 48017ed2..068f2a53 100644 --- a/libraries/radpdfprocessing/features/handling-document-exceptions.md +++ b/libraries/radpdfprocessing/features/handling-document-exceptions.md @@ -73,9 +73,10 @@ As of **Q1 2025** the [PdfExportSettings]({%slug radpdfprocessing-formats-and-co | __NotSupportedXObjectTypeException__| Represents an exception for a document with an XObject type which is not supported.| |**DuplicatedJavaScriptNameException**|Represents an exception for JavaScript with a duplicated name.| |**NotSupportedImageFormatException**|Represents an exception thrown when attempting to use an image format that is not supported by the library.| -|**InvalidAnnotationException**|Represents an exception for an annotation which is not valid. *(Introduced in Q1 2025)*| -|**NotSupportedAnnotationException**|Represents an exception for an annotation which is not supported.*(Introduced in Q1 2025)*| -|**InvalidImageDataException**|Represents an exception for importing an invalid image data.*(Introduced in Q1 2025)*| +|**InvalidAnnotationException**|Represents an exception for an annotation which is not valid.| +|**NotSupportedAnnotationException**|Represents an exception for an annotation which is not supported.| +|**InvalidImageDataException**|Represents an exception for importing an invalid image data.| +|**NotSupportedPdfPrimitivesConversionException**|Represents an exception thrown when attempting to convert unsupported PDF primitive types.| # See Also diff --git a/libraries/radspreadprocessing/formats-and-conversion/data-table/using-data-table-format-provider.md b/libraries/radspreadprocessing/formats-and-conversion/data-table/using-data-table-format-provider.md index 09af9ae2..2d577e57 100644 --- a/libraries/radspreadprocessing/formats-and-conversion/data-table/using-data-table-format-provider.md +++ b/libraries/radspreadprocessing/formats-and-conversion/data-table/using-data-table-format-provider.md @@ -12,7 +12,9 @@ position: 1 The __DataTableFormatProvider__ allows you to easily convert existing [DataTable](https://docs.microsoft.com/en-us/dotnet/api/system.data.datatable?view=net-5.0) to a worksheet and vice versa. Below you can see how to use this format provider to import/export data tables. -To use the DataTableFormatProvider you need to reference the __Telerik.Windows.Documents.Spreadsheet__ package. +To use the DataTableFormatProvider you need to reference the __Telerik.Windows.Documents.Spreadsheet__ package. + +>note As of Q1 2026 the DataTableFormatProvider supports the [timeout mechanism]({%slug timeout-mechanism-in-dpl%}) that was previously introduced for the rest of the providers. ## Import @@ -25,7 +27,7 @@ Example 1 shows how you can import a DataTable. The sample instantiates a __Data DataTable table = GetTable(); DataTableFormatProvider provider = new DataTableFormatProvider(); - Workbook workbook = provider.Import(table); + Workbook workbook = provider.Import(table, TimeSpan.FromSeconds(10)); {{endregion}} @@ -41,7 +43,7 @@ You can import the data from the DataTable to an existing worksheet as well. Workbook workbook = new Workbook(); Worksheet worksheet = workbook.Worksheets.Add(); - provider.Import(table, worksheet); + provider.Import(table, worksheet, TimeSpan.FromSeconds(10)); {{endregion}} @@ -56,7 +58,7 @@ Example 3 demonstrates how you can export an existing Worksheet to a DataTable. Workbook workbook = GetWorkbook(); DataTableFormatProvider provider = new DataTableFormatProvider(); - DataTable table = provider.Export(workbook.ActiveWorksheet); + DataTable table = provider.Export(workbook.ActiveWorksheet, TimeSpan.FromSeconds(10)); {{endregion}}