VBDOfflineStorage

@interface VBDOfflineStorage : NSObject

VBDOfflineStorage 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

    + (nonnull instancetype)sharedOfflineStorage;

  • 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<VBDOfflinePack *> *packs;

  • 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 VBDOfflinePackStateInactive. To begin downloading resources, call -[VBDOfflinePack resume] on the pack from within the completion handler. To monitor download progress, add an observer for VBDOfflinePackProgressChangedNotifications 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<VBDOfflineRegion>)region
             withContext:(nonnull NSData *)context
       completionHandler:
           (nullable VBDOfflinePackAdditionCompletionHandler)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 frees any resources that are no longer required by any remaining packs.

    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.

    Declaration

    Objective-C

    - (void)removePack:(nonnull VBDOfflinePack *)pack
    withCompletionHandler:
        (nullable VBDOfflinePackRemovalCompletionHandler)completion;

    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 VBDOfflinePack 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;

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

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

    Note

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

    Declaration

    Objective-C

    - (void)setMaximumAllowedVietbandoTiles:(uint64_t)maximumCount;