Offline viewing in iOS and OS X

[1ec5]

This PR implements APIs for offline viewing in the iOS and OS X SDKs, based on the work in #3715. Additionally, iosapp’s interface has been partially rewritten using an Interface Builder storyboard and an interface for managing offline downloads has been added.

Here’s a high-level overview of the new classes:

• MGLTilePyramidOfflineRegion, as the only class currently allowed to conform to MGLOfflineRegion, encapsulates mbgl::OfflineRegionDefinition, acting as a “bill of materials” for an MGLOfflineTask.
• MGLOfflineTask encapsulates mbgl::OfflineRegion and provides methods for pausing and resuming a download. It pairs an MGLOfflineRegion with an opaque context data blob (analogous to mbgl::OfflineRegionMetadata).
• A singleton MGLOfflineStorage object encapsulates mbgl::DefaultFileSource and provides methods for creating and destroying MGLOfflineTask objects.

A word about naming: I chose to diverge from the offline class names used by mbgl and the Android SDK in #4085. The intent is to keep the SDK’s naming intuitive for developers who are familiar with Cocoa development but not necessarily with maps, to avoid the kind of confusion we’ve been seeing around MGLAnnotationImage. In particular, along with MapKit, Core Location, and other Apple-provided frameworks, the iOS SDK already uses the word “region” to refer to a more-or-less geographic model object rather than a task or controller. Additionally, in keeping with strong Cocoa conventions, “context” replaces “metadata” and “delegate” replaces “observer”.

To ensure KVO compliance, MGLOfflineTask registers an internal mbgl::OfflineRegionObserver for its entire lifetime that dispatches progress updates to an optional MGLOfflineTaskDelegate. There is a bit of an impedance mismatch with mbgl::OfflineRegion, which expects all progress information to be requested and communicated to the delegate asynchronously via callbacks. You can see how this gets complicated with -[MGLOfflineTask requestProgress]. I’m not completely opposed to removing the state and progress properties and routing all progress information through an asynchronous API. However, we should then consider some kind of affordance for KVO compliance in the near future, because this is a very common paradigm for frequently changing properties in Cocoa. (KVO would help with hooking up MGLOfflineTask to NSProgress, for example.)

In the iosapp Downloads view, tapping the + button adds and begins a download of the main map’s current viewport, from the current zoom level all the way to the maximum zoom level. It is recommended that you zoom in before using this feature, to avoid maxing out the tile limit. Tapping an in-progress download pauses and resumes the download, while tapping a completed download switches to its associated style and navigates to the downloaded viewport.

Fortuitously, my Internet connection went kaput last night as I was preparing 34611a7801fab053bbbb73ec5af61c63eda4ce38, allowing me to test much of the offline functionality in a real-world environment.

Fixes #3892.

/cc @jfirebaugh @boundsj @friedbunny @zugaldia

[1ec5]

@jfirebaugh suggested calling MGLOfflineTask MGLOfflineRecord, MGLOfflineArchive, or MGLOfflineEntry instead. MGLOfflineRecord sounds the best to me; it would fit right in with MGLOfflineStorage. MGLOfflineArchive could also work, but it’s a little close to the unrelated concepts of keyed archiving and unarchiving. MGLOfflineEntry sounds like the role that a resource plays in the current mbgl::OfflineRegion.

[jfirebaugh]

Further terminology discussion in #4250.

[jfirebaugh]

I believe [task invalidate] should be the first line in this method -- as soon as mbglOfflineRegion is moved out of task, it's invalidated.

[1ec5]

What happens if the removal errors out? Would the region be valid again from mbgl’s perspective, or is it still invalid?

[jfirebaugh]

It's still invalid. As soon as deleteOfflineRegion is called, the caller relinquishes ownership of the region. You can get notified of errors, but not do anything about them, other than obtaining another reference to the region via listOfflineRegions.

[1ec5]

@boundsj pointed out that MGLOfflineStorage should KVO-observe MGLAccountManager’s access token just like MGLMapView does, in case client code sets the access token programmatically at a later point.

[jfirebaugh]

Setting the access token after activating an offline download isn't going to work very well. In that situation, resource downloads may have already been attempted, and OnlineFileSource is not equipped to handle changes to the access token after the fact. We should encourage people to set the token as early as possible.

[1ec5]

Oh, I forgot I already implemented KVO on the access token.

We should encourage people to set the token as early as possible.

Agreed. Even for MGLMapView, setting the access token after initialization doesn’t have guaranteed behavior around caching, but we use KVO because it’s the most reliable way for the shared MGLAccountManager object, all instances of MGLMapView, the shared MGLMapboxEvents object, and now the shared MGLOfflineStorage object to stay on the same page with the same access token.

[jfirebaugh]

You can write these two lines more succinctly and with only one allocation, as:

mbglFileSource->setOfflineRegionObserver(*_mbglOfflineRegion, std::make_unique<MBGLOfflineRegionObserver>(self));

[jfirebaugh]

LGTM. Providing this build passes, .

[1ec5]

Updated jazzy symbol categories in 3622c2d. Fixed iosapp build failures due to the last-minute renaming in 4bcc24d.