All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
pdftron::SDF::SDFDoc Class Reference

#include <SDFDoc.h>

Public Types

enum  SaveOptions {
  e_incremental = 0x01, e_remove_unused = 0x02, e_hex_strings = 0x04, e_omit_xref = 0x08,
  e_linearized = 0x10, e_compatibility = 0x20
}
 

Public Member Functions

 SDFDoc ()
 
 SDFDoc (const UString &filepath)
 
 SDFDoc (const char *filepath)
 
 SDFDoc (Filters::Filter stream)
 
 SDFDoc (unsigned char *buf, size_t buf_size)
 
 ~SDFDoc ()
 
void Close ()
 
bool IsEncrypted ()
 
bool InitSecurityHandler (void *custom_data=0)
 
bool InitStdSecurityHandler (const char *password, int password_sz)
 
bool InitStdSecurityHandler (const pdftron::UString &password)
 
bool InitStdSecurityHandler (const std::vector< UInt8 > &password_buf)
 
bool IsModified () const
 
bool HasRepairedXRef () const
 
bool IsFullSaveRequired () const
 
Obj GetTrailer ()
 
Obj GetObj (const UInt32 obj_num) const
 
Obj ImportObj (Obj obj, bool deep_copy)
 
std::vector< ObjImportObjs (const std::vector< Obj > &obj_list)
 
UInt32 XRefSize () const
 
void ClearMarks ()
 
void Save (const UString &path, UInt32 flags, const char *header)
 
void Save (const UString &path, UInt32 flags, Common::ProgressMonitor *progress, const char *header)
 
std::vector< unsigned char > Save (UInt32 flags, const char *header)
 
void Save (const char *&out_buf, size_t &out_buf_size, UInt32 flags, Common::ProgressMonitor *progress, const char *header)
 
void Save (Filters::Filter stream, UInt32 flags, const char *header)
 
const char * GetHeader () const
 
SecurityHandler GetSecurityHandler ()
 
void SetSecurityHandler (SecurityHandler handler)
 
void RemoveSecurity ()
 
void Swap (UInt32 obj_num1, UInt32 obj_num2)
 
Obj CreateIndirectName (const char *name)
 
Obj CreateIndirectArray ()
 
Obj CreateIndirectBool (bool value)
 
Obj CreateIndirectDict ()
 
Obj CreateIndirectNull ()
 
Obj CreateIndirectNumber (double value)
 
Obj CreateIndirectString (const UChar *value, UInt32 size)
 
Obj CreateIndirectString (const UString &str)
 
Obj CreateIndirectStream (Filters::FilterReader &data, Filters::Filter filter_chain=Filters::Filter())
 
Obj CreateIndirectStream (const char *data, const size_t data_size, Filters::Filter filter_chain=Filters::Filter())
 
bool IsLinearized () const
 
SDF::Obj GetLinearizationDict () const
 
SDF::Obj GetHintStream () const
 
void Lock ()
 
void Unlock ()
 
bool TryLock (int milliseconds=0)
 
void LockRead ()
 
void UnlockRead ()
 
bool TryLockRead (int milliseconds=0)
 
UString GetFileName () const
 
void EnableDiskCaching (bool use_cache_flag)
 
ptrdiff_t GetHandleInternal ()
 

Static Public Member Functions

static SDFDocCreateInternal (ptrdiff_t impl)
 

Detailed Description

SDFDoc is a low-level document representing a graph of SDF::Obj nodes that can be used to build higher-level document models such as PDF (Portable Document Format) or FDF (Forms Document Format).

SDFDoc brings together document security, document utility methods, and all SDF objects.

A SDF document can be created from scratch using a default constructor:

SDFDoc mydoc; Obj trailer = mydoc.GetTrailer();

SDF document can be also created from an existing file (e.g. an external PDF document):

* SDFDoc mydoc("in.pdf");
* Obj trailer = mydoc.GetTrailer();
*

or from a memory buffer or some other Filter/Stream such as a HTTP Filter connection:

