DingiOfflineStorage

 

@interface DingiOfflineStorage : NSObject

DingiOfflineStorage 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 maintains a canonical collection of offline packs in its packs property.

  • Returns the shared offline storage object.

    Declaration

    Objective-C

    @property (readonly, nonatomic, class)
    DingiOfflineStorage *_Nonnull sharedOfflineStorage;

    Swift

    class var shared: DingiOfflineStorage { get }

Adding Contents of File

  • Adds the offline packs located at the given file path to offline storage.

    The file must be a valid offline region database bundled with the application or downloaded separately.

    The resulting packs are added or updated to the shared offline storage object’s packs property, then the completion block is executed.

    Declaration

    Objective-C

    - (void)addContentsOfFile:(nonnull NSString *)filePath
    withCompletionHandler:
        (nullable DingiBatchedOfflinePackAdditionCompletionHandler)completion;

    Swift

    func addContents(ofFile filePath: String, withCompletionHandler completion: DingiBatchedOfflinePackAdditionCompletionHandler? = nil)

    Parameters

    filePath

    A string representation of the file path. The file path must be writable as schema updates may be perfomed.
    completion

    The completion handler to call once the contents of the given file has been added to offline storage. This handler is executed asynchronously on the main queue.

  • Adds the offline packs located at the given URL to offline storage.

    The file must be a valid offline region database bundled with the application or downloaded separately.

    The resulting packs are added or updated to the shared offline storage object’s packs property, then the completion block is executed.

    Declaration

    Objective-C

    - (void)addContentsOfURL:(nonnull NSURL *)fileURL
    withCompletionHandler:
        (nullable DingiBatchedOfflinePackAdditionCompletionHandler)completion;

    Swift

    func addContents(of fileURL: URL, withCompletionHandler completion: DingiBatchedOfflinePackAdditionCompletionHandler? = nil)

    Parameters

    fileURL

    A file URL specifying the file to add. URL should be a valid system path. The file URL must be writable as schema updates may be performed.
    completion

    The completion handler to call once the contents of the given file has been added to offline storage. This handler is executed asynchronously on the main queue.

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.

    Declaration

    Objective-C

    @property (readwrite, nonatomic, nullable) id<DingiOfflineStorageDelegate>
    delegate;

    Swift

    @IBOutlet weak var delegate: DingiOfflineStorageDelegate? { get set }

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.

    Declaration

    Objective-C

    @property (readonly, strong, nonatomic, nullable)
    NSArray<DingiOfflinePack *> *packs;

    Swift

    var packs: [DingiOfflinePack]? { get }

  • 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 DingiOfflinePackStateInactive. To begin downloading resources, call -[DingiOfflinePack resume] on the pack from within the completion handler. To monitor download progress, add an observer for DingiOfflinePackProgressChangedNotifications 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.

    Declaration

    Objective-C

    - (void)addPackForRegion:(nonnull id<DingiOfflineRegion>)region
             withContext:(nonnull NSData *)context
       completionHandler:
           (nullable DingiOfflinePackAdditionCompletionHandler)completion;

    Parameters

    region

    A region to download.
    context

    Arbitrary data to store alongside the downloaded resources.
    completion

    The completion handler to call once the pack has been added. This handler is executed asynchronously on the main queue.

  • 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 cache for map resources, such resources may not be immediately removed if the implementation determines that they remain useful for general performance of the map.

    Declaration

    Objective-C

    - (void)removePack:(nonnull DingiOfflinePack *)pack
    withCompletionHandler:
        (nullable DingiOfflinePackRemovalCompletionHandler)completion;

    Swift

    func removePack(_ pack: DingiOfflinePack, withCompletionHandler completion: DingiOfflinePackRemovalCompletionHandler? = nil)

    Parameters

    pack

    The offline pack to remove.
    completion

    The completion handler to call once the pack has been removed. This handler is executed asynchronously on the main queue.

  • Forcibly, asynchronously reloads the packs property. At some point after this method is called, the pointer values of the DingiOfflinePack objects in the 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.

    Declaration

    Objective-C

    - (void)reloadPacks;

    Swift

    func reloadPacks()

  • Sets the maximum number of Mapbox-hosted tiles that may be downloaded and stored on the current device.

    Once this limit is reached, an DingiOfflinePackMaximumDingiTilesReachedNotification is posted for every attempt to download additional tiles until already downloaded tiles are removed by calling the -removePack:withCompletionHandler: method.

    Note

    The Dingi Terms of Service prohibits changing or bypassing this limit without permission from Dingi. Contact your Dingi sales representative to have the limit raised.

    Declaration

    Objective-C

    - (void)setMaximumAllowedMapboxTiles:(uint64_t)maximumCount;

    Swift

    func setMaximumAllowedMapboxTiles(_ maximumCount: UInt64)

  • 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 DingiMapView.

    Declaration

    Objective-C

    @property (readonly, nonatomic) unsigned long long countOfBytesCompleted;

    Swift

    var countOfBytesCompleted: UInt64 { get }