Package com.castlabs.sdk.downloader

# Class MessageHandler

java.lang.Object
com.castlabs.sdk.downloader.MessageHandler

All Implemented Interfaces:
  `Handler.Callback`

public class MessageHandler extends Object implements Handler.Callback
The download message handler broadcasts downloader related messages:

- `ACTION_DOWNLOAD_STOPPED`
- `ACTION_DOWNLOAD_CREATED`
- `ACTION_DOWNLOAD_STARTED`
- `ACTION_DOWNLOAD_DELETED`
- `ACTION_DOWNLOAD_COMPLETED`
- `ACTION_DOWNLOAD_NO_PENDING`
- `ACTION_DOWNLOAD_ERROR`
- `ACTION_DOWNLOAD_STORAGE_LOW`
- `ACTION_DOWNLOAD_STORAGE_OK`

- `ACTION_DOWNLOAD_PROGRESS`
- `ACTION_DOWNLOAD_PATH_UPDATE`
The following sample shows how to subscribe and receive the downloader messages:

     IntentFilter filter = new IntentFilter();
     filter.addCategory(MessageHandler.INTENT_DOWNLOAD_CATEGORY);
     filter.addAction(MessageHandler.ACTION_DOWNLOAD_ERROR);
     filter.addAction(MessageHandler.ACTION_DOWNLOAD_STOPPED);
     filter.addAction(MessageHandler.ACTION_DOWNLOAD_CREATED);
     filter.addAction(MessageHandler.ACTION_DOWNLOAD_STARTED);
     filter.addAction(MessageHandler.ACTION_DOWNLOAD_DELETED);
     filter.addAction(MessageHandler.ACTION_DOWNLOAD_COMPLETED);
     filter.addAction(MessageHandler.ACTION_DOWNLOAD_NO_PENDING);
     filter.addAction(MessageHandler.ACTION_DOWNLOAD_STORAGE_OK);
     filter.addAction(MessageHandler.ACTION_DOWNLOAD_STORAGE_LOW);
     filter.addAction(MessageHandler.ACTION_DOWNLOAD_PROGRESS);
     filter.addAction(MessageHandler.ACTION_DOWNLOAD_PATH_UPDATE);

     LocalBroadcastManager.getInstance(context).registerReceiver(new BroadcastReceiver{
            public void onReceive(Context context, Intent intent) {
                    String downloadId = intent.getStringExtra(MessageHandler.INTENT_DOWNLOAD_ID);
                    Log.d(TAG, "Message: " + intent.getAction() + ", download Id: " + downloadId);
                    switch (intent.getAction()) {
                            case MessageHandler.ACTION_DOWNLOAD_STOPPED:
                                    break;
                            case MessageHandler.ACTION_DOWNLOAD_CREATED:
                                    break;
                            case MessageHandler.ACTION_DOWNLOAD_STARTED:
                                    break;
                            case MessageHandler.ACTION_DOWNLOAD_DELETED:
                                    break;
                            case MessageHandler.ACTION_DOWNLOAD_COMPLETED:
                                    break;
                            case MessageHandler.ACTION_DOWNLOAD_NO_PENDING:
                                    break;
                            case MessageHandler.ACTION_DOWNLOAD_ERROR:
                                    break;
                            case MessageHandler.ACTION_DOWNLOAD_STORAGE_LOW:
                                    break;
                            case MessageHandler.ACTION_DOWNLOAD_STORAGE_OK:
                                    break;
                            case MessageHandler.ACTION_DOWNLOAD_PROGRESS:
                                    break;
                            case MessageHandler.ACTION_DOWNLOAD_PATH_UPDATE:
                                    break;
                            default:
                                    break;
                    }
            }
     }, filter);

## Error handling

The intent bundle that is send with broadcast messages always contains the `INTENT_DOWNLOAD_ID` parameter, which is the download ID `String`. In addition, all `ACTION_DOWNLOAD_ERROR` messages contain the `INTENT_DOWNLOAD_ERROR` `String`, which is a string representation that contains the message from the exception that occurred during the download. Because all intent parameters need to be parcelable, we can unfortunately not embed the original Exception.

Since version 4.1.5, error message also contain additional data. `INTENT_DOWNLOAD_ERROR_TYPE` contains the error type, which is one of the `ERROR_*` constants of this class. Some of the error types might contains additional information. You can check for the http status code under the `INTENT_DOWNLOAD_ERROR_HTTP_STATUS` key. The URL that caused the error can be checked with `INTENT_DOWNLOAD_ERROR_HTTP_URL`. Both of these values are optional and we might not be able to report them for all errors.

General connectivity issues are reported as `ERROR_TYPE_CONNECTION_ERROR` when the underlying socket connection is interrupted. That can happen for instance when the device looses its connectivity.

