[ios, osx] Renamed MGLOfflineTask to MGLOfflinePack

“Offline pack” more effectively communicates the persistent nature of the downloaded content.

4 files changed, 247 insertions, 246 deletions

diff --git a/platform/darwin/include/MGLOfflinePack.h b/platform/darwin/include/MGLOfflinePack.h
new file mode 100644
index 0000000000..d1f5a3ed53
--- /dev/null
+++ b/platform/darwin/include/MGLOfflinePack.h
@@ -0,0 +1,208 @@
+#import <Foundation/Foundation.h>
+
+#import "MGLOfflineRegion.h"
+
+NS_ASSUME_NONNULL_BEGIN
+
+@protocol MGLOfflinePackDelegate;
+
+/**
+ The state an offline pack is currently in.
+ */
+typedef NS_ENUM (NSInteger, MGLOfflinePackState) {
+    /**
+     It is unknown whether the pack is inactive, active, or complete.
+     
+     This is the initial state of a pack that is obtained using the
+     `-[MGLOfflineStorage getPacksWithCompletionHandler:]` method. The state
+     becomes known by the time the pack’s delegate receives its first progress
+     update. For inactive packs, you must explicitly request a progress update
+     using the `-[MGLOfflinePack requestProgress]` method.
+     
+     An invalid pack always has a state of `MGLOfflinePackStateInvalid`, never
+     `MGLOfflinePackStateUnknown`.
+     */
+    MGLOfflinePackStateUnknown = 0,
+    /**
+     The pack is incomplete and is not currently downloading.
+     
+     This is the initial state of a pack that is created using the
+     `-[MGLOfflinePack addPackForRegion:withContext:completionHandler:]` method,
+     as well as after the `-[MGLOfflinePack suspend]` method is
+     called.
+     */
+    MGLOfflinePackStateInactive = 1,
+    /**
+     The pack is incomplete and is currently downloading.
+     
+     This is the state of a pack after the `-[MGLOfflinePack resume]` method is
+     called.
+     */
+    MGLOfflinePackStateActive = 2,
+    /**
+     The pack has downloaded to completion.
+     */
+    MGLOfflinePackStateComplete = 3,
+    /**
+     The pack has been removed using the
+     `-[MGLOfflineStorage removePack:withCompletionHandler:]` method. Sending
+     any message to the pack will raise an exception.
+     */
+    MGLOfflinePackStateInvalid = 4,
+};
+
+/**
+ A structure containing information about an offline pack’s current download
+ progress.
+ */
+typedef struct MGLOfflinePackProgress {
+    /**
+     The number of resources that have been completely downloaded and are ready
+     to use offline.
+     */
+    uint64_t countOfResourcesCompleted;
+    /**
+     The cumulative size of the downloaded resources on disk, measured in bytes.
+     */
+    uint64_t countOfBytesCompleted;
+    /**
+     The minimum number of resources that must be downloaded in order to view
+     the pack’s full region without any omissions.
+     
+     At the beginning of a download, this count is a lower bound; the number of
+     expected resources may increase as the download progresses.
+     */
+    uint64_t countOfResourcesExpected;
+    /**
+     The maximum number of resources that must be downloaded in order to view
+     the pack’s full region without any omissions.
+     
+     At the beginning of a download, when the exact number of required resources
+     is unknown, this field is set to `UINT64_MAX`. Thus this count is always an
+     upper bound.
+     */
+    uint64_t maximumResourcesExpected;
+} MGLOfflinePackProgress;
+
+/**
+ An `MGLOfflinePack` represents a collection of resources necessary for viewing
+ a region offline to a local database. It provides an optional
+ `MGLOfflinePackDelegate` object with progress updates as data or errors arrive
+ from the server.
+ */
+@interface MGLOfflinePack : NSObject
+
+/**
+ The region for which the pack manages resources.
+ */
+@property (nonatomic, readonly) id <MGLOfflineRegion> region;
+
+/**
+ Arbitrary data stored alongside the downloaded resources.
+ 
+ The context typically holds application-specific information for identifying
+ the pack, such as a user-selected name.
+ */
+@property (nonatomic, readonly) NSData *context;
+
+/**
+ The pack’s current state.
+ 
+ The state of an inactive or completed pack is computed lazily and is set to
+ `MGLOfflinePackStateUnknown` by default. If you need the state of a pack
+ inside an `MGLOfflinePackListingCompletionHandler`, set the `delegate` property
+ then call the `-requestProgress` method.
+ */
+@property (nonatomic, readonly) MGLOfflinePackState state;
+
+/**
+ The pack’s current progress.
+ 
+ The progress of an inactive or completed pack is computed lazily, and all its
+ fields are set to 0 by default. If you need the progress of a pack inside an
+ `MGLOfflinePackListingCompletionHandler`, set the `delegate` property then call
+ the `-requestProgress` method.
+ */
+@property (nonatomic, readonly) MGLOfflinePackProgress progress;
+
+/**
+ The pack’s delegate.
+ 
+ You can use the offline pack delegate to be notified of any changes in the
+ pack’s progress and of any errors while downloading. For more information, see
+ the `MGLOfflinePackDelegate` documentation.
+ */
+@property (nonatomic, weak, nullable) id <MGLOfflinePackDelegate> delegate;
+
+- (instancetype)init NS_UNAVAILABLE;
+
+/**
+ Resumes downloading if the pack is inactive.
+ */
+- (void)resume;
+
+/**
+ Temporarily stops downloading if the pack is active.
+ 
+ To resume downloading, call the `-resume` method.
+ */
+- (void)suspend;
+
+/**
+ Request an asynchronous update to the pack’s `state` and `progress` properties.
+ 
+ The state and progress of an inactive or completed pack are computed lazily. If
+ you need the state or progress of a pack inside an
+ `MGLOfflinePackListingCompletionHandler`, set the `delegate` property then call
+ this method.
+ */
+- (void)requestProgress;
+
+@end
+
+/**
+ The `MGLOfflinePackDelegate` protocol defines methods that a delegate of an
+ `MGLOfflinePack` object can optionally implement to be notified of any changes
+ in the pack’s download progress and of any errors while downloading.
+ */
+@protocol MGLOfflinePackDelegate <NSObject>
+
+@optional
+
+/**
+ Sent whenever the pack’s state or download progress changes. Every change to a
+ field in the `progress` property corresponds to an invocation of this method.
+ 
+ @param pack The pack whose state of progress changed.
+ @param progress The updated progress. To get the updated state, refer to the
+    `state` property.
+ */
+- (void)offlinePack:(MGLOfflinePack *)pack progressDidChange:(MGLOfflinePackProgress)progress;
+
+/**
+ Sent whenever the pack encounters an error while downloading.
+ 
+ Download errors may be recoverable. For example, this pack’s implementation may
+ attempt to re-request failed resources based on an exponential backoff
+ strategy or upon the restoration of network access.
+ 
+ @param pack The pack that encountered an error.
+ @param error A download error. For a list of possible error codes, see
+    `MGLErrorCode`.
+ */
+- (void)offlinePack:(MGLOfflinePack *)pack didReceiveError:(NSError *)error;
+
+/**
+ Sent when the maximum number of Mapbox-hosted tiles has been downloaded and
+ stored on the current device.
+ 
+ Once this limit is reached, no instance of `MGLOfflinePack` can download
+ additional tiles from Mapbox APIs until already downloaded tiles are removed by
+ calling the `-[MGLOfflineStorage removePack:withCompletionHandler:]` method.
+ Contact your Mapbox sales representative to have the limit raised.
+ */
+- (void)offlinePack:(MGLOfflinePack *)pack didReceiveMaximumAllowedMapboxTiles:(uint64_t)maximumCount;
+
+@end
+
+NS_ASSUME_NONNULL_END
diff --git a/platform/darwin/include/MGLOfflineRegion.h b/platform/darwin/include/MGLOfflineRegion.h
index 04d2327293..cf98e253bd 100644
--- a/platform/darwin/include/MGLOfflineRegion.h
+++ b/platform/darwin/include/MGLOfflineRegion.h
@@ -6,8 +6,8 @@ NS_ASSUME_NONNULL_BEGIN
 
 /**
  An object conforming to the `MGLOfflineRegion` protocol determines which
- resources are required by an `MGLOfflineTask` object. At present, only
- instances of `MGLTilePyramidOfflineRegion` may be used as `MGLOfflineTask`
+ resources are required by an `MGLOfflinePack` object. At present, only
+ instances of `MGLTilePyramidOfflineRegion` may be used as `MGLOfflinePack`
  regions, but additional conforming implementations may be added in the future.
  */
 @protocol MGLOfflineRegion <NSObject>
