GUACAMOLE-221: Add client support for the "required" instruction.

guacamole-common-js/src/main/webapp/modules/Client.js

@@ -714,6 +714,18 @@ Guacamole.Client = function(tunnel) {
      */
     this.onpipe = null;
     
+    /**
+     * Fired when a "required" instruction is received. A required instruction
+     * indicates that additional parameters are required for the connection to
+     * continue, such as user credentials.
+     * 
+     * @event
+     * @param {String[]} parameters
+     *      The names of the connection parameters that are required to be
+     *      provided for the connection to continue.
+     */
+    this.onrequired = null;
+
     /**
      * Fired whenever a sync instruction is received from the server, indicating
      * that the server is finished processing any input from the client and
@@ -1338,6 +1350,10 @@ Guacamole.Client = function(tunnel) {
 
         },
                 
+        "required": function required(parameters) {
+            if (guac_client.onrequired) guac_client.onrequired(parameters);
+        },
+        
         "reset": function(parameters) {
 
             var layer = getLayer(parseInt(parameters[0]));

guacamole-common/src/main/java/org/apache/guacamole/protocol/GuacamoleProtocolCapability.java

@@ -41,6 +41,15 @@ public enum GuacamoleProtocolCapability {
      */
     PROTOCOL_VERSION_DETECTION(GuacamoleProtocolVersion.VERSION_1_1_0),
 
+    /**
+     * Support for the "required" instruction. The "required" instruction
+     * allows the server to explicitly request connection parameters from the
+     * client without which the connection cannot continue, such as user
+     * credentials. Support for this instruction was introduced in
+     * {@link GuacamoleProtocolVersion#VERSION_1_3_0}.
+     */
+    REQUIRED_INSTRUCTION(GuacamoleProtocolVersion.VERSION_1_3_0),
+
     /**
      * Support for the "timezone" handshake instruction. The "timezone"
      * instruction allows the client to request that the server forward their

guacamole-common/src/main/java/org/apache/guacamole/protocol/GuacamoleProtocolVersion.java

@@ -46,11 +46,18 @@ public class GuacamoleProtocolVersion {
      */
     public static final GuacamoleProtocolVersion VERSION_1_1_0 = new GuacamoleProtocolVersion(1, 1, 0);
 
+    /**
+     * Protocol version 1.3.0, which introduces the "required" instruction
+     * allowing the server to explicitly request connection parameters from the
+     * client.
+     */
+    public static final GuacamoleProtocolVersion VERSION_1_3_0 = new GuacamoleProtocolVersion(1, 3, 0);
+
     /**
      * The most recent version of the Guacamole protocol at the time this
      * version of GuacamoleProtocolVersion was built.
      */
-    public static final GuacamoleProtocolVersion LATEST = VERSION_1_1_0;
+    public static final GuacamoleProtocolVersion LATEST = VERSION_1_3_0;
     
     /**
      * A regular expression that matches the VERSION_X_Y_Z pattern, where