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 String` | `ACTION_DOWNLOAD_COMPLETED` | Use this as action in `IntentFilter.addAction(String)` to receive messages that a download has been completed
    `static String` | `ACTION_DOWNLOAD_CREATED` | Use this as action in `IntentFilter.addAction(String)` to receive messages that a download has been created
    `static String` | `ACTION_DOWNLOAD_DELETED` | Use this as action in `IntentFilter.addAction(String)` to receive messages that a download has been deleted
    `static String` | `ACTION_DOWNLOAD_ERROR` | Use this as action in `IntentFilter.addAction(String)` to receive messages that a download error occurred
    `static 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 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 String` | `ACTION_DOWNLOAD_PROGRESS` | Use this as action in `IntentFilter.addAction(String)` to receive messages that progress was made on the current download
    `static String` | `ACTION_DOWNLOAD_STARTED` | Use this as action in `IntentFilter.addAction(String)` to receive messages that a download has been started
    `static String` | `ACTION_DOWNLOAD_STOPPED` | Use this as action in `IntentFilter.addAction(String)` to receive messages that a download has been stopped
    `static 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 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 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 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 int` | `DOWNLOAD_UPDATE_PATH_RESULT_ERROR_DOWNLOAD_UNKNOWN` | The download path could not be updated due to an unknown error.
    `static int` | `DOWNLOAD_UPDATE_PATH_RESULT_SUCCESS` | The download path has been successfully updated.
    `static int` | `ERROR_TYPE_CONNECTION_ERROR` | Error type that indicates a connectivity issue on the client device
    `static int` | `ERROR_TYPE_DRM_ERROR` | Error type that indicates a DRM license fetching error.
    `static int` | `ERROR_TYPE_HTTP_ERROR` | Error type for HTTP related download error.
    `static int` | `ERROR_TYPE_UNKNOWN_ERROR` | Generic error type for errors that could not be identified more specifically
    `static String` | `INTENT_DOWNLOAD_CATEGORY` | Use this as category in `IntentFilter.addCategory(java.lang.String)` for filtering out the broadcasted downloader messages
    `static String` | `INTENT_DOWNLOAD_ERROR` | Use this as `Intent` key to indicate the download error
    `static String` | `INTENT_DOWNLOAD_ERROR_DRM` | Use this as `Intent` key to find the DRM error.
    `static 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 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 String` | `INTENT_DOWNLOAD_ERROR_TYPE` | Use this as `Intent` key to find the error type.
    `static String` | `INTENT_DOWNLOAD_ID` | Use this as `Intent` key to indicate the download Id
    `static 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 String` | `INTENT_DOWNLOAD_PATH_UPDATE_RESULT` | Use this as `Intent` key to find the result of the Download Path Update.

  - ### Method Summary

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

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

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

    - #### handleMessage

          public boolean handleMessage​(Message msg)

      Specified by:
        `handleMessage` in interface `Handler.Callback`