From 5c941ab832714b8bce24256d1ecbf48c2d9946ba Mon Sep 17 00:00:00 2001 From: Bill Somerville Date: Sun, 10 May 2015 12:02:14 +0000 Subject: [PATCH] Added some more documentation to UDP message descriptions Merged from the wsjtx-1.5 branch. git-svn-id: svn+ssh://svn.code.sf.net/p/wsjt/wsjt/branches/wsjtx@5355 ab8295b8-cf94-4d9e-aec4-7959e3be5d79 --- NetworkMessage.hpp | 91 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 91 insertions(+) diff --git a/NetworkMessage.hpp b/NetworkMessage.hpp index 95f7e1162..329d0c4f7 100644 --- a/NetworkMessage.hpp +++ b/NetworkMessage.hpp @@ -57,6 +57,13 @@ * Heartbeat Out 0 quint32 * Id (unique key) utf8 * + * The heartbeat message is sent on a periodic basis every + * NetworkMessage::pulse seconds (see below). This message is + * intended to be used by server to detect the presence of a client + * and also the unexpected disappearance of a client. The + * message_aggregator reference server does just that. + * + * * Status Out 1 quint32 * Id (unique key) utf8 * Dial Frequency (Hz) quint64 @@ -67,6 +74,22 @@ * Tx Enabled bool * Transmitting bool * + * WSJT-X sends this status message when various internal state + * changes to allow the server to track the relevant state of each + * client without the need for polling commands. The current state + * changes that generate status messages are: + * + * Application start up, + * "Enable Tx" button status changes, + * Dial frequency changes, + * Changes to the "DX Call" field, + * Operating mode changes, + * Transmit mode changed (in dual JT9+JT65 mode), + * Changes to the "Rpt" spinner, + * After an old decodes replay sequence (see Replay below), + * When switching between Tx and Rx mode. + * + * * Decode Out 2 quint32 * Id (unique key) utf8 * New bool @@ -77,9 +100,25 @@ * Mode utf8 * Message utf8 * + * The decode message is send when a new decode is completed, in + * this case the 'New' field is true. It is also used in response + * to a "Replay" message where each old decode in the "Band + * activity" window, that has not been erased, is sent in order + * as a one of these messages with the 'New' field set to + * false. See the "Replay" message below for details of usage. + * + * * Clear Out 3 quint32 * Id (unique key) utf8 * + * This message is send when all prior "Decode" messages in the + * "Band activity" window have been discarded and therefore are + * no long available for actioning with a "Reply" message. It is + * sent when the user erases the "Band activity" window and when + * WSJT-X closes down normally. The server should discard all + * decode messages upon receipt of this message. + * + * * Reply In 4 quint32 * Id (target unique key) utf8 * Time QTime @@ -89,6 +128,22 @@ * Mode utf8 * Message utf8 * + * In order for a server to provide a useful cooperative service + * to WSJT-X it is possible for it to initiate a QSO by sending + * this message to a client. WSJT-X filters this message and only + * acts upon it if the message exactly describes a prior decode + * and that decode is a CQ or QRZ message. The action taken is + * exactly equivalent to the user double clicking the message in + * the "Band activity" window. The intent of this message is for + * servers to be able to provide an advanced look up of potential + * QSO partners, for example determining if they have been worked + * before or if working them may advance some objective like + * award progress. The intention is not to provide a secondary + * user interface for WSJT-X, it is expected that after QSO + * initiation the rest of the QSO is carried out manually using + * the normal WSJT-X user interface. + * + * * QSO Logged Out 5 quint32 * Id (unique key) utf8 * Date & Time QDateTime @@ -102,19 +157,55 @@ * Comments utf8 * Name utf8 * + * The QSO logged message is sent to the server(s) when the + * WSJT-X user accepts the "Log QSO" dialog by clicking the "OK" + * button. + * + * * Close Out 6 quint32 * Id (unique key) utf8 * + * Close is sent by a client immediately prior to it shutting + * down gracefully. + * + * * Replay In 7 quint32 * Id (unique key) utf8 * + * When a server starts it may be useful for it to determine the + * state of preexisting clients. Sending this message to each + * client as it is discovered will cause that client (WSJT-X) to + * send a "Decode" message for each decode currently in its "Band + * activity" window. Each "Decode" message sent will have the + * "New" flag set to false so that they can be distinguished from + * new decodes. After all the old decodes have been broadcast a + * "Status" message is also broadcast. If the server wishes to + * determine the status of a newly discovered client; this + * message should be used. + * + * * Halt Tx In 8 * Id (unique key) utf8 * Auto Tx Only bool * + * The server may stop a client from transmitting messages either + * immediately or at the end of the current transmission period + * using this message. + * + * * Free Text In 9 * Id (unique key) utf8 * Text utf8 + * + * This message allows the server to set the current free text + * message content. Sending this message is equivalent to typing + * a new message (old contents are discarded) in to the WSJT-X + * free text message field or "Tx5" field (both are updated) and + * then clicking the "Next" radio button for the "Tx5" field if + * tab one is current or clicking the "Free msg" radio button if + * tab two is current. It is the responsibility of the sender to + * limit the length of the message text and to legal message + * characters. */ #include