| <?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#argv-instruction">argv</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#timezone-handshake-instruction">timezone</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="idm46420843554608" class="indexterm"></a><a id="idm46420843553840" class="indexterm"></a><a id="idm46420843553072" 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="idm46420843551136" class="indexterm"></a><a id="idm46420843550240" class="indexterm"></a><a id="idm46420843548896" 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="idm46420843545568" 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="idm46420843391888" 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="idm46420843375712" 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="idm46420843369648" 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="idm46420843363424" 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="idm46420843341456" 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="idm46420843318640" 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="idm46420843301312" 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="idm46420843283440" 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="idm46420844230576" 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="idm46420843264784" 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="idm46420843258304" 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="idm46420843248000" 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="idm46420843237632" 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="idm46420843221344" 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="idm46420843206944" 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="idm46420843200384" 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="idm46420843193840" 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="idm46420843177600" 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="idm46420843171168" 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="idm46420843160928" 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="idm46420843152560" 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="idm46420843142288" 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="idm46420843131856" 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="idm46420843105472" 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="idm46420843086176" 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="argv-instruction"></a>argv</h3></div></div></div><a id="idm46420843012912" class="indexterm"></a><p>Allocates a new stream, associating it with the given argument (connection parameter) |
| metadata. The relevant connection parameter data will later be sent along the stream with |
| blob instructions. If sent by the client, this data will be the desired new value of the |
| connection parameter being changed, and will be applied if the server supports changing that |
| connection parameter while the connection is active. If sent by the server, this data will |
| be the current value of a connection parameter being exposed to the client.</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 connection parameter being sent. In most cases, this will |
| be "text/plain".</p></dd><dt><span class="term"><em class="parameter"><code>name</code></em></span></dt><dd><p>The name of the connection parameter whose value 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="audio-stream-instruction"></a>audio</h3></div></div></div><a id="idm46420843002672" 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="idm46420842994352" 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="idm46420842985824" 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="idm46420842977440" 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="idm46420842971120" 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="idm46420842960672" 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="idm46420842944464" class="indexterm"></a><div class="important"><h3 class="title">Important</h3><p><span class="emphasis"><em>The <code class="function">nest</code> instruction has been |
| deprecated.</em></span></p><p>The <code class="function">nest</code> instruction is no longer necessary, having been replaced |
| by other streaming instructions (such as <a class="link" href="protocol-reference.html#blob-instruction" title="blob"><code class="function">blob</code></a>, <a class="link" href="protocol-reference.html#ack-instruction" title="ack"><code class="function">ack</code></a>, and <a class="link" href="protocol-reference.html#end-instruction" title="end"><code class="function">end</code></a>). Code using the <code class="function">nest</code> |
| instruction should instead write instructions directly without wrapping those |
| instructions within <code class="function">nest</code>.</p></div><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="idm46420842929616" 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="idm46420842919264" 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="idm46420842907408" 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="idm46420842894832" 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="idm46420842886304" 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="idm46420842873984" 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="idm46420842861520" 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="idm46420842853488" 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.</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="idm46420842849264" 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="idm46420842844368" 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.</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="idm46420842839072" 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="idm46420842830256" class="indexterm"></a><p>Specifies the client's optimal screen size and resolution.</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="timezone-handshake-instruction"></a>timezone</h3></div></div></div><a id="idm46420842819888" class="indexterm"></a><p>Specifies the timezone of the client system, in IANA zone key format. |
| This is a single-value parameter, and may be used by protocols to |
| set the timezone on the remote computer, if the remote system allows |
| the timezone to be configured. This instruction is optional.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>timezone</code></em></span></dt><dd></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="idm46420842813152" 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.</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 first parameter of this instruction will be the protocol version |
| supported by the server. This is used to negotiate protocol |
| compatibility between the client and the server, with the highest |
| supported protocol by both sides being chosen. Versions of Guacamole |
| prior to 1.1.0 do not support protocol version negotiation, and will |
| silently ignore this instruction.</p><p>The remaining parameters of the args instruction are the names of all |
| connection parameters accepted by the server for the protocol selected |
| by the client, in order. The client's responding connect instruction |
| must contain 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="idm46420842804032" class="indexterm"></a><a id="idm46420842803136" class="indexterm"></a><a id="idm46420842801792" 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="idm46420842797968" 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="idm46420842794032" 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="idm46420842789728" 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="idm46420842783888" 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="idm46420842780064" 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="idm46420842776016" 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="idm46420842766736" 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="idm46420842760000" 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="idm46420842751552" 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="idm46420842747248" 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="idm46420842740288" 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="idm46420842734320" class="indexterm"></a><a id="idm46420842733424" class="indexterm"></a><a id="idm46420842732080" 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="idm46420842728352" 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="idm46420842718976" 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="idm46420842708528" 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> |
| </body></html> |
