Repository: incubator-guacamole-manual
Updated Branches:
  refs/heads/master b5ecd9985 -> 3310df421

GUACAMOLE-88: Remove legacy description of protocol nesting. It's no longer 
correct, and that feature is really no longer needed.


Branch: refs/heads/master
Commit: 69c96d57edd5a94c2cae845fa54646ec5fcfe8c6
Parents: e787d05
Author: Michael Jumper <>
Authored: Mon Oct 17 18:03:22 2016 -0700
Committer: Michael Jumper <>
Committed: Mon Oct 17 18:04:04 2016 -0700

 src/chapters/libguac.xml  | 63 ------------------------------------------
 src/chapters/protocol.xml | 15 ----------
 2 files changed, 78 deletions(-)
diff --git a/src/chapters/libguac.xml b/src/chapters/libguac.xml
index 8f0b420..048ab86 100644
--- a/src/chapters/libguac.xml
+++ b/src/chapters/libguac.xml
@@ -164,69 +164,6 @@
GUAC_DEFAULT_LAYER, 1024, 768);</programlisting>
-    <section xml:id="libguac-protocol-nesting">
-        <title>Protocol nesting</title>
-        <para>When large instructions need to be sent, particularly those
-            associated with audio or video, it is best to send those
-            instructions broken into individual packets using nest 
-            such that the larger instruction can be interleaved with the 
-            instructions such that normal responsiveness is not lessened. As
-            future instructions cannot be parsed until the earlier instructions
-            finish parsing, avoiding large instructions is important if the 
-            is expected to interact with their display in real-time.</para>
-        <para>libguac provides rudimentary means of automatically nesting
-            instructions using the <methodname>guac_socket_nest()</methodname>
-            function. This function returns a new
-                <classname>guac_socket</classname> which writes data to nest
-            instructions to its parent <classname>guac_socket</classname>,
-            rather than to the client's stream directly. By using this and the
-            piecemeal versions of the instruction-sending functions required,
-            audio or video data can be stretched over multiple instructions
-            rather than one single instruction:</para>
-        <informalexample>
-            <programlisting>/* Get nested socket */
-guac_socket* nested_socket = guac_socket_nest(client->socket, 0);
-/* Write audio header */
-    0, "audio/ogg", 250, buffer_size);
-/* Write data packets */
-guac_protocol_send_audio_data(nested_socket, data, sizeof(data));
-/* Finish audio instruction */
-/* When done, close the socket */
-        </informalexample>
-        <para>Providing that calls to guac_protocol_send_audio_data() (or the
-            similar video functions) are made interleaved with calls to smaller
-            instructions, those smaller instructions will not be blocked by the
-            size of the audio data that must be sent.</para>
-        <important>
-            <para>Because of the nature of the Guacamole protocol, the size and
-                duration of audio or video data must be known beforehand. If
-                audio or video data must be streamed in real-time, it will need
-                to be divided into individual self-contained chunks. Smaller
-                chunks have a greater chance of causing noticeable gaps due to
-                network hiccups, but are more responsive and will seem more
-                in-line with what is happening from the user's perspective,
-                while larger chunks will be less vulnerable to network issues,
-                but obviously will require the client to wait for a longer time
-                before the audio or video actually starts playing.</para>
-            <para>Note that the size of each audio or video packet is not
-                related to the size of each nest instruction. Choosing larger
-                audio or video packets does not mean that the nest instruction
-                cannot be used; in fact, this is the purpose of the nest
-                instruction: to allow larger instructions to be broken up into
-                smaller instructions.</para>
-        </important>
-    </section>
     <section xml:id="libguac-event-handling">
         <title>Event handling</title>
         <para>Generally, as guacd receives instructions from the connected
diff --git a/src/chapters/protocol.xml b/src/chapters/protocol.xml
index ba4aced..450c529 100644
--- a/src/chapters/protocol.xml
+++ b/src/chapters/protocol.xml
@@ -106,21 +106,6 @@
-    <section xml:id="guacamole-protocol-nesting">
-        <title>Nesting and interleaving</title>
-        <para>The Guacamole protocol can be nested within itself, such that 
long instructions or
-            independent streams of multiple instructions need not block each 
other; they can be
-            multiplexed into the same stream. Nesting is accomplished with the 
-            instruction.</para>
-        <para>A nest instruction has only two parameters: an arbitrary integer 
index denoting what
-            stream the data is associated with, and the instruction data 
itself. The integer index
-            is important as it defines how the instruction will be 
reassembled. The data from nest
-            instructions with the same stream index is reassembled by the 
client in the order
-            received, and instructions within that data are executed 
immediately once
-            completed.</para>
-        <para>This is particularly important when data needs to be trickled to 
the client rather
-            than as a single atomic instruction.</para>
-    </section>
     <section xml:id="guacamole-protocol-drawing">
         <section xml:id="guacamole-protocol-compositing">

Reply via email to