diff options
Diffstat (limited to 'platform/darwin/src/MGLOfflineStorage.h')
| -rw-r--r-- | platform/darwin/src/MGLOfflineStorage.h | 106 |
1 files changed, 83 insertions, 23 deletions
diff --git a/platform/darwin/src/MGLOfflineStorage.h b/platform/darwin/src/MGLOfflineStorage.h index 9125c5341e..16f134adb1 100644 --- a/platform/darwin/src/MGLOfflineStorage.h +++ b/platform/darwin/src/MGLOfflineStorage.h @@ -7,6 +7,7 @@ NS_ASSUME_NONNULL_BEGIN @class MGLOfflinePack; @protocol MGLOfflineRegion; +@protocol MGLOfflineStorageDelegate; /** Posted by the shared `MGLOfflineStorage` object when an `MGLOfflinePack` @@ -14,14 +15,14 @@ NS_ASSUME_NONNULL_BEGIN downloaded or because the pack discovers during the download that more resources are required for offline viewing. This notification is posted whenever any field in the `progress` property changes. - + The `object` is the `MGLOfflinePack` object whose progress changed. The `userInfo` dictionary contains the pack’s current state in the `MGLOfflinePackStateUserInfoKey` key and details about the pack’s current progress in the `MGLOfflinePackProgressUserInfoKey` key. You may also consult the `MGLOfflinePack.state` and `MGLOfflinePack.progress` properties, which provide the same values. - + If you only need to observe changes in a particular pack’s progress, you can alternatively observe KVO change notifications to the pack’s `progress` key path. @@ -34,7 +35,7 @@ extern MGL_EXPORT const NSNotificationName MGLOfflinePackProgressChangedNotifica may not warrant the user’s attention. For example, the pack’s implementation may attempt to re-request failed resources based on an exponential backoff strategy or upon the restoration of network access. - + The `object` is the `MGLOfflinePack` object that encountered the error. The `userInfo` dictionary contains the error object in the `MGLOfflinePackErrorUserInfoKey` key. @@ -44,11 +45,11 @@ extern MGL_EXPORT const NSNotificationName MGLOfflinePackErrorNotification; /** Posted by the shared `MGLOfflineStorage` object when the maximum number of Mapbox-hosted tiles has been downloaded and stored on the current device. - + The `object` is the `MGLOfflinePack` object that reached the tile limit in the course of downloading. The `userInfo` dictionary contains the tile limit in the `MGLOfflinePackMaximumCountUserInfoKey` key. - + Once this limit is reached, no instance of `MGLOfflinePack` can download additional tiles from Mapbox APIs until already downloaded tiles are removed by calling the `-[MGLOfflineStorage removePack:withCompletionHandler:]` method. @@ -107,10 +108,10 @@ extern MGL_EXPORT NSString * const MGLOfflinePackMaximumCountUserInfoKey __attri /** A block to be called once an offline pack has been completely created and added. - + An application typically calls the `-resume` method on the pack inside this completion handler to begin the download. - + @param pack Contains a pointer to the newly added pack, or `nil` if there was an error creating or adding the pack. @param error Contains a pointer to an error object (if any) indicating why the @@ -121,17 +122,41 @@ typedef void (^MGLOfflinePackAdditionCompletionHandler)(MGLOfflinePack * _Nullab /** A block to be called once an offline pack has been completely invalidated and removed. - + Avoid any references to the pack inside this completion handler: by the time this completion handler is executed, the pack has become invalid, and any messages passed to it will raise an exception. - + @param error Contains a pointer to an error object (if any) indicating why the pack could not be invalidated or removed. */ typedef void (^MGLOfflinePackRemovalCompletionHandler)(NSError * _Nullable error); /** + The type of resource that is requested. + */ +typedef NS_ENUM(NSUInteger, MGLResourceKind) { + /** Unknown type */ + MGLResourceKindUnknown, + /** Style sheet JSON file */ + MGLResourceKindStyle, + /** TileJSON file as specified in https://www.mapbox.com/mapbox-gl-js/style-spec/#root-sources */ + MGLResourceKindSource, + /** A vector or raster tile as described in the style sheet at + https://www.mapbox.com/mapbox-gl-js/style-spec/#sources */ + MGLResourceKindTile, + /** Signed distance field glyphs for text rendering. These are the URLs specified in the style + in https://www.mapbox.com/mapbox-gl-js/style-spec/#root-glyphs */ + MGLResourceKindGlyphs, + /** Image part of a sprite sheet. It is constructed of the prefix in + https://www.mapbox.com/mapbox-gl-js/style-spec/#root-sprite and a PNG file extension. */ + MGLResourceKindSpriteImage, + /** JSON part of a sprite sheet. It is constructed of the prefix in + https://www.mapbox.com/mapbox-gl-js/style-spec/#root-sprite and a JSON file extension. */ + MGLResourceKindSpriteJSON, +}; + +/** MGLOfflineStorage implements a singleton (shared object) that manages offline packs. All of this class’s instance methods are asynchronous, reflecting the fact that offline resources are stored in a database. The shared object @@ -145,15 +170,29 @@ MGL_EXPORT */ + (instancetype)sharedOfflineStorage; +#pragma mark - Accessing the Delegate + +/** + The receiver’s delegate. + + An offline storage object sends messages to its delegate to allow it to + transform URLs before they are requested from the internet. This can be used + add or remove custom parameters, or reroute certain requests to other servers + or endpoints. + */ +@property(nonatomic, weak, nullable) IBOutlet id<MGLOfflineStorageDelegate> delegate; + +#pragma mark - Managing Offline Packs + /** An array of all known offline packs, in the order in which they were created. - + This property is set to `nil`, indicating that the receiver does not yet know the existing packs, for an undefined amount of time starting from the moment the shared offline storage object is initialized until the packs are fetched from the database. After that point, this property is always non-nil, but it may be empty to indicate that no packs are present. - + To detect when the shared offline storage object has finished loading its `packs` property, observe KVO change notifications on the `packs` key path. The initial load results in an `NSKeyValueChangeSetting` change. @@ -163,19 +202,19 @@ MGL_EXPORT /** Creates and registers an offline pack that downloads the resources needed to use the given region offline. - + The resulting pack is added to the shared offline storage object’s `packs` property, then the `completion` block is executed with that pack passed in. - + The pack has an initial state of `MGLOfflinePackStateInactive`. To begin downloading resources, call `-[MGLOfflinePack resume]` on the pack from within the completion handler. To monitor download progress, add an observer for `MGLOfflinePackProgressChangedNotification`s about that pack. - + To detect when any call to this method results in a new pack, observe KVO change notifications on the shared offline storage object’s `packs` key path. Additions to that array result in an `NSKeyValueChangeInsertion` change. - + @param region A region to download. @param context Arbitrary data to store alongside the downloaded resources. @param completion The completion handler to call once the pack has been added. @@ -186,17 +225,17 @@ MGL_EXPORT /** Unregisters the given offline pack and allows resources that are no longer required by any remaining packs to be potentially freed. - + As soon as this method is called on a pack, the pack becomes invalid; any attempt to send it a message will result in an exception being thrown. If an error occurs and the pack cannot be removed, do not attempt to reuse the pack object. Instead, if you need continued access to the pack, suspend all packs and use the `-reloadPacks` method to obtain valid pointers to all the packs. - + To detect when any call to this method results in a pack being removed, observe KVO change notifications on the shared offline storage object’s `packs` key path. Removals from that array result in an `NSKeyValueChangeRemoval` change. - + When you remove an offline pack, any resources that are required by that pack, but not other packs, become eligible for deletion from offline storage. Because the backing store used for offline storage is also used as a general purpose @@ -216,9 +255,9 @@ MGL_EXPORT `packs` property change, even if the underlying data for these packs has not changed. If this method is called while a pack is actively downloading, the behavior is undefined. - + You typically do not need to call this method. - + To detect when the shared offline storage object has finished reloading its `packs` property, observe KVO change notifications on the `packs` key path. A reload results in an `NSKeyValueChangeSetting` change. @@ -228,12 +267,12 @@ MGL_EXPORT /** Sets the maximum number of Mapbox-hosted tiles that may be downloaded and stored on the current device. - + Once this limit is reached, an `MGLOfflinePackMaximumMapboxTilesReachedNotification` is posted for every attempt to download additional tiles until already downloaded tiles are removed by calling the `-removePack:withCompletionHandler:` method. - + @note The <a href="https://www.mapbox.com/tos/">Mapbox Terms of Service</a> prohibits changing or bypassing this limit without permission from Mapbox. Contact your Mapbox sales representative to have the limit raised. @@ -242,7 +281,7 @@ MGL_EXPORT /** The cumulative size, measured in bytes, of all downloaded resources on disk. - + The returned value includes all resources, including tiles, whether downloaded as part of an offline pack or due to caching during normal use of `MGLMapView`. */ @@ -250,4 +289,25 @@ MGL_EXPORT @end +/** + The `MGLOfflineStorageDelegate` protocol defines methods that a delegate of an + `MGLOfflineStorage` object can optionally implement to transform various types + of URLs before downloading them via the internet. + */ +@protocol MGLOfflineStorageDelegate <NSObject> + +/** + Sent whenever a URL needs to be transformed. + + @param storage The storage object processing the download. + @param kind The kind of URL to be transformed. + @param url The original URL to be transformed. + @return A URL that will now be downloaded. + */ +- (NSURL *)offlineStorage:(MGLOfflineStorage *)storage + URLForResourceOfKind:(MGLResourceKind)kind + withURL:(NSURL *)url; + +@end + NS_ASSUME_NONNULL_END |