DL Logo

PDFileAttachment Typedefs

PDFileAttachment

Header: PDExpT.h:6974

Description

A PDFileAttachment represents an embedded file stored in a PDF file, and may be stored at various locations in a PDF file, including the EmbeddedFiles name tree, FileAttachment annotation types, and Multimedia annotations.

Syntax

typedef OPAQUE_64_BITS PDFileAttachment;

Returned From

Used By

PDFileAttachment Functions

PDFileAttachmentFromCosObj

Header: PDProcs.h:12207

Description

Converts a file specification dictionary to a PDFileAttachment object. An exception is raised if the parameter is not a file specification dictionary.

Syntax

PDFileAttachment PDFileAttachmentFromCosObj(CosObj cosAttachment);

Parameters

attachment
The CosObj to convert.

Returns

The file attachment object.

PDFileAttachmentGetCosObj

Header: PDProcs.h:12213

Description

Returns a CosObj representing the file specification dictionary of the file attachment.

Syntax

CosObj PDFileAttachmentGetCosObj(PDFileAttachment attachment);

Parameters

attachment
The file attachment object.

Returns

The CosObj representation of the file attachment.

PDFileAttachmentGetCreationDate

Header: PDProcs.h:12240

Description

Gets the creation date of the file attachment.

Syntax

ASBool PDFileAttachmentGetCreationDate(PDFileAttachment attachment, ASTimeRec *date);

Parameters

attachment
The file attachment object.
date
A pointer to a date that will receive the creation date.

Returns

true if the file attachment has a creation date, false otherwise. A creation date may be absent for various reasons. For example, the file attachment may have originated from a file system that does not provide creation date information, such as Unix.

PDFileAttachmentGetFieldDate

Header: PDProcs.h:12338

Description

Gets the value of the specified date field in the file attachment.

Syntax

ASBool PDFileAttachmentGetFieldDate(PDFileAttachment attachment, ASAtom fieldID, ASTimeRec *date);

Parameters

attachment
The file attachment.
fieldID
The field identifier.
date
The date that will receive the field value.

Returns

true if the field value was found, false otherwise.

PDFileAttachmentGetFieldNumber

Header: PDProcs.h:12321

Description

Gets the value of the specified numeric field in the file attachment.

Syntax

ASBool PDFileAttachmentGetFieldNumber(PDFileAttachment attachment, ASAtom fieldID, float *number);

Parameters

attachment
The file attachment.
fieldID
The field identifier.
number
The number that will receive the field value.

Returns

true if the field value was found, false otherwise.

PDFileAttachmentGetFieldPrefix

Header: PDProcs.h:12355

Description

Gets the specified prefix field in the file attachment.

Syntax

ASBool PDFileAttachmentGetFieldPrefix(PDFileAttachment attachment, ASAtom fieldName, ASText prefix);

Parameters

attachment
The file attachment.
fieldID
The field identifier.
prefix
The text object that will receive the prefix.

PDFileAttachmentGetFieldStyle

Header: PDProcs.h:12304

Description

Gets the value of the specified text field in the file attachment.

Syntax

ASBool PDFileAttachmentGetFieldStyle(PDFileAttachment attachment, ASAtom fieldID, ASCab styles);

Parameters

attachment
The file attachment.
fieldID
The field identifier.
styles
ASCab object that will receive the field styles

Returns

true if the field value was found, false otherwise.

PDFileAttachmentGetFieldStyledText

Header: PDProcs.h:12287

Description

Gets the value of the specified text field in the file attachment as styled text, in XML Text Layout Format.

Syntax

ASBool PDFileAttachmentGetFieldStyledText(PDFileAttachment attachment, ASAtom fieldID, ASText text);

Parameters

attachment
The file attachment.
fieldID
The field identifier.
text
The text object that will receive the field value.

Returns

true if the field value was found, false otherwise.

PDFileAttachmentGetFieldText

Header: PDProcs.h:12279

Description

Gets the value of the specified text field in the file attachment.

Syntax

ASBool PDFileAttachmentGetFieldText(PDFileAttachment attachment, ASAtom fieldID, ASText text);

Parameters

attachment
The file attachment.
fieldID
The field identifier.
text
The text object that will receive the field value.

Returns

