.. Launchers documentation started in sphynx on March 13 2021 Launchers ^^^^^^^^^^^^^ ######################### Purpose ######################### *************************** About author *************************** I am Sergey A. Belous and this is my `home page `_. *************************** About Proxy32 software *************************** In my free time I develop Windows software called `Proxy32 `_ (64-bit GUI executable written in C++). It helps me to organize and perform rather generic and routine computer tasks at work and at home. It is beneficial to have all kind of routine computer tasks neatly organized and always one click away for execution. Examples of routine computer tasks: start programs, open files, fill in the web forms (login/etc) or type complex parametric commands via remote desktop window or via console of virtual machine, especially, when copy/paste does not work. Please, see :numref:`some-launchers-to-execute-routine-computer-tasks`. .. note:: Proxy32 functionality evolution. Over the years (since 2001) functionality of Proxy32.exe software was evolving in different directions. It has started from original focus on development of custom-made automated terminal software that is well integrated with CYGWIN and overcomes many limitations of existing terminals. More recent development focus is on controlling external RemoteDesktop/VM_Console and WebBrowser windows in a manner similar to what can be achieved via AHK. Latest Proxy32 functionality is subset of functionality that one can achieve using AHK, but AHK requires learning the whole new programing language while Proxy32 is trying to employ more of GUI-driven approach for the subset of AHK functionality available. ########################## Launchers and LauncherTree ########################## Starting from 2001 after switching from HP UNIX workstation to Dell Windows laptop at work power of UNIX was missing and there was a desire to automate in Windows all routine operations like starting terminal and automatically connect it to remote host (like router or Linux server) or sending pre-defined sequence of command to such terminal or even opening internal documentation page for such command sequence without regards to what kind of bookmarks are stored (or not stored) in any particular browser. Those operation were eventually presented as nodes on the tree to make them easily accessible. The tree itself is located in the floating application window positioned over or next to terminal window and browser window. When user double-clicks on such tree node routine operation will be executed based on configuration stored inside of such tree node. Such tree nodes can be configured by user in advance and they can be made more universal (applicable to wider ranges of curcumstances) by using substitution parameters (substitution strings) instead of port and hostname for terminal connection or by using substitution parameters for disk or card name in sequence of commands or using substitution parameters in predefined internal URL to switch directly to desired document or topic. Such tree nodes later got to be called Launchers in Proxy32 lingo and the tree window inside of Proxy32 application goes by the name LauncherTree window. Each Launcher is always created by user with the fixed type assigned. There are dozens of Launcher types available for use in Proxy32. Each type can perform very specific operation and it is up to user to choose which type will better suit for the task at hand. In the rest of this chapter I will make an attempt to describe all Launcher types and explain what purpose was in mind when each type was introduced. Some minimal examples will be given to illustrate the use. ################################### Quick overview of Launcher types ################################### +------------------+-------------------------------------------------------------+-------------------------------------------------+ | Launcher Type | Purpose | Configuration parameters | +==================+=============================================================+=================================================+ | SUBTREE | To group other launchers under common root tree node. | Name of the SUBTREE | | | It will collapse (hiding child launchers) or expand | | | | (showing child launchers) on user's double-click. | | | | This is the only node type that can have children nodes | | | | on the LauncherTree. SUBTREE is equivalent to folder | | | | for tree-representation of the directory and file | | | | hierarchy. | | +------------------+-------------------------------------------------------------+-------------------------------------------------+ | COM-PORT-TERMINAL| To create window of Proxy32 built-in terminal and | COM-PORT name and set of | | | connect it to specific COMPORT with specific | communication parameter to | | | communication parameters set | configure the port | +------------------+-------------------------------------------------------------+-------------------------------------------------+ | TELNET-TERMINAL | To create window of Proxy32 built-in terminal and | Hostname or IPv4 of TELNET | | | connect it to specific TELNET or TELNET/TLS server | server, TCP port and TLS | | | | parameters in case TLS is being used | +------------------+-------------------------------------------------------------+-------------------------------------------------+ | SHELL-TERMINAL | To create window of Proxy32 built-in terminal and | Command line to start local child windows | | | connect it to specific Windows or CYGWIN shell or | process. Terminal communicates with child | | | communication shell (which in turn may be | process via STDIN/STDOUT/STDERR. Local process | | | connected to remote server) | can be Windows cmd.exe or it can be (included | | | | with Proxy32) CYGWIN backend called | | | | 'proxycygterm.exe' (based on old 'cygterm' code)| | | | or it can be (included | | | | with Proxy32) SSH backend called | | | | 'proxyplink.exe' (based on PuTTY Plink code). | | | | 'proxycygterm.exe' provides terminal interface | | | | with CYGWIN bash or with CYGWIN communication | | | | shells and termial multiplexers such as | | | | SSH/SFTP/TELNET/FTP/SCREEN. | | | | 'proxyplink.exe' allows to leave all details | | | | of SSH coding and all the options to developers | | | | of PuTTY. | +------------------+-------------------------------------------------------------+-------------------------------------------------+ | COMMAND | - Sends text of the command to active built-in terminal | Text of the command to be sent. | | | by injecting it into byte stream towards the remote host | | | | | | | | or | | | | | | | | - sends text of the command to the active window of external| | | | process by injecting the text into keyboard driver queue | | +------------------+-------------------------------------------------------------+-------------------------------------------------+ | SCRIPT | - Sends text line by line from attached text file to | Path to the text file with lines/commands | | | the remote host of active built-in terminal. | to be sent. | | | Next line is sent automatically only after output | | | | of remote host is paused (was not active) | | | | for specified number of seconds. | | | | | | | | or | | | | | | | | - Sends one text line from attached text file to | | | | the active window of external process by injecting | | | | the text into keyboard driver queue. Next line is sent | | | | when user double-clicks on the same launcher again. | | +------------------+-------------------------------------------------------------+-------------------------------------------------+ | I-SCRIPT | - Sends text line by line from attached text file to | Path to the text file with lines/commands | | | the remote host of active built-in terminal. | to be sent. Each line contains three parts: | | | Next line is sent automatically only after output | | | | of remote host contains match for given | - text of command to be sent | | | regular expression. If output of the command is paused | | | | for given number of seconds and regular | - regular expression to be matched | | | expession is not yet matched, the next line will not be | by command output in order to continue | | | sent and execution of the launcher will be stopped. | to execute next line. | | | | | | | - I-SCRIPT can be invoked automatically by connect event of | - timeout value to indicate maximum pause | | | associated built-in terminal window. In such case it | in the output of command when regular | | | can be used to finish automatic terminal login sequence. | expression is not yet matched the output | +------------------+-------------------------------------------------------------+-------------------------------------------------+ | PLUGIN | Creates child process to control interaction of built-in | Command line to create child process. | | | terminal with remote host. On creation STDOUT of the child | | | | process is connected to write bytes towards remote host, | PLUGIN can be written in any language. | | | STDIN of the child process is connected to read bytes from | | | | remote host, and STDERR of the child process is connected | Examples will be provided of PLUGINs | | | to write bytes to the screen of the built-in terminal. | written in PERL, PYTHON, EXPECT, LUA | | | Keyboard of terminal user is temporarily disconnected. | | | | When child process exits built-in terminal detects it | | | | and automatically reconnects remote host I/O to terminal | | | | screen and keyboard. User can kill stuck child process | | | | by clicking "Kill" button in terminal window. | | | | | | | | PLUGIN can be invoked automatically by connect event of | | | | associated built-in terminal window. In such case it | | | | can be used to finish automatic terminal login sequence. | | +------------------+-------------------------------------------------------------+-------------------------------------------------+ | I-PLUGIN | Creates child process to control interaction of built-in | Command line to create child process. | | | terminal with remote host. On creation STDOUT of the child | | | | process is connected to write bytes towards remote host, | I-PLUGIN can be written in any language. | | | STDIN of the child process is connected to read bytes from | | | | remote host, and STDERR of the child process is connected | Examples will be provided of PLUGINs | | | to write bytes to the screen of the built-in terminal. | written in PERL, PYTHON, EXPECT, LUA | | | | | | | Keyboard of terminal user is writing to temporary file. | | | | Name of temporary file is passed/appended | | | | as a last parameter on command line of I-PLUGIN child | | | | process. I-PLUGIN child process can open temporary file | | | | and read user keystrokes from it. | | | | | | | | When child process exits built-in terminal detects it | | | | and automatically reconnects remote host I/O to terminal | | | | screen and keyboard. User can kill stuck child process | | | | by clicking "Kill" button in terminal window. In any case | | | | temporary file with user keystrokes is deleted when child | | | | process exited or terminated by user of terminal. | | +------------------+-------------------------------------------------------------+-------------------------------------------------+ | LAUNCH | Start Windows Process based | Command line for the process to start. | | | on configured command line. | Regex pattern for window class and title to | | | Capture Process Window into | capture the window into Proxy32 list of | | | Proxy32 workspace if needed. | managed windows | | | Process can be started elevated. | | | | This is similar to Windows Shortcut. | | +------------------+-------------------------------------------------------------+-------------------------------------------------+ | VIEWER | Opens file/web-page with configured | - url of file/web-page to open - in launcher | | | application based on user-configured | | | | **"ViewerDefinions"** table. | - global mapping table of url regex | | | **"ViewerDefinions"** table is an | patterns to viewer application to be | | | ordered list of user-configured regular | used when given regex matches - in | | | expressions. Each regular expression in | the **"ViewerDefinions"** table. | | | the list is associated with certain | | | | windows application. Regular expressions | | | | in the list are sequentially applied | | | | to file/webpage URL configured in VIEWER. | | | | When first regular expression matches | | | | the URL, file or webpage is opened in the | | | | Windows application that is associated | | | | with matched regular expression. | | | | This is similar to associating Windows | | | | applications with file extensions. | | +------------------+-------------------------------------------------------------+-------------------------------------------------+ | CSVPARMS | Imports content of associated CSV file into Proxy32 | Path to CSV file to be imported | | | substitution parameters list | | +------------------+-------------------------------------------------------------+-------------------------------------------------+ | YAMLPARMS | Imports content of associated JSON/YML file into Proxy32 | Path to JSON/YML file to be imported | | | substitution parameters list | | +------------------+-------------------------------------------------------------+-------------------------------------------------+ | AHK-SCRIPT | Saves text to temporary file an passes this file for the | Text of AHK script to be executed | | | execution to external AHK interpreter that is installed | | | | with Proxy32. After execution temporary file is deleted. | | +------------------+-------------------------------------------------------------+-------------------------------------------------+ | LUA-SCRIPT | Passes text for execution to built-in LUA interpreter | Text of LUA script to be executed | +------------------+-------------------------------------------------------------+-------------------------------------------------+ | PYTHON-SCRIPT | Passes text for execution to built-in PYTHON interpreter | Text of PYTHON script to be executed | +------------------+-------------------------------------------------------------+-------------------------------------------------+ ########################## TERMINAL Launchers ########################## Proxy32 application has its own built-in terminal with the features that were desired at the time. That includes connectivity to modem (COMPORT) and telnet and telnet/TLS and direct interprocesss connectivity to dos cmd shell and to various CYGWIN shells. It also includes unlimited scroll buffer with regex search and bookmarking and autobookmarking capabilities. Another external terminal (possibly on remote machine) can connect via TELNET (possibly with TLS) or via COMPORT (possibly with BLUETOOTH) to Proxy32 built-in terminal and type commands into existing terminal session and see the responses coming to both local built-in terminal and to remote external terminal connected to local built-in terminal. That feature was named terminal session sharing and was widely popular at the time when Webex and needed network bandwith were not available for modern-style GUI screen sharing. Also at the time screen sharing over third party web-server probably would not play well from secirity standpoint. Of course, the primary need to develop proprietary built-in terminal in Proxy32 was because such terminal has to be designed from ground up to be controlled via Launchers and via Proxy32 GUI. There are several types of Launchers (COMMAND, SCRIPT, I-SCRIPT, PLUGIN, I-PLUGIN, SHELL-TERMINAL, TELNET-TERMINAL, COMPORT-TERMINAL) that dedicate full or part of their functionality specifically to control Proxy32 built-in terminal. In this chapter we will mention functionality of above Launchers while functionality of built-in terminal will be covered in general in the next chapter. It is hard to develop terminal as good and compatible as - free terminal PuTTY, - Xterm and PuTTY clone MinTTY under CYGWIN, - other commercially available Windows terminals like SecureCRT, to name a few. Therefore, for the situations when there is no compelling need to use built-in Proxy32 terminal, one can use PuTTY, Xterm and MinTTY. I have included those 3 terminals for convinience into Proxy32 self-installing executable. For example, such terminals can be started and connected via LAUNCH launcher (via command line) and then later COMMAND/SCRIPT launchers can be used to send sequences of parametrized commands to the windows of such terminals. As Proxy32 terminal has support for somewhat less terminal control sequences comparing to well established terminal emulators, there could be rare situations when in-terminal full screen application like VI/EMACS/SCREEN or something very proprietary may work better with well established terminal emulators. There are three types of launchers to start and connect Proxy32 built-in terminal: - COM-PORT-TERMINAL - TELNET-TERMINAL - SHELL-TERMINAL +------------------+---------------------------------------------------+-------------------------------------------------+ | Launcher Type | Purpose | Configuration parameters | +==================+===================================================+=================================================+ | COM-PORT-TERMINAL| To create window of Proxy32 built-in terminal and | COM-PORT name and set of | | | connect it to specific COMPORT with specific | communication parameter to | | | communication parameters set | configure the port | +------------------+---------------------------------------------------+-------------------------------------------------+ | TELNET-TERMINAL | To create window of Proxy32 built-in terminal and | Hostname or IPv4 of TELNET | | | connect it to specific TELNET or TELNET/TLS server| server, TCP port and TLS | | | | parameters in case TLS is being used | +------------------+---------------------------------------------------+-------------------------------------------------+ | SHELL-TERMINAL | To create window of Proxy32 built-in terminal and | Command line to start local child windows | | | connect it to specific Windows or CYGWIN shell or | process. Terminal communicates with child | | | communication shell (which in turn may be | process via STDIN/STDOUT/STDERR. Local process | | | connected to remote server) | can be Windows cmd.exe or it can be (included | | | | with Proxy32) CYGWIN backend called | | | | 'proxycygterm.exe' (based on old 'cygterm' code)| | | | or it can be (included | | | | with Proxy32) SSH backend called | | | | 'proxyplink.exe' (based on PuTTY Plink code). | | | | 'proxycygterm.exe' provides terminal interface | | | | with CYGWIN bash or with CYGWIN communication | | | | shells and termial multiplexers such as | | | | SSH/SFTP/TELNET/FTP/SCREEN. | | | | 'proxyplink.exe' allows to leave all details | | | | of SSH coding and all the options to developers | | | | of PuTTY. | +------------------+---------------------------------------------------+-------------------------------------------------+ .. note:: All Proxy32 Launchers have ToolTip text field. ToolTip field is used to show user-provided tooltips when mouse pointer is hovering over the launcher node on the LauncherTree. In case of SHELL-TERMINAL, TELNET-TERMINAL, COMPORT-TERMINAL tooltip field contains title for newly created window of built-in terminal.