Added some commentary to HRDTRansceiver.{hpp,cpp}.

git-svn-id: svn+ssh://svn.code.sf.net/p/wsjt/wsjt/branches/wsjtx@4136 ab8295b8-cf94-4d9e-aec4-7959e3be5d79

HRDTransceiver.cpp

@@ -21,7 +21,8 @@ void HRDTransceiver::register_transceivers (TransceiverFactory::Transceivers * r
 
 struct HRDMessage
 {
-  // placement style new overload for outgoing messages that does the construction too
+  // Placement style new overload for outgoing messages that does the
+  // construction too.
   static void * operator new (size_t size, QString const& payload)
   {
     size += sizeof (QChar) * (payload.size () + 1); // space for terminator too
@@ -35,25 +36,26 @@ struct HRDMessage
     return storage;
   }
 
-  // placement style new overload for incoming messages that does the construction too
+  // Placement style new overload for incoming messages that does the
+  // construction too.
   //
-  // no memory allocation here
+  // No memory allocation here.
   static void * operator new (size_t /* size */, QByteArray const& message)
   {
-    // nasty const_cast here to avoid copying the message buffer
+    // Nasty const_cast here to avoid copying the message buffer.
     return const_cast<HRDMessage *> (reinterpret_cast<HRDMessage const *> (message.data ()));
   }
 
   void operator delete (void * p, size_t)
   {
-    delete [] reinterpret_cast<char *> (p); // mirror allocation in operator new above
+    delete [] reinterpret_cast<char *> (p); // Mirror allocation in operator new above.
   }
 
   qint32 size_;
   qint32 magic_1_;
   qint32 magic_2_;
-  qint32 checksum_;	       // apparently not used
+  qint32 checksum_;            // Apparently not used.
-  QChar payload_[0];	       // UTF-16 (which is wchar_t on Windows)
+  QChar payload_[0];           // UTF-16 (which is wchar_t on Windows)
 
   static qint32 const magic_1_value_;
   static qint32 const magic_2_value_;
@@ -118,30 +120,6 @@ void HRDTransceiver::do_start ()
       throw error {tr ("Failed to connect to Ham Radio Deluxe\n") + hrd_->errorString ()};
     }
 
-  init_radio ();
-}
-
-void HRDTransceiver::do_stop ()
-{
-  if (hrd_)
-    {
-      hrd_->close ();
-    }
-
-  if (wrapped_)
-    {
-      wrapped_->stop ();
-    }
-
-#if WSJT_TRACE_CAT
-  qDebug () << "HRDTransceiver::stop: state:" << state () << "reversed =" << reversed_;
-#endif
-}
-
-void HRDTransceiver::init_radio ()
-{
-  Q_ASSERT (hrd_);
-
   if (none == protocol_)
     {
       try
@@ -160,11 +138,11 @@ void HRDTransceiver::init_radio ()
       hrd_->close ();
 
       protocol_ = v4;		// try again with older protocol
-      hrd_->connectToHost (QHostAddress::LocalHost, 7809);
+      hrd_->connectToHost (std::get<0> (server_details), std::get<1> (server_details));
       if (!hrd_->waitForConnected (socket_wait_time))
         {
 #if WSJT_TRACE_CAT
-          qDebug () << "HRDTransceiver::init_radio failed to connect:" <<  hrd_->errorString ();
+          qDebug () << "HRDTransceiver::do_start failed to connect:" <<  hrd_->errorString ();
 #endif
 
           throw error {tr ("Failed to connect to Ham Radio Deluxe\n") + hrd_->errorString ()};
@@ -182,7 +160,7 @@ void HRDTransceiver::init_radio ()
   if (radios.isEmpty ())
     {
 #if WSJT_TRACE_CAT
-      qDebug () << "HRDTransceiver::init_radio no rig found";
+      qDebug () << "HRDTransceiver::do_start no rig found";
 #endif
 
       throw error {tr ("Ham Radio Deluxe: no rig found")};
@@ -205,7 +183,7 @@ void HRDTransceiver::init_radio ()
   if (send_command ("get radio", false, false, true).isEmpty ())
     {
 #if WSJT_TRACE_CAT
-      qDebug () << "HRDTransceiver::init_radio no rig found";
+      qDebug () << "HRDTransceiver::do_start no rig found";
 #endif
 
       throw error {tr ("Ham Radio Deluxe: no rig found")};
@@ -265,6 +243,23 @@ void HRDTransceiver::init_radio ()
   sync_impl ();
 }
 
+void HRDTransceiver::do_stop ()
+{
+  if (hrd_)
+    {
+      hrd_->close ();
+    }
+
+  if (wrapped_)
+    {
+      wrapped_->stop ();
+    }
+
+#if WSJT_TRACE_CAT
+  qDebug () << "HRDTransceiver::stop: state:" << state () << "reversed =" << reversed_;
+#endif
+}
+
 void HRDTransceiver::sync_impl ()
 {
   if (vfo_count_ == 1)

HRDTransceiver.hpp

@@ -34,6 +34,7 @@ public:
   ~HRDTransceiver ();
 
 protected:
+  // Implement the TransceiverBase interface.
   void do_start () override;
   void do_stop () override;
   void do_frequency (Frequency) override;
@@ -41,10 +42,10 @@ protected:
   void do_mode (MODE, bool rationalise) override;
   void do_ptt (bool on) override;
 
+  // Implement the PollingTransceiver interface.
   void poll () override;
 
 private:
-  void init_radio ();
   QString send_command (QString const&, bool no_debug = false, bool prepend_context = true, bool recurse = false);
   void send_simple_command (QString const&, bool no_debug = false);
   void sync_impl ();
@@ -57,40 +58,100 @@ private:
   void set_button (int button_index, bool checked = true);
   bool is_button_checked (int button_index, bool no_debug = false);
 
+  // This dictionary type maps Transceiver::MODE to a list of mode
+  // drop down selection indexes that equate to that mode.  It is used
+  // to map internal MODE values to HRD drop down selections and vice
+  // versa.
   using ModeMap = std::vector<std::tuple<MODE, std::vector<int> > >;
+
   void map_modes (int dropdown, ModeMap *);
   int lookup_mode (MODE, ModeMap const&) const;
   MODE lookup_mode (int, ModeMap const&) const;
 
+  // An alternate TransceiverBase instance that can be used to drive
+  // PTT if required.
   std::unique_ptr<TransceiverBase> wrapped_;
-  bool use_for_ptt_;
+
-  QString server_;
+  bool use_for_ptt_;            // Use HRD for PTT.
-  QTcpSocket * hrd_;
+
-  enum {none, v4, v5} protocol_;
+  QString server_;              // The TCP/IP addrress and port for
+                                // the HRD server.
+
+  QTcpSocket * hrd_;            // The TCP/IP client that links to the
+                                // HRD server.
+
+  enum {none, v4, v5} protocol_; // The HRD protocol that has been
+                                 // detected.
+
   using RadioMap = std::vector<std::tuple<unsigned, QString> >;
-  RadioMap radios_;
+
-  unsigned current_radio_;
+  RadioMap radios_;             // Dictionary of available radios. 
-  unsigned vfo_count_;
+
-  QStringList buttons_;
+  unsigned current_radio_;      // The current addressed radio.
-  QStringList dropdown_names_;
+
-  QMap<QString, QStringList> dropdowns_;
+  unsigned vfo_count_;          // How many VFOs are supported.
-  int vfo_A_button_;
+
-  int vfo_B_button_;
+  QStringList buttons_;         // The buttons available to click.
-  int vfo_toggle_button_;
+
-  int mode_A_dropdown_;
+  QStringList dropdown_names_;  // The names of drop down selectors
-  ModeMap mode_A_map_;
+                                // available.
-  int mode_B_dropdown_;
+
-  ModeMap mode_B_map_;
+  QMap<QString, QStringList> dropdowns_; // Dictionary of available
-  int split_mode_button_;
+                                         // drop down selections
-  int split_mode_dropdown_;
+                                         // available.
-  bool split_mode_dropdown_write_only_;
+
-  std::vector<int> split_mode_dropdown_selection_on_;
+  int vfo_A_button_;            // The button we use to select VFO
-  std::vector<int> split_mode_dropdown_selection_off_;
+                                // A. May be -1 if none available.
-  int split_off_button_;
+
-  int tx_A_button_;
+  int vfo_B_button_;            // Index of button we use to select
-  int tx_B_button_;
+                                // VFO B. May be -1 if none available.
-  int ptt_button_;
+
-  bool reversed_;
+  int vfo_toggle_button_;       // Index of button we use to toggle
+                                // the VFOs. Use this if VFO A and VFO
+                                // B selection are not available.
+
+  int mode_A_dropdown_;         // Index of the mode drop down for VFO
+                                // A.
+
+  ModeMap mode_A_map_;          // The map of modes available for VFO
+                                // A.
+
+  int mode_B_dropdown_;         // The map of modes available for VFO
+                                // B. May be -1 if independent VFO
+                                // mode setting not available.
+
+  ModeMap mode_B_map_;          // The map of modes for VFO B.
+
+  int split_mode_button_;       // Button to use to select split
+                                // operation. May be -1 if no button
+                                // is available.
+
+  int split_mode_dropdown_;     // The drop down list that allows
+                                // split mode to be turned on and off.
+
+  bool split_mode_dropdown_write_only_; // Some rigs cannot report
+                                        // split status.
+
+  std::vector<int> split_mode_dropdown_selection_on_; // The drop down
+                                                      // selection to
+                                                      // turn on
+                                                      // split.
+
+  std::vector<int> split_mode_dropdown_selection_off_; // The drop
+                                                       // down
+                                                       // selection to
+                                                       // disable
+                                                       // split.
+
+  int split_off_button_;        // The button to turn off split mode.
+
+  int tx_A_button_;             // The button to transmit on VFO A.
+
+  int tx_B_button_;             // The button to transmit on VFO B.
+
+  int ptt_button_;              // The button to toggle PTT.
+
+  bool reversed_;               // True if VFOs are reversed.
 };
 
 #endif