diff --git a/platform/darwin/include/MGLOfflineStorage.h b/platform/darwin/include/MGLOfflineStorage.h
index 4844d9d4a8..022c1f0a1e 100644
--- a/platform/darwin/include/MGLOfflineStorage.h
+++ b/platform/darwin/include/MGLOfflineStorage.h
@@ -4,43 +4,43 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
-@class MGLOfflineTask;
+@class MGLOfflinePack;
 @protocol MGLOfflineRegion;
 
 /**
- A block to be called once an offline task has been completely created and
+ A block to be called once an offline pack has been completely created and
  added.
  
- @param task Contains a pointer to the newly added task, or `nil` if there was
-    an error creating or adding the task.
+ @param pack Contains a pointer to the newly added pack, or `nil` if there was
+    an error creating or adding the pack.
  @param error Contains a pointer to an error object (if any) indicating why the
-    task could not be created or added. For a list of possible error codes, see
+    pack could not be created or added. For a list of possible error codes, see
     `MGLErrorCode`.
  */
-typedef void (^MGLOfflineTaskAdditionCompletionHandler)(MGLOfflineTask * _Nullable task, NSError * _Nullable error);
+typedef void (^MGLOfflinePackAdditionCompletionHandler)(MGLOfflinePack * _Nullable pack, NSError * _Nullable error);
 
 /**
- A block to be called once an offline task has been completely invalidated and
+ A block to be called once an offline pack has been completely invalidated and
  removed.
  
  @param error Contains a pointer to an error object (if any) indicating why the
-    task could not be invalidated or removed.
+    pack could not be invalidated or removed.
  */
