Description
The IPNSession object is the starting point for working with the PNSrv12 COM object. It is associated with a single PEERNET printer, and creates a pool of one or more printers as defined using the SetSessionPrinter method.
The IPNSession object also holds the settings used to control each print job's output. These settings are first determined by the conversion profile passed in to either SetSessionPrinter at the beginning, or passed to SetPrinterProfile on a per file basis. The settings can be further modified using the property methods listed in the table below. Not all methods are valid for all printers.
If no conversion profile is specified, the default system conversion profile for the printer is used.
The printer settings must be set before calling NewPrintSession to get an IPNPrintSession object for printing. The IPNPrintSession object returned contains a copy of the settings from the IPNSession object and is associated with a single non-busy printer from the pool of printers. A new IPNPrintSession object is needed for each document printed.
To further control the print and conversion process, there are several events that are fired that enable an application to intercept and apply specific custom logic. For example, the OnGetNextFileName event can be used to further customize the filename used to store the output file.
There are two main groups of methods for the IPNSession object. The first group, the initialization methods, are methods used to initialize the object and provide access to top-level objects. For example,NewPrintSession returns an IPNPrintSession object. The property methods, the second group of methods, are used to modify the settings for the print jobs over and above the settings in the conversion profile.
Optionally, you can choose to track job information as the documents are printed. This option is off by default and can be turned on by setting the IPNSession property TrackingOn to TRUE. When job tracking is enabled, the Jobs property, an IPNJobs collection, is populated with an IPNJob object for every print job processed.
➢Version 11 Compatibility Mode Methods
Breaking Changes
The following methods, properties, events and any enumerations used by these methods have been removed in PNSrvLib12.
•AddSessionPrinter
•NewPrintSessionEx
•SetCompressionOptions
•SetEmailMessageOptions, SetEmailOn, SetEmailService, SetMAPIEmailService, SetSMTPEmailService, SetVIMEmailService
•SetLandscapeWatermarkOptions, SetPortraitWatermarkOptions, SetWatermarkOptionsOn
•SetUserExit32, SetUserExit64
•OnStartImage,OnEndImage events
•All matching clear properties methods (methods starting with Clear***)
Beginning with version 12.0.027, the following methods, properties, events and enumerations used were re-introduced into PNSrvLib12.
•EnableControlStrings
•ForcePrinterColorMode
•ForcePrinterOrientation
•ForcePrinterPaperSize
•ForcePrinterResolution
•SetDevmodeSettings
•SetErrorReporting
•SetFileNamingOptions
•SetMessageBoxAlerts
•SetNamingProfileFormat
•SetPDFFileFormatOptions
•SetRunAtStartCommand, SetRunAtEndCommand
•SetUserVariable
•All matching clear properties methods (methods starting with Clear***)
Initialization Methods
SetSessionPrinter
Initializes the IPNSession object to work with a particular printer.
SetPrinterProfile
Sets the printer profile that contains the settings that the IPNPrintSession printers will use when converting files.
NewPrintSession
Returns a new instance of an IPNPrintSession object for printing.
Version 11 Compatibility Mode Methods
SetV11CompatibilityModeEnabled
Enables compatibility mode to make the PNSrv12Lib mimic earlier versions of printer driver automation. Use this to migrate to the new version to minimize code changes in your automation code.
SetPrinterWaitForJobCompletion
Previous versions of the printer locked the print job into the print queue until the file was created. If your automation code needs this lock-step behavior, enable it here.
Job Tracking Methods
Reset
Clears any accumulated job information when job information is being tracked.
WaitForCompletion
Waits a given timeout period for all jobs in all print sessions to be completed before returning control back to the calling application.
Property Methods
EnableControlStrings
Enables or disables control string processing in the printer.
ForcePrinterColorMode
Forces the printer to print in color or black and white.
ForcePrinterOrientation
Forces the printer to print in either portrait or landscape orientation.
ForcePrinterPaperSize
Forces the printer to use a particular paper size, such as "Letter", "Legal", or "A4".
ForcePrinterResolution
Forces the printer to print a particular resolution, or dots per inch.
GetProperty
Retrieves settings from the printer using a keyword string.
SetProperty
Set individual printer settings using section and property names. See each individual set options call for a list of section and property names for each call.
SetCustomPaperOn
Enable or disable any custom paper size set.
SetCustomPaperOptions, ClearCustomPaperOptions
Set or clear custom paper size options. Custom paper must be enabled using SetCustomPaperOn for these options to be used.
SetDevmodeSettings, ClearDevModeSettings
[Deprecated - use ForcePrinteColorMode , ForcePrinterResolution, ForcePrinterOrientation and ForcePrinterPaperSize instead.]
Set or clear the printer orientation , color mode, resolution and paper size. Other printer options such as custom paper and fax mode can override these settings.
SetErrorReporting, ClearErrorReporting
Enables and disabled error reporting and debug tracing, sets trace file location.
SetFaxModeOn
Enable or disable fax mode.
SetFaxOptions, ClearFaxOptions
Sets or clears fax options. Fax mode must be enabled by calling SetFaxModeOn for these options to be used.
SetFileNamingOptions
[Deprecated - use SetSaveOptions, or SetV11CompatibilityModeEnabled and SetV11SaveOptions instead. Requires SetV11CompatibilityModeEnabled set to true.]
Set or clear serialized or multi-page output, append mode and set file location and base file naming options.
SetHardwareMargins, ClearHardwareMargins
Set or clear printer hardware margins.
SetImageCopyToOn
Enable or disabled image copy to options.
SetImageCopyToOptions, ClearImageCopyToOptions
Set or clear image copy options. Image Copy To options must be enabled by calling SetImageCopyToOn for these options to be applied.
SetJPEGCompressionOptions, ClearJPEGCompressionOptions
Sets or clears the color and greyscale compression options for creating JPEG files, or JPEG-compressed TIFF or PDF files.
SetMessageBoxAlerts, ClearMessageBoxAlerts
Set and clear error message box display options.
SetNamingProfileFormat, ClearNamingProfileFormat
[Requires SetV11CompatibilityModeEnabled set to true.]
Set and clear the advanced naming profile information for the specified file naming profile.
SetPageBrightness, ClearPageBrightness
Set and clear any page brightness options.
SetPageCropOn
Enable or disable page cropping options.
SetPageCropAreaOptions, ClearPageCropAreaOptions
Set and clear any page cropping area options. Page cropping must be enabled by calling SetPageCropOn for these options to be applied. Only one of SetPageCropAreaOptions or SetPageCropMarginOptions can be set at any one time. Whichever method is last called determines whether margins or a page area is cropped.
SetPageCropMarginOptions, ClearPageCropMarginOptions
Set and clear any page cropping margin options. Page cropping must be enabled by calling SetPageCropOn for these options to be applied. Only one of SetPageCropAreaOptions or SetPageCropMarginOptions can be set at any one time. Whichever method is last called determines whether margins or a page area is cropped.
SetPageRotationOptions, ClearPageRotationOptions
Set or clear page rotation options for portrait and landscape pages.
SetPageTrimOptions, ClearPageTrimOptions
Set or clear page trimming options
SetPDFCompressionOptions, ClearPDFCompressionOptions
Set or clear PDF compression options for color. indexed, greyscale and monochrome images.
SetPDFFileFormatOptions, ClearPDFFileFormatOptions
[Deprecated - use SetSaveOptions, or SetV11CompatibilityModeEnabled and SetV11SaveOptions, with SetPDFCompressionOptions instead.]
Set or clear PDF file format options including color reduction, dithering and compression methods for color. indexed, greyscale and monochrome images.
SetPDFPassword, ClearPDFPassword
Sets or clears the password options for PDF files.
SetPDFSecurity, ClearPDFSecurity
Sets or clears the security options for PDF files.
SetResamplingOn
Enable or disable resampling options.
SetResamplingOptions, ClearResamplingOptions
Set or clear resampling options. Resampling must be enabled by calling SetResamplingOn for these options to be applied.
SetRunAtEndCommand, ClearRunAtEndCommand
Set or clear any Run at End of Job commands. These commands are provided for compatibility with programs using previous versions of the printers; new applications should use the IPNSession events to perform custom actions.
SetRunAtStartCommand, ClearRunAtStartCommand
Set or clear any Run at Start commands. These commands are provided for compatibility with programs using previous versions of the printers; new applications should use the IPNSession events to perform custom actions.
SetSaveOptions
Sets file location and base file naming options, as well as append, prompting and overwrite options.
SetV11SaveOptions, ClearV11SaveOptions
[Requires SetV11CompatibilityModeEnabled set to true.]
Set or clear serialized or multi-page output, append mode and set file location and base file naming options. Use this method with SetV11CompatibilityModeEnabled when migrating from older versions to PNSrv12Lib. This method replaces the SetSaveOptions method used in previous versions.
SetSaveOptionsOutputLocationAndOutputFileName
Set or clear file location and base file naming options.
SetSaveOptionsOutputResolution
Set or clear output resolution options.
SetTextExtractionOn
Enable or disable the text extraction options.
SetTextExtractionOptions, ClearTextExtractionOptions
Set or clear the text extraction options. Text extraction must be enabled by calling SetTextExtractionOn for these options to be applied.
SetTIFFAdvancedOptions, ClearTIFFAdvancedOptions
Set or clear TIFF options such as fill order, photometric and byte alignment.
SetTIFFCompressionOptions, ClearTIFFCompressionOptions
Set or clear TIFF compression options for color, indexed, greyscale and monochrome images.
SetUserVariable
Set or clear any custom information.
Properties
Jobs
Read-only; A collection of IPNJob objects, one for each file printed.
TrackingOn
Read/Write; A boolean flag to turn job information tracking on or off.
Events
OnGetNextFileName
This event is fired each time a filename is needed, allowing full customization of the output file names.
OnStartJob, OnEndJob
Event is fired when a new print job has entered or exited the print queue.
OnOpenFile, OnCloseFile
This event is fired each time a new output file is opened or closed.
OnStartPage, OnEndPage
[Method signature has changed.]
This event is fired each time we start or finish creating a page in the file.
OnReportError
This event is fired when an error is reported by the driver.
OnLogMessage
This event is fired when an informational message is reported by the driver.