* MemoryFilter memory = ....
* SDFDoc mydoc(memory);
* Obj trailer = mydoc.GetTrailer();
*

Finally SDF document can be accessed from a high-level PDF document as follows:

* PDFDoc doc("in.pdf");
* SDFDoc& mydoc = doc.GetSDFDoc();
* Obj trailer = mydoc.GetTrailer();
*

Note that the examples above used doc.GetTrailer() in order to access document trailer, the starting SDF object (root node) in every document. Following the trailer links, it is possible to visit all low-level objects in a document (e.g. all pages, outlines, fonts, etc).

SDFDoc also provides utility methods used to import objects and object collections from one document to another. These methods can be useful for copy operations between documents such as a high-level page merge and document assembly.

Definition at line 67 of file SDFDoc.h.

Member Enumeration Documentation

Enumerator
e_incremental 
e_remove_unused 
e_hex_strings 
e_omit_xref 
e_linearized 
e_compatibility 

Definition at line 335 of file SDFDoc.h.

Constructor & Destructor Documentation

pdftron::SDF::SDFDoc::SDFDoc ( )

Default constructor. Creates a new document. The new document contains only trailer and Info dictionary. To build the rest of the document get document's root dictionary using GetTrailer() and populate it with new key/value pairs.

pdftron::SDF::SDFDoc::SDFDoc ( const UString filepath)

Open a SDF/Cos document from a file.

Parameters
filepath- path name to the file.
Note
Make sure to call InitStdSecurityHandler() or InitSecurityHandler() after SDFDoc(...) in case the document is encrypted.
pdftron::SDF::SDFDoc::SDFDoc ( const char *  filepath)
pdftron::SDF::SDFDoc::SDFDoc ( Filters::Filter  stream)

Open a SDF/Cos document from a Filter (i.e. a data stream) object.

Parameters
stream- input stream containing a serialized document. The input stream may be a random-access file, memory buffer, slow HTTP connection etc.
Note
if the input stream doesn't support Seek() operation the document will load whole data stream in memory before parsing. In case of linearized PDF, the document may be parsed on-the-fly while it is being loaded in memory. Note that since StdFile implements Seek() interface, the document does not have to be fully in memory before it is used.
Make sure to call InitStdSecurityHandler() or InitSecurityHandler() after SDFDoc(...) in case the document is encrypted.
pdftron::SDF::SDFDoc::SDFDoc ( unsigned char *  buf,
size_t  buf_size 
)

Open a SDF/Cos document from a memory buffer.

Note
the document should be fully loaded in the memory buffer.
the buffer ownership is not transfered to the document so the user should clean-up if necessary.
Parameters
buf- a memory buffer containing the serialized document
buf_size- the size of memory buffer.
Note
Make sure to call InitStdSecurityHandler() or InitSecurityHandler() after SDFDoc(...) in case the document is encrypted.
pdftron::SDF::SDFDoc::~SDFDoc ( )

Destructor

Member Function Documentation

void pdftron::SDF::SDFDoc::ClearMarks ( )

Removes 'marked' flag from all objects in cross reference table.

void pdftron::SDF::SDFDoc::Close ( )

Close SDFDoc

Obj pdftron::SDF::SDFDoc::CreateIndirectArray ( )

Used to create SDF/Cos indirect object.

Unlike direct objects, indirect objects can be referenced by more than one object (i.e. indirect objects they can be shared).

Note
In C++ doc.CreateIndirect???(...) is equivalent to ???::CreateIndirect(...).
Obj pdftron::SDF::SDFDoc::CreateIndirectBool ( bool  value)

Used to create SDF/Cos indirect object.

Unlike direct objects, indirect objects can be referenced by more than one object (i.e. indirect objects they can be shared).

Parameters
value- indirect boolean to create.
Note
In C++ doc.CreateIndirect???(...) is equivalent to ???::CreateIndirect(...).
Obj pdftron::SDF::SDFDoc::CreateIndirectDict ( )
Obj pdftron::SDF::SDFDoc::CreateIndirectName ( const char *  name)

