1 ////////////////////////////////////////////////////////////////////////////
3 // Copyright 2016 Realm Inc.
5 // Licensed under the Apache License, Version 2.0 (the "License");
6 // you may not use this file except in compliance with the License.
7 // You may obtain a copy of the License at
9 // http://www.apache.org/licenses/LICENSE-2.0
11 // Unless required by applicable law or agreed to in writing, software
12 // distributed under the License is distributed on an "AS IS" BASIS,
13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 // See the License for the specific language governing permissions and
15 // limitations under the License.
17 ////////////////////////////////////////////////////////////////////////////
19 #import <Foundation/Foundation.h>
24 The current state of the session represented by a session object.
26 typedef NS_ENUM(NSUInteger, RLMSyncSessionState) {
27 /// The sync session is bound to the Realm Object Server and communicating with it.
28 RLMSyncSessionStateActive,
29 /// The sync session is not currently communicating with the Realm Object Server.
30 RLMSyncSessionStateInactive,
31 /// The sync session encountered a fatal error and is permanently invalid; it should be discarded.
32 RLMSyncSessionStateInvalid
36 The transfer direction (upload or download) tracked by a given progress notification block.
38 Progress notification blocks can be registered on sessions if your app wishes to be informed
39 how many bytes have been uploaded or downloaded, for example to show progress indicator UIs.
41 typedef NS_ENUM(NSUInteger, RLMSyncProgressDirection) {
42 /// For monitoring upload progress.
43 RLMSyncProgressDirectionUpload,
44 /// For monitoring download progress.
45 RLMSyncProgressDirectionDownload,
49 The desired behavior of a progress notification block.
51 Progress notification blocks can be registered on sessions if your app wishes to be informed
52 how many bytes have been uploaded or downloaded, for example to show progress indicator UIs.
54 typedef NS_ENUM(NSUInteger, RLMSyncProgressMode) {
56 The block will be called indefinitely, or until it is unregistered by calling
57 `-[RLMProgressNotificationToken invalidate]`.
59 Notifications will always report the latest number of transferred bytes, and the
60 most up-to-date number of total transferrable bytes.
62 RLMSyncProgressModeReportIndefinitely,
64 The block will, upon registration, store the total number of bytes
65 to be transferred. When invoked, it will always report the most up-to-date number
66 of transferrable bytes out of that original number of transferrable bytes.
68 When the number of transferred bytes reaches or exceeds the
69 number of transferrable bytes, the block will be unregistered.
71 RLMSyncProgressModeForCurrentlyOutstandingWork,
74 @class RLMSyncUser, RLMSyncConfiguration, RLMSyncErrorActionToken;
77 The type of a progress notification block intended for reporting a session's network
80 `transferredBytes` refers to the number of bytes that have been uploaded or downloaded.
81 `transferrableBytes` refers to the total number of bytes transferred, and pending transfer.
83 typedef void(^RLMProgressNotificationBlock)(NSUInteger transferredBytes, NSUInteger transferrableBytes);
85 NS_ASSUME_NONNULL_BEGIN
88 A token object corresponding to a progress notification block on a session object.
90 To stop notifications manually, call `-invalidate` on it. Notifications should be stopped before
91 the token goes out of scope or is destroyed.
93 @interface RLMProgressNotificationToken : RLMNotificationToken
97 An object encapsulating a Realm Object Server "session". Sessions represent the
98 communication between the client (and a local Realm file on disk), and the server
99 (and a remote Realm at a given URL stored on a Realm Object Server).
101 Sessions are always created by the SDK and vended out through various APIs. The
102 lifespans of sessions associated with Realms are managed automatically. Session
103 objects can be accessed from any thread.
105 @interface RLMSyncSession : NSObject
107 /// The session's current state.
108 @property (nonatomic, readonly) RLMSyncSessionState state;
110 /// The Realm Object Server URL of the remote Realm this session corresponds to.
111 @property (nullable, nonatomic, readonly) NSURL *realmURL;
113 /// The user that owns this session.
114 - (nullable RLMSyncUser *)parentUser;
117 If the session is valid, return a sync configuration that can be used to open the Realm
118 associated with this session.
120 - (nullable RLMSyncConfiguration *)configuration;
123 Register a progress notification block.
125 Multiple blocks can be registered with the same session at once. Each block
126 will be invoked on a side queue devoted to progress notifications.
128 If the session has already received progress information from the
129 synchronization subsystem, the block will be called immediately. Otherwise, it
130 will be called as soon as progress information becomes available.
132 The token returned by this method must be retained as long as progress
133 notifications are desired, and the `-invalidate` method should be called on it
134 when notifications are no longer needed and before the token is destroyed.
136 If no token is returned, the notification block will never be called again.
137 There are a number of reasons this might be true. If the session has previously
138 experienced a fatal error it will not accept progress notification blocks. If
139 the block was configured in the `RLMSyncProgressForCurrentlyOutstandingWork`
140 mode but there is no additional progress to report (for example, the number
141 of transferrable bytes and transferred bytes are equal), the block will not be
144 @param direction The transfer direction (upload or download) to track in this progress notification block.
145 @param mode The desired behavior of this progress notification block.
146 @param block The block to invoke when notifications are available.
148 @return A token which must be held for as long as you want notifications to be delivered.
150 @see `RLMSyncProgressDirection`, `RLMSyncProgress`, `RLMProgressNotificationBlock`, `RLMProgressNotificationToken`
152 - (nullable RLMProgressNotificationToken *)addProgressNotificationForDirection:(RLMSyncProgressDirection)direction
153 mode:(RLMSyncProgressMode)mode
154 block:(RLMProgressNotificationBlock)block
155 NS_REFINED_FOR_SWIFT;
158 Given an error action token, immediately handle the corresponding action.
160 @see `RLMSyncErrorClientResetError`, `RLMSyncErrorPermissionDeniedError`
162 + (void)immediatelyHandleError:(RLMSyncErrorActionToken *)token;
166 // MARK: - Error action token
168 #pragma mark - Error action token
171 An opaque token returned as part of certain errors. It can be
172 passed into certain APIs to perform certain actions.
174 @see `RLMSyncErrorClientResetError`, `RLMSyncErrorPermissionDeniedError`
176 @interface RLMSyncErrorActionToken : NSObject
179 - (instancetype)init __attribute__((unavailable("This type cannot be created directly")));
182 + (instancetype)new __attribute__((unavailable("This type cannot be created directly")));
186 NS_ASSUME_NONNULL_END