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. Project: http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/commit/69c96d57 Tree: http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/tree/69c96d57 Diff: http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/diff/69c96d57 Branch: refs/heads/master Commit: 69c96d57edd5a94c2cae845fa54646ec5fcfe8c6 Parents: e787d05 Author: Michael Jumper <mjum...@apache.org> Authored: Mon Oct 17 18:03:22 2016 -0700 Committer: Michael Jumper <mjum...@apache.org> Committed: Mon Oct 17 18:04:04 2016 -0700 ---------------------------------------------------------------------- src/chapters/libguac.xml | 63 ------------------------------------------ src/chapters/protocol.xml | 15 ---------- 2 files changed, 78 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/blob/69c96d57/src/chapters/libguac.xml ---------------------------------------------------------------------- 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 @@ <programlisting>guac_protocol_send_size(client->socket, GUAC_DEFAULT_LAYER, 1024, 768);</programlisting> </informalexample> </section> - <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 instructions, - such that the larger instruction can be interleaved with the smaller - 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 user - 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 */ -guac_protocol_send_audio_header(nested_socket, - 0, "audio/ogg", 250, buffer_size); - -... - -/* Write data packets */ -guac_protocol_send_audio_data(nested_socket, data, sizeof(data)); - -... - -/* Finish audio instruction */ -guac_protocol_send_audio_end(nested_socket); - -/* When done, close the socket */ -guac_socket_close(nested_socket);</programlisting> - </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 http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/blob/69c96d57/src/chapters/protocol.xml ---------------------------------------------------------------------- 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 @@ </informalexample> </section> </section> - <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 "nest" - 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"> <title>Drawing</title> <section xml:id="guacamole-protocol-compositing">
