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