diff options
author | John Firebaugh <john.firebaugh@gmail.com> | 2016-02-05 17:10:13 -0800 |
---|---|---|
committer | John Firebaugh <john.firebaugh@gmail.com> | 2016-02-10 15:40:20 -0800 |
commit | c3c4c7b9a695ad1dbebe57242ba071103fe9a567 (patch) | |
tree | e205ecdc6a2f6318c6ba6308b5aa8baacc42f481 /include/mbgl/storage/offline.hpp | |
parent | e9302c797f68c7e48b908b87b126045c8c5e5209 (diff) | |
download | qtlocation-mapboxgl-c3c4c7b9a695ad1dbebe57242ba071103fe9a567.tar.gz |
[core] Interface and implementation for offline
Diffstat (limited to 'include/mbgl/storage/offline.hpp')
-rw-r--r-- | include/mbgl/storage/offline.hpp | 181 |
1 files changed, 181 insertions, 0 deletions
diff --git a/include/mbgl/storage/offline.hpp b/include/mbgl/storage/offline.hpp new file mode 100644 index 0000000000..dd63cf968f --- /dev/null +++ b/include/mbgl/storage/offline.hpp @@ -0,0 +1,181 @@ +#pragma once + +#include <mbgl/util/geo.hpp> +#include <mbgl/util/optional.hpp> +#include <mbgl/style/types.hpp> +#include <mbgl/storage/response.hpp> + +#include <string> +#include <vector> +#include <functional> + +namespace mbgl { + +class TileID; +class SourceInfo; + +/* + * An offline region defined by a style URL, geographic bounding box, zoom range, and + * device pixel ratio. + * + * Both minZoom and maxZoom must be ≥ 0, and maxZoom must be ≥ minZoom. + * + * maxZoom may be ∞, in which case for each tile source, the region will include + * tiles from minZoom up to the maximum zoom level provided by that source. + * + * pixelRatio must be ≥ 0 and should typically be 1.0 or 2.0. + */ +class OfflineTilePyramidRegionDefinition { +public: + OfflineTilePyramidRegionDefinition(const std::string&, const LatLngBounds&, double, double, float); + + /* Private */ + std::vector<TileID> tileCover(SourceType, uint16_t tileSize, const SourceInfo&) const; + + const std::string styleURL; + const LatLngBounds bounds; + const double minZoom; + const double maxZoom; + const float pixelRatio; +}; + +/* + * For the present, a tile pyramid is the only type of offline region. In the future, + * other definition types will be available and this will be a variant type. + */ +using OfflineRegionDefinition = OfflineTilePyramidRegionDefinition; + +/* + * The encoded format is private. + */ +std::string encodeOfflineRegionDefinition(const OfflineRegionDefinition&); +OfflineRegionDefinition decodeOfflineRegionDefinition(const std::string&); + +/* + * Arbitrary binary region metadata. The contents are opaque to the mbgl implementation; + * it just stores and retrieves a BLOB. SDK bindings should leave the interpretation of + * this data up to the application; they _should not_ enforce a higher-level data format. + * In the future we want offline database to be portable across target platforms, and a + * platform-specific metadata format would prevent that. + */ +using OfflineRegionMetadata = std::vector<uint8_t>; + +/* + * A region is either inactive (not downloading, but previously-downloaded + * resources are available for use), or active (resources are being downloaded + * or will be downloaded, if necessary, when network access is available). + * + * This state is independent of whether or not the complete set of resources + * is currently available for offline use. To check if that is the case, use + * `OfflineRegionStatus::complete()`. + */ +enum class OfflineRegionDownloadState { + Inactive, + Active +}; + +/* + * A region's status includes its active/inactive state as well as counts + * of the number of resources that have completed downloading, their total + * size in bytes, and the total number of resources that are required. + * + * Note that the total required size in bytes is not currently available. A + * future API release may provide an estimate of this number. + */ +class OfflineRegionStatus { +public: + OfflineRegionDownloadState downloadState = OfflineRegionDownloadState::Inactive; + + /** + * The number of resources that have been fully downloaded and are ready for + * offline access. + */ + uint64_t completedResourceCount = 0; + + /** + * The cumulative size, in bytes, of all resources that have been fully downloaded. + */ + uint64_t completedResourceSize = 0; + + /** + * The number of resources that are known to be required for this region. See the + * documentation for `requiredResourceCountIsIndeterminate` for an important caveat + * about this number. + */ + uint64_t requiredResourceCount = 0; + + /** + * This property is true during early phases of an offline download, when the total + * required resource count is unknown and requiredResourceCount is merely a lower + * bound. + * + * Specifically, it is true before until the style and tile sources have been + * downloaded, and false thereafter. + */ + bool requiredResourceCountIsIndeterminate = true; + + bool complete() const { + return completedResourceCount == requiredResourceCount; + } +}; + +/* + * A region can have a single observer, which gets notified whenever a change + * to the region's status occurs. + */ +class OfflineRegionObserver { +public: + virtual ~OfflineRegionObserver() = default; + + /* + * Implement this method to be notified of a change in the status of an + * offline region. Status changes include any change in state of the members + * of OfflineRegionStatus. + * + * Note that this method will be executed on the database thread; it is the + * responsibility of the SDK bindings to wrap this object in an interface that + * re-executes the user-provided implementation on the main thread. + */ + virtual void statusChanged(OfflineRegionStatus) {} + + /* + * Implement this method to be notified of errors encountered while downloading + * regional resources. Such errors may be recoverable; for example the implementation + * will attempt to re-request failed resources based on an exponential backoff + * algorithm, or when it detects that network access has been restored. + * + * Note that this method will be executed on the database thread; it is the + * responsibility of the SDK bindings to wrap this object in an interface that + * re-executes the user-provided implementation on the main thread. + */ + virtual void responseError(Response::Error) {} +}; + +class OfflineRegion { +public: + // Move-only; not publicly constructible. + OfflineRegion(OfflineRegion&&); + OfflineRegion& operator=(OfflineRegion&&); + ~OfflineRegion(); + + OfflineRegion() = delete; + OfflineRegion(const OfflineRegion&) = delete; + OfflineRegion& operator=(const OfflineRegion&) = delete; + + int64_t getID() const; + const OfflineRegionDefinition& getDefinition() const; + const OfflineRegionMetadata& getMetadata() const; + +private: + friend class OfflineDatabase; + + OfflineRegion(int64_t id, + const OfflineRegionDefinition&, + const OfflineRegionMetadata&); + + const int64_t id; + const OfflineRegionDefinition definition; + const OfflineRegionMetadata metadata; +}; + +} // namespace mbgl |