-typedef void (^MGLOfflineTaskRemovalCompletionHandler)(NSError * _Nullable error);
+typedef void (^MGLOfflinePackRemovalCompletionHandler)(NSError * _Nullable error);
 
 /**
- A block to be called with a complete list of offline tasks.
+ A block to be called with a complete list of offline packs.
  
- @param task Contains a pointer an array of tasks, or `nil` if there was an
-    error obtaining the tasks.
+ @param pack Contains a pointer an array of packs, or `nil` if there was an
+    error obtaining the packs.
  @param error Contains a pointer to an error object (if any) indicating why the
-    list of tasks could not be obtained.
+    list of packs could not be obtained.
  */
-typedef void (^MGLOfflineTaskListingCompletionHandler)(NS_ARRAY_OF(MGLOfflineTask *) *tasks, NSError * _Nullable error);
+typedef void (^MGLOfflinePackListingCompletionHandler)(NS_ARRAY_OF(MGLOfflinePack *) *packs, NSError * _Nullable error);
 
 /**
  MGLOfflineStorage implements a singleton (shared object) that manages offline
- tasks. All of this class’s instance methods are asynchronous, reflecting the
+ packs. All of this class’s instance methods are asynchronous, reflecting the
  fact that offline resources are stored in a database.
  */
 @interface MGLOfflineStorage : NSObject
