BMPOfflineManager

Objective-C


@interface BMPOfflineManager : NSObject

Swift

class OfflineManager : NSObject

IMPORTANT: Methods from BMPOfflineManager need to be called from the main thread.

This class offers functionality to handle the whole lifecycle of protected and unprotected offline content. Do not create own instances of it, instead use [OfflineManager sharedInstance] to obtain a reference to the singleton.

Depending on the current state of the SourceItem, which can be obtained by calling offlineStateForSourceItem:, different methods are allowed to be called on the BMPOfflineManager. The table below shows all possible and allowed transitions between the different states. Each line describes one transition which happens immediately and synchronous. When there is a method call noted in column “Method call triggering transition”, the “Following State” is entered immediately after the method call returns.

When there is no method call noted, the “Following State” is entered when the event described in column “BMPOfflineManagerListener event” was received.

The “Following State” is always noted under the assumption that no error occurred when calling the transition method, or during processing of the current task. Errors are always reported to offlineManager:didFailWithError:. See the documentation of BMPOfflineManagerListener.h for more information.

Current State Method call triggering transition BMPOfflineManagerListener event Following State
NotDownloaded downloadSourceItem: - Downloading
Downloading cancelDownloadForSourceItem: - Canceling
Downloading suspendDownloadForSourceItem: offlineManagerDidSuspendDownload: Suspended
Downloading - offlineManagerDidFinishDownload: Downloaded
Downloading - offlineManager:didProgressTo: Downloading
Downloaded deleteOfflineDataForSourceItem: - NotDownloaded
Suspended resumeDownloadForSourceItem: offlineManager:didResumeDownloadWithProgress: Downloading
Suspended cancelDownloadForSourceItem: - Canceling
Canceling - offlineManagerDidCancelDownload: NotDownloaded
Downloaded renewOfflineLicenseForSourceItem: offlineManagerDidRenewOfflineLicense: Downloaded

  • Value in megabytes for minimum system free space available before suspending active downloads. Default value is 500Mb.

    Declaration

    Objective-C

    @property (class, nonatomic) NSUInteger minimumAvailableSpaceThreshold;

    Swift

    class var minimumAvailableSpaceThreshold: UInt { get set }

  • Indicates if the OfflineManager is initialized.

    Declaration

    Objective-C

    @property (class, readonly) BOOL isOfflineManagerInitialized;

    Swift

    class var isOfflineManagerInitialized: Bool { get }

  • Specifies if an active WiFi connection is required for downloading media for offline playback. Default is NO.

    Declaration

    Objective-C

    @property (nonatomic) BOOL restrictMediaDownloadsToWiFi;

    Swift

    var restrictMediaDownloadsToWiFi: Bool { get set }

  • Indicates if the OfflineManager has finished restoring suspended downloads.

    Warning

    Any resume or cancel actions triggered before this returns true are not guaranteed and might result in unexpected behaviour.

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL areSuspendedDownloadsRestored;

    Swift

    var areSuspendedDownloadsRestored: Bool { get }

  • The delegate for the OfflineManager

    Declaration

    Objective-C

    @property (nonatomic, weak) id<BMPOfflineManagerDelegate> _Nullable delegate;

  • Unavailable

    Undocumented

    Declaration

    Objective-C

    - (instancetype)init NS_UNAVAILABLE;

  • Unavailable

    Undocumented

    Declaration

    Objective-C

    + (instancetype)new NS_UNAVAILABLE;

  • Declaration

    Objective-C

    + (nonnull instancetype)sharedInstance;

    Swift

    class func sharedInstance() -> Self

    Return Value

    The singleton instance of the BMPOfflineManager.

  • Has to be called in your AppDelegate’s application(application:didFinishLaunchingWithOptions:) method to initialize handling of offline content.

    If the shared instance is already initialized, this method will not have any effect.

    Declaration

    Objective-C

    + (void)initializeOfflineManager;

    Swift

    class func initializeOfflineManager()

  • Has to be called in your AppDelegate’s application(application:didFinishLaunchingWithOptions:) method to initialize handling of offline content.

    Initializes the shared instance with a given OfflineConfiguration. If the shared instance is already initialized, this method will not have any effect.

    Declaration

    Objective-C

    + (void)initializeOfflineManagerWithOfflineConfiguration:
    (nonnull BMPOfflineConfiguration *)offlineConfiguration;

    Swift

    class func initializeOfflineManager(offlineConfiguration: BMPOfflineConfiguration)

    Parameters

    offlineConfiguration

  • Returns the offline state for the given BMPSourceItem.

    Declaration

    Objective-C

    - (BMPOfflineState)offlineStateForSourceItem:
    (nonnull BMPSourceItem *)sourceItem;

    Swift

    func offlineState(for sourceItem: SourceItem) -> BMPOfflineState

    Parameters

    sourceItem

    A BMPSourceItem instance for which the offline state should be determined.

    Return Value

    The offline state for the given BMPSourceItem.

  • Deletes the offline stored media data associated with the given BMPSourceItem. Calling this method is only valid when offlineStateForSourceItem: for the same BMPSourceItem instance returns BMPOfflineStateDownloaded.

    Declaration

    Objective-C

    - (void)deleteOfflineDataForSourceItem:(nonnull BMPSourceItem *)sourceItem;

    Swift

    func deleteOfflineData(for sourceItem: SourceItem)

    Parameters

    sourceItem

    A BMPSourceItem instance for which the offline data should be deleted.

  • Fetches which tracks are available for download. When finished, BMPOfflineManagerListener’s didFetchAvailableTracks:: method is called.

    Declaration

    Objective-C

    - (void)fetchAvailableTracksForSourceItem:(nonnull BMPSourceItem *)sourceItem;

    Swift

    func fetchAvailableTracks(for sourceItem: SourceItem)

    Parameters

    sourceItem

    A BMPSourceItem instance for which the available tracks should be fetched.

  • Downloads the media data associated with the given BMPSourceItem. The highest media bitrate will be selected for download by default. If you want to specify which bitrate should be selected for download, use downloadSourceItem:minimumBitrate:.

    Calling this method is only valid when offlineStateForSourceItem: for the same BMPSourceItem instance returns BMPOfflineStateNotDownloaded.

    Declaration

    Objective-C

    - (void)downloadSourceItem:(nonnull BMPSourceItem *)sourceItem;

    Swift

    func download(sourceItem: SourceItem)

    Parameters

    sourceItem

    A BMPSourceItem instance for which the media data should be downloaded.

  • Deprecated

    Use download(sourceItem:downloadConfiguration:) instead.

    Downloads the media data associated with the given BMPSourceItem. Calling this method is only valid when offlineStateForSourceItem: for the same BMPSourceItem instance returns BMPOfflineStateNotDownloaded.

    Declaration

    Objective-C

    - (void)downloadSourceItem:(nonnull BMPSourceItem *)sourceItem
            minimumBitrate:(nullable NSNumber *)minimumBitrate;

    Swift

    func download(sourceItem: SourceItem, minimumBitrate: NSNumber?)

    Parameters

    sourceItem

    A BMPSourceItem instance for which the media data should be downloaded.
    minimumBitrate

    The lowest media bitrate greater than or equal to this value in bps will be selected for download. If no suitable media bitrate is found, the highest media bitrate will be selected.

  • Downloads the media data associated with the given BMPSourceItem. Calling this method is only valid when offlineStateForSourceItem: for the same BMPSourceItem instance returns BMPOfflineStateNotDownloaded.

    Declaration

    Objective-C

    - (void)downloadSourceItem:(nonnull BMPSourceItem *)sourceItem
     downloadConfiguration:
         (nonnull BMPDownloadConfiguration *)downloadConfiguration;

    Swift

    func download(sourceItem: SourceItem, downloadConfiguration: DownloadConfiguration)

    Parameters

    sourceItem

    A BMPSourceItem instance for which the media data should be downloaded.
    downloadConfiguration

    The BMPDownloadConfiguration used for this download

  • Downloads the media data associated with the given BMPSourceItem depending on the given BMPOfflineTrackSelection. Calling this method is only valid when offlineStateForSourceItem: for the same BMPSourceItem instance returns BMPOfflineStateNotDownloaded.

    Declaration

    Objective-C

    - (void)downloadSourceItem:(nonnull BMPSourceItem *)sourceItem
                    tracks:(nonnull BMPOfflineTrackSelection *)tracks
     downloadConfiguration:
         (nonnull BMPDownloadConfiguration *)downloadConfiguration;

    Swift

    func download(sourceItem: SourceItem, tracks: OfflineTrackSelection, downloadConfiguration: DownloadConfiguration)

    Parameters

    sourceItem

    A BMPSourceItem instance for which the media data should be downloaded.
    tracks

    a BMPOfflineTrackSelection specifying which tracks to download
    downloadConfiguration

    The BMPDownloadConfiguration used for this download

  • Cancels all running download tasks associated with the given BMPSourceItem and deletes the partially downloaded content from disk. Calling this method is only valid when offlineStateForSourceItem: for the same BMPSourceItem instance returns BMPOfflineStateDownloading or BMPOfflineStateSuspended.

    Declaration

    Objective-C

    - (void)cancelDownloadForSourceItem:(nonnull BMPSourceItem *)sourceItem;

    Swift

    func cancelDownload(for sourceItem: SourceItem)

    Parameters

    sourceItem

    A BMPSourceItem instance for which all associated running download tasks should be cancelled.

  • Suspends all running download tasks associated with the given BMPSourceItem. Calling this method is only valid when offlineStateForSourceItem: for the same BMPSourceItem instance returns BMPOfflineStateDownloading. The download can be resumed by calling resumeDownloadForSourceItem:. Not data is deleted when calling this method.

    Declaration

    Objective-C

    - (void)suspendDownloadForSourceItem:(nonnull BMPSourceItem *)sourceItem;

    Swift

    func suspendDownload(for sourceItem: SourceItem)

    Parameters

    sourceItem

    A BMPSourceItem instance for which all associated running download tasks should be suspended.

  • Resumes all suspended download tasks associated with the given BMPSourceItem. Calling this method is only valid when offlineStateForSourceItem: for the same BMPSourceItem instance returns BMPOfflineStateSuspended.

    Declaration

    Objective-C

    - (void)resumeDownloadForSourceItem:(nonnull BMPSourceItem *)sourceItem;

    Swift

    func resumeDownload(for sourceItem: SourceItem)

    Parameters

    sourceItem

    A BMPSourceItem instance for which all associated suspended download tasks should be resumed.

  • Updates the stored DRM license information (e.g. expiration dates) by querying the KSM. The device needs to be online for this. The FairPlayConfiguration#prepareOfflineDrmLicenseInformation block is called after the KSM was queried successfully.

    Declaration

    Objective-C

    - (void)syncOfflineDrmLicenseInformationForSourceItem:
    (nonnull BMPSourceItem *)sourceItem;

    Swift

    func syncOfflineDrmLicenseInformation(for sourceItem: SourceItem)

  • Returns information about the offline DRM license for a given SourceItem, e.g. the remaining license duration. The device does not need to be online for this.

    Declaration

    Objective-C

    - (nonnull BMPDrmLicenseInformation *)offlineDrmLicenseInformationForSourceItem:
    (nonnull BMPSourceItem *)sourceItem;

    Swift

    func offlineDrmLicenseInformation(for sourceItem: SourceItem) -> DrmLicenseInformation

    Parameters

    sourceItem

    A BMPSourceItem instance for which the DRM license information should be returned.

  • Renews the already downloaded DRM license for a given SourceItem. When successfully finished, BMPOfflineManagerListener’s offlineManagerDidRenewOfflineLicense: method is called. In case the license renewal fails an according error is passed via the listener’s offlineManager:didFailWithError: method.

    NOTE: The EXT-X-SESSION-KEY has to be present in the master playlist for this to work properly.

    Declaration

    Objective-C

    - (void)renewOfflineLicenseForSourceItem:(nonnull BMPSourceItem *)sourceItem;

    Swift

    func renewOfflineLicense(for sourceItem: SourceItem)

    Parameters

    sourceItem

    A BMPSourceItem instance for which the DRM license should be renewed.

  • Creates and returns a BMPOfflineSourceItem which should be used with a BMPBitmovinPlayer instance when playback of offline content is desired.

    Note: When intending to create an OfflineSourceItem for DRM protected content, the according DRMConfiguration needs to be applied to the passed sourceItem before creating the OfflineSourceItem.

    Declaration

    Objective-C

    - (nullable BMPOfflineSourceItem *)
    createOfflineSourceItemForSourceItem:(nonnull BMPSourceItem *)sourceItem
                  restrictedToAssetCache:(BOOL)restrictedToAssetCache;

    Swift

    func createOfflineSourceItem(for sourceItem: SourceItem, restrictedToAssetCache: Bool) -> OfflineSourceItem?

    Parameters

    sourceItem

    A BMPSourceItem instance for which a new BMPOfflineSourceItem instance should be created
    restrictedToAssetCache

    Whether or not the player should restrict playback only to audio, video and subtitle tracks which are stored offline on the device. This has to be set to YES if the device has no network access.

    Return Value

    A BMPOfflineSourceItem which can be used with a BMPBitmovinPlayer instance for offline playback.

  • Adds a listener to the BMPOfflineManager.

    Declaration

    Objective-C

    - (void)addListener:(nonnull id<BMPOfflineManagerListener>)listener
      forSourceItem:(nonnull BMPSourceItem *)sourceItem;

    Swift

    func add(listener: OfflineManagerListener, for sourceItem: SourceItem)

    Parameters

    listener

    The listener to add.
    sourceItem

    The BMPSourceItem instance for which the listener should be added.

  • Removes a listener from the BMPOfflineManager.

    Declaration

    Objective-C

    - (void)removeListener:(nonnull id<BMPOfflineManagerListener>)listener
         forSourceItem:(nonnull BMPSourceItem *)sourceItem;

    Swift

    func remove(listener: OfflineManagerListener, for sourceItem: SourceItem)

    Parameters

    listener

    The listener to remove.
    sourceItem

    The BMPSourceItem instance for which the listener should be removed.

  • Should be called from your AppDelegate when application(application:handleEventsForBackgroundURLSession:completionHandler:) is called by the system.

    Declaration

    Objective-C

    - (void)addCompletionHandler:(nonnull void (^)(void))completionHandler
               forIdentifier:(nonnull NSString *)identifier;

    Swift

    func add(completionHandler: @escaping () -> Void, for identifier: String)

    Parameters

    completionHandler

    The completion handler which is provided by the system.
    identifier

    The identifier which is provided by the system.

  • Can be used to determine if the BMPSourceItem is playable without a network connection.

    Declaration

    Objective-C

    - (BOOL)isSourceItemPlayableOffline:(nonnull BMPSourceItem *)sourceItem;

    Swift

    func isPlayableOffline(sourceItem: SourceItem) -> Bool

    Parameters

    sourceItem

    A BMPSourceItem instance for which the state should be determined.

    Return Value

    YES, if the BMPSourceItem instance is playable without a network connection, NO otherwise.

  • Returns how many bytes of storage are used by the offline content.

    Declaration

    Objective-C

    - (long)usedStorageForSourceItem:(nonnull BMPSourceItem *)sourceItem;

    Swift

    func usedStorage(for sourceItem: SourceItem) -> Int

    Parameters

    sourceItem

    A BMPSourceItem instance for which the storage size in bytes should be calculated.

    Return Value

    How many bytes of storage are used by the offline content.