[ios, osx] Distinguish between unknown and inactive state

3 files changed, 38 insertions, 14 deletions

diff --git a/platform/darwin/include/MGLOfflineTask.h b/platform/darwin/include/MGLOfflineTask.h
index 504416aeb9..8b463d1202 100644
--- a/platform/darwin/include/MGLOfflineTask.h
+++ b/platform/darwin/include/MGLOfflineTask.h
@@ -11,27 +11,44 @@ NS_ASSUME_NONNULL_BEGIN
  */
 typedef NS_ENUM (NSInteger, MGLOfflineTaskState) {
     /**
-     The task is incomplete and is not currently downloading. This is the
-     initial state of a task that is added using the
-     `-[MGLOfflineStorage addTaskForRegion:withContext:completionHandler:]`
-     method.
+     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 = 0,
+    MGLOfflineTaskStateInactive = 1,
     /**
-     The task is incomplete and is currently downloading. This is the state of a
-     task after the `-[MGLOfflineTask resume]` method is called.
+     The task is incomplete and is currently downloading.
+     
+     This is the state of a task after the `-[MGLOfflineTask resume]` method is
+     called.
      */
-    MGLOfflineTaskStateActive = 1,
+    MGLOfflineTaskStateActive = 2,
     /**
      The task has downloaded to completion.
      */
-    MGLOfflineTaskStateComplete = 2,
+    MGLOfflineTaskStateComplete = 3,
     /**
      The task has been removed using the
-     `-[MGLOfflineStorage removeTask:withCompletionHandler:]` method. Any
-     messages sent to the task will raise an exception.
+     `-[MGLOfflineStorage removeTask:withCompletionHandler:]` method. Sending
+     any message to the task will raise an exception.
      */
-    MGLOfflineTaskStateInvalid = 3,
+    MGLOfflineTaskStateInvalid = 4,
 };
 
 /**
@@ -91,7 +108,7 @@ typedef struct MGLOfflineTaskProgress {
  The task’s current state.
  
  The state of an inactive or completed task is computed lazily and is set to
- `MGLOfflineTaskStateInactive` by default. If you need the state of a task
+ `MGLOfflineTaskStateUnknown` by default. If you need the state of a task
  inside an `MGLOfflineTaskListingCompletionHandler`, set the `delegate` property
  then call the `-requestProgress` method.
  */
diff --git a/platform/darwin/src/MGLOfflineTask.mm b/platform/darwin/src/MGLOfflineTask.mm
index a78df6a241..9f6aa3312b 100644
--- a/platform/darwin/src/MGLOfflineTask.mm
+++ b/platform/darwin/src/MGLOfflineTask.mm
@@ -51,7 +51,7 @@ private:
 - (instancetype)initWithMBGLRegion:(mbgl::OfflineRegion *)region {
     if (self = [super init]) {
         _mbglOfflineRegion = region;
-        _state = MGLOfflineTaskStateInactive;
+        _state = MGLOfflineTaskStateUnknown;
         
         mbgl::DefaultFileSource *mbglFileSource = [[MGLOfflineStorage sharedOfflineStorage] mbglFileSource];
         MBGLOfflineRegionObserver *mbglObserver = new MBGLOfflineRegionObserver(self);
diff --git a/platform/ios/app/MBXDownloadsTableViewController.m b/platform/ios/app/MBXDownloadsTableViewController.m
index e5edc336a4..9ec665a5d8 100644
--- a/platform/ios/app/MBXDownloadsTableViewController.m
+++ b/platform/ios/app/MBXDownloadsTableViewController.m
@@ -126,6 +126,10 @@ static NSString * const MBXDownloadsTableViewActiveCellReuseIdentifier = @"Activ
                                                                countStyle:NSByteCountFormatterCountStyleFile];
     NSString *statusString;
     switch (task.state) {
+        case MGLOfflineTaskStateUnknown:
+            statusString = @"Calculating progress…";
+            break;
+            
         case MGLOfflineTaskStateInactive:
             statusString = [NSString stringWithFormat:@"%@ of %@ resources (%@)",
                             completedString, expectedString, byteCountString];
@@ -176,6 +180,9 @@ static NSString * const MBXDownloadsTableViewActiveCellReuseIdentifier = @"Activ
     
     MGLOfflineTask *task = self.offlineTasks[indexPath.row];
     switch (task.state) {
+        case MGLOfflineTaskStateUnknown:
+            break;
+            
         case MGLOfflineTaskStateComplete:
             if ([task.region respondsToSelector:@selector(applyToMapView:)]) {
                 [task.region performSelector:@selector(applyToMapView:) withObject:self.mapView];