PTFileSpec

@interface PTFileSpec : NSObject

FileSpec corresponds to the PDF file specification object.

A PDF file can refer to the contents of another file by using a file specification, which can take either of the following forms:

  • A simple file specification gives just the name of the target file in a standard format, independent of the naming conventions of any particular file system.

  • A full file specification includes information related to one or more specific file systems.

  • A URL reference.

Although the file designated by a file specification is normally external to the PDF file referring to it, it is also possible to embed the file allowing its contents to be stored or transmitted along with the PDF file. However, embedding a file does not change the presumption that it is external to (or separate from) the PDF file.

For more details on file specifications, please refer to Section 3.10, ‘File Specifications’ in the PDF Reference Manual.

  • Creates a file specification for the given file. By default, the specified file is embedded in PDF.

    Declaration

    Objective-C

    + (PTFileSpec *)Create:(PTSDFDoc *)doc path:(NSString *)path embed:(BOOL)embed;

    Swift

    class func create(_ doc: PTSDFDoc!, path: String!, embed: Bool) -> PTFileSpec!

    Parameters

    doc

    - A document to which the FileSpec should be added. To obtain SDFDoc from PDFDoc use PDFDoc::GetSDFDoc() or Obj::GetDoc().
    path

    - The path to convert into a file specification.
    embed

    - A flag indicating whether to embed specified in the PDF. By default, all files are embedded.

    Return Value

    newly created FileSpec object.

  • Creates a URL file specification.

    Declaration

    Objective-C

    + (PTFileSpec *)CreateURL:(PTSDFDoc *)doc url:(NSString *)url;

    Swift

    class func createURL(_ doc: PTSDFDoc!, url: String!) -> PTFileSpec!

    Parameters

    doc

    - A document to which the FileSpec should be added. To obtain SDFDoc from PDFDoc use PDFDoc::GetSDFDoc() or Obj::GetDoc().
    url

    - A uniform resource locator (URL) of the form defined in Internet RFC 1738, Uniform Resource Locators Specification.

    Return Value

    newly created FileSpec object.

  • Create a FileSpec and initialize it using given Cos/SDF object.

    Note

    The constructor does not copy any data, but is instead the logical equivalent of a type cast.

    Declaration

    Objective-C

    - (instancetype)initWithF:(PTObj *)f;

    Swift

    init!(f: PTObj!)

  • Undocumented

    Declaration

    Objective-C

    - (BOOL)isEqualTo: (PTFileSpec*)d;

    Swift

    func isEqual(to d: PTFileSpec!) -> Bool

  • Declaration

    Objective-C

    - (BOOL)IsValid;

    Swift

    func isValid() -> Bool

    Return Value

    whether this is a valid (non-null) FileSpec. If the function returns false the underlying SDF/Cos object is null or is not valid and the FileSpec object should be treated as null as well.

  • The function saves the data referenced by this FileSpec to an external file.

    If the file is embedded, the function saves the embedded file. If the file is not embedded, the function will copy the external file. If the file is not embedded and the external file can’t be found, the function returns false.

    Declaration

    Objective-C

    - (BOOL)Export:(NSString *)save_as;

    Swift

    func export(_ save_as: String!) -> Bool

    Parameters

    save_as

    An optional parameter indicating the filepath and filename where the data should be saved. If this parameter is not specified, the function will attempt to save the file using FileSpec.GetFilePath().

    Return Value

    true is the file was saved successfully, false otherwise.

  • The function returns data referenced by this FileSpec.

    Declaration

    Objective-C

    - (PTFilter *)GetFileData;

    Swift

    func getFileData() -> PTFilter!

    Return Value

    A stream (filter) containing file data. If the file is embedded, the function returns a stream to the embedded file. If the file is not embedded, the function will return a stream to the external file. If the file is not embedded and the external file can’t be found, the function returns NULL.

  • If the FileSpec is a dictionary, a corresponding platform specific path is returned (DOS, Mac, or Unix). Otherwise the function returns the path represented in the form described in Section 3.10.1, ‘File Specification Strings,’ or , if the file system is URL, as a uniform resource locator (URL). If the FileSpec is not valid, an empty string is returned.

    Declaration

    Objective-C

    - (NSString *)GetFilePath;

    Swift

    func getFilePath() -> String!

    Return Value

    The file path for this file specification.

  • The functions sets the descriptive text associated with the file specification. This test is typically used in the EmbeddedFiles name tree.

    Declaration

    Objective-C

    - (void)SetDesc:(NSString *)desc;

    Swift

    func setDesc(_ desc: String!)

  • Declaration

    Objective-C

    - (PTObj *)GetSDFObj;

    Swift

    func getSDFObj() -> PTObj!

    Return Value

    The underlying SDF/Cos object.

PTAdditions

  • Returns the descriptive text associated with the file specification.

    Declaration

    Objective-C

    - (nullable NSString *)GetDesc;

    Swift

    func getDesc() -> String?

  • Sets the file path for this file specification.

    Declaration

    Objective-C

    - (void)SetFilePath:(nonnull NSString *)filePath;

    Swift

    func setFilePath(_ filePath: String)

    Parameters

    filePath

    The file path to set for this file specification.

  • Returns whether the file for this file specification is embedded in the PDF document.

    Declaration

    Objective-C

    - (BOOL)IsEmbedded;

    Swift

    func isEmbedded() -> Bool

  • Returns the embedded file dictionary object for this file specification, if the file is embedded.

    See

    -IsEmbedded

    Declaration

    Objective-C

    - (nullable PTObj *)GetEmbeddedFile;

    Swift

    func getEmbeddedFile() -> PTObj?

  • Returns the subtype of the embedded file, if the file is embedded.

    See

    -IsEmbedded

    See

    -GetEmbeddedFile

    Declaration

    Objective-C

    - (nullable NSString *)GetEmbeddedFileType;

    Swift

    func getEmbeddedFileType() -> String?

  • Sets the subtype of the embedded file to the specified value.

    If the file for this file specification is not embedded, this method throws an exception.

    Declaration

    Objective-C

    - (void)SetEmbeddedFileType:(nonnull NSString *)type;

    Swift

    func setEmbeddedFileType(_ type: String)

    Parameters

    type

    the subtype of the embedded file