SyncClient constructor

SyncClient(Store _store, List<String> serverUrls, List<SyncCredentials> credentials, { Map<String, String>? filterVariables, List<String>? certificatePaths, int? flags, })

Creates a Sync client associated with the given store and options. This does not initiate any connection attempts yet, call start to do so.

By default, a Sync client automatically receives updates from the server once login succeeded. To configure this differently, call setRequestUpdatesMode with the wanted mode.

Typically, only a single URL and a single credentials object is passed:

// Connect to a test server running on localhost using
// an unencrypted connection without authentication
SyncClient client =
    SyncClient(store, ['ws://127.0.0.1:9999'], [SyncCredentials.none()]);

Passing multiple URLs allows high availability and load balancing (for ex. using a ObjectBox Sync Server Cluster). A random URL is selected for each connection attempt.

When passing multiple credentials, can't include SyncCredentials.none.

To configure Sync filter 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.

To, for example, use self-signed certificates in a local development environment or custom CAs, pass certificate paths referring to the local file system to certificatePaths.

To configure Sync behavior, pass bitwise OR-ed OBXSyncFlags values to flags. See OBXSyncFlags for available flags.

Implementation

SyncClient(
    this._store, List<String> serverUrls, List<SyncCredentials> credentials,
    {Map<String, String>? filterVariables,
    List<String>? certificatePaths,
    int? flags}) {
  if (syncClientsStorage.containsKey(_store)) {
    throw StateError('Only one sync client can be active for a store');
  }
  if (serverUrls.isEmpty) {
    throw ArgumentError.value(
        serverUrls, "serverUrls", "Provide at least one server URL");
  }

  if (!Sync.isAvailable()) {
    throw UnsupportedError(
        'Sync is not available in the loaded ObjectBox runtime library. '
        'Please visit https://objectbox.io/sync/ for options.');
  }

  // Build options
  final options = checkObxPtr(C.sync_opt(InternalStoreAccess.ptr(_store)),
      'failed to create Sync options');

  for (final url in serverUrls) {
    withNativeString(url, (urlCStr) {
      checkObx(C.sync_opt_add_url(options, urlCStr));
    });
  }

  if (certificatePaths != null) {
    for (final certPath in certificatePaths) {
      withNativeString(certPath, (certPathCStr) {
        checkObx(C.sync_opt_add_cert_path(options, certPathCStr));
      });
    }
  }

  // Note: 0 or invalid flags are ignored by sync_opt_flags
  if (flags != null) {
    checkObx(C.sync_opt_flags(options, flags));
  }

  // Create Sync client with options (options are freed by sync_create)
  _cSync =
      checkObxPtr(C.sync_create(options), 'failed to create Sync client');

  filterVariables?.forEach(putFilterVariable);

  if (credentials.length == 1) {
    setCredentials(credentials[0]);
  } else {
    // also covers the length == 0 case
    setMultipleCredentials(credentials);
  }

  syncClientsStorage[_store] = this;
  InternalStoreAccess.addCloseListener(_store, this, close);
}