PdfFileSpecification Class
Represents a full file specification that might include information related to one or more specific file systems with which a PDF file can refer to the contents of another file (PDF 1.1).
A file specification shall refer to a file external to the PDF file or to a file embedded within the referring PDF file, allowing its contents to be stored or transmitted along with the PDF file. The file is considered external to the PDF file in either case.
public sealed class PdfFileSpecification : PdfObject
Public NotInheritable Class PdfFileSpecification
Inherits PdfObject
- Inheritance:
- PdfFileSpecification
Properties
AssociatedRelationshipType
(Optional; PDF 2.0) A name value that represents the relationship between the component of this PDF document that refers to this PdfFileSpecification and the associated file denoted by this PdfFileSpecification.
Default value: Unspecified.
public PdfAssociatedFileRelationshipType AssociatedRelationshipType { get; set; }
Public Property AssociatedRelationshipType As PdfAssociatedFileRelationshipType
Property Value
A name value that represents the relationship between the component of this PDF document that refers to this PdfFileSpecification and the associated file denoted by this PdfFileSpecification.
Remarks
note
Unspecified is to be used only when no other value correctly reflects the relationship.
Second-class names (see Annex E, "PDF Name Registry") might be used to represent other types of relationships. In that case, AssociatedRelationshipType returns Custom.
note
The value of AssociatedRelationshipType does not explicitly provide any processing instructions for a PDF processor. It is provided for information and semantic purposes for those processors that are able to use such additional information.
Exceptions
Value Custom of enumeration PdfAssociatedFileRelationshipType is not supported in the requested operation.
Description
(Optional; PDF 1.6) Descriptive text associated with the file specification. It shall be used for files in the EmbeddedFiles name tree (see 7.7.4, "Name Dictionary").
Property Value
Descriptive text associated with the file specification.
See Also
EmbeddedFile
(Required if RelatedFiles collection is not empty; PDF 1.3) An embedded file stream (see 7.11.4, "Embedded File Streams").
public PdfEmbeddedFile EmbeddedFile { get; }
Public ReadOnly Property EmbeddedFile As PdfEmbeddedFile
Property Value
An embedded file stream.
See Also
EncryptedPayload
(PDF 2.0; Required if this file specification references an encrypted payload document) The value of this property is a PdfEncryptedPayload which identifies that the file specified in the EmbeddedFile is an encrypted payload.
public PdfEncryptedPayload EncryptedPayload { get; }
Public ReadOnly Property EncryptedPayload As PdfEncryptedPayload
Property Value
The value of this property is a PdfEncryptedPayload which identifies that the file specified in the EmbeddedFile is an encrypted payload.
IsUrl
Gets or sets a value indicating whether the URL file system shall be used to interpret this file specification.
When the IsUrl property in a PdfFileSpecification has the value true, the value of the Name property in that PdfFileSpecification is not a file specification string, but a uniform resource locator (URL) of the form defined in Internet RFC 3986, Uniform Resource Locators.
Default value: false.
Property Value
true if the URL file system shall be used to interpret this file specification; otherwise, false.
Remarks
The URL shall adhere to the character-encoding requirements specified in RFC 3986. Because 7-bit U.S. ASCII is a strict subset of PDFDoc, this value shall also be considered to be in that encoding.
See Also
IsVolatile
(Optional; PDF 1.2) A flag indicating whether the file referenced by the file specification is volatile (changes frequently with time). If the value is true, applications shall not cache a copy of the file. For example, a movie annotation referencing a URL to a live video camera could set this flag to true to notify the conforming reader that it should re-acquire the movie each time it is played.
Default value: false.
Property Value
A flag indicating whether the file referenced by the file specification is volatile (changes frequently with time).
See Also
Name
Gets or sets the file specification string of the form described in 7.11.2, "File Specification Strings", or (if the IsUrl is true) a uniform resource locator, as described in 7.11.5, "URL Specifications".
Property Value
Remarks
GemBox.Pdf tries to get this value from the following entries:
- On Mac OS system: UF, F, Mac, DOS, Unix.
- On UNIX system: UF, F, Unix, DOS, Mac.
- On DOS and all other systems: UF, F, DOS, Mac, Unix.
UF entry is decoded using either PDFDoc or UTF16BE encoding and all other entries (F, DOS, Mac, Unix) are decoded using Byte encoding.
GemBox.Pdf sets the following entries:
Exceptions
Value is null or Empty.
See Also
PortfolioFieldValues
(Optional; shall be indirect reference; PDF 1.7) A collection item dictionary, which shall be used to create the user interface for portable collections (see 7.11.6, "Collection Items").
public PdfPortfolioFieldValueDictionary PortfolioFieldValues { get; }
Public ReadOnly Property PortfolioFieldValues As PdfPortfolioFieldValueDictionary
Property Value
A collection item dictionary, which shall be used to create the user interface for portable collections.
See Also
PortfolioFolder
Gets the parent PdfPortfolioFolder or null if the PDF document is not a PDF Portfolio (Portfolio is null) or if this PdfFileSpecification is one of the root EmbeddedFiles contained in the PdfPortfolio.
public PdfPortfolioFolder PortfolioFolder { get; }
Public ReadOnly Property PortfolioFolder As PdfPortfolioFolder
Property Value
The parent PdfPortfolioFolder or null if the PDF document is not a PDF Portfolio (Portfolio is null) or if this PdfFileSpecification is one of the root EmbeddedFiles contained in the PdfPortfolio.
Remarks
This property performs a linear search in the EmbeddedFiles to find a key associated with this PdfFileSpecification, extracts an internal folder ID from the found key and then performs a search in the Portfolio folder tree to find a PdfPortfolioFolder with that ID.
RelatedFiles
(Optional; PDF 1.3) A related files array (see 7.11.4.2, "Related Files Arrays") identifying files that are related to the EmbeddedFile.
public PdfCollection<KeyValuePair<PdfString, PdfEmbeddedFile>> RelatedFiles { get; }
Public ReadOnly Property RelatedFiles As PdfCollection(Of KeyValuePair(Of PdfString, PdfEmbeddedFile))
Property Value
A related files array identifying files that are related to the EmbeddedFile.
See Also
Thumbnail
(Optional; PDF 2.0) A stream object defining the thumbnail image for the file specification (see 12.3.4, "Thumbnail Images").
Property Value
A stream object defining the thumbnail image for the file specification.
See Also
Methods
AddRelatedFile(PdfString)
Adds a new empty PdfEmbeddedFile to the RelatedFiles collection.
public PdfEmbeddedFile AddRelatedFile(PdfString key)
Public Function AddRelatedFile(key As PdfString) As PdfEmbeddedFile
Parameters
key
- PdfString
The name of one of the related file.
Returns
The related file added to the file specification's RelatedFiles.
Exceptions
key
is null.
The EmbeddedFile is null.
SetEmbeddedFile()
Sets the EmbeddedFile to a new empty PdfEmbeddedFile.
Returns
The file specification's EmbeddedFile.
See Also
SetEmbeddedFile(String)
Sets the EmbeddedFile to a new PdfEmbeddedFile copied from the resource specified by the filePath
.
public PdfEmbeddedFile SetEmbeddedFile(string filePath)
Public Function SetEmbeddedFile(filePath As String) As PdfEmbeddedFile
Parameters
filePath
- String
The location of the resource copied to the EmbeddedFile.
Returns
The file specification's EmbeddedFile.
See Also
SetEncryptedPayload(String)
Sets the EncryptedPayload toa new PdfEncryptedPayload with the specified cryptographicFilterName
.
public PdfEncryptedPayload SetEncryptedPayload(string cryptographicFilterName)
Public Function SetEncryptedPayload(cryptographicFilterName As String) As PdfEncryptedPayload
Parameters
cryptographicFilterName
- String
The name of the cryptographic filter used to encrypt the encrypted payload document. This allows a PDF processor to easily determine whether it has the appropriate cryptographic filter.
Returns
The file specification's EncryptedPayload.
Exceptions
Value is null or Empty.
ToString()
Returns a String that represents this PdfFileSpecification instance.
Returns
A String that represents this PdfFileSpecification instance.
Overrides
Remarks
This method should be used primarily for debugging purposes and should be considered volatile (format of its return value might change in future versions).
Inherited Properties
Metadata | (Optional; PDF 1.4) A metadata stream containing metadata for the component. (Inherited from PdfObject) |