DRM errors are reported as `ERROR_TYPE_DRM_ERROR` if there was a problem while fetching the offline license. The underlying DRM error code can be queried through the `INTENT_DOWNLOAD_ERROR_DRM` key, which will contain one of the values defined in the constants starting with `ERROR_*` in `DrmTodayException`.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `ACTION_DOWNLOAD_COMPLETED`
  Use this as action in `IntentFilter.addAction(String)` to receive messages that a download has been completed
  `static final String`
  `ACTION_DOWNLOAD_CREATED`
  Use this as action in `IntentFilter.addAction(String)` to receive messages that a download has been created
  `static final String`
  `ACTION_DOWNLOAD_DELETED`
  Use this as action in `IntentFilter.addAction(String)` to receive messages that a download has been deleted
  `static final String`
  `ACTION_DOWNLOAD_ERROR`
  Use this as action in `IntentFilter.addAction(String)` to receive messages that a download error occurred
  `static final String`
  `ACTION_DOWNLOAD_NO_PENDING`
  Use this as action in `IntentFilter.addAction(String)` to receive messages that the download queue has no started downloads
  `static final String`
  `ACTION_DOWNLOAD_PATH_UPDATE`
  Use this as action in `IntentFilter.addAction(String)` to receive messages that the path for a download has been updated, or failed to.
  `static final String`
  `ACTION_DOWNLOAD_PROGRESS`
  Use this as action in `IntentFilter.addAction(String)` to receive messages that progress was made on the current download
  `static final String`
  `ACTION_DOWNLOAD_SERVICE_TIMEOUT`
  Use this as action in `IntentFilter.addAction(String)` to receive messages that the download service timed out.
  `static final String`
  `ACTION_DOWNLOAD_STARTED`
  Use this as action in `IntentFilter.addAction(String)` to receive messages that a download has been started
  `static final String`
  `ACTION_DOWNLOAD_STOPPED`
  Use this as action in `IntentFilter.addAction(String)` to receive messages that a download has been stopped
  `static final String`
  `ACTION_DOWNLOAD_STORAGE_LOW`
  Use this as action in `IntentFilter.addAction(String)` to receive messages that the storage is insufficient to continue with downloads If this action is fired all ongoing Downloads (with states `Download.STATE_LOADING` or `Download.STATE_QUEUED`) will be automatically paused.
  `static final String`
  `ACTION_DOWNLOAD_STORAGE_OK`
  Use this as action in `IntentFilter.addAction(String)` to receive messages that the device storage is sufficient to continue with downloads
  `static final int`
  `DOWNLOAD_UPDATE_PATH_RESULT_ERROR_DOWNLOAD_INVALID_STATE`
  The download path could not be updated due to the Download being in an invalid state.
  `static final int`
  `DOWNLOAD_UPDATE_PATH_RESULT_ERROR_DOWNLOAD_NOT_FOUND`
  The download path could not be updated due to that the Download could not be found.
  `static final int`
  `DOWNLOAD_UPDATE_PATH_RESULT_ERROR_DOWNLOAD_UNKNOWN`
  The download path could not be updated due to an unknown error.
  `static final int`
  `DOWNLOAD_UPDATE_PATH_RESULT_SUCCESS`
  The download path has been successfully updated.
  `static final int`
  `ERROR_TYPE_CONNECTION_ERROR`
  Error type that indicates a connectivity issue on the client device
  `static final int`
  `ERROR_TYPE_DRM_ERROR`
  Error type that indicates a DRM license fetching error.
  `static final int`
  `ERROR_TYPE_HTTP_ERROR`
  Error type for HTTP related download error.
  `static final int`
  `ERROR_TYPE_UNKNOWN_ERROR`
  Generic error type for errors that could not be identified more specifically
  `static final String`
  `INTENT_DOWNLOAD_CATEGORY`
  Use this as category in `IntentFilter.addCategory(java.lang.String)` for filtering out the broadcasted downloader messages
  `static final String`
  `INTENT_DOWNLOAD_ERROR`
  Use this as `Intent` key to indicate the download error
  `static final String`
  `INTENT_DOWNLOAD_ERROR_DRM`
  Use this as `Intent` key to find the DRM error.
  `static final String`
  `INTENT_DOWNLOAD_ERROR_HTTP_STATUS`
  Use this as `Intent` key to find the http status error for errors of type `ERROR_TYPE_HTTP_ERROR`.
  `static final String`
  `INTENT_DOWNLOAD_ERROR_HTTP_URL`
  Use this as `Intent` key to find the URL that caused the error for errors of type `ERROR_TYPE_HTTP_ERROR`.
  `static final String`
  `INTENT_DOWNLOAD_ERROR_TYPE`
  Use this as `Intent` key to find the error type.
  `static final String`
  `INTENT_DOWNLOAD_ID`
  Use this as `Intent` key to indicate the download Id
  `static final String`
  `INTENT_DOWNLOAD_PATH_UPDATE_ERROR`
  Use this as `Intent` key to find the `Exception` in case there's been an error while updating the download path.
  `static final String`
  `INTENT_DOWNLOAD_PATH_UPDATE_RESULT`
  Use this as `Intent` key to find the result of the Download Path Update.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `handleMessage(Message msg)`

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

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

