Two Pilots Virtual Printer – Developer Manual

Virtual Printer SDK:       Home       Download       Pricing       FAQ       Manual       Tutorials       Known issues       News

– Download Developer Manual as PDF –

Table of Contents:

◊ Overview
◊ Getting Started
◊ Environment variables and custom variables
◊ Agent
     Agent Settings
◊ Authentication
     Authentication Settings
◊ Applications
     Preconverter
     Postconverter
     Application Settings
     Early Access
◊ Converter
     Converter Settings
     EMF
     BMP
     PNG
     JPEG
     TIFF
     RAW
     INI
     FTP
     PDF
     POS
     Redirect
     Text
     Watermarks
◊ Installation Directory Settings
◊ Properties Dialog Settings
◊ For Developers
     Binaries overview
     Building MSI package
          Using Microsoft Visual Studio
          Using Wix tools
     Building executable package
          NSIS
          Inno Setup
◊ The Driver Pipeline
◊ Legal and Copyright Notices

Overview

The Virtual Printer Driver is a usual printer device in the system. You may print on them from any application, setup printer settings such as DPI, paper size and page orientation. Instead of the real printer device that prints on a real paper, VPD produce copy of the printed document in different formats such as JPEG, PNG, PDF or TEXT. In other words, VPD is a complete solution for documents conversion to other formats with abilities to control conversion process. Moreover, there is an option to notify the specified client application with path to an INI-file that contains:

• Print job information (User name, Job ID, Paper size, Page orientation, etc.);
• Output files information (File format, count, paths).

There is no limitations for the client application logic. It can be a desktop application which popup login dialog and upload files to the cloud via your web-service API. Or it can be a hidden console application that saves files with metadata on the server and calculates user statistics.

Getting Started

The Virtual Printer Driver delivery package contains:

• Binary files for printer driver. Detailed files information here.
• Installation scripts for making your own installation package. How to build MSI and EXE package you will find here and here.

There are three parts of the Virtual Printer Driver:

• Agent service;
• Converter;
• Application.

Agent service and Converter are non-modifiable components but provides a various settings for configuration. Application is a part of your software package and should implement your business logic. There are only two limitations for the application:

1. It should be executable. It can be an EXE-file by itself or a parameter of an interpreter, for example “java.exe -jar app.jar”;
2. It should receive notifications from Agent service through command line or Windows message or named pipe.

For tests, you may build and install a sample installation from the delivery package or install DEMO build from x86 or x64 packages. After the installation completed, use Properties utility from the driver group in the Start menu or registry settings to configure application settings, output formats, general printer settings (paper size, print quality, page orientation), etc.

When your software package will be ready for deployment, you may start to create a custom installation package. It can be EXE-file or MSI-package. You may use this installation files as a part of your installer or modify them for installing your part of software.

Environment variables and custom variables

Using System environment variables, output directory or output file name can be configured. Virtual Printer Driver supports all of them that can be specified with %variable_name% template. In addition to System environment variables, Virtual Printer Driver supports custom variables that can be specified with {variable_name} template. For example, output directory “%TEMP%/{yyyy}/{device}” will expand to “C:/Users/John/AppData/Local/Temp/2017/Two Pilot Demo Printer” directory.

Here is the list of supported custom variables:

Agent

Agent is a Windows service which allows to communicate between Virtual Printer Driver and client applications. In services list it named as VPDAgent. By default Agent calls applications with a logged on user permission rights who prints documents. If Virtual Printer Driver shared via local network or domain you should use Allow guest session or Allow domain session options for allowing to call an application with a current logged on user permission rights. If Virtual Printer Driver installed on a print-server and there are no logged on users you should use Allow self session which allows to call applications with Agent service permission rights without any interactives (GUI).

By default, Agent scheduler uses pool size with 8 simultaneous threads, one thread – one print job. You can change this value by passing “-poolSize X” command line parameter via VPDAgent service property “Start parameter:”, where “X” is a required pool size.

Agent settings are stored in the following registry key:
«HKLM\Software\REGISTRY_ENTRY\Agent»

Agent Settings

Authentication

Virtual Printer Driver supports user authentication through OAuth v2.0 protocol. This feature allows to deny unauthorized access to the Virtual Printer Driver and the services provided. Before using Virtual Printer Driver each user should provide a valid credentials for authentication service.

Authentication settings are stored in the following registry key:
«HKLM\Software\REGISTRY_ENTRY\Agent\OAuth v2.0»

Authentication Settings

Applications

Application is an executable file (exe-file) which called by Agent service during a processing of a print job. There are two types of applications: preconverter and postconverter. Preconverter allows to handle EMF files before processing to other formats. Postconverter allows to handle a result of EMF files processing to BMP, JPEG, TIFF, PNG, TEXT or PDF formats.

