Package com.castlabs.sdk.downloader

# Class DownloadServiceBinder

java.lang.Object
android.os.Binder
com.castlabs.sdk.downloader.DownloadServiceBinder

All Implemented Interfaces:
  `IBinder`

public class DownloadServiceBinder extends Binder
The binder providing access to `DownloadService`.

Bind to `DownloadService` as follows:

     DownloadServiceBinder downloadServiceBinder;
     ServiceConnection downloadServiceConnection = new ServiceConnection() {
            public void onServiceConnected(ComponentName componentName, IBinder iBinder) {
                    downloadServiceBinder = (DownloadServiceBinder) iBinder;
            }
            public void onServiceDisconnected(ComponentName componentName) {
                    downloadServiceBinder = null;
            }
     }

     String downloadId = "ID";
     File moviesFolder = getExternalFilesDir(Environment.DIRECTORY_MOVIES);
     File target = new File(moviesFolder, "Downloads/" + downloadId);

     Bundle bundle = new Bundle();
     bundle.putString(SdkConsts.INTENT_URL, "MANIFEST_URL");
     bundle.putString(SdkConsts.INTENT_DOWNLOAD_ID, downloadId);
     bundle.putString(SdkConsts.INTENT_DOWNLOAD_FOLDER, target.getAbsolutePath());

     downloadServiceBinder.prepareDownload(context, bundle, new Downloader.ModelReadyCallback() {
            public void onError(@NonNull Exception e) {
                    Log.e(TAG, "Error while preparing download: " + e.getMessage(), e);
            }
            public void onModelAvailable(@NonNull Download download) {
                    // initiate selection here of video quality, audio and subtitle tracks
                    // either automatically or manually
            }
     });

Since:
  3.2.0

- ## Nested Class Summary

  ## Nested classes/interfaces inherited from interface android.os.IBinder

  `IBinder.DeathRecipient`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static boolean`
  `allowNonScopedStorageDownload`
  This flag indicates whether to allow `downloads` to be downloaded into system paths which are not part of the scoped storage.
  `static boolean`
  `autoStopService`
  This flag indicates whether to stop the `Service` once there are no pending `downloads`.

  ### Fields inherited from interface android.os.IBinder

  `DUMP_TRANSACTION, FIRST_CALL_TRANSACTION, FLAG_ONEWAY, INTERFACE_TRANSACTION, LAST_CALL_TRANSACTION, LIKE_TRANSACTION, PING_TRANSACTION, TWEET_TRANSACTION`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `createDownload(Download download, boolean startDownload)`
  Stores the download internally and if the startDownload is set then adds the download into the download queue.
  `void`
  `deleteDownload(String downloadId)`
  Deletes download identified by download Id.
  `static void`
  `fetchLicense(Download download, DrmConfiguration drmConfiguration, DrmLicenseLoader.Callback callback)`
  Fetches the appropriate license for the given Download.
  `Download`
  `findDownloadById(String downloadId)`
  Finds download by download Id
  `List<Download>`
  `getDownloads()`
  Returns a list of all downloads that are currently available in the storage
  `void`
  `pauseDownload(String downloadId)`
  Pauses download identified by download Id.
  `void`
  `prepareDownload(Context context, Bundle bundle, Downloader.ModelReadyCallback callback)`
  Creates the download model by downloading and parsing the manifest.
  `static void`
  `removeLicense(Download download, DrmConfiguration drmConfiguration, DrmLicenseLoader.Callback callback)`
  Removes the appropriate license for the given Download.
  `void`
  `resumeDownload(String downloadId)`
  Resumes download identified by download Id.
  `void`
  `resumeQueuedDownloads()`
  Starts the downloader service and resumes downloading queued downloads.
  `void`
  `stopService()`
  Stops the `DownloadService` if it's running.
  `void`
  `updateDownloadPath(String downloadId, String newPath)`
  Updates the internal download path.

  ### Methods inherited from class android.os.Binder

  `attachInterface, clearCallingIdentity, clearCallingWorkSource, dump, dumpAsync, flushPendingCommands, getCallingPid, getCallingUid, getCallingUidOrThrow, getCallingUserHandle, getCallingWorkSourceUid, getInterfaceDescriptor, isBinderAlive, joinThreadPool, linkToDeath, pingBinder, queryLocalInterface, restoreCallingIdentity, restoreCallingWorkSource, setCallingWorkSourceUid, transact, unlinkToDeath`

  ### Methods inherited from class java.lang.Object

  `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Field Details

  - ### allowNonScopedStorageDownload

    public static boolean allowNonScopedStorageDownload
    This flag indicates whether to allow `downloads` to be downloaded into system paths which are not part of the scoped storage. This flag is false by default.

  - ### autoStopService

    public static boolean autoStopService
    This flag indicates whether to stop the `Service` once there are no pending `downloads`. You may want to disable this flag in case your workflow contemplates starting or resuming Downloads whenever the app is in background, or whenever the App is in a state which is not allowed by the system to `promote the service to foreground`. If disabled, you must take responsibility for stopping the service once it's not needed by your Application anymore. The recommended approach is to listen for the `MessageHandler.ACTION_DOWNLOAD_NO_PENDING` broadcast event. See `stopService()`. true by default.

