Class SDFDoc

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

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

Inheritance

object

SDFDoc

Implements

IDisposable

Inherited Members

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

Namespace: pdftron.SDF

Assembly: PDFNet.dll

Syntax

public class SDFDoc : IDisposable

Remarks

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.

Examples

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

SDFDoc mydoc = new SDFDoc();
Obj trailer = mydoc.getTrailer();

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

SDFDoc mydoc = new SDFDoc("in.pdf");
Obj trailer = mydoc.getTrailer();

SDF document can be also created from a memory buffer or some other Filter/Stream such as a HTTP Filter connection:

MemoryFilter memory = ....
SDFDoc mydoc = new SDFDoc(memory);
Obj trailer = mydoc.getTrailer();

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

PDFDoc doc = new PDFDoc("in.pdf");
SDFDoc mydoc = doc.getSDFDoc();
Obj trailer = mydoc.getTrailer();

Constructors

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.

Declaration

public SDFDoc()

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

SDFDoc(byte[], int)

Instantiates a new SDFDoc.

Declaration

public SDFDoc(byte[] buf, int buf_size)

Parameters

Type	Name	Description
byte[]	buf	the buffer
int	buf_size	the size

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception
PDFNetException	IOException Signals that an I/O exception has occurred.

SDFDoc(string)

Open a SDF/Cos document from a file.

Declaration

public SDFDoc(string filepath)

Parameters

Type	Name	Description
string	filepath	path name to the file.

Remarks

Make sure to call InitStdSecurityHandler() or InitSecurityHandler() after SDFDoc(...) in case the document is encrypted.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

SDFDoc(Filter)

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

Declaration

public SDFDoc(Filter stream)

Parameters

Type	Name	Description
Filter	stream	input stream containing a serialized document. The input stream may be a random-access file, memory buffer, slow HTTP connection etc.

Remarks

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.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

SDFDoc(PDFDoc)

Open a SDF/Cos document from a PDFDoc object.

Declaration

public SDFDoc(PDFDoc pdfdoc)

Parameters

Type	Name	Description
PDFDoc	pdfdoc	`PDFDoc` object containing `SDFDoc` object

Methods

ClearMarks()

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

Declaration

public void ClearMarks()

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

Close()

Close.

Declaration

public void Close()

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

CreateIndirectArray()

Creates the indirect array.

Declaration

public Obj CreateIndirectArray()

Returns

Type	Description
Obj	the obj

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

CreateIndirectBool(bool)

Creates the indirect bool.

Declaration

public Obj CreateIndirectBool(bool value)

Parameters

Type	Name	Description
bool	value	the value

Returns

Type	Description
Obj	the obj

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

CreateIndirectDict()

Creates the indirect dict.

Declaration

public Obj CreateIndirectDict()

Returns

Type	Description
Obj	the obj

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

CreateIndirectName(string)

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

Declaration

public Obj CreateIndirectName(string name)

Parameters

Type	Name	Description
string	name	the name

Returns

Type	Description
Obj	the obj

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

CreateIndirectNull()

Creates the indirect null.

Declaration

public Obj CreateIndirectNull()

Returns

Type	Description
Obj	the obj

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

CreateIndirectNumber(double)

Creates the indirect number.

Declaration

public Obj CreateIndirectNumber(double value)

Parameters

Type	Name	Description
double	value	the value

Returns

Type	Description
Obj	the obj

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

CreateIndirectStream(byte[])

Creates the indirect stream.

Declaration

public Obj CreateIndirectStream(byte[] buf)

Parameters

Type	Name	Description
byte[]	buf	the data

Returns

Type	Description
Obj	the obj

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

CreateIndirectStream(byte[], Filter)

Creates the indirect stream.

Declaration

public Obj CreateIndirectStream(byte[] buf, Filter filter)

Parameters

Type	Name	Description
byte[]	buf	the data
Filter	filter	the filter_chain

Returns

Type	Description
Obj	the obj

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

CreateIndirectStream(FilterReader)

Creates the indirect stream.

Declaration

public Obj CreateIndirectStream(FilterReader data)

Parameters

Type	Name	Description
FilterReader	data	the data

Returns

Type	Description
Obj	the obj

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

CreateIndirectStream(FilterReader, Filter)

