Update some mbglib files for better variant name support

3 files changed, 145 insertions, 40 deletions

diff --git a/mbglib/common/mbgdevio.h b/mbglib/common/mbgdevio.h
index f17ca2b..f27e653 100644
--- a/mbglib/common/mbgdevio.h
+++ b/mbglib/common/mbgdevio.h
@@ -1,7 +1,7 @@
 
 /**************************************************************************
  *
- *  $Id: mbgdevio.h 1.60 2022/02/10 13:56:19Z martin.burnicki REL_M $
+ *  $Id: mbgdevio.h 1.61 2022/04/27 15:04:20Z martin.burnicki REL_M $
  *
  *  Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany
  *
@@ -10,7 +10,11 @@
  *
  * -----------------------------------------------------------------------
  *  $Log: mbgdevio.h $
- *  Revision 1.60  2022/02/10 13:56:19Z  martin.burnicki
+ *  Revision 1.61  2022/04/27 15:04:20Z  martin.burnicki
+ *  New inline functions mbg_create_dev_name() and
+ *  mbg_create_dev_name_from_dev_info().
+ *  Updated function prototypes.
+ *  Revision 1.60  2022/02/10 13:56:19  martin.burnicki
  *  Fixed some doxygen comments.
  *  Revision 1.59  2021/11/08 21:31:51  martin.burnicki
  *  Updated function prototypes.
@@ -240,6 +244,7 @@
 #include <mbg_tgt.h>
 #include <mbg_arch.h>
 #include <cfg_hlp.h>
+#include <mbgutil.h>
 #include <timeutil.h>
 #include <mbgmutex.h>
 #include <mbgerror.h>
@@ -2920,26 +2925,30 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh );
  _MBG_API_ATTR void _MBG_API mbg_free_device_name_list( MBG_DEV_NAME_LIST_ENTRY *list ) ;
 
  /**
- * @brief Split an ::MBG_DEV_NAME into the 'type name' and 'serial number' components.
+ * @brief Split a string in ::MBG_DEV_NAME format its components.
+ *
+ * The components are the 'type name' and 'serial number' strings.
  *
  * See ::MBG_DEV_NAME for the possible formats of a device name.
  * If no @p dev_name is passed, the destination buffers are set
  * to empty strings.
  *
- * The complementary function ::snprint_dev_name can be used
- * to generate a device name string.
+ * One of the complementary functions ::mbg_create_dev_name or
+ * ::mbg_create_dev_name_from_dev_info can be used to generate
+ * a device name string.
  *
- * @param[in]   dev_name        The ::MBG_DEV_NAME string to be split up.
+ * @param[in]   dev_name        The string in ::MBG_DEV_NAME format to be split up.
  * @param[out]  type_name       Output buffer for the type name part, e.g. a ::PCPS_CLOCK_NAME.
  * @param[in]   type_name_size  Size of the output buffer for the type name string.
  * @param[out]  sernum          Output buffer for the sernum part, e.g. a ::PCPS_SN_STR.
  * @param[in]   sernum_size     Size of the output buffer for the sernum string.
  *
- * @see ::snprint_dev_name
+ * @see ::mbg_create_dev_name
+ * @see ::mbg_create_dev_name_from_dev_info
  * @see ::MBG_DEV_NAME
  * @see ::MBG_DEV_NAME_FMT
  */
- _MBG_API_ATTR void _MBG_API mbg_split_dev_name( const MBG_DEV_NAME dev_name, char *type_name, size_t type_name_size, char *sernum, size_t sernum_size ) ;
+ _MBG_API_ATTR void _MBG_API mbg_split_dev_name( const char *dev_name, char *type_name, size_t type_name_size, char *sernum, size_t sernum_size ) ;
 
  /**
  * @brief Return a handle to a device with a particular device name.
@@ -2951,7 +2960,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh );
  *
  * For details and similar functions see  @ref mbgdevio_open_fncs.
  *
- * @param[in]  srch_name       String with the ::MBG_DEV_NAME of a device to be opened.
+ * @param[in]  srch_name       String in ::MBG_DEV_NAME format of a device to be opened.
  * @param[in]  selection_mode  One of the ::MBG_MATCH_MODES.
  *
  * @return A valid device handle on success, else ::MBG_INVALID_DEV_HANDLE.
@@ -2962,7 +2971,7 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh );
  * @see ::MBG_DEV_NAME
  * @see ::MBG_MATCH_MODES
  */
