![]() |
#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 } |
Public Member Functions | |
SDFDoc () | |
Default constructor. | |
SDFDoc (const UString &filepath) | |
Open a SDF/Cos document from a file. | |
SDFDoc (const char *filepath) | |
SDFDoc (Filters::Filter stream) | |
Open a SDF/Cos document from a Filter (i.e. | |
SDFDoc (const char *buf, size_t buf_size) | |
Open a SDF/Cos document from a memory buffer. | |
~SDFDoc () | |
Destructor. | |
bool | IsEncrypted () |
bool | InitSecurityHandler (void *custom_data=0) |
Initializes document's SecurityHandler. | |
bool | InitStdSecurityHandler (const char *password, int password_sz=0) |
Initializes document's SecurityHandler using the supplied password. | |
bool | IsModified () const |
bool | IsFullSaveRequired () const |
Obj | GetTrailer () |
Obj | GetObj (const UInt32 obj_num) const |
Obj | ImportObj (Obj obj, bool deep_copy) |
std::vector< Obj > | ImportObjs (const std::vector< Obj > &obj_list) |
The function performs a deep copy of all objects specified in the 'obj_list'. | |
UInt32 | XRefSize () const |
void | ClearMarks () |
Removes 'marked' flag from all objects in cross reference table. | |
void | Save (const UString &path, UInt32 flags, Common::ProgressMonitor *progress, const char *header) |
Saves the document to a file. | |
void | Save (const char *&out_buf, size_t &out_buf_size, UInt32 flags, Common::ProgressMonitor *progress, const char *header) |
Saves the document to a memory buffer. | |
const char * | GetHeader () const |
SecurityHandler | GetSecurityHandler () |
void | SetSecurityHandler (SecurityHandler handler) |
The function sets a new SecurityHandler as the current security handler. | |
void | RemoveSecurity () |
This function removes document security. | |
void | Swap (UInt32 obj_num1, UInt32 obj_num2) |
Sometimes it is desirable to modify all indirect references to a given indirect object. | |
Obj | CreateIndirectName (const char *name) |
The following list of methods is used to create SDF/Cos indirect objects. | |
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 |
Call this function to determine whether the document is represented in linearized (fast web view) format. | |
SDF::Obj | GetLinearizationDict () const |
Returns document's initial linearization dictionary if it is available. | |
SDF::Obj | GetHintStream () const |
Returns document's initial linearization hint stream if it is available. | |
void | Lock () |
Locks the document to prevent competing threads from accessing the document at the same time. | |
void | Unlock () |
Removes the lock from the document. | |
bool | IsLocked () |
bool | TryLock (int milliseconds=0) |
Try locking the document, waiting no longer than specified number of milliseconds. | |
UString | GetFileName () const |
void | 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). |
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();
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.
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.
filepath | - path name to the file. |
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.
stream | - input stream containing a serialized document. The input stream may be a random-access file, memory buffer, slow HTTP connection etc. |
Make sure to call InitStdSecurityHandler() or InitSecurityHandler() after SDFDoc(...) in case the document is encrypted.
pdftron::SDF::SDFDoc::SDFDoc | ( | const char * | buf, | |
size_t | buf_size | |||
) |
Open a SDF/Cos document from a memory buffer.
the buffer ownership is not transfered to the document so the user should clean-up if necessary.
buf | - a memory buffer containing the serialized document | |
buf_size | - the size of memory buffer. |
pdftron::SDF::SDFDoc::~SDFDoc | ( | ) |
Destructor.
bool pdftron::SDF::SDFDoc::IsEncrypted | ( | ) |
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.
An | exception 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). |
custom_data | An 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 = 0 | |||
) |
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.
An | exception 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). |
password | Specifies 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_len | An 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. |
bool pdftron::SDF::SDFDoc::IsModified | ( | ) | const |
bool pdftron::SDF::SDFDoc::IsFullSaveRequired | ( | ) | const |
Obj pdftron::SDF::SDFDoc::GetTrailer | ( | ) |
- | obj_num object number of the object to retrieve. |
- | exception is thrown if the object is not found. |
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 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.
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.
- The function does not perform the shallow copy since ImportObj() can be used instead.
obj | - a list of root objects to import. All directly or indirectly objects will be imported as well. |
UInt32 pdftron::SDF::SDFDoc::XRefSize | ( | ) | const |
void pdftron::SDF::SDFDoc::ClearMarks | ( | ) |
Removes 'marked' flag from all objects in cross reference table.
void pdftron::SDF::SDFDoc::Save | ( | const UString & | path, | |
UInt32 | flags, | |||
Common::ProgressMonitor * | progress, | |||
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.
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. |
- | if the file can't be opened for saving or if there is a problem during Save an Exception object will be thrown. |
void pdftron::SDF::SDFDoc::Save | ( | const char *& | out_buf, | |
size_t & | out_buf_size, | |||
UInt32 | flags, | |||
Common::ProgressMonitor * | progress, | |||
const char * | header | |||
) |
Saves the document to a memory buffer.
out_buf | a 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_size | the 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. |
- | if there is a problem during Save an Exception object will be thrown. |
const char* pdftron::SDF::SDFDoc::GetHeader | ( | ) | const |
SecurityHandler pdftron::SDF::SDFDoc::GetSecurityHandler | ( | ) |
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.
void pdftron::SDF::SDFDoc::SetSecurityHandler | ( | SecurityHandler | handler | ) |
The function sets a new SecurityHandler as the current security handler.
- | new SecurityHandler |
void pdftron::SDF::SDFDoc::RemoveSecurity | ( | ) |
This function removes document security.
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.
- | obj_num1 & obj_num2 are object numbers of objects to be swapped. |
the | function throws exception in case the swap can't be performed. |
Obj pdftron::SDF::SDFDoc::CreateIndirectName | ( | const char * | name | ) |
The following list of methods is used to create SDF/Cos indirect objects.
Unlike direct objects, indirect objects can be referenced by more than one object (i.e. indirect objects they can be shared).
Obj pdftron::SDF::SDFDoc::CreateIndirectArray | ( | ) |
Obj pdftron::SDF::SDFDoc::CreateIndirectBool | ( | bool | value | ) |
Obj pdftron::SDF::SDFDoc::CreateIndirectDict | ( | ) |
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() | |||
) |
Obj pdftron::SDF::SDFDoc::CreateIndirectStream | ( | const char * | data, | |
const size_t | data_size, | |||
Filters::Filter | filter_chain = Filters::Filter() | |||
) |
bool pdftron::SDF::SDFDoc::IsLinearized | ( | ) | const |
Call this function to determine whether the document is represented in linearized (fast web view) format.
To save a document in linearized (fast web view) format you only need to pass 'SDFDoc.SaveOptions.e_linearized' flag in the Save method.
SDF::Obj pdftron::SDF::SDFDoc::GetLinearizationDict | ( | ) | const |
Returns document's initial linearization dictionary if it is available.
SDF::Obj pdftron::SDF::SDFDoc::GetHintStream | ( | ) | const |
Returns document's initial linearization hint stream if it is available.
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::Unlock | ( | ) |
Removes the lock from the document.
bool pdftron::SDF::SDFDoc::IsLocked | ( | ) |
bool pdftron::SDF::SDFDoc::TryLock | ( | int | milliseconds = 0 |
) |
Try locking the document, waiting no longer than specified number of milliseconds.
UString pdftron::SDF::SDFDoc::GetFileName | ( | ) | const |
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).
Use this function to enable to disable this feature dynamically.