true if the field value was found, false otherwise.

PDFileAttachmentGetFileName

Header: PDProcs.h:12253

Description

Gets the file name of the file attachment.

Syntax

ASText PDFileAttachmentGetFileName(PDFileAttachment attachment);

Parameters

attachment
The file attachment.

Returns

An ASText copy of the file name of the file attachment.

PDFileAttachmentGetFileSize

Header: PDProcs.h:12230

Description

Returns the size, in bytes, that the file will occupy if exported to disk.

Syntax

ASUns32 PDFileAttachmentGetFileSize(PDFileAttachment attachment);

Parameters

attachment
The file attachment object

Returns

The size of the file attachment. It returns 0 if the PDFileAttachment object does not specify a file size and one cannot be determined.

PDFileAttachmentGetModDate

Header: PDProcs.h:12247

Description

Gets the modification date of the file attachment.

Syntax

ASBool PDFileAttachmentGetModDate(PDFileAttachment attachment, ASTimeRec *date);

Parameters

attachment
The file attachment object.
date
A pointer to a date that will receive the modification date.

Returns

true if the file attachment has a modification date, false otherwise.

PDFileAttachmentIsValid

Header: PDProcs.h:12119

Description

Tests a file attachment for validity.

Syntax

ASBool PDFileAttachmentIsValid(PDFileAttachment attachment);

Parameters

attachment
The file attachment.

Returns

true if the file attachment is a dictionary, false otherwise.

PDFileAttachmentNewFromFile

Header: PDProcs.h:12164

Description

Creates a new file attachment from the given file. The resulting file specification dictionary is created for the given document, but is not referenced. The client must reference the resulting file specification dictionary by attaching it to another object in the PDF file, such as an annotation or name tree. An exception is raised if the file could not be read or the attachment stream could not be created.

Note that permissions must be checked by the caller before invoking this function.

For example, to have an attachment flate compressed and then ASCII base-85 encoded:

ASAtom filterNames[2]; filterNames[0] = ASAtomFromString("ASCII85Decode"); filterNames[1] = ASAtomFromString("FlateDecode"); PDFileAttachmentNewFromFile(parentDoc, sourceFile, filterNames, 2, CosNewNull(), NULL, NULL, NULL);

Syntax

PDFileAttachment PDFileAttachmentNewFromFile(CosDoc parentDoc, ASFile sourceFile, const ASAtom *filterNames, const ASArraySize numFilters, CosObj filterParams, ASProgressMonitor monitor, ASConstText monitorText, void *monitorData);

Parameters

parentDoc
The CosDoc in which the file attachment dictionary will be created.
sourceFile
The ASFile from which to create the file attachment.
filterNames

An array of filters to apply to the file attachment stream. Filters are indentified by name. See the description of Filters in the ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section 7.4, page 22.

You can find this document on the web store of the International Standards Organization (ISO).

numFilters
The number of elements in filterNames.
filterParams
The filter parameters, represented as a CosArray or CosNull. When the array form is used, the array must contain the same number of elements as filterNames. Each element in the CosArray is a CosDict representing the filter parameters for the corresponding filter in the filterNames array, or CosNull to indicate that default parameters should be used for that filter. When the CosNull form is used for filterParams, default parameters are used for every filter in the filterNames array.
monitor
The ASProgressMonitor to use for the duration of the call. The monitor object is owned by the caller. NULL indicates that no progress updates are needed.
monitorText
The text for the monitor to display, or NULL if no text is needed. The text object is owned by the caller.
monitorData
Opaque data that is specific to the monitor object.

Returns

The new file attachment.

PDFileAttachmentOpenStream

Header: PDProcs.h:12221

Description

Returns a stream for reading the data from an existing file attachment. An exception is raised if the file attachment does not have a stream (it is not embedded) or the stream could not be opened. The caller is responsible for closing the returned stream.

Syntax

ASStm PDFileAttachmentOpenStream(PDFileAttachment attachment);

Parameters

attachment
The file attachment object.

Returns

The file attachment stream.

PDFileAttachmentSaveToFile

Header: PDProcs.h:12200

Description

