GemBox.Pdf
  • Overview
  • Examples
  • Free version
  • Support
  • Pricelist

    Show / Hide Table of Contents

    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.

    • C#
    • VB.NET
    public sealed class PdfFileSpecification : PdfObject
    Public NotInheritable Class PdfFileSpecification
        Inherits PdfObject
    Inheritance:
    Object
    PdfObject
    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.

    • C#
    • VB.NET
    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").

    • C#
    • VB.NET
    public string Description { get; set; }
    Public Property Description As String
    Property Value
    String

    Descriptive text associated with the file specification.

    See Also
    PDF Specification ISO 32000-1:2008, section '7.11.3 File specification dictionaries'

    EmbeddedFile

    (Required if RelatedFiles collection is not empty; PDF 1.3) An embedded file stream (see 7.11.4, "Embedded File Streams").

    • C#
    • VB.NET
    public PdfEmbeddedFile EmbeddedFile { get; }
    Public ReadOnly Property EmbeddedFile As PdfEmbeddedFile
    Property Value
    PdfEmbeddedFile

    An embedded file stream.

    See Also
    PDF Specification ISO 32000-1:2008, section '7.11.3 File specification dictionaries'
    PDF Specification ISO 32000-1:2008, section '7.11.4 Embedded File Streams'

    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.

    • C#
    • VB.NET
    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.

    • C#
    • VB.NET
    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
    PDF Specification ISO 32000-1:2008, section '7.11.3 File specification dictionaries'
    PDF Specification ISO 32000-1:2008, section '7.11.5 URL Specifications'

    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.

    • C#
    • VB.NET
    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
    PDF Specification ISO 32000-1:2008, section '7.11.3 File specification dictionaries'

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

    • C#
    • VB.NET
    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
    PDF Specification ISO 32000-1:2008, section '7.11.3 File specification dictionaries'
    PDF Specification ISO 32000-1:2008, section '7.11.2 File Specification Strings'
    PDF Specification ISO 32000-1:2008, section '7.11.5 URL Specifications'

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

    • C#
    • VB.NET
    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
    PDF Specification ISO 32000-1:2008, section '7.11.3 File specification dictionaries'
    PDF Specification ISO 32000-1:2008, section '7.11.6 Collection Items'

    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.

    • C#
    • VB.NET
    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.

    • C#
    • VB.NET
    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
    PDF Specification ISO 32000-1:2008, section '7.11.3 File specification dictionaries'
    PDF Specification ISO 32000-1:2008, section '7.11.4.2 Related Files Arrays'

    Thumbnail

    (Optional; PDF 2.0) A stream object defining the thumbnail image for the file specification (see 12.3.4, "Thumbnail Images").

    • C#
    • VB.NET
    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
    PDF Specification ISO 32000-1:2008, section '12.3.4 Thumbnail Images'

    Methods

    AddRelatedFile(PdfString)

    Adds a new empty PdfEmbeddedFile to the RelatedFiles collection.

    • C#
    • VB.NET
    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.

    • C#
    • VB.NET
    public PdfEmbeddedFile SetEmbeddedFile()
    Public Function SetEmbeddedFile As PdfEmbeddedFile
    Returns
    PdfEmbeddedFile

    The file specification's EmbeddedFile.

    See Also
    PDF Specification ISO 32000-1:2008, section '7.11.3 File specification dictionaries'
    PDF Specification ISO 32000-1:2008, section '7.11.4 Embedded File Streams'

    SetEmbeddedFile(String)

    Sets the EmbeddedFile to a new PdfEmbeddedFile copied from the resource specified by the filePath.

    • C#
    • VB.NET
    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
    PDF Specification ISO 32000-1:2008, section '7.11.3 File specification dictionaries'
    PDF Specification ISO 32000-1:2008, section '7.11.4 Embedded File Streams'

    SetEncryptedPayload(String)

    Sets the EncryptedPayload toa new PdfEncryptedPayload with the specified cryptographicFilterName.

    • C#
    • VB.NET
    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.

    • C#
    • VB.NET
    public override string ToString()
    Public Overrides Function ToString As String
    Returns
    String

    A String that represents this PdfFileSpecification instance.

    Overrides
    Object.ToString()
    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

    PdfObjectExtensions.GetDictionary(PdfObject)
    PdfObjectExtensions.GetOrAddDictionary(PdfObject)
    PdfObjectExtensions.GetArray(PdfObject)

    Examples

    Embedded Files example
    Associated Files example
    Embedded Files example
    Portfolios example

    See Also

    PDF Specification ISO 32000-1:2008, section '7.11.3 File Specification Dictionaries'
    Back to top

    Facebook • Twitter • LinkedIn

    © GemBox Ltd. — All rights reserved.