[core] prepare api for ecal6 (#1399)

deprecate all functions that will be finally removed in eCAL6

cpack/innosetup.cmake

@@ -29,4 +29,4 @@ else()
     COMMAND "${ISSC_PATH}" "${CPACK_TOPLEVEL_DIRECTORY}/innosetup/ecal_setup.iss"
     WORKING_DIRECTORY "${CPACK_TOPLEVEL_DIRECTORY}/innosetup"
   )
-endif()
+endif()

ecal/core/include/ecal/cimpl/ecal_callback_cimpl.h

@@ -34,7 +34,7 @@ enum eCAL_Subscriber_Event
   sub_event_connected         = 1,
   sub_event_disconnected      = 2,
   sub_event_dropped           = 3,
-  sub_event_timeout           = 4,
+  sub_event_timeout           = 4,  //!< deprecated, will be removed in future eCAL versions
   sub_event_corrupted         = 5,
   sub_event_update_connection = 6,
 };
@@ -106,25 +106,31 @@ struct SReceiveCallbackDataC
 **/
 struct SPubEventCallbackDataC
 {
-  enum eCAL_Publisher_Event  type;  //!< event type
-  long long                  time;  //!< event time stamp
-  long long                  clock; //!< event clock
-  const char*                tid;   //!< topic id of the connected subscriber                     (for pub_event_update_connection only)
-  const char*                ttype; //!< topic type information of the connected subscriber       (for pub_event_update_connection only)
-  const char*                tdesc; //!< topic descriptor information of the connected subscriber (for pub_event_update_connection only)
+  enum eCAL_Publisher_Event  type;         //!< event type
+  long long                  time;         //!< event time stamp
+  long long                  clock;        //!< event clock
+  const char*                tid;          //!< topic id of the connected subscriber                          (for pub_event_update_connection only)
+  const char*                tname;        //!< topic type name of the connected subscriber                   (for pub_event_update_connection only)
+  const char*                tencoding;    //!< topic type encoding of the connected subscriber               (for pub_event_update_connection only)
+  const char*                tdesc;        //!< topic type descriptor information of the connected subscriber (for pub_event_update_connection only)
+
+  const char*                ttype;        //!< deprecated, please use new tname + tencoding fields
 };
 
 /**
  * @brief eCAL subscriber event callback struct (C variant).
 **/
 struct SSubEventCallbackDataC
 {
-  enum eCAL_Subscriber_Event type;  //!< event type
-  long long                  time;  //!< event time stamp
-  long long                  clock; //!< event clock
-  const char*                tid;   //!< topic id of the connected publisher                     (for sub_event_update_connection only)
-  const char*                ttype; //!< topic type information of the connected publisher       (for sub_event_update_connection only)
-  const char*                tdesc; //!< topic descriptor information of the connected publisher (for sub_event_update_connection only)
+  enum eCAL_Subscriber_Event type;         //!< event type
+  long long                  time;         //!< event time stamp
+  long long                  clock;        //!< event clock
+  const char*                tid;          //!< topic id of the connected publisher                          (for sub_event_update_connection only)
+  const char*                tname;        //!< topic type name of the connected publisher                   (for sub_event_update_connection only)
+  const char*                tencoding;    //!< topic type encoding of the connected publisher               (for sub_event_update_connection only)
+  const char*                tdesc;        //!< topic type descriptor information of the connected publisher (for sub_event_update_connection only)
+
+  const char*                ttype;        //!< deprecated, please use new tname + tencoding fields
 };
 
 /**

ecal/core/include/ecal/cimpl/ecal_event_cimpl.h

@@ -19,7 +19,7 @@
 
 /**
  * @file   ecal_event_cimpl.h
- * @brief  eCAL event c interface
+ * @brief  eCAL event c interface (deprecated, will be removed in future eCAL versions)
 **/
 
 #ifndef ecal_event_cimpl_h_included
@@ -34,49 +34,54 @@ extern "C"
 #endif /*__cplusplus*/
   /**
    * @brief Open a named or unnamed event.
+   * @deprecated Will be removed in future eCAL versions.
    *
    * @param  event_name_  Event name ("" == unnamed).
    *
    * @return  Handle to opened event or NULL if failed.
   **/
