GUACAMOLE-88: Describe libguac support for streams.


Branch: refs/heads/master
Commit: 1dcac2fb61ff918e3c7b53b3d9d60315c55b95fd
Parents: ea562cf
Author: Michael Jumper <>
Authored: Mon Oct 17 19:40:32 2016 -0700
Committer: Michael Jumper <>
Committed: Mon Oct 17 19:40:32 2016 -0700

 src/chapters/libguac.xml | 66 ++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 65 insertions(+), 1 deletion(-)
diff --git a/src/chapters/libguac.xml b/src/chapters/libguac.xml
index d4f876b..ddaa448 100644
--- a/src/chapters/libguac.xml
+++ b/src/chapters/libguac.xml
@@ -215,6 +215,43 @@ client->free_handler = free_handler;</programlisting>
             somehow, this is the layer you want to use as the operand of your
             drawing instruction.</para>
+    <section xml:id="libguac-streams">
+        <title>Streams</title>
+        <para>In addition to drawing, the Guacamole protocol supports 
streaming of arbitrary data.
+            The main operand of all streaming instructions is the stream, 
represented within libguac
+            by the <classname>guac_stream</classname> structure. Each
+                <classname>guac_stream</classname> exists either at the user 
or client levels,
+            depending on whether the stream is intended to be broadcast to all 
users or just one,
+            and is thus allocated using either 
+            or <methodname>guac_user_alloc_stream()</methodname>. 
Explicitly-allocated streams must
+            eventually be freed with 
<methodname>guac_client_free_stream()</methodname> or
+                <methodname>guac_user_free_stream()</methodname>.</para>
+        <important>
+            <para>Just as with layers, care must be taken to invoke the 
allocate and free pairs
+                correctly for each explicitly-allocated stream.
+                    <methodname>guac_client_free_stream()</methodname> should 
only be used to free
+                streams allocated with 
<methodname>guac_client_alloc_stream()</methodname>, and
+                    <methodname>guac_user_free_stream()</methodname> should 
only be used to free
+                streams allocated with 
+            <para>If these restrictions are not observed, the effect of 
invoking these functions is
+                undefined.</para>
+        </important>
+        <para>Streams are the means by which data is transmitted for clipboard 
(via the <link
+                xmlns:xlink=""; 
+                >"clipboard" instruction</link>), audio (via the <link
+                xmlns:xlink=""; 
+                >"audio" instruction</link>), and even the images which make 
up typical drawing
+            operations (via the <link 
+                linkend="img-instruction">"img" instruction</link>). They will 
either be allocated
+            for you, when an inbound stream is received from a user, or 
allocated manually, when an
+            outbound stream needs to be sent to a user. As with 
+            and <classname>guac_user</classname>, each 
<classname>guac_stream</classname> has a set
+            of handlers which correspond to instructions received related to 
streams. These
+            instructions are documented in more detail in <xref
+                xmlns:xlink=""; 
+            and <xref xmlns:xlink=""; 
+            />.</para>
+    </section>
     <section xml:id="libguac-sending-instructions">
         <title>Sending instructions</title>
         <para>All drawing in Guacamole is accomplished through the sending of 
instructions to the
@@ -344,7 +381,7 @@ user->mouse_handler = mouse_handler;</programlisting>
         <section xml:id="libguac-clipboard-events">
-            <title>Clipboard events</title>
+            <title>Clipboard, file, and other stream events</title>
             <para>If a connected user sends data which should be sent to the 
clipboard of the remote
                 desktop, guacd will trigger the clipboard handler installed in 
                     <property>clipboard_handler</property> member of the
@@ -359,6 +396,33 @@ user->mouse_handler = mouse_handler;</programlisting>
 /* Within the "join" handler of guac_client */
 user->clipboard_handler = clipboard_handler;</programlisting>
+            <para>The handler is expected to assign further handlers to the 
+                    <classname>guac_stream</classname> as necessary, such that 
the <link
+                    xmlns:xlink=""; 
+                    >"blob"</link> and <link 
+                    linkend="end-instruction">"end"</link> instructions 
received along the stream
+                can be handled. A similar handler is provided for received 
+            <informalexample>
+                <programlisting>int file_handler(guac_user* user, guac_stream* 
+        char* mimetype, char* filename) {
+    /* Do something */
+/* Within the "join" handler of guac_client */
+user->file_handler = file_handler;</programlisting>
+            </informalexample>
+            <para>This pattern continues for all other types of streams which 
can be received from a
+                user. The instruction which begins the stream has a 
corresponding handler within
+                    <classname>guac_user</classname>, and the metadata 
describing that stream and
+                provided with the instruction is included within the 
parameters passed to that
+                handler.</para>
+            <para>These handlers are, of course, optional. If any type of 
stream lacks a
+                corresponding handler, guacd will automatically close the 
stream and respond with an
+                    <link xmlns:xlink=""; 
+                    instruction</link> and appropriate error code, informing 
the user's Guacamole
+                client that the stream is unsupported.</para>

Reply via email to