Creates the indirect stream.

Declaration

public Obj CreateIndirectStream(FilterReader data, Filter filter)

Parameters

Type	Name	Description
FilterReader	data	the data
Filter	filter	the filter_chain

Returns

Type	Description
Obj	the obj

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

CreateIndirectString(byte[])

Creates the indirect string.

Declaration

public Obj CreateIndirectString(byte[] buf)

Parameters

Type	Name	Description
byte[]	buf	the value

Returns

Type	Description
Obj	the obj

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

CreateIndirectString(string)

Creates the indirect string.

Declaration

public Obj CreateIndirectString(string value)

Parameters

Type	Name	Description
string	value	the str

Returns

Type	Description
Obj	the obj

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

Dispose()

Releases all resources used by the SDFDoc

Declaration

public override sealed void Dispose()

Dispose(bool)

Declaration

[HandleProcessCorruptedStateExceptions]
protected virtual void Dispose(bool A_0)

Parameters

Type	Name	Description
bool	A_0

EnableDiskCaching(bool)

If true, this PDFDoc will use a temporary file to cache new content streams (this is the default behavior).

Declaration

public void EnableDiskCaching(bool use_cache)

Parameters

Type	Name	Description
bool	use_cache	the use_cache

~SDFDoc()

Allows an SDFDoc to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection.

Declaration

protected ~SDFDoc()

GetFileName()

Gets the file name.

Declaration

public string GetFileName()

Returns

Type	Description
string	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.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetHeader()

Gets the PDF file header.

Declaration

public string GetHeader()

Returns

Type	Description
string	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.

Type

Description

string

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.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetHintStream()

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

Declaration

public Obj GetHintStream()

Returns

Type	Description
Obj	the linearization hint stream of the original document or NULL if the hint stream is not available.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetLinearizationDict()

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

Declaration

public Obj GetLinearizationDict()

Returns

Type	Description
Obj	the linearization dictionary of the original document or NULL if the dictionary is not available.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetObj(int)

Declaration

public Obj GetObj(int obj_num)

Parameters

Type	Name	Description
int	obj_num

Returns

Type	Description
Obj

GetSecurityHandler()

Gets the security handler.

Declaration

public SecurityHandler GetSecurityHandler()

Returns

Type	Description
SecurityHandler	Currently selected SecurityHandler.

Remarks

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 exisitng document. Changes to the current handler will not invalidate the access to the original file and will take effect during document Save().

GetTrailer()

Gets the trailer.

Declaration

public Obj GetTrailer()

Returns

Type	Description
Obj	A dictionary representing the root of the document (i.e. a document trailer dictionary)

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

HasRepairedXRef()

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.

Declaration

public bool HasRepairedXRef()

Returns

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

Remarks

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

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

ImportObj(Obj, bool)

Import obj.

Declaration

public Obj ImportObj(Obj obj, bool deep_copy)

Parameters

Type

Name

Description

Obj

obj

an object to import.

bool

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 responibility to delete free objects.

Returns

Type	Description
Obj	a pointer to the root indirect object in this document

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

InitSecurityHandler()

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.

Declaration

public bool InitSecurityHandler()

Returns

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

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

InitStdSecurityHandler(byte[])

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.

Declaration

public bool InitStdSecurityHandler(byte[] passwordBuffer)

Parameters

Type	Name	Description
byte[]	passwordBuffer	Specifies the password used to open the document without any user feedback.

Returns

Type	Description
bool	True if the SecurityHandler was successfully initialized.

InitStdSecurityHandler(string)

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.

Declaration

public bool InitStdSecurityHandler(string password)

Parameters

Type	Name	Description
string	password	Specifies the password used to open the document without any user feedback.

Returns

Type	Description
bool	True if the SecurityHandler was successfully initialized.

IsEncrypted()

Checks if is encrypted.

Declaration

public bool IsEncrypted()

Returns

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

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

IsFullSaveRequired()

Checks if is full save required.

Declaration

public bool IsFullSaveRequired()

Returns

Type	Description
bool	true if the document requires full save.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

IsLinearized()

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

Declaration

public bool IsLinearized()

Returns

Type	Description
bool	true if document is stored in fast web view format, false otherwise.

Remarks

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.e_linearized' flag in the Save method.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

IsModified()

