Method #1

1) Open your project (or create a new one) and choose “Add Reference” in the Solution Manager (you can also do this from the main menu -> Project -> Add Reference…) and then select the “COM” tab.

2) In the component list find “PDFCreatorPilot Type Library” and press the “OK” button.

3) In the code file (*.cs) add this line:

using PDFCreatorLib;

and declare a variable somewhere in your code:

PDFDocument4 pdf = new PDFDocument4();
pdf.SetLicenseData(”demo”, “demo”);
// more code…

4) You may set project target type to “x64″ or leave it as “Any CPU”.

If all is done correctly, the PDF Creator Pilot now will be available to you in your project.

In some cases developers may not be able to add a reference as shown in the example above. In that case we recommend that you manually register the COM dll (PDFCreatorPilot.dll) with an administrator’s credentials:

regsvr32 PDFCreatorPilot.dll

After this please restart the Visual Studio and try to add the reference again. If this does not help, then please use Method #2.

Method #2

1) We need to manually create an interop wrapper library for .NET from the “PDF Creator Pilot x64″ COM library. Find please where the “PDFCreatorPilot.dll” (x64 version) is located and create a simple batch file with the following line:

2) Launch this file. This will produce the “Interop.PDFCreatorPilotLib.dll” file which is an interop library for the COM dll.

Note: the TlbImp.exe is a standard Windows SDK utility. If you do not have it on your machine,  please install the Windows SDK from the Microsoft website: http://www.microsoft.com/downloads/details.aspx?FamilyID=6b6c21d2-2006-4afa-9702-529fa782d63b&displaylang=en

3) Open your project (or create a new one) and choose “Add Reference” in the Solution Manager (you can also do this from the main menu -> Project -> Add Reference…) and select the “Browse” tab. In the file list find “Interop.PDFCreatorPilotLib.dll” created in the previous step and press the “OK” button.

4) In the code file (*.cs) add this line:

using PDFCreatorLib;
/* PDFCreatorLib is a namespace you’ve specified as a parameter for TlbImp.exe. */

and declare a variable somewhere in your code:

PDFDocument4 pdf = new PDFDocument4();
pdf.SetLicenseData(”demo”, “demo”);
// more code…

5) You may set the project target type to “x64″ or leave it as “Any CPU”.

If all is done correctly, the PDF Creator Pilot now will be available to you in your project.

You may download the sample project here. This project contains a manually created interop DLL, and a C# project that refers this interop.

Max Filimonov,
Two Pilots Developers Team.

PDF Library has the following methods for splitting, merging, and reorganizing pages:

• Append - This method appends the contents of a previously saved PDF file (not a BLOB) to a newly created (or opened) PDF document.

• Open - This method opens an existing PDF document, then reads and parses its contents.

• AddPage - This method creates a new PDF page, appending it to the end of the PDF document. It does not set the new page as current.

• DeletePage - This method removes the specified page from a PDF document.

With the help of PDF Creator Pilot, you can easily and quickly manage your PDFs, reduce the size of PDF files, and quickly combine a group of files using the merge feature.

Artem Golubnichenko

Artem Golubnichenko

The problem arose while converting an EMF into a PDF or while drawing an HDC-context taken from a PDF. The problem was connected to the Polyline(To) function. The function transformed an array of points with close value coordinates. Then, to draw a set of lines in a PDF, transformation of the
coordinates from HDC to PDF coordinates was necessary. For this transformation the LPtoDP function was used. But LPtoDP returns integer values. For example, this function transforms the (160, 74) and (159, 60) coordinates from EMF to (1, 1) and (1, 2) for a PDF. So a set of lines was generated as shown in the left picture. To improve the results, we have stopped using the LPtoDP function. Now Polyline(To) function gives the correct results.

Artem Golubnichenko

* Embedded fonts
* Device-independent color
* XMP metadata

The PDF Creator Pilot has property gets or sets the value indicating whether to produce a PDF/A compatible output file. There is ProducePDFA. Setting ProducePDFA to VARIANT_TRUE means that the output PDF file will be built compatible to the PDF/A standard. You should set this property before any text or graphics output.
If you need long-term preservation documents, use the PDF/A docs. With PDF Creator Pilot you can create such documents easy.

Artem Golubnichenko

The PDF to Image converter is based on PDF Rasterization Pilot. PDF Rasterization Pilot is a library for developers. Using this tool, developers can add to their products such features as export PDF to graphic format and output PDF to a device context (display or printer).