Preconverter

Using the preconverter you can modify or remove the EMF files in print job and alter conversion settings. When the driver runs the preconverter, this information is available:

• document name
• job id
• machine name
• user name
• print resolution
• paper orientation
• paper size
• bin name
• pages
• EMF files

Using this data the preconverter can stop or resume the print job. To resume the print job the preconverter should put this section in the ini-file:
[Preconverting]
Status = resumed

To cancel the print job, this section:
[Preconverting]
Status = canceled

Preconverter settings are stored in the following registry keys:
«HKCU\Software\REGISTRY_ENTRY\Application\Preconverter»
«HKLM\Software\REGISTRY_ENTRY\Application\Preconverter»

Postconverter

Postconverter (or the client application) is started at the end of the print job processing. When the driver runs the postconverter, this information is available:

• document name
• job id
• machine name
• user name
• print resolution
• paper orientation
• paper size
• bin name
• pages
• full paths to EMF, BMP, TIFF, JPEG, PNG, TEXT, PDF files.

Postconverter settings are stored in the following registry keys:
«HKCU\Software\REGISTRY_ENTRY\Application\Postconverter»
«HKLM\Software\REGISTRY_ENTRY\Application\Postconverter»

Application Settings

Early Access

Early Access allows to receive information from Virtual Printer Driver in run-time. In this mode, Virtual Printer Driver sends to the Application packages with required information. Packages sends according to the next scheme:

• The first package contain a path to the INI-file and a “Document” section of the INI-file contain “Status” equal to “Spooling”:
       [Document]
       Status = Spooling
   
• The second and all the next packages contains paths to converted files with zero (‘\0’) as delimiter and double zero at the end of the package. For example, “printer name\0jobid\0c:\Output\result.emf\0c:\Output\result.bmp\0c:\Output\result.png\0\0”. Paths to multipage formats (TIFF, PDF and Text) sends before the last package;
   
• The last package contain path to INI-file and the “Document” section of the INI-file contain “Status” equal to “Printed”:
       [Document]
       Status = Printed

To enable “Early Access” you should add “Application/Postconverter/Early Access”, REG_DWORD value and set to “1”.

Converter

Converter performs conversion of EMF files to BMP, JPEG, TIFF, PNG, TEXT or PDF formats. If a source format is ESC/POS, it is converted to the EMF first, then to other formats. Also converter allow to add graphical and textual watermarks to produced files, redirect a print job to other printer or upload produced files to FTP/SFTP/FTPS server. All produced files are stored in the output directory.

Converter settings are stored in the following registry keys:
«HKCU\Software\REGISTRY_ENTRY\Converter»
«HKLM\Software\REGISTRY_ENTRY\Converter»

Target format settings for BMP, JPEG, TIFF, PNG, TEXT, PDF, POS, FTP, WATERMARKS and REDIRECTION are stored in corresponding subkeys.

Converter Settings

EMF

BMP

PNG

JPEG

TIFF

RAW

INI

FTP

PDF

POS

Redirect

abcdefghijklmnopqrstuvwxyz
ABCDEFGHIJKLMNOPQRSTUVWXYZ
0123456789
!&+:?^}\'";@_~#(-<[`$).=\{%*/>]|

0x00 = "NUL", 0x01 = "SOH", 0x02 = "STX", 0x03 = "ETX",
0x04 = "EOT", 0x05 = "ENQ", 0x06 = "ACK", 0x07 = "BEL",
0x08 = "BS ", 0x09 = "HT ", 0x0A = "LF ", 0x0B = "VT ",
0x0C = "FF ", 0x0D = "CR ", 0x0E = "SO ", 0x0F = "SI ",
0x10 = "DLE", 0x11 = "DC1", 0x12 = "DC2", 0x13 = "DC3",
0x14 = "DC4", 0x15 = "NAK", 0x16 = "SYN", 0x17 = "ETB",
0x18 = "CAN", 0x19 = "EM ", 0x1A = "SUB", 0x1B = "ESC",
0x1C = "FS ", 0x1D = "GS ", 0x1E = "RS ", 0x1F = "US ",
0x20 = "SP ", 0x7F = "DEL"

Text

Watermarks

Installation Directory Settings

Properties Dialog Settings

For Developers

For developers we provide a full set of files and scripts for building their own installation package or incorporate Virtual Printer Driver to their products. We provide set of installation scripts for Wix Toolset and NSIS + Inno Setup. You will receive your a delivery package after purchase the Virtual Printer Driver. For tests we provide Devkit for our demo build of Virtual Printer Driver (x86 and x64 builds). Inside the Devkit you will find the next directories:

• Files – files for VPD for x86 systems;
• Files_x64 – files for VPD for x64 systems;
• msi_installer – files for building MSI package with using Wix Toolset;

Binaries overview

