RLMSyncSession

@interface RLMSyncSession : NSObject

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. Session objects can be accessed from any thread.

  • The session’s current state.

    This property is not KVO-compliant.

    Declaration

    Objective-C

    @property (readonly, nonatomic) RLMSyncSessionState state;
    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, atomic) RLMSyncConnectionState connectionState;
    Show on GitHub

  • The Realm Object Server URL of the remote Realm this session corresponds to.

    Declaration

    Objective-C

    @property (readonly, nonatomic, nullable) NSURL *realmURL;
    Show on GitHub

  • The user that owns this session.

    Declaration

    Objective-C

    - (nullable RLMSyncUser *)parentUser;
    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;
    Show on GitHub

  • Temporarily suspend syncronization and disconnect from the server.

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

    Declaration

    Objective-C

    - (void)suspend;
    Show on GitHub

  • Resume syncronization and reconnect to Realm Object Server 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;
    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, 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

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

    See

    RLMSyncErrorClientResetError, RLMSyncErrorPermissionDeniedError

    Declaration

    Objective-C

    + (void)immediatelyHandleError:(nonnull RLMSyncErrorActionToken *)token;
    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;
    Show on GitHub