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:13 UTC
[2/7] incubator-guacamole-manual git commit: GUACAMOLE-88: Update
event handler documentation regarding user-specific events.
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>