- _MBG_API_ATTR MBG_DEV_HANDLE _MBG_API mbg_open_device_by_name( const MBG_DEV_NAME srch_name, int selection_mode ) ;
+ _MBG_API_ATTR MBG_DEV_HANDLE _MBG_API mbg_open_device_by_name( const char *srch_name, int selection_mode ) ;
 
  /**
  * @brief Close a device handle and set the handle value to ::MBG_INVALID_DEV_HANDLE.
@@ -5698,6 +5707,84 @@ typedef int _MBG_API MBG_CHK_SUPP_FNC( MBG_DEV_HANDLE dh );
 /* ----- function prototypes end ----- */
 
 
+
+/*HDR*/
+/**
+ * @brief Create a string with a unique device name.
+ *
+ * The device name is composed of the type name of the device,
+ * and its serial number which is appended after an underscore '_'.
+ * So the string buffer is typically an ::MBG_DEV_NAME.
+ * See ::MBG_DEV_NAME for the possible formats of a device name.
+ *
+ * A more specific version of this function is
+ * ::mbg_create_dev_name_from_dev_info.
+ *
+ * The complementary function ::mbg_split_dev_name can be used
+ * to split an ::MBG_DEV_NAME into its components.
+ *
+ * @param[out]  s         Pointer to the output buffer for the string.
+ * @param[in]   max_len   Size of the output buffer.
+ * @param[in]   type_str  Type name string.
+ * @param[in]   sn_str    Serial number string.
+ *
+ * @return The number of characters written to the output buffer,
+ *         except the terminating 0.
+ *
+ * @see ::mbg_create_dev_name_from_dev_info
+ * @see ::mbg_split_dev_name
+ * @see ::MBG_DEV_NAME
+ */
+static __mbg_inline
+int mbg_create_dev_name( char *s, size_t max_len,
+                         const char *type_str, const char *sn_str )
+{
+  int n = mbg_snprintf( s, max_len, MBG_DEV_NAME_FMT, type_str, sn_str );
+
+  return n;
+
+}  // mbg_create_dev_name
+
+
+
+/*HDR*/
+/**
+ * @brief Create a string with a unique device name from a PCPS_DEV structure.
+ *
+ * The device name is composed of the type name of the device,
+ * and its serial number which is appended after an underscore '_'.
+ * So the string buffer is typically an ::MBG_DEV_NAME.
+ * See ::MBG_DEV_NAME for the possible formats of a device name.
+ *
+ * A more versatile version of this function is ::mbg_create_dev_name.
+ *
+ * The complementary function ::mbg_split_dev_name can be used
+ * to split an ::MBG_DEV_NAME into its components.
+ *
+ * @param[out]  s        Pointer to the output buffer for the string.
+ * @param[in]   max_len  Size of the output buffer.
+ * @param[in]   p_dev    Pointer to a ::PCPS_DEV structure providing the required information.
+ *
+ * @return The number of characters written to the output buffer,
+ *         except the terminating 0.
+ *
+ * @see ::mbg_create_dev_name
+ * @see ::mbg_split_dev_name
+ * @see ::MBG_DEV_NAME
+ */
+static __mbg_inline
+int mbg_create_dev_name_from_dev_info( char *s, size_t max_len,
+                                       const PCPS_DEV *p_dev )
+{
+  int n = mbg_create_dev_name( s, max_len, _pcps_type_name( p_dev ),
+                               _pcps_sernum( p_dev ) );
+
+  return n;
+
+}  // mbg_create_dev_name_from_dev_info
+
+
+
 #if defined( MBG_TGT_WIN32 )
 
   /**
diff --git a/mbglib/common/pcpsdev.h b/mbglib/common/pcpsdev.h
index 5727b24..9fee496 100644
--- a/mbglib/common/pcpsdev.h
+++ b/mbglib/common/pcpsdev.h
@@ -1,7 +1,7 @@
 
 /**************************************************************************
  *
- *  $Id: pcpsdev.h 1.67 2022/03/30 15:35:49Z martin.burnicki REL_M $
+ *  $Id: pcpsdev.h 1.68 2022/04/27 15:07:26Z martin.burnicki REL_M $
  *
  *  Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany
  *
@@ -17,7 +17,11 @@
  *
  * -----------------------------------------------------------------------
  *  $Log: pcpsdev.h $
- *  Revision 1.67  2022/03/30 15:35:49Z  martin.burnicki
+ *  Revision 1.68  2022/04/27 15:07:26Z  martin.burnicki
+ *  Changed the definition of MBG_DEV_NAME in a way that it can now
+ *  take up a name based on RECEIVER_INFO::model_name.
+ *  Updated some doxygen comments accordingly.
+ *  Revision 1.67  2022/03/30 15:35:49  martin.burnicki
  *  New inline function setup_default_receiver_info() which is used to
  *  set up a RECEIVER_INFO structure for devices that don't provide one,
  *  and also copies the device name into the model_name field.
@@ -1631,22 +1635,34 @@ void setup_hr_time_cycles_from_timestamp_cycles( PCPS_HR_TIME_CYCLES *p_ht_c,
 /**
  * @brief A string buffer for a unique device ID.
  *
- * The unique ID is made up of the device model name
- * and its serial number, i.e. [model_name]_[serial_number]
- * E.g.: "GPS170PCI_028210040670"
+ * Originally, the unique ID was made up of the basic device model name
+ * and the serial number of the device, i.e. [model_name]_[serial_number],
+ * e.g. "GPS170PCI_028210040670".
  *
- * @see ::snprint_dev_name
+ * However, starting with some versions of TCR180PEX and TCR180USB,
+ * there are device variants that are identified by an extension of
+ * the basic name, e.g. "TCR180PEX-EL", which is stored in the
+ * ::RECEIVER_INFO::model_name field, which is longer than the
+ * ::PCPS_DEV_TYPE::name field used originally.
+ *
+ * It is thus possible to create a unique name for a device from the
+ * short basic name or from the longer model name, plus the serial number,
+ * so the size of this buffer has been expanded accordingly.
+ *
+ * @see ::mbg_create_dev_name
+ * @see ::mbg_create_dev_name_from_dev_info
  * @see ::MBG_DEV_NAME_FMT
  */
