You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@guacamole.apache.org by "necouchman (via GitHub)" <gi...@apache.org> on 2023/01/23 18:48:30 UTC
[GitHub] [guacamole-manual] necouchman opened a new pull request, #192: GUACAMOLE-1293: Document protocol changes associated with sending messages to the client.
necouchman opened a new pull request, #192:
URL: https://github.com/apache/guacamole-manual/pull/192
This PR documents the protocol changes that were made when implementing the notification of connection join and leave events, notably the changes to the client -> server handshake, and the msg instruction.
--
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
[GitHub] [guacamole-manual] necouchman commented on a diff in pull request #192: GUACAMOLE-1293: Document protocol changes associated with sending messages to the client.
Posted by "necouchman (via GitHub)" <gi...@apache.org>.
necouchman commented on code in PR #192:
URL: https://github.com/apache/guacamole-manual/pull/192#discussion_r1085985505
##########
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:
Yeah, good point - fixed via rebase.
##########
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:
Fixed via rebase.
--
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
[GitHub] [guacamole-manual] necouchman commented on a diff in pull request #192: GUACAMOLE-1293: Document protocol changes associated with sending messages to the client.
Posted by "necouchman (via GitHub)" <gi...@apache.org>.
necouchman commented on code in PR #192:
URL: https://github.com/apache/guacamole-manual/pull/192#discussion_r1092430920
##########
src/protocol-reference.rst:
##########
@@ -1203,3 +1230,22 @@ human-readable way.
The client is already using too many resources. Existing resources must be
freed before further requests are allowed.
+Message Codes
+-------------
+
+The `msg` instruction must have at least one numeric argument that the client
+then uses to interpret the message and determine what action, if any, it
+should take based on the message. The following numeric codes are currently
+implemented for this instruction.
+
+1 (``USER_JOINED``)
+ Notifies the owner of a connection that another user has joined the
+ connection. This message is expected to include one additional
+ argument, which is a string with the name of the user who has
+ joined the connection.
+
+2 (``USER_LEFT``)
+ Notifies the owner of a connection that another user has left the
+ connection. This message is expected to include one additional
+ argument, a string with the name of the user who has left the
+ connection.
Review Comment:
Yep, you are correct - fixed via rebase.
--
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
[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.
Posted by "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
[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.
Posted by "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_r1089801081
##########
src/protocol-reference.rst:
##########
@@ -1203,3 +1230,22 @@ human-readable way.
The client is already using too many resources. Existing resources must be
freed before further requests are allowed.
+Message Codes
+-------------
+
+The `msg` instruction must have at least one numeric argument that the client
+then uses to interpret the message and determine what action, if any, it
+should take based on the message. The following numeric codes are currently
+implemented for this instruction.
+
+1 (``USER_JOINED``)
+ Notifies the owner of a connection that another user has joined the
+ connection. This message is expected to include one additional
+ argument, which is a string with the name of the user who has
+ joined the connection.
+
+2 (``USER_LEFT``)
+ Notifies the owner of a connection that another user has left the
+ connection. This message is expected to include one additional
+ argument, a string with the name of the user who has left the
+ connection.
Review Comment:
I think these message types are missing an argument. For example, from `client.c`:
```c
/* Send user joined notification to owner. */
const char* args[] = { (const char*)joiner->user_id, (const char*)send_joiner, NULL };
return (void*) ((intptr_t) guac_protocol_send_msg(user->socket, GUAC_MESSAGE_USER_JOINED, args));
```
There are two arguments sent with the join/leave messages: a unique ID for the relevant user (assigned by guacd) and that user's arbitrary name (received by guacd during the connection handshake).
--
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
[GitHub] [guacamole-manual] necouchman commented on a diff in pull request #192: GUACAMOLE-1293: Document protocol changes associated with sending messages to the client.
Posted by "necouchman (via GitHub)" <gi...@apache.org>.
necouchman commented on code in PR #192:
URL: https://github.com/apache/guacamole-manual/pull/192#discussion_r1085990725
##########
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:
Added a commit with the message code documentation.
--
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
[GitHub] [guacamole-manual] mike-jumper merged pull request #192: GUACAMOLE-1293: Document protocol changes associated with sending messages to the client.
Posted by "mike-jumper (via GitHub)" <gi...@apache.org>.
mike-jumper merged PR #192:
URL: https://github.com/apache/guacamole-manual/pull/192
--
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
[GitHub] [guacamole-manual] necouchman commented on a diff in pull request #192: GUACAMOLE-1293: Document protocol changes associated with sending messages to the client.
Posted by "necouchman (via GitHub)" <gi...@apache.org>.
necouchman commented on code in PR #192:
URL: https://github.com/apache/guacamole-manual/pull/192#discussion_r1085985189
##########
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:
Fixed via rebase.
##########
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:
Fixed via rebase.
--
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
[GitHub] [guacamole-manual] necouchman commented on a diff in pull request #192: GUACAMOLE-1293: Document protocol changes associated with sending messages to the client.
Posted by "necouchman (via GitHub)" <gi...@apache.org>.
necouchman commented on code in PR #192:
URL: https://github.com/apache/guacamole-manual/pull/192#discussion_r1085985822
##########
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:
Okay, will add them after the status codes.
--
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