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
|
#import <Foundation/Foundation.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 becomes known by the time
the shared `MGLOfflineStorage` object sends its first
`MGLOfflinePackProgressChangedNotification`.
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.
To create an instance of `MGLOfflinePack`, use the
`+[MGLOfflineStorage addPackForRegion:withContext:completionHandler:]` method.
A pack created using `-[MGLOfflinePack init]` is immediately invalid.
*/
@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 get notified when the state becomes
known, 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 get notified when the progress becomes
known, 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.
A pack resumes asynchronously. To get notified when this pack resumes, 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.
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. To get notified when this pack resumes, observe
KVO change notifications on this pack’s `state` key path. Alternatively, you
can add an observer for `MGLOfflinePackProgressChangedNotification` about this
pack that come from the default notification center.
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;
@end
/**
Methods for round-tripping `MGLOfflinePackProgress` values.
*/
@interface NSValue (MGLOfflinePackAdditions)
/**
Creates a new value object containing the given `MGLOfflinePackProgress`
structure.
@param progress The value for the new object.
@return A new value object that contains the offline pack progress information.
*/
+ (NSValue *)valueWithMGLOfflinePackProgress:(MGLOfflinePackProgress)progress;
/**
The `MGLOfflinePackProgress` structure representation of the value.
*/
@property (readonly) MGLOfflinePackProgress MGLOfflinePackProgressValue;
@end
NS_ASSUME_NONNULL_END
|
