LayerPD_Layer
ObjectPDFileAttachment

PDF file attachment object.


Typedef Summary
 Typedef
 PDFileAttachment
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.
Method Summary
 Method
 
PDFileAttachment PDFileAttachmentFromCosObj(CosObj cosAttachment)
Converts a file specification dictionary to a PDFileAttachment object. An exception is raised if the parameter is not a file specification dictionary.
 
CosObj PDFileAttachmentGetCosObj(PDFileAttachment attachment)
Returns a CosObj representing the file specification dictionary of the file attachment.
 
ASBool PDFileAttachmentGetCreationDate(PDFileAttachment attachment, ASTimeRec* date)
Gets the creation date of the file attachment.
 
ASBool PDFileAttachmentGetFieldDate(PDFileAttachment attachment, ASAtom fieldID, ASTimeRec* date)
Gets the value of the specified date field in the file attachment.
 
ASBool PDFileAttachmentGetFieldNumber(PDFileAttachment attachment, ASAtom fieldID, float* number)
Gets the value of the specified numeric field in the file attachment.
 
ASBool PDFileAttachmentGetFieldPrefix(PDFileAttachment attachment, ASAtom fieldName, ASText prefix)
Gets the specified prefix field in the file attachment.
 
ASBool PDFileAttachmentGetFieldStyle(PDFileAttachment attachment, ASAtom fieldID, ASCab styles)
Gets the value of the specified text field in the file attachment.
 
ASBool PDFileAttachmentGetFieldStyledText(PDFileAttachment attachment, ASAtom fieldID, ASText text)
Gets the value of the specified text field in the file attachment as styled text, in XML Text Layout Format.
 
ASBool PDFileAttachmentGetFieldText(PDFileAttachment attachment, ASAtom fieldID, ASText text)
Gets the value of the specified text field in the file attachment.
 
ASText PDFileAttachmentGetFileName(PDFileAttachment attachment)
Gets the file name of the file attachment.
 
ASUns32 PDFileAttachmentGetFileSize(PDFileAttachment attachment)
Returns the size, in bytes, that the file will occupy if exported to disk.
 
ASBool PDFileAttachmentGetModDate(PDFileAttachment attachment, ASTimeRec* date)
Gets the modification date of the file attachment.
 
ASBool PDFileAttachmentIsValid(PDFileAttachment attachment)
Tests a file attachment for validity.
 
PDFileAttachment PDFileAttachmentNewFromFile(CosDoc parentDoc, ASFile sourceFile, const ASAtom* filterNames, const ASArraySize numFilters, CosObj filterParams, ASProgressMonitor monitor, ASConstText monitorText, void* monitorData)
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.
 
ASStm PDFileAttachmentOpenStream(PDFileAttachment attachment)
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.
 
void PDFileAttachmentSaveToFile(PDFileAttachment attachment, ASFile destFile)
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.
 
void PDFileAttachmentSetFieldDate(PDFileAttachment attachment, ASAtom fieldID, const ASTimeRec* date)
Sets the specified date field in the file attachment.
 
void PDFileAttachmentSetFieldNumber(PDFileAttachment attachment, ASAtom fieldID, float number)
Sets the specified numeric field in the file attachment.
 
void PDFileAttachmentSetFieldPrefix(PDFileAttachment attachment, ASAtom fieldName, ASText text)
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.
 
void PDFileAttachmentSetFieldStyle(PDFileAttachment attachment, ASAtom fieldID, ASConstCab styles)
Sets the specified text field in the file attachment using styled text.
 
void PDFileAttachmentSetFieldStyledText(PDFileAttachment attachment, ASAtom fieldID, ASConstText text)
Sets the specified text field in the file attachment using styled text.
 
void PDFileAttachmentSetFieldText(PDFileAttachment attachment, ASAtom fieldID, ASText text)
Sets the specified text field in the file attachment.
 
void PDFileAttachmentUpdateFromFile(PDFileAttachment attachment, ASFile sourceFile, ASProgressMonitor monitor, ASConstText monitorText, void* monitorData)
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.

Typedefs Detail
PDFileAttachment 
Product availability: All
Platform availability: All

Syntax

typedef OPAQUE_64_BITS PDFileAttachment;

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.

See Also

PDFileAttachmentNewFromFile
PDFileAttachmentUpdateFromFile
PDFileAttachmentSaveToFile

File: PDExpT.h
Line: 6826



Method Detail
PDFileAttachmentFromCosObj()
Product availability: All
Platform availability: All

Syntax

PDFileAttachment PDFileAttachmentFromCosObj(CosObj cosAttachment)

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

Parameters

cosAttachment — 

The CosObj to convert.

Returns

The file attachment object.


File: PDProcs.h
Line: 12022
PDFileAttachmentGetCosObj() 
Product availability: All
Platform availability: All

Syntax

CosObj PDFileAttachmentGetCosObj(PDFileAttachment attachment)

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

Parameters

attachment — 

The file attachment object.

Returns

The CosObj representation of the file attachment.


File: PDProcs.h
Line: 12028
PDFileAttachmentGetCreationDate() 
Product availability: All
Platform availability: All

Syntax

ASBool PDFileAttachmentGetCreationDate(PDFileAttachment attachment, ASTimeRec* date)

