| <?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-NS Stylesheets V1.78.1" /><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#disconnect-instruction">disconnect</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#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#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#mouse-instruction">mouse</a></span></dt></dl></dd></dl></div><a id="idm140538186461904" class="indexterm"></a><a id="idm140538185765840" class="indexterm"></a><a id="idm140538185765040" 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="idm140538185763216" class="indexterm"></a><a id="idm140538185762320" class="indexterm"></a><a id="idm140538185760976" 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="idm140538185757760" 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="idm140538185815120" 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="idm140538185747840" 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="idm140538185741264" 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="idm140538185735040" 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="idm140538185719056" 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="idm140538185696176" 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="idm140538185678368" 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="idm140538185660048" 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="idm140538185653568" 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="idm140538185635280" 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="idm140538185628864" 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="idm140538185618352" 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="idm140538185607984" 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="idm140538185591488" 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="idm140538185576944" 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="idm140538185570448" 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="idm140538185563904" 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="idm140538185547664" 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="idm140538185541232" 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="idm140538185530592" 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="idm140538185522160" 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="idm140538185511888" 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="idm140538185501456" 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. For a list of available |
| functions, see |
| [[http://guac-dev.org/trac/browser/libguac/include/protocol.h|guacamole/protocol.h.</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. For a list of |
| available functions, see |
| [[http://guac-dev.org/trac/browser/libguac/include/protocol.h|guacamole/protocol.h.</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="idm140538185478608" 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="idm140538185458960" 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 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>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="idm140538185399760" 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="idm140538185391056" 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="idm140538185382512" 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="idm140538185373824" 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="idm140538185367136" 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="idm140538185356608" 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="idm140538185340064" 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="idm140538185331104" 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="idm140538185320240" 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="idm140538185308064" 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="idm140538185295488" 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="idm140538185287024" 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="idm140538185274624" 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="idm140538185262224" 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="idm140538185254256" 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="idm140538185250016" 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="idm140538185245120" 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="idm140538185239760" class="indexterm"></a><p>Requests that the connection be made using the specified protocol. |
| 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>protocol</code></em></span></dt><dd><p>The protocol to use.</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="idm140538185233280" 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="idm140538185222848" 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="idm140538185214208" class="indexterm"></a><a id="idm140538185213312" class="indexterm"></a><a id="idm140538185211968" class="indexterm"></a><div xml:lang="en" class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="disconnect-instruction"></a>disconnect</h3></div></div></div><a id="idm140538185208224" 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-sync-instruction"></a>sync</h3></div></div></div><a id="idm140538185204048" 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="idm140538185197680" class="indexterm"></a><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="idm140538185194016" 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="idm140538185184800" 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="nop-instruction"></a>nop</h3></div></div></div><a id="idm140538185178160" class="indexterm"></a><p>The 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="idm140538185173856" 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="idm140538185166896" 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="idm140538185160928" class="indexterm"></a><a id="idm140538185160032" class="indexterm"></a><a id="idm140538185158688" 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="idm140538185154960" 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="mouse-instruction"></a>mouse</h3></div></div></div><a id="idm140538185145616" 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></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> |
| <!-- End Google Analytics --> |
| </body></html> |