SyncClient: support Sync filter variables #157

Author: greenrobot-team

objectbox/CHANGELOG.md

@@ -8,6 +8,12 @@
     integer (`4_294_967_295`) that is used as the target object of a ToOne, correctly re-set the
     target ID of the ToOne to `0`. [#740](https://github.com/objectbox/objectbox-dart/issues/740)
 
+### Sync
+
+- Support Sync server version 5.0.
+  - **User-Specific Data Sync**: support configuring [Sync filter](https://sync.objectbox.io/sync-server/sync-filters)
+    variables on `SyncClient`.
+
 ## 4.3.1 (2025-09-02)
 
 * Requires at least Dart SDK 3.7 or Flutter SDK 3.29.

objectbox/lib/src/native/sync.dart

@@ -191,7 +191,8 @@ class SyncClient {
   /// Creates a Sync client associated with the given store and options.
   /// This does not initiate any connection attempts yet: call start() to do so.
   SyncClient._(
-      this._store, List<String> serverUrls, List<SyncCredentials> credentials) {
+      this._store, List<String> serverUrls, List<SyncCredentials> credentials,
+      {Map<String, String>? filterVariables}) {
     if (serverUrls.isEmpty) {
       throw ArgumentError.value(
           serverUrls, "serverUrls", "Provide at least one server URL");
@@ -209,6 +210,8 @@ class SyncClient {
             C.sync_urls(InternalStoreAccess.ptr(_store), ptr, size),
             'failed to create Sync client'));
 
+    filterVariables?.forEach(putFilterVariable);
+
     if (credentials.length == 1) {
       setCredentials(credentials[0]);
     } else {
@@ -258,6 +261,40 @@ class SyncClient {
     }
   }
 
+  /// Adds or replaces a [Sync filter](https://sync.objectbox.io/sync-server/sync-filters)
+  /// variable value for the given name.
+  ///
+  /// Eventually, existing values for the same name are replaced.
+  ///
+  /// Sync client filter variables can be used in server-side Sync filters to
+  /// filter out objects that do not match the filters. Filter variables must be
+  /// added before login, so before calling `start()`.
+  ///
+  /// See also [removeFilterVariable] and [removeAllFilterVariables].
+  void putFilterVariable(String name, String value) {
+    withNativeString(
+        name,
+        (nameCStr) => withNativeString(
+            value,
+            (valueCStr) => checkObx(
+                C.sync_filter_variables_put(_ptr, nameCStr, valueCStr))));
+  }
+
+  /// Removes a previously added Sync filter variable value.
+  ///
+  /// See also [putFilterVariable] and [removeAllFilterVariables].
+  void removeFilterVariable(String name) {
+    withNativeString(name,
+        (nameCStr) => checkObx(C.sync_filter_variables_remove(_ptr, nameCStr)));
+  }
+
+  /// Removes all previously added Sync filter variable values.
+  ///
+  /// See also [putFilterVariable] and [removeFilterVariable].
+  void removeAllFilterVariables() {
+    checkObx(C.sync_filter_variables_remove_all(_ptr));
+  }
+
   /// Configure authentication credentials, depending on your server config.
   void setCredentials(SyncCredentials creds) {
     if (creds is _SyncCredentialsNone) {
@@ -697,30 +734,43 @@ class Sync {
   ///
   /// Before [SyncClient.start()], you can still configure some aspects of the
   /// client, e.g. its [SyncRequestUpdatesMode] mode.
+  ///
+  /// To configure [Sync filter](https://sync.objectbox.io/sync-server/sync-filters)
+  /// variables, pass variable names mapped to their value to [filterVariables].
+  ///
+  /// Sync client filter variables can be used in server-side Sync filters to
+  /// filter out objects that do not match the filter.
   static SyncClient client(
-          Store store, String serverUrl, SyncCredentials credentials) =>
-      clientMultiUrls(store, [serverUrl], credentials);
+          Store store, String serverUrl, SyncCredentials credentials,
+          {Map<String, String>? filterVariables}) =>
+      clientMultiUrls(store, [serverUrl], credentials,
+          filterVariables: filterVariables);
 
   /// Like [client], but accepts a list of credentials.
   ///
   /// When passing multiple credentials, does **not** support
   /// [SyncCredentials.none()].
   static SyncClient clientMultiCredentials(
-          Store store, String serverUrl, List<SyncCredentials> credentials) =>
-      clientMultiCredentialsMultiUrls(store, [serverUrl], credentials);
+          Store store, String serverUrl, List<SyncCredentials> credentials,
+          {Map<String, String>? filterVariables}) =>
+      clientMultiCredentialsMultiUrls(store, [serverUrl], credentials,
+          filterVariables: filterVariables);
 
   /// Like [client], but accepts a list of URLs to work with multiple servers.
   static SyncClient clientMultiUrls(
-          Store store, List<String> serverUrls, SyncCredentials credentials) =>
-      clientMultiCredentialsMultiUrls(store, serverUrls, [credentials]);
+          Store store, List<String> serverUrls, SyncCredentials credentials,
+          {Map<String, String>? filterVariables}) =>
+      clientMultiCredentialsMultiUrls(store, serverUrls, [credentials],
+          filterVariables: filterVariables);
 
   /// Like [client], but accepts a list of credentials and a list of URLs to
   /// work with multiple servers.
   ///
   /// When passing multiple credentials, does **not** support
   /// [SyncCredentials.none()].
   static SyncClient clientMultiCredentialsMultiUrls(
-      Store store, List<String> serverUrls, List<SyncCredentials> credentials) {
+      Store store, List<String> serverUrls, List<SyncCredentials> credentials,
+      {Map<String, String>? filterVariables}) {
     if (syncClientsStorage.containsKey(store)) {
       throw StateError('Only one sync client can be active for a store');
     }

objectbox_test/test/sync_test.dart

@@ -260,6 +260,29 @@ void main() {
       ]);
     });
 
+    test('SyncClient filter variables', () {
+      final filterVariables = {
+        'test-var-1': 'test value 1',
+        'test-var-2': 'test value 2'
+      };
+      SyncClient client = Sync.client(
+          store, serverUrl(), SyncCredentials.none(),
+          filterVariables: filterVariables);
+      addTearDown(() {
+        client.close();
+      });
+
+      client.putFilterVariable('test-var-2', 'test value 2');
+      client.removeFilterVariable('test-var-2');
+      client.putFilterVariable('test-var-2', '');
+      client.removeAllFilterVariables();
+
+      expect(
+          () => client.putFilterVariable('', 'value'),
+          throwsA(isA<ArgumentError>().having((e) => e.message, 'message',
+              contains('Filter variables must have a name'))));
+    });
+
     group('Server tests using sync-server in PATH', () {
       late SyncServer server;