PTSDFDoc

@interface PTSDFDoc : NSObject

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.

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

    Declaration

    Objective-C

    - (instancetype)init;

    Swift

    init!()

  • Undocumented

    Declaration

    Objective-C

    - (instancetype)initWithFilepath: (NSString *)filepath;

    Swift

    init!(filepath: String!)

  • Undocumented

    Declaration

    Objective-C

    - (instancetype)initWithStream: (PTFilter*)stream;

    Swift

    init!(stream: PTFilter!)

  • Undocumented

    Declaration

    Objective-C

    - (instancetype)initWithBuf: (NSData*)buf buf_size:  (unsigned long)buf_size;

    Swift

    init!(buf: Data!, buf_size: UInt)

  • Close SDFDoc

    Declaration

    Objective-C

    - (void)Close;

    Swift

    func close()

  • Declaration

    Objective-C

    - (BOOL)IsEncrypted;

    Swift

    func isEncrypted() -> Bool

    Return Value

    true if the document is/was originally encrypted false otherwise.

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

    @exception 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).

    Declaration

    Objective-C

    - (BOOL)InitSecurityHandler;

    Swift

    func initSecurityHandler() -> Bool

    Parameters

    custom_data

    An optional parameter used to specify custom data that should be passed in SecurityHandler::Initialize() callback.

    Return Value

    true if the SecurityHandler was successfully initialized (this may include authentication data collection, verification etc.), false otherwise.

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

    @exception 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).

    @remark Deprecated. Use versions that accepts UString or buffer instead.

    Declaration

    Objective-C

    - (BOOL)InitStdSecurityHandler:(NSString *)password
                   password_sz:(int)password_sz;

    Swift

    func initStdSecurityHandler(_ password: String!, password_sz: Int32) -> Bool

    Parameters

    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_sz

    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.

    Return Value

    true if the given password successfully unlocked the document, false otherwise.

  • Declaration

    Objective-C

    - (BOOL)IsModified;

    Swift

    func isModified() -> Bool

    Return Value

    - true if document was modified, false otherwise

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

    Note

    - If this function returns true, it is not possible to incrementally save the document (see http://www.pdftron.com/kb_corrupt_xref)

    Declaration

    Objective-C

    - (BOOL)HasRepairedXRef;

    Swift

    func hasRepairedXRef() -> Bool

    Return Value

    - true if document was found to be corrupted, and was repaired, during opening and has not been saved since.

  • Declaration

    Objective-C

    - (BOOL)IsFullSaveRequired;

    Swift

    func isFullSaveRequired() -> Bool

    Return Value

    - true if the document requires full save.

  • Declaration

    Objective-C

    - (PTObj *)GetTrailer;

    Swift

    func getTrailer() -> PTObj!

    Return Value

    - A dictionary representing the root of the document (i.e. a document trailer dictionary)

  • Declaration

    Objective-C

    - (PTObj *)GetObj:(unsigned int)obj_num;

    Swift

    func getObj(_ obj_num: UInt32) -> PTObj!

    Parameters

    obj_num

    - object number of the object to retrieve.

    Return Value

    - the latest version of the object matching specified object number. @exception - exception is thrown if the object is not found.

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

    Declaration

    Objective-C

    - (PTObj *)ImportObj:(PTObj *)obj deep_copy:(BOOL)deep_copy;

    Swift

    func `import`(_ obj: PTObj!, deep_copy: Bool) -> PTObj!

    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.

    Return Value

    - a pointer to the root indirect object in this document

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

    Note

    - The function does not perform the shallow copy since ImportObj() can be used instead.

    Declaration

    Objective-C

    - (PTVectorObj *)ImportObjs:(PTVectorObj *)obj_list;

    Swift

    func importObjs(_ obj_list: PTVectorObj!) -> PTVectorObj!

    Parameters

    obj_list

    - a list of root objects to import. All directly or indirectly objects will be imported as well.

    Return Value

    - a list of imported root objects in this document.

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

    Note

    - The function does not perform the shallow copy since ImportObj() can be used instead.

    Declaration

    Objective-C

    - (PTVectorObj *)ImportObjsWithExcludeList:(PTVectorObj *)obj_list
                              exclude_list:(PTVectorObj *)exclude_list;

    Swift

    func importObjs(withExcludeList obj_list: PTVectorObj!, exclude_list: PTVectorObj!) -> PTVectorObj!

    Parameters

    obj_list

    - a list of root objects to import. All directly or indirectly objects will be imported as well.
    exclude_list

    - a list of objects to not include in the deep copy.

    Return Value

    - a list of imported root objects in this document.

  • Declaration

    Objective-C

    - (unsigned int)XRefSize;

    Swift

    func xRefSize() -> UInt32

    Return Value

    - The size of cross reference table

  • Removes ‘marked’ flag from all objects in cross reference table.

    Declaration

    Objective-C

    - (void)ClearMarks;

    Swift

    func clearMarks()

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

    @exception - 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.

    Declaration

    Objective-C

    - (void)SaveSDFDocToFile:(NSString *)path
                   flags:(unsigned int)flags
                  header:(NSString *)header;

    Swift

    func save(toFile path: String!, flags: UInt32, header: String!)

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

    - File header. A new file header is set only during full save.

  • Saves the document to a memory buffer.

    @exception - 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.

    Declaration

    Objective-C

    - (NSData *)SaveSDFDocToBuf:(unsigned int)flags header:(NSString *)header;

    Swift

    func save(toBuf flags: UInt32, header: String!) -> Data!

    Parameters

    flags

    - A bit field composed of an OR of the SDFDoc::SaveOptions values. Note that this method ignores e_incremental flag.
    header

    - File header. A new file header is set only during full save.

    Return Value

    the buffer containing the serialized version of the document.

  • Saves the document to a stream.

    @exception - 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.

    Declaration

    Objective-C

    - (void)Save:(PTFilter *)stream
       flags:(unsigned int)flags
      header:(NSString *)header;

    Swift

    func save(_ stream: PTFilter!, flags: UInt32, header: String!)

    Parameters

    stream

    The output stream where to write data.
    flags

    - A bit field composed of an OR of the SDFDoc::SaveOptions values.
    header

    - File header. A new file header is set only during full save. See also GetHeader()

  • Declaration

    Objective-C

    - (NSString *)GetHeader;

    Swift

    func getHeader() -> String!

    Return Value

    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.

  • Note

    InitSecurityHandler() should be called before GetSecurityHandler() in order to initialize the handler.

    Note

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

    Note

    If the security handler is modified, document will perform a full save even if e_incremental was given as a flag in Save() method.

    Declaration

    Objective-C

    - (PTSecurityHandler *)GetSecurityHandler;

    Swift

    func getSecurityHandler() -> PTSecurityHandler!

    Return Value

    Currently selected SecurityHandler.

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

    Note

    Setting a new security handler will not invalidate the access to the original file and will take effect during document Save().

    Note

    If the security handler is modified, document will perform a full save even if e_incremental was given as a flag in Save() method.

    Declaration

    Objective-C

    - (void)SetSecurityHandler:(PTSecurityHandler *)handler;

    Swift

    func setSecurityHandler(_ handler: PTSecurityHandler!)

    Parameters

    handler

    - new SecurityHandler

  • This function removes document security.

    Declaration

    Objective-C

    - (void)RemoveSecurity;

    Swift

    func removeSecurity()

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

    @exception the function throws exception in case the swap can’t be performed.

    Declaration

    Objective-C

    - (void)Swap:(unsigned int)obj_num1 obj_num2:(unsigned int)obj_num2;

    Swift

    func swap(_ obj_num1: UInt32, obj_num2: UInt32)

    Parameters

    obj_num1

    - object number of first object to be swapped.
    obj_num2

    - object number of second object to be swapped.

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

    Declaration

    Objective-C

    - (PTObj *)CreateIndirectName:(NSString *)name;

    Swift

    func createIndirectName(_ name: String!) -> PTObj!

    Parameters

    name

    - indirect const char* object to create.

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

    Declaration

    Objective-C

    - (PTObj *)CreateIndirectArray;

    Swift

    func createIndirectArray() -> PTObj!

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

    Declaration

    Objective-C

    - (PTObj *)CreateIndirectBool:(BOOL)value;

    Swift

    func createIndirectBool(_ value: Bool) -> PTObj!

    Parameters

    value

    - indirect boolean to create.

  • Undocumented

    Declaration

    Objective-C

    - (PTObj*)CreateIndirectDict;

    Swift

    func createIndirectDict() -> PTObj!

  • Undocumented

    Declaration

    Objective-C

    - (PTObj*)CreateIndirectNull;

    Swift

    func createIndirectNull() -> PTObj!

  • Undocumented

    Declaration

    Objective-C

    - (PTObj*)CreateIndirectNumber: (double)value;

    Swift

    func createIndirectNumber(_ value: Double) -> PTObj!

  • Undocumented

    Declaration

    Objective-C

    - (PTObj*)CreateIndirectString: (NSData*)value size:  (unsigned int)size;

    Swift

    func createIndirectString(_ value: Data!, size: UInt32) -> PTObj!

  • Undocumented

    Declaration

    Objective-C

    - (PTObj*)CreateIndirectStringWithStr: (NSString *)str;

    Swift

    func createIndirectString(withStr str: String!) -> PTObj!

  • Note

    After calling the following methods the filter object is invalidated and should not be used

    Declaration

    Objective-C

    - (PTObj *)CreateIndirectStreamWithFilterReader:(PTFilterReader *)data
                                   filter_chain:(PTFilter *)filter_chain;

    Swift

    func createIndirectStream(with data: PTFilterReader!, filter_chain: PTFilter!) -> PTObj!

  • Undocumented

    Declaration

    Objective-C

    - (PTObj*)CreateIndirectStream: (PTFilterReader*)data;

    Swift

    func createIndirectStream(_ data: PTFilterReader!) -> PTObj!

  • Undocumented

    Declaration

    Objective-C

    - (PTObj*)CreateIndirectStreamWithbuf: (NSString *)data data_size:  (unsigned long)data_size filter_chain:  (PTFilter*)filter_chain;

    Swift

    func createIndirectStreamWithbuf(_ data: String!, data_size: UInt, filter_chain: PTFilter!) -> PTObj!

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

    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.

    Declaration

    Objective-C

    - (BOOL)IsLinearized;

    Swift

    func isLinearized() -> Bool

    Return Value

    - true if document is stored in fast web view format, false otherwise.

  • Returns document’s initial linearization dictionary if it is available.

    Declaration

    Objective-C

    - (PTObj *)GetLinearizationDict;

    Swift

    func getLinearizationDict() -> PTObj!

    Return Value

    - the linearization dictionary of the original document or NULL if the dictionary is not available.

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

    Declaration

    Objective-C

    - (PTObj *)GetHintStream;

    Swift

    func getHintStream() -> PTObj!

    Return Value

    - the linearization hint stream of the original document or NULL if the hint stream is not available.

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

    Declaration

    Objective-C

    - (void)Lock;

    Swift

    func lock()

  • Removes the lock from the document.

    Declaration

    Objective-C

    - (void)Unlock;

    Swift

    func unlock()

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

    Declaration

    Objective-C

    - (BOOL)TryLock:(int)milliseconds;

    Swift

    func tryLock(_ milliseconds: Int32) -> Bool

    Parameters

    milliseconds

    - max number of milliseconds to wait for the document to lock

    Return Value

    true if the document is locked for multi-threaded access, false otherwise.

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

    Declaration

    Objective-C

    - (void)LockRead;

    Swift

    func lockRead()

  • Removes the lock from the document.

    Declaration

    Objective-C

    - (void)UnlockRead;

    Swift

    func unlockRead()

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

    Declaration

    Objective-C

    - (BOOL)TryLockRead:(int)milliseconds;

    Swift

    func tryLockRead(_ milliseconds: Int32) -> Bool

    Parameters

    milliseconds

    - max number of milliseconds to wait for the document to lock

    Return Value

    true if the document is locked for multi-threaded access, false otherwise.

  • Declaration

    Objective-C

    - (NSString *)GetFileName;

    Swift

    func getFileName() -> String!

    Return Value

    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.

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

    Declaration

    Objective-C

    - (void)EnableDiskCaching:(BOOL)use_cache_flag;

    Swift

    func enableDiskCaching(_ use_cache_flag: Bool)

    Parameters

    use_cache_flag

    - true to enable caching, false to disable caching. Use this function to enable or disable this feature dynamically.

  • Undocumented

    Declaration

    Objective-C

    + (PTSDFDoc*)CreateInternal: (unsigned long long)impl;

    Swift

    class func createInternal(_ impl: UInt64) -> PTSDFDoc!

  • Undocumented

    Declaration

    Objective-C

    - (unsigned long long)GetHandleInternal;

    Swift

    func getHandleInternal() -> UInt64

Locking

  • Synchronously acquires a read lock for this PTSDFDoc instance and executes the given block on the current queue. Any NSException thrown while locking or unlocking the document, or executing the block, is converted into an NSError object and returned in the error parameter.

    Note

    In Swift, this method returns Void and is marked with the throws keyword to indicate that it throws an error in cases of failure.

    Declaration

    Objective-C

    - (BOOL)lockReadWithBlock:(nonnull void (^)(PTSDFDoc *_Nonnull))block
                    error:(NSError *_Nullable *_Nullable)error;

    Swift

    func lockRead(_ block: (PTSDFDoc) -> Void) throws

    Parameters

    block

    The block to perform.
    error

    On input, a pointer to an error object. If an error occurs (an NSException is thrown), this pointer is set to an actual error object containing the error information. You may specify nil for this parameter if you do not want the error information.

    Return Value

    YES if the document could be locked and the block could be run successfully. If an error occurs (an NSException is thrown), this method returns NO and assigns an appropriate error object to the error parameter.

  • Synchronously acquires a write lock for this PTSDFDoc instance and executes the given block.

    Simultaneous write access to a PTPDFDoc instance is not allowed. A write lock cannot be acquired if the thread already holds a read lock. Attempting to do so is an error.

    Any NSException thrown while locking or unlocking the document, or executing the block, is converted into an NSError object and returned in the error parameter.

    Note

    In Swift, this method returns Void and is marked with the throws keyword to indicate that it throws an error in cases of failure.

    Declaration

    Objective-C

    - (BOOL)lockWithBlock:(nonnull void (^)(PTSDFDoc *_Nonnull))block
                error:(NSError *_Nullable *_Nullable)error;

    Swift

    func lock(_ block: (PTSDFDoc) -> Void) throws

    Parameters

    block

    The block to perform.
    error

    On input, a pointer to an error object. If an error occurs (an NSException is thrown), this pointer is set to an actual error object containing the error information. You may specify nil for this parameter if you do not want the error information.

    Return Value

    YES if the document could be locked and the block could be run successfully. If an error occurs (an NSException is thrown), this method returns NO and assigns an appropriate error object to the error parameter.

Additions

  • Creates an indirect object clone from the specified direct object.

    This method throws an exception if the specified object is not direct (ie. is already indirect).

    Declaration

    Objective-C

    - (nonnull PTObj *)CreateIndirectCloneFromDirectObj:(nonnull PTObj *)directObj;

    Swift

    func createIndirectClone(fromDirectObj directObj: PTObj) -> PTObj

    Parameters

    directObj

    The direct object to clone

    Return Value

    an indirect object clone

Importing

  • Imports the specified annotations into this document.

    Declaration

    Objective-C

    - (nullable NSArray<PTAnnot *> *)
    importAnnotations:(nonnull NSArray<PTAnnot *> *)annotations
            withError:(NSError *_Nullable *_Nullable)error;

    Swift

    func importAnnotations(_ annotations: [PTAnnot]) throws -> [PTAnnot]

    Parameters

    annotations

    the annotations to be imported into this document
    error

    On input, a pointer to an error object. If an error occurs, this pointer is set to an actual error object containing the error information. You may specify nil for this parameter if you do not want the error information.

    Return Value

    the imported annotations, or nil if an error occurs