guacamole-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jmuehl...@apache.org
Subject [2/7] incubator-guacamole-manual git commit: GUACAMOLE-88: Update event handler documentation regarding user-specific events.
Date Tue, 18 Oct 2016 03:06:13 GMT
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 <mjumper@apache.org>
Authored: Mon Oct 17 18:18:24 2016 -0700
Committer: Michael Jumper <mjumper@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>


Mime
View raw message