PdfFileSpecification Class

Namespace:
GemBox.Pdf
Assembly:
GemBox.Pdf.dll

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
PdfAssociatedFileRelationshipType

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
NotSupportedException

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").

public string Description { get; set; }
Public Property Description As String
Property Value
String

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
PdfEmbeddedFile

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
PdfEncryptedPayload

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.

public bool IsUrl { get; set; }
Public Property IsUrl As Boolean
Property Value
Boolean

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.

public bool IsVolatile { get; set; }
Public Property IsVolatile As Boolean
Property Value
Boolean

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".

public string Name { get; set; }
Public Property Name As String
Property Value
String

The file specification string, or (if the IsUrl is true) a uniform resource locator.

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:

  • UF entry encoded either with PDFDoc or UTF16BE encoding for cross-platform and cross-language compatibility.
  • F entry encoded with ASCII encoding for backwards compatibility.
  • DOS, Mac and Unix entries are removed because they are obsolescent and should not be used by conforming writers.
Exceptions
ArgumentNullException

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
PdfPortfolioFieldValueDictionary

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
PdfPortfolioFolder

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
PdfCollection<KeyValuePair<PdfString, PdfEmbeddedFile>>

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").

public PdfImage Thumbnail { get; set; }
Public Property Thumbnail As PdfImage
Property Value
PdfImage

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
PdfEmbeddedFile

The related file added to the file specification's RelatedFiles.

Exceptions
ArgumentNullException

key is null.

InvalidOperationException

The EmbeddedFile is null.

SetEmbeddedFile()

Sets the EmbeddedFile to a new empty PdfEmbeddedFile.

public PdfEmbeddedFile SetEmbeddedFile()
Public Function SetEmbeddedFile As PdfEmbeddedFile
Returns
PdfEmbeddedFile

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
PdfEmbeddedFile

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
PdfEncryptedPayload

The file specification's EncryptedPayload.

Exceptions
ArgumentNullException

Value is null or Empty.

ToString()

Returns a String that represents this PdfFileSpecification instance.

public override string ToString()
Public Overrides Function ToString As String
Returns
String

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)

Extension Methods

Examples

See Also