Used to create SDF/Cos indirect object.

Unlike direct objects, indirect objects can be referenced by more than one object (i.e. indirect objects they can be shared).

Parameters
name- indirect const char* object to create.
Note
In C++ doc.CreateIndirect???(...) is equivalent to ???::CreateIndirect(...).
Obj pdftron::SDF::SDFDoc::CreateIndirectNull ( )
Obj pdftron::SDF::SDFDoc::CreateIndirectNumber ( double  value)
Obj pdftron::SDF::SDFDoc::CreateIndirectStream ( Filters::FilterReader data,
Filters::Filter  filter_chain = Filters::Filter() 
)
Note
After calling the following methods the filter object is invalidated and should not be used
Obj pdftron::SDF::SDFDoc::CreateIndirectStream ( const char *  data,
const size_t  data_size,
Filters::Filter  filter_chain = Filters::Filter() 
)
Obj pdftron::SDF::SDFDoc::CreateIndirectString ( const UChar value,
UInt32  size 
)
Obj pdftron::SDF::SDFDoc::CreateIndirectString ( const UString str)
static SDFDoc* pdftron::SDF::SDFDoc::CreateInternal ( ptrdiff_t  impl)
static
void pdftron::SDF::SDFDoc::EnableDiskCaching ( bool  use_cache_flag)

A document uses a temporary file which is used to cache the contents of any new stream object created in the document (that is the default behavior).

Parameters
use_cache_flag- true to enable caching, false to disable caching. Use this function to enable or disable this feature dynamically.
UString pdftron::SDF::SDFDoc::GetFileName ( ) const
Returns
The filename of the document if the document is loaded from disk, or empty string if the document is not yet saved or is loaded from a memory buffer.
ptrdiff_t pdftron::SDF::SDFDoc::GetHandleInternal ( )
const char* pdftron::SDF::SDFDoc::GetHeader ( ) const
Returns
the header string identifying the document version to which the file conforms. For a file conforming to PDF version 1.4, the header should be PDF-1.4. In general header strings have the following syntax: AAA-N.n where AAA identifies document specification (such as PDF, FDF, PJTF etc), N is the major version and n is the minor version. The new header string can be set during a full save (see SDFDoc::Save()). For a document that is not serialized the function returns an empty string.
SDF::Obj pdftron::SDF::SDFDoc::GetHintStream ( ) const

Returns document's initial linearization hint stream if it is available.

Returns
- the linearization hint stream of the original document or NULL if the hint stream is not available.
SDF::Obj pdftron::SDF::SDFDoc::GetLinearizationDict ( ) const

Returns document's initial linearization dictionary if it is available.

Returns
- the linearization dictionary of the original document or NULL if the dictionary is not available.
Obj pdftron::SDF::SDFDoc::GetObj ( const UInt32  obj_num) const
Parameters
obj_num- object number of the object to retrieve.
Returns
- the latest version of the object matching specified object number.
Exceptions
-exception is thrown if the object is not found.
SecurityHandler pdftron::SDF::SDFDoc::GetSecurityHandler ( )
Returns
Currently selected SecurityHandler.
Note
InitSecurityHandler() should be called before GetSecurityHandler() in order to initialize the handler.
Returned security handler can be modified in order to change the security settings of the existing document. Changes to the current handler will not invalidate the access to the original file and will take effect during document Save().
If the security handler is modified, document will perform a full save even if e_incremental was given as a flag in Save() method.
Obj pdftron::SDF::SDFDoc::GetTrailer ( )
Returns
- A dictionary representing the root of the document (i.e. a document trailer dictionary)
bool pdftron::SDF::SDFDoc::HasRepairedXRef ( ) const

Checks whether or not the underlying file has an XRef table that had to be repaired when the file was opened. If the document had an invalid XRef table when opened, PDFNet will have repaired the XRef table for its working representation of the document.

