iOS/Pods/Realm/include/RLMSyncUtil.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 <Realm/RLMConstants.h>
  20
  21 /// A token originating from the Realm Object Server.
  22 typedef NSString* RLMServerToken;
  23
  24 NS_ASSUME_NONNULL_BEGIN
  25
  26 /// A user info key for use with `RLMSyncErrorClientResetError`.
  27 extern NSString *const kRLMSyncPathOfRealmBackupCopyKey;
  28
  29 /// A user info key for use with certain error types.
  30 extern NSString *const kRLMSyncErrorActionTokenKey;
  31
  32 /**
  33  The error domain string for all SDK errors related to errors reported
  34  by the synchronization manager error handler, as well as general sync
  35  errors that don't fall into any of the other categories.
  36  */
  37 extern NSString *const RLMSyncErrorDomain;
  38
  39 /**
  40  The error domain string for all SDK errors related to the authentication
  41  endpoint.
  42  */
  43 extern NSString *const RLMSyncAuthErrorDomain;
  44
  45 /**
  46  The error domain string for all SDK errors related to the permissions
  47  system and APIs.
  48  */
  49 extern NSString *const RLMSyncPermissionErrorDomain;
  50
  51 /**
  52  An error related to a problem that might be reported by the synchronization manager
  53  error handler, or a callback on a sync-related API that performs asynchronous work.
  54  */
  55 typedef RLM_ERROR_ENUM(NSInteger, RLMSyncError, RLMSyncErrorDomain) {
  56
  57     /// An error that indicates a problem with the session (a specific Realm opened for sync).
  58     RLMSyncErrorClientSessionError      = 4,
  59
  60     /// An error that indicates a problem with a specific user.
  61     RLMSyncErrorClientUserError         = 5,
  62
  63     /**
  64      An error that indicates an internal, unrecoverable problem
  65      with the underlying synchronization engine.
  66      */
  67     RLMSyncErrorClientInternalError     = 6,
  68
  69     /**
  70      An error that indicates the Realm needs to be reset.
  71
  72      A synced Realm may need to be reset because the Realm Object Server encountered an
  73      error and had to be restored from a backup. If the backup copy of the remote Realm
  74      is of an earlier version than the local copy of the Realm, the server will ask the
  75      client to reset the Realm.
  76
  77      The reset process is as follows: the local copy of the Realm is copied into a recovery
  78      directory for safekeeping, and then deleted from the original location. The next time
  79      the Realm for that URL is opened, the Realm will automatically be re-downloaded from the
  80      Realm Object Server, and can be used as normal.
  81
  82      Data written to the Realm after the local copy of the Realm diverged from the backup
  83      remote copy will be present in the local recovery copy of the Realm file. The
  84      re-downloaded Realm will initially contain only the data present at the time the Realm
  85      was backed up on the server.
  86
  87      The client reset process can be initiated in one of two ways.
  88
  89      The `userInfo` dictionary contains an opaque token object under the key
  90      `kRLMSyncErrorActionTokenKey`. This token can be passed into
  91      `+[RLMSyncSession immediatelyHandleError:]` in order to immediately perform the client
  92      reset process. This should only be done after your app closes and invalidates every
  93      instance of the offending Realm on all threads (note that autorelease pools may make this
  94      difficult to guarantee).
  95
  96      If `+[RLMSyncSession immediatelyHandleError:]` is not called, the client reset process
  97      will be automatically carried out the next time the app is launched and the
  98      `RLMSyncManager` singleton is accessed.
  99
 100      The value for the `kRLMSyncPathOfRealmBackupCopyKey` key in the `userInfo` dictionary
 101      describes the path of the recovered copy of the Realm. This copy will not actually be
 102      created until the client reset process is initiated.
 103
 104      @see `-[NSError rlmSync_errorActionToken]`, `-[NSError rlmSync_clientResetBackedUpRealmPath]`
 105      */
 106     RLMSyncErrorClientResetError        = 7,
 107
 108     /**
 109      An error that indicates an authentication error occurred.
 110
 111      The `kRLMSyncUnderlyingErrorKey` key in the user info dictionary will contain the
 112      underlying error, which is guaranteed to be under the `RLMSyncAuthErrorDomain`
 113      error domain.
 114      */
 115     RLMSyncErrorUnderlyingAuthError     = 8,
 116
 117     /**
 118      An error that indicates the user does not have permission to perform an operation
 119      upon a synced Realm. For example, a user may receive this error if they attempt to
 120      open a Realm they do not have at least read access to, or write to a Realm they only
 121      have read access to.
 122
 123      This error may also occur if a user incorrectly opens a Realm they have read-only
 124      permissions to without using the `asyncOpen()` APIs.
 125
 126      A Realm that suffers a permission denied error is, by default, flagged so that its
 127      local copy will be deleted the next time the application starts.
 128
 129      The `userInfo` dictionary contains an opaque token object under the key
 130      `kRLMSyncErrorActionTokenKey`. This token can be passed into
 131      `+[RLMSyncSession immediatelyHandleError:]` in order to immediately delete the local
 132      copy. This should only be done after your app closes and invalidates every instance
 133      of the offending Realm on all threads (note that autorelease pools may make this
 134      difficult to guarantee).
 135
 136      @warning It is strongly recommended that, if a Realm has encountered a permission denied
 137               error, its files be deleted before attempting to re-open it.
 138
 139      @see `-[NSError rlmSync_errorActionToken]`
 140      */
 141     RLMSyncErrorPermissionDeniedError   = 9,
 142 };
 143
 144 /// An error which is related to authentication to a Realm Object Server.
 145 typedef RLM_ERROR_ENUM(NSInteger, RLMSyncAuthError, RLMSyncAuthErrorDomain) {
 146     /// An error that indicates that the response received from the authentication server was malformed.
 147     RLMSyncAuthErrorBadResponse                     = 1,
 148
 149     /// An error that indicates that the supplied Realm path was invalid, or could not be resolved by the authentication
 150     /// server.
 151     RLMSyncAuthErrorBadRemoteRealmPath              = 2,
 152
 153     /// An error that indicates that the response received from the authentication server was an HTTP error code. The
 154     /// `userInfo` dictionary contains the actual error code value.
 155     RLMSyncAuthErrorHTTPStatusCodeError             = 3,
 156
 157     /// An error that indicates a problem with the session (a specific Realm opened for sync).
 158     RLMSyncAuthErrorClientSessionError              = 4,
 159
 160     /// An error that indicates that the provided credentials are invalid.
 161     RLMSyncAuthErrorInvalidCredential               = 611,
 162
 163     /// An error that indicates that the user with provided credentials does not exist.
 164     RLMSyncAuthErrorUserDoesNotExist                = 612,
 165
 166     /// An error that indicates that the user cannot be registered as it exists already.
 167     RLMSyncAuthErrorUserAlreadyExists               = 613,
 168
 169     /// An error that indicates the path is invalid or the user doesn't have access to that Realm.
 170     RLMSyncAuthErrorAccessDeniedOrInvalidPath       = 614,
 171
 172     /// An error that indicates the refresh token was invalid.
 173     RLMSyncAuthErrorInvalidAccessToken              = 615,
 174
 175     /// An error that indicates the permission offer is expired.
 176     RLMSyncAuthErrorExpiredPermissionOffer          = 701,
 177
 178     /// An error that indicates the permission offer is ambiguous.
 179     RLMSyncAuthErrorAmbiguousPermissionOffer        = 702,
 180
 181     /// An error that indicates the file at the given path can't be shared.
 182     RLMSyncAuthErrorFileCannotBeShared              = 703,
 183 };
 184
 185 /**
 186  An error related to the permissions subsystem.
 187  */
 188 typedef RLM_ERROR_ENUM(NSInteger, RLMSyncPermissionError, RLMSyncPermissionErrorDomain) {
 189     /**
 190      An error that indicates a permission change operation failed. The `userInfo`
 191      dictionary contains the underlying error code and a message (if any).
 192      */
 193     RLMSyncPermissionErrorChangeFailed          = 1,
 194
 195     /**
 196      An error that indicates that attempting to retrieve permissions failed.
 197      */
 198     RLMSyncPermissionErrorGetFailed             = 2,
 199
 200     /**
 201      An error that indicates that trying to create a permission offer failed.
 202      */
 203     RLMSyncPermissionErrorOfferFailed           = 3,
 204
 205     /**
 206      An error that indicates that trying to accept a permission offer failed.
 207      */
 208     RLMSyncPermissionErrorAcceptOfferFailed     = 4,
 209
 210     /**
 211      An error that indicates that an internal error occurred.
 212      */
 213     RLMSyncPermissionErrorInternal              = 5,
 214 };
 215
 216 NS_ASSUME_NONNULL_END