MapLibreParticleLab/platform/darwin/include/MGLOfflineTask.h

#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) {
    /**
     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.
     */
    MGLOfflineTaskStateInactive = 0,
    /**
     The task is incomplete and is currently downloading. This is the state of a
     task after the `-[MGLOfflineTask resume]` method is called.
     */
    MGLOfflineTaskStateActive = 1,
    /**
     The task has downloaded to completion.
     */
    MGLOfflineTaskStateComplete = 2,
    /**
     The task has been removed using the
     `-[MGLOfflineStorage removeTask:withCompletionHandler:]` method. Any
     messages sent to the task will raise an exception.
     */
    MGLOfflineTaskStateInvalid = 3,
};

/**
 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
 `MGLOfflineTaskStateInactive` 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