Preparing 5.0.0-rc3

greenrobot · greenrobot · commit fcac9a59c8e0 · 2025-11-26T14:25:38.000+01:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,8 +1,8 @@
 ObjectBox C and C++ API Changelog
 =================================
 
-5.0.0-rc (2025-09-30)
----------------------
+5.0.0-rc3 (2025-11-26)
+----------------------
 
 ### User-Specific Data Sync
 
@@ -12,22 +12,28 @@ ObjectBox C and C++ API Changelog
 
 ### New supported platform: Windows ARM64
 
-* Besides x86 and x64, ObjectBox now also supports Windows ARM64
+* Besides x86 and x64, ObjectBox for Windows now also supports ARM64
 * Use git tag `v5.0.0-rc2` for CMake (the arm64 libs were added to the 5.0.0-rc release in a later commit)
 
+### Sync
+
+* Sync clients may now provide certificate locations for SSL(TLS) connections
+
 ### Fixes
 
 * Fixed clearing 1:N backlinks for IDs larger than 32-bit (setting backlink ID to 0 on the "1" side)
 * In-memory with WAL file: improved error handling
 * Safeguard against undefined behavior by panicking in rare illegal usage patterns that are not recoverable.
   I.e. deleting a (write) transaction in a non-owner thread cannot be safely handled in any other way.
+* Various small improvements and updates under the hood.
 
 ### Examples
 
 * Make each example self-contained, you can e.g. copy an example's directory as a starting point for your own app
 * Add a convenient `build.sh` script to each example that works the same way across examples,
   e.g. `./build.sh run` to build and run the example in one step
 * Make sources more readable (refactorings, added additional comments)
