From 98c46c2b8c4bda22f166a011100f2ad6747efea8 Mon Sep 17 00:00:00 2001
From: "Timur A. Fatkhullin" <timur@sao.ru>
Date: Sun, 28 Sep 2025 19:31:03 +0300
Subject: [PATCH] ...

---
 mcc/mcc_netserver_proto.h | 54 ++++++++++++++++++++++++++++++++-------
 1 file changed, 45 insertions(+), 9 deletions(-)

diff --git a/mcc/mcc_netserver_proto.h b/mcc/mcc_netserver_proto.h
index d80ca55..b1a23a4 100644
--- a/mcc/mcc_netserver_proto.h
+++ b/mcc/mcc_netserver_proto.h
@@ -49,6 +49,15 @@ static constexpr std::string_view MCC_COMMPROTO_KEYWORD_SERVER_ERROR_STR = "ERRO
 static constexpr std::string_view MCC_COMMPROTO_SERVER_ERROR_INVKEY_STR = "INVKEY";  // invalid keyword
 static constexpr std::string_view MCC_COMMPROTO_SERVER_ERROR_INVPAR_STR = "INVPAR";  // invalid parameter
 
+
+/*    server control keywords     */
+
+static constexpr std::string_view MCC_COMMPROTO_KEYWORD_RESTART_SERVER_STR = "RESTART";  // restart server
+
+
+/*                  BELOW IS ONE OF THE PROTOCOL OPTIONS CORRESPONDING MCC_GENERIC_MOUNT_C CONCEPT */
+
+
 /*    predefined parameters    */
 
 static constexpr std::string_view MCC_COMMPROTO_COORD_KIND_RADEC_ICRS = "RADEC_ICRS";  // ICRS RA and DEC
@@ -88,11 +97,6 @@ static constexpr MccCoordPairKind mcc_str2pairkind(R&& spair)
                                                                               : MccCoordPairKind::COORDS_KIND_GENERIC;
 }
 
-// static constexpr MccCoordPairKind mcc_str2pairkind(const char* spair)
-// {
-//     return mcc_str2pairkind(std::string_view{spair});
-// }
-
 
 static constexpr std::string_view mcc_pairkind2str(MccCoordPairKind kind)
 {
@@ -143,6 +147,7 @@ static constexpr std::string_view MCC_COMMPROTO_KEYWORD_COORDFMT_STR = "COORDFMT
 static constexpr std::string_view MCC_COMMPROTO_KEYWORD_COORDFMT_SEXGM_STR = "SGM";  // sexagesimal
 static constexpr std::string_view MCC_COMMPROTO_KEYWORD_COORDFMT_FIXED_STR = "FIX";  // fixed point
 
+
 // precision (number of decimal places) of returned coordinates:
 //     "COORDPREC seconds-prec arcseconds-prec\n"
 //     seconds-prec - precision of hour-based coordinates (RA and HA) or time-related quantities
@@ -224,7 +229,7 @@ static constexpr std::array MCC_COMMPROTO_VALID_KEYS = {
     MCC_COMMPROTO_KEYWORD_STATUS_STR};
 
 
-// hashes valid keywords
+// hashes of valid keywords
 static constexpr std::array MCC_COMMPROTO_VALID_KEYS_HASH = []<size_t... Is>(std::index_sequence<Is...>) {
     return std::array{mcc::utils::FNV1aHash(MCC_COMMPROTO_VALID_KEYS[Is])...};
 }(std::make_index_sequence<MCC_COMMPROTO_VALID_KEYS.size()>());
@@ -248,15 +253,22 @@ struct mcc_netmsg_parse_result_t {
     RT params;
 };
 
+
+// network message parsing result class concept
 template <typename T>
 concept mcc_netmsg_parse_result_c = requires(T t) {
-    requires std::same_as<decltype(t.keyword_hash), size_t>;
-    requires traits::mcc_char_range<decltype(t.keyword)>;
+    requires std::same_as<decltype(t.keyword_hash), size_t>;  // hash of keyword
+    requires traits::mcc_char_range<decltype(t.keyword)>;     // keyword char-range representation
+    // a range of parameters char-range representations
     requires std::ranges::output_range<decltype(t.params), decltype(t.keyword)>;
 };
 
 // the function returns hash of message keyword
-// template <traits::mcc_input_char_range IR, traits::mcc_range_of_output_char_range OT>
+//     if 'from_server' is true then given network message is considered as a server response, i.e.,
+//     valid keywords are "ACK" or "ERROR"
+//
+//     the funtions returns false in the case of invalid message format and true otherwise
+//
 template <traits::mcc_input_char_range IR, mcc_netmsg_parse_result_c ResT>
 bool mcc_parse_netmsg(const IR& netmsg, ResT& parse_res, bool from_server = false)
 {
@@ -299,6 +311,9 @@ bool mcc_parse_netmsg(const IR& netmsg, ResT& parse_res, bool from_server = fals
     return true;
 }
 
+
+// construct network message
+//     the function returns false if input keyword is not valid one (see MCC_COMMPROTO_VALID_KEYS)!
 template <typename... PTs>
 bool mcc_netmsg_construct(traits::mcc_output_char_range auto& msg,
                           traits::mcc_input_char_range auto const& keyword,
@@ -340,6 +355,27 @@ bool mcc_netmsg_construct(traits::mcc_output_char_range auto& msg,
     return true;
 }
 
+
+// the function convert given network message parsing result class to
+// celestial point coordinates according to parsed message parameters.
+//
+// It is assumed that the coordinates and their type are contained in the consecutive elements of the input array
+// starting from the element 'from_idx' (zero-based):
+//
+//    parse_res.params[...,  X-COORD, Y-COORD, XY-KIND, ...]
+//
+//    th last parameter 'XY-KIND' can be omitted and, in this case, 'default_kind' is assumed
+//
+// NOTE: IT IS ASSUMED THAT THE COORDINATES ARE REPRESENTED AS DEGREES EXPRESSED BY THE NUMBER WITH A FLOATING POINT
+//       OR IN SEXAGESIMAL FORM. IN THE CASE OF SEXAGESIMAL FORM THE TYPE (DEGREES OR HOURS) OF THE COORDINATE
+//       REPRESENTATION IS DETERMINED BY 'XY-KIND', E.G.:
+//           parse_res.params[...,  "12:34:52.123", "23:43:56.12", "HADEC", ...]
+//               'HADEC' STRING FOR 'XY-KIND' DETERMINES THE FIRST COORDINATE (HOUR ANGLE)
+//               AS AN ANGLE IN HOUR FORM WHILE THE SECOND ONE (DECLINATION) IN DEGREES
+//
+//
+// The function returns false if it can not convert coordinate string to number or the 'XY-KIND' string is invalid
+//
 bool mcc_netmsg_get_cpoint(mcc_netmsg_parse_result_c auto const& parse_res,
                            size_t from_idx,
                            mcc_celestial_point_c auto& cpoint,