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
|
#import <Foundation/Foundation.h>
#import "MGLFoundation.h"
#import "MGLOfflineRegion.h"
NS_ASSUME_NONNULL_BEGIN
/**
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. The state of a pack becomes known by
the time the shared `MGLOfflineStorage` object sends the first
`MGLOfflinePackProgressChangedNotification` about the pack. 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
`-[MGLOfflineStorage 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, including tiles, that have been completely
downloaded and are ready to use offline.
*/
uint64_t countOfResourcesCompleted;
/**
The cumulative size of the downloaded resources on disk, including tiles,
measured in bytes.
*/
uint64_t countOfBytesCompleted;
/**
The number of tiles that have been completely downloaded and are ready
to use offline.
*/
uint64_t countOfTilesCompleted;
/**
The cumulative size of the downloaded tiles on disk, measured in bytes.
*/
uint64_t countOfTileBytesCompleted;
/**
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.
To create an instance of `MGLOfflinePack`, use the
`+[MGLOfflineStorage addPackForRegion:withContext:completionHandler:]` method.
A pack created using `-[MGLOfflinePack init]` is immediately invalid.
*/
MGL_EXPORT
@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. To request the pack’s status, use the
`-requestProgress` method. To get notified when the state becomes known and
when it changes, observe KVO change notifications on this pack’s `state` key
path. Alternatively, you can add an observer for
`MGLOfflinePackProgressChangedNotification`s about this pack that come from the
default notification center.
*/
@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. To request the pack’s progress, use the
`-requestProgress` method. To get notified when the progress becomes
known and when it changes, observe KVO change notifications on this pack’s
`state` key path. Alternatively, you can add an observer for
`MGLOfflinePackProgressChangedNotification`s about this pack that come from the
default notification center.
*/
@property (nonatomic, readonly) MGLOfflinePackProgress progress;
/**
Resumes downloading if the pack is inactive.
When a pack resumes after being suspended, it may begin by iterating over the
already downloaded resources. As a result, the `progress` structure’s
`countOfResourcesCompleted` field may revert to 0 before rapidly returning to
the level of progress at the time the pack was suspended.
To temporarily suspend downloading, call the `-suspend` method.
*/
- (void)resume;
/**
Temporarily stops downloading if the pack is active.
A pack suspends asynchronously, so some network requests may be sent after this
method is called. Regardless, the `progress` property will not be updated until
`-resume` is called.
If the pack previously reached a higher level of progress before being
suspended, it may wait to suspend until it returns to that level.
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 whose `state` property is currently
set to `MGLOfflinePackStateUnknown`, observe KVO change notifications on this
pack’s `state` key path, then call this method. Alternatively, you can add an
observer for `MGLOfflinePackProgressChangedNotification` about this pack that
come from the default notification center.
*/
- (void)requestProgress;
@end
NS_ASSUME_NONNULL_END
|
