GUACAMOLE-1204: Add libguac support for processing the "touch" instruction.

src/libguac/guacamole/user-fntypes.h

@@ -95,6 +95,51 @@ typedef void* guac_user_callback(guac_user* user, void* data);
 typedef int guac_user_mouse_handler(guac_user* user, int x, int y,
         int button_mask);
 
+/**
+ * Handler for Guacamole touch events, invoked when a "touch" instruction has
+ * been received from a user.
+ *
+ * @param user
+ *     The user that sent the touch event.
+ *
+ * @param id
+ *     An arbitrary integer ID which uniquely identifies this contact relative
+ *     to other active contacts.
+ *
+ * @param x
+ *     The X coordinate of the center of the touch contact within the display
+ *     when the event occurred, in pixels. This value is not guaranteed to be
+ *     within the bounds of the display area.
+ *
+ * @param y
+ *     The Y coordinate of the center of the touch contact within the display
+ *     when the event occurred, in pixels. This value is not guaranteed to be
+ *     within the bounds of the display area.
+ *
+ * @param x_radius
+ *     The X radius of the ellipse covering the general area of the touch
+ *     contact, in pixels.
+ *
+ * @param y_radius
+ *     The Y radius of the ellipse covering the general area of the touch
+ *     contact, in pixels.
+ *
+ * @param angle
+ *     The rough angle of clockwise rotation of the general area of the touch
+ *     contact, in degrees.
+ *
+ * @param force
+ *     The relative force exerted by the touch contact, where 0 is no force
+ *     (the touch has been lifted) and 1 is maximum force (the maximum amount
+ *     of force representable by the device).
+ *
+ * @return
+ *     Zero if the touch event was handled successfully, or non-zero if an
+ *     error occurred.
+ */
+typedef int guac_user_touch_handler(guac_user* user, int id, int x, int y,
+        int x_radius, int y_radius, double angle, double force);
+
 /**
  * Handler for Guacamole key events, invoked when a "key" event has been
  * received from a user.

src/libguac/guacamole/user.h

@@ -509,6 +509,27 @@ struct guac_user {
      */
     guac_user_argv_handler* argv_handler;
 
+    /**
+     * Handler for touch events sent by the Guacamole web-client.
+     *
+     * The handler takes the integer X and Y coordinates representing the
+     * center of the touch contact, as well as several parameters describing
+     * the general shape of the contact area. The force parameter indicates the
+     * amount of force exerted by the contact, including whether the contact
+     * has been lifted.
+     *
+     * Example:
+     * @code
+     *     int touch_handler(guac_user* user, int id, int x, int y,
+     *             int x_radius, int y_radius, double angle, double force);
+     *
+     *     int guac_user_init(guac_user* user, int argc, char** argv) {
+     *         user->touch_handler = touch_handler;
+     *     }
+     * @endcode
+     */
+    guac_user_touch_handler* touch_handler;
+
 };
 
 /**

src/libguac/user-handlers.c

@@ -37,6 +37,7 @@
 
 __guac_instruction_handler_mapping __guac_instruction_handler_map[] = {
    {"sync",       __guac_handle_sync},
+   {"touch",      __guac_handle_touch},
    {"mouse",      __guac_handle_mouse},
    {"key",        __guac_handle_key},
    {"clipboard",  __guac_handle_clipboard},
@@ -150,6 +151,21 @@ int __guac_handle_sync(guac_user* user, int argc, char** argv) {
     return 0;
 }
 
+int __guac_handle_touch(guac_user* user, int argc, char** argv) {
+    if (user->touch_handler)
+        return user->touch_handler(
+            user,
+            atoi(argv[0]), /* id */
+            atoi(argv[1]), /* x */
+            atoi(argv[2]), /* y */
+            atoi(argv[3]), /* x_radius */
+            atoi(argv[4]), /* y_radius */
+            atof(argv[5]), /* angle */
+            atof(argv[6])  /* force */
+        );
+    return 0;
+}
+
 int __guac_handle_mouse(guac_user* user, int argc, char** argv) {
     if (user->mouse_handler)
         return user->mouse_handler(

src/libguac/user-handlers.h

@@ -85,6 +85,13 @@ __guac_instruction_handler __guac_handle_sync;
  */
 __guac_instruction_handler __guac_handle_mouse;
 
+/**
+ * Internal initial handler for the touch instruction. When a touch instruction
+ * is received, this handler will be called. The client's touch handler will
+ * be invoked if defined.
+ */
+__guac_instruction_handler __guac_handle_touch;
+
 /**
  * Internal initial handler for the key instruction. When a key instruction
  * is received, this handler will be called. The client's key handler will