added iOS source code
[wl-app.git] / iOS / Pods / Realm / include / RLMSyncUser.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 "RLMResults.h"
22 #import "RLMSyncCredentials.h"
23 #import "RLMSyncPermission.h"
24
25 @class RLMSyncUser, RLMSyncUserInfo, RLMSyncCredentials, RLMSyncPermission, RLMSyncSession, RLMRealm;
26
27 /**
28  The state of the user object.
29  */
30 typedef NS_ENUM(NSUInteger, RLMSyncUserState) {
31     /// The user is logged out. Call `logInWithCredentials:...` with valid credentials to log the user back in.
32     RLMSyncUserStateLoggedOut,
33     /// The user is logged in, and any Realms associated with it are syncing with the Realm Object Server.
34     RLMSyncUserStateActive,
35     /// The user has encountered a fatal error state, and cannot be used.
36     RLMSyncUserStateError,
37 };
38
39 /// A block type used for APIs which asynchronously vend an `RLMSyncUser`.
40 typedef void(^RLMUserCompletionBlock)(RLMSyncUser * _Nullable, NSError * _Nullable);
41
42 /// A block type used to report the status of a password change operation.
43 /// If the `NSError` argument is nil, the operation succeeded.
44 typedef void(^RLMPasswordChangeStatusBlock)(NSError * _Nullable);
45
46 /// A block type used to report the status of a permission apply or revoke operation.
47 /// If the `NSError` argument is nil, the operation succeeded.
48 typedef void(^RLMPermissionStatusBlock)(NSError * _Nullable);
49
50 /// A block type used to report the status of a permission offer operation.
51 typedef void(^RLMPermissionOfferStatusBlock)(NSString * _Nullable, NSError * _Nullable);
52
53 /// A block type used to report the status of a permission offer response operation.
54 typedef void(^RLMPermissionOfferResponseStatusBlock)(NSURL * _Nullable, NSError * _Nullable);
55
56 /// A block type used to asynchronously report results of a permissions get operation.
57 /// Exactly one of the two arguments will be populated.
58 typedef void(^RLMPermissionResultsBlock)(RLMResults<RLMSyncPermission *> * _Nullable, NSError * _Nullable);
59
60 /// A block type used to asynchronously report results of a user info retrieval.
61 /// Exactly one of the two arguments will be populated.
62 typedef void(^RLMRetrieveUserBlock)(RLMSyncUserInfo * _Nullable, NSError * _Nullable);
63
64 /// A block type used to report an error related to a specific user.
65 typedef void(^RLMUserErrorReportingBlock)(RLMSyncUser * _Nonnull, NSError * _Nonnull);
66
67 NS_ASSUME_NONNULL_BEGIN
68
69 /**
70  A `RLMSyncUser` instance represents a single Realm Object Server user account.
71
72  A user may have one or more credentials associated with it. These credentials
73  uniquely identify the user to the authentication provider, and are used to sign
74  into a Realm Object Server user account.
75
76  Note that user objects are only vended out via SDK APIs, and cannot be directly
77  initialized. User objects can be accessed from any thread.
78  */
79 @interface RLMSyncUser : NSObject
80
81 /**
82  A dictionary of all valid, logged-in user identities corresponding to their user objects.
83  */
84 + (NSDictionary<NSString *, RLMSyncUser *> *)allUsers NS_REFINED_FOR_SWIFT;
85
86 /**
87  The logged-in user. `nil` if none exists.
88
89  @warning Throws an exception if more than one logged-in user exists.
90  */
91 + (nullable RLMSyncUser *)currentUser NS_REFINED_FOR_SWIFT;
92
93 /**
94  The unique Realm Object Server user ID string identifying this user.
95  */
96 @property (nullable, nonatomic, readonly) NSString *identity;
97
98 /**
99  The URL of the authentication server this user will communicate with.
100  */
101 @property (nullable, nonatomic, readonly) NSURL *authenticationServer;
102
103 /**
104  Whether the user is a Realm Object Server administrator. Value reflects the
105  state at the time of the last successful login of this user.
106  */
107 @property (nonatomic, readonly) BOOL isAdmin;
108
109 /**
110  The current state of the user.
111  */
112 @property (nonatomic, readonly) RLMSyncUserState state;
113
114 #pragma mark - Lifecycle
115
116 /**
117  Create, log in, and asynchronously return a new user object, specifying a custom
118  timeout for the network request and a custom queue to run the callback upon.
119  Credentials identifying the user must be passed in. The user becomes available in
120  the completion block, at which point it is ready for use.
121  */
122 + (void)logInWithCredentials:(RLMSyncCredentials *)credentials
123                authServerURL:(NSURL *)authServerURL
124                      timeout:(NSTimeInterval)timeout
125                callbackQueue:(dispatch_queue_t)callbackQueue
126                 onCompletion:(RLMUserCompletionBlock)completion NS_REFINED_FOR_SWIFT;
127
128 /**
129  Create, log in, and asynchronously return a new user object.
130
131  If the login completes successfully, the completion block will invoked with
132  a `RLMSyncUser` object representing the logged-in user. This object can be
133  used to open synchronized Realms. If the login fails, the completion block
134  will be invoked with an error.
135
136  The completion block always runs on the main queue.
137
138  @param credentials     A credentials value identifying the user to be logged in.
139  @param authServerURL   The URL of the authentication server (e.g. "http://realm.example.org:9080").
140  @param completion      A callback block that returns a user object or an error,
141                         indicating the completion of the login operation.
142  */
143 + (void)logInWithCredentials:(RLMSyncCredentials *)credentials
144                authServerURL:(NSURL *)authServerURL
145                 onCompletion:(RLMUserCompletionBlock)completion
146 NS_SWIFT_UNAVAILABLE("Use the full version of this API.");
147
148 /**
149  Log a user out, destroying their server state, unregistering them from the SDK,
150  and removing any synced Realms associated with them from on-disk storage on
151  next app launch. If the user is already logged out or in an error state, this
152  method does nothing.
153
154  This method should be called whenever the application is committed to not using
155  a user again unless they are recreated.
156  Failing to call this method may result in unused files and metadata needlessly
157  taking up space.
158  */
159 - (void)logOut;
160
161 /**
162  An optional error handler which can be set to notify the host application when
163  the user encounters an error. Errors reported by this error handler are always
164  `RLMSyncAuthError`s.
165
166  @note Check for `RLMSyncAuthErrorInvalidAccessToken` to see if the user has
167        been remotely logged out because its refresh token expired, or because the
168        third party authentication service providing the user's identity has
169        logged the user out.
170
171  @warning Regardless of whether an error handler is installed, certain user errors
172           will automatically cause the user to enter the logged out state.
173  */
174 @property (nullable, nonatomic) RLMUserErrorReportingBlock errorHandler NS_REFINED_FOR_SWIFT;
175
176 #pragma mark - Sessions
177
178 /**
179  Retrieve a valid session object belonging to this user for a given URL, or `nil`
180  if no such object exists.
181  */
182 - (nullable RLMSyncSession *)sessionForURL:(NSURL *)url;
183
184 /**
185  Retrieve all the valid sessions belonging to this user.
186  */
187 - (NSArray<RLMSyncSession *> *)allSessions;
188
189 #pragma mark - Passwords
190
191 /**
192  Change this user's password asynchronously.
193
194  @warning Changing a user's password using an authentication server that doesn't
195           use HTTPS is a major security flaw, and should only be done while
196           testing.
197
198  @param newPassword The user's new password.
199  @param completion  Completion block invoked when login has completed or failed.
200                     The callback will be invoked on a background queue provided
201                     by `NSURLSession`.
202  */
203 - (void)changePassword:(NSString *)newPassword completion:(RLMPasswordChangeStatusBlock)completion;
204
205 /**
206  Change an arbitrary user's password asynchronously.
207
208  @note    The current user must be an admin user for this operation to succeed.
209
210  @warning Changing a user's password using an authentication server that doesn't
211           use HTTPS is a major security flaw, and should only be done while
212           testing.
213
214  @param newPassword The user's new password.
215  @param userID      The identity of the user whose password should be changed.
216  @param completion  Completion block invoked when login has completed or failed.
217                     The callback will be invoked on a background queue provided
218                     by `NSURLSession`.
219  */
220 - (void)changePassword:(NSString *)newPassword forUserID:(NSString *)userID completion:(RLMPasswordChangeStatusBlock)completion;
221
222 #pragma mark - Administrator
223
224 /**
225  Given a Realm Object Server authentication provider and a provider identifier for a user
226  (for example, a username), look up and return user information for that user.
227
228  @param providerUserIdentity    The username or identity of the user as issued by the authentication provider.
229                                 In most cases this is different from the Realm Object Server-issued identity.
230  @param provider                The authentication provider that manages the user whose information is desired.
231  @param completion              Completion block invoked when request has completed or failed.
232                                 The callback will be invoked on a background queue provided
233                                 by `NSURLSession`.
234  */
235 - (void)retrieveInfoForUser:(NSString *)providerUserIdentity
236            identityProvider:(RLMIdentityProvider)provider
237                  completion:(RLMRetrieveUserBlock)completion;
238
239 #pragma mark - Permissions
240
241 /**
242  Asynchronously retrieve all permissions associated with the user calling this method.
243
244  The results will be returned through the callback block, or an error if the operation failed.
245  The callback block will be run on the same thread the method was called on.
246
247  @warning This method must be called from a thread with a currently active run loop. Unless
248           you have manually configured a run loop on a side thread, this will usually be the
249           main thread.
250  */
251 - (void)retrievePermissionsWithCallback:(RLMPermissionResultsBlock)callback NS_REFINED_FOR_SWIFT;
252
253 /**
254  Apply a given permission.
255
256  The operation will take place asynchronously, and the callback will be used to report whether
257  the permission change succeeded or failed. The user calling this method must have the right
258  to grant the given permission, or else the operation will fail.
259
260  @see `RLMSyncPermission`
261  */
262 - (void)applyPermission:(RLMSyncPermission *)permission callback:(RLMPermissionStatusBlock)callback;
263
264 /**
265  Revoke a given permission.
266
267  The operation will take place asynchronously, and the callback will be used to report whether
268  the permission change succeeded or failed. The user calling this method must have the right
269  to grant the given permission, or else the operation will fail.
270
271  @see `RLMSyncPermission`
272  */
273 - (void)revokePermission:(RLMSyncPermission *)permission callback:(RLMPermissionStatusBlock)callback;
274
275 /**
276  Create a permission offer for a Realm.
277
278  A permission offer is used to grant access to a Realm this user manages to another
279  user. Creating a permission offer produces a string token which can be passed to the
280  recepient in any suitable way (for example, via e-mail).
281
282  The operation will take place asynchronously. The token can be accepted by the recepient
283  using the `-[RLMSyncUser acceptOfferForToken:callback:]` method.
284
285  @param url             The URL of the Realm for which the permission offer should pertain. This
286                         may be the URL of any Realm which this user is allowed to manage. If the URL
287                         has a `~` wildcard it will be replaced with this user's user identity.
288  @param accessLevel     What access level to grant to whoever accepts the token.
289  @param expirationDate  Optionally, a date which indicates when the offer expires. If the
290                         recepient attempts to accept the offer after the date it will be rejected.
291  @param callback        A callback indicating whether the operation succeeded or failed. If it
292                         succeeded the token will be passed in as a string.
293
294  @see `acceptOfferForToken:callback:`
295  */
296 - (void)createOfferForRealmAtURL:(NSURL *)url
297                      accessLevel:(RLMSyncAccessLevel)accessLevel
298                       expiration:(nullable NSDate *)expirationDate
299                         callback:(RLMPermissionOfferStatusBlock)callback NS_REFINED_FOR_SWIFT;
300
301 /**
302  Accept a permission offer.
303
304  Pass in a token representing a permission offer. The operation will take place asynchronously.
305  If the operation succeeds, the callback will be passed the URL of the Realm for which the
306  offer applied, so the Realm can be opened.
307
308  The token this method accepts can be created by the offering user through the
309  `-[RLMSyncUser createOfferForRealmAtURL:accessLevel:expiration:callback:]` method.
310
311  @see `createOfferForRealmAtURL:accessLevel:expiration:callback:`
312  */
313 - (void)acceptOfferForToken:(NSString *)token
314                    callback:(RLMPermissionOfferResponseStatusBlock)callback;
315
316 /// :nodoc:
317 - (instancetype)init __attribute__((unavailable("RLMSyncUser cannot be created directly")));
318 /// :nodoc:
319 + (instancetype)new __attribute__((unavailable("RLMSyncUser cannot be created directly")));
320
321 @end
322
323 #pragma mark - User info classes
324
325 /**
326  A data object representing a user account associated with a user.
327
328  @see `RLMSyncUserInfo`
329  */
330 @interface RLMSyncUserAccountInfo : NSObject
331
332 /// The authentication provider which manages this user account.
333 @property (nonatomic, readonly) RLMIdentityProvider provider;
334
335 /// The username or identity of this user account.
336 @property (nonatomic, readonly) NSString *providerUserIdentity;
337
338 /// :nodoc:
339 - (instancetype)init __attribute__((unavailable("RLMSyncUserAccountInfo cannot be created directly")));
340 /// :nodoc:
341 + (instancetype)new __attribute__((unavailable("RLMSyncUserAccountInfo cannot be created directly")));
342
343 @end
344
345 /**
346  A data object representing information about a user that was retrieved from a user lookup call.
347  */
348 @interface RLMSyncUserInfo : NSObject
349
350 /**
351  An array of all the user accounts associated with this user.
352  */
353 @property (nonatomic, readonly) NSArray<RLMSyncUserAccountInfo *> *accounts;
354
355 /**
356  The identity issued to this user by the Realm Object Server.
357  */
358 @property (nonatomic, readonly) NSString *identity;
359
360 /**
361  Metadata about this user stored on the Realm Object Server.
362  */
363 @property (nonatomic, readonly) NSDictionary<NSString *, NSString *> *metadata;
364
365 /**
366  Whether the user is flagged on the Realm Object Server as an administrator.
367  */
368 @property (nonatomic, readonly) BOOL isAdmin;
369
370 /// :nodoc:
371 - (instancetype)init __attribute__((unavailable("RLMSyncUserInfo cannot be created directly")));
372 /// :nodoc:
373 + (instancetype)new __attribute__((unavailable("RLMSyncUserInfo cannot be created directly")));
374
375 @end
376
377 NS_ASSUME_NONNULL_END