diff --git a/source/includes/api-details/cpp/api-not-supported.rst b/source/includes/api-details/cpp/api-not-supported.rst new file mode 100644 index 0000000000..15ed2dd493 --- /dev/null +++ b/source/includes/api-details/cpp/api-not-supported.rst @@ -0,0 +1 @@ +The C++ SDK does not currently support this API. diff --git a/source/includes/api-details/cpp/sync/manage-sync-sessions-check-network-connection-description.rst b/source/includes/api-details/cpp/sync/manage-sync-sessions-check-network-connection-description.rst new file mode 100644 index 0000000000..4f2f4f9a7a --- /dev/null +++ b/source/includes/api-details/cpp/sync/manage-sync-sessions-check-network-connection-description.rst @@ -0,0 +1,28 @@ +**Check Connection State** + +To check the connection state, you can read the +:cpp-sdk:`sync session instance's ` +``connection_state()`` property directly. + +.. literalinclude:: /examples/generated/cpp/sync-session.snippet.connection-state.cpp + :language: cpp + +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. + +**Observe Connection State** + +You can also observe the connection state with the +:cpp-sdk:`observe_connection_change() ` +function. This function registers a callback that the SDK invokes when the +underlying sync session changes its connection state. + +.. literalinclude:: /examples/generated/cpp/sync-session.snippet.observe-connection-change.cpp + :language: cpp + +If you register a connection change listener, you can unregister it when +you're done listening for changes. Call the sync session instance's +:cpp-sdk:`unregister_connection_change_observer() ` +method to unregister an observation token. diff --git a/source/includes/api-details/cpp/sync/manage-sync-sessions-check-sync-state-description.rst b/source/includes/api-details/cpp/sync/manage-sync-sessions-check-sync-state-description.rst new file mode 100644 index 0000000000..3acaeeece8 --- /dev/null +++ b/source/includes/api-details/cpp/sync/manage-sync-sessions-check-sync-state-description.rst @@ -0,0 +1,4 @@ +You can use the :cpp-sdk:`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. diff --git a/source/includes/api-details/cpp/sync/manage-sync-sessions-get-sync-session-description.rst b/source/includes/api-details/cpp/sync/manage-sync-sessions-get-sync-session-description.rst new file mode 100644 index 0000000000..336e047156 --- /dev/null +++ b/source/includes/api-details/cpp/sync/manage-sync-sessions-get-sync-session-description.rst @@ -0,0 +1,6 @@ +You can use the member function :cpp-sdk:`get_sync_session() +` to get a +:cpp-sdk:`sync_session +` +object for any synced database. The SDK returns this object as an optional. +It is a lightweight handle that you can pass around by value. diff --git a/source/includes/api-details/cpp/sync/manage-sync-sessions-manually-reconnect-sync-sessions-description.rst b/source/includes/api-details/cpp/sync/manage-sync-sessions-manually-reconnect-sync-sessions-description.rst new file mode 100644 index 0000000000..5582e05cbc --- /dev/null +++ b/source/includes/api-details/cpp/sync/manage-sync-sessions-manually-reconnect-sync-sessions-description.rst @@ -0,0 +1,3 @@ +You can choose to manually trigger a reconnect attempt with a sync session's +:cpp-sdk:`reconnect() ` +method. diff --git a/source/includes/api-details/cpp/sync/manage-sync-sessions-pause-resume-sync-session-description.rst b/source/includes/api-details/cpp/sync/manage-sync-sessions-pause-resume-sync-session-description.rst new file mode 100644 index 0000000000..46d325379c --- /dev/null +++ b/source/includes/api-details/cpp/sync/manage-sync-sessions-pause-resume-sync-session-description.rst @@ -0,0 +1,10 @@ +To pause a sync session, call the sync session's +:cpp-sdk:`pause() ` +method. + +.. literalinclude:: /examples/generated/cpp/sync-session.snippet.pause.cpp + :language: cpp + +To resume a sync session, call the sync session's +:cpp-sdk:`resume() ` +method. diff --git a/source/includes/api-details/cpp/sync/manage-sync-sessions-wait-for-changes-to-upload-or-download-description.rst b/source/includes/api-details/cpp/sync/manage-sync-sessions-wait-for-changes-to-upload-or-download-description.rst new file mode 100644 index 0000000000..060084f9ea --- /dev/null +++ b/source/includes/api-details/cpp/sync/manage-sync-sessions-wait-for-changes-to-upload-or-download-description.rst @@ -0,0 +1,17 @@ +You can use the +:cpp-sdk:`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 database, +use the member function ``wait_for_upload_completion()``. + +.. literalinclude:: /examples/generated/cpp/sync-session.snippet.wait-for-upload.cpp + :language: cpp + +To wait for all changes from Atlas +to download to your synced database, use the member function +``wait_for_download_completion()``. Refresh the database after downloading +any changes to be sure it reflects the most recent data. diff --git a/source/includes/api-details/csharp/sync/manage-sync-sessions-check-network-connection-description.rst b/source/includes/api-details/csharp/sync/manage-sync-sessions-check-network-connection-description.rst new file mode 100644 index 0000000000..af6e1fa2f4 --- /dev/null +++ b/source/includes/api-details/csharp/sync/manage-sync-sessions-check-network-connection-description.rst @@ -0,0 +1,6 @@ +To check the connection state, you can read the +:dotnet-sdk:`Session instance's ConnectionState +` +property. Its value is a :dotnet-sdk:`ConnectionState enum +` that reflects the current state +of the sync session's connection. diff --git a/source/includes/api-details/csharp/sync/manage-sync-sessions-check-sync-state-description.rst b/source/includes/api-details/csharp/sync/manage-sync-sessions-check-sync-state-description.rst new file mode 100644 index 0000000000..b2da639c2c --- /dev/null +++ b/source/includes/api-details/csharp/sync/manage-sync-sessions-check-sync-state-description.rst @@ -0,0 +1,6 @@ +To check the Sync state, you can read the +:dotnet-sdk:`Session instance's State +` +property. Its value is a :dotnet-sdk:`ConnectionState enum +` that reflects the current state +of the Sync session's communication with the server. diff --git a/source/includes/api-details/csharp/sync/manage-sync-sessions-check-upload-and-download-progress-description.rst b/source/includes/api-details/csharp/sync/manage-sync-sessions-check-upload-and-download-progress-description.rst new file mode 100644 index 0000000000..7fac246cf2 --- /dev/null +++ b/source/includes/api-details/csharp/sync/manage-sync-sessions-check-upload-and-download-progress-description.rst @@ -0,0 +1,26 @@ +To monitor Sync progress, get the Sync session from the +:dotnet-sdk:`Realms.Sync.SyncSession +` property, then add a +progress notification by calling the +:dotnet-sdk:`session.GetProgressObservable() ` +method. + +The ``session.GetProgressObservable`` method takes in the following two parameters: + +- A :dotnet-sdk:`ProgressDirection ` + parameter that can be set to ``Upload`` or ``Download``. + +- A :dotnet-sdk:`ProgressMode ` parameter + that can be set to ``ReportIndefinitely`` + for the notifications to continue until the callback is unregistered, or + ``ForCurrentlyOutstandingWork`` for the notifications to continue until only + the currently transferable bytes are synced. + +When you `Subscribe `_ +to the notifications, you receive a +:dotnet-sdk:`SyncProgress ` +object that provides a percentage estimate of the current progress, expressed +as a double between 0.0 and 1.0. + +Once you no longer wish to receive notifications, unregister the token with +``token.Dispose()``. diff --git a/source/includes/api-details/csharp/sync/manage-sync-sessions-get-sync-session-description.rst b/source/includes/api-details/csharp/sync/manage-sync-sessions-get-sync-session-description.rst new file mode 100644 index 0000000000..e85b478d09 --- /dev/null +++ b/source/includes/api-details/csharp/sync/manage-sync-sessions-get-sync-session-description.rst @@ -0,0 +1,3 @@ +You can access the Sync +:dotnet-sdk:`Session ` through a synced +:dotnet-sdk:`Realm `. diff --git a/source/includes/api-details/csharp/sync/manage-sync-sessions-pause-resume-sync-session-description.rst b/source/includes/api-details/csharp/sync/manage-sync-sessions-pause-resume-sync-session-description.rst new file mode 100644 index 0000000000..a48f936cba --- /dev/null +++ b/source/includes/api-details/csharp/sync/manage-sync-sessions-pause-resume-sync-session-description.rst @@ -0,0 +1,10 @@ +To pause synchronization for a specific session, you can call the +:dotnet-sdk:`Stop() ` +method on the session. + +When you then call the +:dotnet-sdk:`Start() ` +method on the paused session, the Sync session resumes. + +The following code block demonstrates calling the ``Stop()`` and ``Start()`` +methods: diff --git a/source/includes/api-details/csharp/sync/manage-sync-sessions-wait-for-changes-to-upload-or-download-description.rst b/source/includes/api-details/csharp/sync/manage-sync-sessions-wait-for-changes-to-upload-or-download-description.rst new file mode 100644 index 0000000000..ce0dc54d51 --- /dev/null +++ b/source/includes/api-details/csharp/sync/manage-sync-sessions-wait-for-changes-to-upload-or-download-description.rst @@ -0,0 +1,11 @@ +To asynchronously wait for your changes to finish uploading, get the Sync +session from the :dotnet-sdk:`Realms.Sync.SyncSession +` +property, and then call the :dotnet-sdk:`session.WaitForUploadAsync() +` +method. + +To wait for changes to finish downloading, call the +:dotnet-sdk:`session.WaitForDownloadAsync() +` +method. diff --git a/source/includes/api-details/dart/sync/manage-sync-sessions-check-network-connection-description.rst b/source/includes/api-details/dart/sync/manage-sync-sessions-check-network-connection-description.rst new file mode 100644 index 0000000000..e91a317e2b --- /dev/null +++ b/source/includes/api-details/dart/sync/manage-sync-sessions-check-network-connection-description.rst @@ -0,0 +1,17 @@ +You can get the state of the current network connection with +:flutter-sdk:`Session.connectionState `. +This returns a :flutter-sdk:`ConnectionState ` enum +that contains the network connection's state, which is one of: + +- ``connected`` +- ``disconnected`` +- ``connecting`` + +.. literalinclude:: /examples/generated/flutter/manage_sync_session_test.snippet.get-network-connection.dart + :language: dart + +Monitor the state of the network connection with +:flutter-sdk:`Session.connectionStateChanges `. +This property returns a Stream of :flutter-sdk:`ConnectionStateChange ` +objects that updates when the network connection changes. +You can access the current and previous ``ConnectionState`` from ``ConnectionStateChange``. diff --git a/source/includes/api-details/dart/sync/manage-sync-sessions-check-sync-state-description.rst b/source/includes/api-details/dart/sync/manage-sync-sessions-check-sync-state-description.rst new file mode 100644 index 0000000000..38a07ae047 --- /dev/null +++ b/source/includes/api-details/dart/sync/manage-sync-sessions-check-sync-state-description.rst @@ -0,0 +1,7 @@ +You can get the state of the current Sync session state with +:flutter-sdk:`Session.state `. +This returns a :flutter-sdk:`SessionState ` enum +that contains the Sync session state, which is one of: + +- ``active`` +- ``inactive`` diff --git a/source/includes/api-details/dart/sync/manage-sync-sessions-check-upload-download-progress-description.rst b/source/includes/api-details/dart/sync/manage-sync-sessions-check-upload-download-progress-description.rst new file mode 100644 index 0000000000..41fd0c0f00 --- /dev/null +++ b/source/includes/api-details/dart/sync/manage-sync-sessions-check-upload-download-progress-description.rst @@ -0,0 +1,24 @@ +.. versionchanged:: 2.0.0 + ``transferredBytes`` and ``transferrableBytes`` deprecated in favor of ``progressEstimate`` + +To monitor Sync progress, call :flutter-sdk:`SyncSession.getProgressStream() +`. This method returns a Stream of +:flutter-sdk:`SyncProgress ` objects that provide +a ``progressEstimate`` for the current upload or download. + +The provided ``progressEstimate`` is a double whose value +ranges from ``0.0`` to ``1.0``. At ``1.0``, the progress stream is complete. + +``SyncSession.getProgressStream()`` takes two arguments: + +- A :flutter-sdk:`ProgressDirection ` + enum that can be set to ``upload`` or ``download``. Specifies whether the + progress stream monitors upload or download progress. + +- A :flutter-sdk:`ProgressMode ` enum + that can be set to one of the following: + + - ``reportIndefinitely``: Sets notifications to continue until the callback is + unregistered. + - ``forCurrentlyOutstandingWork``: Sets notifications to continue until the + ``progressEstimate`` reaches ``1.0``. diff --git a/source/includes/api-details/dart/sync/manage-sync-sessions-get-sync-session-description.rst b/source/includes/api-details/dart/sync/manage-sync-sessions-get-sync-session-description.rst new file mode 100644 index 0000000000..28c1a2700a --- /dev/null +++ b/source/includes/api-details/dart/sync/manage-sync-sessions-get-sync-session-description.rst @@ -0,0 +1,3 @@ +You can access the :flutter-sdk:`Session ` of any +synced database through the :flutter-sdk:`Realm.syncSession +` property. diff --git a/source/includes/api-details/dart/sync/manage-sync-sessions-manually-reconnect-sync-sessions-description.rst b/source/includes/api-details/dart/sync/manage-sync-sessions-manually-reconnect-sync-sessions-description.rst new file mode 100644 index 0000000000..6ac3b9af17 --- /dev/null +++ b/source/includes/api-details/dart/sync/manage-sync-sessions-manually-reconnect-sync-sessions-description.rst @@ -0,0 +1,3 @@ +You can choose to manually trigger a reconnect attempt with the +:flutter-sdk:`App.reconnect() ` instead of waiting for +the duration of the incremental backoff. diff --git a/source/includes/api-details/dart/sync/manage-sync-sessions-pause-resume-sync-session-description.rst b/source/includes/api-details/dart/sync/manage-sync-sessions-pause-resume-sync-session-description.rst new file mode 100644 index 0000000000..1a5fa67a2f --- /dev/null +++ b/source/includes/api-details/dart/sync/manage-sync-sessions-pause-resume-sync-session-description.rst @@ -0,0 +1,4 @@ +To pause syncing for a session, call :flutter-sdk:`Session.pause() `. +The database does not sync changes with Atlas while the session is paused. + +To resume syncing a changes, call :flutter-sdk:`Session.resume() `. diff --git a/source/includes/api-details/dart/sync/manage-sync-sessions-wait-for-changes-to-upload-or-download-description.rst b/source/includes/api-details/dart/sync/manage-sync-sessions-wait-for-changes-to-upload-or-download-description.rst new file mode 100644 index 0000000000..1b12edfb86 --- /dev/null +++ b/source/includes/api-details/dart/sync/manage-sync-sessions-wait-for-changes-to-upload-or-download-description.rst @@ -0,0 +1,8 @@ +To wait for the session to finish uploading all pending changes, call +:flutter-sdk:`Session.waitForUpload() `. + +To wait for the session to finish downloading all pending changes, call +:flutter-sdk:`Session.waitForDownload() `. + +Both of these sessions can take an optional :flutter-sdk:`CancellationToken +` to cancel the wait operation. diff --git a/source/includes/api-details/java/sync/manage-sync-sessions-check-network-connection-description.rst b/source/includes/api-details/java/sync/manage-sync-sessions-check-network-connection-description.rst new file mode 100644 index 0000000000..6a3cfac398 --- /dev/null +++ b/source/includes/api-details/java/sync/manage-sync-sessions-check-network-connection-description.rst @@ -0,0 +1,7 @@ +To check the current network connection, call :java-sdk:`getConnectionState() +` on your +:java-sdk:`SyncSession `. + +You can also subscribe to connection changes on your ``SyncSession`` +with :java-sdk:`addConnectionChangeListener() +` diff --git a/source/includes/api-details/java/sync/manage-sync-sessions-check-sync-state-description.rst b/source/includes/api-details/java/sync/manage-sync-sessions-check-sync-state-description.rst new file mode 100644 index 0000000000..9b3c807e6a --- /dev/null +++ b/source/includes/api-details/java/sync/manage-sync-sessions-check-sync-state-description.rst @@ -0,0 +1,3 @@ +To check the current Sync state, call :java-sdk:`getState() +` on your +:java-sdk:`SyncSession `. diff --git a/source/includes/api-details/java/sync/manage-sync-sessions-get-sync-session-description.rst b/source/includes/api-details/java/sync/manage-sync-sessions-get-sync-session-description.rst new file mode 100644 index 0000000000..b4fbbc8b3c --- /dev/null +++ b/source/includes/api-details/java/sync/manage-sync-sessions-get-sync-session-description.rst @@ -0,0 +1,2 @@ +You can access the session of any synced database through the +:java-sdk:`SyncSession `. diff --git a/source/includes/api-details/java/sync/manage-sync-sessions-pause-resume-sync-session-java-description.rst b/source/includes/api-details/java/sync/manage-sync-sessions-pause-resume-sync-session-java-description.rst new file mode 100644 index 0000000000..de8efa52e2 --- /dev/null +++ b/source/includes/api-details/java/sync/manage-sync-sessions-pause-resume-sync-session-java-description.rst @@ -0,0 +1,11 @@ +To pause a currently active sync session, call +:java-sdk:`stop() ` +on your :java-sdk:`SyncSession `: + +.. literalinclude:: /examples/generated/java/sync/SyncDataTest.snippet.pause-sync-session.java + :language: java + :copyable: false + +To resume a currently paused sync session, call +:java-sdk:`start() ` +on your :java-sdk:`SyncSession `: diff --git a/source/includes/api-details/java/sync/manage-sync-sessions-pause-resume-sync-session-kotlin-description.rst b/source/includes/api-details/java/sync/manage-sync-sessions-pause-resume-sync-session-kotlin-description.rst new file mode 100644 index 0000000000..cfd5d1b42c --- /dev/null +++ b/source/includes/api-details/java/sync/manage-sync-sessions-pause-resume-sync-session-kotlin-description.rst @@ -0,0 +1,11 @@ +To pause a currently active sync session, call +:java-sdk:`stop() ` +on your :java-sdk:`SyncSession `: + +.. literalinclude:: /examples/generated/java/sync/SyncDataTest.snippet.pause-sync-session.kt + :language: kotlin + :copyable: false + +To resume a currently paused sync session, call +:java-sdk:`start() ` +on your :java-sdk:`SyncSession `: diff --git a/source/includes/api-details/java/sync/manage-sync-sessions-wait-for-changes-to-upload-or-download-description.rst b/source/includes/api-details/java/sync/manage-sync-sessions-wait-for-changes-to-upload-or-download-description.rst new file mode 100644 index 0000000000..e0779dc6c4 --- /dev/null +++ b/source/includes/api-details/java/sync/manage-sync-sessions-wait-for-changes-to-upload-or-download-description.rst @@ -0,0 +1,13 @@ +You can wait for changes to upload with :java-sdk:`SyncSession.uploadAllLocalChanges() +` or +:java-sdk:`SyncSession.uploadAllLocalChanges(long timeout, TimeUnit unit) +`. +These methods block block execution until all known changes on the device have +been uploaded to the server (or the specified timeout is hit). + +You can wait for changes to download with :java-sdk:`SyncSession.downloadAllServerChanges() +` or +:java-sdk:`SyncSession.downloadAllServerChanges(long timeout, TimeUnit unit) +`. +These methods block block execution until all known changes on the server have +downloaded to the device (or the specified timeout is hit). diff --git a/source/includes/api-details/javascript/sync/manage-sync-sessions-check-network-connection-js-ts-description.rst b/source/includes/api-details/javascript/sync/manage-sync-sessions-check-network-connection-js-ts-description.rst new file mode 100644 index 0000000000..ae7f851aa9 --- /dev/null +++ b/source/includes/api-details/javascript/sync/manage-sync-sessions-check-network-connection-js-ts-description.rst @@ -0,0 +1,3 @@ +To check the current state of the connection to the server, call the +:js-sdk:`syncSession.connectionState() +` method. diff --git a/source/includes/api-details/javascript/sync/manage-sync-sessions-check-sync-state-js-ts-description.rst b/source/includes/api-details/javascript/sync/manage-sync-sessions-check-sync-state-js-ts-description.rst new file mode 100644 index 0000000000..6227def9e2 --- /dev/null +++ b/source/includes/api-details/javascript/sync/manage-sync-sessions-check-sync-state-js-ts-description.rst @@ -0,0 +1,2 @@ +To check the current state of the Sync session, call the +:js-sdk:`syncSession.state() ` method. diff --git a/source/includes/api-details/javascript/sync/manage-sync-sessions-check-upload-download-progress-js-ts-description.rst b/source/includes/api-details/javascript/sync/manage-sync-sessions-check-upload-download-progress-js-ts-description.rst new file mode 100644 index 0000000000..357f3b8ebd --- /dev/null +++ b/source/includes/api-details/javascript/sync/manage-sync-sessions-check-upload-download-progress-js-ts-description.rst @@ -0,0 +1,16 @@ +To check the upload and download progress for a sync session, add a progress +notification using the :js-sdk:`syncSession.addProgressNotification() +` method. + +The ``syncSession.addProgressNotification()`` method takes in the following +three parameters: + +- A ``direction`` parameter. + Set to ``"upload"`` to register notifications for uploading data. + Set to ``"download"`` to register notifications for downloading data. +- A ``mode`` parameter. Set to ``"reportIndefinitely"`` + for the notifications to continue until the callback is unregistered using + :js-sdk:`syncSession.removeProgressNotification() `. + Set to ``"forCurrentlyOutstandingWork"`` for the notifications to continue + until only the currently transferable bytes are synced. +- A callback function parameter. diff --git a/source/includes/api-details/javascript/sync/manage-sync-sessions-get-sync-session-js-ts-description.rst b/source/includes/api-details/javascript/sync/manage-sync-sessions-get-sync-session-js-ts-description.rst new file mode 100644 index 0000000000..c896582625 --- /dev/null +++ b/source/includes/api-details/javascript/sync/manage-sync-sessions-get-sync-session-js-ts-description.rst @@ -0,0 +1,2 @@ +After opening a synced database, you can access its sync session with the +:js-sdk:`Realm.syncSession ` property. diff --git a/source/includes/api-details/javascript/sync/manage-sync-sessions-manually-reconnect-sync-sessions-js-ts-description.rst b/source/includes/api-details/javascript/sync/manage-sync-sessions-manually-reconnect-sync-sessions-js-ts-description.rst new file mode 100644 index 0000000000..8b0ac6d0a5 --- /dev/null +++ b/source/includes/api-details/javascript/sync/manage-sync-sessions-manually-reconnect-sync-sessions-js-ts-description.rst @@ -0,0 +1,3 @@ +To attempt to manually reconnect all Sync sessions, call +:js-sdk:`Realm.App.Sync.Session.reconnect() +`. diff --git a/source/includes/api-details/javascript/sync/manage-sync-sessions-pause-resume-sync-session-js-ts-description.rst b/source/includes/api-details/javascript/sync/manage-sync-sessions-pause-resume-sync-session-js-ts-description.rst new file mode 100644 index 0000000000..63bcb440c6 --- /dev/null +++ b/source/includes/api-details/javascript/sync/manage-sync-sessions-pause-resume-sync-session-js-ts-description.rst @@ -0,0 +1,3 @@ +To pause synchronization, use the :js-sdk:`syncSession.pause() +` method. To resume synchronization, use the +:js-sdk:`syncSession.resume() ` method. diff --git a/source/includes/api-details/javascript/sync/manage-sync-sessions-wait-for-changes-to-upload-or-download-description.rst b/source/includes/api-details/javascript/sync/manage-sync-sessions-wait-for-changes-to-upload-or-download-description.rst new file mode 100644 index 0000000000..e44d9ef28f --- /dev/null +++ b/source/includes/api-details/javascript/sync/manage-sync-sessions-wait-for-changes-to-upload-or-download-description.rst @@ -0,0 +1,17 @@ +To asynchronously wait for all changes to upload to Atlas from your synced +database, call :js-sdk:`uploadAllLocalChanges() +`. This method returns +true when all changes have been uploaded. + +To asynchronously wait for all changes on Atlas to download from the +Device Sync server to your synced database, call +:js-sdk:`downloadAllServerChanges() `. +This method returns true when all changes have been downloaded. + +You can specify a request timeout on the :js-sdk:`App configuration +`. With a timeout specified, you can set +``cancelWaitsOnNonFatalErrors`` on your :js-sdk:`BaseSyncConfiguration +`. When ``true`` and the timeout interval +arrives, any any outstanding work that is awaiting uploads and downloads +cancels. When this setting is false, awaiting uploads and downloads does +not cancel because the SDK treats these timeouts as non-fatal errors. diff --git a/source/includes/api-details/kotlin/sync/manage-sync-sessions-check-network-connection-description.rst b/source/includes/api-details/kotlin/sync/manage-sync-sessions-check-network-connection-description.rst new file mode 100644 index 0000000000..ca08e230c8 --- /dev/null +++ b/source/includes/api-details/kotlin/sync/manage-sync-sessions-check-network-connection-description.rst @@ -0,0 +1,19 @@ +You can check the network connection state through the +:kotlin-sync-sdk:`SyncSession.ConnectionState +`. This is a +property of type ConnectionState enum, whose possible values are: + +- DISCONNECTED +- CONNECTING +- CONNECTED + +.. literalinclude:: /examples/generated/kotlin/ManageSyncSession.snippet.get-network-connection.kt + :language: kotlin + +Monitor the state of the network connection with +:kotlin-sync-sdk:`connectionStateAsFlow +`. +This property returns a Flow of :kotlin-sync-sdk:`ConnectionStateChange +` +objects that updates when the network connection changes. You can access the +new and old ``ConnectionState`` from ``ConnectionStateChange``. diff --git a/source/includes/api-details/kotlin/sync/manage-sync-sessions-check-sync-state-description.rst b/source/includes/api-details/kotlin/sync/manage-sync-sessions-check-sync-state-description.rst new file mode 100644 index 0000000000..b5bc79aa2f --- /dev/null +++ b/source/includes/api-details/kotlin/sync/manage-sync-sessions-check-sync-state-description.rst @@ -0,0 +1,10 @@ +You can check the Sync session state through the +:kotlin-sync-sdk:`SyncSession.State +`. This is a +property of type State enum, whose possible values are: + +- INACTIVE +- ACTIVE +- PAUSED +- DYING +- WAITING_FOR_ACCESS_TOKEN diff --git a/source/includes/api-details/kotlin/sync/manage-sync-sessions-check-upload-download-progress-description.rst b/source/includes/api-details/kotlin/sync/manage-sync-sessions-check-upload-download-progress-description.rst new file mode 100644 index 0000000000..fa70a47154 --- /dev/null +++ b/source/includes/api-details/kotlin/sync/manage-sync-sessions-check-upload-download-progress-description.rst @@ -0,0 +1,24 @@ +To monitor Sync upload and download progress, call +:kotlin-sync-sdk:`SyncSession.progressAsFlow() +`. + +This method returns a Flow of :kotlin-sync-sdk:`Progress +` events. ``Progress`` +provides an ``estimate``, a double, that represents a transfer progress +estimate that ranges from 0.0 to 1.0. It also provides an +``isTransferComplete`` bool. + +``syncSession.progressAsFlow()`` takes two arguments: + +- A :kotlin-sync-sdk:`Direction ` + enum that can be set to ``UPLOAD`` or ``DOWNLOAD``. + This specifies that the progress stream tracks uploads or downloads. + +- A :kotlin-sync-sdk:`ProgressMode + ` enum that can be + set to either: + + - ``INDEFINITELY``: Sets notifications to continue until the callback is + unregistered. + - ``CURRENT_CHANGES``: Sets notifications to continue until only the currently + transferable bytes are synced. diff --git a/source/includes/api-details/kotlin/sync/manage-sync-sessions-get-sync-session-description.rst b/source/includes/api-details/kotlin/sync/manage-sync-sessions-get-sync-session-description.rst new file mode 100644 index 0000000000..e4c4f295ae --- /dev/null +++ b/source/includes/api-details/kotlin/sync/manage-sync-sessions-get-sync-session-description.rst @@ -0,0 +1,4 @@ +You can access the :kotlin-sync-sdk:`SyncSession +` +of a single synced database through the :kotlin-sync-sdk:`realm.syncSession +` property. diff --git a/source/includes/api-details/kotlin/sync/manage-sync-sessions-manually-reconnect-sync-sessions-description.rst b/source/includes/api-details/kotlin/sync/manage-sync-sessions-manually-reconnect-sync-sessions-description.rst new file mode 100644 index 0000000000..8f28ffce8d --- /dev/null +++ b/source/includes/api-details/kotlin/sync/manage-sync-sessions-manually-reconnect-sync-sessions-description.rst @@ -0,0 +1,9 @@ +In Kotlin SDK version 1.11.0 and later, you can choose to manually trigger a +reconnect attempt with the :kotlin-sync-sdk:`App.Sync.reconnect() +` +instead of waiting for the duration of the incremental backoff. This is +useful if you have a more accurate understanding of +the network conditions (for example, when monitoring network changes with the +``ConnectivityManager`` on Android) and don't want to rely on Realm's automatic +reconnect detection. The SDK also automatically calls this method when a device +toggles off airplane mode. diff --git a/source/includes/api-details/kotlin/sync/manage-sync-sessions-pause-resume-sync-session-description.rst b/source/includes/api-details/kotlin/sync/manage-sync-sessions-pause-resume-sync-session-description.rst new file mode 100644 index 0000000000..a2bd9cbeeb --- /dev/null +++ b/source/includes/api-details/kotlin/sync/manage-sync-sessions-pause-resume-sync-session-description.rst @@ -0,0 +1,6 @@ +To pause syncing for a session, call :kotlin-sync-sdk:`syncSession.pause() +`. +The database does not sync changes with Atlas while the session is paused. + +To resume syncing changes, call :kotlin-sync-sdk:`syncSession.resume() +`. diff --git a/source/includes/api-details/kotlin/sync/manage-sync-sessions-wait-for-changes-to-upload-or-download-description.rst b/source/includes/api-details/kotlin/sync/manage-sync-sessions-wait-for-changes-to-upload-or-download-description.rst new file mode 100644 index 0000000000..a7978e205a --- /dev/null +++ b/source/includes/api-details/kotlin/sync/manage-sync-sessions-wait-for-changes-to-upload-or-download-description.rst @@ -0,0 +1,13 @@ +To asynchronously wait for all changes to upload to Atlas from your synced +database, call :kotlin-sync-sdk:`uploadAllLocalChanges +`. +This method returns ``true`` when all changes have been uploaded. + +To asynchronously wait for all changes on Atlas to download from the Device Sync +server to your synced database, call :kotlin-sync-sdk:`downloadAllServerChanges +`. +This method returns ``true`` when all changes have been downloaded. + +You can also include an optional ``timeout`` parameter to either method to +determine the maximum amount of time before returning ``false``. Note that +the upload or download continues in the background even after returning ``false``. diff --git a/source/includes/api-details/objectivec/sync/manage-sync-sessions-check-network-connection-description.rst b/source/includes/api-details/objectivec/sync/manage-sync-sessions-check-network-connection-description.rst new file mode 100644 index 0000000000..ce2a81ec15 --- /dev/null +++ b/source/includes/api-details/objectivec/sync/manage-sync-sessions-check-network-connection-description.rst @@ -0,0 +1,22 @@ +To get the connection state of a :dotnet-sdk:`SyncSession +`, set an event handler +on the :dotnet-sdk:`PropertyChanged ` +event. The event handler is a standard +`.NET PropertyChangedEventHandler delegate +`_ +that takes in a ``sender`` object and +`PropertyChangedEventArgs `_ +object. + +In the event handler, cast the sender to a ``Session`` object and check if +the event argument's ``PropertyName`` property is ``Session.ConnectionState``. +You can then get the +:dotnet-sdk:`ConnectionState ` +value, which is one of the following: + +- Connecting +- Connected +- Disconnected + +The following code demonstrates setting the event handler, casting the session +object, and checking the Sync status: diff --git a/source/includes/api-details/objectivec/sync/manage-sync-sessions-check-sync-state-description.rst b/source/includes/api-details/objectivec/sync/manage-sync-sessions-check-sync-state-description.rst new file mode 100644 index 0000000000..80a23d5f54 --- /dev/null +++ b/source/includes/api-details/objectivec/sync/manage-sync-sessions-check-sync-state-description.rst @@ -0,0 +1,5 @@ +You can use the :objc-sdk:`RLMSyncSession.state +`property to +check whether the Sync session is active. This property is an +:objc-sdk:`RLMSyncSessionState enum ` whose +value reflects possible Device Sync states. diff --git a/source/includes/api-details/objectivec/sync/manage-sync-sessions-check-upload-download-progress-description.rst b/source/includes/api-details/objectivec/sync/manage-sync-sessions-check-upload-download-progress-description.rst new file mode 100644 index 0000000000..bd72faa3fc --- /dev/null +++ b/source/includes/api-details/objectivec/sync/manage-sync-sessions-check-upload-download-progress-description.rst @@ -0,0 +1,12 @@ +.. versionchanged:: 10.50.0 + ``addProgressNotificationForDirection`` deprecated in favor of ``addSyncProgressNotificationForDirection`` + +You can add a progress notification using the RLMSyncSession instance's +:objc-sdk:`addSyncProgressNotificationForDirection:mode:block: +` +method. + +This method returns a token that you should retain until you wish +to stop observing upload or download progress. Note that if you +keep the token in a local variable, observation will stop when the +local variable goes out of scope. diff --git a/source/includes/api-details/objectivec/sync/manage-sync-sessions-get-sync-session-description.rst b/source/includes/api-details/objectivec/sync/manage-sync-sessions-get-sync-session-description.rst new file mode 100644 index 0000000000..48b6d43296 --- /dev/null +++ b/source/includes/api-details/objectivec/sync/manage-sync-sessions-get-sync-session-description.rst @@ -0,0 +1,2 @@ +You can access the :objc-sdk:`SyncSession ` +object on a synced :objc-sdk:`Realm `. diff --git a/source/includes/api-details/objectivec/sync/manage-sync-sessions-manually-reconnect-sync-sessions-description.rst b/source/includes/api-details/objectivec/sync/manage-sync-sessions-manually-reconnect-sync-sessions-description.rst new file mode 100644 index 0000000000..310d207e1a --- /dev/null +++ b/source/includes/api-details/objectivec/sync/manage-sync-sessions-manually-reconnect-sync-sessions-description.rst @@ -0,0 +1,5 @@ +.. versionadded:: 10.44.0 + +In Swift SDK version 10.44.0 and later, you can choose to manually trigger a +reconnect attempt with :objc-sdk:`RLMSyncSession.reconnect() +`. diff --git a/source/includes/api-details/objectivec/sync/manage-sync-sessions-pause-resume-sync-session-description.rst b/source/includes/api-details/objectivec/sync/manage-sync-sessions-pause-resume-sync-session-description.rst new file mode 100644 index 0000000000..3e9e3ee8a1 --- /dev/null +++ b/source/includes/api-details/objectivec/sync/manage-sync-sessions-pause-resume-sync-session-description.rst @@ -0,0 +1,7 @@ +You can pause a Sync session by calling :objc-sdk:`RLMSyncSession.suspend() +` on a +synced database instance. + +Call :objc-sdk:`RLMSyncSession.resume() +` to start +syncing again. diff --git a/source/includes/api-details/objectivec/sync/manage-sync-sessions-wait-for-changes-to-upload-or-download-description.rst b/source/includes/api-details/objectivec/sync/manage-sync-sessions-wait-for-changes-to-upload-or-download-description.rst new file mode 100644 index 0000000000..8b74e39c25 --- /dev/null +++ b/source/includes/api-details/objectivec/sync/manage-sync-sessions-wait-for-changes-to-upload-or-download-description.rst @@ -0,0 +1,7 @@ +To wait for all changes to upload or download from your synced database, call: + +- Upload: :objc-sdk:`RLMRealm.waitForUploadCompletionOnQueue:callback: `. +- Download: :objc-sdk:`RLMRealm.waitForUploadCompletionOnQueue:callback: `. + +These methods take a callback, which they dispatch onto the specified queue +after the work item completes or the session expires. diff --git a/source/includes/api-details/swift/sync/manage-sync-sessions-check-network-connection-description.rst b/source/includes/api-details/swift/sync/manage-sync-sessions-check-network-connection-description.rst new file mode 100644 index 0000000000..c92942f313 --- /dev/null +++ b/source/includes/api-details/swift/sync/manage-sync-sessions-check-network-connection-description.rst @@ -0,0 +1,8 @@ +To check the connection state, you can read the ``SyncSession`` instance's +:swift-sdk:`connectionState +` +property directly. + +This property is :apple:`KVO-compliant +`, +so you can observe changes using KVO or even Combine. diff --git a/source/includes/api-details/swift/sync/manage-sync-sessions-check-sync-state-description.rst b/source/includes/api-details/swift/sync/manage-sync-sessions-check-sync-state-description.rst new file mode 100644 index 0000000000..dd57eb09ad --- /dev/null +++ b/source/includes/api-details/swift/sync/manage-sync-sessions-check-sync-state-description.rst @@ -0,0 +1,6 @@ +You can use the :swift-sdk:`SyncSession.state +` +property to check whether the Sync session is active. This property is a +typealias for the :objc-sdk:`RLMSyncSessionState enum +` whose value reflects possible Device Sync +states. diff --git a/source/includes/api-details/swift/sync/manage-sync-sessions-check-upload-download-progress-description.rst b/source/includes/api-details/swift/sync/manage-sync-sessions-check-upload-download-progress-description.rst new file mode 100644 index 0000000000..b0a0886c51 --- /dev/null +++ b/source/includes/api-details/swift/sync/manage-sync-sessions-check-upload-download-progress-description.rst @@ -0,0 +1,22 @@ +.. versionchanged:: 10.50.0 + ``transferredBytes`` and ``transferrableBytes`` deprecated in favor of ``progressEstimate`` + +You can check upload and download progress by registering a token that provides +a ``progressEstimate`` for a given upload or download direction and work scope. +You can set a ``ProgressMode`` to determine the work scope: either observe +indefinitely or unregister the block after the current work item has completed. + +The ``progressEstimate`` value provided by the token is a double whose value +ranges from ``0.0`` to ``1.0``. At ``1.0``, the upload or download is complete. +You can use this ``progressEstimate`` to display a progress indicator or +estimated data transfer percentage. + +You can add a progress notification using the SyncSession instance's +:swift-sdk:`addProgressNotification(for:mode:block:) +` +method. + +This method returns a token that you should retain until you wish +to stop observing upload or download progress. Note that if you +keep the token in a local variable, observation will stop when the +local variable goes out of scope. diff --git a/source/includes/api-details/swift/sync/manage-sync-sessions-get-sync-session-description.rst b/source/includes/api-details/swift/sync/manage-sync-sessions-get-sync-session-description.rst new file mode 100644 index 0000000000..339fdd378c --- /dev/null +++ b/source/includes/api-details/swift/sync/manage-sync-sessions-get-sync-session-description.rst @@ -0,0 +1,2 @@ +You can access the :swift-sdk:`SyncSession ` +on a synced :swift-sdk:`Realm `. diff --git a/source/includes/api-details/swift/sync/manage-sync-sessions-manually-reconnect-sync-sessions-description.rst b/source/includes/api-details/swift/sync/manage-sync-sessions-manually-reconnect-sync-sessions-description.rst new file mode 100644 index 0000000000..389c178484 --- /dev/null +++ b/source/includes/api-details/swift/sync/manage-sync-sessions-manually-reconnect-sync-sessions-description.rst @@ -0,0 +1,4 @@ +.. versionadded:: 10.44.0 + +In Swift SDK version 10.44.0 and later, you can choose to manually trigger a +reconnect attempt with ``SyncSession.reconnect()``. diff --git a/source/includes/api-details/swift/sync/manage-sync-sessions-pause-resume-sync-session-description.rst b/source/includes/api-details/swift/sync/manage-sync-sessions-pause-resume-sync-session-description.rst new file mode 100644 index 0000000000..c9ec0e8c5b --- /dev/null +++ b/source/includes/api-details/swift/sync/manage-sync-sessions-pause-resume-sync-session-description.rst @@ -0,0 +1,5 @@ +You can pause a Sync session by calling +``SyncSession.suspend()`` on the :swift-sdk:`SyncSession +` of a synced database instance. + +You can resume a Sync session with ``SyncSession.resume()``. diff --git a/source/includes/api-details/swift/sync/manage-sync-sessions-wait-for-changes-to-upload-or-download-description.rst b/source/includes/api-details/swift/sync/manage-sync-sessions-wait-for-changes-to-upload-or-download-description.rst new file mode 100644 index 0000000000..929c628023 --- /dev/null +++ b/source/includes/api-details/swift/sync/manage-sync-sessions-wait-for-changes-to-upload-or-download-description.rst @@ -0,0 +1,11 @@ +To wait for all changes to upload or download from your synced database, +call :swift-sdk:`realm.syncSession?.wait(for: ) `. + +This method takes a :swift-sdk:`ProgressDirection ` +argument to specify whether to track upload or download progress. + +You can use these methods with Swift's async/await syntax, or with the +callback syntax. The callback version, +:swift-sdk:`realm.syncSession?.wait(for:queue:block:) `, +can take a queue to dispatch the callback onto, and a block to invoke when +waiting is complete. diff --git a/source/includes/api-details/typescript/sync/manage-sync-sessions-wait-for-changes-to-upload-or-download-description.rst b/source/includes/api-details/typescript/sync/manage-sync-sessions-wait-for-changes-to-upload-or-download-description.rst new file mode 100644 index 0000000000..aa5918a509 --- /dev/null +++ b/source/includes/api-details/typescript/sync/manage-sync-sessions-wait-for-changes-to-upload-or-download-description.rst @@ -0,0 +1,20 @@ +To asynchronously wait for all changes to upload to Atlas from your synced +database, call :js-sdk:`uploadAllLocalChanges() +`. This method returns +true when all changes have been uploaded. + +.. literalinclude:: /examples/generated/node/v12/configure-and-open-synced-realm.test.snippet.wait-for-upload.ts + :language: typescript + +To asynchronously wait for all changes on Atlas to download from the +Device Sync server to your synced database, call +:js-sdk:`downloadAllServerChanges() `. +This method returns true when all changes have been downloaded. + +You can specify a request timeout on the :js-sdk:`App configuration +`. With a timeout specified, you can set +``cancelWaitsOnNonFatalErrors`` on your :js-sdk:`BaseSyncConfiguration +`. When ``true`` and the timeout interval +arrives, any any outstanding work that is awaiting uploads and downloads +cancels. When this setting is false, awaiting uploads and downloads does +not cancel because the SDK treats these timeouts as non-fatal errors. diff --git a/source/includes/sdk-examples/sync/manage-sync-sessions-check-network-connection.rst b/source/includes/sdk-examples/sync/manage-sync-sessions-check-network-connection.rst new file mode 100644 index 0000000000..cfebc51b5b --- /dev/null +++ b/source/includes/sdk-examples/sync/manage-sync-sessions-check-network-connection.rst @@ -0,0 +1,68 @@ +.. tabs-drivers:: + + tabs: + - id: cpp + content: | + + .. literalinclude:: /examples/generated/cpp/sync-session.snippet.unregister-observation-token.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/generated/dotnet/ProgressNotifications.snippet.connection-state.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/manage_sync_session_test.snippet.monitor-network-connection.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/generated/java/sync/SyncDataTest.snippet.check-current-network-connection.java + :language: java + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/generated/java/sync/SyncDataTest.snippet.check-current-network-connection.kt + :language: kotlin + + - id: javascript + content: | + + .. literalinclude:: /examples/generated/node/device-sync.snippet.check-network-connection.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/ManageSyncSession.snippet.monitor-network-connection.kt + :language: kotlin + + - id: objectivec + content: | + + .. literalinclude:: /examples/generated/code/start/Sync.snippet.check-network-connection-setup.m + :language: objectivec + + You can then attach an observer instance to the RLMSyncSession + object. Be sure to remove the observer when finished. + + .. literalinclude:: /examples/generated/code/start/Sync.snippet.check-network-connection.m + :language: objectivec + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/Sync.snippet.check-network-connection.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/generated/node/device-sync.snippet.check-network-connection.ts + :language: typescript diff --git a/source/includes/sdk-examples/sync/manage-sync-sessions-check-sync-state.rst b/source/includes/sdk-examples/sync/manage-sync-sessions-check-sync-state.rst new file mode 100644 index 0000000000..d6eaa8f7f8 --- /dev/null +++ b/source/includes/sdk-examples/sync/manage-sync-sessions-check-sync-state.rst @@ -0,0 +1,62 @@ +.. tabs-drivers:: + + tabs: + - id: cpp + content: | + + .. literalinclude:: /examples/generated/cpp/sync-session.snippet.sync-state.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.java + :language: java + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example-java-kotlin.kt + :language: kotlin + + - id: javascript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.kt + :language: kotlin + + - id: objectivec + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.m + :language: objectivec + + - id: swift + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.ts + :language: typescript diff --git a/source/includes/sdk-examples/sync/manage-sync-sessions-check-upload-download-progress.rst b/source/includes/sdk-examples/sync/manage-sync-sessions-check-upload-download-progress.rst new file mode 100644 index 0000000000..f69cc86741 --- /dev/null +++ b/source/includes/sdk-examples/sync/manage-sync-sessions-check-upload-download-progress.rst @@ -0,0 +1,62 @@ +.. tabs-drivers:: + + tabs: + - id: cpp + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/manage_sync_session_test.snippet.monitor-progress.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.java + :language: java + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api-java-kotlin.kt + :language: kotlin + + - id: javascript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.kt + :language: kotlin + + - id: objectivec + content: | + + .. literalinclude:: /examples/generated/code/start/Sync.snippet.check-progress.m + :language: objectivec + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/Sync.snippet.check-progress-estimate.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.ts + :language: typescript diff --git a/source/includes/sdk-examples/sync/manage-sync-sessions-get-sync-session.rst b/source/includes/sdk-examples/sync/manage-sync-sessions-get-sync-session.rst new file mode 100644 index 0000000000..6e70e78649 --- /dev/null +++ b/source/includes/sdk-examples/sync/manage-sync-sessions-get-sync-session.rst @@ -0,0 +1,64 @@ +.. tabs-drivers:: + + tabs: + - id: cpp + content: | + + .. literalinclude:: /examples/generated/cpp/sync-session.snippet.sync-session.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.java + :language: java + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example-java-kotlin.kt + :language: kotlin + + - id: javascript + content: | + + .. code-block:: javascript + + const realm = await Realm.open(config); + const syncSession = realm.syncSession; + + - id: kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.kt + :language: kotlin + + - id: objectivec + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.m + :language: objectivec + + - id: swift + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.ts + :language: typescript diff --git a/source/includes/sdk-examples/sync/manage-sync-sessions-manually-reconnect-sync-sessions.rst b/source/includes/sdk-examples/sync/manage-sync-sessions-manually-reconnect-sync-sessions.rst new file mode 100644 index 0000000000..7c1f791acc --- /dev/null +++ b/source/includes/sdk-examples/sync/manage-sync-sessions-manually-reconnect-sync-sessions.rst @@ -0,0 +1,62 @@ +.. tabs-drivers:: + + tabs: + - id: cpp + content: | + + .. literalinclude:: /examples/generated/cpp/sync-session.snippet.reconnect.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/manage_sync_session_test.snippet.session-reconnect.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.java + :language: java + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api-java-kotlin.kt + :language: kotlin + + - id: javascript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/ManageSyncSession.snippet.app-sync-reconnect.kt + :language: kotlin + + - id: objectivec + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.m + :language: objectivec + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/Sync.snippet.sync-session-reconnect.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.ts + :language: typescript diff --git a/source/includes/sdk-examples/sync/manage-sync-sessions-pause-resume.rst b/source/includes/sdk-examples/sync/manage-sync-sessions-pause-resume.rst new file mode 100644 index 0000000000..1f341e208a --- /dev/null +++ b/source/includes/sdk-examples/sync/manage-sync-sessions-pause-resume.rst @@ -0,0 +1,64 @@ +.. tabs-drivers:: + + tabs: + - id: cpp + content: | + + .. literalinclude:: /examples/generated/cpp/sync-session.snippet.resume.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/generated/dotnet/DataSyncExamples.snippet.pause-synced-realm.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/manage_sync_session_test.snippet.pause-resume-sync.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/generated/java/sync/SyncDataTest.snippet.resume-sync-session.java + :language: java + :copyable: false + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/generated/java/sync/SyncDataTest.snippet.resume-sync-session.kt + :language: kotlin + :copyable: false + + - id: javascript + content: | + + .. literalinclude:: /examples/generated/node/device-sync.snippet.pause-sync-session.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/ManageSyncSession.snippet.pause-resume-sync.kt + :language: kotlin + + - id: objectivec + content: | + + .. literalinclude:: /examples/generated/code/start/Sync.snippet.pause-resume-sync-session.m + :language: objectivec + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/Sync.snippet.pause-resume-sync-session.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/generated/node/device-sync.snippet.pause-sync-session.ts + :language: typescript diff --git a/source/includes/sdk-examples/sync/manage-sync-sessions-wait-for-changes-to-upload-or-download.rst b/source/includes/sdk-examples/sync/manage-sync-sessions-wait-for-changes-to-upload-or-download.rst new file mode 100644 index 0000000000..cd146d9662 --- /dev/null +++ b/source/includes/sdk-examples/sync/manage-sync-sessions-wait-for-changes-to-upload-or-download.rst @@ -0,0 +1,69 @@ +.. tabs-drivers:: + + tabs: + - id: cpp + content: | + + .. literalinclude:: /examples/generated/cpp/sync-session.snippet.wait-for-download.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/generated/dotnet/ProgressNotifications.snippet.wait-for-changes-to-download-async-progress-notification.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.java + :language: java + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example-java-kotlin.kt + :language: kotlin + + - id: javascript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/ManageSyncSession.snippet.wait-upload-download.kt + :language: kotlin + + - id: objectivec + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.m + :language: objectivec + + - id: swift + content: | + + **Async/Await** + + .. literalinclude:: /examples/generated/code/start/Sync.snippet.awaitable-wait-for-upload-download.swift + :language: swift + + **Callback** + + .. literalinclude:: /examples/generated/code/start/Sync.snippet.callback-wait-for-upload-download.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/generated/node/v12/configure-and-open-synced-realm.test.snippet.wait-for-download.ts + :language: typescript diff --git a/source/includes/when-to-pause-sync.rst b/source/includes/when-to-pause-sync.rst deleted file mode 100644 index e89c39b836..0000000000 --- a/source/includes/when-to-pause-sync.rst +++ /dev/null @@ -1,36 +0,0 @@ -For most applications, there is no need to manually pause and resume a sync -session. However, there are a few circumstances under which you may want to -pause or suspend a sync session: - -- You only want to sync after the user takes a specific action -- You only want to sync during a certain time of the day -- You don't want to attempt to sync when there is poor network connectivity -- You want to explicitly force a sync session to connect - -In the case of poor network connectivity, continually trying to establish -a network connection can drain the user's device battery. - -The case of explicitly forcing a sync session to connect is most commonly -related to being offline for some time. The sync client attempts to -connect, and upon failure, goes into exponential backoff. After being offline -for a long time, the client may not immediately reconnect. Pausing and -resuming the sync session explicitly forces the connection. - -When you do pause a sync session, keep these things in mind: - -- If the client may be offline longer than the :ref:`client maximum offline - time `, the client will be unable to resume - syncing and must perform a :ref:`client reset `. -- Pausing a sync session pauses it in both directions. Changes that your app - makes on the device do not sync with the backend, *and* changes to the - data in the backend or on other devices do not sync to the device. There - is no way to pause only uploads or pause only downloads. -- Do not pause a sync session if you want a client to permanently stop - syncing with the backend. To permanently stop syncing, - copy the contents of the synced realm into a non-synced - realm, and use the non-synced realm in the client. - -*Do not* pause sync to stop syncing for indefinite time periods or time -ranges in months and years. The functionality is not designed or tested -for these use cases. You could encounter a range of issues when using it -this way. diff --git a/source/sdk/sync/manage-sync-sessions.txt b/source/sdk/sync/manage-sync-sessions.txt index 49254167b0..3168fee8c7 100644 --- a/source/sdk/sync/manage-sync-sessions.txt +++ b/source/sdk/sync/manage-sync-sessions.txt @@ -6,21 +6,527 @@ Manage Sync Sessions .. meta:: :description: Access the Sync session to check network connection, wait for uploads and downloads, and check Sync progress. - :keywords: code example + :keywords: Realm, C++ SDK, Flutter SDK, Kotlin SDK, Java SDK, .NET SDK, Node.js SDK, Swift SDK, code example .. facet:: :name: genre :values: reference +.. facet:: + :name: programming_language + :values: cpp, csharp, dart, java, javascript/typescript, kotlin, objective-c, swift + .. contents:: On this page :local: :backlinks: none :depth: 2 :class: singlecol -Placeholder page for information about managing sync sessions. +.. tabs-selector:: drivers + +Opening a synced database starts a Sync session for that database. +Atlas Device SDK provides methods to: + +- Check the network connection state. +- Manually pause and resume a Sync session. +- Wait for changes to upload or download. +- Check upload or download progress. +- Manually reconnect Sync sessions after a device has been offline. + +You can also define the Sync connection behavior. App Services defaults to +sharing a single connection to the server for all opened synced databases. +The connection to the server is independent of the Sync session, and is based +on the App Services user. + +You can change the Sync connection behavior from the :ref:`App client +configuration `. + +.. _sdks-access-sync-session: + +Get the Sync Session +-------------------- + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/sync/manage-sync-sessions-get-sync-session-description.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/sync/manage-sync-sessions-get-sync-session-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/sync/manage-sync-sessions-get-sync-session-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/sync/manage-sync-sessions-get-sync-session-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/sync/manage-sync-sessions-get-sync-session-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/sync/manage-sync-sessions-get-sync-session-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/sync/manage-sync-sessions-get-sync-session-description.rst + + .. tab:: + :tabid: objectivec + + .. include:: /includes/api-details/objectivec/sync/manage-sync-sessions-get-sync-session-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/sync/manage-sync-sessions-get-sync-session-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/sync/manage-sync-sessions-get-sync-session-js-ts-description.rst + +.. include:: /includes/sdk-examples/sync/manage-sync-sessions-get-sync-session.rst + +.. _sdks-check-network-connection: + +Check the Network Connection +---------------------------- + +The SDK's *offline-first* design means that you generally don't need to check +the current network connection state. However, the SDK provides a connection +state property if your app calls for some indication of connection state. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/sync/manage-sync-sessions-check-network-connection-description.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/sync/manage-sync-sessions-check-network-connection-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/sync/manage-sync-sessions-check-network-connection-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/sync/manage-sync-sessions-check-network-connection-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/sync/manage-sync-sessions-check-network-connection-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/sync/manage-sync-sessions-check-network-connection-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/sync/manage-sync-sessions-check-network-connection-description.rst + + .. tab:: + :tabid: objectivec + + .. include:: /includes/api-details/objectivec/sync/manage-sync-sessions-check-network-connection-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/sync/manage-sync-sessions-check-network-connection-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/sync/manage-sync-sessions-check-network-connection-js-ts-description.rst + +.. include:: /includes/sdk-examples/sync/manage-sync-sessions-check-network-connection.rst + +.. _sdks-check-sync-state: + +Check the Sync State +-------------------- + +You can check the state of the Sync session itself to determine whether the +sync session is active. The Sync connection state is distinct from the network +connection state. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/sync/manage-sync-sessions-check-sync-state-description.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/sync/manage-sync-sessions-check-sync-state-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/sync/manage-sync-sessions-check-sync-state-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/sync/manage-sync-sessions-check-sync-state-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/sync/manage-sync-sessions-check-sync-state-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/sync/manage-sync-sessions-check-sync-state-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/sync/manage-sync-sessions-check-sync-state-description.rst + + .. tab:: + :tabid: objectivec + + .. include:: /includes/api-details/objectivec/sync/manage-sync-sessions-check-sync-state-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/sync/manage-sync-sessions-check-sync-state-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/sync/manage-sync-sessions-check-sync-state-js-ts-description.rst + +.. include:: /includes/sdk-examples/sync/manage-sync-sessions-check-sync-state.rst .. _sdks-pause-resume-sync: Pause or Resume a Sync Session ------------------------------ + +You can pause and resume the sync session on the database. Pausing a sync +session only suspends that database's sync session. If you have more than one +open database, and you have enabled multiple sync sessions, pausing one sync +session does not affect the sync sessions for other databases. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/sync/manage-sync-sessions-pause-resume-sync-session-description.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/sync/manage-sync-sessions-pause-resume-sync-session-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/sync/manage-sync-sessions-pause-resume-sync-session-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/sync/manage-sync-sessions-pause-resume-sync-session-java-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/sync/manage-sync-sessions-pause-resume-sync-session-kotlin-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/sync/manage-sync-sessions-pause-resume-sync-session-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/sync/manage-sync-sessions-pause-resume-sync-session-description.rst + + .. tab:: + :tabid: objectivec + + .. include:: /includes/api-details/objectivec/sync/manage-sync-sessions-pause-resume-sync-session-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/sync/manage-sync-sessions-pause-resume-sync-session-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/sync/manage-sync-sessions-pause-resume-sync-session-js-ts-description.rst + +.. include:: /includes/sdk-examples/sync/manage-sync-sessions-pause-resume.rst + +When to Pause a Sync Session +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For most applications, there is no need to manually pause and resume a sync +session. However, there are a few circumstances under which you may want to +pause or suspend a sync session: + +- You only want to sync after the user takes a specific action +- You only want to sync during a certain time of the day +- You don't want to attempt to sync when there is poor network connectivity +- You want to force the SDK to re-evaluate the user's permissions after making + a permissions-related change + +In the case of poor network connectivity, continually trying to establish +a network connection can drain the user's device battery. + +The case of explicitly forcing a sync session to connect is most commonly +related to being offline for some time. The sync client attempts to +connect, and upon failure, goes into exponential backoff. After being offline +for a long time, the client may not immediately reconnect. Pausing and +resuming the sync session explicitly forces the connection. + +When you do pause a sync session, keep these things in mind: + +- If the client may be offline longer than the :ref:`client maximum offline + time `, the client will be unable to resume + syncing and must perform a :ref:`client reset `. +- Pausing a sync session pauses it in both directions. Changes that your app + makes on the device do not sync with the backend, *and* changes to the + data in the backend or on other devices do not sync to the device. There + is no way to pause only uploads or pause only downloads. +- Do not pause a sync session if you want a client to permanently stop + syncing with the backend. To permanently stop syncing, + copy the contents of the synced database into a non-synced + database, and use the non-synced database in the client. + +*Do not* pause sync to stop syncing for indefinite time periods or time +ranges in months and years. The functionality is not designed or tested +for these use cases. You could encounter a range of issues when using it +this way. + +.. _sdks-sync-session-wait-for-changes: + +Wait for Changes to Upload or Download +-------------------------------------- + +You can wait for changes to upload or download. You might want to wait for +changes to upload or download before you close a synced database, pause a +Sync session, or change Sync subscriptions. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/sync/manage-sync-sessions-wait-for-changes-to-upload-or-download-description.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/sync/manage-sync-sessions-wait-for-changes-to-upload-or-download-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/sync/manage-sync-sessions-wait-for-changes-to-upload-or-download-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/sync/manage-sync-sessions-wait-for-changes-to-upload-or-download-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/sync/manage-sync-sessions-wait-for-changes-to-upload-or-download-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/sync/manage-sync-sessions-wait-for-changes-to-upload-or-download-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/sync/manage-sync-sessions-wait-for-changes-to-upload-or-download-description.rst + + .. tab:: + :tabid: objectivec + + .. include:: /includes/api-details/objectivec/sync/manage-sync-sessions-wait-for-changes-to-upload-or-download-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/sync/manage-sync-sessions-wait-for-changes-to-upload-or-download-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/typescript/sync/manage-sync-sessions-wait-for-changes-to-upload-or-download-description.rst + +.. include:: /includes/sdk-examples/sync/manage-sync-sessions-wait-for-changes-to-upload-or-download.rst + +.. _sdks-check-upload-and-download-progress: + +Check Upload and Download Progress +---------------------------------- + +You can check the upload and download progress for a Sync session. You might +want to check upload or download progress when you want to provide a progress +estimate indicator in your app's user interface. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/sync/manage-sync-sessions-check-upload-and-download-progress-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/sync/manage-sync-sessions-check-upload-download-progress-description.rst + + .. tab:: + :tabid: java + + .. tab:: + :tabid: java-kotlin + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/sync/manage-sync-sessions-check-upload-download-progress-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/sync/manage-sync-sessions-check-upload-download-progress-description.rst + + .. tab:: + :tabid: objectivec + + .. include:: /includes/api-details/objectivec/sync/manage-sync-sessions-check-upload-download-progress-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/sync/manage-sync-sessions-check-upload-download-progress-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/sync/manage-sync-sessions-check-upload-download-progress-js-ts-description.rst + +.. include:: /includes/sdk-examples/sync/manage-sync-sessions-check-upload-download-progress.rst + +.. _sdks-reconnect-sync-sessions: + +Manually Reconnect All Sync Sessions +------------------------------------ + +The SDK automatically detects when a device regains connectivity after being +offline and attempts to reconnect using an incremental backoff strategy. +For example, on Apple platforms, the SDK listens for network change +notifications and automatically triggers a reconnect immediately after +receiving one. + +You can choose to manually trigger a reconnect attempt with with the 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 the SDK's automatic reconnect detection. + +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. + +.. important:: Cannot Reconnect Within Socket Read Timeout Duration + + The SDK has an internal default socket read timeout of 2 minutes. The + SDK times out if a read operation does not receive any data within a + 2-minute window. If you call the reconnect method within that window, the + SDK does *not* attempt to reconnect. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/sync/manage-sync-sessions-manually-reconnect-sync-sessions-description.rst + + .. tab:: + :tabid: csharp + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/sync/manage-sync-sessions-manually-reconnect-sync-sessions-description.rst + + .. tab:: + :tabid: java + + .. tab:: + :tabid: java-kotlin + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/sync/manage-sync-sessions-manually-reconnect-sync-sessions-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/sync/manage-sync-sessions-manually-reconnect-sync-sessions-description.rst + + .. tab:: + :tabid: objectivec + + .. include:: /includes/api-details/objectivec/sync/manage-sync-sessions-manually-reconnect-sync-sessions-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/sync/manage-sync-sessions-manually-reconnect-sync-sessions-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/sync/manage-sync-sessions-manually-reconnect-sync-sessions-js-ts-description.rst + +.. include:: /includes/sdk-examples/sync/manage-sync-sessions-manually-reconnect-sync-sessions.rst +