summaryrefslogtreecommitdiff
path: root/platform/darwin/src/MGLOfflinePack.h
blob: 3d4422da336bfaa8947f2280cee39518340edbe4 (plain)
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

/**
 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
     `-[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, 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.
 */
@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.
 
 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;

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