PrintGate Thin Client – v.2.00.0001 - projects, source code, documentation, release specifications -
This document describes the complete projects and source code release for the entire PrintGate project, client side, server side, installation programs, protocol, documentation, prototypes, tools and programs, as well as the technologies used, software requirements, and detailed instructions on using, updating, building and releasing the entire distribution. The full release is organized in 10 folders, as described below: ClientProjects – contains the entire suite of projects needed to build the client release. There are 6 Visual C++ 6.0 projects in this distribuition, as described below. They all require: Microsoft Windows 2000 or Microsoft Windows XP or Microsoft Windows Vista installed, Microsoft Windows 2000 Platform SDK, and Microsoft Visual Studio 6.0 installed in order to be opened, ran, and built successfully. The Platform SDK’s include and lib paths must be added and moved in the first position in the Microsoft Visual C++ 6.0 environment. The projects open in the environment for updates and rebuilds through the main *.dsw file available in each project folder, that contains complete project data. The main build results, the *.exe or *.dll files will result into four different versions, in four different subfolders under the project folder. The Debug versions are used in debugging sessions, while the Release versions are used for distribution. The simple (ANSI) versions may be used if no internationalization features are required, the Unicode versions are used for versions that support internationalizations and multiple character sets. In conlusion, the version that will be used for packaging and distribution for a new release, is the Unicode Release version. PrintGate – is the main PrintGate Thin Client project, resulting in the module (PrintGate.exe) that actually performs all printer monitoring, client-server comunication and graphical interface, along with all other logic, operation, and features that this version contains. It is a complex project, consisting of over 100 source files and classes, running on up to 10 execution threads, that perform all the client logic. As of this version, it does not contain any hard-coded interface strings. Instead, it loads all the strings and messages that interface the user, from a separate resources library (PrintGate.dll) that contains all these resources for a given language. The installer program decides which one of these resources library will actualy acompany the installation, thus the client will run in the selected and installed language. Another executable module (PrintMonitor.exe) is also installed alongside, actualy a system windows service, unstopable through normal operations, that has the only task of keeping the main module PrintGate.exe alive and running at all times, starting it at system starts and logons, restarting and reinitializing it upon critical errors, crashes, or user intervention, and protecting it from unauthorized actions, deletion, etc. Aside from that, all other features, logic, processing, data and resources are located inside the current PrintGate project, including monitoring the system registry settings, client’s files and folders, and printer settings changes, which were prefiously PrintMonitor’s atribution. That is why this is the most critical project of this release and must be handled appropriately. The architecture is highly modular and
scalable, names and conventions used pretty self explanatory, and attention has been payed to making the entire project as readble and well organized as possible, as well as commenting the critical sections, main modules, and using detailed logging that can be enabled at run time, or just used as refference points upon editing the project. The project results in a high performance, safe and stable module, that has absolutely no prerequisites upon running on client systems, and is now fully compatible with Microsoft Windows 2000, Microsoft Windows XP, and Microsoft Windows Vista, with all their flavours and types. The module is actualy a Windows COM Singletone Server that needs to be registered on the system to run, only runs in one instance per logged user, only starts given the appropriate command line, only runs when it can locate and load it’s system registry client settings and his language resources library, and cannot be stopped, disabled, or actually affected in any way while it’s PrintMonitor security service is running. After any change to this project, you must rebuild the entire distribution, and copy the resulted Unicode Release PrintGate.exe to the InstallerProjects\Client\INSTALLDIR\Service, then follow the rest of the steps further described. For local testing, you should copy the required Debug or Release, Unicode or Non-Unicode PrintGate.exe to ClientTest\PrintGate Thin Client\Service, and proceed as further instructed, or just run the project in debug mode from the Visual C++ 6.0 environment, after perfoming the required steps further described. PrintGateEng – is the PrintGate Thin Client English Language Resources Library project. It contains no actual logic, only the PrintGate Thin Client’s string resources for the English Language. They are located in the PrintGate.rc recources file, and should only be edited in the Visual C++ 6.0 resource editor. The resulting library (PrintGate.dll) is an actual Window COM local server, and must pe registerd on the client system, and reside by the main PrintGate.exe excutable, in the application path, for the client service to run. It’s registration data is also the signature used by the PrintGate Thin Client Web Installer, to determine if the client software is installed on the client system, needs to be installed or updated. In order to create a new language library, for a new language, the project only needs to be copied and rename with the appropriate language extension, the strings in the PrintGate.rc file translated to the required language, and the project rebuilt. No other change must be done to this project as it might compromise the client system’s ability to locate and load it, or the web installer’s ability to detect it. After any change to this project, you must rebuild the entire distribution, and copy the resulted Unicode Release PrintGate.dll to the InstallerProjects\Client\INSTALLDIR\Service\PrintGateEng, then follow the rest of the steps further described. For local testing, you should copy the required Debug or Release, Unicode or Non-Unicode PrintGate.dll to ClientTest\PrintGate Thin Client\Service, and proceed as further instructed. PrintGateRom – is the PrintGate Thin Client Romanian Language Resources Library. The instructions for this project are the same as above, and can be applied to any number of different language resources library, that can be simply generated by multiplying this project and translating the resource file. The resulted PrintGate.dll must then be copied in its own language subfolder in the installer project and included in the installer project, then only the selected language library will be installed on the client system alongside the main service files, and used for that installation.
PrintMonitor – is the PrintGate Thin Client Security Monitor, a Windows NT service (PrintMonitor.exe), that registers along the client system’s services, automatically starts with the system, restarts on crashes, does not accept shutdown or disabling, and permanently monitors the main PrintGate Thin Client service (PrintGate.exe) and its language resources library (PrintGate.dll). Aside from the task of sytem monitoring and protection, the most critical parts of the project consist of it’s underlying Windows NT Service architecture, and the registration settings that make it perform as required. The resulted service is very light on system resources, but provides one critical feature, making the PrintGate Thin Client system virtually full proof to any kind of system conditions or errors, any kind of intended or unintended user intervention, or any attempt to malliciously bypass or disable the sytem. While being a critical part of the system’s security in production distribution, the service des not play any part in the actual system’s activity, and can be turned off for development testing and debugging sessions, in order to allow stopping, modifying and overriding the main service files. After any change to this project, you must rebuild the entire distribution, and copy the resulted Unicode Release PrintMonitor.exe to the InstallerProjects\Client\INSTALLDIR\Service, then follow the rest of the steps further described. For local testing, you should copy the required Debug or Release, Unicode or Non-Unicode PrintMonitor.exe to ClientTest\PrintGate Thin Client\Service, and proceed as further instructed. SetupActionsDll – is a Windows Installer Custom Action Library (Custom.dll), that exports a series of functions to the installation process. The project contains some parts of the main PrintGate project, in order to make the installation/uninstallation xml request/response processing, as well as many other functions such as removing previous versions, configuring the package for installation/update/removal, installation language selection, services configuration, GUI tasks, and many others. The requirements for the Windows Installer Custom Actions Libraries make it impossible to use a good modular and abstract design, but rather a series of C-style functions that each perform a certain Windows Installer task. After any change to this project, you must rebuild the entire distribution, and copy the resulted Unicode Release Custom.dll to the InstallerProjects\Client folder, then rebuild the installer project and follow the rest of the steps further described. Tesing of the custom actions library functions can only be performed by actually running the installer program and monitoring the setup actions behavior. SetupActionsExe – is a very simple Setup Launcher Program (Setup.exe). As of this version the windows installer installation database (PrintGate Thin Client.msi), containing the setup actions library (Custom.dll), and accompanied by the setup initialization file (Setup.ini) is almost completely self sufficient and can be ran directly, without launching it from the setup launcher. However, the setup launcher provides some advantages, such as being the exe file to launch from a CD autorun feature, from the packaged or web releases, and is the only way, by reading the first two fields in the setup intialization file, that are only available through this launcher, to launch in the installation in silent, inivisible, unattended mode, or in visible or invisible update mode. All the rest of the fields in the setup initialization file are avaialble directly form the installation database, but due to limitaions of the Windows Installer technology itself, running the
installation process in silent or update mode can only be done by launching it from the setup launcher with the appropriate intialization parameters, which is why for these cases it is important to warn the users about not running the installation database directly, or to use the packed or web version which use the setup launcher by default. After any change to this project, you must rebuild the entire distribution, and copy the resulted Unicode Release Setup.exe directly to the Releases\Client\PrintGate\Unpacked, ready for distribution. That is the only destianation for the resulted executable, directly in the unpacked release folder, as the packed and web versios use a modified setup launcher, stored in the SetupPackager folder, that perfroms the same logic but also packs the files. ClientTest – contains a PrintGate Thin Client distribution for testing purposes, without the need to perform a client installation. In order to bring the client distribution in working condition, there are some prliminary steps to be taken: First copy the distribution in the location of your choice. The distribution initialy contains only the service files in the Service subfolder, and empty folders for the rest of the application files. Next add the Registry.reg file the system’s registry, by simpy running it. Now open the registry key HKLM\SOFTWARE\PGI Technologies\PrintGate Thin Client and set apropriate values for each value that is stores, with special attention to the application’s path which must point to the chosen location, and server data neded for the system to communicate. Now register the service files with the system by running the following command lines in the Service subfolder: Regsvr32.exe PrintGate.dll – to register the resources library. PrintGate.exe /RegServer – to register the main application server. PrintMonitor.exe /Regservice – only if you want to register the security monitor service, which is not reccomended for testing purposes. To start the security monitor service run the command line: net start PrintMonitor - after registering the service. The service cannot be stopped by running net stop, neither can it be stopped, disabled or altered in anyway from the services control manager. The only way it can be stopped and unregistered at the same time, is by running the command line: PrintMonitor.exe /Unregservice. With it stopped, you can freely manipulate, move, overrite the service and other application files. To start the main application server first make sure that no other instance of it is running under current account, from Task Manager. Then run the command line: PrintGate.exe /Monitor – in the Service Subfolder. This should start the PrintGate service and printer monitoring cycle. Stop the PrintGate service by ending the process from Task Manager. This will not succeed if the security monitor is running. To unregister the PrintGate service, run the command line: PrintGate.exe /UnregServer – in the Service subfolder. To unregister the language library run the command line: Regsvr32.exe /u PrintGate.dll – in the Service subfolder. You will not be able to make registry settings changes while the PrintGate service is running, if SystemProtection setting is ENABLED. This information should make it easier to test and debug the project, as the client installation disables by default any means of intervention, stoping, disabling, overriting, etc. of the service files. Documentation – contains all the available documents, diagrams, specifications, prototypes and tools used in this PrintGate release, including this document. Comments – contains the xml protocol requests and responses, xml client settings, client registry settings, and setup intialization settings files, with comments and
details for each value, sample settings and possible values. These are useful for quick reference in determining appropriate values and comparison with test values. Documents – contains the PrintGate Thin Client client-server communication diagram and data workflow, the protocol specifications draft, the database specifications draft, and this document, the projects, source code, documentation and release specifications. Protocol – contains the entire set of xml protocol request and response files, for quick reference and comparison with test values, as fully implemented as of this version. Prototypes – contains a series of Visual C++, Visual Basic, and .NET small scale projects, that emloy and test some of the new important features of the system, such as routing, spool file parsing and color detection. These were used in erly development and testing stages of these features, and can be used for reference and further developments on these features. Settings – contains a set of PrintGate Thin Client xml settings files, with sample values, similar to the ones that would result in a production environment, for reference and test comparison, along with the registry settings file, that can be used as the base to populate the registry with the required values for a PrintGate client to work, and a setup intialization file that can be used as the base to acompany client installation programs. Specifications – contains the original PrintGate Thin Client Version 2 specifications as agreed upon, and implemented as of this version. InstallerProjects – contains the Windows Installer projects used to create the installation databases for the components of the system to be released. At the moment it only contains the client installer project, but a new, improved, upgraded, server installer should be built as soon as possible. The client installer has been completely rebuilt to support the new internationalatization features now avaialble, better support for silent, unattended installations, automatic uninstallations and upgrades, and improved GUI. The project is created and built using InstallShiled Developer 8.0, and has no other prerequisites than running on Windows 2000 / XP / Vista with Microsoft Windows Installer engine version 2.0 or higher installed, included by default in service pack releases and windows updates. The installer project opens into the environment through its main project file, PrintGate.ism, located in the InstallerProjects\Client folder, and can be immediately rebuilt, after replacing the distributed files, located under the INSTALLDIR subfolder, as described above, the additional Custom.dll library or ExitSetup.vbs in the project folder or the Eula.rtf license agreement document. The project folder also contains a preconfigured Setup.ini file, that should also be properly customized for distribution upon building a new release, to be distributed alongside the PrintGate Thin Client.msi installation database, which results upon build in the PrintGate subfoler. The setup project contains solid logic, fully separated into the custom actions library, and usual update and maintainance of the project, such as service files updates, adding new languages, settings or files, is a very simple and straight forward process. As of this version the installation database can be ran standalone, with no predefined values, alongside the Setup.ini setup
intialization file to preconfigure the setup with client and server data, and appropriate initial client settings, or from the Setup.exe setup launcher file, the reccomended method, packed or unpacked, to allow silent installations and upgrades. After rebuilding the project, copy the customized Setup.ini file from the project folder, and the resulted PrintGate Thin Client.msi installation database from the PrintGate subfolder to the Releases\Client\PrintGate\Unpacked folder for standard installations, or Releases\Client\[CustomBuild]\Unpacked folder for custom builds, along side Setup.exe, for the unpacked release. For packed and web installations copy the above mentioned two files to the SetupPackager\Client folder, and follow further instructions. PackageBuilder – is at the moment an empty folder, that shall contain upon completion, the full release builder automation project, that shall automatically perform most of the steps described in this document, as requested, to build and prepare for distribution full custom releases, given the custom input data. Releases – is the folder where the fully built and cofigured distributions, ready fo release, in all needed, packed, unpacked, or web configurations, are stored according to their type and destination. At the moment it only contains a fully configured standard client release, located in the Releases\Client\Printgate folder, but a server release must also be prepared for local server configurations, and additional custom client builds shall be built upon need alongside the standard PrintGate distribution, the process, described throughout this document, buing a simple and straightforward one. ServerProjects – contains the full Eclipse Java server project. The project has not been radically changed, so it has the same structure, prerequisites and settings as it had when we started working on it, only a new clientV2 folder was added containing the logic behind the new version’s protocol, in the WEB-ING\src\com\printgate folder, along with three additional java files, Printer2.java, PrintFailure2.java, and PrintRequest2.java, in order to maintain the clientV1 protocol and files unchanged, needed changes were made to the web.xml and server.xml files to accommodate the new clientV2 web application, and the server database printgate.gdb was updated as described in the database specifications draft document, maintaining full compatibility with the previous versions. ServerTest – contains a full working PrintGate Local Server installation, used for testing, containing all the new classes and settings, and a new format database, preconfigured with some data that will make it usable right away for test client installations. This can be used for further server developments testing, by updating the modified classes and settings, and amking manual changes to the database until the web interface is updated, and used as the base for generating the new server installation database when needed. SetupPackager – contains a modified setup launcher Visual C++ 6.0 project, that packs the preconfigured Setup.ini setup intialization file, and PrintGate Thin Client.msi installation database, along with the setup launcher, and generates a single executable file, Setup.exe fully configured setup program, that can be distributed through any channel with maximum ease, with no risk of intervention on the stored settings or misuse. To build this packed release, overwrite the existiting Setup.ini and/or PrintGate Thin Client.msi files in the SetupPackager\Client folder with the newly cofigured/built ones as
deescribed above, open the project in Visual C++ 6.0 through its main project file, Setup.dsw, and fully rebuild it. Use the Debug versions for testing and debugging, and release versions for distribution. Use the Unicode versions for internationalized releases. After fully rebuilding, copy the resulting Setup.exe file in the Unicode Release folder to the apporpriate distribution folder in the Releases\Client subfolder, such as Releases\Client\PrintGate\Packed for the standard distribution, or Releases\Client\[CustomBuild]\Packed for a custom distribution. The resulted file contains everything needed to perform a full client installation, of any tipe, as configured through the Setup.ini file, and can also be used for automatic upgrades or downloads through the web. To generate a new web installation, copy the resulting Setup.exe file in the Unicode Release folder to the WebInstaller\Client folder, then follow further instructions. WebInstaller – contains the files needed to create an automatic web installation. To rebuild the web installer program, first overrite the existing printgate.exe program with the newly built packed setup program, Setup.exe, as described above, by copying and renaming. If the new build updates the client version, edit the printgate.inf file and modify the FileVersion field accordingly, then open the printgate.htm file and modify printgate.cab#version field in the second last row accordingly. The printgate.htm file is just a sample placeholder, the key to it are only the last two lines, which can be added to any download page of your will. After that, delete the old printgate.cab file, and generate a new printgate.cab file using any archiving program, such as win ace, by compressing printgate.exe and printgate.inf into a standard MS-Cabinet file. Finally, run the printgate.bat batch file to sign the cabinet with a test verisign certificate, for marking it as safe to download from the web and allow web clients to download and install it with normal security settings. For signing, you will have to provide a password of your will, the same throughtout the signing process. If necessarry, a production verisign certificate, with the name and logo of the owner, can be purchased, and the test certificate files, printgate.cer, printgate pvk and printgate.spc can be replaced with the production ones, maintaining the rest of the process. After that, you can copy the printgate.cab and printer.htm file if modified (or just the last two lines of it) into the Releases\Client\PrintGate\Webpacked folder, for a standard release, or Releases\Client\[CustomBuild]\Webpacked for a custom distribution. The files are now ready for automatic web distribution, and can be used for all purposes, normal silent, unattended installations, optional or automatic upgrades, etc. The page will only upgrade the client system if it detects the software is not installed, or an older version is installed, and performs no action if the current version is already installed. All this information should be able to help you perform the entire rebuild, update and customizing process, but we’ll be continuously available for this and perform all the steps involved quickly and accurately, and deliver the results within hours upon request, while preparing the automatic release builder projects, that shall further ease this job.