iOS/Pods/Realm/include/RLMSyncPermission.h

   1 ////////////////////////////////////////////////////////////////////////////
   2 //
   3 // Copyright 2017 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 /**
  22  Access levels which can be granted to Realm Mobile Platform users
  23  for specific synchronized Realms, using the permissions APIs.
  24
  25  Note that each access level guarantees all allowed actions provided
  26  by less permissive access levels. Specifically, users with write
  27  access to a Realm can always read from that Realm, and users with
  28  administrative access can always read or write from the Realm.
  29  */
  30 typedef NS_ENUM(NSUInteger, RLMSyncAccessLevel) {
  31     /// No access whatsoever.
  32     RLMSyncAccessLevelNone          = 0,
  33     /**
  34      User can only read the contents of the Realm.
  35
  36      @warning Users who have read-only access to a Realm should open the
  37               Realm using `+[RLMRealm asyncOpenWithConfiguration:callbackQueue:callback:]`.
  38               Attempting to directly open the Realm is an error; in this
  39               case the Realm must be deleted and re-opened.
  40      */
  41     RLMSyncAccessLevelRead          = 1,
  42     /// User can read and write the contents of the Realm.
  43     RLMSyncAccessLevelWrite         = 2,
  44     /// User can read, write, and administer the Realm, including
  45     /// granting permissions to other users.
  46     RLMSyncAccessLevelAdmin         = 3,
  47 };
  48
  49 NS_ASSUME_NONNULL_BEGIN
  50
  51 /**
  52  A property on which a `RLMResults<RLMSyncPermission *>` can be queried or filtered.
  53
  54  @warning If building `NSPredicate`s using format strings including these string
  55           constants, use %K instead of %@ as the substitution parameter.
  56  */
  57 typedef NSString * RLMSyncPermissionSortProperty NS_STRING_ENUM;
  58
  59 /// Sort by the Realm Object Server path to the Realm to which the permission applies.
  60 extern RLMSyncPermissionSortProperty const RLMSyncPermissionSortPropertyPath;
  61 /// Sort by the identity of the user to whom the permission applies.
  62 extern RLMSyncPermissionSortProperty const RLMSyncPermissionSortPropertyUserID;
  63 /// Sort by the date the permissions were last updated.
  64 extern RLMSyncPermissionSortProperty const RLMSyncPermissionSortPropertyUpdated;
  65
  66 /**
  67  A value representing a permission granted to the specified user(s) to access the specified Realm(s).
  68
  69  `RLMSyncPermission` is immutable and can be accessed from any thread.
  70
  71  See https://realm.io/docs/realm-object-server/#permissions for general documentation.
  72  */
  73 @interface RLMSyncPermission : NSObject
  74
  75 /**
  76  The Realm Object Server path to the Realm to which this permission applies (e.g. "/path/to/realm").
  77
  78  Specify "*" if this permission applies to all Realms managed by the server.
  79  */
  80 @property (nonatomic, readonly) NSString *path;
  81
  82 /**
  83  The access level described by this permission.
  84  */
  85 @property (nonatomic, readonly) RLMSyncAccessLevel accessLevel;
  86
  87 /// Whether the access level allows the user to read from the Realm.
  88 @property (nonatomic, readonly) BOOL mayRead;
  89
  90 /// Whether the access level allows the user to write to the Realm.
  91 @property (nonatomic, readonly) BOOL mayWrite;
  92
  93 /// Whether the access level allows the user to administer the Realm.
  94 @property (nonatomic, readonly) BOOL mayManage;
  95
  96 /**
  97  Create a new sync permission value, for use with permission APIs.
  98
  99  @param path        The Realm Object Server path to the Realm whose permission should be modified
 100                     (e.g. "/path/to/realm"). Pass "*" to apply to all Realms managed by the user.
 101  @param identity    The Realm Object Server identity of the user who should be granted access to
 102                     the Realm at `path`.
 103                     Pass "*" to apply to all users managed by the server.
 104  @param accessLevel The access level to grant.
 105  */
 106 - (instancetype)initWithRealmPath:(NSString *)path
 107                          identity:(NSString *)identity
 108                       accessLevel:(RLMSyncAccessLevel)accessLevel;
 109
 110 /**
 111  Create a new sync permission value, for use with permission APIs.
 112
 113  @param path        The Realm Object Server path to the Realm whose permission should be modified
 114                     (e.g. "/path/to/realm"). Pass "*" to apply to all Realms managed by the user.
 115  @param username    The username (often an email address) of the user who should be granted access
 116                     to the Realm at `path`.
 117  @param accessLevel The access level to grant.
 118  */
 119 - (instancetype)initWithRealmPath:(NSString *)path
 120                          username:(NSString *)username
 121                       accessLevel:(RLMSyncAccessLevel)accessLevel;
 122
 123 /**
 124  The identity of the user to whom this permission is granted, or "*"
 125  if all users are granted this permission. Nil if the permission is
 126  defined in terms of a key-value pair.
 127  */
 128 @property (nullable, nonatomic, readonly) NSString *identity;
 129
 130 /**
 131  If the permission is defined in terms of a key-value pair, the key
 132  describing the type of criterion used to determine what users the
 133  permission applies to. Otherwise, nil.
 134  */
 135 @property (nullable, nonatomic, readonly) NSString *key;
 136
 137 /**
 138  If the permission is defined in terms of a key-value pair, a string
 139  describing the criterion value used to determine what users the
 140  permission applies to. Otherwise, nil.
 141  */
 142 @property (nullable, nonatomic, readonly) NSString *value;
 143
 144 /**
 145  When this permission was last updated.
 146  */
 147 @property (nonatomic, readonly) NSDate *updatedAt;
 148
 149 /// :nodoc:
 150 - (instancetype)init __attribute__((unavailable("Use the designated initializer")));
 151
 152 /// :nodoc:
 153 + (instancetype)new __attribute__((unavailable("Use the designated initializer")));
 154
 155 // MARK: - Migration assistance
 156
 157 /// :nodoc:
 158 @property (nullable, nonatomic, readonly) NSString *userId __attribute__((unavailable("Renamed to `identity`")));
 159
 160 /// :nodoc:
 161 - (instancetype)initWithRealmPath:(NSString *)path
 162                            userID:(NSString *)identity
 163                       accessLevel:(RLMSyncAccessLevel)accessLevel
 164 __attribute__((unavailable("Renamed to `-initWithRealmPath:identity:accessLevel:`")));
 165
 166 @end
 167
 168 NS_ASSUME_NONNULL_END