-typedef char MBG_DEV_NAME[PCPS_CLOCK_NAME_SZ + PCPS_SN_SIZE + 1];
+typedef char MBG_DEV_NAME[GPS_ID_STR_SIZE + PCPS_SN_SIZE + 1];
 
 
 
 /**
  * @brief A string format specifier for ::MBG_DEV_NAME.
  *
- * @see ::snprint_dev_name
- * @see ::MBG_DEV_NAME_FMT
+ * @see ::mbg_create_dev_name
+ * @see ::mbg_create_dev_name_from_dev_info
+ * @see ::MBG_DEV_NAME
  */
 #define MBG_DEV_NAME_FMT  "%s_%s"
 
diff --git a/mbglib/win32/mbgsvcio.h b/mbglib/win32/mbgsvcio.h
index ab3b3a7..850426a 100644
--- a/mbglib/win32/mbgsvcio.h
+++ b/mbglib/win32/mbgsvcio.h
@@ -1,7 +1,7 @@
 
 /**************************************************************************
  *
- *  $Id: mbgsvcio.h 1.19 2020/06/22 13:08:11Z martin.burnicki REL_M $
+ *  $Id: mbgsvcio.h 1.20 2022/04/20 19:40:28Z martin.burnicki REL_M $
  *
  *  Copyright (c) Meinberg Funkuhren, Bad Pyrmont, Germany
  *
@@ -10,6 +10,8 @@
  *
  * -----------------------------------------------------------------------
  *  $Log: mbgsvcio.h $
+ *  Revision 1.20  2022/04/20 19:40:28Z  martin.burnicki
+ *  Fixed some doxygen comments.
  *  Revision 1.19  2020/06/22 13:08:11Z  martin.burnicki
  *  FT_DWL::dwl is now an int64_t instead of an uint64_t.
  *  REF_TIME was renamed to FT_DWL_EX.
@@ -88,7 +90,7 @@
 #define MBGSVCIO_COMPAT_VERSION  0x0200
 
 
-#define USE_SERIAL_XHRT    0  // FIXME should be 0 by default // not fully implemented/tested
+#define USE_SERIAL_XHRT    0  // FIXME Should be 0 by default // not fully implemented/tested.
 
 
 #ifdef __cplusplus
@@ -96,7 +98,7 @@ extern "C" {
 #endif
 
 /**
- * @brief A union used to access a FILETIME as 64 bit number
+ * @brief A union used to access a FILETIME as 64 bit number.
  *
  * @note using this union may be tricky. Even though no problems
  * have been observed, yet, the MS docs clearly say there may be
@@ -106,21 +108,21 @@ extern "C" {
  */
 typedef union
 {
-  FILETIME ft;   ///< FILETIME structure as provided by the Windows API
-  int64_t dwl;   ///< used to access as single 64 bit number
+  FILETIME ft;   ///< @a FILETIME structure as provided by the Windows API.
+  int64_t dwl;   ///< Used to access as single 64 bit number
 
 } FT_DWL;
 
 
 
 /**
- * @brief A timestamp in Windows format, plus %UTC offset and clock status
+ * @brief A timestamp in Windows format, plus %UTC offset and clock status.
  */
 typedef struct
 {
-  FT_DWL ftdwl;               ///< time stamp, based on %UTC
-  int32_t utc_offs;           ///< %UTC offset in [sec]
-  PCPS_TIME_STATUS_X status;  ///< extended status, see ::PCPS_TIME_STATUS_X
+  FT_DWL ftdwl;               ///< Time stamp, based on %UTC.
+  int32_t utc_offs;           ///< %UTC offset in [sec].
+  PCPS_TIME_STATUS_X status;  ///< Extended status, see ::PCPS_TIME_STATUS_X.
 
 } FT_DWL_EX;
 