Checks if is modified.

Declaration

public bool IsModified()

Returns

Type	Description
bool	true if document was modified, false otherwise

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

Lock()

Locks the document to prevent competing threads from accessiong 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

public void Lock()

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

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.

Declaration

public void LockRead()

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

Save(Stream, SaveOptions, string)

Saves the document to the given stream.

Declaration

public void Save(Stream stm, SDFDoc.SaveOptions flags, string header)

Parameters

Type	Name	Description
Stream	stm	A stream where to serialize the document.
SDFDoc.SaveOptions	flags	A bit field composed of an OR of `SDF.SDFDoc.SaveOptions`.
string	header	File header. A new file header is set only during full save.

Remarks

this method ignores e_incremental flag

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

Save(string, SaveOptions, string)

Saves the document to file

Declaration

public void Save(string path, SDFDoc.SaveOptions flags, string header)

Parameters

Type	Name	Description
string	path	path to save
SDFDoc.SaveOptions	flags	A bit field composed of an OR of `SDF.SDFDoc.SaveOptions`.
string	header	File header. A new file header is set only during full save.

Remarks

Saving modifies the SDFDoc's internal representation. As such, the user should acquire a write lock before calling save. If the original pdf has a corrupt xref table (see HasRepairedXref or http://www.pdftron.com/kb_corrupt_xref), then it can not be saved using the e_incremental flag.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

Save(string, SaveOptions, ProgressMonitor, string)

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.

Declaration

public void Save(string path, SDFDoc.SaveOptions flags, ProgressMonitor progress, string header)

Parameters

Type	Name	Description
string	path	The full path name to which the file is saved.
SDFDoc.SaveOptions	flags	A bit field composed of an OR of `SDF.SDFDoc.SaveOptions`.
ProgressMonitor	progress	A pointer to the progress interface. NULL if progress tracking is not required.
string	header	File header. A new file header is set only during full save.

Remarks

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

Save(SaveOptions, string)

Saves the document to a memory buffer.

Declaration

public byte[] Save(SDFDoc.SaveOptions flags, string header)

Parameters

Type	Name	Description
SDFDoc.SaveOptions	flags	A bit field composed of an OR of `SDF.SDFDoc.SaveOptions`.
string	header	File header. A new file header is set only during full save.

Returns

Type	Description
byte[]	buffer containing the serialized version of the document

Remarks

this method ignores e_incremental flag

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

SetSecurityHandler(SecurityHandler)

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

Declaration

public void SetSecurityHandler(SecurityHandler handler)

Parameters

Type	Name	Description
SecurityHandler	handler	the new security handler

Remarks

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

Swap(int, int)

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.

Declaration

public void Swap(int obj_num1, int obj_num2)

Parameters

Type	Name	Description
int	obj_num1	the obj_num1
int	obj_num2	the obj_num2

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

TimedLock(int)

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

Declaration

public bool TimedLock(int milliseconds)

Parameters

Type	Name	Description
int	milliseconds	the milliseconds

Returns

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

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

TimedLockRead(int)

Tries to obtain a read lock on the document, waiting no longer than specified number of milliseconds.

Declaration

public bool TimedLockRead(int milliseconds)

Parameters

Type	Name	Description
int	milliseconds	maxiumum number of milliseconds to wait for the lock

Returns

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

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

TryLock()

Try locking the document

Declaration

public bool TryLock()

Returns

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

TryLockRead()

Tries to obtain a read lock in a non-blocking manner.

Declaration

public bool TryLockRead()

Returns

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

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

Unlock()

Removes the lock from the document.

Declaration

public void Unlock()

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

UnlockRead()

Removes the read lock from the document.

Declaration

public void UnlockRead()

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

XRefSize()

X ref size.

Declaration

public int XRefSize()

Returns

Type	Description
int	The size of cross reference table

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

Operators

implicit operator SDFDoc(PDFDoc)

Explicit and implicit conversion operator from PDFDoc to SDF::Doc.

Declaration

public static implicit operator SDFDoc(PDFDoc pdfdoc)

Parameters

Type	Name	Description
PDFDoc	pdfdoc	`PDFDoc` to convert to `SDFDoc`

Returns

Type	Description
SDFDoc	document's SDF/Cos document

Implements

IDisposable