The PNSrv12 COM object,PNSrv12Lib is included with your TIFF Image Printer printer.
This topic covers the sample programs provided, adding PNSrv12Lib to your program, and how to do common tasks.
Sample programs are provided as part of the install to demonstrate using PNSrv12Lib in your own programs.
These samples can be found in the COMSamples folder of the installation folder. This is usually C:\Program Files\TIFF Image Printer 12\COMSamples\.
A pre-built demo of each sample is available in a \Demo folder under each individual project.
All of the sample programs include a reference to Microsoft Word 2016 to automate printing to the TIFF Image Printer printer. If you have a different version of Office installed, you will need to update the Word reference in order to build and run the samples.
•ConvertWord - converts a Word document using the settings in the selected conversion profile. Also demonstrates overriding the conversion profile's setting for the name of the output file.
•ConvertPDF - converts a PDF document using the settings in the selected conversion profile using the ShellPrintTo feature instead of automating the printing application. Also demonstrates overriding the conversion profile's setting for the name of the output file.
•CustomNaming - this sample also converts a Word document using the selected conversion profile settings, and then uses the OnGetNextFileName event to create a unique filename for the output file at the point at which the file is to be saved. It also shows using the other IPNSession events to monitor the start and end of the print job, as well as to log errors and messages.
•ConsoleConvertFolder - illustrates batch conversion with a folder of files using Parallel.For to take advantage of the printer pool and setting a custom name for each file. Demonstrates using the printer pool and setting options in a thread-safe way.
The samples all use the folder C:\PEERNET\Samples\ to store the created files, with a sub folder for the output created when running each sample.
For the purposes of the samples, all of the profiles are configured to use copy protection when creating files and default to use the name of the profile as the preset output file name unless changed as part of the sample.
To add PNSrv12Lib as a COM reference in your application select PNSrv12 1.0 Type Library from the list of available COM objects.
If you are updating an older application that uses a previous version of the COM interface see Migrating to PNSrv12Lib for upgrade instructions.
The samples are designed to work with any of the PEERNET printers and profiles for each of the printers that included in the samples folder. For your own programs, you will instead want to create your own profiles.
The sample profiles ending in pntifprofile are for TIFF Image Printer printer. They can be copied and edited using the Profile Editor. You can also create your own profiles in the Profile Manager and then export the profile to use in your programs.
Conversion profiles are used to set the conversion settings when initializing the IPNSession object with the SetSessionPrinter method. This approach works well when you are using the same settings for all of your documents.
When your conversion settings are the same for all documents, but you need to control the output folder and/or the output file name for each document, the section Customize the Output File Name shows how to use a single conversion profile and only alter the file destination and/or name using SetSaveOptionsOutputLocationAndOutputFileName.
If you need to set different conversion settings individually for each document, SetPrinterProfile allows you to change printer profiles before printing each document. Again, this can be combined with SetSaveOptionsOutputLocationAndOutputFileName to customize the file name for each file.
The starting point of working with the TIFF Image Printer is the IPNSession interface.
Once you have an instance of a IPNSession object, that object is then initialized with one of PEERNET's printers through a call to SetSessionPrinter. This establishes the printer that will be used by this IPNSession object and the number of available printer queues in the printer pool for this session.
A process ID is passed to the COM object and used to monitor the running process to ensure all COM objects, references and printers are cleaned up if the current owner process (your program) unexpectedly crashes or is terminated.
An optional prefix can be used when naming the GUID-named printers in the printer pool for easy recognition. This can be useful if you have more than one program using PNSrv12Lib running at a time and you need to examine the printer queues.
PNSession session = new PNSession();
int pID = Process.GetCurrentProcess().Id;
session.SetSessionPrinter(pID, "TIFF Image Printer 12", 2, "Converter-",
Dim session As PNSession = New PNSession
Dim pID As Integer = Process.GetCurrentProcess().Id
session.SetSessionPrinter(pID, "TIFF Image Printer 12", 2, "Converter-",
Providing custom file naming for your output files can normally be accomplished by setting up your file name formatting in the conversion profile used by the printer. See the Filename Creator settings available in the conversion profile for configuring custom naming, including unique IDs, prefix and suffix terms, page numbers and date and time strings as part of the name..
When your file naming requirements vary too much from file to file, the main object IPNSession has two alternative options.
The SetSaveOptionsOutputLocationAndOutputFileName method allows you to override the output folder and/or the output file name before you print the file. One or the other or both of the arguments can be set by passing empty string for the unneeded argument.
An example scenario would be if you need to read an index file that contains the path to the source file to convert and the desired name and final output location. This method would be used to set the output folder or the output file name from the index file.
The ConvertWord sample uses this method to override the chosen conversion profile settings and set the output directory to C:\PEERNET\Samples\ConvertWordOutput and to set the output file name to any custom filename entered on the form.
The OnGetNextFileName event is called each time the printer needs to create a new file on disk.
For example, when creating a single, multi-paged file from a single print job, the event will be call exactly once, at the start. When when creating serialized output where one output file is created for each page in a single print job, this event is called once for each page.
The sample, CustomNaming, uses this event to name each file based on a fictional call to get an order number from an external source.
The IPNPrintSession object is used to manage a printer from the pool to be used to print a single document. A new IPNPrintSession object is needed for each document printed. This object should not be retrieved until just before you are about to print the document and should be released back into the printer pool as soon as possible.
•get an IPNPrintSession object to control the printing steps
•using the printer name (PrinterName) from the object, print the document to that printer
•check for the document to have been sent to the printer using WaitForJobsSpooled
•wait for the document to finish printing using WaitForJobsCompleted
•handle error cases with Cancel
•free the IPNPrintSession object using Marshal.FinalReleaseComObject
All of the samples demonstrate these steps, as well as handling error cases and exceptions to clean up properly.
As there may not be a free printer available, NewPrintSession is a timed method and will return null if no printer is available. This allows looping while waiting for a printer and the ability to cancel if a set time period has been exceeded.
With the PNSrv12 COM object it is easy to determine when the output file has been created, or "done".
In many cases, this information is needed in order to know when to move on to the next file, or continue the workflow for the current file. There are two different approaches that can be used to find this out.
The first way is to add an event handler to the IPNSession OnEndJob event. This event is called when the file is complete. An IPNJob object is passed to the event that contains information about the job, such as the name of the source file, and a list of the file or files created.
This allows you to get the exact name of the file created, even when serialized or other custom file naming properties have been set.
The CustomNaming sample demonstrates using an OnEndJob event handler to retrieve the names of the created files. It also demonstrates how to use Marshal.FinalReleaseComObject to safely dispose of the objects passed into and used in the event handler. These objects must be released properly in order for the COM object to shutdown cleanly when your application is finished.
The other way is to use the IPNPrintSession WaitForJobsCompleted method after printing the file.
This method does not return until the file(s) have been created, or until a specified timeout period has expired. If the timeout period has not expired then the printer has created the file and it is available for further processing.
This approach works when the exact file name created is not needed, such as when creating all output files in a specific folder, and then uploading the entire folder contents to an archive system.
Job tracking will add an IPNJob item to the Jobs collection on the parent IPNSession object for every job printed on any printer in the pool. This collection will continue to grow until Reset is called to clear the current list, or the IPNSession is released using Marshal.FinalReleaseComObject.
When using this technique with a very large number of files, or with long running applications, it is critical to periodically call Reset to clear this list or you will eventually run out of memory and resources.
The ConvertWord sample uses job tracking to store the completed job information for the file conversion. The information is outputted to the form and then cleared to keep the memory use low.