- ## Method Details

  - ### getDownloads

    @NonNull public List<Download> getDownloads() throws IOException
    Returns a list of all downloads that are currently available in the storage
    Returns:
      The list of all available downloads
    Throws:
      `IOException` - In case an error occurs while reading the download list

  - ### findDownloadById

    @Nullable public Download findDownloadById(@NonNull String downloadId)
    Finds download by download Id
    Parameters:
      `downloadId` - The download Id
    Returns:
      The found download or null otherwise

  - ### deleteDownload

    public void deleteDownload(@NonNull String downloadId)
    Deletes download identified by download Id. This is the asynchronous call and after the download is successfully deleted the `MessageHandler.ACTION_DOWNLOAD_DELETED` is sent or `MessageHandler.ACTION_DOWNLOAD_ERROR` in case of error. In case the download is currently loading then it is deleted and the next scheduled download is started.
    Parameters:
      `downloadId` - The download Id

  - ### updateDownloadPath

    public void updateDownloadPath(@NonNull String downloadId, @NonNull String newPath)
    Updates the internal download path. Note that data migration (Media content) is *NOT* moved by this method. It *won't* migrate the contents of the Download to the specified path. This is to be called after data migration is performed manually. For more information check out the "Scoped Storage" section inside the Downloader in the SDK manual.
    Parameters:
      `downloadId` - The Download Id
      `newPath` - The new path

  - ### fetchLicense

    public static void fetchLicense(@NonNull Download download, @Nullable DrmConfiguration drmConfiguration, @NonNull DrmLicenseLoader.Callback callback)
    Fetches the appropriate license for the given Download. Note that this a static method, since it's just a convenience method and does not require an active `DownloadService`.
    Parameters:
      `download` - the Download for which to fetch the license.
      `drmConfiguration` - `DrmConfiguration` used to fetch the license. If null, the Download's configuration will be used instead
      `callback` - Callback to be invoked when the license is retrieved or an error occurs

  - ### removeLicense

    public static void removeLicense(@NonNull Download download, @Nullable DrmConfiguration drmConfiguration, @NonNull DrmLicenseLoader.Callback callback)
    Removes the appropriate license for the given Download. Note that this a static method, since it's just a convenience method and does not require an active `DownloadService`.
    Parameters:
      `download` - the Download for which to remove the license.
      `drmConfiguration` - `DrmConfiguration` used to remove the license. If null, the Download's configuration will be used instead
      `callback` - Callback to be invoked when the license is removed or an error occurs

  - ### resumeDownload

    public void resumeDownload(@NonNull String downloadId)
    Resumes download identified by download Id. This is the asynchronous call and after the download is successfully resumed the `MessageHandler.ACTION_DOWNLOAD_STARTED` is broadcasted or `MessageHandler.ACTION_DOWNLOAD_ERROR` in case of error. In case the device storage is low, the download is not resumed and the `MessageHandler.ACTION_DOWNLOAD_STORAGE_LOW` is broadcasted
    Parameters:
      `downloadId` - The download Id

  - ### pauseDownload

    public void pauseDownload(@NonNull String downloadId)
    Pauses download identified by download Id. This is the asynchronous call and after the download is successfully paused the `MessageHandler.ACTION_DOWNLOAD_STOPPED` is broadcasted or `MessageHandler.ACTION_DOWNLOAD_ERROR` in case of error. In case the device storage is enough the next scheduled download is started.
    Parameters:
      `downloadId` - The download Id

  - ### createDownload

    public void createDownload(@NonNull Download download, boolean startDownload) throws IOException
    Stores the download internally and if the startDownload is set then adds the download into the download queue. This is the asynchronous call and after the download is stored, the `MessageHandler.ACTION_DOWNLOAD_CREATED` is broadcasted. If the startDownload is set then after successful adding of the download into the download queue the `MessageHandler.ACTION_DOWNLOAD_STARTED` is sent or `MessageHandler.ACTION_DOWNLOAD_ERROR` in case of error. In case the device storage is low, the `MessageHandler.ACTION_DOWNLOAD_STORAGE_LOW` is broadcasted instead.
    Parameters:
      `download` - The download
      `startDownload` - The flag whether to start the download upon creation.
    Throws:
      `IOException` - In case an error occurs while reading the download list

  - ### resumeQueuedDownloads

    public void resumeQueuedDownloads()
    Starts the downloader service and resumes downloading queued downloads. Use this method primarily when you use the `DownloaderPlugin.STORAGE_LOW_MODE_QUEUED` storage mode and you want to restart pending downloads.

  - ### prepareDownload

    public void prepareDownload(@NonNull Context context, @NonNull Bundle bundle, @Nullable Downloader.ModelReadyCallback callback)
    Creates the download model by downloading and parsing the manifest. The caller callback is invoked upon completion. This method takes a `Bundle` and extracts the information needed for the download model. The following bundle keys will be checked:
    - `SdkConsts.INTENT_URL` expects a String (mandatory)
    - `SdkConsts.INTENT_DOWNLOAD_ID` expects a String (mandatory)
    - `SdkConsts.INTENT_DOWNLOAD_FOLDER` expects a String (mandatory)
    - `SdkConsts.INTENT_DRM_CONFIGURATION` expects a `DrmConfiguration` (optional)
    - `SdkConsts.INTENT_CONTENT_TYPE` expects a `Integer` (default: `SdkConsts.CONTENT_TYPE_UNKNOWN` to auto-detect). Allowed values are one of `SdkConsts.CONTENT_TYPE_UNKNOWN`, `SdkConsts.CONTENT_TYPE_DASH`, `SdkConsts.CONTENT_TYPE_SMOOTHSTREAMING`, or `SdkConsts.CONTENT_TYPE_MP4`
  - `SdkConsts.INTENT_HD_CONTENT_FILTER`
  - `SdkConsts.INTENT_VIDEO_SIZE_FILTER`
  - `SdkConsts.INTENT_VIDEO_CODEC_FILTER`
  - `SdkConsts.INTENT_MERGE_VIDEO_TRACKS`

Parameters:
  `context` - The context
  `bundle` - The bundle
  `callback` - The caller callback or null

- ### stopService

  public void stopService()
  Stops the `DownloadService` if it's running. Also pauses any ongoing Downloads. There's usually no need to call this method, unless you're setting `autoStopService` to false.