Merge pull request #33 from mac-can/development

Release candidate 1 for version 0.3.1
mac-can · Jun 10, 2024 · c4aa890 · c4aa890
2 parents e8ab458 + 194731e
commit c4aa890
Show file tree

Hide file tree

Showing 66 changed files with 7,692 additions and 1,649 deletions.
diff --git a/Deployment.md b/Deployment.md
@@ -30,9 +30,7 @@ _All rights reserved._
   - `$(PROJROOT)/Sources/Swift/CANAPI.swift`
   - `$(PROJROOT)/Libraries/CANAPI/Makefile`<sup>*</sup>
   - `$(PROJROOT)/Libraries/TouCAN/Makefile`<sup>*</sup>
-  - `$(PROJROOT)/Utilities/can_moni/Makefile`
   - `$(PROJROOT)/Utilities/can_moni/README.md`
-  - `$(PROJROOT)/Utilities/can_test/Makefile`
   - `$(PROJROOT)/Utilities/can_test/README.md`
 
   <sup>*</sup>_) Set variable_ `CURRENT_VERSION` _and_ `COMPATIBILITY_VERSION` _accordingly._
@@ -103,7 +101,7 @@ _All rights reserved._
 
 1. Click on `Draft a new release` in the [GitHub](https://github.com/mac-can/RusokuCAN) repo.
 2. Fill out all required fields:
-  - Tag version: e.g `v0.3` (cf. semantic versioning)
+  - Tag version: e.g `v0.3.1` (cf. semantic versioning)
   - Target: `main` (default branch)
   - Release title: e.g. `Release of January 19, 2038`
   - Change-log: list all major changes, e.g. from commit comments

diff --git a/Libraries/CANAPI/Makefile b/Libraries/CANAPI/Makefile
@@ -51,7 +51,7 @@ current_OS := $(patsubst MSYS%,MinGW,$(current_OS))
 
 MAJOR = 0
 MINOR = 3
-PATCH = 0
+PATCH = 1
 
 ifeq ($(PATCH),0)
 VERSION = $(MAJOR).$(MINOR)

diff --git a/Libraries/TouCAN/Makefile b/Libraries/TouCAN/Makefile
@@ -51,7 +51,7 @@ current_OS := $(patsubst MSYS%,MinGW,$(current_OS))
 
 MAJOR = 0
 MINOR = 3
-PATCH = 0
+PATCH = 1
 
 ifeq ($(PATCH),0)
 VERSION = $(MAJOR).$(MINOR)

diff --git a/Package.swift b/Package.swift
@@ -66,7 +66,7 @@ let package = Package(
                 CSetting.define("OPTION_TOUCAN_DYLIB=1"),
                 CSetting.define("OPTION_CANAPI_TOUCAN_DYLIB=0"),
                 CSetting.define("OPTION_CANAPI_DRIVER=1"),
-                CSetting.define("OPTION_CANAPI_RETVALS=1"),
+                CSetting.define("OPTION_CANAPI_RETVALS=0"),
                 CSetting.define("OPTION_CANAPI_COMPANIONS=1"),
                 CSetting.define("OPTION_MACCAN_LOGGER=0"),
                 CSetting.define("OPTION_MACCAN_MULTICHANNEL=0"),

diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
 ### macOS&reg; User-Space Driver for TouCAN USB Interfaces from Rusoku
 
-_Copyright &copy; 2020-2024 Uwe Vogt, UV Software, Berlin ([email protected])_
+_Copyright &copy; 2020-2024  Uwe Vogt, UV Software, Berlin ([email protected])_
 
 ![macOS Build](https://github.com/mac-can/RusokuCAN.dylib/actions/workflows/macos-build.yml/badge.svg)
 
@@ -131,13 +131,13 @@ Type `can_test --help` to display all program options.
 
 #### macOS Sonoma
 
-- macOS Sonoma (14.4.1) on a Mac mini (M1, 2020)
+- macOS Sonoma (14.5) on a Mac mini (M1, 2020)
 - Apple clang version 15.0.0 (clang-1500.3.9.4)
-- Xcode Version 15.3 (15E204a)
+- Xcode Version 15.4 (15F31d)
 
 #### macOS Monterey
 
-- macOS Monterey (12.7.4) on a MacBook Pro (2019)
+- macOS Monterey (12.7.5) on a MacBook Pro (2019)
 - Apple clang version 13.0.0 (clang-1300.0.29.30)
 - Xcode Version 13.2.1 (13C100)
 
@@ -153,16 +153,14 @@ For a list of known bugs and caveats see tab [Issues](https://github.com/mac-can
 
 ### CAN API V3 Reference
 
-A generic documentation of the CAN API V3 application programming interface can be found [here](https://uv-software.github.io/CANAPI-Docs/#/).
+A generic documentation of the CAN API V3 application programming interface can be found [here](https://uv-software.github.io/CANAPI-Docs).
 
 ### Dual-License
 
 Except where otherwise noted, this work is dual-licensed under the terms of the BSD 2-Clause "Simplified" License
 and under the terms of the GNU General Public License v3.0 (or any later version).
 You can choose between one of them if you use these portions of this work in whole or in part.
 
-`SPDX-License-Identifier: BSD-2-Clause OR GPL-3.0-or-later`
-
 ### Trademarks
 
 Mac and macOS are trademarks of Apple Inc., registered in the U.S. and other countries. \

diff --git a/Sources/CANAPI/.gitignore b/Sources/CANAPI/.gitignore
@@ -1,3 +1,8 @@
-.svn/
+.svn
 # we don't use the JSON files yet
 can_dev.?
+vanilla.?
+# other blacklisted files
+SerialCAN_Defines.h
+SocketCAN_Defines.h
+RocketCAN_Defines.h
diff --git a/Sources/CANAPI/CANAPI.h b/Sources/CANAPI/CANAPI.h
@@ -73,9 +73,9 @@
 ///              zero to compile your program with the CAN API source files or to
 ///              link your program with the static library at compile-time.
 ///
-/// \author      $Author: eris $
+/// \author      $Author: quaoar $
 //
-/// \version     $Rev: 1270 $
+/// \version     $Rev: 1294 $
 //
 /// \defgroup    can_api CAN Interface API, Version 3
 /// \{
@@ -191,7 +191,20 @@ class CANCPP CCanApi {
         char m_szVendorName[CANPROP_MAX_BUFFER_SIZE];  ///< vendor name at actual index in the vendor list
         char m_szVendorDllName[CANPROP_MAX_BUFFER_SIZE];  ///< file name of the DLL at actual index in the vendor list
     };
-    /// \brief       query library information of the first CAN API library in the
+    /// \brief       sets the search path for readings library informations from
+    ///              JSON files.
+    //
+    /// \note        The search path can only be set once, either by ths function
+    ///               or by the non-default constructor with a path argument.
+    //
+    /// \param[in]   path    - path name, or NULL for current working directory
+    //
+    /// \returns     true if the search path has been successfully set, or
+    ///              false on error.
+    //
+    static bool SetSearchPath(const char *path);
+
+    /// \brief       queries library information of the first CAN API library in the
     ///              list of vendors, if any.
     //
     /// \param[out]  info    - the library information of the first entry in the list
@@ -201,7 +214,7 @@ class CANCPP CCanApi {
     //
     static bool GetFirstLibrary(SLibraryInfo &info);
 
-    /// \brief       query library information of the next CAN API library in the
+    /// \brief       queries library information of the next CAN API library in the
     ///              list of vendors, if any.
     //
     /// \param[out]  info    - the library information of the next entry in the list
@@ -211,7 +224,7 @@ class CANCPP CCanApi {
     //
     static bool GetNextLibrary(SLibraryInfo &info);
 #endif
-    /// \brief       query channel information of the first CAN interface in the
+    /// \brief       queries channel information of the first CAN interface in the
     ///              list of CAN interfaces, if any.
     //
     /// \param[in]   library - library id of the CAN interface list, or -1 for all vendors
@@ -227,7 +240,7 @@ class CANCPP CCanApi {
     static bool GetFirstChannel(SChannelInfo &info, void *param = NULL);
 #endif
 
-    /// \brief       query channel information of the next CAN interface in the
+    /// \brief       queries channel information of the next CAN interface in the
     ///              list of CAN interfaces, if any.
     //
     /// \param[out]  info    - the channel information of the next entry in the list
@@ -464,8 +477,16 @@ class CANCPP CCanApi {
     //
     virtual char *GetFirmwareVersion() = 0;  // deprecated
 
-    /// \brief       retrieves version information of the CAN API V3 driver
-    ///              as a zero-terminated string.
+#if (OPTION_CANAPI_LIBRARY != 0)
+    /// \brief       retrieves version information of the CAN API V3 wrapper
+    ///              library as a zero-terminated string.
+    //
+    /// \returns     pointer to a zero-terminated string, or NULL on error.
+    //
+    virtual char *GetSoftwareVersion() = 0;  // deprecated
+#endif
+    /// \brief       retrieves version information of the CAN API V3 wrapper
+    ///              (or loader) library as a zero-terminated string.
     //
     /// \returns     pointer to a zero-terminated string, or NULL on error.
     //
@@ -515,4 +536,4 @@ class CANCPP CCanApi {
 /// \}
 #endif // CANAPI_H_INCLUDED
 /// \}
-// $Id: CANAPI.h 1270 2024-04-15 18:42:43Z eris $  Copyright (c) UV Software //
+// $Id: CANAPI.h 1294 2024-05-16 19:50:25Z quaoar $  Copyright (c) UV Software //
diff --git a/Sources/CANAPI/CANAPI_Defines.h b/Sources/CANAPI/CANAPI_Defines.h
@@ -49,9 +49,9 @@
  *
  *  @brief       CAN API V3 for generic CAN Interfaces - Definitions and Options
  *
- *  @author      $Author: eris $
+ *  @author      $Author: quaoar $
  *
- *  @version     $Rev: 1270 $
+ *  @version     $Rev: 1293 $
  *
  *  @addtogroup  can_api
  *  @{
@@ -79,23 +79,25 @@ extern "C" {
 
 /** @name  Library IDs
  *  @brief Unique IDs to identify a CAN API library (CAN API V1 compatible)
+ *  @note  These defines are still valid, but IDs are taken from JSON files.
  *  @{ */
 #define CANLIB_IXXAT_VCI        100     /**< IXXAT Virtual CAN interfaces */
 #define CANLIB_IXXAT_CAC        800     /**< IXXAT canAnalyzer/32 Client */
-#define CANLIB_PEAK_PCAN        200     /**< PEAK PCAN interfaces */
+#define CANLIB_PEAK_PCAN        200     /**< PEAK PCAN-Light interfaces */
 #define CANLIB_VECTOR_XL        300     /**< Vector XL-Driver library */
 #define CANLIB_PCANBASIC        400     /**< PEAK PCAN-Basic interfaces */
-#define CANLIB_RUSOKU_LT        500     /**< Rusuko TouCAN interfaces */
+#define CANLIB_RUSOKU_LT        500     /**< Rusoku TouCAN interfaces */
 #define CANLIB_KVASER_32        600     /**< Kvaser CANLIB (canlib32) */
 #define CANLIB_ROCKETCAN        700     /**< CAN-over-IP (RocketCAN) */
 #define CANLIB_SERIALCAN        900     /**< Serial-Line (SerialCAN) */
-#define CANLIB_SOCKETCAN        1000    /**< Linux CAN (SocketCAN) */
+#define CANLIB_SOCKETCAN        1000    /**< Linux-CAN (SocketCAN) */
 #define CANLIB_CANAPILIB        (-1)    /**< CAN API Main Library */
-/** @note  Peak's PCAN-Light DLL is outdated, so the library ID can be reused.
+/** @note  PCAN-Light is outdated, its ID is reused by macCAN-PeakCAN.
  *  @} */
 
 /** @name  Library Names
  *  @brief Filenames of the CAN API libraries (depending on the platform)
+ *  @note  Theses defines are outdated. DLL names are taken from JSON files.
  *  @{ */
 #if defined(__linux__)
  #define CANAPI_PLATFORM       "Linux"
@@ -154,9 +156,9 @@ extern "C" {
 #define CAN_API_WEBSITE        "www.uv-software.com"
 #define CAN_API_CONTACT        "[email protected]"
 #define CAN_API_LICENSE        "BSD-2-Clause OR GPL-3.0-or-later"
-#define CAN_API_COPYRIGHT      "Copyright (c) 2005-20%02u, UV Software, Berlin"
-#define CAN_API_HAZARD_NOTE    "Do not connect your CAN device to a real CAN network when using this program.\n" \
-                               "This can damage your application."
+#define CAN_API_COPYRIGHT      "Copyright (c) 2004-20%02u, UV Software, Berlin"
+#define CAN_API_HAZARD_NOTE    "If you connect your CAN device to a real CAN network when using this library,\n" \
+                               "you might damage your application."
 /** @} */
 
 

diff --git a/Sources/CANAPI/CANAPI_Types.h b/Sources/CANAPI/CANAPI_Types.h
@@ -49,9 +49,9 @@
  *
  *  @brief       CAN API V3 for generic CAN Interfaces - Data Types and Defines
  *
- *  @author      $Author: eris $
+ *  @author      $Author: quaoar $
  *
- *  @version     $Rev: 1270 $
+ *  @version     $Rev: 1286 $
  *
  *  @addtogroup  can_api
  *  @{
@@ -320,13 +320,13 @@ extern "C" {
 #define CANPROP_GET_PATCH_NO         2U /**< patch number of the library (uint8_t) */
 #define CANPROP_GET_BUILD_NO         3U /**< build number of the library (uint32_t) */
 #define CANPROP_GET_LIBRARY_ID       4U /**< library id of the library (int32_t) */
-#define CANPROP_GET_LIBRARY_VENDOR   5U /**< vendor name of the library (char[256]) */
-#define CANPROP_GET_LIBRARY_DLLNAME  6U /**< file name of the library DLL (char[256]) */
+#define CANPROP_GET_LIBRARY_VENDOR   5U /**< vendor name of the library (char[]) */
+#define CANPROP_GET_LIBRARY_DLLNAME  6U /**< file name of the library DLL (char[]) */
 #define CANPROP_GET_DEVICE_TYPE     10U /**< device type of the CAN interface (int32_t) */
-#define CANPROP_GET_DEVICE_NAME     11U /**< device name of the CAN interface (char[256]) */
-#define CANPROP_GET_DEVICE_VENDOR   12U /**< vendor name of the CAN interface (char[256]) */
-#define CANPROP_GET_DEVICE_DLLNAME  13U /**< file name of the CAN interface DLL (char[256]) */
-#define CANPROP_GET_DEVICE_PARAM    14U /**< device parameter of the CAN interface (char[256]) */
+#define CANPROP_GET_DEVICE_NAME     11U /**< device name of the CAN interface (char[]) */
+#define CANPROP_GET_DEVICE_VENDOR   12U /**< vendor name of the CAN interface (char[]) */
+#define CANPROP_GET_DEVICE_DLLNAME  13U /**< file name of the CAN interface DLL (char[]) */
+#define CANPROP_GET_DEVICE_PARAM    14U /**< device parameter of the CAN interface (char[]) */
 #define CANPROP_GET_OP_CAPABILITY   15U /**< supported operation modes of the CAN controller (uint8_t) */
 #define CANPROP_GET_OP_MODE         16U /**< active operation mode of the CAN controller (uint8_t) */
 #define CANPROP_GET_BITRATE         17U /**< active bit-rate of the CAN controller (can_bitrate_t) */
@@ -355,21 +355,21 @@ extern "C" {
 #define CANPROP_GET_BTR_INDEX       64U /**< bit-rate as CiA index (int32_t) */
 #define CANPROP_GET_BTR_VALUE       65U /**< bit-rate as struct (can_bitrate_t) */
 #define CANPROP_GET_BTR_SPEED       66U /**< bit-rate as bus speed (can_speed_t) */
-#define CANPROP_GET_BTR_STRING      67U /**< bit-rate as string (char[256]) */
+#define CANPROP_GET_BTR_STRING      67U /**< bit-rate as string (char[]) */
 #define CANPROP_GET_BTR_SJA1000     68U /**< bit-rate as SJA1000 register (uint16_t) */
 #define CANPROP_SET_BTR_INDEX       72U /**< set value for conversion form CiA index (int32_t) */
 #define CANPROP_SET_BTR_VALUE       73U /**< set value for conversion form struct (can_bitrate_t) */
 #define CANPROP_SET_BTR_SPEED       74U /**< set value for conversion form bus speed (can_speed_t) */
-#define CANPROP_SET_BTR_STRING      75U /**< set value for conversion form string (char[256]) */
+#define CANPROP_SET_BTR_STRING      75U /**< set value for conversion form string (char[]) */
 #define CANPROP_SET_BTR_SJA1000     76U /**< set value for conversion form SJA1000 register (uint16_t) */
 /* - -  build-in message formatter  - - - - - - - - - - - - - - - - - - */
-#define CANPROP_GET_MSG_STRING     128U /**< last received or sent message as formatted string (char[1024]) */
-#define CANPROP_GET_MSG_TIME       129U /**< time-stamp of last received or sent message (char[256]) */
-#define CANPROP_GET_MSG_ID         130U /**< identifier of last received or sent message (char[256]) */
-#define CANPROP_GET_MSG_DLC        131U /**< DLC/length of last received or sent message (char[256]) */
-#define CANPROP_GET_MSG_FLAGS      132U /**< flags of last received or sent message (char[256]) */
-#define CANPROP_GET_MSG_DATA       133U /**< data of last received or sent message (char[256]) */
-#define CANPROP_GET_MSG_ASCII      134U /**< data as ASCII of last received or sent message (char[256]) */
+#define CANPROP_GET_MSG_STRING     128U /**< last received or sent message as formatted string (char[]) */
+#define CANPROP_GET_MSG_TIME       129U /**< time-stamp of last received or sent message (char[]) */
+#define CANPROP_GET_MSG_ID         130U /**< identifier of last received or sent message (char[]) */
+#define CANPROP_GET_MSG_DLC        131U /**< DLC/length of last received or sent message (char[]) */
+#define CANPROP_GET_MSG_FLAGS      132U /**< flags of last received or sent message (char[]) */
+#define CANPROP_GET_MSG_DATA       133U /**< data of last received or sent message (char[]) */
+#define CANPROP_GET_MSG_ASCII      134U /**< data as ASCII of last received or sent message (char[]) */
 #define CANPROP_SET_MSG_FORMAT     144U /**< set message output format {DEFAULT, ...} (int) */
 #define CANPROP_SET_FMT_TIMESTAMP  145U /**< set formatter option: time-stamp {ZERO, ABS, REL} (int) */
 #define CANPROP_SET_FMT_TIEMUSEC   146U /**< set formatter option: time-stamp in usec {OFF, ON} (int) */
@@ -396,22 +396,23 @@ extern "C" {
 #define CANPROP_SET_FIRST_VENDOR   224U /**< set index to the first entry in the vendor list (NULL) */
 #define CANPROP_SET_NEXT_VENDOR    225U /**< set index to the next entry in the vendor list (NULL) */
 #define CANPROP_GET_VENDOR_ID      226U /**< get library id at actual index in the vendor list (int32_t) */
-#define CANPROP_GET_VENDOR_NAME    227U /**< get vendor name at actual index in the vendor list (char[256]) */
-#define CANPROP_GET_VENDOR_DLLNAME 228U /**< get file name of the DLL at actual index in the vendor list (char[256]) */
+#define CANPROP_GET_VENDOR_NAME    227U /**< get vendor name at actual index in the vendor list (char[]) */
+#define CANPROP_GET_VENDOR_DLLNAME 228U /**< get file name of the DLL at actual index in the vendor list (char[]) */
 #endif
 #define CANPROP_SET_FIRST_CHANNEL  240U /**< set index to the first entry in the interface list (int32_t or NULL) */
 #define CANPROP_SET_NEXT_CHANNEL   241U /**< set index to the next entry in the interface list (NULL) */
 #define CANPROP_GET_CHANNEL_NO     242U /**< get channel no. at actual index in the interface list (int32_t) */
-#define CANPROP_GET_CHANNEL_NAME   243U /**< get channel name at actual index in the interface list (char[256]) */
-#define CANPROP_GET_CHANNEL_DLLNAME 244U /**< get file name of the DLL at actual index in the interface list (char[256]) */
+#define CANPROP_GET_CHANNEL_NAME   243U /**< get channel name at actual index in the interface list (char[]) */
+#define CANPROP_GET_CHANNEL_DLLNAME 244U /**< get file name of the DLL at actual index in the interface list (char[]) */
 #define CANPROP_GET_CHANNEL_VENDOR_ID 245U /**< get library id at actual index in the interface list (int32_t) */
-#define CANPROP_GET_CHANNEL_VENDOR_NAME 246U /**< get vendor name at actual index in the interface list (char[256]) */
+#define CANPROP_GET_CHANNEL_VENDOR_NAME 246U /**< get vendor name at actual index in the interface list (char[]) */
 /* - -  search path for JSON files (for C++ wrapper classes)  - - - - - */
 #if (OPTION_CANAPI_LIBRARY != 0)
-#define CANPROP_SET_SEARCH_PATH    253U /**< set search path for interface configuration files (char[256]) */
+#define CANPROP_SET_SEARCH_PATH    253U /**< set search path for interface configuration files (char[]) */
+#define CANPROP_GET_SEARCH_PATH    254U /**< get search path for interface configuration files (char[]) */
 #endif
 /* - -  access to device handle (for C++ wrapper classes) - - - - - - - */
-#define CANPROP_GET_CPP_BACKDOOR   255U /**< get device handle (int32_t) */
+#define CANPROP_GET_CPP_BACKDOOR   255U /**< get device handle (int) */
 /* - -  access to vendor-specific properties  - - - - - - - - - - - - - */
 #define CANPROP_GET_VENDOR_PROP    256U /**< offset to get a vendor-specific property value (void*) */
 #define CANPROP_SET_VENDOR_PROP    512U /**< offset to set a vendor-specific property value (void*) */

diff --git a/Sources/CANAPI/README.md b/Sources/CANAPI/README.md
@@ -1,9 +1,9 @@
 ### CAN Interface API, Version 3
 
-_Copyright &copy; 2004-2024  Uwe Vogt, UV Software, Berlin ([email protected])_ \
+_Copyright &copy; 2004-2024 Uwe Vogt, UV Software, Berlin ([email protected])_ \
 _All rights reserved._
 
-Version $Rev: 1270 $
+Version $Rev: 1312 $
 
 # A CAN Interface Wrapper Specification
 
@@ -69,13 +69,17 @@ See header file `can_api.h` for a description of the provided functions.
 
 A generic documentation of the CAN API V3 application programming interface can be found [here](https://uv-software.github.io/CANAPI-Docs/#/).
 
+### vanilla-json
+
+The implementation is using [vanilla-json](https://github.com/uv-software/vanilla-json) to read CAN API wrapper configurations from JSON files.
+
+**vanilla-json** is a very simple JSON parser by UV&nbsp;Software written in C90, and it has the same dual-license model as CAN API V3; see below.
+
 ### Dual-License
 
 This work is dual-licensed under the terms of the BSD 2-Clause "Simplified" License and under the terms of the GNU General Public License v3.0 (or any later version).
 You can choose between one of them if you use this work in whole or in part.
 
-`SPDX-License-Identifier: BSD-2-Clause OR GPL-3.0-or-later`
-
 ### Contact
 
 E-Mail: mailto://[email protected] \