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

    All Methods Static Methods Instance Methods Concrete Methods
    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 Detail

    - #### 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 Detail

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