<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Appendix B. Guacamole protocol reference</title><link rel="stylesheet" type="text/css" href="gug.css" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="home" href="index.html" title="Guacamole Manual" /><link rel="up" href="appendices.html" title="Part III. Appendices" /><link rel="prev" href="faq.html" title="Appendix A. FAQ" /><link rel="next" href="book-index.html" title="Index" />
            <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0, user-scalable=no, target-densitydpi=device-dpi"/>
        </head><body>
            <!-- CONTENT -->

            <div id="page"><div id="content">
        <div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Appendix B. Guacamole protocol reference</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="faq.html">Prev</a> </td><th width="60%" align="center">Part III. Appendices</th><td width="20%" align="right"> <a accesskey="n" href="book-index.html">Next</a></td></tr></table><hr /></div><div xml:lang="en" class="appendix" lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="protocol-reference"></a>Appendix B. Guacamole protocol reference</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="section"><a href="protocol-reference.html#drawing-instructions">Drawing instructions</a></span></dt><dd><dl><dt><span class="section"><a href="protocol-reference.html#arc-instruction">arc</a></span></dt><dt><span class="section"><a href="protocol-reference.html#cfill-instruction">cfill</a></span></dt><dt><span class="section"><a href="protocol-reference.html#clip-instruction">clip</a></span></dt><dt><span class="section"><a href="protocol-reference.html#close-instruction">close</a></span></dt><dt><span class="section"><a href="protocol-reference.html#copy-instruction">copy</a></span></dt><dt><span class="section"><a href="protocol-reference.html#cstroke-instruction">cstroke</a></span></dt><dt><span class="section"><a href="protocol-reference.html#cursor-instruction">cursor</a></span></dt><dt><span class="section"><a href="protocol-reference.html#curve-instruction">curve</a></span></dt><dt><span class="section"><a href="protocol-reference.html#dispose-instruction">dispose</a></span></dt><dt><span class="section"><a href="protocol-reference.html#distort-instruction">distort</a></span></dt><dt><span class="section"><a href="protocol-reference.html#identity-instruction">identity</a></span></dt><dt><span class="section"><a href="protocol-reference.html#lfill-instruction">lfill</a></span></dt><dt><span class="section"><a href="protocol-reference.html#line-instruction">line</a></span></dt><dt><span class="section"><a href="protocol-reference.html#lstroke-instruction">lstroke</a></span></dt><dt><span class="section"><a href="protocol-reference.html#move-instruction">move</a></span></dt><dt><span class="section"><a href="protocol-reference.html#pop-instruction">pop</a></span></dt><dt><span class="section"><a href="protocol-reference.html#push-instruction">push</a></span></dt><dt><span class="section"><a href="protocol-reference.html#rect-instruction">rect</a></span></dt><dt><span class="section"><a href="protocol-reference.html#reset-instruction">reset</a></span></dt><dt><span class="section"><a href="protocol-reference.html#set-instruction">set</a></span></dt><dt><span class="section"><a href="protocol-reference.html#shade-instruction">shade</a></span></dt><dt><span class="section"><a href="protocol-reference.html#size-instruction">size</a></span></dt><dt><span class="section"><a href="protocol-reference.html#start-instruction">start</a></span></dt><dt><span class="section"><a href="protocol-reference.html#transfer-instruction">transfer</a></span></dt><dt><span class="section"><a href="protocol-reference.html#transform-instruction">transform</a></span></dt></dl></dd><dt><span class="section"><a href="protocol-reference.html#streaming-instructions">Streaming instructions</a></span></dt><dd><dl><dt><span class="section"><a href="protocol-reference.html#ack-instruction">ack</a></span></dt><dt><span class="section"><a href="protocol-reference.html#audio-stream-instruction">audio</a></span></dt><dt><span class="section"><a href="protocol-reference.html#blob-instruction">blob</a></span></dt><dt><span class="section"><a href="protocol-reference.html#clipboard-instruction">clipboard</a></span></dt><dt><span class="section"><a href="protocol-reference.html#end-instruction">end</a></span></dt><dt><span class="section"><a href="protocol-reference.html#file-stream-instruction">file</a></span></dt><dt><span class="section"><a href="protocol-reference.html#img-instruction">img</a></span></dt><dt><span class="section"><a href="protocol-reference.html#nest-stream-instruction">nest</a></span></dt><dt><span class="section"><a href="protocol-reference.html#pipe-instruction">pipe</a></span></dt><dt><span class="section"><a href="protocol-reference.html#video-stream-instruction">video</a></span></dt></dl></dd><dt><span class="section"><a href="protocol-reference.html#object-instructions">Object instructions</a></span></dt><dd><dl><dt><span class="section"><a href="protocol-reference.html#body-object-instruction">body</a></span></dt><dt><span class="section"><a href="protocol-reference.html#filesystem-object-instruction">filesystem</a></span></dt><dt><span class="section"><a href="protocol-reference.html#get-object-instruction">get</a></span></dt><dt><span class="section"><a href="protocol-reference.html#put-object-instruction">put</a></span></dt><dt><span class="section"><a href="protocol-reference.html#undefine-object-instruction">undefine</a></span></dt></dl></dd><dt><span class="section"><a href="protocol-reference.html#client-handshake-instructions">Client handshake instructions</a></span></dt><dd><dl><dt><span class="section"><a href="protocol-reference.html#audio-handshake-instruction">audio</a></span></dt><dt><span class="section"><a href="protocol-reference.html#connect-instruction">connect</a></span></dt><dt><span class="section"><a href="protocol-reference.html#image-handshake-instruction">image</a></span></dt><dt><span class="section"><a href="protocol-reference.html#select-instruction">select</a></span></dt><dt><span class="section"><a href="protocol-reference.html#size-handshake-instruction">size</a></span></dt><dt><span class="section"><a href="protocol-reference.html#video-handshake-instruction">video</a></span></dt></dl></dd><dt><span class="section"><a href="protocol-reference.html#server-handshake-instructions">Server handshake instructions</a></span></dt><dd><dl><dt><span class="section"><a href="protocol-reference.html#args-instruction">args</a></span></dt></dl></dd><dt><span class="section"><a href="protocol-reference.html#client-control-instructions">Client control instructions</a></span></dt><dd><dl><dt><span class="section"><a href="protocol-reference.html#client-disconnect-instruction">disconnect</a></span></dt><dt><span class="section"><a href="protocol-reference.html#client-nop-instruction">nop</a></span></dt><dt><span class="section"><a href="protocol-reference.html#client-sync-instruction">sync</a></span></dt></dl></dd><dt><span class="section"><a href="protocol-reference.html#server-control-instructions">Server control instructions</a></span></dt><dd><dl><dt><span class="section"><a href="protocol-reference.html#server-disconnect-instruction">disconnect</a></span></dt><dt><span class="section"><a href="protocol-reference.html#error-instruction">error</a></span></dt><dt><span class="section"><a href="protocol-reference.html#log-instruction">log</a></span></dt><dt><span class="section"><a href="protocol-reference.html#server-mouse-instruction">mouse</a></span></dt><dt><span class="section"><a href="protocol-reference.html#server-nop-instruction">nop</a></span></dt><dt><span class="section"><a href="protocol-reference.html#ready-instruction">ready</a></span></dt><dt><span class="section"><a href="protocol-reference.html#server-sync-instruction">sync</a></span></dt></dl></dd><dt><span class="section"><a href="protocol-reference.html#client-events">Client events</a></span></dt><dd><dl><dt><span class="section"><a href="protocol-reference.html#key-instruction">key</a></span></dt><dt><span class="section"><a href="protocol-reference.html#client-mouse-instruction">mouse</a></span></dt><dt><span class="section"><a href="protocol-reference.html#size-event-instruction">size</a></span></dt></dl></dd></dl></div><a id="idm140500638413728" class="indexterm"></a><a id="idm140500638412960" class="indexterm"></a><a id="idm140500638412192" class="indexterm"></a><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="drawing-instructions"></a>Drawing instructions</h2></div></div></div><a id="idm140500638410256" class="indexterm"></a><a id="idm140500638409360" class="indexterm"></a><a id="idm140500638408016" class="indexterm"></a><div xml:lang="en" class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="arc-instruction"></a>arc</h3></div></div></div><a id="idm140500638404688" class="indexterm"></a><p>The arc instruction adds the specified arc subpath to the existing
        path, creating a new path if no path exists. The path created can be
        modified further by other path-type instructions, and finally stroked,
        filled, and/or closed.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>layer</code></em></span></dt><dd><p>The layer which should have the specified arc subpath
                    added.</p></dd><dt><span class="term"><em class="parameter"><code>x</code></em></span></dt><dd><p>The X coordinate of the center of the circle containing
                    the arc to be drawn.</p></dd><dt><span class="term"><em class="parameter"><code>y</code></em></span></dt><dd><p>The Y coordinate of the center of the circle containing
                    the arc to be drawn.</p></dd><dt><span class="term"><em class="parameter"><code>radius</code></em></span></dt><dd><p>The radius of the circle containing the arc to be drawn,
                    in pixels.</p></dd><dt><span class="term"><em class="parameter"><code>start</code></em></span></dt><dd><p>The starting angle of the arc to be drawn, in
                    radians.</p></dd><dt><span class="term"><em class="parameter"><code>end</code></em></span></dt><dd><p>The ending angle of the arc to be drawn, in
                    radians.</p></dd><dt><span class="term"><em class="parameter"><code>negative</code></em></span></dt><dd><p>Non-zero if the arc should be drawn from START to END in
                    order of decreasing angle, zero otherwise.</p></dd></dl></div></div><div xml:lang="en" class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="cfill-instruction"></a>cfill</h3></div></div></div><a id="idm140500638484336" class="indexterm"></a><p>Fills the current path with the specified color. This instruction
        completes the current path. Future path instructions will begin a new
        path.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>mask</code></em></span></dt><dd><p>The channel mask to apply when filling the current path in
                    the specified layer.</p></dd><dt><span class="term"><em class="parameter"><code>layer</code></em></span></dt><dd><p>The layer whose path should be filled.</p></dd><dt><span class="term"><em class="parameter"><code>r</code></em></span></dt><dd><p>The red component of the color to use to fill the current
                    path in the specified layer.</p></dd><dt><span class="term"><em class="parameter"><code>g</code></em></span></dt><dd><p>The green component of the color to use to fill the
                    current path in the specified layer.</p></dd><dt><span class="term"><em class="parameter"><code>b</code></em></span></dt><dd><p>The blue component of the color to use to fill the current
                    path in the specified layer.</p></dd><dt><span class="term"><em class="parameter"><code>a</code></em></span></dt><dd><p>The alpha component of the color to use to fill the
                    current path in the specified layer.</p></dd></dl></div></div><div xml:lang="en" class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="clip-instruction"></a>clip</h3></div></div></div><a id="idm140500638390032" class="indexterm"></a><p>Applies the current path as the clipping path. Future operations will
        only draw within the current path. Note that future clip instructions
        will also be limited by this path. To set a completely new clipping path,
        you must first reset the layer with a reset instruction. If you wish to
        only reset the clipping path, but preserve the current transform matrix,
        push the layer state before setting the clipping path, and pop the layer
        state to reset.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>layer</code></em></span></dt><dd><p>The layer whose clipping path should be set.</p></dd></dl></div></div><div xml:lang="en" class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="close-instruction"></a>close</h3></div></div></div><a id="idm140500638383968" class="indexterm"></a><p>Closes the current path by connecting the start and end points with a
        straight line.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>layer</code></em></span></dt><dd><p>The layer whose path should be closed.</p></dd></dl></div></div><div xml:lang="en" class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="copy-instruction"></a>copy</h3></div></div></div><a id="idm140500638377744" class="indexterm"></a><p>Copies image data from the specified rectangle of the specified layer
        or buffer to a different location of another specified layer or
        buffer.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>srclayer</code></em></span></dt><dd><p>The index of the layer to copy image data from.</p></dd><dt><span class="term"><em class="parameter"><code>srcx</code></em></span></dt><dd><p>The X coordinate of the upper-left corner of the source
                    rectangle within the source layer.</p></dd><dt><span class="term"><em class="parameter"><code>srcy</code></em></span></dt><dd><p>The Y coordinate of the upper-left corner of the source
                    rectangle within the source layer.</p></dd><dt><span class="term"><em class="parameter"><code>srcwidth</code></em></span></dt><dd><p>The width of the source rectangle within the source
                    layer.</p></dd><dt><span class="term"><em class="parameter"><code>srcheight</code></em></span></dt><dd><p>The height of the source rectangle within the source
                    layer.</p></dd><dt><span class="term"><em class="parameter"><code>mask</code></em></span></dt><dd><p>The channel mask to apply when drawing the image data on
                    the destination layer.</p></dd><dt><span class="term"><em class="parameter"><code>dstlayer</code></em></span></dt><dd><p>The index of the layer to draw the image data to.</p></dd><dt><span class="term"><em class="parameter"><code>dstx</code></em></span></dt><dd><p>The X coordinate of the upper-left corner of the
                    destination within the destination layer.</p></dd><dt><span class="term"><em class="parameter"><code>dsty</code></em></span></dt><dd><p>The Y coordinate of the upper-left corner of the
                    destination within the destination layer.</p></dd></dl></div></div><div xml:lang="en" class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="cstroke-instruction"></a>cstroke</h3></div></div></div><a id="idm140500638355776" class="indexterm"></a><p>Strokes the current path with the specified color. This instruction
        completes the current path. Future path instructions will begin a new
        path.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>mask</code></em></span></dt><dd><p>The channel mask to apply when stroking the current path
                    in the specified layer.</p></dd><dt><span class="term"><em class="parameter"><code>layer</code></em></span></dt><dd><p>The layer whose path should be stroked.</p></dd><dt><span class="term"><em class="parameter"><code>cap</code></em></span></dt><dd><p>The index of the line cap style to use. This can be either
                    butt (0), round (1), or square (2).</p></dd><dt><span class="term"><em class="parameter"><code>join</code></em></span></dt><dd><p>The index of the line join style to use. This can be
                    either bevel (0), miter (1), or round (2).</p></dd><dt><span class="term"><em class="parameter"><code>thickness</code></em></span></dt><dd><p>The thickness of the stroke to draw, in pixels.</p></dd><dt><span class="term"><em class="parameter"><code>r</code></em></span></dt><dd><p>The red component of the color to use to stroke the
                    current path in the specified layer.</p></dd><dt><span class="term"><em class="parameter"><code>g</code></em></span></dt><dd><p>The green component of the color to use to stroke the
                    current path in the specified layer.</p></dd><dt><span class="term"><em class="parameter"><code>b</code></em></span></dt><dd><p>The blue component of the color to use to stroke the
                    current path in the specified layer.</p></dd><dt><span class="term"><em class="parameter"><code>a</code></em></span></dt><dd><p>The alpha component of the color to use to stroke the
                    current path in the specified layer.</p></dd></dl></div></div><div xml:lang="en" class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="cursor-instruction"></a>cursor</h3></div></div></div><p>Sets the client's cursor to the image data from the specified
        rectangle of a layer, with the specified hotspot.</p><a id="idm140500638332960" class="indexterm"></a><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>x</code></em></span></dt><dd><p>The X coordinate of the cursor's hotspot.</p></dd><dt><span class="term"><em class="parameter"><code>y</code></em></span></dt><dd><p>The Y coordinate of the cursor's hotspot.</p></dd><dt><span class="term"><em class="parameter"><code>srclayer</code></em></span></dt><dd><p>The index of the layer to copy image data from.</p></dd><dt><span class="term"><em class="parameter"><code>srcx</code></em></span></dt><dd><p>The X coordinate of the upper-left corner of the source
                    rectangle within the source layer.</p></dd><dt><span class="term"><em class="parameter"><code>srcy</code></em></span></dt><dd><p>The Y coordinate of the upper-left corner of the source
                    rectangle within the source layer.</p></dd><dt><span class="term"><em class="parameter"><code>srcwidth</code></em></span></dt><dd><p>The width of the source rectangle within the source
                    layer.</p></dd><dt><span class="term"><em class="parameter"><code>srcheight</code></em></span></dt><dd><p>The height of the source rectangle within the source
                    layer.</p></dd></dl></div></div><div xml:lang="en" class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="curve-instruction"></a>curve</h3></div></div></div><a id="idm140500638320912" class="indexterm"></a><p>Adds the specified cubic bezier curve subpath.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>layer</code></em></span></dt><dd><p>The layer which should have the specified curve subpath
                    added.</p></dd><dt><span class="term"><em class="parameter"><code>cp1x</code></em></span></dt><dd><p>The X coordinate of the first control point of the
                    curve.</p></dd><dt><span class="term"><em class="parameter"><code>cp1y</code></em></span></dt><dd><p>The Y coordinate of the first control point of the
                    curve.</p></dd><dt><span class="term"><em class="parameter"><code>cp2x</code></em></span></dt><dd><p>The X coordinate of the second control point of the
                    curve.</p></dd><dt><span class="term"><em class="parameter"><code>cp2y</code></em></span></dt><dd><p>The Y coordinate of the second control point of the
                    curve.</p></dd><dt><span class="term"><em class="parameter"><code>x</code></em></span></dt><dd><p>The X coordinate of the endpoint of the curve.</p></dd><dt><span class="term"><em class="parameter"><code>y</code></em></span></dt><dd><p>The Y coordinate of the endpoint of the curve.</p></dd></dl></div></div><div xml:lang="en" class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="dispose-instruction"></a>dispose</h3></div></div></div><a id="idm140500638303488" class="indexterm"></a><p>Removes the specified layer. The specified layer will be recreated as a
        new layer if it is referenced again.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>layer</code></em></span></dt><dd><p>The layer to remove.</p></dd></dl></div></div><div xml:lang="en" class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="distort-instruction"></a>distort</h3></div></div></div><a id="idm140500638297008" class="indexterm"></a><p>Sets the given affine transformation matrix to the layer. Unlike
        transform, this operation is independent of any previously sent
        transformation matrix. This operation can be undone by setting the
        layer's transformation matrix to the identity matrix using
        distort</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>layer</code></em></span></dt><dd><p>The layer to distort.</p></dd><dt><span class="term"><em class="parameter"><code>a</code></em></span></dt><dd><p>The matrix value in row 1, column 1.</p></dd><dt><span class="term"><em class="parameter"><code>b</code></em></span></dt><dd><p>The matrix value in row 2, column 1.</p></dd><dt><span class="term"><em class="parameter"><code>c</code></em></span></dt><dd><p>The matrix value in row 1, column 2.</p></dd><dt><span class="term"><em class="parameter"><code>d</code></em></span></dt><dd><p>The matrix value in row 2, column 2.</p></dd><dt><span class="term"><em class="parameter"><code>e</code></em></span></dt><dd><p>The matrix value in row 1, column 3.</p></dd><dt><span class="term"><em class="parameter"><code>f</code></em></span></dt><dd><p>The matrix value in row 2, column 3.</p></dd></dl></div></div><div xml:lang="en" class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="identity-instruction"></a>identity</h3></div></div></div><a id="idm140500638279088" class="indexterm"></a><p>Resets the transform matrix of the specified layer to the identity
        matrix.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>layer</code></em></span></dt><dd><p>The layer whose transform matrix should be reset.</p></dd></dl></div></div><div xml:lang="en" class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="lfill-instruction"></a>lfill</h3></div></div></div><a id="idm140500638272608" class="indexterm"></a><p>Fills the current path with a tiled pattern of the image data from the
        specified layer. This instruction completes the current path. Future
        path instructions will begin a new path.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>mask</code></em></span></dt><dd><p>The channel mask to apply when filling the current path in
                    the specified layer.</p></dd><dt><span class="term"><em class="parameter"><code>layer</code></em></span></dt><dd><p>The layer whose path should be filled.</p></dd><dt><span class="term"><em class="parameter"><code>srclayer</code></em></span></dt><dd><p>The layer to use as the pattern.</p></dd></dl></div></div><div xml:lang="en" class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="line-instruction"></a>line</h3></div></div></div><a id="idm140500638262304" class="indexterm"></a><p>Adds the specified line subpath.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>layer</code></em></span></dt><dd><p>The layer which should have the specified line subpath
                    added.</p></dd><dt><span class="term"><em class="parameter"><code>x</code></em></span></dt><dd><p>The X coordinate of the endpoint of the line.</p></dd><dt><span class="term"><em class="parameter"><code>y</code></em></span></dt><dd><p>The Y coordinate of the endpoint of the line.</p></dd></dl></div></div><div xml:lang="en" class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="lstroke-instruction"></a>lstroke</h3></div></div></div><a id="idm140500638252000" class="indexterm"></a><p>Strokes the current path with a tiled pattern of the image data from
        the specified layer. This instruction completes the current path. Future
        path instructions will begin a new path.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>mask</code></em></span></dt><dd><p>The channel mask to apply when filling the current path in
                    the specified layer.</p></dd><dt><span class="term"><em class="parameter"><code>layer</code></em></span></dt><dd><p>The layer whose path should be filled.</p></dd><dt><span class="term"><em class="parameter"><code>cap</code></em></span></dt><dd><p>The index of the line cap style to use. This can be either
                    butt (0), round (1), or square (2).</p></dd><dt><span class="term"><em class="parameter"><code>join</code></em></span></dt><dd><p>The index of the line join style to use. This can be
                    either bevel (0), miter (1), or round (2).</p></dd><dt><span class="term"><em class="parameter"><code>thickness</code></em></span></dt><dd><p>The thickness of the stroke to draw, in pixels.</p></dd><dt><span class="term"><em class="parameter"><code>srclayer</code></em></span></dt><dd><p>The layer to use as the pattern.</p></dd></dl></div></div><div xml:lang="en" class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="move-instruction"></a>move</h3></div></div></div><a id="idm140500638235776" class="indexterm"></a><p>Moves the given layer to the given location within the specified parent
        layer. This operation is applicable only to layers, and cannot be
        applied to buffers (layers with negative indices). Applying this
        operation to the default layer (layer 0) also has no effect.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>layer</code></em></span></dt><dd><p>The layer to move.</p></dd><dt><span class="term"><em class="parameter"><code>parent</code></em></span></dt><dd><p>The layer that should be the parent of the given
                    layer.</p></dd><dt><span class="term"><em class="parameter"><code>x</code></em></span></dt><dd><p>The X coordinate to move the layer to.</p></dd><dt><span class="term"><em class="parameter"><code>y</code></em></span></dt><dd><p>The Y coordinate to move the layer to.</p></dd><dt><span class="term"><em class="parameter"><code>z</code></em></span></dt><dd><p>The relative Z-ordering of this layer. Layers with larger
                    values will appear above layers with smaller values.</p></dd></dl></div></div><div xml:lang="en" class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="pop-instruction"></a>pop</h3></div></div></div><a id="idm140500638221376" class="indexterm"></a><p>Restores the previous state of the specified layer from the stack. The
        state restored includes the transformation matrix and clipping
        path.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>layer</code></em></span></dt><dd><p>The layer whose state should be restored.</p></dd></dl></div></div><div xml:lang="en" class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="push-instruction"></a>push</h3></div></div></div><a id="idm140500638214816" class="indexterm"></a><p>Saves the current state of the specified layer to the stack. The state
        saved includes the current transformation matrix and clipping
        path.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>layer</code></em></span></dt><dd><p>The layer whose state should be saved.</p></dd></dl></div></div><div xml:lang="en" class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="rect-instruction"></a>rect</h3></div></div></div><a id="idm140500638208272" class="indexterm"></a><p>Adds a rectangular path to the specified layer.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>mask</code></em></span></dt><dd><p>The channel mask to apply when drawing the image
                    data.</p></dd><dt><span class="term"><em class="parameter"><code>layer</code></em></span></dt><dd><p>The destination layer.</p></dd><dt><span class="term"><em class="parameter"><code>x</code></em></span></dt><dd><p>The X coordinate of the upper-left corner of the rectangle
                    to draw.</p></dd><dt><span class="term"><em class="parameter"><code>y</code></em></span></dt><dd><p>The Y coordinate of the upper-left corner of the rectangle
                    to draw.</p></dd><dt><span class="term"><em class="parameter"><code>width</code></em></span></dt><dd><p>The width of the rectangle to draw.</p></dd><dt><span class="term"><em class="parameter"><code>height</code></em></span></dt><dd><p>The width of the rectangle to draw.</p></dd></dl></div></div><div xml:lang="en" class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="reset-instruction"></a>reset</h3></div></div></div><a id="idm140500638192096" class="indexterm"></a><p>Resets the transformation and clip state of the layer.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>layer</code></em></span></dt><dd><p>The layer whose state should be reset.</p></dd></dl></div></div><div xml:lang="en" class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="set-instruction"></a>set</h3></div></div></div><a id="idm140500638185664" class="indexterm"></a><p>Sets the given client-side property to the specified value. Currently
        there is only one property: miter-limit, the maximum distance between
        the inner and outer points of a miter joint, proportional to stroke
        width (if miter-limit is set to 10.0, the default, then the maximum
        distance between the points of the joint is 10 times the stroke
        width).</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>layer</code></em></span></dt><dd><p>The layer whose property should be set.</p></dd><dt><span class="term"><em class="parameter"><code>property</code></em></span></dt><dd><p>The name of the property to set.</p></dd><dt><span class="term"><em class="parameter"><code>value</code></em></span></dt><dd><p>The value to set the given property to.</p></dd></dl></div></div><div xml:lang="en" class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="shade-instruction"></a>shade</h3></div></div></div><a id="idm140500638175424" class="indexterm"></a><p>Sets the opacity of the given layer.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>layer</code></em></span></dt><dd><p>The layer whose opacity should be set.</p></dd><dt><span class="term"><em class="parameter"><code>opacity</code></em></span></dt><dd><p>The opacity of the layer, where 0 is completely
                    transparent, and 255 is completely opaque.</p></dd></dl></div></div><div xml:lang="en" class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="size-instruction"></a>size</h3></div></div></div><a id="idm140500638166992" class="indexterm"></a><p>Sets the size of the specified layer.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>layer</code></em></span></dt><dd><p>The layer to resize.</p></dd><dt><span class="term"><em class="parameter"><code>width</code></em></span></dt><dd><p>The new width of the layer</p></dd><dt><span class="term"><em class="parameter"><code>height</code></em></span></dt><dd><p>The new height of the layer</p></dd></dl></div></div><div xml:lang="en" class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="start-instruction"></a>start</h3></div></div></div><a id="idm140500638156784" class="indexterm"></a><p>Starts a new subpath at the specified point.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>layer</code></em></span></dt><dd><p>The layer which should start a new subpath.</p></dd><dt><span class="term"><em class="parameter"><code>x</code></em></span></dt><dd><p>The X coordinate of the first point of the new
                    subpath.</p></dd><dt><span class="term"><em class="parameter"><code>y</code></em></span></dt><dd><p>The Y coordinate of the first point of the new
                    subpath.</p></dd></dl></div></div><div xml:lang="en" class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="transfer-instruction"></a>transfer</h3></div></div></div><a id="idm140500638146352" class="indexterm"></a><p>Transfers image data from the specified rectangle of the specified layer or buffer to a
        different location of another specified layer or buffer, using the specified transfer
        function. </p><p>For a list of available functions, see the definition of
            <code class="classname">guac_transfer_function</code> within the <a class="link" href="https://github.com/apache/guacamole-server/blob/master/src/libguac/guacamole/protocol-types.h" target="_top"><code class="filename">guacamole/protocol-types.h</code></a> header included with
        libguac.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>srclayer</code></em></span></dt><dd><p>The index of the layer to transfer image data from.</p></dd><dt><span class="term"><em class="parameter"><code>srcx</code></em></span></dt><dd><p>The X coordinate of the upper-left corner of the source
                    rectangle within the source layer.</p></dd><dt><span class="term"><em class="parameter"><code>srcy</code></em></span></dt><dd><p>The Y coordinate of the upper-left corner of the source
                    rectangle within the source layer.</p></dd><dt><span class="term"><em class="parameter"><code>srcwidth</code></em></span></dt><dd><p>The width of the source rectangle within the source
                    layer.</p></dd><dt><span class="term"><em class="parameter"><code>srcheight</code></em></span></dt><dd><p>The height of the source rectangle within the source
                    layer.</p></dd><dt><span class="term"><em class="parameter"><code>function</code></em></span></dt><dd><p>The index of the transfer function to use.</p><p>For a list of available functions, see the definition of
                        <code class="classname">guac_transfer_function</code> within the <a class="link" href="https://github.com/apache/guacamole-server/blob/master/src/libguac/guacamole/protocol-types.h" target="_top"><code class="filename">guacamole/protocol-types.h</code></a> header included
                    with libguac.</p></dd><dt><span class="term"><em class="parameter"><code>dstlayer</code></em></span></dt><dd><p>The index of the layer to draw the image data to.</p></dd><dt><span class="term"><em class="parameter"><code>dstx</code></em></span></dt><dd><p>The X coordinate of the upper-left corner of the
                    destination within the destination layer.</p></dd><dt><span class="term"><em class="parameter"><code>dsty</code></em></span></dt><dd><p>The Y coordinate of the upper-left corner of the
                    destination within the destination layer.</p></dd></dl></div></div><div xml:lang="en" class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="transform-instruction"></a>transform</h3></div></div></div><a id="idm140500638119968" class="indexterm"></a><p>Applies the specified transformation matrix to future operations.
        Unlike distort, this operation is dependent on any previously sent
        transformation matrices, and only affects future operations. This
        operation can be undone by setting the layer's transformation matrix to
        the identity matrix using identity, but image data already drawn will
        not be affected.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>layer</code></em></span></dt><dd><p>The layer to apply the given transformation matrix
                    to.</p></dd><dt><span class="term"><em class="parameter"><code>a</code></em></span></dt><dd><p>The matrix value in row 1, column 1.</p></dd><dt><span class="term"><em class="parameter"><code>b</code></em></span></dt><dd><p>The matrix value in row 2, column 1.</p></dd><dt><span class="term"><em class="parameter"><code>c</code></em></span></dt><dd><p>The matrix value in row 1, column 2.</p></dd><dt><span class="term"><em class="parameter"><code>d</code></em></span></dt><dd><p>The matrix value in row 2, column 2.</p></dd><dt><span class="term"><em class="parameter"><code>e</code></em></span></dt><dd><p>The matrix value in row 1, column 3.</p></dd><dt><span class="term"><em class="parameter"><code>f</code></em></span></dt><dd><p>The matrix value in row 2, column 3.</p></dd></dl></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="streaming-instructions"></a>Streaming instructions</h2></div></div></div><div xml:lang="en" class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="ack-instruction"></a>ack</h3></div></div></div><a id="idm140500638100608" class="indexterm"></a><p>The ack instruction acknowledges a received data blob, providing a status code and message
        indicating whether the operation associated with the blob succeeded or failed. A status code
        other than <code class="constant">SUCCESS</code> implicitly ends the stream.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>stream</code></em></span></dt><dd><p>The index of the stream the corresponding blob was received on.</p></dd><dt><span class="term"><em class="parameter"><code>message</code></em></span></dt><dd><p>A human-readable error message. This typically is not exposed within any user
                    interface, and mainly helps with debugging.</p></dd><dt><span class="term"><em class="parameter"><code>status</code></em></span></dt><dd><p>The Guacamole status code denoting success or failure.</p></dd></dl></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="status-codes"></a>Status codes</h4></div></div></div><p>Several Guacamole instructions, and various other internals of the Guacamole core, use
            a common set of numeric status codes. These codes denote success or failure of
            operations, and can be rendered by user interfaces in a human-readable
                way.</p><div class="informaltable"><table class="informaltable" border="1"><colgroup><col class="c1" /><col class="c2" /><col class="c3" /></colgroup><thead><tr><th>Code</th><th>Name</th><th>Description</th></tr></thead><tbody><tr><td>0</td><td><code class="constant">SUCCESS</code></td><td>
                                <p>The operation succeeded. No error.</p>
                            </td></tr><tr><td>256</td><td><code class="constant">UNSUPPORTED</code></td><td>
                                <p>The requested operation is unsupported.</p>
                            </td></tr><tr><td>512</td><td><code class="constant">SERVER_ERROR</code></td><td>
                                <p>An internal error occurred, and the operation could not be
                                    performed.</p>
                            </td></tr><tr><td>513</td><td><code class="constant">SERVER_BUSY</code></td><td>
                                <p>The operation could not be performed because the server is
                                    busy.</p>
                            </td></tr><tr><td>514</td><td><code class="constant">UPSTREAM_TIMEOUT</code></td><td>
                                <p>The upstream server is not responding. In most cases, the
                                    upstream server is the remote desktop server.</p>
                            </td></tr><tr><td>515</td><td><code class="constant">UPSTREAM_ERROR</code></td><td>
                                <p>The upstream server encountered an error. In most cases, the
                                    upstream server is the remote desktop server.</p>
                            </td></tr><tr><td>516</td><td><code class="constant">RESOURCE_NOT_FOUND</code></td><td>
                                <p>An associated resource, such as a file or stream, could not be
                                    found, and thus the operation failed.</p>
                            </td></tr><tr><td>517</td><td><code class="constant">RESOURCE_CONFLICT</code></td><td>
                                <p>A resource is already in use or locked, preventing the
                                    requested operation.</p>
                            </td></tr><tr><td>518</td><td><code class="constant">RESOURCE_CLOSED</code></td><td>
                                <p>The requested operation cannot continue because the associated
                                    resource has been closed.</p>
                            </td></tr><tr><td>519</td><td><code class="constant">UPSTREAM_NOT_FOUND</code></td><td>
                                <p>The upstream server does not appear to exist, or cannot be
                                    reached over the network. In most cases, the upstream server is
                                    the remote desktop server.</p>
                            </td></tr><tr><td>520</td><td><code class="constant">UPSTREAM_UNAVAILABLE</code></td><td>
                                <p>The upstream server is refusing to service connections. In
                                    most cases, the upstream server is the remote desktop
                                    server.</p>
                            </td></tr><tr><td>521</td><td><code class="constant">SESSION_CONFLICT</code></td><td>
                                <p>The session within the upstream server has ended because it
                                    conflicts with another session. In most cases, the upstream
                                    server is the remote desktop server.</p>
                            </td></tr><tr><td>522</td><td><code class="constant">SESSION_TIMEOUT</code></td><td>
                                <p>The session within the upstream server has ended because it
                                    appeared to be inactive. In most cases, the upstream server is
                                    the remote desktop server.</p>
                            </td></tr><tr><td>523</td><td><code class="constant">SESSION_CLOSED</code></td><td>
                                <p>The session within the upstream server has been forcibly
                                    closed. In most cases, the upstream server is the remote desktop
                                    server.</p>
                            </td></tr><tr><td>768</td><td><code class="constant">CLIENT_BAD_REQUEST</code></td><td>
                                <p>The parameters of the request are illegal or otherwise
                                    invalid.</p>
                            </td></tr><tr><td>769</td><td><code class="constant">CLIENT_UNAUTHORIZED</code></td><td>
                                <p>Permission was denied, because the user is not logged in. Note
                                    that the user may be logged into Guacamole, but still not logged
                                    in with respect to the remote desktop server.</p>
                            </td></tr><tr><td>771</td><td><code class="constant">CLIENT_FORBIDDEN</code></td><td>
                                <p>Permission was denied, and logging in will not solve the
                                    problem.</p>
                            </td></tr><tr><td>776</td><td><code class="constant">CLIENT_TIMEOUT</code></td><td>
                                <p>The client (usually the user of Guacamole or their browser) is
                                    taking too long to respond.</p>
                            </td></tr><tr><td>781</td><td><code class="constant">CLIENT_OVERRUN</code></td><td>
                                <p>The client has sent more data than the protocol allows.</p>
                            </td></tr><tr><td>783</td><td><code class="constant">CLIENT_BAD_TYPE</code></td><td>
                                <p>The client has sent data of an unexpected or illegal
                                    type.</p>
                            </td></tr><tr><td>797</td><td><code class="constant">CLIENT_TOO_MANY</code></td><td>
                                <p>The client is already using too many resources. Existing
                                    resources must be freed before further requests are
                                    allowed.</p>
                            </td></tr></tbody></table></div></div></div><div xml:lang="en" class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="audio-stream-instruction"></a>audio</h3></div></div></div><a id="idm140500638027472" class="indexterm"></a><p>Allocates a new stream, associating it with the given audio metadata. Audio data will
        later be sent along the stream with blob instructions. The mimetype given must be a mimetype
        previously specified by the client during the handshake procedure. Playback will begin
        immediately and will continue as long as blobs are received along the stream.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>stream</code></em></span></dt><dd><p>The index of the stream to allocate.</p></dd><dt><span class="term"><em class="parameter"><code>mimetype</code></em></span></dt><dd><p>The mimetype of the audio data being sent.</p></dd></dl></div></div><div xml:lang="en" class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="blob-instruction"></a>blob</h3></div></div></div><a id="idm140500638019152" class="indexterm"></a><p>Sends a blob of data along the given stream. This blob of data is arbitrary,
        base64-encoded data, and only has meaning to the Guacamole client or server through the
        metadata assigned to the stream when the stream was allocated.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>stream</code></em></span></dt><dd><p>The index of the stream along which the given data should be sent.</p></dd><dt><span class="term"><em class="parameter"><code>data</code></em></span></dt><dd><p>The base64-encoded data to send.</p></dd></dl></div></div><div xml:lang="en" class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="clipboard-instruction"></a>clipboard</h3></div></div></div><a id="idm140500638010624" class="indexterm"></a><p>Allocates a new stream, associating it with the given clipboard metadata. The clipboard
        data will later be sent along the stream with blob instructions. If sent by the client, this
        data will be the contents of the client-side clipboard. If sent by the server, this data
        will be the contents of the clipboard within the remote desktop.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>stream</code></em></span></dt><dd><p>The index of the stream to allocate.</p></dd><dt><span class="term"><em class="parameter"><code>mimetype</code></em></span></dt><dd><p>The mimetype of the clipboard data being sent. In most cases, this will be
                    "text/plain".</p></dd></dl></div></div><div xml:lang="en" class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="end-instruction"></a>end</h3></div></div></div><a id="idm140500638002304" class="indexterm"></a><p>The end instruction terminates an open stream, freeing any client-side or server-side
        resources. Data sent to a terminated stream will be ignored. Terminating a stream with the
        end instruction only denotes the end of the stream and does not imply an error.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>stream</code></em></span></dt><dd><p>The index of the stream the corresponding blob was received on.</p></dd></dl></div></div><div xml:lang="en" class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="file-stream-instruction"></a>file</h3></div></div></div><a id="idm140500637995984" class="indexterm"></a><p>Allocates a new stream, associating it with the given arbitrary file metadata. The
        contents of the file will later be sent along the stream with blob instructions. The full
        size of the file need not be known ahead of time.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>stream</code></em></span></dt><dd><p>The index of the stream to allocate.</p></dd><dt><span class="term"><em class="parameter"><code>mimetype</code></em></span></dt><dd><p>The mimetype of the file being sent.</p></dd><dt><span class="term"><em class="parameter"><code>filename</code></em></span></dt><dd><p>The name of the file, as it would be saved on a filesystem.</p></dd></dl></div></div><div xml:lang="en" class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="img-instruction"></a>img</h3></div></div></div><a id="idm140500637985536" class="indexterm"></a><p>Allocates a new stream, associating it with the metadata of an image update, including the
        image type, the destination layer, and destination coordinates. The contents of the image
        will later be sent along the stream with blob instructions. The full size of the image need
        not be known ahead of time.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>stream</code></em></span></dt><dd><p>The index of the stream to allocate.</p></dd><dt><span class="term"><em class="parameter"><code>mimetype</code></em></span></dt><dd><p>The mimetype of the image being sent.</p></dd><dt><span class="term"><em class="parameter"><code>mask</code></em></span></dt><dd><p>The channel mask to apply when drawing the image data.</p></dd><dt><span class="term"><em class="parameter"><code>layer</code></em></span></dt><dd><p>The destination layer.</p></dd><dt><span class="term"><em class="parameter"><code>x</code></em></span></dt><dd><p>The X coordinate of the upper-left corner of the destination within the
                    destination layer.</p></dd><dt><span class="term"><em class="parameter"><code>y</code></em></span></dt><dd><p>The Y coordinate of the upper-left corner of the destination within the
                    destination layer.</p></dd></dl></div></div><div xml:lang="en" class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="nest-stream-instruction"></a>nest</h3></div></div></div><a id="idm140500637969328" class="indexterm"></a><p>Encodes part of one or more instructions within a single instruction,
        associating that packet of data with a stream index. Future nest
        instructions with the same stream index will append their data to the
        same logical stream on the client side. Once nested data is received on
        the client side, the client immediately executes any completed
        instructions within the associated stream, in order.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>index</code></em></span></dt><dd><p>The index of the stream this data should be appended to.
                    This index is completely arbitrary, and denotes only how
                    nested data should be reassembled.</p></dd><dt><span class="term"><em class="parameter"><code>data</code></em></span></dt><dd><p>The protocol data, containing part of one or more
                    instructions.</p></dd></dl></div></div><div xml:lang="en" class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="pipe-instruction"></a>pipe</h3></div></div></div><a id="idm140500637960816" class="indexterm"></a><p>Allocates a new stream, associating it with the given arbitrary named pipe metadata. The
        contents of the pipe will later be sent along the stream with blob instructions. Pipes in
        the Guacamole protocol are unidirectional, named pipes, very similar to a UNIX FIFO or pipe.
        It is up to client-side code to handle pipe data appropriately, likely based upon the name
        of the pipe, which is arbitrary. Pipes may be opened by either the client or the
        server.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>stream</code></em></span></dt><dd><p>The index of the stream to allocate.</p></dd><dt><span class="term"><em class="parameter"><code>mimetype</code></em></span></dt><dd><p>The mimetype of the data being sent along the pipe.</p></dd><dt><span class="term"><em class="parameter"><code>name</code></em></span></dt><dd><p>The arbitrary name of the pipe, which may have special meaning to client-side
                    code.</p></dd></dl></div></div><div xml:lang="en" class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="video-stream-instruction"></a>video</h3></div></div></div><a id="idm140500637949952" class="indexterm"></a><p>Allocates a new stream, associating it with the given video metadata. Video data will
        later be sent along the stream with blob instructions. The mimetype given must be a mimetype
        previously specified by the client during the handshake procedure. Playback will begin
        immediately and will continue as long as blobs are received along the stream.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>stream</code></em></span></dt><dd><p>The index of the stream to allocate.</p></dd><dt><span class="term"><em class="parameter"><code>layer</code></em></span></dt><dd><p>The index of the layer to stream the video data into. The effect of other
                    drawing operations on this layer during playback is undefined, as the client
                    codec implementation may leverage any rendering mechanism it sees fit, including
                    hardware decoding.</p></dd><dt><span class="term"><em class="parameter"><code>mimetype</code></em></span></dt><dd><p>The mimetype of the video data being sent.</p></dd></dl></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="object-instructions"></a>Object instructions</h2></div></div></div><div xml:lang="en" class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="body-object-instruction"></a>body</h3></div></div></div><a id="idm140500637938032" class="indexterm"></a><p>Allocates a new stream, associating it with the name of a stream previously requested by a
        get instruction. The contents of the stream will be sent later with blob instructions. The
        full size of the stream need not be known ahead of time.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>object</code></em></span></dt><dd><p>The index of the object associated with this stream.</p></dd><dt><span class="term"><em class="parameter"><code>stream</code></em></span></dt><dd><p>The index of the stream to allocate.</p></dd><dt><span class="term"><em class="parameter"><code>mimetype</code></em></span></dt><dd><p>The mimetype of the data being sent.</p></dd><dt><span class="term"><em class="parameter"><code>name</code></em></span></dt><dd><p>The name of the stream associated with the object.</p></dd></dl></div></div><div xml:lang="en" class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="filesystem-object-instruction"></a>filesystem</h3></div></div></div><a id="idm140500637925456" class="indexterm"></a><p>Allocates a new object, associating it with the given arbitrary filesystem metadata. The
        contents of files and directories within the filesystem will later be sent along streams
        requested with get instructions or created with put instructions.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>object</code></em></span></dt><dd><p>The index of the object to allocate.</p></dd><dt><span class="term"><em class="parameter"><code>name</code></em></span></dt><dd><p>The name of the filesystem.</p></dd></dl></div></div><div xml:lang="en" class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="get-object-instruction"></a>get</h3></div></div></div><a id="idm140500637916928" class="indexterm"></a><p>Requests that a new stream be created, providing read access to the object stream having
        the given name. The requested stream will be created, in response, with a body
        instruction.</p><p>Stream names are arbitrary and dictated by the object from which they are requested, with
        the exception of the root stream of the object itself, which has the reserved name
            "<code class="constant">/</code>". The root stream of the object has the mimetype
            "<code class="constant">application/vnd.glyptodon.guacamole.stream-index+json</code>", and
        provides a simple JSON map of available stream names to their corresponding mimetypes. If
        the object contains a hierarchy of streams, some of these streams may also be
            "<code class="constant">application/vnd.glyptodon.guacamole.stream-index+json</code>".</p><p>For example, the ultimate content of the body stream provided in response to a get request
        for the root stream of an object containing two text streams, "A" and "B", would be the
        following:</p><div class="informalexample"><pre class="programlisting">{
    "A" : "text/plain",
    "B" : "text/plain"
}</pre></div><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>object</code></em></span></dt><dd><p>The index of the object to request a stream from.</p></dd><dt><span class="term"><em class="parameter"><code>name</code></em></span></dt><dd><p>The name of the stream being requested from the given object.</p></dd></dl></div></div><div xml:lang="en" class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="put-object-instruction"></a>put</h3></div></div></div><a id="idm140500637904752" class="indexterm"></a><p>Allocates a new stream, associating it with the given arbitrary object and stream name.
        The contents of the stream will later be sent with blob instructions.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>object</code></em></span></dt><dd><p>The index of the object associated with this stream.</p></dd><dt><span class="term"><em class="parameter"><code>stream</code></em></span></dt><dd><p>The index of the stream to allocate.</p></dd><dt><span class="term"><em class="parameter"><code>mimetype</code></em></span></dt><dd><p>The mimetype of the data being sent.</p></dd><dt><span class="term"><em class="parameter"><code>name</code></em></span></dt><dd><p>The name of the stream within the given object to which data is being
                    sent.</p></dd></dl></div></div><div xml:lang="en" class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="undefine-object-instruction"></a>undefine</h3></div></div></div><a id="idm140500637892288" class="indexterm"></a><p>Undefines an existing object, allowing its index to be reused by another future object.
        The resource associated with the original object may or may not continue to exist - it
        simply no longer has an associated object.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>object</code></em></span></dt><dd><p>The index of the object to undefine.</p></dd></dl></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="client-handshake-instructions"></a>Client handshake instructions</h2></div></div></div><div xml:lang="en" class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="audio-handshake-instruction"></a>audio</h3></div></div></div><a id="idm140500637884256" class="indexterm"></a><p>Specifies which audio mimetypes are supported by the client. Each
        parameter must be a single mimetype, listed in order of client
        preference, with the optimal mimetype being the first parameter. This is
        the third instruction sent during the handshake phase.</p></div><div xml:lang="en" class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="connect-instruction"></a>connect</h3></div></div></div><a id="idm140500637879952" class="indexterm"></a><p>Begins the connection using the previously specified protocol with the
        given arguments.  This is the last instruction sent during the handshake
        phase.</p><p>The parameters of this instruction correspond exactly to the
        parameters of the received args instruction. If the received args
        instruction has, for example, three parameters, the responding connect
        instruction must also have three parameters.</p></div><div xml:lang="en" class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="image-handshake-instruction"></a>image</h3></div></div></div><a id="idm140500637875056" class="indexterm"></a><p>Specifies which image mimetypes are supported by the client. Each parameter must be a
        single mimetype, listed in order of client preference, with the optimal mimetype being the
        first parameter. This is the fifth instruction sent during the handshake phase.</p><p>It is expected that the supported mimetypes will include at least "image/png" and
        "image/jpeg", and the server <span class="emphasis"><em>may</em></span> safely assume that these mimetypes are
        supported, even if they are absent from the handshake.</p></div><div xml:lang="en" class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="select-instruction"></a>select</h3></div></div></div><a id="idm140500637869760" class="indexterm"></a><p>Requests that the connection be made using the specified protocol, or to the specified
        existing connection. Whether a new connection is established or an existing connection is
        joined depends on whether the ID of an active connection is provided. The Guacamole protocol
        dictates that the IDs generated for active connections (provided during the handshake of
        those connections via the <a class="link" href="protocol-reference.html#ready-instruction" title="ready">ready instruction</a>) must not collide with any
        supported protocols.</p><p>This is the first instruction sent during the handshake phase.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>ID</code></em></span></dt><dd><p>The name of the protocol to use, such as "vnc" or "rdp", or the ID of the
                    active connection to be joined, as returned via the <a class="link" href="protocol-reference.html#ready-instruction" title="ready">ready
                        instruction</a>.</p></dd></dl></div></div><div xml:lang="en" class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="size-handshake-instruction"></a>size</h3></div></div></div><a id="idm140500637860944" class="indexterm"></a><p>Specifies the client's optimal screen size and resolution. This is the second instruction
        sent during the handshake phase.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>width</code></em></span></dt><dd><p>The optimal screen width.</p></dd><dt><span class="term"><em class="parameter"><code>height</code></em></span></dt><dd><p>The optimal screen height.</p></dd><dt><span class="term"><em class="parameter"><code>dpi</code></em></span></dt><dd><p>The optimal screen resolution, in approximate DPI.</p></dd></dl></div></div><div xml:lang="en" class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="video-handshake-instruction"></a>video</h3></div></div></div><a id="idm140500637850656" class="indexterm"></a><p>Specifies which video mimetypes are supported by the client. Each
        parameter must be a single mimetype, listed in order of client
        preference, with the optimal mimetype being the first parameter. This is
        the fourth instruction sent during the handshake phase.</p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="server-handshake-instructions"></a>Server handshake instructions</h2></div></div></div><div xml:lang="en" class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="args-instruction"></a>args</h3></div></div></div><p>Reports the expected format of the argument list for the protocol
        requested by the client. This message can be sent by the server during
        the handshake phase only.</p><p>The parameters of the args instruction are the names of all parameters
        accepted by the server for the protocol in selected by the client, in
        order. The client's responding connect instruction must the values of
        each of these parameters in the same order.</p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="client-control-instructions"></a>Client control instructions</h2></div></div></div><a id="idm140500637842208" class="indexterm"></a><a id="idm140500637841312" class="indexterm"></a><a id="idm140500637839968" class="indexterm"></a><div xml:lang="en" class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="client-disconnect-instruction"></a>disconnect</h3></div></div></div><a id="idm140500637836144" class="indexterm"></a><p>Notifies the server that the connection is about to be closed by the
        client. This message can be sent by the client during any phase, and
        takes no parameters.</p></div><div xml:lang="en" class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="client-nop-instruction"></a>nop</h3></div></div></div><a id="idm140500637832208" class="indexterm"></a><p>The client "nop" instruction does absolutely nothing, has no parameters, and is
        universally ignored by the Guacamole server. Its main use is as a keep-alive signal, and may
        be sent by Guacamole clients when there is no activity to ensure the socket is not closed
        due to timeout.</p></div><div xml:lang="en" class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="client-sync-instruction"></a>sync</h3></div></div></div><a id="idm140500637827904" class="indexterm"></a><p>Reports that all operations as of the given server-relative timestamp
        have been completed. If a sync is received from the server, the client
        must respond with a corresponding sync once all previous operations have
        been completed, or the server may stop sending updates until the client
        catches up. For the client, sending a sync with a timestamp newer than
        any timestamp received from the server is an error.</p><p>Both client and server are expected to occasionally send sync to
        report on current operation execution state.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>timestamp</code></em></span></dt><dd><p>A valid server-relative timestamp.</p></dd></dl></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="server-control-instructions"></a>Server control instructions</h2></div></div></div><a id="idm140500637822064" class="indexterm"></a><div xml:lang="en" class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="server-disconnect-instruction"></a>disconnect</h3></div></div></div><a id="idm140500637818240" class="indexterm"></a><p>Notifies the client that the connection is about to be closed by the server. This message
        can be sent by the server during any phase, and takes no parameters.</p></div><div xml:lang="en" class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="error-instruction"></a>error</h3></div></div></div><a id="idm140500637814128" class="indexterm"></a><p>Notifies the client that the connection is about to be closed due to
        the specified error. This message can be sent by the server during any
        phase.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>text</code></em></span></dt><dd><p>An arbitrary message describing the error</p></dd><dt><span class="term"><em class="parameter"><code>status</code></em></span></dt><dd><p>The Guacamole status code describing the error. For a list of status codes,
                    see the table in <a class="xref" href="protocol-reference.html#status-codes" title="Status codes">the section called “Status codes”</a>.</p></dd></dl></div></div><div xml:lang="en" class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="log-instruction"></a>log</h3></div></div></div><a id="idm140500637804912" class="indexterm"></a><p>The log instruction sends an arbitrary string for debugging purposes. This instruction
        will be ignored by Guacamole clients, but can be seen in protocol dumps if such dumps become
        necessary. Sending a log instruction can help add context when searching for the cause of a
        fault in protocol support.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>message</code></em></span></dt><dd><p>An arbitrary, human-readable message.</p></dd></dl></div></div><div xml:lang="en" class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="server-mouse-instruction"></a>mouse</h3></div></div></div><a id="idm140500637798176" class="indexterm"></a><p>Reports that a user on the current connection has moved the mouse to the given
        coordinates.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>x</code></em></span></dt><dd><p>The current X coordinate of the mouse pointer.</p></dd><dt><span class="term"><em class="parameter"><code>y</code></em></span></dt><dd><p>The current Y coordinate of the mouse pointer.</p></dd></dl></div></div><div xml:lang="en" class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="server-nop-instruction"></a>nop</h3></div></div></div><a id="idm140500637789728" class="indexterm"></a><p>The server "nop" instruction does absolutely nothing, has no parameters, and is
        universally ignored by Guacamole clients. Its main use is as a keep-alive signal, and may be
        sent by guacd or client plugins when there is no activity to ensure the socket is not closed
        due to timeout.</p></div><div xml:lang="en" class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="ready-instruction"></a>ready</h3></div></div></div><a id="idm140500637785424" class="indexterm"></a><p>The ready instruction sends the ID of a new connection and marks the beginning of the
        interactive phase of a new, successful connection. The ID sent is a completely arbitrary
        string, and has no standard format. It must be unique from all existing and future
        connections and may not match the name of any installed protocol support.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>ID</code></em></span></dt><dd><p>An arbitrary, unique identifier for the current connection. This identifier
                    must be unique from all existing and future connections, and may not match the
                    name of any installed protocol support (such as "vnc" or "rdp").</p></dd></dl></div></div><div xml:lang="en" class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="server-sync-instruction"></a>sync</h3></div></div></div><a id="idm140500637778464" class="indexterm"></a><p>Indicates that the given timestamp is the current timestamp as of all
        previous operations. The client must respond to every sync instruction
        received.</p><p>Both client and server are expected to occasionally send sync to
        report on current operation execution state.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>timestamp</code></em></span></dt><dd><p>A valid server-relative timestamp.</p></dd></dl></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="client-events"></a>Client events</h2></div></div></div><a id="idm140500637772432" class="indexterm"></a><a id="idm140500637771536" class="indexterm"></a><a id="idm140500637770192" class="indexterm"></a><div xml:lang="en" class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="key-instruction"></a>key</h3></div></div></div><a id="idm140500637766464" class="indexterm"></a><p>Sends the specified key press or release event.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>keysym</code></em></span></dt><dd><p>The <a class="link" href="http://www.x.org/wiki/KeySyms" target="_top">X11
                        keysym</a> of the key being pressed or
                    released.</p></dd><dt><span class="term"><em class="parameter"><code>pressed</code></em></span></dt><dd><p>0 if the key is not pressed, 1 if the key is
                    pressed.</p></dd></dl></div></div><div xml:lang="en" class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="client-mouse-instruction"></a>mouse</h3></div></div></div><a id="idm140500637757152" class="indexterm"></a><p>Sends the specified mouse movement or button press or release event (or
        combination thereof).</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>x</code></em></span></dt><dd><p>The current X coordinate of the mouse pointer.</p></dd><dt><span class="term"><em class="parameter"><code>y</code></em></span></dt><dd><p>The current Y coordinate of the mouse pointer.</p></dd><dt><span class="term"><em class="parameter"><code>mask</code></em></span></dt><dd><p>The button mask, representing the pressed or released
                    status of each mouse button.</p></dd></dl></div></div><div xml:lang="en" class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="size-event-instruction"></a>size</h3></div></div></div><a id="idm140500637746768" class="indexterm"></a><p>Specifies that the client's optimal screen size has changed from what was specified during
        the handshake, or from previously-sent "size" instructions.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>width</code></em></span></dt><dd><p>The new, optimal screen width.</p></dd><dt><span class="term"><em class="parameter"><code>height</code></em></span></dt><dd><p>The new, optimal screen height.</p></dd></dl></div></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="faq.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="appendices.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="book-index.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Appendix A. FAQ </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Index</td></tr></table></div>

            </div></div>
        <!-- Google Analytics -->
        <script type="text/javascript">
          (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
          (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
          m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
          })(window,document,'script','//www.google-analytics.com/analytics.js','ga');

          ga('create', 'UA-75289145-1', 'auto');
          ga('send', 'pageview');
        </script>
        </body></html>