Manage a Sync Session - C++ SDK

Prerequisites

Before you can manage a sync session state, you must:

1. Configure Flexible Sync on the Atlas App Services backend

2. Open a Synced Realm

Get the Sync Session

You can use the member function get_sync_session() to get a sync_session object for any synced realm. The SDK returns this object as an optional. It is a lightweight handle that you can pass around by value.

auto syncSession = realm.get_sync_session();

Check the Network Connection

To check the connection state, you can read the sync session instance's connection_state() property directly.

syncSession->connection_state();

You can also observe the connection state with the observe_connection_change() function. This function registers a callback that the SDK invokes when the underlying sync session changes its connection state.

auto connectionToken = syncSession->observe_connection_change(
    [&](enum realm::sync_session::connection_state,
        enum realm::sync_session::connection_state new_state) {
      // Register a block to execute when connection state changes.
    });

If you register a connection change listener, you can unregister it when you're done listening for changes. Call the sync session instance's unregister_connection_change_observer() method to unregister an observation token.

syncSession->unregister_connection_change_observer(connectionToken);

The network connection state is distinct from the Device Sync connection state that you can check with the state() method. For more information about sync connection state, refer to the Check the Sync State documentation on this page.

Pause or Resume a Sync Session

You can pause and resume the sync session on the realm. Pausing a sync session only suspends that realm's sync session. If you have more than one open realm, suspend does not affect the sync sessions for other realms.

To pause a sync session, call the sync session's pause() method.

syncSession->pause();

To resume a sync session, call the sync session's resume() method.

syncSession->resume();

Wait for Changes to Upload and Download

You can use the sync_session's wait_for_upload_completion() and wait_for_download_completion() methods to wait for changes to upload to or download from Atlas. Both of these methods can optionally take a callback to execute when upload or download is complete.

To wait for all changes to upload to Atlas from your synced realm, use the member function wait_for_upload_completion().

syncSession->wait_for_upload_completion().get();

To wait for all changes from Atlas to download to your synced realm, use the member function wait_for_download_completion(). Refresh the realm after downloading any changes to be sure it reflects the most recent data.

syncSession->wait_for_download_completion().get();
realm.refresh();

Check the Sync State

You can use the sync_session's public member function state() to check whether the sync session is active. This returns an enum whose value reflects possible Device Sync states.

syncSession->state();

The sync connection state is distinct from the network connection state that you can check with the connection_state() method. For more information about network connection state, refer to the Check the Network Connection documentation on this page.

Manually Reconnect All Sync Sessions

Realm automatically detects when a device regains connectivity after being offline and attempts to reconnect using an incremental backoff strategy.

You can choose to manually trigger a reconnect attempt with a sync session's reconnect() method instead of waiting for the duration of the incremental backoff. This is useful if you have a more accurate understanding of the network conditions and don't want to rely on Realm's automatic reconnect detection.

syncSession->reconnect();

When you call this method, the SDK forces all sync sessions to attempt to reconnect immediately. This resets any timers used for incremental backoff.

Calling this method does not guarantee the device can reconnect. If the SDK gets a fatal error, or if the device is already connected or is trying to connect, calling this method has no effect.