Gets the creation date of the file attachment.

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.


File: PDProcs.h
Line: 12055
PDFileAttachmentGetFieldDate() 
Product availability: All
Platform availability: All

Syntax

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

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

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.


File: PDProcs.h
Line: 12153
PDFileAttachmentGetFieldNumber() 
Product availability: All
Platform availability: All

Syntax

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

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

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.


File: PDProcs.h
Line: 12136
PDFileAttachmentGetFieldPrefix() 
Product availability: All
Platform availability: All

Syntax

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

Gets the specified prefix field in the file attachment.

Parameters

attachment — 

The file attachment.

 
fieldName — 

The field identifier.

 
prefix — 

The text object that will receive the prefix.

Returns

File: PDProcs.h
Line: 12170
PDFileAttachmentGetFieldStyle() 
Product availability: All
Platform availability: All

Syntax

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

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

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.


File: PDProcs.h
Line: 12119
PDFileAttachmentGetFieldStyledText() 
Product availability: All
Platform availability: All

Syntax

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

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

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.


File: PDProcs.h
Line: 12102
PDFileAttachmentGetFieldText() 
Product availability: All
Platform availability: All

Syntax

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

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

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.


File: PDProcs.h
Line: 12094
PDFileAttachmentGetFileName() 
Product availability: All
Platform availability: All

Syntax

ASText PDFileAttachmentGetFileName(PDFileAttachment attachment)

Gets the file name of the file attachment.

Parameters

attachment — 

The file attachment.

Returns

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


File: PDProcs.h
Line: 12068
PDFileAttachmentGetFileSize() 
Product availability: All
Platform availability: All

Syntax

ASUns32 PDFileAttachmentGetFileSize(PDFileAttachment attachment)

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

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.


File: PDProcs.h
Line: 12045
PDFileAttachmentGetModDate() 
Product availability: All
Platform availability: All

Syntax

ASBool PDFileAttachmentGetModDate(PDFileAttachment attachment, ASTimeRec* date)

Gets the modification date of the file attachment.

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.


File: PDProcs.h
Line: 12062
PDFileAttachmentIsValid() 
Product availability: All
Platform availability: All

Syntax

ASBool PDFileAttachmentIsValid(PDFileAttachment attachment)

Tests a file attachment for validity.

Parameters

attachment — 

The file attachment.

Returns

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


File: PDProcs.h
Line: 11936
PDFileAttachmentNewFromFile() 
Product availability: All
Platform availability: All

Syntax

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

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);

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, in accordance with section 3.3 of the PDF Reference.

 
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.


File: PDProcs.h
Line: 11982
PDFileAttachmentOpenStream() 
Product availability: All
Platform availability: All

Syntax

ASStm PDFileAttachmentOpenStream(PDFileAttachment attachment)

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.

Parameters

attachment — 

The file attachment object.

Returns

The file attachment stream.


File: PDProcs.h
Line: 12036
PDFileAttachmentSaveToFile() 
Product availability: All
Platform availability: All

Syntax

void PDFileAttachmentSaveToFile(PDFileAttachment attachment, ASFile destFile)

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.

Parameters

attachment — 

The file attachment.

 
destFile — 

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


File: PDProcs.h
Line: 12015
PDFileAttachmentSetFieldDate() 
Product availability: All
Platform availability: All

Syntax

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

Sets the specified date field in the file attachment.

Parameters

attachment — 

The file attachment.

 
fieldID — 

The field identifier.

 
date — 

The date to use as the new value for the specified field.

Exceptions

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

File: PDProcs.h
Line: 12145
PDFileAttachmentSetFieldNumber() 
Product availability: All
Platform availability: All

Syntax

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

Sets the specified numeric field in the file attachment.

Parameters

attachment — 

The file attachment.

 
fieldID — 

The field identifier.

 
number — 

The number to use as the new value for the specified field.

Exceptions

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

File: PDProcs.h
Line: 12128
PDFileAttachmentSetFieldPrefix() 
Product availability: All
Platform availability: All

Syntax

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

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.

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

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

File: PDProcs.h
Line: 12163
PDFileAttachmentSetFieldStyle() 
Product availability: All
Platform availability: All

Syntax

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

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

Parameters

attachment — 

The file attachment.

 
fieldID — 

The field identifier.

 
styles — 

ASConstCab containing field styles for the specified field.

Exceptions

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

File: PDProcs.h
Line: 12111
PDFileAttachmentSetFieldStyledText() 
Product availability: All
Platform availability: All

Syntax

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

Sets the specified text field in the file attachment using styled 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

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

File: PDProcs.h
Line: 12086
PDFileAttachmentSetFieldText() 
Product availability: All
Platform availability: All

Syntax

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

Sets the specified text field in the file attachment.

Parameters

attachment — 

The file attachment.

 
fieldID — 

The field identifier.

 
text — 

The text to use as the new value for the specified field.

Exceptions

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

File: PDProcs.h
Line: 12077
PDFileAttachmentUpdateFromFile() 
Product availability: All
Platform availability: All

Syntax

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

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.

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.


File: PDProcs.h
Line: 12002



© 2004-2013 Adobe Systems Incorporated. All rights reserved.
Thu Jan 21 2016, 11:19 AM IST