RecAPI: RecPDF.Net

RecPDF.NET is the object oriented .NET API of RecPDFAPI. Supported on: Windows. More...

Namespaces
namespace	Kofax::OmniPageCSDK::RecPDF

Detailed Description

RecPDF.NET is the object oriented .NET API of RecPDFAPI. Supported on: Windows.

To start with RecPDF first a Manager object must be created via the RecPDF static class. The simplest method is using the 'using' keyword which is also able to uninitialize the RecPDF at the end.

    using (var manager = RecPDF.Initialize())
    {
        // Use the library...
    }

In the using several file level methods are directly available. E.g. checking the password protection of a PDF file:

    using (var manager = RecPDF.Initialize())
    {
        System.Console.WriteLine("{0} is password protected: {1}", fileName, manager.IsPDFPasswordProtected(fileName));
    }

However executing every operation on files one by one would be very ineffective, a file can be opened by the Manager's class OpenDocument methods: (And a new file can be created by the CreateDocument method.)

    using (var manager = RecPDF.Initialize())
    using (var document = manager.OpenDocument(fileName))
    {
        // Use the document...
    }

In the Document class there are some document level methods, and several properties of the PDF file. This sample prints on the console if the file has text:

    using (var manager = RecPDF.Initialize())
    using (var document = manager.OpenDocument(fileName))
    {
        Console.WriteLine("{0} {1} text.", document.Path, document.HasText ? "has" : "hasn't")
    }

To handle multiple documents and pages in an optimized way, the Operation class has been created. An operation object mostly used for copying, moving, rotating, deleting, and adding pages to documents. To use an operation first the input and output documents must be attached to it. The attaching method is the same for the input and output documents. Actually a document can be both input and output at the same time. e.g. A page is moved inside the document, then the document is the input source of the page, and the output target to the page as well. The documents can be attached through the parameters of the CreateOperation method or the Operation class's AddDocument method.

Then commands must be used on the operation. These commands will be executed at the same time when the Operation object's Execute method is called. If in the meantime it turns out that these commands are not needed, then the Operation object should be disposed. It will cancel all the commands. After the Dispose or the Execute method the Operation object is no longer available. A second Dispose or a Dispose after Execute won't do anything and won't cause any problem. So the Execute method can be used in a using block without problem. This example appends the 3., 5., and 6. page of the source file to the destination file:

    using (var manager = RecPDF.Initialize())
    using (var documentSrc = manager.OpenDocument(fileName1))
    using (var documentDst = manager.OpenDocument(fileName2))
    using (var op = manager.CreateOperation(documentSrc, documentDst))
    {
        op.AppendPage(documentDst, documentSrc, 2, 4, 5);
        if (StillNeedsToCopyPages()) // If not, the using statement at end of scope calls the Dispose method to cancel the operation.
            op.Execute();
    }

A document at a time can only attach to a single operation. And during that every command to the operation virtually executed on it at the moment the command used. e.g. If the first page of the document is deleted, then later the page 0 will refer to the original document's second page. If a page is insert into a document's first page, then the page 1 will refer to the original document's first page, and page 0 will be the new page. However the commands won't really be executed until the Execute method is called. But with this method the document's changing will be easily traceable.

Be aware that the Operation object is not a transaction. If the Execute method throws an exception it is not guaranteed that the output files contents reverts to the original contents. This could be achieved only by temporarly backuping the files. However if Dispose is used instead of Execute it is guaranteed that no files has been changed.

Exception safety: All methods has strong exception safety level except only a few one. That means when an exception has been thrown these methods reverts the owning object to the state before the calling of the function, and free up any resources they allocated. They work like a transaction. However the state of the file system may have changed, like a file is modified in the meantime. The Dispose methods use instead the no-throw exception safety level. Which means they never throw. Because some Dispose method shares a great part of their codes with the finalizer method, and finalizers can't throw. The last exception of the rule is Execute method of the Manager class which always disposes the Manager object even if an exception has been thrown.

Thread safety: Every method is thread safe. Because every method uses locks to ensure thread safety calling them from multiple threads without care may cause dead lock.

Namespaces

Detailed Description