Aucune description

AWSCognitoService.h 17KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405
  1. //
  2. // Copyright 2014-2016 Amazon.com,
  3. // Inc. or its affiliates. All Rights Reserved.
  4. //
  5. // Licensed under the Amazon Software License (the "License").
  6. // You may not use this file except in compliance with the
  7. // License. A copy of the License is located at
  8. //
  9. // http://aws.amazon.com/asl/
  10. //
  11. // or in the "license" file accompanying this file. This file is
  12. // distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
  13. // CONDITIONS OF ANY KIND, express or implied. See the License
  14. // for the specific language governing permissions and
  15. // limitations under the License.
  16. //
  17. #import <Foundation/Foundation.h>
  18. #import <AWSCore/AWSCore.h>
  19. #import "AWSCognitoHandlers.h"
  20. #import "AWSCognitoSyncService.h"
  21. NS_ASSUME_NONNULL_BEGIN
  22. FOUNDATION_EXPORT NSString *const AWSCognitoSDKVersion;
  23. @class AWSCognitoDataset;
  24. @class AWSCognitoDatasetMetadata;
  25. @class AWSCognitoCredentialsProvider;
  26. @class AWSTask;
  27. /**
  28. AWSCognito
  29. @warning The AWSCognito (Amazon Cognito Sync) SDK is deprecated. Please use AWSAppSync for data sync.
  30. @deprecated Please use AWSAppSync for data sync.
  31. */
  32. DEPRECATED_MSG_ATTRIBUTE("Use `AWSAppSync` for data synchronization.")
  33. @interface AWSCognito : AWSService
  34. /**
  35. Posted when the synchronization is started.
  36. The notification sender is an instance of AWSCognitoClient. The userInfo
  37. contains the dataset name.
  38. @discussion This notification is posted once per synchronization.
  39. The notification is posted on the Grand Central Dispatch
  40. DISPATCH_QUEUE_PRIORITY_DEFAULT queue. The user interface should not be
  41. modified on the thread.
  42. */
  43. extern NSString *const AWSCognitoDidStartSynchronizeNotification;
  44. /**
  45. Posted when the synchronization is finished with or without errors.
  46. The notification sender is an instance of AWSCognitoClient. The userInfo
  47. contains the dataset name.
  48. @discussion This notification is posted once per synchronization.
  49. The notification is posted on the Grand Central Dispatch
  50. DISPATCH_QUEUE_PRIORITY_DEFAULT queue. The user interface should not be
  51. modified on the thread.
  52. */
  53. extern NSString *const AWSCognitoDidEndSynchronizeNotification;
  54. /**
  55. Posted when values are changed to the value from the remote data store. The notification
  56. sender is an instance of AWSCognitoClient. The userInfo contains the dataset name and
  57. an NSArray of changed keys.
  58. @discussion This notification may be posted multiple times per synchronization.
  59. The notification is posted on the Grand Central Dispatch
  60. DISPATCH_QUEUE_PRIORITY_DEFAULT queue. The user interface should not be
  61. modified on the thread.
  62. */
  63. extern NSString *const AWSCognitoDidChangeLocalValueFromRemoteNotification;
  64. /**
  65. Posted when locally changed values are pushed to the remote store. The notification
  66. sender is an instance of AWSCognitoClient. The userInfo contains the dataset name and
  67. an NSArray of changed keys.
  68. @discussion This notification may be posted multiple times per synchronization.
  69. The notification is posted on the Grand Central Dispatch
  70. DISPATCH_QUEUE_PRIORITY_DEFAULT queue. The user interface should not be
  71. modified on the thread.
  72. */
  73. extern NSString *const AWSCognitoDidChangeRemoteValueNotification;
  74. /**
  75. Posted when the synchronization for the for the dataset failed. The notification
  76. sender is an instance of AWSCognitoClient. The userInfo contains the dataset name
  77. and error.
  78. @discussion This notification may be posted multiple times per synchronization.
  79. The notification is posted on the Grand Central Dispatch
  80. DISPATCH_QUEUE_PRIORITY_DEFAULT queue. The user interface should not be
  81. modified on the thread.
  82. */
  83. extern NSString *const AWSCognitoDidFailToSynchronizeNotification;
  84. /**
  85. The error domain for AWSCognito errors.
  86. <ul>
  87. <li>AWSCognitoErrorUnknown - Unknow error.</li>
  88. <li>AWSCognitoErrorRemoteDataStorageFailed - The Amazon Cognito call temporarily failed.</li>
  89. <li>AWSCognitoErrorInvalidDataValue - The Amazon Cognito call failed. The value for the
  90. key is invalid and has been deleted from the local database.</li>
  91. <li>AWSCognitoErrorDataSizeLimitExceeded - The Amazon Cognito call failed. A
  92. dataset has exceeded the max dataset size.</li>
  93. <li>AWSCognitoErrorLocalDataStorageFailed - The SQLite call failed.</li>
  94. <li>AWSCognitoErrorIllegalArgument - The input value is invalid.</li>
  95. <li>AWSCognitoErrorConflictRetriesExhausted - The number of attempts to resolve a conflict
  96. has exceeded the max number of retries.</li>
  97. <li>AWSCognitoErrorWiFiNotAvailable - WiFi is required and not currently available.</li>
  98. <li>AWSCognitoErrorDeviceNotRegistered - The device has not been registered yet.</li>
  99. <li>AWSCognitoErrorSyncAlreadyPending - This sync is unecessary, there is already a pending sync.</li>
  100. <li>AWSCognitoErrorTimedOutWaitingForInFlightSync - There is a in flight sync that took over 5 minutes to complete, so this one was cancelled.</li>
  101. </ul>
  102. */
  103. FOUNDATION_EXPORT NSString *const AWSCognitoErrorDomain;
  104. typedef NS_ENUM(NSInteger, AWSCognitoErrorType) {
  105. AWSCognitoErrorUnknown = 0,
  106. AWSCognitoErrorRemoteDataStorageFailed = -1000,
  107. AWSCognitoErrorInvalidDataValue = -1001,
  108. AWSCognitoErrorUserDataSizeLimitExceeded = -1002,
  109. AWSCognitoErrorLocalDataStorageFailed = -2000,
  110. AWSCognitoErrorIllegalArgument = -3000,
  111. AWSCognitoAuthenticationFailed = -4000,
  112. AWSCognitoErrorTaskCanceled = -5000,
  113. AWSCognitoErrorConflictRetriesExhausted = -6000,
  114. AWSCognitoErrorWiFiNotAvailable = -7000,
  115. AWSCognitoErrorDeviceNotRegistered = -8000,
  116. AWSCognitoErrorSyncAlreadyPending = -9000,
  117. AWSCognitoErrorTimedOutWaitingForInFlightSync = -10000,
  118. };
  119. @property (nonatomic, strong, readonly) AWSServiceConfiguration *configuration;
  120. /**
  121. A conflict resolution handler that will receive calls when there is a
  122. conflict during a sync operation. A conflict will occur when both remote and
  123. local data have been updated since the last sync time.
  124. When not explicitly set, we will use the default conflict resolution of
  125. 'last writer wins', where the data most recently updated will be persisted.
  126. This handler will be propagated to any AWSCognitoDataset opened by this client.
  127. */
  128. @property (nonatomic, strong) AWSCognitoRecordConflictHandler conflictHandler;
  129. /**
  130. A deleted dataset handler. This handler will be called during a synchronization
  131. when the remote service indicates that a dataset has been deleted.
  132. Returning YES from the handler will cause the service to recreate the dataset
  133. on the remote on the next synchronization. Returning NO or leaving this property
  134. nil will cause the client to delete the dataset locally.
  135. This handler will be propagated to any AWSCognitoDataset opened by this client.
  136. */
  137. @property (nonatomic, strong) AWSCognitoDatasetDeletedHandler datasetDeletedHandler;
  138. /**
  139. A merged dataset handler. This handler will be called during a synchronization
  140. when the remote service indicates that other datasets should be merged with this one.
  141. Merged datasets should be fetched, their data overlayed locally and then removed.
  142. Failing to implement this handler will result in merged datasets remaining on the
  143. service indefinitely.
  144. This handler will be propagated to any AWSCognitoDataset opened by this client.
  145. */
  146. @property (nonatomic, strong) AWSCognitoDatasetMergedHandler datasetMergedHandler;
  147. /**
  148. The identifier used for this client in Amazon Cognito. If not supplied
  149. Amazon Cognito will create a random GUID for the device.
  150. */
  151. @property (nonatomic, strong) NSString *deviceId;
  152. /**
  153. The number of times to attempt a synchronization before failing. This will
  154. be set on any AWSCognitoDatasets opened with this client. Defaults to 5 if not set.
  155. */
  156. @property (nonatomic, assign) uint32_t synchronizeRetries;
  157. /**
  158. Only synchronize if device is on a WiFi network. Defaults to NO if not set.
  159. */
  160. @property (nonatomic, assign) BOOL synchronizeOnWiFiOnly;
  161. /**
  162. Returns the singleton service client. If the singleton object does not exist, the SDK instantiates the default service client with `defaultServiceConfiguration` from `[AWSServiceManager defaultServiceManager]`. The reference to this object is maintained by the SDK, and you do not need to retain it manually. Returns `nil` if the credentials provider is not an instance of `AWSCognitoCredentials` provider.
  163. For example, set the default service configuration in `- application:didFinishLaunchingWithOptions:`
  164. *Swift*
  165. func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {
  166. let credentialProvider = AWSCognitoCredentialsProvider(regionType: .USEast1, identityPoolId: "YourIdentityPoolId")
  167. let configuration = AWSServiceConfiguration(region: .USEast1, credentialsProvider: credentialProvider)
  168. AWSServiceManager.default().defaultServiceConfiguration = configuration
  169. return true
  170. }
  171. *Objective-C*
  172. - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  173. AWSCognitoCredentialsProvider *credentialsProvider = [[AWSCognitoCredentialsProvider alloc] initWithRegionType:AWSRegionUSEast1
  174. identityPoolId:@"YourIdentityPoolId"];
  175. AWSServiceConfiguration *configuration = [[AWSServiceConfiguration alloc] initWithRegion:AWSRegionUSEast1
  176. credentialsProvider:credentialsProvider];
  177. [AWSServiceManager defaultServiceManager].defaultServiceConfiguration = configuration;
  178. return YES;
  179. }
  180. Then call the following to get the default service client:
  181. *Swift*
  182. let Cognito = AWSCognito.default()
  183. *Objective-C*
  184. AWSCognito *Cognito = [AWSCognito defaultCognito];
  185. @return The default service client.
  186. */
  187. + (instancetype)defaultCognito;
  188. /**
  189. Creates a service client with the given service configuration and registers it for the key.
  190. For example, set the default service configuration in `- application:didFinishLaunchingWithOptions:`
  191. *Swift*
  192. func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {
  193. let credentialProvider = AWSCognitoCredentialsProvider(regionType: .USEast1, identityPoolId: "YourIdentityPoolId")
  194. let configuration = AWSServiceConfiguration(region: .USWest2, credentialsProvider: credentialProvider)
  195. AWSCognito.register(with: configuration!, forKey: "USWest2Cognito")
  196. return true
  197. }
  198. *Objective-C*
  199. - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  200. AWSCognitoCredentialsProvider *credentialsProvider = [[AWSCognitoCredentialsProvider alloc] initWithRegionType:AWSRegionUSEast1
  201. identityPoolId:@"YourIdentityPoolId"];
  202. AWSServiceConfiguration *configuration = [[AWSServiceConfiguration alloc] initWithRegion:AWSRegionUSWest2
  203. credentialsProvider:credentialsProvider];
  204. [AWSCognito registerCognitoWithConfiguration:configuration forKey:@"USWest2Cognito"];
  205. return YES;
  206. }
  207. Then call the following to get the service client:
  208. *Swift*
  209. let Cognito = AWSCognito(forKey: "USWest2Cognito")
  210. *Objective-C*
  211. AWSCognito *Cognito = [AWSCognito CognitoForKey:@"USWest2Cognito"];
  212. @warning After calling this method, do not modify the configuration object. It may cause unspecified behaviors.
  213. @param configuration A service configuration object.
  214. @param key A string to identify the service client.
  215. */
  216. + (void)registerCognitoWithConfiguration:(AWSServiceConfiguration *)configuration forKey:(NSString *)key;
  217. /**
  218. Retrieves the service client associated with the key. You need to call `+ registerCognitoWithConfiguration:forKey:` before invoking this method.
  219. For example, set the default service configuration in `- application:didFinishLaunchingWithOptions:`
  220. *Swift*
  221. func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {
  222. let credentialProvider = AWSCognitoCredentialsProvider(regionType: .USEast1, identityPoolId: "YourIdentityPoolId")
  223. let configuration = AWSServiceConfiguration(region: .USWest2, credentialsProvider: credentialProvider)
  224. AWSCognito.register(with: configuration!, forKey: "USWest2Cognito")
  225. return true
  226. }
  227. *Objective-C*
  228. - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  229. AWSCognitoCredentialsProvider *credentialsProvider = [[AWSCognitoCredentialsProvider alloc] initWithRegionType:AWSRegionUSEast1
  230. identityPoolId:@"YourIdentityPoolId"];
  231. AWSServiceConfiguration *configuration = [[AWSServiceConfiguration alloc] initWithRegion:AWSRegionUSWest2
  232. credentialsProvider:credentialsProvider];
  233. [AWSCognito registerCognitoWithConfiguration:configuration forKey:@"USWest2Cognito"];
  234. return YES;
  235. }
  236. Then call the following to get the service client:
  237. *Swift*
  238. let Cognito = AWSCognito(forKey: "USWest2Cognito")
  239. *Objective-C*
  240. AWSCognito *Cognito = [AWSCognito CognitoForKey:@"USWest2Cognito"];
  241. @param key A string to identify the service client.
  242. @return An instance of the service client.
  243. */
  244. + (instancetype)CognitoForKey:(NSString *)key;
  245. /**
  246. Removes the service client associated with the key and release it.
  247. @warning Before calling this method, make sure no method is running on this client.
  248. @param key A string to identify the service client.
  249. */
  250. + (void)removeCognitoForKey:(NSString *)key;
  251. /**
  252. Opens an existing dataset or creates a new one.
  253. @return handle to AWSCognitoDataset
  254. */
  255. - (AWSCognitoDataset *)openOrCreateDataset:(NSString *)datasetName;
  256. /**
  257. List all datasets our client is aware of. Call refreshDatasetMetadata to ensure
  258. the client has knowledge of all datasets available on the remote store.
  259. @return NSArray of AWSCognitoDatasetMetadata
  260. */
  261. - (NSArray<AWSCognitoDatasetMetadata *> *)listDatasets;
  262. /**
  263. List all of the datasets. Returns a AWSTask. The result of this task will be an array of
  264. AWSCognitoDatasetMetadata objects.
  265. */
  266. - (AWSTask<NSArray<AWSCognitoDatasetMetadata *> *> *)refreshDatasetMetadata;
  267. /**
  268. Wipe all cached data.
  269. */
  270. - (void)wipe;
  271. /**
  272. Get the default, last writer wins conflict handler
  273. */
  274. + (AWSCognitoRecordConflictHandler) defaultConflictHandler;
  275. /**
  276. Register this device for push notifications. You will not receive any notifications until you actually subscribe the
  277. dataset you want to receive push notifications for. If your build targets Release, this will register the device
  278. with APNS, if your build targets Debug this will register the device with APNS_SANDBOX. Returns a AWSTask.
  279. The result of this task will be a AWSCognitoSyncRegisterDeviceResponse.
  280. */
  281. - (AWSTask *)registerDevice: (NSData *) deviceToken;
  282. /**
  283. Get the device id Cognito Sync gave this device. nil if device has never been registered
  284. */
  285. + (NSString *) cognitoDeviceId;
  286. /**
  287. Used to override the platform for push notifications. If you are not using the CocoaPods distribution,
  288. #ifdef DEBUG
  289. [[AWSCognito defaultCognito] setPushPlatform:AWSCognitoSyncPlatformApnsSandbox];
  290. #endif
  291. will set push notifications to use the APNS_SANDBOX if your build targets Debug. Otherwise it will
  292. always use APNS.
  293. */
  294. + (void)setPushPlatform:(AWSCognitoSyncPlatform) pushPlatform;
  295. /**
  296. The push platform for push notifications
  297. */
  298. + (AWSCognitoSyncPlatform)pushPlatform;
  299. /**
  300. Subscribe to a list of datasets. Make sure you have called synchronize on each of the datasets in the list
  301. at least once prior to calling this. Returns a AWSTask. The result of this task will be a NSArray of
  302. AWSCognitoSyncSubscribeToDatasetResponse
  303. */
  304. - (AWSTask *)subscribe:(NSArray<NSString *> *) datasetNames;
  305. /**
  306. Subscribe to all datasets you have locally. Make sure you have called synchronize on all of your local datasets
  307. at least once prior to calling this. Returns a AWSTask. The result of this task will be a NSArray of
  308. AWSCognitoSyncSubscribeToDatasetResponse
  309. */
  310. - (AWSTask *)subscribeAll;
  311. /**
  312. Unsubscribe to a list of datasets. Returns a AWSTask. The result of this task will be a NSArray of
  313. AWSCognitoSyncUnsubscribeToDatasetResponse
  314. */
  315. - (AWSTask *)unsubscribe:(NSArray<NSString *> *) datasetNames;
  316. /**
  317. Unsubscribe to all datasets you have locally. Make sure you have called synchronize on all of your local datasets
  318. at least once prior to calling this. Returns a AWSTask. The result of this task will be a NSArray of
  319. AWSCognitoSyncUnsubscribeToDatasetResponse
  320. */
  321. - (AWSTask *)unsubscribeAll;
  322. @end
  323. NS_ASSUME_NONNULL_END