@@ -53,53 +53,53 @@ typedef void (^MGLOfflineTaskListingCompletionHandler)(NS_ARRAY_OF(MGLOfflineTas
 - (instancetype)init NS_UNAVAILABLE;
 
 /**
- Creates and registers an offline task that downloads the resources needed to
+ Creates and registers an offline pack that downloads the resources needed to
  use the given region offline.
  
- The resulting task starts out with a state of `MGLOfflineTaskStateInactive`. To
- begin downloading resources, call `-[MGLOfflineTask resume]`. To monitor
- download progress, set the task’s `delegate` property to an object that
- conforms to the `MGLOfflineTaskDelegate` protocol.
+ The resulting pack starts out with a state of `MGLOfflinePackStateInactive`. To
+ begin downloading resources, call `-[MGLOfflinePack resume]`. To monitor
+ download progress, set the pack’s `delegate` property to an object that
+ conforms to the `MGLOfflinePackDelegate` protocol.
  
  @param region A region to download.
  @param context Arbitrary data to store alongside the downloaded resources.
- @param completion The completion handler to call once the task has been added.
+ @param completion The completion handler to call once the pack has been added.
     This handler is executed asynchronously on the main queue.
  */
-- (void)addTaskForRegion:(id <MGLOfflineRegion>)region withContext:(NSData *)context completionHandler:(MGLOfflineTaskAdditionCompletionHandler)completion;
+- (void)addPackForRegion:(id <MGLOfflineRegion>)region withContext:(NSData *)context completionHandler:(MGLOfflinePackAdditionCompletionHandler)completion;
 
 /**
- Unregisters the given offline task and frees any resources that are no longer
- required by any remaining tasks.
+ Unregisters the given offline pack and frees any resources that are no longer
+ required by any remaining packs.
  
- As soon as this method is called on a task, the task becomes invalid; any
+ As soon as this method is called on a pack, the pack becomes invalid; any
  attempt to send it a message will result in an exception being thrown. If an
- error occurs and the task cannot be removed, do not attempt to reuse the task
- object. Instead, use the `-getTasksWithCompletionHandler:` method to obtain a
- valid pointer to the task object.
+ error occurs and the pack cannot be removed, do not attempt to reuse the pack
+ object. Instead, use the `-getPacksWithCompletionHandler:` method to obtain a
+ valid pointer to the pack object.
  
- @param task The offline task to remove.
- @param completion The completion handler to call once the task has been
+ @param pack The offline pack to remove.
+ @param completion The completion handler to call once the pack has been
     removed. This handler is executed asynchronously on the main queue.
  */
-- (void)removeTask:(MGLOfflineTask *)task withCompletionHandler:(MGLOfflineTaskRemovalCompletionHandler)completion;
+- (void)removePack:(MGLOfflinePack *)pack withCompletionHandler:(MGLOfflinePackRemovalCompletionHandler)completion;
 
 /**
- Asynchronously calls a completion callback with all existing offline tasks.
+ Asynchronously calls a completion callback with all existing offline packs.
  
- @param completion The completion handler to call with the list of tasks. This
+ @param completion The completion handler to call with the list of packs. This
      handler is executed asynchronously on the main queue.
  */
-- (void)getTasksWithCompletionHandler:(MGLOfflineTaskListingCompletionHandler)completion;
+- (void)getPacksWithCompletionHandler:(MGLOfflinePackListingCompletionHandler)completion;
 
 /**
  Sets the maximum number of Mapbox-hosted tiles that may be downloaded and
  stored on the current device.
  
  Once this limit is reached,
- `-[MGLOfflineTaskDelegate offlineTask:didReceiveMaximumAllowedMapboxTiles:]` is
- called on every delegate of `MGLOfflineTask` until already downloaded tiles are
- removed by calling the `-removeTask:withCompletionHandler:` method.
+ `-[MGLOfflinePackDelegate offlinePack:didReceiveMaximumAllowedMapboxTiles:]` is
+ called on every delegate of `MGLOfflinePack` until already downloaded tiles are
+ removed by calling the `-removePack:withCompletionHandler:` method.
  
  @note The [Mapbox Terms of Service](https://www.mapbox.com/tos/) prohibits
     changing or bypassing this limit without permission from Mapbox. Contact
diff --git a/platform/darwin/include/MGLOfflineTask.h b/platform/darwin/include/MGLOfflineTask.h
deleted file mode 100644
index 8b463d1202..0000000000
--- a/platform/darwin/include/MGLOfflineTask.h
+++ /dev/null
@@ -1,207 +0,0 @@
-#import <Foundation/Foundation.h>
-
-#import "MGLOfflineRegion.h"
-
-NS_ASSUME_NONNULL_BEGIN
-
-@protocol MGLOfflineTaskDelegate;
-
-/**
- The state an offline task is currently in.
- */
-typedef NS_ENUM (NSInteger, MGLOfflineTaskState) {
-    /**
-     It is unknown whether the task is inactive, active, or complete.
-     
-     This is the initial state of a task that is obtained using the
-     `-[MGLOfflineStorage getTasksWithCompletionHandler:]` method. The state
-     becomes known by the time the task’s delegate receives its first progress
-     update. For inactive tasks, you must explicitly request a progress update
-     using the `-[MGLOfflineTask requestProgress]` method.
-     
-     An invalid task always has a state of `MGLOfflineTaskStateInvalid`, never
-     `MGLOfflineTaskStateUnknown`.
-     */
-    MGLOfflineTaskStateUnknown = 0,
-    /**
-     The task is incomplete and is not currently downloading.
-     
-     This is the initial state of a task that is created using the
-     `-[MGLOfflineTask addTaskForRegion:withContext:completionHandler:]` method,
-     as well as after the `-[MGLOfflineTask suspend]` method is
-     called.
-     */
-    MGLOfflineTaskStateInactive = 1,
-    /**
-     The task is incomplete and is currently downloading.
-     
-     This is the state of a task after the `-[MGLOfflineTask resume]` method is
-     called.
-     */
-    MGLOfflineTaskStateActive = 2,
-    /**
-     The task has downloaded to completion.
-     */
-    MGLOfflineTaskStateComplete = 3,
-    /**
-     The task has been removed using the
-     `-[MGLOfflineStorage removeTask:withCompletionHandler:]` method. Sending
-     any message to the task will raise an exception.
-     */
-    MGLOfflineTaskStateInvalid = 4,
-};
-
-/**
- A structure containing information about an offline task’s current download
- progress.
- */
-typedef struct MGLOfflineTaskProgress {
-    /**
-     The number of resources that have been completely downloaded and are ready
-     to use offline.
-     */
-    uint64_t countOfResourcesCompleted;
-    /**
-     The cumulative size of the downloaded resources on disk, measured in bytes.
-     */
-    uint64_t countOfBytesCompleted;
-    /**
-     The minimum number of resources that must be downloaded in order to view
-     the task’s full region without any omissions.
-     
-     At the beginning of a download, this count is a lower bound; the number of
-     expected resources may increase as the download progresses.
-     */
-    uint64_t countOfResourcesExpected;
-    /**
-     The maximum number of resources that must be downloaded in order to view
-     the task’s full region without any omissions.
-     
-     At the beginning of a download, when the exact number of required resources
-     is unknown, this field is set to `UINT64_MAX`. Thus this count is always an
-     upper bound.
-     */
-    uint64_t maximumResourcesExpected;
-} MGLOfflineTaskProgress;
-
-/**
- An `MGLOfflineTask` writes the resources necessary for viewing a region offline
- to a local database, providing an optional `MGLOfflineTaskDelegate` object with
- progress updates as data or errors arrive from the server.
- */
-@interface MGLOfflineTask : NSObject
-
-/**
- The region for which the task manages resources.
- */
-@property (nonatomic, readonly) id <MGLOfflineRegion> region;
-
-/**
- Arbitrary data stored alongside the downloaded resources.
- 
- The context typically holds application-specific information for identifying
- the task, such as a user-selected name.
- */
-@property (nonatomic, readonly) NSData *context;
-
-/**
- The task’s current state.
- 
- The state of an inactive or completed task is computed lazily and is set to
- `MGLOfflineTaskStateUnknown` by default. If you need the state of a task
- inside an `MGLOfflineTaskListingCompletionHandler`, set the `delegate` property
- then call the `-requestProgress` method.
- */
-@property (nonatomic, readonly) MGLOfflineTaskState state;
-
-/**
- The task’s current progress.
- 
- The progress of an inactive or completed task is computed lazily, and all its
- fields are set to 0 by default. If you need the progress of a task inside an
- `MGLOfflineTaskListingCompletionHandler`, set the `delegate` property then call
- the `-requestProgress` method.
- */
-@property (nonatomic, readonly) MGLOfflineTaskProgress progress;
-
-/**
- The task’s delegate.
- 
- You can use the offline task delegate to be notified of any changes in the
- task’s progress and of any errors while downloading. For more information, see
- the `MGLOfflineTaskDelegate` documentation.
- */
-@property (nonatomic, weak, nullable) id <MGLOfflineTaskDelegate> delegate;
-
-- (instancetype)init NS_UNAVAILABLE;
-
-/**
- Resumes downloading if the task is inactive.
- */
-- (void)resume;
-
-/**
- Temporarily stops downloading if the task is active.
- 
- To resume downloading, call the `-resume` method.
- */
-- (void)suspend;
-
-/**
- Request an asynchronous update to the task’s `state` and `progress` properties.
- 
- The state and progress of an inactive or completed task are computed lazily. If
- you need the state or progress of a task inside an
- `MGLOfflineTaskListingCompletionHandler`, set the `delegate` property then call
- this method.
- */
-- (void)requestProgress;
-
-@end
-
-/**
- The `MGLOfflineTaskDelegate` protocol defines methods that a delegate of an
- `MGLOfflineTask` object can optionally implement to be notified of any changes
- in the task’s download progress and of any errors while downloading.
- */
-@protocol MGLOfflineTaskDelegate <NSObject>
-
-@optional
-
-/**
- Sent whenever the task’s state or download progress changes. Every change to a
- field in the `progress` property corresponds to an invocation of this method.
- 
- @param task The task whose state of progress changed.
- @param progress The updated progress. To get the updated state, refer to the
-    `state` property.
- */
-- (void)offlineTask:(MGLOfflineTask *)task progressDidChange:(MGLOfflineTaskProgress)progress;
-
-/**
- Sent whenever the task encounters an error while downloading.
- 
- Download errors may be recoverable. For example, this task’s implementation may
- attempt to re-request failed resources based on an exponential backoff
- strategy or upon the restoration of network access.
- 
- @param task The task that encountered an error.
- @param error A download error. For a list of possible error codes, see
-    `MGLErrorCode`.
- */
-- (void)offlineTask:(MGLOfflineTask *)task didReceiveError:(NSError *)error;
-
-/**
- Sent when the maximum number of Mapbox-hosted tiles has been downloaded and
- stored on the current device.
- 
- Once this limit is reached, no instance of `MGLOfflineTask` can download
- additional tiles from Mapbox APIs until already downloaded tiles are removed by
- calling the `-[MGLOfflineStorage removeTask:withCompletionHandler:]` method.
- Contact your Mapbox sales representative to have the limit raised.
- */
-- (void)offlineTask:(MGLOfflineTask *)task didReceiveMaximumAllowedMapboxTiles:(uint64_t)maximumCount;
-
-@end
-
-NS_ASSUME_NONNULL_END