Document Attachments

The LEADTOOLS Document library supplies the following support for attachments:

Reading Embedded 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:

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.

Using External Attachments

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:

The rest of the properties can be set (but are not required) to match the attachment document:

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.

Attachments and Cache

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.

Loading Attachments

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:

• If DocumentAttachment.DocumentId is not null, it will load the specified document from the cache by ID.
• If the value is null and IsEmbedded is true, then the AttachmentNumber is used to identify the embedded attachment and attempts 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. 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).

Saving Attachments

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.