@@ -139,27 +141,27 @@ typedef struct
 
 
 /**
- * @brief Error information retrieved from the time adjustment service
+ * @brief Error information retrieved from the time adjustment service.
  */
 typedef struct
 {
-  uint32_t code;       ///< error/status code, see ::ERR_INFO_CODES
-  FT_DWL_EX time;  ///< clock's time and status when ::code was updated
+  uint32_t code;   ///< Error/status code, see ::ERR_INFO_CODES.
+  FT_DWL_EX time;  ///< Time and status of the clock when #code was updated.
 
 } ERR_INFO;
 
 
 /**
- * @brief Codes used with ::ERR_INFO::code
+ * @brief Codes used with ::ERR_INFO::code.
  */
 enum ERR_INFO_CODES
 {
-  MBG_SVC_NO_ERROR,              ///< No current error condition
-  MBG_SVC_ERR_OPEN_CLOCK_DEV,    ///< Failed to open clock device
-  MBG_SVC_ERR_OPEN_SERIAL_PORT,  ///< Failed to open serial port
-  MBG_SVC_ERR_SAME_REF_TIME,     ///< Clock device always returns same time (hardware failure)
-  MBG_SVC_ERR_REF_TIME_STEP,     ///< Time on the clock device has jumped, service stopped disciplining system time
-  N_MBG_SVC_ERR_CODE             ///< the number of known codes 
+  MBG_SVC_NO_ERROR,              ///< No current error condition.
+  MBG_SVC_ERR_OPEN_CLOCK_DEV,    ///< Failed to open clock device.
+  MBG_SVC_ERR_OPEN_SERIAL_PORT,  ///< Failed to open serial port.
+  MBG_SVC_ERR_SAME_REF_TIME,     ///< Clock device always returns same time (hardware failure).
+  MBG_SVC_ERR_REF_TIME_STEP,     ///< Time on the clock device has jumped, service stopped disciplining system time.
+  N_MBG_SVC_ERR_CODE             ///< The number of known codes.
 };
 
 
@@ -212,9 +214,9 @@ enum ERR_INFO_CODES
  _MBG_API_ATTR int _MBG_API mbg_time_adjustment_active( void ) ;
 
  /**
- * @brief Read the ::ERROR_INFO structure from the Meinberg time adjustment service
+ * @brief Read the ::ERR_INFO structure from the Meinberg time adjustment service
  *
- * @param[out]  p  Pointer to an ::ERROR_INFO structure to be filled on success
+ * @param[out]  p  Pointer to an ::ERR_INFO structure to be filled on success
  * 
  * @return ::MBG_SUCCESS on success, else one of the @ref MBG_ERROR_CODES
  */