References ▼
The LEADTOOLS Document library provides the following support for attachments:
Some file formats (such as PDF) support embedded file attachments. These can be any binary or text data embedded in the original document. In the case of PDF, this 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 (such as, the JPEG data of an embedded image in a PDF), for each attachment that is not loaded yet.
The value of the other properties of DocumentAttachment will be 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 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 the 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 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 the 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's 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 this is not embedded because it is an external document. |
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 what happens to 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 an 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, 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.
DocumentFactory.loadDocumentAttachment can be used 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, and if not null, will load the specified document from the cache by ID. If the value is null and isEmbedded is true, then attachmentNumber is used to identify the embedded attachment and attempt to load it.
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.
The attachment's binary data can be obtained using DocumentFactory.downloadDocumentData. This method returns the data as a byte array. Using downloadDocumentData can be useful in certain situations (for example, if the embedded attachment is not a file format that can be loaded using the document library, such as an audio or video file).
DocumentFactory.saveAttachmentToCache can be used to save an attachment to the cache. This method checks the DocumentAttachment.documentId value, and if not null, returns the same document ID. If the value is null and isEmbedded is true, then 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.