[next] [prev] [prev-tail] [tail] [up]

Chapter 12
File Attachments

cpdf -attach-file <filename> [-to-page <page number>] in.pdf -o out.pdf

cpdf -list-attached-files in.pdf

cpdf -remove-files in.pdf -o out.pdf

cpdf -dump-attachments in.pdf -o <directory>

PDF supports adding attachments (files of any kind, including other PDFs) to an existing file. The cpdf tool supports adding and removing document-level attachments — that is, ones which are associated with the document as a whole rather than with an individual page, and also page-level attachments, associated with a particular page.

12.1 Adding Attachments

To add an attachment, use the -attach-file operation. For instance,

cpdf -attach-file sheet.xls in.pdf -o out.pdf

attaches the Excel spreadsheet sheet.xls to the input file. If the file already has attachments, the new file is added to their number. You can specify multiple files to be attached by using -attach-file multiple times. They will be attached in the given order.

The -to-page option can be used to specify that the files will be attached to the given page, rather than at the document level. The -to-page option may be specified at most once.

12.2 Listing Attachments

To list all document- and page-level attachments, use the -list-attached-files operation. The page number and filename of each attachment is given, page 0 representing a document-level attachment. 

$cpdf -list-attached-files 14psfonts.pdf
0 utility.ml
0 utility.mli
4 notes.xls

12.3 Removing Attachments

To remove all document-level and page-level attachments from a file, use the -remove-files operation:

cpdf -remove-files in.pdf -o out.pdf

12.4 Dumping Attachments to File

The -dump-attachments operation, when given a PDF file and a directory path as the output, will write each attachment under its filename (as displayed by -list-attached-files to that directory. The directory must exist prior to the call.

cpdf -dump-attachments in.pdf -o /home/fred/attachments

Unless the -raw option is given, the filenames are stripped of dubious special characters before writing. It is converted from unicode to 7 bit ASCII, and the following characters are removed, in addition to any character with ASCII code less than 32:

 / ? < > '  : * | " ˆ + =

Java Interface

 
/* CHAPTER 12. File Attachments */ 
 
/** Attaches a file to the PDF. It is attached at document level. 
@param filename file name 
@param pdf PDF document */ 
public void attachFile(String filename, Pdf pdf) throws CpdfError; 
 
/** Attaches a file to a page of the PDF. Given its file name, pdf, and the 
page number to which it should be attached. 
@param filename file name 
@param pdf PDF document 
@param pagenumber page number to attach to */ 
public void attachFileToPage(String filename, Pdf pdf, int pagenumber) 
    throws CpdfError; 
 
/** Attaches data from memory to a document. 
@param data attachment itself 
@param filename file name to use to describe attachment 
@param pdf PDF document */ 
public void attachFileFromMemory(byte[] data, String filename, Pdf pdf) 
    throws CpdfError; 
 
/** Attaches data to a page from memory. 
@param data attachment itself 
@param filename file name to use to describe attachment 
@param pdf PDF document */ 
public void attachFileToPageFromMemory(byte[] data, String filename, 
                                       Pdf pdf, int pagenumber) 
    throws CpdfError; 
 
/** Removes all page- and document-level attachments from a document. */ 
public native void removeAttachedFiles(Pdf pdf) throws CpdfError; 
 
/** Lists information about attachments. Call 
{@link #startGetAttachments(pdf) startGetAttachments} first, then {@link 
#numberGetAttachments() numberGetAttachments} to find out how many there are. 
Then {@link #getAttachmentName(int) getAttachmentName}, {@link 
#getAttachmentPage(int) getAttachmentPage}, or {@link #getAttachmentData(int) 
getAttachmentData}. to return each one <code>0...(n - 1)</code>. Finally, call 
{@link #endGetAttachments() #endGetAttachments} to clean up. */ 
public native void startGetAttachments(Pdf pdf) throws CpdfError; 
 
public native int numberGetAttachments() throws CpdfError; 
 
/** Gets the name of an attachment, given a serial number. */ 
public native String getAttachmentName(int serial) throws CpdfError; 
 
/** Gets the page number, given a serial number. 0 = document level. */ 
public native int getAttachmentPage(int serial) throws CpdfError; 
 
/** Gets the attachment data itself, given a serial number. */ 
public native byte[] getAttachmentData(int serial) throws CpdfError; 
 
public native void endGetAttachments() throws CpdfError;

[next] [prev] [prev-tail] [front] [up]