Here is a short description of delivery package components.

Building MSI package

We provide sample scripts for building MSI package with using Wix Toolset. You should download and install Wix Toolset package. For this tutorial we use Wix v3.8 (Stable) version. Online documentation for Wix Toolet v3.* available here.

Before build you should to modify the RegistrySettings.wxs file to provide a valid settings for Application, Converter and Agent service components.

There are two ways of building MSI package:

• with using Microsoft Visual Studio;
• with using Wix tools.

Using Microsoft Visual Studio

Here is a short brief of building our sample with using Microsoft Visual Studio. The detailed documentation «Working in Visual Studio» availabe here.

Before starting you should install Wix Toolset and Wix Visual Studio Plugin. Open «msi_intaller/VPDInstaller» solution in your delivery package with using Microsoft Visual Studio. Specify target platform «x86» or «x64» in Solution Platforms and build Wix project via «Build → Build Solution». The result MSI package will placed to «msi_installer/VPDIntaller/bin» directory.

Using Wix tools

Here is short brief of building our sample with using Wix tools. The detailed documentation «Tools and concepts» available here.

Before starting you should install Wix Toolset. Open directory «msi_installer/VPDInstaller» in your delivery package. Here you will find two Batch files «make_msi_x86.bat» and «make_msi_x64.bat» which builds MSI package for x86 and x64 platforms respectively and place it to the «msi_intaller/VPDInstaller/bin» directory.

Building executable package

We provide sample scripts for building executable installation package with using NSIS and Inno Setup installers. For this tutorial we use NSIS v3.06.1 and Inno Setup 5.6.1(u) versions.

Before starting you should install NSIS and Inno Setup installers. For building installation package for x86 platform, you should use files and scripts from the «files_full» directory of your delivery package. For x64 platform you should use files and scripts from the «files_full_x64» directory. Later in the text we will refer to files from «files_full» directory. You can apply the same things to the files from the «files_full_x64» directory.

NSIS

Open «SetupPrn.nsi» in the favorite text editor and look at the two lines at the beginning of the file:

!define PRINTER_NAME “Your printer name”
!define PREFIX “Your file prefix”

Here you should change PRINTER_NAME and PREFIX defines to your specified.
PRINTER_NAME is a printer name which you have selected after purchace, for demo build you should set it to «Two Pilots Demo Printer»:

!define PRINTER_NAME “Two Pilots Demo Printer”

The next, you should set PREFIX to your file prefix. Look at the .gpd or .ini file in the «files_full» directory and place its name as PREFIX. For example, demo build has «tpdps.gpd» and «tpdps.ini» files, so, PREFIX should be «tpdps»:

!define PREFIX «tpdps»

Save changes and close «SetupPrn.nsi» file. Now, run «makensisw.exe» from the NSIS installation directory and select «SetupPrn.nsi» script from «File → Load script», NSIS will compile script. If all is correct you will receive «SetupPrn.exe» file in the «files_full» directory. Now you are ready to build Inno Setup script.

Inno Setup

Before starting you should build «SetupPrn.nsi» script. See previous section.

Open «Make.iss» with using Inno Setup Compiler («Compil32.exe» in the Inno Setup installation Directory) and look at the two lines at the beginning of the file:

#define PRINTER_NAME “Your printer name”
#define REGISTRY_KEY “Your registry key”

Here you should change PRINTER_NAME and REGISTRY_KEY defines to your specified.
PRINTER_NAME is a printer name which you have selected after purchace, for demo build you should set it to «Two Pilots Demo Printer». This is the same name as in the «SetupPrn.nsi» script.

#define PRINTER_NAME “Two Pilots Demo Printer”

REGISTRY_KEY is a registry key for storing VPD setting in the registry which you have selected after purchace, for demo build you should set it to «Two Pilots Demo Printer»:

#define REGISTRY_KEY “Two Pilots Demo Printer”

Modify the registry settings in the “[Registry]” section to provide a valid settings for Application, Converter and Agent service components.

Save changes and compile script «Build → Compile» in the «Inno Setup Compiler». If all is correct, you will receive «sample_installation.exe» in the «Output» directory. This file you can provide to your customers.

The Driver Pipeline

– Download Developer Manual as PDF –

Legal and Copyright Notices

Copyright © 2002-2022 Rais Garifullin and his licensors. All rights reserved. The Software is protected by international copyright treaties, as well as other intellectual property laws and treaties.

Portions of this product use the following libraries:

• CxImage
• LibJPEG
• LibPNG
• LibTIFF
• zlib
• libcurl
• Crypto++
• PDF Creator Pilot
• libiconv
• libidn

These libraries are redistributed under their own licenses. Read more…

Virtual Printer SDK:       Home       Download       Pricing       FAQ       Manual       Tutorials       Known issues       News