-  ECALC_API ECAL_HANDLE eCAL_Event_gOpenEvent(const char* event_name_);
+  ECALC_API_DEPRECATED ECAL_HANDLE eCAL_Event_gOpenEvent(const char* event_name_);
 
   /**
    * @brief Close an event.
+   * @deprecated Will be removed in future eCAL versions.
    *
    * @param handle_  Event handle.
    *
    * @return  None zero if succeeded.
   **/
-  ECALC_API int eCAL_Event_gCloseEvent(ECAL_HANDLE handle_);
+  ECALC_API_DEPRECATED int eCAL_Event_gCloseEvent(ECAL_HANDLE handle_);
 
   /**
    * @brief Set an event active.
+   * @deprecated Will be removed in future eCAL versions.
    *
    * @param handle_  Event handle.
    *
    * @return  None zero if succeeded.
   **/
-  ECALC_API int eCAL_Event_gSetEvent(ECAL_HANDLE handle_);
+  ECALC_API_DEPRECATED int eCAL_Event_gSetEvent(ECAL_HANDLE handle_);
 
   /**
    * @brief Wait for an event with timeout.
+   * @deprecated Will be removed in future eCAL versions.
    *
    * @param handle_   Event handle.
    * @param timeout_  Timeout in ms (-1 == infinite).
    *
    * @return  None zero if succeeded.
   **/
-  ECALC_API int eCAL_Event_gWaitForEvent(ECAL_HANDLE handle_, long timeout_);
+  ECALC_API_DEPRECATED int eCAL_Event_gWaitForEvent(ECAL_HANDLE handle_, long timeout_);
 
   /**
    * @brief Check whether an event is valid or not.
+   * @deprecated Will be removed in future eCAL versions.
    *
    * @param handle_  Event handle.
    *
    * @return  None zero if event is valid.
   **/
-  ECALC_API int eCAL_Event_gEventIsValid(ECAL_HANDLE handle_);
+  ECALC_API_DEPRECATED int eCAL_Event_gEventIsValid(ECAL_HANDLE handle_);
 #ifdef __cplusplus
 }
 #endif /*__cplusplus*/

ecal/core/include/ecal/cimpl/ecal_init_cimpl.h

@@ -31,7 +31,7 @@
 #define eCAL_Init_Monitoring  0x08                          /*!< Initialize Monitoring API           */
 #define eCAL_Init_Logging     0x10                          /*!< Initialize Logging API              */
 #define eCAL_Init_TimeSync    0x20                          /*!< Initialize Time API                 */
-#define eCAL_Init_RPC         0x40                          /*!< Initialize RPC API                  */
+#define eCAL_Init_RPC         0x40                          /*!< deprecated, will be removed in future eCAL versions */
 #define eCAL_Init_ProcessReg  0x80                          /*!< Initialize Process Registration API */
 
 #define eCAL_Init_All        (eCAL_Init_Publisher  \

ecal/core/include/ecal/cimpl/ecal_log_cimpl.h

@@ -56,25 +56,29 @@ extern "C"
 
   /**
    * @brief Mark the start of the user core process. 
+   * @deprecated Will be removed in future eCAL versions.
   **/
-  ECALC_API void eCAL_Logging_StartCoreTimer();
+  ECALC_API_DEPRECATED void eCAL_Logging_StartCoreTimer();
 
   /**
    * @brief Mark the stop of the user core process. 
+   * @deprecated Will be removed in future eCAL versions.
   **/
-  ECALC_API void eCAL_Logging_StopCoreTimer();
+  ECALC_API_DEPRECATED void eCAL_Logging_StopCoreTimer();
 
   /**
    * @brief Set the current measured core time in s (for user implemented measuring). 
+   * @deprecated Will be removed in future eCAL versions.
    *
    * @param time_  The core time.
   **/
-  ECALC_API void eCAL_Logging_SetCoreTime(double time_);
+  ECALC_API_DEPRECATED void eCAL_Logging_SetCoreTime(double time_);
 
   /**
    * @brief Returns the current measured core time in s. 
+   * @deprecated Will be removed in future eCAL versions.
   **/
-  ECALC_API double eCAL_Logging_GetCoreTime();
+  ECALC_API_DEPRECATED double eCAL_Logging_GetCoreTime();
 #ifdef __cplusplus
 }
 #endif /*__cplusplus*/

ecal/core/include/ecal/cimpl/ecal_process_cimpl.h