+* The Task sync example moved to [ObjectBox Sync Examples](https://github.com/objectbox/objectbox-sync-examples)
 
 4.3.1 (2025-07-28)
 ------------------
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -55,7 +55,7 @@ else ()
 
     function(defineObjectBoxLib VARIANT)
         # Configuration updated for each release
-        set(DL_VERSION 5.0.0-rc)
+        set(DL_VERSION 5.0.0-rc3)
 
         # Platform detection and other setup
         set(DL_URL https://github.com/objectbox/objectbox-c/releases/download)
diff --git a/README.md b/README.md
@@ -18,7 +18,7 @@ box.put({.text = "Buy milk"});
 
 See [ObjectBox C and C++ docs](https://cpp.objectbox.io/) for API details.
 
-**Latest version: 5.0.0-rc** (2025-09-30).
+**Latest version: 5.0.0-rc3** (2025-11-26).
 See [changelog](CHANGELOG.md) for more details.
 
 ## Table of Contents:
diff --git a/download.sh b/download.sh
@@ -44,7 +44,7 @@ tty -s || quiet=true
 
 # Note: optional arguments like "--quiet" shifts argument positions in the case block above
 
-version=${1:-5.0.0-rc}
+version=${1:-5.0.0-rc3}
 os=${2:-$(uname)}
 arch=${3:-$(uname -m)}
 echo "Base config: OS ${os} and architecture ${arch}"
diff --git a/doxygen/Changelog.md b/doxygen/Changelog.md
@@ -3,28 +3,39 @@
 ObjectBox C and C++ API Changelog
 =================================
 
-5.0.0-rc (2025-09-30)
-------------------
+5.0.0-rc3 (2025-11-26)
+----------------------
 
 ### User-Specific Data Sync
 
 * Sync filters: define server-side filter expression to sync individual data for each sync user.
   This is also known as "user-specific data sync" and requires Sync clients version 5.0.
 * Client variables: clients may define key/value pairs that can be used in sync filters
 
+### New supported platform: Windows ARM64
+
+* Besides x86 and x64, ObjectBox for Windows now also supports ARM64
+* Use git tag `v5.0.0-rc2` for CMake (the arm64 libs were added to the 5.0.0-rc release in a later commit)
+
+### Sync
+
+* Sync clients may now provide certificate locations for SSL(TLS) connections
+
 ### Fixes
 
 * Fixed clearing 1:N backlinks for IDs larger than 32-bit (setting backlink ID to 0 on the "1" side)
 * In-memory with WAL file: improved error handling
 * Safeguard against undefined behavior by panicking in rare illegal usage patterns that are not recoverable.
   I.e. deleting a (write) transaction in a non-owner thread cannot be safely handled in any other way.
+* Various small improvements and updates under the hood.
 
 ### Examples
 
 * Make each example self-contained, you can e.g. copy an example's directory as a starting point for your own app
 * Add a convenient `build.sh` script to each example that works the same way across examples,
   e.g. `./build.sh run` to build and run the example in one step
 * Make sources more readable (refactorings, added additional comments)
+* The Task sync example moved to [ObjectBox Sync Examples](https://github.com/objectbox/objectbox-sync-examples)
 
 4.3.1 (2025-07-28)
 ------------------
diff --git a/doxygen/Doxyfile b/doxygen/Doxyfile
@@ -38,7 +38,7 @@ PROJECT_NAME           = "ObjectBox C and C++ API"
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = "5.0.0-rc"
+PROJECT_NUMBER         = "5.0.0-rc3"
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a
diff --git a/examples/c-tasks-lowlevel/CMakeLists.txt b/examples/c-tasks-lowlevel/CMakeLists.txt
@@ -17,7 +17,7 @@ if (NOT TARGET objectbox) # Using "if" in case a (potential) parent project alre
     FetchContent_Declare(
             objectbox
             GIT_REPOSITORY https://github.com/objectbox/objectbox-c.git
-            GIT_TAG v5.0.0-rc2 # For latest versions, check https://github.com/objectbox/objectbox-c/releases
+            GIT_TAG v5.0.0-rc3 # For latest versions, check https://github.com/objectbox/objectbox-c/releases
     )
     FetchContent_MakeAvailable(objectbox)
 
diff --git a/examples/c-tasks/CMakeLists.txt b/examples/c-tasks/CMakeLists.txt
@@ -17,7 +17,7 @@ if (NOT TARGET objectbox) # Using "if" in case a (potential) parent project alre
     FetchContent_Declare(
             objectbox
             GIT_REPOSITORY https://github.com/objectbox/objectbox-c.git
-            GIT_TAG v5.0.0-rc2 # For latest versions, check https://github.com/objectbox/objectbox-c/releases
+            GIT_TAG v5.0.0-rc3 # For latest versions, check https://github.com/objectbox/objectbox-c/releases
     )
     FetchContent_MakeAvailable(objectbox)
 
diff --git a/examples/tasks/CMakeLists.txt b/examples/tasks/CMakeLists.txt
@@ -17,7 +17,7 @@ if (NOT TARGET objectbox) # Using "if" in case a (potential) parent project alre
     FetchContent_Declare(
             objectbox
             GIT_REPOSITORY https://github.com/objectbox/objectbox-c.git
-            GIT_TAG v5.0.0-rc2 # For latest versions, check https://github.com/objectbox/objectbox-c/releases
+            GIT_TAG v5.0.0-rc3 # For latest versions, check https://github.com/objectbox/objectbox-c/releases
     )
     FetchContent_MakeAvailable(objectbox)
 
diff --git a/examples/vectorsearch-cities/CMakeLists.txt b/examples/vectorsearch-cities/CMakeLists.txt
@@ -17,7 +17,7 @@ if (NOT TARGET objectbox) # Using "if" in case a (potential) parent project alre
     FetchContent_Declare(
             objectbox
             GIT_REPOSITORY https://github.com/objectbox/objectbox-c.git
-            GIT_TAG v5.0.0-rc2 # For latest versions, check https://github.com/objectbox/objectbox-c/releases
+            GIT_TAG v5.0.0-rc3 # For latest versions, check https://github.com/objectbox/objectbox-c/releases
     )
     FetchContent_MakeAvailable(objectbox)
 
diff --git a/include/objectbox-sync.h b/include/objectbox-sync.h
@@ -190,14 +190,22 @@ typedef void OBX_sync_listener_msg_objects(void* arg, const OBX_sync_msg_objects
 /// Creates a sync client associated with the given store and sync server URL.
 /// This does not initiate any connection attempts yet: call obx_sync_start() to do so.
 /// Before obx_sync_start(), you must configure credentials via obx_sync_credentials.
-/// By default a sync client automatically receives updates from the server once login succeeded.
+/// By default, a sync client automatically receives updates from the server once login succeeded.
 /// To configure this differently, call obx_sync_request_updates_mode() with the wanted mode.
 OBX_C_API OBX_sync* obx_sync(OBX_store* store, const char* server_url);
 
-/// Creates a sync client associated with the given store and a list of sync server URL.
-/// For details, see obx_sync()
+/// Creates a sync client associated with the given store and a list of sync server URLs (minimum: one URL).
+/// Passing multiple URLs allows high availability and load balancing (i.e. using a ObjectBox Sync Server Cluster).
+/// A random URL is selected for each connection attempt.
+/// For general details, see obx_sync()
 OBX_C_API OBX_sync* obx_sync_urls(OBX_store* store, const char* server_urls[], size_t server_urls_count);
 
+/// Creates a sync client associated with the given store, sync server URLs and SSL certificate paths.
+/// Like obx_sync_urls(), but also allows to pass SSL certificate paths referring to the local file system.
+/// Example use cases are using self-signed certificates in a local development environment and custom CAs.
+OBX_C_API OBX_sync* obx_sync_certs(OBX_store* store, const char* server_urls[], size_t server_urls_count,
+                                   const char* cert_paths[], size_t cert_paths_count);
+
 /// Stops and closes (deletes) the sync client, freeing its resources.
 OBX_C_API obx_err obx_sync_close(OBX_sync* sync);
 
@@ -262,6 +270,7 @@ OBX_C_API obx_err obx_sync_max_messages_in_flight(OBX_sync* sync, int value);
 /// Triggers a reconnection attempt immediately.
 /// By default, an increasing backoff interval is used for reconnection attempts.
 /// But sometimes the user of this API has additional knowledge and can initiate a reconnection attempt sooner.
+/// @return OBX_SUCCESS if a reconnect could be triggered, OBX_NO_SUCCESS if not, or an error code in exceptional cases.
 OBX_C_API obx_err obx_sync_trigger_reconnect(OBX_sync* sync);
 
 /// Sets the interval in which the client sends "heartbeat" messages to the server, keeping the connection alive.
diff --git a/include/objectbox-sync.hpp b/include/objectbox-sync.hpp
@@ -289,16 +289,26 @@ class SyncClient : public Closable {
     using Guard = std::lock_guard<std::mutex>;
 
 public:
-    /// Creates a sync client associated with the given store and options.
+    /// Creates a sync client associated with the given store and options
+    /// (server URLs, credentials, optional certificate paths).
     /// This does not initiate any connection attempts yet: call start() to do so.
-    explicit SyncClient(Store& store, const std::vector<std::string>& serverUrls, const SyncCredentials& creds)
+    SyncClient(Store& store, const std::vector<std::string>& serverUrls, const SyncCredentials& creds,
+               const std::vector<std::string>& certPaths = {})
         : store_(store) {
         std::vector<const char*> urlPointers;  // Convert serverUrls to a vector of C strings for the C API
         urlPointers.reserve(serverUrls.size());
         for (const std::string& serverUrl : serverUrls) {
             urlPointers.emplace_back(serverUrl.c_str());
         }
-        cSync_ = obx_sync_urls(store.cPtr(), urlPointers.data(), urlPointers.size());
+
+        std::vector<const char*> certPointers;
+        certPointers.reserve(certPaths.size());
+        for (const std::string& certPath : certPaths) {
+            certPointers.emplace_back(certPath.c_str());
+        }
+
+        cSync_ = obx_sync_certs(store.cPtr(), urlPointers.data(), urlPointers.size(), certPointers.data(),
+                                certPointers.size());
 
         internal::checkPtrOrThrow(cSync_, "Could not initialize sync client");
         try {
@@ -309,13 +319,17 @@ class SyncClient : public Closable {
         }
     }
 
-    explicit SyncClient(Store& store, const std::string& serverUrl, const SyncCredentials& creds)
-        : SyncClient(store, std::vector<std::string>{serverUrl}, creds) {}
+    /// Creates a sync client associated with the given store and options
+    /// (server URL, credentials, optional certificate paths).
+    /// This does not initiate any connection attempts yet: call start() to do so.
+    SyncClient(Store& store, const std::string& serverUrl, const SyncCredentials& creds,
+               const std::vector<std::string>& certPaths = {})
+        : SyncClient(store, std::vector<std::string>{serverUrl}, creds, certPaths) {}
 
     /// Creates a sync client associated with the given store and options.
     /// This does not initiate any connection attempts yet: call start() to do so.
     /// @param cSync an initialized sync client. You must NOT call obx_sync_close() yourself anymore.
-    explicit SyncClient(Store& store, OBX_sync* cSync) : store_(store), cSync_(cSync) {
+    SyncClient(Store& store, OBX_sync* cSync) : store_(store), cSync_(cSync) {
         OBX_VERIFY_STATE(obx_has_feature(OBXFeature_Sync));
         OBX_VERIFY_ARGUMENT(cSync);
     }
@@ -434,7 +448,7 @@ class SyncClient : public Closable {
     /// Triggers a reconnection attempt immediately.
     /// By default, an increasing backoff interval is used for reconnection attempts.
     /// But sometimes the user of this API has additional knowledge and can initiate a reconnection attempt sooner.
-    bool triggerReconnect() { return internal::checkSuccessOrThrow(obx_sync_trigger_reconnect(cPtr())); }
+    bool triggerReconnect() const { return internal::checkSuccessOrThrow(obx_sync_trigger_reconnect(cPtr())); }
 
     /// Sets the interval in which the client sends "heartbeat" messages to the server, keeping the connection alive.
     /// To detect disconnects early on the client side, you can also use heartbeats with a smaller interval.
@@ -492,7 +506,7 @@ class SyncClient : public Closable {
     ///       While this will still be fast, avoid calling this function excessively.
     ///       2) the result follows transaction view semantics, thus it may not always match the actual value.
     /// @return the number of messages in the outgoing queue
-    uint64_t outgoingMessageCount(uint64_t limit = 0) {
+    uint64_t outgoingMessageCount(uint64_t limit = 0) const {
         uint64_t result;
         internal::checkErrOrThrow(obx_sync_outgoing_message_count(cPtr(), limit, &result));
         return result;
@@ -970,39 +984,39 @@ class SyncServer : public Closable {
     void stop() { internal::checkErrOrThrow(obx_sync_server_stop(cPtr())); }
 
     /// Returns if this sync server is running
-    bool isRunning() { return obx_sync_server_running(cPtr()); }
+    bool isRunning() const { return obx_sync_server_running(cPtr()); }
 
     /// Returns a URL this server is listening on, including the bound port (see port().
-    std::string url() {
+    std::string url() const {
         return internal::checkedPtrOrThrow(obx_sync_server_url(cPtr()), "Can't get SyncServer bound URL");
     }
 
     /// Returns a port this server listens on. This is especially useful if the bindUri given to the constructor
     /// specified "0" port (i.e. automatic assignment).
-    uint16_t port() {
+    uint16_t port() const {
         uint16_t result = obx_sync_server_port(cPtr());
         if (result == 0) internal::throwLastError();
         return result;
     }
 
     /// Returns the number of clients connected to this server.
-    uint64_t connections() { return obx_sync_server_connections(cPtr()); }
+    uint64_t connections() const { return obx_sync_server_connections(cPtr()); }
 
     /// Get server runtime statistics.
-    std::string statsString(bool includeZeroValues = true) {
+    std::string statsString(bool includeZeroValues = true) const {
         const char* serverStatsString = obx_sync_server_stats_string(cPtr(), includeZeroValues);
         return internal::checkedPtrOrThrow(serverStatsString, "Can't get SyncServer stats string");
     }
 
     /// Get u64 value for sync server statistics.
-    uint64_t statsValueU64(OBXSyncServerStats counterType) {
+    uint64_t statsValueU64(OBXSyncServerStats counterType) const {
         uint64_t value;
         internal::checkErrOrThrow(obx_sync_server_stats_u64(cPtr(), counterType, &value));
         return value;
     }
 
     /// Get double value for sync server statistics.
-    double statsValueF64(OBXSyncServerStats counterType) {
+    double statsValueF64(OBXSyncServerStats counterType) const {
         double value;
         internal::checkErrOrThrow(obx_sync_server_stats_f64(cPtr(), counterType, &value));
         return value;
@@ -1188,7 +1202,7 @@ class AbstractCustomMsgClient {
     /// @param messageSize the number of message bytes.
     /// @returns true if the given message could be forwarded.
     /// @returns false in case the operation encountered an issue.
-    inline bool forwardReceivedMessageFromServer(const void* messageData, size_t messageSize) {
+    bool forwardReceivedMessageFromServer(const void* messageData, size_t messageSize) {
         obx_err err = obx_custom_msg_client_receive_message_from_server(id_, messageData, messageSize);
         return internal::checkSuccessOrThrow(err);
     }
@@ -1198,15 +1212,15 @@ class AbstractCustomMsgClient {
     /// @returns true if the client was in a state that allowed the transition to the given state.
     /// @returns false if no state transition was possible from the current to the given state (e.g. an internal
     /// "closed" state was reached).
-    inline bool forwardState(OBXCustomMsgClientState state) {
+    bool forwardState(OBXCustomMsgClientState state) {
         obx_err err = obx_custom_msg_client_set_state(id_, state);
         return internal::checkSuccessOrThrow(err);
     }
 
     /// The custom msg client may call this if it has knowledge when a reconnection attempt makes sense,
     /// for example, when the network becomes available.
     /// @returns true if a reconnect was actually triggered and false otherwise.
-    inline bool triggerReconnect() {
+    bool triggerReconnect() const {
         obx_err err = obx_custom_msg_client_trigger_reconnect(id_);
         return internal::checkSuccessOrThrow(err);
     }
diff --git a/include/objectbox.h b/include/objectbox.h
@@ -1582,10 +1582,18 @@ OBX_C_API OBX_bytes_array* obx_cursor_backlinks(OBX_cursor* cursor, obx_schema_i
 OBX_C_API OBX_id_array* obx_cursor_backlink_ids(OBX_cursor* cursor, obx_schema_id entity_id, obx_schema_id property_id,
                                                 obx_id id);
 
+/// Puts a standalone (many-to-many) relation instance to "connect" two objects.
+/// @warning Ensure that the source and target IDs are pointing to actually existing objects.
+///          Failing to do so may result in subtle errors.
+///          For example, a known problem is that sync filters always filter out relations that have no valid objects.
+/// @note It's called a "standalone" relation because the relation data is stored separately of object data.
 OBX_C_API obx_err obx_cursor_rel_put(OBX_cursor* cursor, obx_schema_id relation_id, obx_id source_id, obx_id target_id);
+
+/// Removes a standalone (many-to-many) relation instance to "disconnect" two objects.
 OBX_C_API obx_err obx_cursor_rel_remove(OBX_cursor* cursor, obx_schema_id relation_id, obx_id source_id,
                                         obx_id target_id);
 
+/// Gets the standalone (many-to-many) relation instance for the given source ID (the "connections" to other objects).
 /// @returns NULL if the operation failed, see functions like obx_last_error_code() to get error details
 OBX_C_API OBX_id_array* obx_cursor_rel_ids(OBX_cursor* cursor, obx_schema_id relation_id, obx_id source_id);
 

Original file line number	Diff line number	Diff line change
`@@ -17,7 +17,7 @@ if (NOT TARGET objectbox) # Using "if" in case a (potential) parent project alre`
`17`	`17`	`FetchContent_Declare(`
`18`	`18`	`objectbox`
`19`	`19`	`GIT_REPOSITORY https://github.com/objectbox/objectbox-c.git`
`20`		`- GIT_TAG v5.0.0-rc2 # For latest versions, check https://github.com/objectbox/objectbox-c/releases`
	`20`	`+ GIT_TAG v5.0.0-rc3 # For latest versions, check https://github.com/objectbox/objectbox-c/releases`
`21`	`21`	`)`
`22`	`22`	`FetchContent_MakeAvailable(objectbox)`
`23`	`23`