pdftron::PDF::FileSpec Class Reference

FileSpec corresponds to the PDF file specification object. More...

#include <FileSpec.h>

List of all members.

Public Member Functions

 FileSpec (SDF::Obj f)
 Create a FileSpec and initialize it using given Cos/SDF object.
 FileSpec (const FileSpec &d)
 Copy constructor.
FileSpecoperator= (const FileSpec &d)
 Assignment operator.
bool operator== (const FileSpec &d)
 Compares two FileSpec-s for equality.
bool IsValid () const
bool Export (const UString &save_as="") const
 The function saves the data referenced by this FileSpec to an external file.
Filters::Filter GetFileData () const
 The function returns data referenced by this FileSpec.
UString GetFilePath () const
void SetDesc (const UString &desc)
 The functions sets the descriptive text associated with the file specification.
SDF::Obj GetSDFObj () const

Static Public Member Functions

static FileSpec Create (SDF::SDFDoc &doc, const char *path, bool embed=true)
 Creates a file specification for the given file.
static FileSpec CreateURL (SDF::SDFDoc &doc, const char *url)
 Creates a URL file specification.


Detailed Description

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:

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.


Constructor & Destructor Documentation

pdftron::PDF::FileSpec::FileSpec ( SDF::Obj  f  ) 

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.

pdftron::PDF::FileSpec::FileSpec ( const FileSpec d  ) 

Copy constructor.


Member Function Documentation

static FileSpec pdftron::PDF::FileSpec::Create ( SDF::SDFDoc doc,
const char *  path,
bool  embed = true 
) [static]

Creates a file specification for the given file.

By default, the specified file is embedded in PDF.

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.
Returns:
newly created FileSpec object.

static FileSpec pdftron::PDF::FileSpec::CreateURL ( SDF::SDFDoc doc,
const char *  url 
) [static]

Creates a URL file specification.

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.
Returns:
newly created FileSpec object.

FileSpec& pdftron::PDF::FileSpec::operator= ( const FileSpec d  ) 

Assignment operator.

bool pdftron::PDF::FileSpec::operator== ( const FileSpec d  ) 

Compares two FileSpec-s for equality.

The comparison will return true only if both annotations share the same underlying SDF/Cos object.

bool pdftron::PDF::FileSpec::IsValid (  )  const

Returns:
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.

bool pdftron::PDF::FileSpec::Export ( const UString save_as = ""  )  const

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

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

Returns:
true is the file was saved successfully, false otherwise.

Filters::Filter pdftron::PDF::FileSpec::GetFileData (  )  const

The function returns data referenced by this FileSpec.

Returns:
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.

UString pdftron::PDF::FileSpec::GetFilePath (  )  const

Returns:
The file path for this file specification.
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.

void pdftron::PDF::FileSpec::SetDesc ( const UString desc  ) 

The functions sets the descriptive text associated with the file specification.

This test is typically used in the EmbeddedFiles name tree.

SDF::Obj pdftron::PDF::FileSpec::GetSDFObj (  )  const

Returns:
The underlying SDF/Cos object.


© 2002-2010 PDFTron Systems Inc.