@@ -52,10 +52,11 @@ extern "C"
 
   /**
    * @brief  Get unique host id.
+   * @deprecated Will be removed in future eCAL versions.
    *
    * @return  The host id.
   **/
-  ECALC_API int eCAL_Process_GetHostID();
+  ECALC_API_DEPRECATED int eCAL_Process_GetHostID();
 
   /**
    * @brief  Get process unit name (defined with eCAL_Initialize). 
@@ -118,55 +119,61 @@ extern "C"
 
   /**
    * @brief  Get CPU usage of current process. 
+   * @deprecated Will be removed in future eCAL versions.
    *
    * @return  The CPU usage in percent. 
   **/
-  ECALC_API float eCAL_Process_GetProcessCpuUsage();
+  ECALC_API_DEPRECATED float eCAL_Process_GetProcessCpuUsage();
 
   /**
    * @brief  Get memory usage of current process. 
+   * @deprecated Will be removed in future eCAL versions.
    *
    * @return  The memory usage in bytes. 
   **/
-  ECALC_API unsigned long eCAL_Process_GetProcessMemory();
+  ECALC_API_DEPRECATED unsigned long eCAL_Process_GetProcessMemory();
 
   /**
-  * @deprecated  Use the function eCAL_Process_GetWClock() instead
+   * @deprecated Will be removed in future eCAL versions.
   **/
-  ECALC_API long long eCAL_Process_GetSClock();
+  ECALC_API_DEPRECATED long long eCAL_Process_GetSClock();
 
   /**
-  * @deprecated  Use the function eCAL_Process_GetWBytes() instead
+   * @deprecated Will be removed in future eCAL versions.
   **/
-  ECALC_API long long eCAL_Process_GetSBytes();
+  ECALC_API_DEPRECATED long long eCAL_Process_GetSBytes();
 
   /**
    * @brief  Get the write clock of the current process. 
+   * @deprecated Will be removed in future eCAL versions.
    *
    * @return  The message write count per second. 
   **/
-  ECALC_API long long eCAL_Process_GetWClock();
+  ECALC_API_DEPRECATED long long eCAL_Process_GetWClock();
 
   /**
    * @brief  Get the write bytes of the current process. 
+   * @deprecated Will be removed in future eCAL versions.
    *
    * @return  The message write bytes per second. 
   **/
-  ECALC_API long long eCAL_Process_GetWBytes();
+  ECALC_API_DEPRECATED long long eCAL_Process_GetWBytes();
 
   /**
    * @brief  Get the read clock of the current process. 
+   * @deprecated Will be removed in future eCAL versions.
    *
    * @return  The message read count per second. 
   **/
-  ECALC_API long long eCAL_Process_GetRClock();
+  ECALC_API_DEPRECATED long long eCAL_Process_GetRClock();
 
   /**
    * @brief  Get the read bytes of the current process. 
+   * @deprecated Will be removed in future eCAL versions.
    *
    * @return  The message read bytes per second. 
   **/
-  ECALC_API long long eCAL_Process_GetRBytes();
+  ECALC_API_DEPRECATED long long eCAL_Process_GetRBytes();
 
   /**
    * @brief  Set process state info. 

ecal/core/include/ecal/cimpl/ecal_proto_dyn_json_subscriber_cimpl.h

@@ -19,7 +19,7 @@
 
 /**
  * @file   ecal_proto_dyn_json_subscriber_cimpl.h
- * @brief  eCAL subscriber c interface
+ * @brief  eCAL subscriber c interface (deprecated, will be removed in future eCAL versions)
 **/
 
 #ifndef ecal_proto_dyn_json_subscriber_cimpl_h_included
@@ -36,37 +36,39 @@ extern "C"
 #endif /*__cplusplus*/
   /**
    * @brief Create a subscriber. 
+   * @deprecated Will be removed in future eCAL versions.
    *
    * @param topic_name_  Unique topic name. 
    *
    * @return  Handle to created subscriber or NULL if failed.
   **/
-  ECALC_API ECAL_HANDLE eCAL_Proto_Dyn_JSON_Sub_Create(const char* topic_name_);
+  ECALC_API_DEPRECATED ECAL_HANDLE eCAL_Proto_Dyn_JSON_Sub_Create(const char* topic_name_);
 
   /**
    * @brief Destroy a subscriber. 
+   * @deprecated Will be removed in future eCAL versions.
    *
    * @param handle_  Subscriber handle. 
    *
    * @return  None zero if succeeded.
   **/
