Realm.Sync.Session

An object encapsulating a Realm Object Server session. Sessions represent the communication between the client (and a local Realm file on disk), and the server (and a remote Realm at a given URL stored on a Realm Object Server). Sessions are always created by the SDK and vended out through various APIs. The lifespans of sessions associated with Realms are managed automatically.

config

Gets the Sync-part of the configuration that the corresponding Realm was constructed with.

Type:
object
state

Gets the current state of the session. Can be either:

  • "active": The session is connected to the Realm Object Server and is actively transferring data.
  • "inactive": The session is not currently communicating with the Realm Object Server.
  • "invalid": A non-recoverable error has occurred, and this session is semantically invalid. A new session should be created.
Type:
string
url

Gets the URL of the Realm Object Server that this session is connected to.

Type:
string
user

Gets the User that this session was created with.

Type:
User
addConnectionNotification(callback)

Registers a connection notification on the session object. This will be notified about changes to the underlying connection to the Realm Object Server.

Parameters:
  • callback
    • Type: callback(newState, oldState)
    • called with the following arguments:

      • newState - the new state of the connection
      • oldState - the state the connection transitioned from.
addProgressNotification(direction, mode, callback)

Register a progress notification callback on a session object

Parameters:
  • direction
    • Type: string
    • The progress direction to register for. Can be either:

      • download - report download progress
      • upload - report upload progress
  • mode
    • Type: string
    • The progress notification mode to use for the registration. Can be either:

      • reportIndefinitely - the registration will stay active until the callback is unregistered
      • forCurrentlyOutstandingWork - the registration will be active until only the currently transferable bytes are synced
  • callback
    • Type: callback(transferred, transferable)
    • called with the following arguments:

      • transferred - the current number of bytes already transferred
      • transferable - the total number of transferable bytes (the number of bytes already transferred plus the number of bytes pending transfer)
connectionState()

Gets the current state of the connection to the server. Multiple sessions might share the same underlying connection. In that case, any connection change is sent to all sessions.

Can be either:

  • Realm.Sync.ConnectionState.Disconnected: No connection to the server is available.
  • Realm.Sync.ConnectionState.Connecting: An attempt to connect to the server is in progress.
  • Realm.Sync.ConnectionState.Connected: The connection to the server is active and data can be synchronized.

Data will only be synchronized with the Realm ObjectServer if this method returns Connected and state() returns Active or Dying.

isConnected()

Returns true if the session is currently active and connected to the server, false if not.

pause()

Pause a sync session.

This method is asynchronous so in order to know when the session has started you will need to add a connection notification with addConnectionNotification.

This method is idempotent so it will be a no-op if the session is already paused.

removeConnectionNotification(callback)

Unregister a state notification callback that was previously registered with addStateNotification. Calling the function multiple times with the same callback is ignored.

Parameters:
  • callback
    • Type: callback(oldState, newState)
    • a previously registered state callback.

removeProgressNotification(callback)

Unregister a progress notification callback that was previously registered with addProgressNotification. Calling the function multiple times with the same callback is ignored.

Parameters:
  • callback
    • Type: callback(transferred, transferable)
    • a previously registered progress callback

resume()

Resumes a sync session that has been paused.

This method is asynchronous so in order to know when the session has started you will need to add a connection notification with addConnectionNotification.

This method is idempotent so it will be a no-op if the session is already started.