Copies the data embedded in the file attachment to the specified file. The file must be open for write or append. The caller is responsible for closing the file after this call returns. If an error is encountered during the write, some data may have been written to the destination file. This call will make no attempt at restoring the file after failure. An exception is raised if the file attachment has no embedded stream or if a file write error occurs.

Syntax

void PDFileAttachmentSaveToFile(PDFileAttachment attachment, ASFile destFile);

Parameters

attachment
The file attachment.
destFile
The file that will be written with the file attachment data.

PDFileAttachmentSetFieldDate

Header: PDProcs.h:12330

Description

Sets the specified date field in the file attachment.

Syntax

void PDFileAttachmentSetFieldDate(PDFileAttachment attachment, ASAtom fieldID, const ASTimeRec *date);

Parameters

attachment
The file attachment.
fieldID
The field identifier.
date
The date to use as the new value for the specified field.

Exceptions

is raised if the field does not exist in the collection schema or the field type is not D (date).

PDFileAttachmentSetFieldNumber

Header: PDProcs.h:12313

Description

Sets the specified numeric field in the file attachment.

Syntax

void PDFileAttachmentSetFieldNumber(PDFileAttachment attachment, ASAtom fieldID, float number);

Parameters

attachment
The file attachment.
fieldID
The field identifier.
number
The number to use as the new value for the specified field.

Exceptions

is raised if the field does not exist in the collection schema or the field type is not N (number).

PDFileAttachmentSetFieldPrefix

Header: PDProcs.h:12348

Description

Sets the specified prefix field in the file attachment. The prefix allows additional text to be prepended to the visual appearance of a field without affecting its actual value.

Syntax

void PDFileAttachmentSetFieldPrefix(PDFileAttachment attachment, ASAtom fieldName, ASText text);

Parameters

attachment
The file attachment.
fieldName
The field identifier.
text
The prefix to use as the new value for the specified field. Note that if a NULL value is passed into this parameter, the prefix is removed and an exception will not be thrown.

Exceptions

is raised if the field does not exist in the collection schema.

PDFileAttachmentSetFieldStyle

Header: PDProcs.h:12296

Description

Sets the specified text field in the file attachment using styled text.

Syntax

void PDFileAttachmentSetFieldStyle(PDFileAttachment attachment, ASAtom fieldID, ASConstCab styles);

Parameters

attachment
The file attachment.
fieldID
The field identifier.
styles
ASConstCab containing field styles for the specified field.

Exceptions

is raised if the field does not exist in the collection schema or the field type is not S (text).

PDFileAttachmentSetFieldStyledText

Header: PDProcs.h:12271

Description

Sets the specified text field in the file attachment using styled text.

Syntax

void PDFileAttachmentSetFieldStyledText(PDFileAttachment attachment, ASAtom fieldID, ASConstText text);

Parameters

attachment
The file attachment.
fieldID
The field identifier.
text
Text Layout Format XML containing the text to use as the new value for the specified field.

Exceptions

is raised if the field does not exist in the collection schema or the field type is not S (text).

PDFileAttachmentSetFieldText

Header: PDProcs.h:12262

Description

Sets the specified text field in the file attachment.

Syntax

void PDFileAttachmentSetFieldText(PDFileAttachment attachment, ASAtom fieldID, ASText text);

Parameters

attachment
The file attachment.
fieldID
The field identifier.
text
The text to use as the new value for the specified field.

Exceptions

is raised if the field does not exist in the collection schema or the field type is not S (text).

PDFileAttachmentUpdateFromFile

Header: PDProcs.h:12185

Description

Updates a file attachment from the given file. The attachment uses the filters specified in the attachment to encode the data. An exception is raised if the file could not be read or the attachment stream could not be updated.

Note that permissions must be checked by the caller before invoking this function.

Syntax

void PDFileAttachmentUpdateFromFile(PDFileAttachment attachment, ASFile sourceFile, ASProgressMonitor monitor, ASConstText monitorText, void *monitorData);

Parameters

attachment
The file attachment.
sourceFile
The file to use as input for the update operation.
monitor
The ASProgressMonitor to use for the duration of the call. The monitor object is owned by the caller. NULL indicates that no progress updates are needed.
monitorText
The text for the monitor to display, or NULL if no text is needed. The text object is owned by the caller.
monitorData
Opaque data that is specific to the monitor object.