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
|
#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
|
