You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@guacamole.apache.org by jm...@apache.org on 2016/10/18 03:06:12 UTC
[1/7] incubator-guacamole-manual git commit: GUACAMOLE-88: Remove
legacy description of protocol nesting. It's no longer correct,
and that feature is really no longer needed.
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 <mj...@apache.org>
Authored: Mon Oct 17 18:03:22 2016 -0700
Committer: Michael Jumper <mj...@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">
[5/7] incubator-guacamole-manual git commit: GUACAMOLE-88: Document
new plugin lifecycle.
Posted by jm...@apache.org.
GUACAMOLE-88: Document new plugin lifecycle.
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/ea562cf6
Tree: http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/tree/ea562cf6
Diff: http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/diff/ea562cf6
Branch: refs/heads/master
Commit: ea562cf6269ebb7f14ec2c97a15763fc909eaf34
Parents: 5ab54f0
Author: Michael Jumper <mj...@apache.org>
Authored: Mon Oct 17 19:12:55 2016 -0700
Committer: Michael Jumper <mj...@apache.org>
Committed: Mon Oct 17 19:15:26 2016 -0700
----------------------------------------------------------------------
src/chapters/libguac.xml | 175 +++++++++++++++++++++++++++++++-----------
1 file changed, 129 insertions(+), 46 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/blob/ea562cf6/src/chapters/libguac.xml
----------------------------------------------------------------------
diff --git a/src/chapters/libguac.xml b/src/chapters/libguac.xml
index 1d32993..d4f876b 100644
--- a/src/chapters/libguac.xml
+++ b/src/chapters/libguac.xml
@@ -45,52 +45,135 @@
</section>
<section xml:id="libguac-client-plugins">
<title>Client plugins</title>
- <para>Client plugins are libraries loaded dynamically using the
- functions of libdl. Each client plugin is required to follow a
- naming convention, where the name of the library is
- <package>libguac-client-<replaceable>PROTOCOL</replaceable></package>.
- Failing to do this means that guacd will be unable to find the
- library when the client plugin needs to be loaded.</para>
- <para>To load a client plugin, guacd calls the guac_client_plugin_open()
- function with the name of the protocol corresponding to the plugin
- to be loaded. Upon success,
- <methodname>guac_client_plugin_open()</methodname> returns a
- handle to the library containing the client plugin within an
- instance of <classname>guac_client_plugin</classname>. This instance
- will eventually be cleaned up by
- <methodname>guac_client_plugin_close()</methodname> when guacd
- is finished using it. While these functions are intended to be used
- by guacd, there is no reason they cannot be used in another proxy
- implementation, even if that proxy implementation resides within
- another client plugin.</para>
- <para>Once the client plugin is successfully loaded, guacd makes a call
- to <methodname>guac_client_plugin_init_client()</methodname> to
- initialize the client. This function calls the
- <methodname>guac_client_init()</methodname> function within the
- client plugin which absolutely all client plugins must define. This
- function is the entry point of all client plugins, similar to the
- <methodname>main()</methodname> function of a C program.</para>
- <para>As guacd handles the handshake procedure required by the Guacamole
- protocol, it reads a statically-allocated,
- <constant>NULL</constant>-terminated set of argument names declared
- within the client plugin: <varname>GUAC_CLIENT_ARGS</varname>. As
- with <methodname>guac_client_init()</methodname>, all client plugins
- must define this variable if they are to work. As the handshake
- procedure is completed, guacd will initialize and populate a
- <classname>guac_client</classname> structure, including the
- <classname>guac_client_info</classname> structure contained
- within it, and pass it to
- <methodname>guac_client_init()</methodname> along with the
- argument count and argument values received by the connecting
- client.</para>
- <para>It is the duty of the client plugin implementation to populate the
- event handlers of the <classname>guac_client</classname> it receives
- as applicable. Once this is done, and the
- <methodname>guac_client_init()</methodname> function returns
- successfully, communication with the connected client begins, and
- guacd will invoke the event handlers of the
- <classname>guac_client</classname> as necessary for any
- instruction received.</para>
+ <para>Client plugins are libraries which follow specific conventions such that they can be
+ loaded dynamically by guacd. All client plugins <emphasis>must</emphasis>:</para>
+ <orderedlist>
+ <listitem>
+ <para>Follow a naming convention, where the name of the library is
+ <package>libguac-client-<replaceable>PROTOCOL</replaceable></package>.
+ <emphasis>This is necessary for guacd to locate the library for a requested
+ protocol.</emphasis></para>
+ </listitem>
+ <listitem>
+ <para>Be linked against libguac, the library used by guacd to handle the Guacamole
+ protocol. The structures which are given to functions invoked by guacd are
+ defined by libguac, and are expected to be manipulated via the functions
+ provided by libguac or as otherwise documented within the structure itself.
+ <emphasis>Communication between guacd and client plugins is only possible if
+ they share the same core structural and functional definitions provided by
+ libguac.</emphasis></para>
+ </listitem>
+ <listitem>
+ <para>Implement the standard entry point for client plugins,
+ <methodname>guac_client_init()</methodname>, described in more detail below.
+ It is this function which initializes the structures provided by guacd such that
+ users can join and interact with the connection.</para>
+ </listitem>
+ </orderedlist>
+ <section xml:id="libguac-lifecycle-entry">
+ <title>Entry point</title>
+ <para>All client plugins must provide a function named
+ <methodname>guac_client_init</methodname> which accepts, as its sole argument, a
+ pointer to a <classname>guac_client</classname> structure. This function is similar
+ in principle to the <methodname>main()</methodname> function of a C program, and it
+ is the responsibility of this function to initialize the provided structure as
+ necessary to begin the actual remote desktop connection, allow users to join/leave,
+ etc.</para>
+ <para>The provided <classname>guac_client</classname> will already have been initialized
+ with handlers for logging, the broadcast socket, etc. The absolutely critical pieces
+ which must be provided by <methodname>guac_client_init</methodname> are:</para>
+ <orderedlist>
+ <listitem>
+ <para>A handler for users which join the connection
+ (<property>join_handler</property>). The join handler is also usually
+ the most appropriate place for the actual remote desktop connection to be
+ established.</para>
+ </listitem>
+ <listitem>
+ <para>A <constant>NULL</constant>-terminated set of argument names which the
+ client plugin accepts, assigned to the <property>args</property> property of
+ the given <classname>guac_client</classname>. As the handshake procedure is
+ completed for each connecting user, these argument names will be presented
+ as part of the handshake, and the values for those arguments will be passed
+ to the join handler once the handshake completes.</para>
+ </listitem>
+ <listitem>
+ <para>A handler for users leaving the connection
+ (<property>leave_handler</property>), if any cleanup, updates, etc. are
+ required.</para>
+ </listitem>
+ <listitem>
+ <para>A handler for freeing the data associated with the
+ <classname>guac_client</classname> after the connection has terminated
+ (<property>free_handler</property>). If your plugin will allocate any
+ data at all, implementing the free handler is necessary to avoid memory
+ leaks.</para>
+ </listitem>
+ </orderedlist>
+ <para>If <methodname>guac_client_init</methodname> returns successfully, guacd will
+ proceed with allowing the first use to join the connection, and the rest of the
+ plugin lifecycle commences.</para>
+ </section>
+ <section xml:id="libguac-lifecycle-users">
+ <title>Joining/leaving a connection</title>
+ <para>Whenever a user joins a connection, including the very first user of a connection
+ (the user which is establishing the remote desktop connection in the first place),
+ the join handler of the <property>guac_client</property> will be invoked. This
+ handler is provided with the <classname>guac_user</classname> structure representing
+ the user that just joined, along with the arguments provided during the handshake
+ procedure:</para>
+ <informalexample>
+ <programlisting>int join_handler(guac_user* user, int argc, char** argv) {
+ /* Synchronize display state, init the user, etc. */
+}
+
+...
+
+/* Within guac_client_init */
+client->join_handler = join_handler;</programlisting>
+ </informalexample>
+ <para>As the parameters and user information provided during the Guacamole protocol
+ handshake are often required to be known before the remote desktop connection can be
+ established, the join handler is usually the best place to create a thread which
+ establishes the remote desktop connection and updates the display
+ accordingly.</para>
+ <para>If necessary, the user which first established the connection can be distinguished
+ from all other users by the <property>owner</property> flag of
+ <classname>guac_user</classname>, which will be set to a non-zero value.</para>
+ <para>Once a user has disconnected, the leave handler of
+ <classname>guac_client</classname> will be invoked. Just as with the join
+ handler, this handler is provided the <classname>guac_user</classname> structure of
+ the user that disconnected. The <classname>guac_user</classname> structure will be
+ freed immediately after the handler completes:</para>
+ <informalexample>
+ <programlisting>int leave_handler(guac_user* user) {
+ /* Free user-specific data and clean up */
+}
+
+...
+
+/* Within guac_client_init */
+client->leave_handler = leave_handler;</programlisting>
+ </informalexample>
+ </section>
+ <section xml:id="libguac-lifecycle-termination">
+ <title>Termination</title>
+ <para>Once the last user of a connection has left, guacd will begin freeing resources
+ allocated to that connection, invoking the free handler of the
+ <classname>guac_client</classname>. At this point, the "leave" handler has been
+ invoked for all previous users. All that remains is for the client plugin to free
+ any remaining data that it allocated, such that guacd can clean up the rest:</para>
+ <informalexample>
+ <programlisting>int free_handler(guac_client* client) {
+ /* Disconnect, free client-specific data, etc. */
+}
+
+...
+
+/* Within guac_client_init */
+client->free_handler = free_handler;</programlisting>
+ </informalexample>
+ </section>
</section>
<section xml:id="libguac-layers">
<title>Layers and buffers</title>
[3/7] incubator-guacamole-manual git commit: GUACAMOLE-88: Remove
legacy description of handle_messages. It does not exist any longer.
Posted by jm...@apache.org.
GUACAMOLE-88: Remove legacy description of handle_messages. It does not exist any longer.
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/fe5f04d8
Tree: http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/tree/fe5f04d8
Diff: http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/diff/fe5f04d8
Branch: refs/heads/master
Commit: fe5f04d81d18352e6689e6705473d29f8d340bd3
Parents: 2a7ef1e
Author: Michael Jumper <mj...@apache.org>
Authored: Mon Oct 17 18:21:30 2016 -0700
Committer: Michael Jumper <mj...@apache.org>
Committed: Mon Oct 17 18:21:30 2016 -0700
----------------------------------------------------------------------
src/chapters/libguac.xml | 30 ------------------------------
1 file changed, 30 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/blob/fe5f04d8/src/chapters/libguac.xml
----------------------------------------------------------------------
diff --git a/src/chapters/libguac.xml b/src/chapters/libguac.xml
index ad2c137..ef8a9c0 100644
--- a/src/chapters/libguac.xml
+++ b/src/chapters/libguac.xml
@@ -267,35 +267,5 @@ user->mouse_handler = mouse_handler;</programlisting>
user->clipboard_handler = clipboard_handler;</programlisting>
</informalexample>
</section>
- <section xml:id="libguac-message-handling">
- <title>Handling server messages</title>
- <para>A client plugin implementation is expected to only handle
- server messages when control is given to it via a call to the
- message handler installed in the
- <property>handle_messages</property> member of the
- <classname>guac_client</classname>. While it might seem
- intuitive to simply create a thread which handles server message
- in the background, it is important that you do not do this, as
- guacd pays attention to the exchange of sync instructions back
- and forth between itself and the client to determine if the
- client is under load or falling behind due to network problems,
- and will restrict how frequently the message handler is called
- accordingly. Ignoring this can lead to the client being
- overwhelmed with instructions, leading to a bad user
- experience.</para>
- <para>The message handler is simpler than all the other handlers,
- receiving only a pointer to the current
- <classname>guac_client</classname>:</para>
- <informalexample>
- <programlisting>int message_handler(guac_client* client) {
- /* Handle server messages */
-}
-
-...
-
-/* Within guac_client_init */
-client->handle_messages = message_handler;</programlisting>
- </informalexample>
- </section>
</section>
</chapter>
[2/7] incubator-guacamole-manual git commit: GUACAMOLE-88: Update
event handler documentation regarding user-specific events.
Posted by jm...@apache.org.
GUACAMOLE-88: Update event handler documentation regarding user-specific events.
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/2a7ef1e5
Tree: http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/tree/2a7ef1e5
Diff: http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/diff/2a7ef1e5
Branch: refs/heads/master
Commit: 2a7ef1e5396ae800a6be54b81bafb6775823bc34
Parents: 69c96d5
Author: Michael Jumper <mj...@apache.org>
Authored: Mon Oct 17 18:18:24 2016 -0700
Committer: Michael Jumper <mj...@apache.org>
Committed: Mon Oct 17 18:18:24 2016 -0700
----------------------------------------------------------------------
src/chapters/libguac.xml | 74 +++++++++++++++++++------------------------
1 file changed, 33 insertions(+), 41 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/blob/2a7ef1e5/src/chapters/libguac.xml
----------------------------------------------------------------------
diff --git a/src/chapters/libguac.xml b/src/chapters/libguac.xml
index 048ab86..ad2c137 100644
--- a/src/chapters/libguac.xml
+++ b/src/chapters/libguac.xml
@@ -166,54 +166,50 @@
</section>
<section xml:id="libguac-event-handling">
<title>Event handling</title>
- <para>Generally, as guacd receives instructions from the connected
- client, it invokes event handlers if set within the associated
- <classname>guac_client</classname> instance. These handlers
- correspond to the instructions received, which in turn correspond to
- events which occur on the client side. The only exception to this is
- when guacd wishes to give the client plugin control and allow it to
- handle any messages that may have arrived from the remote desktop
- server, in which case it invokes a specific event handler dedicated
- to this purpose.</para>
+ <para>Generally, as guacd receives instructions from the connected client, it invokes event
+ handlers if set within the associated <classname>guac_user</classname> or
+ <classname>guac_client</classname>, depending on the nature of the event. Most
+ events are user-specific, and thus the event handlers reside within the
+ <classname>guac_user</classname> structure, but there are client-specific events as
+ well, such as a user joining or leaving the current connection. Event handlers typically
+ correspond to Guacamole protocol instructions received over the socket by a connected
+ user, which in turn correspond to events which occur on the client side.</para>
<section xml:id="libguac-key-events">
<title>Key events</title>
- <para>When keys are pressed or released on the client side, the
- client sends key instructions to the server. These instructions
- are parsed and handled by calling the key event handler
- installed in the <property>key_handler</property> member of the
- <classname>guac_client</classname>. This key handler is
- given the keysym of the key that was changed, and a boolean
- value indicating whether the key was pressed or released.</para>
+ <para>When keys are pressed or released on the client side, the client sends key
+ instructions to the server. These instructions are parsed and handled by calling the
+ key event handler installed in the <property>key_handler</property> member of the
+ <classname>guac_user</classname>. This key handler is given the keysym of the
+ key that was changed, and a boolean value indicating whether the key was pressed or
+ released.</para>
<informalexample>
- <programlisting>int key_handler(guac_client* client, int keysym, int pressed) {
+ <programlisting>int key_handler(guac_user* user, int keysym, int pressed) {
/* Do something */
}
...
-/* Within guac_client_init */
-client->key_handler = key_handler;</programlisting>
+/* Within the "join" handler of guac_client */
+user->key_handler = key_handler;</programlisting>
</informalexample>
</section>
<section xml:id="libguac-mouse-events">
<title>Mouse events</title>
- <para>When the mouse is moved, and buttons are pressed or released,
- the client sends mouse instructions to the server. These
- instructions are parsed and handled by calling the mouse event
- handler installed in the <property>mouse_handler</property>
- member of the <classname>guac_client</classname>. This mouse
- handler is given the current X and Y coordinates of the mouse
- pointer, as well as a mask indicating which buttons are pressed
- and which are released.</para>
+ <para>When the mouse is moved, and buttons are pressed or released, the client sends
+ mouse instructions to the server. These instructions are parsed and handled by
+ calling the mouse event handler installed in the <property>mouse_handler</property>
+ member of the <classname>guac_user</classname>. This mouse handler is given the
+ current X and Y coordinates of the mouse pointer, as well as a mask indicating which
+ buttons are pressed and which are released.</para>
<informalexample>
- <programlisting>int mouse_handler(guac_client* client, int x, int y, int button_mask) {
+ <programlisting>int mouse_handler(guac_user* user, int x, int y, int button_mask) {
/* Do something */
}
...
-/* Within guac_client_init */
-client->mouse_handler = mouse_handler;</programlisting>
+/* Within the "join" handler of guac_client */
+user->mouse_handler = mouse_handler;</programlisting>
</informalexample>
<para>The file <filename>client.h</filename> also defines the mask
of each button for convenience:</para>
@@ -256,24 +252,20 @@ client->mouse_handler = mouse_handler;</programlisting>
</section>
<section xml:id="libguac-clipboard-events">
<title>Clipboard events</title>
- <para>If the client sends data which should be sent to the clipboard
- of the remote desktop, guacd will trigger the clipboard handler
- installed in the <property>clipboard_handler</property> member
- of the <classname>guac_client</classname>.</para>
+ <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 the
+ <property>clipboard_handler</property> member of the
+ <classname>guac_user</classname> associated with that user.</para>
<informalexample>
- <programlisting>int clipboard_handler(guac_client* client, char* text) {
+ <programlisting>int clipboard_handler(guac_user* user, guac_stream* stream, char* mimetype) {
/* Do something */
}
...
-/* Within guac_client_init */
-client->clipboard_handler = clipboard_handler;</programlisting>
+/* Within the "join" handler of guac_client */
+user->clipboard_handler = clipboard_handler;</programlisting>
</informalexample>
- <para>The data given will always be a
- <constant>NULL</constant>-terminated string of UTF8-encoded
- text. The Guacamole protocol does not yet support clipboard data
- in other formats.</para>
</section>
<section xml:id="libguac-message-handling">
<title>Handling server messages</title>
[6/7] incubator-guacamole-manual git commit: GUACAMOLE-88: Describe
libguac support for streams.
Posted by jm...@apache.org.
GUACAMOLE-88: Describe libguac support for streams.
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/1dcac2fb
Tree: http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/tree/1dcac2fb
Diff: http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/diff/1dcac2fb
Branch: refs/heads/master
Commit: 1dcac2fb61ff918e3c7b53b3d9d60315c55b95fd
Parents: ea562cf
Author: Michael Jumper <mj...@apache.org>
Authored: Mon Oct 17 19:40:32 2016 -0700
Committer: Michael Jumper <mj...@apache.org>
Committed: Mon Oct 17 19:40:32 2016 -0700
----------------------------------------------------------------------
src/chapters/libguac.xml | 66 ++++++++++++++++++++++++++++++++++++++++++-
1 file changed, 65 insertions(+), 1 deletion(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/blob/1dcac2fb/src/chapters/libguac.xml
----------------------------------------------------------------------
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>
+ <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 <methodname>guac_client_alloc_stream()</methodname>
+ 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 <methodname>guac_user_alloc_stream()</methodname>.</para>
+ <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="http://www.w3.org/1999/xlink" linkend="clipboard-instruction"
+ >"clipboard" instruction</link>), audio (via the <link
+ xmlns:xlink="http://www.w3.org/1999/xlink" linkend="audio-stream-instruction"
+ >"audio" instruction</link>), and even the images which make up typical drawing
+ operations (via the <link xmlns:xlink="http://www.w3.org/1999/xlink"
+ 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 <classname>guac_client</classname>
+ 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="http://www.w3.org/1999/xlink" linkend="guacamole-protocol-streaming"/>
+ and <xref xmlns:xlink="http://www.w3.org/1999/xlink" linkend="protocol-reference"
+ />.</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>
</variablelist>
</section>
<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 the
<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>
</informalexample>
+ <para>The handler is expected to assign further handlers to the provided
+ <classname>guac_stream</classname> as necessary, such that the <link
+ xmlns:xlink="http://www.w3.org/1999/xlink" linkend="blob-instruction"
+ >"blob"</link> and <link xmlns:xlink="http://www.w3.org/1999/xlink"
+ linkend="end-instruction">"end"</link> instructions received along the stream
+ can be handled. A similar handler is provided for received files:</para>
+ <informalexample>
+ <programlisting>int file_handler(guac_user* user, guac_stream* 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="http://www.w3.org/1999/xlink" linkend="ack-instruction">"ack"
+ instruction</link> and appropriate error code, informing the user's Guacamole
+ client that the stream is unsupported.</para>
</section>
</section>
</chapter>
[7/7] incubator-guacamole-manual git commit: GUACAMOLE-88: Merge
updated documentation for libguac.
Posted by jm...@apache.org.
GUACAMOLE-88: Merge updated documentation for libguac.
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/3310df42
Tree: http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/tree/3310df42
Diff: http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/diff/3310df42
Branch: refs/heads/master
Commit: 3310df42196d984c5d0bd49ae3f8adb6f52178f3
Parents: b5ecd99 1dcac2f
Author: James Muehlner <ja...@guac-dev.org>
Authored: Mon Oct 17 20:05:15 2016 -0700
Committer: James Muehlner <ja...@guac-dev.org>
Committed: Mon Oct 17 20:05:15 2016 -0700
----------------------------------------------------------------------
src/chapters/libguac.xml | 426 +++++++++++++++++++++++------------------
src/chapters/protocol.xml | 15 --
2 files changed, 241 insertions(+), 200 deletions(-)
----------------------------------------------------------------------
[4/7] incubator-guacamole-manual git commit: GUACAMOLE-88: Describe
user-specific vs. broadcast sockets.
Posted by jm...@apache.org.
GUACAMOLE-88: Describe user-specific vs. broadcast sockets.
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/5ab54f0a
Tree: http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/tree/5ab54f0a
Diff: http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/diff/5ab54f0a
Branch: refs/heads/master
Commit: 5ab54f0a2c93b7315b4e7d11b263145bd8e83072
Parents: fe5f04d
Author: Michael Jumper <mj...@apache.org>
Authored: Mon Oct 17 18:29:08 2016 -0700
Committer: Michael Jumper <mj...@apache.org>
Committed: Mon Oct 17 18:29:08 2016 -0700
----------------------------------------------------------------------
src/chapters/libguac.xml | 34 ++++++++++++++++++++++------------
1 file changed, 22 insertions(+), 12 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/blob/5ab54f0a/src/chapters/libguac.xml
----------------------------------------------------------------------
diff --git a/src/chapters/libguac.xml b/src/chapters/libguac.xml
index ef8a9c0..1d32993 100644
--- a/src/chapters/libguac.xml
+++ b/src/chapters/libguac.xml
@@ -134,12 +134,10 @@
</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 connected client using the Guacamole protocol.
- The same goes for streaming audio, video, or file content. All
- features and content supported by Guacamole ultimately reduces to
- one or more instructions which are part of the documented
- protocol.</para>
+ <para>All drawing in Guacamole is accomplished through the sending of instructions to the
+ connected client using the Guacamole protocol. The same goes for streaming audio, video,
+ or file content. All features and content supported by Guacamole ultimately reduce to
+ one or more instructions which are part of the documented protocol.</para>
<para>Most drawing using libguac is done using Cairo functions on a
<classname>cairo_surface_t</classname> (see the Cairo API documentation) which is
later streamed to the client using an <methodname>img</methodname> instruction and
@@ -154,15 +152,27 @@
all Guacamole protocol instructions, each instruction has a
corresponding function in libguac following the naming convention
<methodname>guac_protocol_send_<replaceable>OPCODE</replaceable>()</methodname>.</para>
- <para>Each protocol function takes a <classname>guac_socket</classname>
- as an argument, which is the buffered I/O object used by libguac.
- The <classname>guac_socket</classname> corresponding to the
- connected client is stored within the socket member of the
- <classname>guac_client</classname> object in use, for
- example:</para>
+ <para>Each protocol function takes a <classname>guac_socket</classname> as an argument,
+ which is the buffered I/O object used by libguac. For each active connection, there are
+ two important types of <classname>guac_socket</classname> instance: the broadcast
+ socket, which exists at the client level within the <classname>guac_client</classname>,
+ and the per-user socket, which is accessible within each
+ <classname>guac_user</classname>. Data sent along the client-level broadcast socket
+ will be sent to all connected users beneath that <classname>guac_client</classname>,
+ while data sent along a user-level socket will be sent only to that user.</para>
+ <para>For example, to send a "size" instruction to all connected users via the client-level
+ broadcast socket, you could invoke:</para>
<informalexample>
<programlisting>guac_protocol_send_size(client->socket, GUAC_DEFAULT_LAYER, 1024, 768);</programlisting>
</informalexample>
+ <para>Or, if the instruction is only relevant to a particular user, the socket associated
+ with that user can be used instead:</para>
+ <informalexample>
+ <programlisting>guac_protocol_send_size(<emphasis>user</emphasis>->socket, GUAC_DEFAULT_LAYER, 1024, 768);</programlisting>
+ </informalexample>
+ <para>The sockets provided by libguac are threadsafe at the protocol level. Instructions
+ written to a socket by multiple threads are guaranteed to be written atomically with
+ respect to that socket.</para>
</section>
<section xml:id="libguac-event-handling">
<title>Event handling</title>