-  ECALC_API int eCAL_Proto_Dyn_JSON_Sub_Destroy(ECAL_HANDLE handle_);
+  ECALC_API_DEPRECATED int eCAL_Proto_Dyn_JSON_Sub_Destroy(ECAL_HANDLE handle_);
 
   /**
    * @brief Add callback function for incoming receives. 
-   * @since eCAL 5.10.0
+   * @deprecated Will be removed in future eCAL versions.
    *
    * @param handle_    Subscriber handle. 
    * @param callback_  The callback function to add.
    * @param par_       User defined context that will be forwarded to the callback function.  
    *
    * @return  None zero if succeeded.
   **/
-  ECALC_API int eCAL_Proto_Dyn_JSON_Sub_AddReceiveCallback(ECAL_HANDLE handle_, ReceiveCallbackCT callback_, void* par_);
+  ECALC_API_DEPRECATED int eCAL_Proto_Dyn_JSON_Sub_AddReceiveCallback(ECAL_HANDLE handle_, ReceiveCallbackCT callback_, void* par_);
 
   /**
-   * @deprecated Please use eCAL_Proto_Dyn_JSON_Sub_AddReceiveCallback instead
    * @brief Add callback function for incoming receives.
+   * @deprecated Will be removed in future eCAL versions.
    *
    * @param handle_    Subscriber handle.
    * @param callback_  The callback function to add.
@@ -78,12 +80,13 @@ extern "C"
 
   /**
    * @brief Remove callback function for incoming receives. 
+   * @deprecated Will be removed in future eCAL versions.
    *
    * @param  handle_  Subscriber handle. 
    *
    * @return  None zero if succeeded.
   **/
-  ECALC_API int eCAL_Proto_Dyn_JSON_Sub_RemReceiveCallback(ECAL_HANDLE handle_);
+  ECALC_API_DEPRECATED int eCAL_Proto_Dyn_JSON_Sub_RemReceiveCallback(ECAL_HANDLE handle_);
 
 #ifdef __cplusplus
 }

ecal/core/include/ecal/cimpl/ecal_publisher_cimpl.h

@@ -135,23 +135,25 @@ extern "C"
 
   /**
    * @brief Set publisher quality of service attributes.
+   * @deprecated Will be removed in future eCAL versions.
    *
    * @param handle_  Publisher handle.
    * @param qos_     Quality of service policies.
    *
    * @return  None zero if succeeded.
   **/
-  ECALC_API int eCAL_Pub_SetQOS(ECAL_HANDLE handle_, struct SWriterQOSC qos_);
+  ECALC_API_DEPRECATED int eCAL_Pub_SetQOS(ECAL_HANDLE handle_, struct SWriterQOSC qos_);
 
   /**
    * @brief Get publisher quality of service attributes.
+   * @deprecated Will be removed in future eCAL versions.
    *
    * @param handle_  Publisher handle.
    * @param qos_     Quality of service policies.
    *
    * @return  None zero if succeeded.
   **/
-  ECALC_API int eCAL_Pub_GetQOS(ECAL_HANDLE handle_, struct SWriterQOSC* qos_);
+  ECALC_API_DEPRECATED int eCAL_Pub_GetQOS(ECAL_HANDLE handle_, struct SWriterQOSC* qos_);
 
   /**
    * @brief Set publisher send mode for specific transport layer.
@@ -166,13 +168,14 @@ extern "C"
 
   /**
    * @brief Set publisher maximum transmit bandwidth for the udp layer.
+   * @deprecated Will be removed in future eCAL versions.
    *
    * @param handle_     Publisher handle.
    * @param bandwidth_  Maximum bandwidth in bytes/s (-1 == unlimited).
    *
    * @return  True if it succeeds, false if it fails.
   **/
-  ECALC_API int eCAL_Pub_SetMaxBandwidthUDP(ECAL_HANDLE handle_, long bandwidth_);
+  ECALC_API_DEPRECATED int eCAL_Pub_SetMaxBandwidthUDP(ECAL_HANDLE handle_, long bandwidth_);
 
   /**
    * @brief Set publisher maximum number of used shared memory buffers.