-
Notifications
You must be signed in to change notification settings - Fork 43
/
Simperium.h
245 lines (181 loc) · 10.1 KB
/
Simperium.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
//
// Simperium.h
//
// Created by Michael Johnston on 11-02-11.
// Copyright 2011 Simperium. All rights reserved.
//
// A simple system for shared state. See http://simperium.com for details.
#import <Foundation/Foundation.h>
#import <CoreData/CoreData.h>
#import "SPBucket.h"
#import "SPManagedObject.h"
#import "SPAuthenticator.h"
#import "SPAuthenticationInterface.h"
#import "SPUser.h"
#if TARGET_OS_IPHONE
#import <UIKit/UIApplication.h>
#else
#import <AppKit/AppKit.h>
#endif
NS_ASSUME_NONNULL_BEGIN
@class Simperium;
#if TARGET_OS_IPHONE
@class UIViewController;
#else
@class NSWindow;
#endif
#pragma mark ====================================================================================
#pragma mark Simperium Constants
#pragma mark ====================================================================================
extern NSString * const SimperiumWillSaveNotification;
typedef NS_ENUM(NSInteger, SPSimperiumErrors) {
SPSimperiumErrorsMissingAppID,
SPSimperiumErrorsMissingAPIKey,
SPSimperiumErrorsMissingToken,
SPSimperiumErrorsMissingWindow,
SPSimperiumErrorsInvalidToken
};
#pragma mark ====================================================================================
#pragma mark SimperiumDelegate
#pragma mark ====================================================================================
/** You can use this delegate to respond to general events and errors.
If you want explicit callbacks when objects are changed/added/deleted, you can also use SPBucketDelegate in SPBucket.h.
Standard Core Data notifications are also generated, allowing you to update a `UITableView` (for example) in your `NSFetchedResultsControllerDelegate`.
*/
@protocol SimperiumDelegate <NSObject>
@optional
- (void)simperium:(Simperium *)simperium didFailWithError:(NSError *)error;
- (void)simperiumDidLogin:(Simperium *)simperium;
- (void)simperiumDidLogout:(Simperium *)simperium;
- (void)simperiumDidCancelLogin:(Simperium *)simperium;
- (void)simperiumDidCreateAccount:(Simperium *)simperium;
@end
#pragma mark ====================================================================================
#pragma mark Simperium: The main class through which you access Simperium.
#pragma mark ====================================================================================
@interface Simperium : NSObject
// Initializes Simperium: After executing this method, your CoreData Stack will be fully initialized
- (instancetype)initWithModel:(NSManagedObjectModel *)model
context:(NSManagedObjectContext *)context
coordinator:(NSPersistentStoreCoordinator *)coordinator;
// Initializes Simperium: This constructor allows you to specify custom mappings between local and remote buckets.
- (instancetype)initWithModel:(NSManagedObjectModel *)model
context:(NSManagedObjectContext *)context
coordinator:(NSPersistentStoreCoordinator *)coordinator
label:(NSString *)label
bucketOverrides:(nullable NSDictionary *)bucketOverrides;
#if TARGET_OS_IPHONE
// Starts Simperium and displays the auth interface, if needed.
- (void)authenticateWithAppID:(NSString *)identifier APIKey:(NSString *)key rootViewController:(UIViewController *)controller;
#else
// Starts Simperium and displays the auth interface, if needed.
- (void)authenticateWithAppID:(NSString *)identifier APIKey:(NSString *)key window:(NSWindow *)aWindow;
#endif
// Starts Simperium with a given token, with no UI interaction required.
- (void)authenticateWithAppID:(NSString *)identifier token:(NSString *)token;
#pragma mark ====================================================================================
#pragma mark Public Methods
#pragma mark ====================================================================================
// Save and sync all changed objects. If you're using Core Data, this is just a convenience method
// (you can also just save your context and Simperium will see the changes).
- (BOOL)save;
// Support for iOS Background Fetch. 'result' flag will be set to UIBackgroundFetchResultNewData, if new data was retrieved,
// or set to UIBackgroundFetchResultNoData in any other case.
#if defined(__IPHONE_7_0) && (__IPHONE_OS_VERSION_MAX_ALLOWED >= __IPHONE_7_0)
typedef void (^SimperiumBackgroundFetchCompletion)(UIBackgroundFetchResult result);
- (void)backgroundFetchWithCompletion:(SimperiumBackgroundFetchCompletion)completion;
#endif
// Get a particular bucket (which, for Core Data, corresponds to a particular Entity name in your model).
// Once you have a bucket instance, you can set a SPBucketDelegate to react to changes.
- (nullable SPBucket *)bucketForName:(NSString *)name;
// Convenience methods for accessing the Core Data stack.
- (NSManagedObjectContext *)managedObjectContext;
- (NSManagedObjectContext *)writerManagedObjectContext;
- (NSManagedObjectModel *)managedObjectModel;
- (NSPersistentStoreCoordinator *)persistentStoreCoordinator;
// OTHER
// Saves without syncing (typically not used).
- (BOOL)saveWithoutSyncing;
#if !TARGET_OS_IPHONE
// Support for OSX delayed app termination: Ensure local changes have a chance to fully save.
- (NSApplicationTerminateReply)applicationShouldTerminate:(NSApplication *)sender;
#endif
// Clears all locally stored data from the device. Can be used to perform a manual sign out.
// Note: This method is now asynchronous. Please, listen to signout delegate calls, or implement a completion callback block.
typedef void (^SimperiumSignoutCompletion)(void);
- (void)signOutAndRemoveLocalData:(BOOL)remove completion:(nullable SimperiumSignoutCompletion)completion;
// Removes all of the sync'ing metadata. This helper method may be used after a faulty core data migration, to ensure
// sync'ing consistency: next time Simperium is authenticated, it will resync the entire database again.
- (void)resetMetadata;
// Shares an object with a particular user's email address (forthcoming).
//- (void)shareObject:(SPManagedObject *)object withEmail:(NSString *)email;
// Alternative to setting delegates on each individual bucket (if you want a single handler for everything).
// If you need to, call this after starting Simperium.
- (void)setAllBucketDelegates:(nullable id<SPBucketDelegate>)aDelegate;
// Alternative to toggling propertyMismatchFailsafeE on each individual bucket (if you want the same behavior everywhere).
// When enabled, Simperium will capture any exceptions thrown while setting property values, and log the error.
- (void)setAllBucketPropertyMismatchFailsafeEnabled:(BOOL)isEnabled;
// Opens an authentication interface if necessary.
- (BOOL)authenticateIfNecessary;
// A SimperiumDelegate for system callbacks.
@property (nonatomic, readwrite, weak) id<SimperiumDelegate> delegate;
// Set this to true if you need to be able to cancel the authentication dialog.
@property (nonatomic, readwrite, assign) BOOL authenticationOptional;
// Indiccates if the Authentication UI should be embedded in a NavigationController
@property (nonatomic, readwrite, assign) BOOL authenticationShouldBeEmbeddedInNavigationController;
// Toggle Simperium's Backend Pinning.
@property (nonatomic, readwrite, assign) BOOL certificatePinningEnabled;
// Toggle verbose logging.
@property (nonatomic, readwrite, assign) BOOL verboseLoggingEnabled;
// Toggle remote logging.
@property (nonatomic, readwrite, assign) BOOL remoteLoggingEnabled;
// Enables or disables the network.
@property (nonatomic, readwrite, assign) BOOL networkEnabled;
// Indicates if the Authentication UI should start in LogIn mode by default
@property (nonatomic, readwrite, assign) BOOL presentsLoginByDefault;
// Delays Inserted Objects initialization until the MOC is saved. Useful for importing data while preventing duplicates.
@property (nonatomic, readwrite, assign) BOOL delaysNewObjectsInitialization;
// Enables or disables full database validation: objects with missing simperiumKey or ghost will be initialized.
// By default this is enabled, and should be ran at least once after implementing Simperium on legacy databases.
@property (nonatomic, readwrite, assign) BOOL validatesObjects;
// Returns the currently authenticated Simperium user.
@property (nonatomic, readonly, strong, nullable) SPUser *user;
// The full URL used to communicate with Simperium.
@property (nonatomic, readonly, copy) NSString *appURL;
// URL to a Simperium server (can be changed to point to a custom installation).
@property (nonatomic, readwrite, copy) NSString *rootURL;
// A unique ID for this app (configured at simperium.com).
@property (nonatomic, readonly, copy) NSString *appID;
// An access token for this app (generated at simperium.com).
@property (nonatomic, readonly, copy) NSString *APIKey;
// A hashed, unique ID for this client.
@property (nonatomic, readonly, copy) NSString *clientID;
// Remote Bucket Name Overrides!
@property (nonatomic, readonly, nullable, copy) NSDictionary *bucketOverrides;
// Returns the current SPAuthenticator instance.
@property (nonatomic, readwrite, strong) SPAuthenticator *authenticator;
// Returns a flag indicating if the network is not accessible.
@property (nonatomic, readonly, assign) BOOL requiresConnection;
// Returns a string describing the network status.
@property (nonatomic, readonly, strong) NSString *networkStatus;
// Returns the timestamp of the last message received by the backend.
@property (nonatomic, readonly, strong) NSDate *networkLastSeenTime;
// Returns the number of bytes sent per session.
@property (nonatomic, readonly, assign) NSUInteger bytesSent;
// Returns the number of bytes received per session.
@property (nonatomic, readonly, assign) NSUInteger bytesReceived;
// You can implement your own subclass of SPAuthenticationViewController (iOS) or
// SPAuthenticationWindowController (OSX) to customize authentication.
//
#if TARGET_OS_IPHONE
@property (nonatomic, readwrite, weak) Class authenticationViewControllerClass;
#else
@property (nonatomic, readwrite, weak) Class authenticationWindowControllerClass;
#endif
#if TARGET_OS_IPHONE
@property (nonatomic, readwrite, weak) UIViewController *rootViewController;
#else
@property (nonatomic, readwrite, weak) NSWindow *window;
#endif
@end
NS_ASSUME_NONNULL_END