(DOCSP-39535): Consolidate Manage Sync Subscriptions page

source/includes/api-details/cpp/sync/manage-sync-subscriptions-access-subscription-set-description.rst

@@ -0,0 +1,7 @@
+You can access the subscription set through the ``subscriptions()`` public
+member function of a :cpp-sdk:`realm <structrealm_1_1db.html>`. This 
+provides the :cpp-sdk:`sync_subscription_set 
+<structrealm_1_1sync__subscription__set.html>` where you can use the 
+``size()``, ``find()``, or ``update()`` member functions. You perform all
+operations to add, find, update, remove, or watch subscriptions through this
+property.

source/includes/api-details/cpp/sync/manage-sync-subscriptions-add-subscription-description.rst

@@ -0,0 +1,10 @@
+To add a subscription:
+
+1. Open the synced database.
+#. Access the database's ``subscriptions`` property.
+#. Open a subscription ``update`` block.
+#. Call the ``add`` method with the object type to append the new subscription
+   to the subscription set. Optionally, add a query to subscribe to only a
+   subset of the objects that match the query.
+
+.. include:: /includes/note-cpp-supports-subset-of-rql.rst

source/includes/api-details/cpp/sync/manage-sync-subscriptions-change-named-subscription-description.rst

@@ -0,0 +1,8 @@
+To update a subscription set, use the ``subscription().updates()`` function.
+This gives you access to a :cpp-sdk:`mutable_sync_subscription_set 
+<structrealm_1_1mutable__sync__subscription__set.html>` where you can use the
+``update_subscription()`` function to update a specific :cpp-sdk:`sync_subscription 
+<structrealm_1_1sync__subscription.html>`.
+
+You can change a ``sync_subscription``'s query in an update. You can add, remove,
+or update the query string for a given ``sync_subscription``.

source/includes/api-details/cpp/sync/manage-sync-subscriptions-change-unnamed-subscription-not-supported.rst

@@ -0,0 +1,7 @@
+C++ does not provide the ability to change an unnamed subscription. If you know
+in advance that your app may need to change subscriptions, :ref:`create the
+subscription with a name <sdks-add-named-subscription>`.
+
+Alternately, you can :ref:`remove all subscriptions
+<sdks-remove-all-subscriptions>`, and :ref:`create new subscriptions
+<sdks-sync-subscriptions-add-subscription>` with the desired query.

source/includes/api-details/cpp/sync/manage-sync-subscriptions-find-subscription-description.rst

@@ -0,0 +1,4 @@
+To find a specific subscription, call the ``subscriptions().find()`` method
+with the name of a subscription.
+
+You cannot find unnamed subscriptions in C++.

source/includes/api-details/cpp/sync/manage-sync-subscriptions-refresh-realm-description.rst

@@ -0,0 +1,6 @@
+After you update subscriptions, call ``refresh()`` on the :cpp-sdk:`realm 
+<structrealm_1_1db.html>`. This updates the database and outstanding objects 
+managed by the database to point to the most recent data.
+
+.. literalinclude:: /examples/generated/cpp/flexible-sync.snippet.refresh-the-realm.cpp
+   :language: cpp

source/includes/api-details/cpp/sync/manage-sync-subscriptions-remove-all-subscriptions-description.rst

@@ -0,0 +1,2 @@
+You can remove all subscriptions in a subscription set using the ``clear()`` 
+function.

source/includes/api-details/cpp/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-not-supported.rst

@@ -0,0 +1,8 @@
+C++ does not provide the ability to remove all subscriptions to a specific
+object type. If you know in advance that your app may need to remove
+subscriptions, :ref:`create the subscription with a name
+<sdks-add-named-subscription>`.
+
+Alternately, you can :ref:`remove all subscriptions
+<sdks-remove-all-subscriptions>`, and then :ref:`add subscriptions
+<sdks-sync-subscriptions-add-subscription>` that your app still needs.

source/includes/api-details/cpp/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-not-supported.rst

@@ -0,0 +1,5 @@
+C++ does not provide the ability to remove all unnamed subscriptions.
+
+Instead, you can :ref:`remove all subscriptions
+<sdks-remove-all-subscriptions>`, and then :ref:`add subscriptions
+<sdks-sync-subscriptions-add-subscription>` that your app still needs.

source/includes/api-details/cpp/sync/manage-sync-subscriptions-remove-named-subscription-description.rst

@@ -0,0 +1,4 @@
+You can remove a specific subscription by name using the ``remove()`` function
+inside a ``subscription().updates()`` block. Removing a subscription by name
+throws an error if the subscription does not exist, so you should check for a
+subscription before removing it.

source/includes/api-details/cpp/sync/manage-sync-subscriptions-remove-subscription-by-reference-not-supported.rst

@@ -0,0 +1,7 @@
+C++ does not provide the ability to remove a subscription by reference. If
+you know in advance that your app may need to remove subscriptions,
+:ref:`create the subscription with a name <sdks-add-named-subscription>`.
+
+Alternately, you can :ref:`remove all subscriptions
+<sdks-remove-all-subscriptions>`, and then :ref:`add subscriptions
+<sdks-sync-subscriptions-add-subscription>` that your app still needs.

source/includes/api-details/cpp/sync/manage-sync-subscriptions-remove-unnamed-subscription-not-supported.rst

@@ -0,0 +1,7 @@
+C++ does not provide the ability to remove a single unnamed subscription. If
+you know in advance that your app may need to remove subscriptions,
+:ref:`create the subscription with a name <sdks-add-named-subscription>`.
+
+Alternately, you can :ref:`remove all subscriptions
+<sdks-remove-all-subscriptions>`, and then :ref:`add subscriptions
+<sdks-sync-subscriptions-add-subscription>` that your app still needs.

source/includes/api-details/cpp/sync/manage-sync-subscriptions-subscription-set-state-not-supported.rst

@@ -0,0 +1 @@
+C++ does not currently provide an API to check the state of a subscription set.

source/includes/api-details/cpp/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-not-supported.rst

@@ -0,0 +1 @@
+C++ does not currently provide an API to wait for subscription changes to sync.

source/includes/api-details/csharp/sync/manage-sync-subscriptions-access-subscription-set-description.rst

@@ -0,0 +1,5 @@
+You can access the :dotnet-sdk:`SubscriptionSet
+<reference/Realms.Sync.SubscriptionSet.html>` through the database
+:dotnet-sdk:`Subscriptions <reference/Realms.Realm.html#Realms_Realm_Subscriptions>`
+property. You perform all operations to add, find, update, remove, or watch
+subscriptions through this property.

source/includes/api-details/csharp/sync/manage-sync-subscriptions-add-subscription-description.rst

@@ -0,0 +1,20 @@
+To add a subscription:
+
+1. Open the synced database.
+#. Access the database's :dotnet-sdk:`Realm.Subscriptions <reference/Realms.Realm.html#Realms_Realm_Subscriptions>` 
+   property.
+#. Open a subscription ``Update`` block.
+#. Create a subscription to a specific object type. Optionally add a query to
+   subscribe to only a subset of the objects that match the query.
+#. Call the ``Subscriptions.Add`` method with the subscription you just created
+   to append the new subscription to the subscription set.
+
+Alternately, to add a subscription to an existing subscription set, create 
+the query and then call :dotnet-sdk:`IQueryable.SubscribeAsync()
+<reference/Realms.CollectionExtensions.html#Realms_CollectionExtensions_SubscribeAsync__1_System_Linq_IQueryable___0__Realms_Sync_SubscriptionOptions_Realms_Sync_WaitForSyncMode_System_Nullable_System_Threading_CancellationToken__>`.
+
+The ``SubscribeAsync`` method is shorthand for using :dotnet-sdk:`SubscriptionSet.Update()
+<reference/Realms.Sync.SubscriptionSet.html#Realms_Sync_SubscriptionSet_Update_System_Action_>`
+to create an update block, and then calling the :dotnet-sdk:`SubscriptionSet.Add()
+<reference/Realms.Sync.SubscriptionSet.html#Realms_Sync_SubscriptionSet_Add__1_System_Linq_IQueryable___0__Realms_Sync_SubscriptionOptions_>`
+method on the ``SubscriptionSet``.

source/includes/api-details/csharp/sync/manage-sync-subscriptions-change-named-subscription-description.rst

@@ -0,0 +1,12 @@
+You can update a named subscription with a new query. To update a subscription's
+query, pass the new query and a subscription option with the name of the
+subscription that you want to update to the
+``SubscriptionSet.Add()`` method. Like adding a new subscription,
+you must update a subscription within an update block by calling
+``SubscriptionSet.Update()`` method.
+
+The ``SubscriptionOptions.UpdateExisting`` field must be set to ``true``, or
+else attempting to change the subscription throws an exception.
+
+In the following example, long running tasks are re-defined to be any tasks that
+have taken more than 130 minutes.

source/includes/api-details/csharp/sync/manage-sync-subscriptions-change-unnamed-subscription-not-supported.rst

@@ -0,0 +1,7 @@
+C# does not provide the ability to change an unnamed subscription. If you know
+in advance that your app may need to change subscriptions, :ref:`create the
+subscription with a name <sdks-add-named-subscription>`.
+
+Alternately, you can :ref:`delete the unnamed subscription
+<sdks-remove-subscriptions>`, and :ref:`create a new subscription
+<sdks-sync-subscriptions-add-subscription>` with the desired query.

source/includes/api-details/csharp/sync/manage-sync-subscriptions-find-subscription-description.rst

@@ -0,0 +1,8 @@
+To find a specific subscription by name, call the 
+:dotnet-sdk:`Find() <reference/Realms.Sync.SubscriptionSet.html#Realms_Sync_SubscriptionSet_Find_System_String_>`
+method with the name of a subscription.
+
+You can also find a subscription matching a specific query by calling the
+:dotnet-sdk:`Find()
+<reference/Realms.Sync.SubscriptionSet.html#Realms_Sync_SubscriptionSet_Find__1_System_Linq_IQueryable___0__>`
+method with an IQueryable<T> argument.

source/includes/api-details/csharp/sync/manage-sync-subscriptions-remove-all-subscriptions-description.rst

@@ -0,0 +1,8 @@
+Within an update block, you can remove all subscriptions from the
+subscriptions set. Call the :dotnet-sdk:`RemoveAll()
+<reference/Realms.Sync.SubscriptionSet.html#Realms_Sync_SubscriptionSet_RemoveAll_System_Boolean_>`
+method on the ``SubscriptionSet``.
+
+By default, the ``RemoveAll()`` method only removes unnamed subscriptions. 
+Set the optional ``removedName`` boolean to ``true`` to also remove named
+subscriptions.

source/includes/api-details/csharp/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-description.rst

@@ -0,0 +1,14 @@
+Within an update block, you can remove remove all unnamed subscriptions of a
+class by passing the class name as a string to the
+:dotnet-sdk:`RemoveAll("ClassName")
+<reference/Realms.Sync.SubscriptionSet.html#Realms_Sync_SubscriptionSet_RemoveAll_System_String_System_Boolean_>`
+method. The ``RemoveAll()`` method has an optional second argument that is a
+boolean, ``removedName``, which also removes the named subscriptions if it is
+set to ``true``. ``removedName`` is set to false by default.
+
+Alternatively, you can remove all unnamed subscriptions of an object type
+with :dotnet-sdk:`RemoveAll()
+<reference/Realms.Sync.SubscriptionSet.html#Realms_Sync_SubscriptionSet_RemoveAll__1_System_Boolean_>`.
+The ``RemoveAll<Type>()`` method has an optional boolean ``removedName`` argument 
+that also removes the named subscriptions if it is set to ``true``. The ``removedName`` 
+argument is set to false by default.

source/includes/api-details/csharp/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-description.rst

@@ -0,0 +1,5 @@
+Within an update block, you can remove all unnamed subscriptions from the
+subscriptions set. Call the :dotnet-sdk:`RemoveAll()
+<reference/Realms.Sync.SubscriptionSet.html#Realms_Sync_SubscriptionSet_RemoveAll_System_Boolean_>`
+method on the ``SubscriptionSet``, with the optional boolean ``removedName``
+argument set to false. This removes only unnamed subscriptions.

source/includes/api-details/csharp/sync/manage-sync-subscriptions-remove-named-subscription-description.rst

@@ -0,0 +1,4 @@
+Within an update block, you can remove a specific subscription by name. Pass the 
+name to the :dotnet-sdk:`Remove()
+<reference/Realms.Sync.SubscriptionSet.html#Realms_Sync_SubscriptionSet_Remove_System_String_>`
+method on the ``SubscriptionSet``.

source/includes/api-details/csharp/sync/manage-sync-subscriptions-remove-subscription-by-reference-description.rst

@@ -0,0 +1,4 @@
+Within an update block, you can remove a specific subscription by reference.
+Pass the subscription to the :dotnet-sdk:`Remove()
+<reference/Realms.Sync.SubscriptionSet.html#Realms_Sync_SubscriptionSet_Remove_System_String_>`
+method on the ``SubscriptionSet``.

source/includes/api-details/csharp/sync/manage-sync-subscriptions-remove-unnamed-subscription-description.rst

@@ -0,0 +1,7 @@
+Within an update block, you can remove an unnamed subscription by its query.
+Pass the query to the :dotnet-sdk:`Remove()
+<reference/Realms.Sync.SubscriptionSet.html#Realms_Sync_SubscriptionSet_Remove__1_System_Linq_IQueryable___0__System_Boolean_>`
+method on the ``SubscriptionSet``.
+
+In the following example, the subscription to tasks with an owner named 'Ben' is
+removed from the subscriptions set.

source/includes/api-details/csharp/sync/manage-sync-subscriptions-set-initial-subscriptions-description.rst

@@ -0,0 +1,8 @@
+You can bootstrap the database with an initial subscription set
+when you open it with a :dotnet-sdk:`FlexibleSyncConfiguration  
+<reference/Realms.Sync.FlexibleSyncConfiguration.html>`. Set the 
+:dotnet-sdk:`PopulateInitialSubscriptions 
+<reference/Realms.Sync.FlexibleSyncConfiguration.html#Realms_Sync_FlexibleSyncConfiguration_PopulateInitialSubscriptions>` 
+parameter to a callback that is invoked when the database instance is created.
+Add the queries you want to use to bootstrap the database, as shown in the
+following example.

source/includes/api-details/csharp/sync/manage-sync-subscriptions-subscription-set-state-description.rst

@@ -0,0 +1,9 @@
+Use the :dotnet-sdk:`SubscriptionSet.State
+<reference/Realms.Sync.SubscriptionSet.html#Realms_Sync_SubscriptionSet_State>`
+property to read the current state of the subscription set.
+
+The ``Superseded`` state is a :dotnet-sdk:`SubscriptionSetState
+<reference/Realms.Sync.SubscriptionSetState.html>` that can occur when another
+thread updates a subscription on a different instance of the subscription set.
+If the state becomes ``Superseded``, you must obtain a new instance of the
+subscription set before you can update it.

source/includes/api-details/csharp/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-description.rst

@@ -0,0 +1,17 @@
+Use the :dotnet-sdk:`SubscriptionSet.WaitForSynchronizationAsync()
+<reference/Realms.Sync.SubscriptionSet.html#Realms_Sync_SubscriptionSet_WaitForSynchronizationAsync_System_Nullable_System_Threading_CancellationToken__>`
+method to wait for the server to acknowledge this set of subscriptions. If the
+server rejects the change, the :dotnet-sdk:`SubscriptionSetState
+<reference/Realms.Sync.SubscriptionSetState.html>` will be an error state, and
+an exception will be thrown.
+
+An exception may occur if: 
+
+- An unsupported query is subscribed to. Subscribing to an unsupported query 
+  will pause synchronization. To resume synchronization, :ref:`remove the 
+  unsupported query <sdks-remove-subscriptions>`.
+
+- You are performing an invalid action, such as adding an object that does not 
+  match a subscription. This triggers a :ref:`client reset <client-resets>`: 
+  data is erased from the device, and a new copy of the data is created without 
+  any subscriptions in the set.

source/includes/api-details/dart/sync/manage-sync-subscriptions-access-subscription-set-description.rst

@@ -0,0 +1,5 @@
+you can access a
+:flutter-sdk:`SubscriptionSet <realm/SubscriptionSet-class.html>`, a
+collection of subscriptions, through the ``Realm.subscriptions`` property.
+You perform all operations to add, find, update, remove, or watch
+subscriptions through this property.

source/includes/api-details/dart/sync/manage-sync-subscriptions-add-subscription-description.rst

@@ -0,0 +1,11 @@
+To add a subscription:
+
+1. Open the synced database.
+#. Access the database's ``subscriptions`` property to interact with the
+   :flutter-sdk:`SubscriptionSet <realm/SubscriptionSet-class.html>`.
+#. Open a subscription ``update`` block by calling 
+   :flutter-sdk:`SubscriptionSet.update() <realm/SubscriptionSet/update.html>`.
+#. Call the ``add`` method to append the new subscription to the
+   subscription set.
+#. Pass a ``RealmResults`` query that you can create using the
+   :ref:`Realm Query Language query <rql>`. Optionally, add a query name.

source/includes/api-details/dart/sync/manage-sync-subscriptions-change-named-subscription-description.rst

@@ -0,0 +1,10 @@
+You can update a named subscription with a new query. To update a subscription's
+query, open an update block with ``SubscriptionSet.update()``.
+In the callback function of the update block, pass the following arguments to ``MutableSubscriptionSet.add()``:
+
+- The new query
+- The name of the subscription that you want to update
+- ``update: true``
+
+In the following example, long trains are re-defined to be any trains that
+have more than 10 cars.

source/includes/api-details/dart/sync/manage-sync-subscriptions-change-unnamed-subscription-not-supported.rst

@@ -0,0 +1,7 @@
+Dart does not provide the ability to change an unnamed subscription. If you
+know in advance that your app may need to change subscriptions, :ref:`create
+the subscription with a name <sdks-add-named-subscription>`.
+
+Alternately, you can :ref:`delete the unnamed subscription
+<sdks-remove-subscriptions>`, and :ref:`create a new subscription
+<sdks-sync-subscriptions-add-subscription>` with the desired query.

source/includes/api-details/dart/sync/manage-sync-subscriptions-duplicate-subscriptions-description.rst

@@ -0,0 +1,3 @@
+If you add a duplicate **unnamed** subscription with the same query, the SDK
+automatically removes it; adding an identical **named** subscription is a
+no-op. Therefore, in both cases, duplicate subscriptions are ignored.

source/includes/api-details/dart/sync/manage-sync-subscriptions-find-subscription-description.rst

@@ -0,0 +1,7 @@
+To find a specific subscription by name, call the 
+:flutter-sdk:`findByName() <realm/SubscriptionSet/findByName.html>`
+method with the name of a subscription.
+
+You can also find a subscription matching a specific query by calling the
+:flutter-sdk:`find() <realm/SubscriptionSet/find.html>` method with an
+RQL query.

source/includes/api-details/dart/sync/manage-sync-subscriptions-remove-all-subscriptions-description.rst

@@ -0,0 +1,2 @@
+Within a subscription update block, you can remove all subscriptions from the
+subscriptions set with :flutter-sdk:`MutableSubscriptionSet.clear() <realm/MutableSubscriptionSet/clear.html>`.

source/includes/api-details/dart/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-description.rst

@@ -0,0 +1,3 @@
+You can remove all subscriptions for a given SDK object type. Within a 
+subscription update block, call
+:flutter-sdk:`MutableSubscriptionSet.removeByType() <realm/MutableSubscriptionSet/removeByType.html>`.

source/includes/api-details/dart/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-description.rst

@@ -0,0 +1,4 @@
+Within a subscription update block, you can remove all unnamed subscriptions
+from the subscriptions set by calling :flutter-sdk:`MutableSubscriptionSet.clear()
+<realm/MutableSubscriptionSet/clear.html>` with an ``unnamedOnly`` argument
+set to ``true``.

source/includes/api-details/dart/sync/manage-sync-subscriptions-remove-named-subscription-description.rst

@@ -0,0 +1,3 @@
+Within an update block, you can remove a specific subscription by name. Pass
+the name to :flutter-sdk:`MutableSubscriptionSet.removeByName()
+<realm/MutableSubscriptionSet/removeByName.html>`.

source/includes/api-details/dart/sync/manage-sync-subscriptions-remove-subscription-by-reference-description.rst

@@ -0,0 +1,4 @@
+You can remove a subscription if you have a reference to its :flutter-sdk:`Subscription
+<realm/Subscription-class.html>` object.
+Within a subscription update block, pass the ``Subscription`` reference to
+:flutter-sdk:`MutableSubscriptionSet.remove() <realm/MutableSubscriptionSet/remove.html>`.

source/includes/api-details/dart/sync/manage-sync-subscriptions-remove-unnamed-subscription-description.rst

@@ -0,0 +1,6 @@
+Within an update block, you can remove a specific subscription by query.
+Open an update block with ``SubscriptionSet.update()``. Pass the
+``Subscription`` to :flutter-sdk:`MutableSubscriptionSet.removeByQuery()
+<realm/MutableSubscriptionSet/removeByQuery.html>`.
+
+In the following example, the subscription for all ``Plane`` objects is removed.

source/includes/api-details/dart/sync/manage-sync-subscriptions-subscribe-to-query-description.rst

@@ -0,0 +1,11 @@
+To subscribe to a query, pass the following arguments to ``subscribe()``:
+
+- ``RealmResults query``: Required. A ``RealmResults`` object that you can
+  create using the :ref:`Realm Query Language <rql>`.
+- ``String name``: Optional. Name for the subscription that you can refer to. 
+- ``bool update``:  Optional. When true, adding a subscription with an existing
+  name replaces the existing query with the new query. When false, the SDK
+  throws an exception for duplicate subscriptions. Only use with named
+  subscriptions.
+
+In the following example, we subscribe to two new named queries.

source/includes/api-details/dart/sync/manage-sync-subscriptions-subscribe-to-query-with-name-description.rst

@@ -0,0 +1,7 @@
+To subscribe to a query with a name, pass the following arguments to ``subscribe()``:
+
+- ``RealmResults query``: Required. A ``RealmResults`` object that you can create using the
+  :ref:`Realm Query Language <rql>`.
+- ``String name``: Optional. Name for the subscription that you can refer to. 
+
+In the following example, we subscribe to two new named queries.

source/includes/api-details/dart/sync/manage-sync-subscriptions-subscription-set-state-description.rst

@@ -0,0 +1,8 @@
+Use the :flutter-sdk:`Realm.subscriptions.state <realm/SubscriptionSet/state.html>`
+property to read the current state of the subscription set.
+
+The ``superseded`` state is a :flutter-sdk:`SubscriptionSetState
+<realm/SubscriptionSetState.html>` that can occur when another thread updates a
+subscription on a different instance of the subscription set. If the state
+becomes ``superseded``, you must obtain a new instance of the subscription set
+before you can update it.

source/includes/api-details/dart/sync/manage-sync-subscriptions-unsubscribe-from-query-description.rst

@@ -0,0 +1,2 @@
+You can unsubscribe from a query's results using :flutter-sdk:`unsubscribe()
+<realm/RealmResultsOfRealmObject/unsubscribe.html>`.

source/includes/api-details/dart/sync/manage-sync-subscriptions-wait-for-query-subscription-to-sync-description.rst

@@ -0,0 +1,21 @@
+When you do need specify the desired sync behavior, configure the
+:flutter-sdk:`waitForSyncMode <realm/WaitForSyncMode.html>` option. 
+
+This example uses the ``firstTime`` option, which is the default behavior.
+A subscription with ``firstTime`` behavior only waits for sync to finish when a
+subscription is first created.
+
+.. literalinclude:: /examples/generated/flutter/manage_sync_subscription_test.snippet.wait-first-time-subscribe-api.dart
+   :language: dart
+   :emphasize-lines: 5
+
+The other supported ``waitForSyncMode`` options are:
+
+- ``always``: Wait to download matching objects every time your app launches.
+  The app must have an internet connection at every launch.
+- ``never``: Never wait to download matching objects. The app needs an internet
+  connection for the user to authenticate the first time the app launches, but
+  can open offline on subsequent launches using cached credentials.
+
+You can optionally specify a :flutter-sdk:`cancellationToken <realm/CancellationToken-class.html>` 
+to limit how long the sync download runs.

source/includes/api-details/dart/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-description.rst

@@ -0,0 +1,11 @@
+Use :flutter-sdk:`Realm.subscriptions.waitForSynchronization() <realm/SubscriptionSet/waitForSynchronization.html>`
+to wait for the server to acknowledge this set of subscriptions.
+If the server rejects the change, and an exception is thrown.
+
+An exception may occur if:
+
+- You subscribe to an unsupported query. Subscribing to an unsupported query will pause synchronization.
+  To resume synchronization, :ref:`remove the unsupported query <sdks-remove-subscriptions>`.
+- You are performing an invalid action, such as adding an object that does not match a subscription.
+  This triggers a :ref:`client reset <client-resets>`: data is erased from the device,
+  and a new copy of the data is created without any subscriptions in the set.

source/includes/api-details/generic/sync/manage-sync-subscriptions-set-initial-subscriptions-not-supported.rst

@@ -0,0 +1,3 @@
+The selected language does not provide a dedicated API to set initial
+subscriptions. Instead, refer to the :ref:`sdks-sync-subscriptions-add-subscription`
+section on this page.

source/includes/api-details/generic/sync/manage-sync-subscriptions-subscribe-to-query-not-supported.rst

@@ -0,0 +1,3 @@
+The selected language does not support the API that enables you to subscribe
+to a query. Instead, refer to :ref:`manually manage queries
+<sdks-manually-manage-subscriptions>`.