- ## Field Details

  - ### ERROR_TYPE_UNKNOWN_ERROR

    public static final int ERROR_TYPE_UNKNOWN_ERROR
    Generic error type for errors that could not be identified more specifically
    See Also:
      - Constant Field Values

  - ### ERROR_TYPE_HTTP_ERROR

    public static final int ERROR_TYPE_HTTP_ERROR
    Error type for HTTP related download error. Errors for this type typically also carry the response status code
    See Also:
      - Constant Field Values

  - ### ERROR_TYPE_CONNECTION_ERROR

    public static final int ERROR_TYPE_CONNECTION_ERROR
    Error type that indicates a connectivity issue on the client device
    See Also:
      - Constant Field Values

  - ### ERROR_TYPE_DRM_ERROR

    public static final int ERROR_TYPE_DRM_ERROR
    Error type that indicates a DRM license fetching error. The DRM error can be accessed through the `INTENT_DOWNLOAD_ERROR_DRM` key.
    See Also:
      - Constant Field Values

  - ### INTENT_DOWNLOAD_CATEGORY

    public static final String INTENT_DOWNLOAD_CATEGORY
    Use this as category in `IntentFilter.addCategory(java.lang.String)` for filtering out the broadcasted downloader messages
    See Also:
      - Constant Field Values

  - ### INTENT_DOWNLOAD_ID

    public static final String INTENT_DOWNLOAD_ID
    Use this as `Intent` key to indicate the download Id
    See Also:
      - Constant Field Values

  - ### INTENT_DOWNLOAD_ERROR

    public static final String INTENT_DOWNLOAD_ERROR
    Use this as `Intent` key to indicate the download error
    See Also:
      - Constant Field Values

  - ### INTENT_DOWNLOAD_ERROR_TYPE

    public static final String INTENT_DOWNLOAD_ERROR_TYPE
    Use this as `Intent` key to find the error type. The value is an `int` representing one of the `ERROR_*` constants in this class.
    See Also:
      - Constant Field Values

  - ### INTENT_DOWNLOAD_ERROR_HTTP_STATUS

    public static final String INTENT_DOWNLOAD_ERROR_HTTP_STATUS
    Use this as `Intent` key to find the http status error for errors of type `ERROR_TYPE_HTTP_ERROR`. The status code is reported as an `int`. If the status code could not be identified, it will be set to `-1`.
    See Also:
      - Constant Field Values

  - ### INTENT_DOWNLOAD_ERROR_HTTP_URL

    public static final String INTENT_DOWNLOAD_ERROR_HTTP_URL
    Use this as `Intent` key to find the URL that caused the error for errors of type `ERROR_TYPE_HTTP_ERROR`. The URL is reported as an `String`.
    See Also:
      - Constant Field Values

  - ### INTENT_DOWNLOAD_ERROR_DRM

    public static final String INTENT_DOWNLOAD_ERROR_DRM
    Use this as `Intent` key to find the DRM error. The value is an `int` representing one of the `ERROR_*` constants in `DrmTodayException`.
    See Also:
      - Constant Field Values

  - ### ACTION_DOWNLOAD_STOPPED

    public static final String ACTION_DOWNLOAD_STOPPED
    Use this as action in `IntentFilter.addAction(String)` to receive messages that a download has been stopped
    See Also:
      - Constant Field Values

  - ### ACTION_DOWNLOAD_CREATED

    public static final String ACTION_DOWNLOAD_CREATED
    Use this as action in `IntentFilter.addAction(String)` to receive messages that a download has been created
    See Also:
      - Constant Field Values

  - ### ACTION_DOWNLOAD_STARTED

    public static final String ACTION_DOWNLOAD_STARTED
    Use this as action in `IntentFilter.addAction(String)` to receive messages that a download has been started
    See Also:
      - Constant Field Values

  - ### ACTION_DOWNLOAD_DELETED

    public static final String ACTION_DOWNLOAD_DELETED
    Use this as action in `IntentFilter.addAction(String)` to receive messages that a download has been deleted
    See Also:
      - Constant Field Values

  - ### ACTION_DOWNLOAD_COMPLETED

    public static final String ACTION_DOWNLOAD_COMPLETED
    Use this as action in `IntentFilter.addAction(String)` to receive messages that a download has been completed
    See Also:
      - Constant Field Values

  - ### ACTION_DOWNLOAD_NO_PENDING

    public static final String ACTION_DOWNLOAD_NO_PENDING
    Use this as action in `IntentFilter.addAction(String)` to receive messages that the download queue has no started downloads
    See Also:
      - Constant Field Values

  - ### ACTION_DOWNLOAD_ERROR

    public static final String ACTION_DOWNLOAD_ERROR
    Use this as action in `IntentFilter.addAction(String)` to receive messages that a download error occurred
    See Also:
      - Constant Field Values

  - ### ACTION_DOWNLOAD_STORAGE_LOW

    public static final String ACTION_DOWNLOAD_STORAGE_LOW
    Use this as action in `IntentFilter.addAction(String)` to receive messages that the storage is insufficient to continue with downloads If this action is fired all ongoing Downloads (with states `Download.STATE_LOADING` or `Download.STATE_QUEUED`) will be automatically paused.
    See Also:
      - Constant Field Values

  - ### ACTION_DOWNLOAD_STORAGE_OK

    public static final String ACTION_DOWNLOAD_STORAGE_OK
    Use this as action in `IntentFilter.addAction(String)` to receive messages that the device storage is sufficient to continue with downloads
    See Also:
      - Constant Field Values

  - ### ACTION_DOWNLOAD_PROGRESS

    public static final String ACTION_DOWNLOAD_PROGRESS
    Use this as action in `IntentFilter.addAction(String)` to receive messages that progress was made on the current download
    See Also:
      - Constant Field Values

  - ### ACTION_DOWNLOAD_PATH_UPDATE

    public static final String ACTION_DOWNLOAD_PATH_UPDATE
    Use this as action in `IntentFilter.addAction(String)` to receive messages that the path for a download has been updated, or failed to.
    See Also:
      - Constant Field Values

  - ### ACTION_DOWNLOAD_SERVICE_TIMEOUT

    public static final String ACTION_DOWNLOAD_SERVICE_TIMEOUT
    Use this as action in `IntentFilter.addAction(String)` to receive messages that the download service timed out.

    When targeting Android 15 (API 35) and higher, the system imposes time limits for background services of type dataSync, which the DownloadService uses. If this limit is hit the service will automatically pause any ongoing downloads and immediately stop itself. It is then the responsibility of the application to resume any paused downloads when the app returns to the foreground.

    See Also:
      - Constant Field Values

  - ### INTENT_DOWNLOAD_PATH_UPDATE_RESULT

    public static final String INTENT_DOWNLOAD_PATH_UPDATE_RESULT
    Use this as `Intent` key to find the result of the Download Path Update. The value is an `int` representing one of the `DOWNLOAD_UPTADE_PATH_RESULT_*` constants in `MessageHandler`.
    See Also:
      - Constant Field Values

  - ### INTENT_DOWNLOAD_PATH_UPDATE_ERROR

    public static final String INTENT_DOWNLOAD_PATH_UPDATE_ERROR
    Use this as `Intent` key to find the `Exception` in case there's been an error while updating the download path. Will be null if the result is `DOWNLOAD_UPDATE_PATH_RESULT_SUCCESS`.
    See Also:
      - Constant Field Values

  - ### DOWNLOAD_UPDATE_PATH_RESULT_SUCCESS

    public static final int DOWNLOAD_UPDATE_PATH_RESULT_SUCCESS
    The download path has been successfully updated.
    See Also:
      - Constant Field Values

  - ### DOWNLOAD_UPDATE_PATH_RESULT_ERROR_DOWNLOAD_UNKNOWN

    public static final int DOWNLOAD_UPDATE_PATH_RESULT_ERROR_DOWNLOAD_UNKNOWN
    The download path could not be updated due to an unknown error.
    See Also:
      - Constant Field Values

  - ### DOWNLOAD_UPDATE_PATH_RESULT_ERROR_DOWNLOAD_NOT_FOUND

    public static final int DOWNLOAD_UPDATE_PATH_RESULT_ERROR_DOWNLOAD_NOT_FOUND
    The download path could not be updated due to that the Download could not be found.
    See Also:
      - Constant Field Values

  - ### DOWNLOAD_UPDATE_PATH_RESULT_ERROR_DOWNLOAD_INVALID_STATE

    public static final int DOWNLOAD_UPDATE_PATH_RESULT_ERROR_DOWNLOAD_INVALID_STATE
    The download path could not be updated due to the Download being in an invalid state.
    See Also:
      - Constant Field Values

- ## Method Details

  - ### handleMessage

    public boolean handleMessage(Message msg)
    Specified by:
      `handleMessage` in interface `Handler.Callback`