[GitHub] [guacamole-manual] mike-jumper commented on a diff in pull request #192: GUACAMOLE-1293: Document protocol changes associated with sending messages to the client.

["mike-jumper (via GitHub)" <gi...@apache.org>]

mike-jumper commented on code in PR #192:
URL: https://github.com/apache/guacamole-manual/pull/192#discussion_r1085757766


##########
src/protocol-reference.rst:
##########
@@ -713,6 +713,23 @@ Streaming instructions
     :arg string filename:
         The name of the file, as it would be saved on a filesystem.
 
+.. guac:instruction:: msg
+    :sent-by: server
+    :phase: interactive
+
+    Sends a message from the server (gaucd) to the client. The nature of these

Review Comment:
   guacd*



##########
src/protocol-reference.rst:
##########
@@ -713,6 +713,23 @@ Streaming instructions
     :arg string filename:
         The name of the file, as it would be saved on a filesystem.
 
+.. guac:instruction:: msg
+    :sent-by: server
+    :phase: interactive
+
+    Sends a message from the server (gaucd) to the client. The nature of these
+    messages is intentionally ambiguous and flexible - the message must include
+    a numeric code that the client understands and can act on, and may also
+    include one or more arguments that can be used by the client in association
+    with the message.
+
+    :arg integer msg:
+        A numeric value indicating the message that is being passed to the client.
+
+    :arg string args:
+        One or more arguments associated with the message that is being sent
+        to the client.

Review Comment:
   Does the `msg` instruction also allows zero arguments? If so, I think this should be rephrased to "any number of arguments".



##########
src/protocol-reference.rst:
##########
@@ -713,6 +713,23 @@ Streaming instructions
     :arg string filename:
         The name of the file, as it would be saved on a filesystem.
 
+.. guac:instruction:: msg
+    :sent-by: server
+    :phase: interactive
+
+    Sends a message from the server (gaucd) to the client. The nature of these
+    messages is intentionally ambiguous and flexible - the message must include
+    a numeric code that the client understands and can act on, and may also
+    include one or more arguments that can be used by the client in association
+    with the message.
+
+    :arg integer msg:
+        A numeric value indicating the message that is being passed to the client.

Review Comment:
   We should document those values, as well, similar to: https://guacamole.apache.org/doc/gug/protocol-reference.html#status-codes



##########
src/protocol-reference.rst:
##########
@@ -713,6 +713,23 @@ Streaming instructions
     :arg string filename:
         The name of the file, as it would be saved on a filesystem.
 
+.. guac:instruction:: msg
+    :sent-by: server
+    :phase: interactive
+
+    Sends a message from the server (gaucd) to the client. The nature of these
+    messages is intentionally ambiguous and flexible - the message must include

Review Comment:
   I don't think "ambiguous" is quite right - each `msg` unambiguously represents a specific server-side event. Perhaps "broad"?



##########
src/guacamole-protocol.md:
##########
@@ -87,6 +87,12 @@ parameter.
 
 Valid protocol versions are as follows:
 
+`VERSION_1_5_0`
+: Protocol version 1.5.0 introduced two new instructions - the "msg"
+  instruction, which is used to send arbitrary messages to the client, and
+  the "name" handshake instruction, which allows the client to set the

Review Comment:
   `msg` and `name` here should be within backticks so that they are represented as inline code.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: dev-unsubscribe@guacamole.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org