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.
Implements
Inherited Members
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 |
|
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 |
|
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 |
|
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. |
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
bool | deep_copy |
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 |
|
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 |
|
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 |
|
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 |
|
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 |
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 |
|
string | header |
|
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 |
|
SDFDoc.SaveOptions | flags |
|
ProgressMonitor | progress |
|
string | header |
|
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(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 |
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 |
|
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 |
|
Returns
Type | Description |
---|---|
SDFDoc | document's SDF/Cos document |