Returns
- true if document was found to be corrupted, and was repaired, during opening and has not been saved since.
Note
- If this function returns true, it is not possible to incrementally save the document (see http://www.pdftron.com/kb_corrupt_xref)
Obj pdftron::SDF::SDFDoc::ImportObj ( Obj  obj,
bool  deep_copy 
)
Parameters
obj- an object to import.
deep_copy- a boolean indicating whether to perform a deep or shallow copy. In case of shallow copy all indirect references will be set to null.

If the object belongs to a document the function will perform deep or shallow clone depending whether deep_copy flag was specified.

If the object does not belong to any document ImportObj does not take the object ownership. ImportObj copies the source object and it is users responsibility to delete free objects.

Returns
- a pointer to the root indirect object in this document
std::vector<Obj> pdftron::SDF::SDFDoc::ImportObjs ( const std::vector< Obj > &  obj_list)

The function performs a deep copy of all objects specified in the 'obj_list'. If objects in the list are directly or indirectly referring to the same object/s, only one copy of the shared object/s will be copied. Therefore, unlike repeated calls to ImportObj, this method will import only one copy of shared objects (objects representing an intersection of graphs specified through 'obj_list' of root pointers.

Note
- All object in the import list must belong to the same source document.
- The function does not perform the shallow copy since ImportObj() can be used instead.
Parameters
obj- a list of root objects to import. All directly or indirectly objects will be imported as well.
Returns
- a list of imported root objects in this document
bool pdftron::SDF::SDFDoc::InitSecurityHandler ( void *  custom_data = 0)

Initializes document's SecurityHandler. This version of InitSecurityHandler() works with Standard and Custom PDF security and can be used in situations where the password is obtained dynamically via user feedback. See EncTest sample for example code.

This function should be called immediately after an encrypted document is opened. The function does not have any side effects on documents that are not encrypted.

If the security handler was successfully initialized it can be later obtained using GetSecurityHandler() method.

Exceptions
Anexception is thrown if the matching handler for document's security was not found in the global SecurityManager. In this case, you need to register additional custom security handlers with the global SecurityManager (using SecurityManagerSingleton).
Returns
true if the SecurityHandler was successfully initialized (this may include authentication data collection, verification etc.), false otherwise.
Parameters
custom_dataAn optional parameter used to specify custom data that should be passed in SecurityHandler::Initialize() callback.
bool pdftron::SDF::SDFDoc::InitStdSecurityHandler ( const char *  password,
int  password_sz 
)

Initializes document's SecurityHandler using the supplied password. This version of InitSecurityHandler() assumes that document uses Standard security and that a password is specified directly.

This function should be called immediately after an encrypted document is opened. The function does not have any side effects on documents that are not encrypted.

If the security handler was successfully initialized, it can be later obtained using GetSecurityHandler() method.

Returns
true if the given password successfully unlocked the document, false otherwise.
Exceptions
Anexception is thrown if the document's security Filter is not 'Standard'. In this case, you need to register additional custom security handlers with the global SecurityManager (SecurityManagerSingleton).
Parameters
passwordSpecifies the password used to open the document without any user feedback. If you would like to dynamically obtain the password, you need to derive a custom class from StdSecurityHandler() and use InitSecurityHandler() without any parameters. See EncTest sample for example code.
password_szAn optional parameter used to specify the size of the password buffer, in bytes. If the 'password_sz' is 0, or if the parameter is not specified, the function assumes that the string is null terminated.
Remarks
Deprecated. Use versions that accepts UString or buffer instead.
bool pdftron::SDF::SDFDoc::InitStdSecurityHandler ( const pdftron::UString password)

Initializes document's SecurityHandler using the supplied password. This version of InitSecurityHandler() assumes that document uses Standard security and that a password is specified directly.

This function should be called immediately after an encrypted document is opened. The function does not have any side effects on documents that are not encrypted.

If the security handler was successfully initialized, it can be later obtained using GetSecurityHandler() method.

Parameters
passwordSpecifies the password used to open the document without any user feedback. If you would like to dynamically obtain the password, you need to derive a custom class from StdSecurityHandler() and use InitSecurityHandler() without any parameters. See EncTest sample for example code.
Returns
true if the given password successfully unlocked the document, false otherwise.
Exceptions
Anexception is thrown if the document's security Filter is not 'Standard'. In this case, you need to register additional custom security handlers with the global SecurityManager (SecurityManagerSingleton).
bool pdftron::SDF::SDFDoc::InitStdSecurityHandler ( const std::vector< UInt8 > &  password_buf)

Initializes document's SecurityHandler using the supplied password. This version of InitSecurityHandler() assumes that document uses Standard security and that a password is specified directly.

This function should be called immediately after an encrypted document is opened. The function does not have any side effects on documents that are not encrypted.

If the security handler was successfully initialized, it can be later obtained using GetSecurityHandler() method.

Parameters
password_bufSpecifies the password used to open the document without any user feedback. If you would like to dynamically obtain the password, you need to derive a custom class from StdSecurityHandler() and use InitSecurityHandler() without any parameters. See EncTest sample for example code.
Returns
true if the given password successfully unlocked the document, false otherwise.
Exceptions
Anexception is thrown if the document's security Filter is not 'Standard'. In this case, you need to register additional custom security handlers with the global SecurityManager (SecurityManagerSingleton).
bool pdftron::SDF::SDFDoc::IsEncrypted ( )
Returns
true if the document is/was originally encrypted false otherwise.
bool pdftron::SDF::SDFDoc::IsFullSaveRequired ( ) const
Returns
- true if the document requires full save.
bool pdftron::SDF::SDFDoc::IsLinearized ( ) const

Call this function to determine whether the document is represented in linearized (fast web view) format.

Returns
- true if document is stored in fast web view format, false otherwise.
Note
any changes to the document can invalidate linearization. The function will return 'true' only if the original document is linearized and if it is not modified.

In order to provide good performance over relatively slow communication links, PDFNet can generate PDF documents with linearized objects and hint tables that can allow a PDF viewer application to download and view one page of a PDF file at a time, rather than requiring the entire file (including fonts and images) to be downloaded before any of it can be viewed.

To save a document in linearized (fast web view) format you only need to pass 'SDFDoc.SaveOptions.e_linearized' flag in the Save method.

bool pdftron::SDF::SDFDoc::IsModified ( ) const
Returns
- true if document was modified, false otherwise
void pdftron::SDF::SDFDoc::Lock ( )

Locks the document to prevent competing threads from accessing the document at the same time. Threads attempting to access the document will wait in suspended state until the thread that owns the lock calls doc.Unlock().

void pdftron::SDF::SDFDoc::LockRead ( )

Locks the document to prevent competing write threads (using Lock()) from accessing the document at the same time. Other reader threads however, will be allowed to access the document. Threads attempting to obtain write access to the document will wait in suspended state until the thread that owns the lock calls doc.UnlockRead(). Note: To avoid deadlocks obtaining a write lock while holding a read lock is not permitted and will throw an exception. If this situation is encountered please either unlock the read lock before the write lock is obtained or acquire a write lock (rather than read lock) in the first place.

void pdftron::SDF::SDFDoc::RemoveSecurity ( )

This function removes document security.

void pdftron::SDF::SDFDoc::Save ( const UString path,
UInt32  flags,
const char *  header 
)

Saves the document to a file.

If a full save is requested to the original path, the file is saved to a file system-determined temporary file, the old file is deleted, and the temporary file is renamed to path.

A full save with remove unused or linearization option may re-arrange object in the cross reference table. Therefore all pointers and references to document objects and resources should be re acquired in order to continue document editing.

In order to use incremental save the specified path must match original path and e_incremental flag bit should be set.

Parameters
path- The full path name to which the file is saved.
flags- A bit field composed of an OR of the SDFDoc::SaveOptions values.
progress- A pointer to the progress interface. NULL if progress tracking is not required.
header- File header. A new file header is set only during full save.
Exceptions
-if the file can't be opened for saving or if there is a problem during Save an Exception object will be thrown.
Note
- Save will modify the SDFDoc object's internal representation. As such, the user should acquire a write lock before calling save.
void pdftron::SDF::SDFDoc::Save ( const UString path,
UInt32  flags,
Common::ProgressMonitor *  progress,
const char *  header 
)
std::vector<unsigned char> pdftron::SDF::SDFDoc::Save ( UInt32  flags,
const char *  header 
)

Saves the document to a memory buffer.

Parameters
out_bufa pointer to the buffer containing the serialized version of the document. (C++ Note) The buffer is owned by a document and the client doesn't need to do any initialization or cleanup.
out_buf_sizethe size of the serialized document (i.e. out_buf) in bytes.
flags- A bit field composed of an OR of the SDFDoc::SaveOptions values. Note that this method ignores e_incremental flag.
progress- A pointer to the progress interface. NULL if progress tracking is not required.
header- File header. A new file header is set only during full save.
Exceptions
-if there is a problem during Save an Exception object will be thrown.
Note
- Save will modify the SDFDoc object's internal representation. As such, the user should acquire a write lock before calling save.
void pdftron::SDF::SDFDoc::Save ( const char *&  out_buf,
size_t &  out_buf_size,
UInt32  flags,
Common::ProgressMonitor *  progress,
const char *  header 
)
void pdftron::SDF::SDFDoc::Save ( Filters::Filter  stream,
UInt32  flags,
const char *  header 
)

Saves the document to a stream.

Parameters
streamThe output stream where to write data.
flags- A bit field composed of an OR of the SDFDoc::SaveOptions values.
progress- A pointer to the progress interface. NULL if progress tracking is not required.
header- File header. A new file header is set only during full save. See also GetHeader()
Exceptions
-if there is a problem during Save an Exception object will be thrown.
Note
- Save will modify the SDFDoc object's internal representation. As such, the user should acquire a write lock before calling save.
void pdftron::SDF::SDFDoc::SetSecurityHandler ( SecurityHandler  handler)

The function sets a new SecurityHandler as the current security handler.

Parameters
handler- new SecurityHandler
Note
Setting a new security handler will not invalidate the access to the original file and will take effect during document Save().
If the security handler is modified, document will perform a full save even if e_incremental was given as a flag in Save() method.
void pdftron::SDF::SDFDoc::Swap ( UInt32  obj_num1,
UInt32  obj_num2 
)

Sometimes it is desirable to modify all indirect references to a given indirect object. It would be inefficient to manually search for all indirect references to a given indirect object.

A more efficient and less error prone method is to replace the indirect object in the cross reference table with a new object. This way the object that is referred to is modified (or replaced) and indirect references do not have to be changed.

Parameters
obj_num1- object number of first object to be swapped.
obj_num2- object number of second object to be swapped.
Exceptions
thefunction throws exception in case the swap can't be performed.
bool pdftron::SDF::SDFDoc::TryLock ( int  milliseconds = 0)

Try locking the document, waiting no longer than specified number of milliseconds.

Parameters
milliseconds- max number of milliseconds to wait for the document to lock
Returns
true if the document is locked for multi-threaded access, false otherwise.
bool pdftron::SDF::SDFDoc::TryLockRead ( int  milliseconds = 0)

Try locking the document, waiting no longer than specified number of milliseconds.

Parameters
milliseconds- max number of milliseconds to wait for the document to lock
Returns
true if the document is locked for multi-threaded access, false otherwise.
void pdftron::SDF::SDFDoc::Unlock ( )

Removes the lock from the document.

void pdftron::SDF::SDFDoc::UnlockRead ( )

Removes the lock from the document.

UInt32 pdftron::SDF::SDFDoc::XRefSize ( ) const
Returns
- The size of cross reference table

The documentation for this class was generated from the following file: