RLMSyncSession

Objective-C


@interface RLMSyncSession : NSObject

Swift

@_nonSendable(_assumed) class RLMSyncSession : NSObject, @unchecked Sendable

An object encapsulating an Atlas App Services “session”. Sessions represent the communication between the client (and a local Realm file on disk), and the server (and a remote Realm with a given partition value stored on Atlas App Services).

Sessions are always created by the SDK and vended out through various APIs. The lifespans of sessions associated with Realms are managed automatically. Session objects can be accessed from any thread.

Show on GitHub

  • The session’s current state.

    This property is not KVO-compliant.

    Declaration

    Objective-C

    @property (nonatomic, readonly) RLMSyncSessionState state;

    Swift

    var state: RLMSyncSessionState { get }
    Show on GitHub

  • The session’s current connection state.

    This property is KVO-compliant and can be observed to be notified of changes. Be warned that KVO observers for this property may be called on a background thread.

    Declaration

    Objective-C

    @property (readonly) RLMSyncConnectionState connectionState;

    Swift

    var connectionState: RLMSyncConnectionState { get }
    Show on GitHub

  • The user that owns this session.

    Declaration

    Objective-C

    - (nullable RLMUser *)parentUser;

    Swift

    func parentUser() -> RLMUser?
    Show on GitHub

  • If the session is valid, return a sync configuration that can be used to open the Realm associated with this session.

    Declaration

    Objective-C

    - (nullable RLMSyncConfiguration *)configuration;

    Swift

    func configuration() -> RLMSyncConfiguration?
    Show on GitHub

  • Temporarily suspend syncronization and disconnect from the server.

    The session will not attempt to connect to Atlas App Services until resume is called or the Realm file is closed and re-opened.

    Declaration

    Objective-C

    - (void)suspend;

    Swift

    func suspend()
    Show on GitHub

  • Resume syncronization and reconnect to Atlas App Services after suspending.

    This is a no-op if the session was already active or if the session is invalid. Newly created sessions begin in the Active state and do not need to be resumed.

    Declaration

    Objective-C

    - (void)resume;

    Swift

    func resume()
    Show on GitHub

  • Request an immediate reconnection to the server if the session is disconnected.

    Realm automatically reconnects after disconnects with an exponential backoff, which is reset when the reachability handler reports a network status change. In some scenarios an application may wish to skip the reconnect delay, such as when an application receives the DidBecomeActive notification, which can be done by calling this method. Calling this method is never required.

    This method is asynchronous and merely skips the current reconnect delay, so the connection state will still normally be disconnected immediately after calling it.

    Has no effect if the session is currently connected.

    Declaration

    Objective-C

    - (void)reconnect;

    Swift

    func reconnect()
    Show on GitHub

  • Deprecated

    Use addSyncProgressNotificationForDirection instead

    Register a progress notification block.

    Multiple blocks can be registered with the same session at once. Each block will be invoked on a side queue devoted to progress notifications.

    If the session has already received progress information from the synchronization subsystem, the block will be called immediately. Otherwise, it will be called as soon as progress information becomes available.

    The token returned by this method must be retained as long as progress notifications are desired, and the -invalidate method should be called on it when notifications are no longer needed and before the token is destroyed.

    If no token is returned, the notification block will never be called again. There are a number of reasons this might be true. If the session has previously experienced a fatal error it will not accept progress notification blocks. If the block was configured in the RLMSyncProgressForCurrentlyOutstandingWork mode but there is no additional progress to report (for example, the number of transferrable bytes and transferred bytes are equal), the block will not be called again.

    See

    RLMSyncProgressDirection, RLMSyncProgress, RLMProgressNotificationBlock, RLMProgressNotificationToken

    Declaration

    Objective-C

    - (nullable RLMProgressNotificationToken *)
    addProgressNotificationForDirection:(RLMSyncProgressDirection)direction
                                   mode:(RLMSyncProgressMode)mode
                                  block:(nonnull RLMProgressNotificationBlock)
                                            block;

    Parameters

    direction

    The transfer direction (upload or download) to track in this progress notification block.
    mode

    The desired behavior of this progress notification block.
    block

    The block to invoke when notifications are available.

    Return Value

    A token which must be held for as long as you want notifications to be delivered.

    Show on GitHub

  • Register a progress notification block.

    Multiple blocks can be registered with the same session at once. Each block will be invoked on a side queue devoted to progress notifications.

    If the session has already received progress information from the synchronization subsystem, the block will be called immediately. Otherwise, it will be called as soon as progress information becomes available.

    The token returned by this method must be retained as long as progress notifications are desired, and the -invalidate method should be called on it when notifications are no longer needed and before the token is destroyed.

    If no token is returned, the notification block will never be called again. There are a number of reasons this might be true. If the session has previously experienced a fatal error it will not accept progress notification blocks. If the block was configured in the RLMSyncProgressForCurrentlyOutstandingWork mode but there is no additional progress to report (for example, the number of transferrable bytes and transferred bytes are equal), the block will not be called again.

    See

    RLMSyncProgressDirection, RLMSyncProgress, RLMSyncProgressNotificationBlock, RLMProgressNotificationToken

    Declaration

    Objective-C

    - (nullable RLMProgressNotificationToken *)
    addSyncProgressNotificationForDirection:(RLMSyncProgressDirection)direction
                                       mode:(RLMSyncProgressMode)mode
                                      block:
                                          (nonnull
                                               RLMSyncProgressNotificationBlock)
                                              block;

    Parameters

    direction

    The transfer direction (upload or download) to track in this progress notification block.
    mode

    The desired behavior of this progress notification block.
    block

    The block to invoke when notifications are available.

    Return Value

    A token which must be held for as long as you want notifications to be delivered.

    Show on GitHub

  • Wait for pending uploads to complete or the session to expire, and dispatch the callback onto the specified queue.

    Declaration

    Objective-C

    - (BOOL)waitForUploadCompletionOnQueue:(nullable dispatch_queue_t)queue
                              callback:(nonnull void (^)(NSError *_Nullable))
                                           callback;
    Show on GitHub

  • Wait for pending downloads to complete or the session to expire, and dispatch the callback onto the specified queue.

    Declaration

    Objective-C

    - (BOOL)waitForDownloadCompletionOnQueue:(nullable dispatch_queue_t)queue
                                callback:(nonnull void (^)(NSError *_Nullable))
                                             callback;
    Show on GitHub

  • Given an error action token, immediately handle the corresponding action.

    See

    `RLMSyncErrorClientResetError, RLMSyncErrorPermissionDeniedError

    Declaration

    Objective-C

    + (void)immediatelyHandleError:(nonnull RLMSyncErrorActionToken *)token;

    Swift

    class func immediatelyHandleError(_ token: RLMSyncErrorActionToken)
    Show on GitHub

  • Get the sync session for the given Realm if it is a synchronized Realm, or nil if it is not.

    Declaration

    Objective-C

    + (nullable RLMSyncSession *)sessionForRealm:(nonnull RLMRealm *)realm;

    Swift

    /*not inherited*/ init?(for realm: RLMRealm)
    Show on GitHub