doc/gug/guacamole-common-js.html

<!DOCTYPE html> <html class="writer-html5" lang="en" > <head> <meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>guacamole-common-js — Apache Guacamole Manual v1.5.5</title> <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> <link rel="stylesheet" href="_static/css/theme.css" type="text/css" /> <link rel="stylesheet" href="_static/tabs.css" type="text/css" /> <link rel="stylesheet" href="_static/gug.css" type="text/css" />  <script src="_static/jquery.js?v=5d32c60e"></script> <script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script> <script src="_static/documentation_options.js?v=5929fcd5"></script> <script src="_static/doctools.js?v=888ff710"></script> <script src="_static/sphinx_highlight.js?v=dc90522c"></script> <script src="_static/tabs.js?v=3ee01567"></script> <script src="_static/js/theme.js"></script> <link rel="index" title="Index" href="genindex.html" /> <link rel="search" title="Search" href="search.html" /> <link rel="next" title="guacamole-ext" href="guacamole-ext.html" /> <link rel="prev" title="guacamole-common" href="guacamole-common.html" /> </head> <body class="wy-body-for-nav"> <div class="wy-grid-for-nav"> <nav data-toggle="wy-nav-shift" class="wy-nav-side"> <div class="wy-side-scroll"> <div class="wy-side-nav-search" > <a href="index.html" class="icon icon-home"> Apache Guacamole </a> <div class="version"> 1.5.5 </div> <div role="search"> <form id="rtd-search-form" class="wy-form" action="search.html" method="get"> <input type="text" name="q" placeholder="Search docs" aria-label="Search docs" /> <input type="hidden" name="check_keywords" value="yes" /> <input type="hidden" name="area" value="default" /> </form> </div> </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu"> Overview <ul> <li class="toctree-l1"><a class="reference internal" href="introduction.html">Introduction</a></li> </ul> User's Guide <ul> <li class="toctree-l1"><a class="reference internal" href="guacamole-architecture.html">Implementation and architecture</a></li> <li class="toctree-l1"><a class="reference internal" href="installing-guacamole.html">Installing Guacamole natively</a></li> <li class="toctree-l1"><a class="reference internal" href="guacamole-docker.html">Installing Guacamole with Docker</a></li> <li class="toctree-l1"><a class="reference internal" href="reverse-proxy.html">Proxying Guacamole</a></li> <li class="toctree-l1"><a class="reference internal" href="configuring-guacamole.html">Configuring Guacamole</a></li> <li class="toctree-l1"><a class="reference internal" href="jdbc-auth.html">Database authentication</a></li> <li class="toctree-l1"><a class="reference internal" href="ldap-auth.html">LDAP authentication</a></li> <li class="toctree-l1"><a class="reference internal" href="vault.html">Retrieving secrets from a vault</a></li> <li class="toctree-l1"><a class="reference internal" href="duo-auth.html">Duo two-factor authentication</a></li> <li class="toctree-l1"><a class="reference internal" href="totp-auth.html">TOTP two-factor authentication</a></li> <li class="toctree-l1"><a class="reference internal" href="header-auth.html">HTTP header authentication</a></li> <li class="toctree-l1"><a class="reference internal" href="json-auth.html">Encrypted JSON authentication</a></li> <li class="toctree-l1"><a class="reference internal" href="cas-auth.html">CAS Authentication</a></li> <li class="toctree-l1"><a class="reference internal" href="openid-auth.html">OpenID Connect Authentication</a></li> <li class="toctree-l1"><a class="reference internal" href="saml-auth.html">SAML Authentication</a></li> <li class="toctree-l1"><a class="reference internal" href="radius-auth.html">RADIUS Authentication</a></li> <li class="toctree-l1"><a class="reference internal" href="adhoc-connections.html">Ad-hoc Connections</a></li> <li class="toctree-l1"><a class="reference internal" href="using-guacamole.html">Using Guacamole</a></li> <li class="toctree-l1"><a class="reference internal" href="recording-playback.html">Viewing session recordings in-browser</a></li> <li class="toctree-l1"><a class="reference internal" href="administration.html">Administration</a></li> <li class="toctree-l1"><a class="reference internal" href="troubleshooting.html">Troubleshooting</a></li> </ul> Developer's Guide <ul class="current"> <li class="toctree-l1"><a class="reference internal" href="guacamole-protocol.html">The Guacamole protocol</a></li> <li class="toctree-l1"><a class="reference internal" href="libguac.html">libguac</a></li> <li class="toctree-l1"><a class="reference internal" href="guacamole-common.html">guacamole-common</a></li> <li class="toctree-l1 current"><a class="current reference internal" href="#">guacamole-common-js</a><ul> <li class="toctree-l2"><a class="reference internal" href="#guacamole-client">Guacamole client</a></li> <li class="toctree-l2"><a class="reference internal" href="#http-tunnel">HTTP tunnel</a></li> <li class="toctree-l2"><a class="reference internal" href="#input-abstraction">Input abstraction</a><ul> <li class="toctree-l3"><a class="reference internal" href="#mouse">Mouse</a></li> <li class="toctree-l3"><a class="reference internal" href="#touch">Touch</a></li> <li class="toctree-l3"><a class="reference internal" href="#keyboard">Keyboard</a></li> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="#on-screen-keyboard">On-screen keyboard</a><ul> <li class="toctree-l3"><a class="reference internal" href="#keyboard-layouts">Keyboard layouts</a></li> <li class="toctree-l3"><a class="reference internal" href="#displaying-the-keyboard">Displaying the keyboard</a></li> <li class="toctree-l3"><a class="reference internal" href="#styling-the-keyboard">Styling the keyboard</a></li> <li class="toctree-l3"><a class="reference internal" href="#handling-key-events">Handling key events</a></li> </ul> </li> </ul> </li> <li class="toctree-l1"><a class="reference internal" href="guacamole-ext.html">guacamole-ext</a></li> <li class="toctree-l1"><a class="reference internal" href="custom-protocols.html">Adding new protocols</a></li> <li class="toctree-l1"><a class="reference internal" href="custom-auth.html">Custom authentication</a></li> <li class="toctree-l1"><a class="reference internal" href="event-listeners.html">Event listeners</a></li> <li class="toctree-l1"><a class="reference internal" href="writing-you-own-guacamole-app.html">Writing your own Guacamole application</a></li> </ul> Appendices <ul> <li class="toctree-l1"><a class="reference internal" href="protocol-reference.html">Guacamole protocol reference</a></li> </ul> </div> </div> </nav> <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" > <a href="index.html">Apache Guacamole</a> </nav> <div class="wy-nav-content"> <div class="rst-content"> <div role="navigation" aria-label="Page navigation"> <ul class="wy-breadcrumbs"> <li><a href="index.html" class="icon icon-home" aria-label="Home"></a></li> <li class="breadcrumb-item active">guacamole-common-js</li> <li class="wy-breadcrumbs-aside"> <a href="_sources/guacamole-common-js.md.txt" rel="nofollow"> View page source</a> </li> </ul> <hr/> </div> <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article"> <div itemprop="articleBody"> <section id="guacamole-common-js"> <h1>guacamole-common-js<a class="headerlink" href="#guacamole-common-js" title="Link to this heading"></a></h1> The Guacamole project provides a JavaScript API for interfacing with other components that conform to the design of Guacamole, such as projects using libguac or guacamole-common. This API is called guacamole-common-js. guacamole-common-js provides a JavaScript implementation of a Guacamole client, as well as tunneling mechanisms for getting protocol data out of JavaScript and into guacd or the server side of a web application. For convenience, it also provides mouse and keyboard abstraction objects that translate JavaScript mouse, touch, and keyboard events into consistent data that Guacamole can more easily digest. The extendable on-screen keyboard that was developed for the Guacamole web application is also included. <section id="guacamole-client"> <h2>Guacamole client<a class="headerlink" href="#guacamole-client" title="Link to this heading"></a></h2> The main benefit to using the JavaScript API is the full Guacamole client implementation, which implements all Guacamole instructions, and makes use of the tunnel implementations provided by both the JavaScript and Java APIs. Using the Guacamole client is straightforward. The client, like all other objects within the JavaScript API, is within the <code class="docutils literal notranslate">Guacamole</code> namespace. It is instantiated given an existing, unconnected tunnel: <div class="highlight-javascript notranslate"><div class="highlight"><pre>var client = new Guacamole.Client(tunnel); </pre></div> </div> Once you have the client, it won’t immediately appear within the DOM. You need to add its display element manually: <div class="highlight-javascript notranslate"><div class="highlight"><pre>document.body.appendChild(client.getDisplay().getElement()); </pre></div> </div> At this point, the client will be visible, rendering all updates as soon as they are received through the tunnel. <div class="highlight-javascript notranslate"><div class="highlight"><pre>client.connect(); </pre></div> </div> It is possible to pass arbitrary data to the tunnel during connection which can be used for authentication or for choosing a particular connection. When the <code class="docutils literal notranslate">connect()</code> function of the Guacamole client is called, it in turn calls the <code class="docutils literal notranslate">connect()</code> function of the tunnel originally given to the client, establishing a connection. <div class="admonition important"> Important When creating the <code class="docutils literal notranslate">Guacamole.Client</code>, the tunnel used must not already be connected. The <code class="docutils literal notranslate">Guacamole.Client</code> will call the <code class="docutils literal notranslate">connect()</code> function for you when its own <code class="docutils literal notranslate">connect()</code> function is invoked. If the tunnel is already connected when it is given to the <code class="docutils literal notranslate">Guacamole.Client</code>, connection may not work at all. </div> In general, all instructions available within the Guacamole protocol are automatically handled by the Guacamole client, including instructions related to audio and video. The only instructions which you must handle yourself are “name” (used to name the connection), “clipboard” (used to update clipboard data on the client side), and “error” (used when something goes wrong server-side). Each of these instructions has a corresponding event handler; you need only supply functions to handle these events. If any of these event handlers are left unset, the corresponding instructions are simply ignored. </section> <section id="http-tunnel"> <h2>HTTP tunnel<a class="headerlink" href="#http-tunnel" title="Link to this heading"></a></h2> Both the Java and JavaScript API implement corresponding ends of an HTTP tunnel, based on <code class="docutils literal notranslate">XMLHttpRequest</code>. The tunnel is a true stream - there is no polling. An initial request is made from the JavaScript side, and this request is handled on the Java side. While this request is open, data is streamed along the connection, and instructions within this stream are handled as soon as they are received by the client. While data is being streamed along this existing connection, a second connection attempt is made. Data continues to be streamed along the original connection until the server receives and handles the second request, at which point the original connection closes and the stream is transferred to the new connection. This process repeats, alternating between active streams, thus creating an unbroken sequence of instructions, while also allowing JavaScript to free any memory used by the previously active connection. The tunnel is created by supplying the relative URL to the server-side tunnel servlet: <div class="highlight-javascript notranslate"><div class="highlight"><pre>var tunnel = new Guacamole.Tunnel("tunnel"); </pre></div> </div> Once created, the tunnel can be passed to a <code class="docutils literal notranslate">Guacamole.Client</code> for use in a Guacamole connection. The tunnel actually takes care of the Guacamole protocol parsing on behalf of the client, triggering “oninstruction” events for every instruction received, splitting each element into elements of an array so that the client doesn’t have to. </section> <section id="input-abstraction"> <h2>Input abstraction<a class="headerlink" href="#input-abstraction" title="Link to this heading"></a></h2> Browsers can be rather finicky when it comes to keyboard and mouse input, not to mention touch events. There is little agreement on which keyboard events get fired when, and what detail about the event is made available to JavaScript. Touch and mouse events can also cause confusion, as most browsers will generate both events when the user touches the screen (for compatibility with JavaScript code that only handles mouse events), making it more difficult for applications to support both mouse and touch independently. The Guacamole JavaScript API abstracts mouse, keyboard, and touch interaction, providing several helper objects which act as an abstract interface between you and the browser events. <section id="mouse"> <h3>Mouse<a class="headerlink" href="#mouse" title="Link to this heading"></a></h3> Mouse event abstraction is provided by the <code class="docutils literal notranslate">Guacamole.Mouse</code> object. Given an arbitrary DOM element, <code class="docutils literal notranslate">Guacamole.Mouse</code> triggers onmousedown, onmousemove, and onmouseup events which are consistent across browsers. This object only responds to true mouse events. Mouse events which are actually the result of touch events are ignored. <div class="highlight-javascript notranslate"><div class="highlight"><pre>var element = document.getElementById("some-arbitrary-id"); var mouse = new Guacamole.Mouse(element); mouse.onmousedown = mouse.onmousemove = mouse.onmouseup = function(state) { // Do something with the mouse state received ... }; </pre></div> </div> The handles of each event are given an instance of <code class="docutils literal notranslate">Guacamole.Mouse.State</code> which represents the current state of the mouse, containing the state of each button (including the scroll wheel) as well as the X and Y coordinates of the pointer in pixels. </section> <section id="touch"> <h3>Touch<a class="headerlink" href="#touch" title="Link to this heading"></a></h3> Touch event abstraction is provided by either <code class="docutils literal notranslate">Guacamole.Touchpad</code> (emulates a touchpad to generate artificial mouse events) or <code class="docutils literal notranslate">Guacamole.Touchscreen</code> (emulates a touchscreen, again generating artificial mouse events). Guacamole uses the touchpad emulation, as this provides the most flexibility and mouse-like features, including scrollwheel and clicking with different buttons, but your preferences may differ. <div class="highlight-javascript notranslate"><div class="highlight"><pre>var element = document.getElementById("some-arbitrary-id"); var touch = new Guacamole.Touchpad(element); // or Guacamole.Touchscreen touch.onmousedown = touch.onmousemove = touch.onmouseup = function(state) { // Do something with the mouse state received ... }; </pre></div> </div> Note that even though these objects are touch-specific, they still provide mouse events. The state object given to the event handlers of each event is still an instance of <code class="docutils literal notranslate">Guacamole.Mouse.State</code>. Ultimately, you could assign the same event handler to all the events of both an instance of <code class="docutils literal notranslate">Guacamole.Mouse</code> as well as <code class="docutils literal notranslate">Guacamole.Touchscreen</code> or <code class="docutils literal notranslate">Guacamole.Touchpad</code>, and you would magically gain mouse and touch support. This support, being driven by the needs of remote desktop, is naturally geared around the mouse and providing a reasonable means of interacting with it. For an actual mouse, events are translated simply and literally, while touch events go through additional emulation and heuristics. From the perspective of the user and the code, this is all transparent. </section> <section id="keyboard"> <h3>Keyboard<a class="headerlink" href="#keyboard" title="Link to this heading"></a></h3> Keyboard events in Guacamole are abstracted with the <code class="docutils literal notranslate">Guacamole.Keyboard</code> object as only keyup and keydown events; there is no keypress like there is in JavaScript. Further, all the craziness of keycodes vs. scancodes vs. key identifiers normally present across browsers is abstracted away. All your event handlers will see is an X11 keysym, which represent every key unambiguously. Conveniently, X11 keysyms are also what the Guacamole protocol requires, so if you want to use <code class="docutils literal notranslate">Guacamole.Keyboard</code> to drive key events sent over the Guacamole protocol, everything can be connected directly. Just like the other input abstraction objects, <code class="docutils literal notranslate">Guacamole.Keyboard</code> requires a DOM element as an event target. Only key events directed at this element will be handled. <div class="highlight-javascript notranslate"><div class="highlight"><pre>var keyboard = new Guacamole.Keyboard(document); keyboard.onkeydown = function(keysym) { // Do something ... }; keyboard.onkeyup = function(keysym) { // Do something ... }; </pre></div> </div> In this case, we are using <code class="docutils literal notranslate">document</code> as the event target, thus receiving all key events while the browser window (or tab) has focus. </section> </section> <section id="on-screen-keyboard"> <h2>On-screen keyboard<a class="headerlink" href="#on-screen-keyboard" title="Link to this heading"></a></h2> The Guacamole JavaScript API also provides an extendable on-screen keyboard, <code class="docutils literal notranslate">Guacamole.OnScreenKeyboard</code>, which requires the URL of an XML file describing the keyboard layout. The on-screen keyboard object provides no hard-coded layout information; the keyboard layout is described entirely within the XML layout file. <section id="keyboard-layouts"> <h3>Keyboard layouts<a class="headerlink" href="#keyboard-layouts" title="Link to this heading"></a></h3> The keyboard layout XML included in the Guacamole web application would be a good place to start regarding how these layout files are written, but in general, the keyboard is simply a set of rows or columns, denoted with <code class="docutils literal notranslate"><row></code> and <code class="docutils literal notranslate"><column></code> tags respectively, where each can be nested within the other as desired. Each key is represented with a <code class="docutils literal notranslate"><key></code> tag, but this is not what the user sees, nor what generates the key event. Each key contains any number of <code class="docutils literal notranslate"><cap></code> tags, which represent the visible part of the key. The cap describes which X11 keysym will be sent when the key is pressed. Each cap can be associated with any combination of arbitrary modifier flags which dictate when that cap is active. For example: <div class="highlight-xml notranslate"><div class="highlight"><pre><keyboard lang="en_US" layout="example" size="5"> <row> <key size="4"> <cap modifier="shift" keysym="0xFFE1">Shift</cap> </key> <key> <cap>a</cap> <cap if="shift">A</cap> </key> </row> </keyboard> </pre></div> </div> Here we have a very simple keyboard which defines only two keys: “shift” (a modifier) and the letter “a”. When “shift” is pressed, it sets the “shift” modifier, affecting other keys in the keyboard. The “a” key has two caps: one lowercase (the default) and one uppercase (which requires the shift modifier to be active). Notice that the shift key needed the keysym explicitly specified, while the “a” key did not. This is because the on-screen keyboard will automatically derive the correct keysym from the text of the key cap if the text contains only a single character. </section> <section id="displaying-the-keyboard"> <h3>Displaying the keyboard<a class="headerlink" href="#displaying-the-keyboard" title="Link to this heading"></a></h3> Once you have a keyboard layout available, adding an on-screen keyboard to your application is simple: <div class="highlight-javascript notranslate"><div class="highlight"><pre>// Add keyboard to body var keyboard = new Guacamole.OnScreenKeyboard("path/to/layout.xml"); document.body.appendChild(keyboard.getElement()); // Set size of keyboard to 100 pixels keyboard.resize(100); </pre></div> </div> Here, we have explicitly specified the width of the keyboard as 100 pixels. Normally, you would determine this by inspecting the width of the containing component, or by deciding on a reasonable width beforehand. Once the width is given, the height of the keyboard is determined based on the arrangement of each row. </section> <section id="styling-the-keyboard"> <h3>Styling the keyboard<a class="headerlink" href="#styling-the-keyboard" title="Link to this heading"></a></h3> While the <code class="docutils literal notranslate">Guacamole.OnScreenKeyboard</code> object will handle most of the layout, you will still need to style everything yourself with CSS to get the elements to render properly and the keys to change state when clicked or activated. It defines several CSS classes, which you will need to manually style to get things looking as desired: <dl class="simple myst"> <dt><code class="docutils literal notranslate">guac-keyboard</code></dt><dd>This class is assigned to the root element containing the entire keyboard, returned by <code class="docutils literal notranslate">getElement()</code>, </dd> <dt><code class="docutils literal notranslate">guac-keyboard-row</code></dt><dd>Assigned to the <code class="docutils literal notranslate">div</code> elements which contain each row. </dd> <dt><code class="docutils literal notranslate">guac-keyboard-column</code></dt><dd>Assigned to the <code class="docutils literal notranslate">div</code> elements which contain each column. </dd> <dt><code class="docutils literal notranslate">guac-keyboard-gap</code></dt><dd>Assigned to any <code class="docutils literal notranslate">div</code> elements created as a result of <code class="docutils literal notranslate"><gap></code> tags in the keyboard layout. <code class="docutils literal notranslate"><gap></code> tags are intended to behave as keys with no visible styling or caps. </dd> <dt><code class="docutils literal notranslate">guac-keyboard-key-container</code></dt><dd>Assigned to the <code class="docutils literal notranslate">div</code> element which contains a key, and provides that key with its required dimensions. It is this element that will be scaled relative to the size specified in the layout XML and the size given to the <code class="docutils literal notranslate">resize()</code> function. </dd> <dt><code class="docutils literal notranslate">guac-keyboard-key</code></dt><dd>Assigned to the <code class="docutils literal notranslate">div</code> element which represents the actual key, not the cap. This element will not directly contain text, but it will contain all caps that this key can have. With clever CSS rules, you can take advantage of this and cause inactive caps to appear on the key in a corner (for example), or hide them entirely. </dd> <dt><code class="docutils literal notranslate">guac-keyboard-cap</code></dt><dd>Assigned to the <code class="docutils literal notranslate">div</code> element representing a key cap. Each cap is a child of its corresponding key, and it is up to the author of the CSS rules to hide or show or reposition each cap appropriately. Each cap will contain the display text defined within the <code class="docutils literal notranslate"><cap></code> element in the layout XML. </dd> <dt><code class="samp docutils literal notranslate">guac-keyboard-requires-MODIFIER</code></dt><dd>Added to the cap element when that cap requires a specific modifier. </dd> <dt><code class="samp docutils literal notranslate">guac-keyboard-uses-MODIFIER</code></dt><dd>Added to the key element when any cap contained within it requires a specific modifier. </dd> <dt><code class="samp docutils literal notranslate">guac-keyboard-modifier-MODIFIER</code></dt><dd>Added to and removed from the root keyboard element when a modifier key is activated or deactivated respectively. </dd> <dt><code class="docutils literal notranslate">guac-keyboard-pressed</code></dt><dd>Added to and removed from any key element as it is pressed and released respectively. </dd> </dl> <div class="admonition important"> Important The CSS rules required for the on-screen keyboard to work as expected can be quite complex. Looking over the CSS rules used by the on-screen keyboard in the Guacamole web application would be a good place to start to see how the appearance of each key can be driven through the simple class changes described above. Inspecting the elements of an active on-screen keyboard within the Guacamole web application with the developer tools of your favorite browser is also a good idea. </div> </section> <section id="handling-key-events"> <h3>Handling key events<a class="headerlink" href="#handling-key-events" title="Link to this heading"></a></h3> Key events generated by the on-screen keyboard are identical to those of <code class="docutils literal notranslate">Guacamole.Keyboard</code> in that they consist only of a single X11 keysym. Only keyup and keydown events exist, as before; there is no keypress event. <div class="highlight-javascript notranslate"><div class="highlight"><pre>// Assuming we have an instance of Guacamole.OnScreenKeyboard already // called "keyboard" keyboard.onkeydown = function(keysym) { // Do something ... }; keyboard.onkeyup = function(keysym) { // Do something ... }; </pre></div> </div> </section> </section> </section> </div> </div> <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer"> <a href="guacamole-common.html" class="btn btn-neutral float-left" title="guacamole-common" accesskey="p" rel="prev"> Previous</a> <a href="guacamole-ext.html" class="btn btn-neutral float-right" title="guacamole-ext" accesskey="n" rel="next">Next </a> </div> <hr/> <div role="contentinfo"> Copyright © 2024 <a href="http://www.apache.org/">The Apache Software Foundation</a>, Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>. Apache Guacamole, Guacamole, Apache, the Apache feather logo, and the Apache Guacamole project logo are trademarks of The Apache Software Foundation. </div> Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>. </footer> </div> </div> </section> </div> <script> jQuery(function () { SphinxRtdTheme.Navigation.enable(true); }); </script> </body> </html>

doc/gug/guacamole-common-js.html (460 lines of code) (raw):