added iOS source code
[wl-app.git] / iOS / Pods / Realm / include / RLMSyncSession.h
1 ////////////////////////////////////////////////////////////////////////////
2 //
3 // Copyright 2016 Realm Inc.
4 //
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
8 //
9 // http://www.apache.org/licenses/LICENSE-2.0
10 //
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.
16 //
17 ////////////////////////////////////////////////////////////////////////////
18
19 #import <Foundation/Foundation.h>
20
21 #import "RLMRealm.h"
22
23 /**
24  The current state of the session represented by a session object.
25  */
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
33 };
34
35 /**
36  The transfer direction (upload or download) tracked by a given progress notification block.
37
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.
40  */
41 typedef NS_ENUM(NSUInteger, RLMSyncProgressDirection) {
42     /// For monitoring upload progress.
43     RLMSyncProgressDirectionUpload,
44     /// For monitoring download progress.
45     RLMSyncProgressDirectionDownload,
46 };
47
48 /**
49  The desired behavior of a progress notification block.
50
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.
53  */
54 typedef NS_ENUM(NSUInteger, RLMSyncProgressMode) {
55     /**
56      The block will be called indefinitely, or until it is unregistered by calling
57      `-[RLMProgressNotificationToken invalidate]`.
58
59      Notifications will always report the latest number of transferred bytes, and the
60      most up-to-date number of total transferrable bytes.
61      */
62     RLMSyncProgressModeReportIndefinitely,
63     /**
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.
67
68      When the number of transferred bytes reaches or exceeds the
69      number of transferrable bytes, the block will be unregistered.
70      */
71     RLMSyncProgressModeForCurrentlyOutstandingWork,
72 };
73
74 @class RLMSyncUser, RLMSyncConfiguration, RLMSyncErrorActionToken;
75
76 /**
77  The type of a progress notification block intended for reporting a session's network
78  activity to the user.
79
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.
82  */
83 typedef void(^RLMProgressNotificationBlock)(NSUInteger transferredBytes, NSUInteger transferrableBytes);
84
85 NS_ASSUME_NONNULL_BEGIN
86
87 /**
88  A token object corresponding to a progress notification block on a session object.
89
90  To stop notifications manually, call `-invalidate` on it. Notifications should be stopped before
91  the token goes out of scope or is destroyed.
92  */
93 @interface RLMProgressNotificationToken : RLMNotificationToken
94 @end
95
96 /**
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).
100
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.
104  */
105 @interface RLMSyncSession : NSObject
106
107 /// The session's current state.
108 @property (nonatomic, readonly) RLMSyncSessionState state;
109
110 /// The Realm Object Server URL of the remote Realm this session corresponds to.
111 @property (nullable, nonatomic, readonly) NSURL *realmURL;
112
113 /// The user that owns this session.
114 - (nullable RLMSyncUser *)parentUser;
115
116 /**
117  If the session is valid, return a sync configuration that can be used to open the Realm
118  associated with this session.
119  */
120 - (nullable RLMSyncConfiguration *)configuration;
121
122 /**
123  Register a progress notification block.
124
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.
127
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.
131
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.
135
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
142  called again.
143
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.
147
148  @return A token which must be held for as long as you want notifications to be delivered.
149
150  @see `RLMSyncProgressDirection`, `RLMSyncProgress`, `RLMProgressNotificationBlock`, `RLMProgressNotificationToken`
151  */
152 - (nullable RLMProgressNotificationToken *)addProgressNotificationForDirection:(RLMSyncProgressDirection)direction
153                                                                           mode:(RLMSyncProgressMode)mode
154                                                                          block:(RLMProgressNotificationBlock)block
155 NS_REFINED_FOR_SWIFT;
156
157 /**
158  Given an error action token, immediately handle the corresponding action.
159  
160  @see `RLMSyncErrorClientResetError`, `RLMSyncErrorPermissionDeniedError`
161  */
162 + (void)immediatelyHandleError:(RLMSyncErrorActionToken *)token;
163
164 @end
165
166 // MARK: - Error action token
167
168 #pragma mark - Error action token
169
170 /**
171  An opaque token returned as part of certain errors. It can be
172  passed into certain APIs to perform certain actions.
173
174  @see `RLMSyncErrorClientResetError`, `RLMSyncErrorPermissionDeniedError`
175  */
176 @interface RLMSyncErrorActionToken : NSObject
177
178 /// :nodoc:
179 - (instancetype)init __attribute__((unavailable("This type cannot be created directly")));
180
181 /// :nodoc:
182 + (instancetype)new __attribute__((unavailable("This type cannot be created directly")));
183
184 @end
185
186 NS_ASSUME_NONNULL_END