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 OfflineManagerListener 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 }

  • 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 OfflineConfig. If the shared instance is already initialized, this method will not have any effect.

    Declaration

    Objective-C

    + (void)initializeOfflineManagerWithOfflineConfig:
    (nonnull BMPOfflineConfig *)offlineConfig;

    Swift

    class func initializeOfflineManager(offlineConfig: BMPOfflineConfig)

    Parameters

    offlineConfig

  • Returns an OfflineContentManager instance which can be used to manage offline content and offline DRM related tasks for the provided SourceConfig.

    The instance returned by this method will always be the same for the same SourceConfig.

    This method will throw an error (or return nil in ObjC) in case a SourceConfig is passed that is not supported for being downloaded. A SourceConfig is only valid for download when it’s configured using an HLS asset.

    Declaration

    Objective-C

    - (nullable id<BMPOfflineContentManager>)
    offlineContentManagerForSourceConfig:(nonnull BMPSourceConfig *)sourceConfig
                                   error:(NSError *_Nullable *_Nullable)error;

    Parameters

    sourceConfig

    A SourceConfig for which the OfflineContentManger is requested.

    Return Value

    OfflineContentManager instance for the provided SourceConfig @throws an error if the provided SourceConfig is not supported.

  • Returns an OfflineContentManager instance which can be used to manage offline content and offline DRM related tasks for the provided SourceConfig.

    The provided identifier will be used to create a folder containing needed resources for the offline content.

    The instance returned by this method will always be the same for the same identifier.

    This method will throw an error (or return nil in ObjC) in case a SourceConfig is passed that is not supported for being downloaded. A SourceConfig is only valid for download when it’s configured using an HLS asset.

    Warning

    If an OfflineContentManager is acquired using this method, subsequent calls to any content related API on the OfflineManager are not supported, meaning they could result in unexpected behaviour.

    Declaration

    Objective-C

    - (nullable id<BMPOfflineContentManager>)
    offlineContentManagerForSourceConfig:(nonnull BMPSourceConfig *)sourceConfig
                              identifier:(nonnull NSString *)identifier
                                   error:(NSError *_Nullable *_Nullable)error;

    Parameters

    sourceConfig

    A SourceConfig for which the OfflineContentManger is requested.
    identifier

    A unique identifier for the given SourceConfig which must not change once provided.

    Return Value

    OfflineContentManager instance for the provided SourceConfig @throws an error if the provided SourceConfig is not supported.

  • Deprecated

    Use OfflineContentManager.offlineState instead

    Returns the offline state for the given BMPSourceConfig.

    Declaration

    Objective-C

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

    Swift

    func offlineState(for sourceConfig: BMPSourceConfig) -> OfflineState

    Parameters

    sourceConfig

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

    Return Value

    The offline state for the given BMPSourceConfig.

  • Deprecated

    Use OfflineContentManager.deleteOfflineData() instead

    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: BMPSourceConfig)

    Parameters

    sourceConfig

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

  • Deprecated

    Use OfflineContentManager.fetchAvailableTracks() instead

    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: BMPSourceConfig)

    Parameters

    sourceConfig

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

  • Deprecated

    Use OfflineContentManager.download() instead

    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: BMPSourceConfig)

    Parameters

    sourceConfig

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

  • Deprecated

    Use OfflineContentManager.download(downloadConfig:) instead

    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: BMPSourceConfig, downloadConfig: DownloadConfig)

    Parameters

    sourceConfig

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

    The BMPDownloadConfig used for this download

  • Deprecated

    Use OfflineContentManager.download(tracks:downloadConfig:) instead

    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: BMPSourceConfig, tracks: BMPOfflineTrackSelection, 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

  • Deprecated

    Use OfflineContentManager.cancelDownload() instead

    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: BMPSourceConfig)

    Parameters

    sourceConfig

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

  • Deprecated

    Use OfflineContentManager.suspendDownload() instead

    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: BMPSourceConfig)

    Parameters

    sourceConfig

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

  • Deprecated

    Use OfflineContentManager.resumeDownload() instead

    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: BMPSourceConfig)

    Parameters

    sourceConfig

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

  • Deprecated

    Use OfflineContentManager.syncOfflineDrmLicenseInformation() instead

    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: BMPSourceConfig)

  • Deprecated

    Use OfflineContentManager.offlineDrmLicenseInformation instead

    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

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

    Swift

    func offlineDrmLicenseInformation(for sourceConfig: BMPSourceConfig) -> BMPDrmLicenseInformation?

    Parameters

    sourceConfig

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

  • Deprecated

    Use OfflineContentManager.renewOfflineLicense() instead

    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: BMPSourceConfig)

    Parameters

    sourceConfig

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

  • Deprecated

    Use OfflineContentManager.createOfflineSourceConfig() instead

    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: BMPSourceConfig, restrictedToAssetCache: Bool) -> BMPOfflineSourceConfig?

    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.

  • Deprecated

    Use OfflineContentManager.add(listener:) instead

    Adds a listener to the BMPOfflineManager.

    Declaration

    Objective-C

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

    Parameters

    listener

    The listener to add.
    sourceConfig

    The BMPSourceConfig instance for which the listener should be added.

  • Deprecated

    Use OfflineContentManager.remove(listener:) instead

    Removes a listener from the BMPOfflineManager.

    Declaration

    Objective-C

    - (void)removeListener:(nonnull id<BMPOfflineManagerListener>)listener
       forSourceConfig:(nonnull BMPSourceConfig *)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.

  • Deprecated

    Use OfflineContentManager.offlineState == .downloaded instead

    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: BMPSourceConfig) -> 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.

  • Deprecated

    Use OfflineContentManager.usedStorage instead

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

    This can be used to get the current storage for in-progress downloads.

    Declaration

    Objective-C

    - (long)usedStorageForSourceConfig:(nonnull BMPSourceConfig *)sourceConfig;

    Swift

    func usedStorage(for sourceConfig: BMPSourceConfig) -> 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.