References ▼
The LEADTOOLS Document library supplies the following support for attachments:
Some file formats (such as PDF) support embedded file attachments. These can be any binary or textual data embedded in the original document. In the case of PDF, embedded file attachments can be other PDF documents, PNG or TIF images, text files, or any other data.
To parse the embedded attachments in a document, set the value of LoadDocumentOptions.LoadAttachmentsMode to AsAttachments and call any load method (such as DocumentFactory.LoadFromFile or DocumentFactory.LoadFromUri). The resulting LEADDocument object will have the Attachments collection populated with the properties of the embedded attachments found in the original document, along with the type of each item in the collection as a DocumentAttachment. Note that at this point the binary data for each attachment (such as the JPEG data of an embedded image in a PDF), is not loaded yet.
The value of the other properties of DocumentAttachment are set as follows:
| Property | Value |
|---|---|
| DocumentAttachment.AttachmentNumber | The 1-based embedded attachment number. |
| DocumentAttachment.DocumentId | null, since this is an embedded attachment. |
| DocumentAttachment.IsEmbedded | true, since this is an embedded attachment. |
| DocumentAttachment.FileName | The attachment's file name. This is parsed from the original document and will not be null. |
| DocumentAttachment.DisplayName | Display name of the attachment. This is parsed from original document and is optional. |
| DocumentAttachment.FileLength | The length of the attachment file in bytes. This is optional. |
| DocumentAttachment.MimeType | The mime type of the attachment file, such as image/jpeg or application/pdf. This is optional. |
| DocumentAttachment.Metadata | Generic dictionary of values specific to the file format. For example, PDF documents will have the created/modified date of the attachment file as well as the PDF object number. |
Refer to DocumentAttachment for an example.
Note: The document library uses RasterCodecs to load the attachments. Refer to RasterCodecs.ReadAttachments for information about attachment file format support in LEADTOOLS.
Any LEADDocument can be manually added to another one as an attachment by creating a new instance of DocumentAttachment, setting its properties, and adding it to the owner document Attachments collection. The following properties must be set:
| Property | Value |
|---|---|
| DocumentAttachment.AttachmentNumber | Must be set to a unique 1-based value to identify this attachment. |
| DocumentAttachment.DocumentId | Must be set to the ID of the attachment document. |
| DocumentAttachment.IsEmbedded | Must be set to false, since the attachment is not embedded. |
The rest of the properties can be set (but are not required) to match the attachment document:
| Property | Value |
|---|---|
| DocumentAttachment.FileName | Can be set to LEADDocument.Name. |
| DocumentAttachment.DisplayName | Can be set to LEADDocument.Name. |
| DocumentAttachment.FileLength | Can be set to LEADDocument.FileLength. |
| DocumentAttachment.MimeType | Can be set to LEADDocument.MimeType. |
| DocumentAttachment.Metadata | Any extra application-specific values. |
The value of LEADDocument.AutoDeleteAttachmentsFromCache controls handling of the external attachment documents when the owner document is deleted from the cache. If true (the default value), then the document factory will try to delete all documents with ID equal to DocumentAttachment.DocumentId from the cache when DocumentFactory.DeleteFromCache is called on the owner document.
External attachments can be mixed with embedded attachments in a LEADDocument.
Refer to DocumentAttachment.DocumentId for an example.
The values set in LEADDocument.Attachments are preserved when the owner LEADDocument is saved into and then re-loaded from the cache. The application can modify the attachments at any time (for instance, when adding, removing, or re-arranging the items of the Attachments collection).
The data of embedded or external attachments are not loaded when the owner document is loaded from the cache. Only the DocumentAttachment properties (such as AttachmentNumber and DocumentId) are re-populated.
Use DocumentFactory.LoadDocumentAttachment to load an attachment as a new LEADDocument object. This object is separate and independent of the original owner document. LoadDocumentAttachment checks the DocumentAttachment.DocumentId value:
When using DocumentFactory.LoadDocumentAttachment with embedded attachments, the value of DocumentAttachment.DocumentId is always null by default and the attachment data is parsed from the owner document every time this method is called. Applications can optimize this operation by setting the value of DocumentAttachment.DocumentId to the ID of the attachment document. Subsequent calls to DocumentFactory.LoadDocumentAttachment will then reference this value and load the attachment document from the cache instead. To have the factory automatically load the attachment document from the cache, have it set the value of LoadAttachmentOptions.UpdateAttachmentDocumentId to true in the options used to load the attachment.
Use DocumentAttachments.CreateAttachmentStream to obtain the attachment's binary data. This method returns the data as a low level stream. Using CreateAttachmentStream can be useful in certain situations (for instance, if the embedded attachment is not a file format that can be loaded using the document library, such as an audio or video file).
Use DocumentFactory.SaveAttachmentToCache to save an attachment to the cache. This method checks the DocumentAttachment.DocumentId value, and if not null, will return the same document ID. If the value is null and IsEmbedded is true, then the AttachmentNumber is used to identify the embedded attachment and attempt to extract it from the owner document before saving it to the cache.
Refer to DocumentAttachment and DocumentAttachment.DocumentId for examples.