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 SourceConfig, which can be obtained by calling offlineStateForSourceConfig:, 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 downloadSourceConfig: - Downloading
Downloading cancelDownloadForSourceConfig: - Canceling
Downloading suspendDownloadForSourceConfig: offlineManagerDidSuspendDownload: Suspended
Downloading - offlineManagerDidFinishDownload: Downloaded
Downloading - offlineManager:didProgressTo: Downloading
Downloaded deleteOfflineDataForSourceConfig: - NotDownloaded
Suspended resumeDownloadForSourceConfig: offlineManager:didResumeDownloadWithProgress: Downloading
Suspended cancelDownloadForSourceConfig: - Canceling
Canceling - offlineManagerDidCancelDownload: NotDownloaded
Downloaded renewOfflineLicenseForSourceConfig: 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 }

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

    Declaration

    Objective-C

    + (void)initializeOfflineManager;

    Swift

    class func initializeOfflineManager()

  • Returns the offline state for the given BMPSourceConfig.

    Declaration

    Objective-C

    - (BMPOfflineState)offlineStateForSourceConfig:
    (nonnull BMPSourceConfig *)sourceConfig;

    Swift

    func offlineState(for sourceConfig: SourceConfig) -> OfflineState

    Parameters

    sourceConfig

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

    Return Value

    The offline state for the given BMPSourceConfig.

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

    Declaration

    Objective-C

    - (void)deleteOfflineDataForSourceConfig:
    (nonnull BMPSourceConfig *)sourceConfig;

    Swift

    func deleteOfflineData(for sourceConfig: SourceConfig)

    Parameters

    sourceConfig

    A BMPSourceConfig 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)fetchAvailableTracksForSourceConfig:
    (nonnull BMPSourceConfig *)sourceConfig;

    Swift

    func fetchAvailableTracks(for sourceConfig: SourceConfig)

    Parameters

    sourceConfig

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

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

    Calling this method is only valid when offlineStateForSourceConfig: for the same BMPSourceConfig instance returns BMPOfflineStateNotDownloaded.

    Declaration

    Objective-C

    - (void)downloadSourceConfig:(nonnull BMPSourceConfig *)sourceConfig;

    Swift

    func download(sourceConfig: SourceConfig)

    Parameters

    sourceConfig

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

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

    Declaration

    Objective-C

    - (void)downloadSourceConfig:(nonnull BMPSourceConfig *)sourceConfig
              downloadConfig:(nonnull BMPDownloadConfig *)downloadConfig;

    Swift

    func download(sourceConfig: SourceConfig, downloadConfig: DownloadConfig)

    Parameters

    sourceConfig

    A BMPSourceConfig instance for which the media data should be downloaded.
    downloadConfig

    The BMPDownloadConfig used for this download

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

    Declaration

    Objective-C

    - (void)downloadSourceConfig:(nonnull BMPSourceConfig *)sourceConfig
                      tracks:(nonnull BMPOfflineTrackSelection *)tracks
              downloadConfig:(nonnull BMPDownloadConfig *)downloadConfig;

    Swift

    func download(sourceConfig: SourceConfig, tracks: OfflineTrackSelection, downloadConfig: DownloadConfig)

    Parameters

    sourceConfig

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

    a BMPOfflineTrackSelection specifying which tracks to download
    downloadConfig

    The BMPDownloadConfig used for this download

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

    Declaration

    Objective-C

    - (void)cancelDownloadForSourceConfig:(nonnull BMPSourceConfig *)sourceConfig;

    Swift

    func cancelDownload(for sourceConfig: SourceConfig)

    Parameters

    sourceConfig

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

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

    Declaration

    Objective-C

    - (void)suspendDownloadForSourceConfig:(nonnull BMPSourceConfig *)sourceConfig;

    Swift

    func suspendDownload(for sourceConfig: SourceConfig)

    Parameters

    sourceConfig

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

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

    Declaration

    Objective-C

    - (void)resumeDownloadForSourceConfig:(nonnull BMPSourceConfig *)sourceConfig;

    Swift

    func resumeDownload(for sourceConfig: SourceConfig)

    Parameters

    sourceConfig

    A BMPSourceConfig 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 FairPlayConfig#prepareOfflineDrmLicenseInformation block is called after the KSM was queried successfully.

    Declaration

    Objective-C

    - (void)syncOfflineDrmLicenseInformationForSourceConfig:
    (nonnull BMPSourceConfig *)sourceConfig;

    Swift

    func syncOfflineDrmLicenseInformation(for sourceConfig: SourceConfig)

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

    Declaration

    Objective-C

    - (nonnull BMPDrmLicenseInformation *)
    offlineDrmLicenseInformationForSourceConfig:
        (nonnull BMPSourceConfig *)sourceConfig;

    Swift

    func offlineDrmLicenseInformation(for sourceConfig: SourceConfig) -> DrmLicenseInformation

    Parameters

    sourceConfig

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

  • Renews the already downloaded DRM license for a given SourceConfig. 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)renewOfflineLicenseForSourceConfig:
    (nonnull BMPSourceConfig *)sourceConfig;

    Swift

    func renewOfflineLicense(for sourceConfig: SourceConfig)

    Parameters

    sourceConfig

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

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

    Note: When intending to create an OfflineSourceConfig for DRM protected content, the according DRMConfig needs to be applied to the passed sourceConfig before creating the OfflineSourceConfig.

    Declaration

    Objective-C

    - (nullable BMPOfflineSourceConfig *)
    createOfflineSourceConfigForSourceConfig:
        (nonnull BMPSourceConfig *)sourceConfig
                      restrictedToAssetCache:(BOOL)restrictedToAssetCache;

    Swift

    func createOfflineSourceConfig(for sourceConfig: SourceConfig, restrictedToAssetCache: Bool) -> OfflineSourceConfig?

    Parameters

    sourceConfig

    A BMPSourceConfig instance for which a new BMPOfflineSourceConfig 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 BMPOfflineSourceConfig which can be used with a BMPPlayer instance for offline playback.

  • Adds a listener to the BMPOfflineManager.

    Declaration

    Objective-C

    - (void)addListener:(nonnull id<BMPOfflineManagerListener>)listener
    forSourceConfig:(nonnull BMPSourceConfig *)sourceConfig;

    Swift

    func add(listener: OfflineManagerListener, for sourceConfig: SourceConfig)

    Parameters

    listener

    The listener to add.
    sourceConfig

    The BMPSourceConfig instance for which the listener should be added.

  • Removes a listener from the BMPOfflineManager.

    Declaration

    Objective-C

    - (void)removeListener:(nonnull id<BMPOfflineManagerListener>)listener
       forSourceConfig:(nonnull BMPSourceConfig *)sourceConfig;

    Swift

    func remove(listener: OfflineManagerListener, for sourceConfig: SourceConfig)

    Parameters

    listener

    The listener to remove.
    sourceConfig

    The BMPSourceConfig 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 BMPSourceConfig is playable without a network connection.

    Declaration

    Objective-C

    - (BOOL)isSourceConfigPlayableOffline:(nonnull BMPSourceConfig *)sourceConfig;

    Swift

    func isPlayableOffline(sourceConfig: SourceConfig) -> Bool

    Parameters

    sourceConfig

    A BMPSourceConfig instance for which the state should be determined.

    Return Value

    YES, if the BMPSourceConfig 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)usedStorageForSourceConfig:(nonnull BMPSourceConfig *)sourceConfig;

    Swift

    func usedStorage(for sourceConfig: SourceConfig) -> Int

    Parameters

    sourceConfig

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

    Return Value

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