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

@@ -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 <QDataStream>