# MGLOfflineStorage

    @interface MGLOfflineStorage : NSObject

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

#### Related examples

See the Download an offline map example to learn how to create and register an offline pack for a defined region.

- `sharedOfflineStorage`

  Returns the shared offline storage object.

  #### Declaration

  Objective-C

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

  Swift

      class var shared: MGLOfflineStorage { get }

  View Source on GitHub

### Adding Contents of File

- `-addContentsOfFile:withCompletionHandler:`

  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 MGLBatchedOfflinePackAdditionCompletionHandler)completion;

  Swift

      func addContents(ofFile filePath: String, withCompletionHandler completion: MGLBatchedOfflinePackAdditionCompletionHandler? = 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.

  View Source on GitHub
- `-addContentsOfURL:withCompletionHandler:`

  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 MGLBatchedOfflinePackAdditionCompletionHandler)completion;

  Swift

      func addContents(of fileURL: URL, withCompletionHandler completion: MGLBatchedOfflinePackAdditionCompletionHandler? = 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.

  View Source on GitHub

### Accessing the Delegate

- `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<MGLOfflineStorageDelegate>
          delegate;

  Swift

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

  View Source on GitHub

### Managing Offline Packs

- `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<MGLOfflinePack *> *packs;

  Swift

      var packs: [MGLOfflinePack]? { get }

  View Source on GitHub
- `-addPackForRegion:withContext:completionHandler:`

  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.

  #### Declaration

  Objective-C

      - (void)addPackForRegion:(nonnull id<MGLOfflineRegion>)region
                   withContext:(nonnull NSData *)context
             completionHandler:
                 (nullable MGLOfflinePackAdditionCompletionHandler)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.

  View Source on GitHub
- `-removePack:withCompletionHandler:`

  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 MGLOfflinePack *)pack
          withCompletionHandler:
              (nullable MGLOfflinePackRemovalCompletionHandler)completion;

  Swift

      func removePack(_ pack: MGLOfflinePack, withCompletionHandler completion: MGLOfflinePackRemovalCompletionHandler? = 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.

  View Source on GitHub
- `-reloadPacks`

  Forcibly, asynchronously reloads the `packs` property. At some point after this method is called, the pointer values of the `MGLOfflinePack` 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()

  View Source on GitHub
- `-setMaximumAllowedMapboxTiles:`

  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 Mapbox Terms of Service prohibits changing or bypassing this limit without permission from Mapbox. Contact your Mapbox sales representative to have the limit raised.

  #### Declaration

  Objective-C

      - (void)setMaximumAllowedMapboxTiles:(uint64_t)maximumCount;

  Swift

      func setMaximumAllowedMapboxTiles(_ maximumCount: UInt64)

  View Source on GitHub
- `countOfBytesCompleted`

  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`.

  #### Declaration

  Objective-C

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

  Swift

      var countOfBytesCompleted: UInt64 { get }

  View Source on GitHub