The new PDF2Image Pilot uses only PDF Rasterization Pilot for saving PDF into graphic files and outputting PDF content to a preview window. In PDF2Image Pilot, we tried to connect the features of the PDF Rasterization library and our many years experience in the development of easy and useful interfaces. We hope that PDF2Image converter helps you to solve your tasks. We await your responses and proposals!

Artem Golubnichenko

A group is assigned a state, which is either ON or OFF. States can be set programmatically or through the viewer user interface to change the visibility of content. In the typical case, content belonging to a group is visible when the group is ON and invisible when it is OFF. When a piece of optional content in a PDF file is determined to be hidden, the content is not drawn.

You may see all layers in PDF document on Layers tab. (for Adobe Reader) Go into the “View” menu and select “Navigation Tabs” and then choose “Layers”.

So this gives us an instruction on how to create Layered PDFs within PDF Creator Pilot.  In our example we’ve created a PDF with several layers. (example for VBScript)

' create pdf library object
Set PDF = CreateObject("PDFCreatorPilot.PDFDocument4")

' initialize PDF Engine
PDF.SetLicenseData "demo@demo", "demo"

' set document title
PDF.SetTitle "PDF with Layers", 1

' disconnect from library
Set PDF = Nothing

Hopefully from the example code and the example PDFs you should see how useful Layers can be.

Here you can download examples of PDF documents created by PDF Creator Pilot:
http://www.colorpilot.com/downloads/ContentGroupsExample.pdf
http://www.colorpilot.comdownloads/ContentGroupsExample_SourceCode.zip

Artem Golubnichenko
Project Manager of Virtual Printer

Today I want to talk about important improvements in the current version of the PDF Creator Pilot Library.

It was always one of the weakest things about the Library – it demanded huge amounts of memory to work with larger documents. Quite often clients were not able to create a document consisting of more than 100 pages, because they did not have enough memory. In this version, we have managed to open up a bottleneck, which helped us significantly reduce memory requirements. In short, if a page contains a lot of graphics, it also contains a lot of page operation commands. Keeping all these commands in memory was the bottleneck. We cached the commands into a temporary file, and that solved the problem.

The other improvement concerns conversion of EMF files to PDF files. We’ve improved the processing of paths and clipping regions. This was no trivial task, because the path processing toolset of the PDF format isn’t as rich as required by GDI. Clipping regions are the worst supported; there are no other region operations in a PDF except intersection. To adequately process an EMF, we had to support all operations defined in Set theory. For a long time the problem remained unsolved, however we have now left the problem behind us. Now these kinds of EMF files converted correctly.

This last bit of news should be of interest to those who use “non-standard” versions of the Library, such as the 64-bit variant or the static variant (which is for C++ only). We’ve found that the x64 build failed to convert EMF files, and the static library refused to work from VS2005. All of these problems have also been fixed.

Here are the current builds:

http://www.colorpilot.com/~builds/PDFCreatorPilot4_1_2492.zip
http://www.colorpilot.com/~builds/PDFCreatorPilot4_1_2492_x64.zip
http://www.colorpilot.com/~builds/PDFCreatorPilot4_1_2492_static.zip (18 Mb, contains both the Debug and the Release versions)

In the next release, we plan both to improve processing of TIFF files and to add support for CMYK TIFFs.

Vitaly Shibaev
Developer of PDF Library

First, let’s create a Visual C++/ATL project:

Click “OK” and then select “Allow merging of proxy/stub code”:

Click “Finish”. Studio creates a project for us. With the help of Solution Explorer, we can see the following files:

It’s just a shell. If we would compile and build the project at this stage, there would be a DLL-file without a single component.

To add a component to our project, let’s review the “FirstCOM.idl” file. It’s the file that contains the definitions of the interfaces.

So far, this is all that file contains (comments have been removed):

import "oaidl.idl";
import "ocidl.idl";
[
    uuid(0652E0B7-4360-4542-8D22-8F52940AEFCE),
    version(1.0),
    helpstring("FirstCOM 1.0 Type Library")
]
library FirstCOMLib
{
    importlib("stdole2.tlb");
};

This means that there is a library of types named FirstCOM that lacks the types. There are two attributes, though, “version” that holds the version of our library and “helpstring” that should hold a description of the library.

Let’s add a component. Select “Add->Class” from the context menu:

Select “ATL Simple Object”:

Now let’s enter the class information, as illustrated below:

Click “Finish”. Studio will create all the necessary files and add the necessary constants to the resource files. “FirstCOM.idl” should now look like this:

import "oaidl.idl";
import "ocidl.idl";
[
    object,
    uuid(5F9CB782-BDE1-48E3-91CC-E8EC0280EFA0),
    dual,
    nonextensible,
    helpstring("IFirstCOMClass Interface"),
    pointer_default(unique)
]
interface IFirstCOMClass : IDispatch
{
};
[
    uuid(FD0B5C1A-6E02-4EFA-958B-046A0AD17381),
    version(1.0),
    helpstring("FirstCOM 1.0 Type Library")
]
library FirstCOMLib
{
    importlib("stdole2.tlb");
    [
        uuid(61A52F01-320D-41E4-B5F2-A59C6E220292),
        helpstring("FirstCOMClass Class")
    ]
    coclass FirstCOMClass
    {
        [default] interface IFirstCOMClass;
    };
};

We have added a description of a class (component) with some interface IFirstCOMClass to the description section of the library (library FirstCOMLib{…}). The definition of that interface has been automatically added at the beginning of the file.

Now we have created a component (class) FirstCOMClass and declared its interface (IFirstCOMClass). This interface will be used to provide access to our component.

Now let’s define methods and functions for our component. For instance, let’s add two methods, one that would return the sum of two numbers and one to return the length of a string. Also, we’ll add a property “Author” to allow read and write access. To do that, in the section

interface IFirstCOMClass : IDispatch
{
};

we should add definitions of our methods and properties:

interface IFirstCOMClass : IDispatch
{
    [id(1)] HRESULT CalcSumm([in] LONG lParam1, [in] LONG lParam2,
        [out, retval] LONG* retVal);
    [id(2)] HRESULT GetStringLen([in] BSTR strParam,
        [out, retval] LONG* retVal);
   
    [propget, id(3)]
    HRESULT Author([out, retval] BSTR* retVal);
    [propput, id(3)]
    HRESULT Author(BSTR strValue);
};

Where:
[id(N)] – defines the identification number of a method or a property (This number must be unique.);
[in] denotes an input parameter;
[out, retval] – denotes an output parameter.Important: The read properties and the write properties should have the same name and identification (id).

Now let’s declare the methods described in CFirstCOMClass. Locate the “CFirstCOMClass.h” and open it. There is this:

class ATL_NO_VTABLE CFirstCOMClass :
    public CComObjectRootEx<CComSingleThreadModel>,
    public CComCoClass<CFirstCOMClass, &CLSID_FirstCOMClass>,
    public IDispatchImpl<IFirstCOMClass, &IID_IFirstCOMClass,
        &LIBID_FirstCOMLib, /*wMajor =*/ 1, /*wMinor =*/ 0>

This declaration allows the compiler to bind the COM class and its interface with a real C++ class.

Add this to the public section:

public:
    STDMETHOD(CalcSumm)(LONG lParam1, LONG lParam2, VARIANT_BOOL* retVal);
    STDMETHOD(GetStringLen)(BSTR strParam, VARIANT_BOOL* retVal;
    STDMETHOD(get_Author)(BSTR* sVal);
    STDMETHOD(put_Author)(BSTR sVal);

It is recommended to declare a constructor and a destructor and then move their implementation into file “CFirstCOMClass.cpp”.

Important: The read and write accessor methods of the property “Author” must begin with the “get_” and “put_” prefixes.

Then we create the private section. Here we will hold the value of the “Author” property.

private:
    CComBSTR m_author;

In “CFirstCOMClass.cpp”:

// FirstCOMClass.cpp : Implementation of CFirstCOMClass
#include "stdafx.h"
#include "FirstCOMClass.h" // CFirstCOMClass CFirstCOMClass::CFirstCOMClass()
{
    // initial value of the property Author
    m_author = OLESTR("Vasya");
}CFirstCOMClass::~CFirstCOMClass()
{
}

STDMETHODIMP CFirstCOMClass::CalcSumm(LONG lParam1, LONG lParam2, LONG* retVal)
{
    // if pointer is invalid - return error
    if (!retVal)
        return S_FALSE;
    *retVal = lParam1 + lParam2;

    // no errors - return OK
    return S_OK;
}

STDMETHODIMP CFirstCOMClass::GetStringLen(BSTR strParam, LONG* retVal)
{
    // if pointer is invalid - return error
    if (!retVal)
        return S_FALSE;

    CComBSTR str(strParam);
    *retVal = (LONG)str.Length();

    // no errors - return OK
    return S_OK;
}

STDMETHODIMP CFirstCOMClass::get_Author(BSTR* retVal)
{
    // if pointer is invalid - return error
    if (!retVal)
        return S_FALSE;

    // don't forget to allocate memory for the result string
    *retVal = SysAllocString((BSTR)m_author);

    // no errors - return OK
    return S_OK;
}

STDMETHODIMP CFirstCOMClass::put_Author(BSTR newVal)
{
    CComBSTR newAuthor(newVal);
    m_author = newAuthor;

    // no errors - return OK
    return S_OK;
}

Our COM library is almost ready. We have created the library itself, a class, and its interface. We’ve also added the implementation of the interface. It would be great to know the name of our COM library and its class. Their names are in the “FirstCOMClass.rgs”. Open it and find “VersionIndependentProgID”:

VersionIndependentProgID = s 'FirstCOM.FirstCOMClass'

The name of our library is FirstCOM, and the class is “FirstCOM.FirstCOMClass”.

When we add more classes, for each there will be an “.rgs” file with the following text:

VersionIndependentProgID = s 'FirstCOM._class_name_'

After building the project, in the “Debug” or “Release” folder we will find “FirstCOM.dll”, our COM library. To use it from another computer, it must be registered in its operating system. That can be done with an installer or with this command:

regsvr32 FirstCOM.dll

Now, let’s check whether it works. Create a text file “test.vbs” and copy the following Visual Basic Script into it:

' create COM object, use library name and class name
Set comObj = CreateObject("FirstCOM.FirstCOMClass") ' test CalcSumm method
res = comObj.CalcSumm(1, 2)
WScript.Echo "1 + 2 = " & res' test GetStringLen method
res = comObj.GetStringLen("QwertY123")
WScript.Echo "Len = " & res

' read property Author
auth = comObj.Author
WScript.Echo "Author = " & auth

' read property Author
comObj.Author = "Petya"
auth = comObj.Author
WScript.Echo "Author = " & auth

' cleanup
Set comObj = Nothing

Save and launch the file this way:

wscript.exe test.vbs

or this:

cscript.exe test.vbs

If we did everything correctly, we should see the results of our tests.

We could execute it from PHP:

<?php
// create COM object, use library name and class name
$comObj = new COM("FirstCOM.FirstCOMClass") or die("Can't create COM."); // test CalcSumm method
$res = $comObj.CalcSumm(1, 2);
echo("1 + 2 = " . $res);// test GetStringLen method
$res = $comObj.GetStringLen("QwertY123");
echo("Len = " . $res);

// read property Author
$auth = $comObj.Author;
$echo("Author = " . $auth);

// read property Author
$comObj.Author = "Petya";
$auth = $comObj.Author;
echo("Author = " . $auth);

// cleanup
$comObj = null;
?>

If you want to learn how to use COM from C/C++ and .NET, look here.

You can download the source of the COM library here.

Max Filimonov.

Development Tools

1. Subversion (SVN) Control

The life of a programmer would be unbearable without a source control manager . As of this writing, we have executed 2387 commits in the PDF Creator project using the Tortoise SVN, (http://tortoisesvn.tigris.org/). Since every mistake would cost a lot, we try to follow this rule – one that we would recommend to everyone: Always commit smaller portions of the code. Every commit must correspond to a single task!

This way it is (a) easier to find an error during rollbacks (every commit changes a small amount of source code), (b) often easy to discover an error before the commit just by looking at it, and (c) easier for colleagues to be aware of the changes in the source code, since all they have to do is read the comments and look at the smaller portions of the code.

Of course, this is not possible in all cases, and sometimes we do have to perform huge commits. Still this is a rule worth following. After all, it is one of the refactoring rules: Change smaller portions of the code, preserving its workability between sessions.

Two more source-control rules:

1. There must always be two versions in the SVN – a version that compiles and a workable version. It is easy to create code that compiles, but the real aim is its correctness.
2. Text comments should be supplied to every commit. This is also a good way to check whether the commit implements only a single task. If a comment describes several targets instead of just one, the rule has been violaled.

2. Bug Tracker

We use Mantis (http://www.mantisbt.org/). PDF Creator is the base for a number of other products – converters, virtual printer, etc. (See http://www.colorpilot.com/developer.html) The number of its users is much higher than the count of those who purchased the base product. We needed to simplify communications between the developers and the users of the products.

To make the things clear for those who have never used a bug tracker, here is a sample of how it works. The virtual printer developers receive (from the users of their product) information about an incorrect conversion into a PDF. The Virtual Printer gets an EMF file from input, then our library converts it. The information from the user is used to create a “ticket” for the library developers. The ticket is accompanied by a description of the problem and the problematic EMF file. Then we investigate the degree of severity of the problem to find out how critical it is and appoint a specific developer to work on a fix. After the problem has been resolved, the ticket gets closed. Everybody concerned is notified and may keep an eye on what is going on.

3. Technical Support

To manage our correspondence with clients, we use RT (http://bestpractical.com/rt/). We need the system for convenient storage of the archive, as well as assurance that every person who should read the messages does receive them.

Ideally, (2) and (3) might have been united into a single service, so that the clients were aware of their problem status. In the example above, the virtual printer user would keep an eye on developers’ correspondence concerning his problem. One such system that could help is FogBugz (http://fogcreek.com/FogBugz/).

4. Technical Documentation

Our internal technical documentation project, Squirrel (http://www.colorpilot.com/squirrel.html), isn’t widely known, however, it is publicly available. The program makes it easier to create a CHM-version of the documentation, integrates with SVN, and permits creation of the online documentation. See http://www.colorpilot.com/pdfcreatorpilotmanual/PDF_Creator_Pilot.html for the results of Squirrel’s work.

5. Development Environment

We use Visual Studio 2008, C++, and C#.

6. Refactoring Tools

There are no built-in tools for C++ refactoring in Visual Assist X (http://www.wholetomato.com/), so we have to use a third party plug-in for Visual Studio.

7. Unit Tests in C++

Here we use UnitTest++ (http://unittest-cpp.sourceforge.net/).

8. Profiling Tools

To diagnose memory leaks, we use http://www.colorpilot.com/~vit.shibaev/mmgr.zip. (I described that tool in one of my previous articles which you can find here: http://www.colorpilot.com/blog/about-pdf-creator-39/.) To control performance, we also use the Intel VTune, from time to time.

Project Organization

PDF Creator is a library for PDF processing: creation, reading, modification, text extraction, etc. Currently, the project exists as a solution with 18 sub-projects in Visual Studio 2008. There are five general types of sub-projects.

1. The Library Core

Here we define all the logic of PDF processing. This project is always in the process of modification. One of our old dreams (and still a dream today) is to make the core cross-platform. The biggest obstacle is the fact that EMF is a private Windows format. To make our dream come true, we should separate the conversion from the cross-platform part.

2. Client Interfaces

Two of the projects implement the client interfaces. One of them implements the COM interface; the other one implements a static library. The COM interface delegates its tasks to the static library; the static library forwards them to the core. No code is duplicated.

The static library isn’t advertised on our site, however every client may receive it together with the COM version. The static library contains some undocumented features that allow users to get some additional information about a document. If you are a developer and your product is intended to view PDFs, these features may be very useful for you.

3. Test Projects

1. Non-automated tests for the COM interface. A set of APIs that form and render PDF documents immediately after their launch.
2. Unit tests for the static library and the core. In addition to those described immediately above, the unit tests check the internal state of the classes, handle errors, etc.
3. Projects that check the EMF-conversion. The first one (written in WTL) converts the specified EMF file into a PDF. Its interafce is minimalistic, looking very much like our online service http://www.colorpilot.com/pdflibrary_convert-emf-to-pdf.html.
   The second one (written in C#) are a work in progress. However, it is already possible to convert all PDFs from a folder and to instantly review the results. This provides a significant speed increase during the testing process, which is especially great since we’ve got hundreds of test metafiles already.

4. Auxiliary Projects

These include a font-processing library (that parses TrueType and Type1 fonts, works with encodings, and modifies the TrueType fonts), font installer, working with the keys, etc.

5. Third Party Open-Source Products

PDF is a complex format. It is based on many areas of science, multiple algorithms, and formats. It involves compression and encryption algorithms, various image and font formats, color spaces, etc. A big part of our implementation is based on open source projects with a free license, for instance, CxImage, ZLib, LibJPEG, Lcms, and UnitTest++.

Vitaly Shibaev
Developer of PDF Library