Skip to content

SDK / exoplayer

Go to a project
Commit 9d99f921 by olly Committed by Toni
Options

Improve DownloadService action documentation 

PiperOrigin-RevId: 240440477
parent e3a8429e
Inline Side-by-side
Showing with 97 additions and 46 deletions
library/core/src/main/java/com/google/android/exoplayer2/offline/DownloadService.java
...@@ -36,51 +36,95 @@ import java.util.HashMap; ...@@ -36,51 +36,95 @@ import java.util.HashMap;
/** A {@link Service} for downloading media. */ /** A {@link Service} for downloading media. */
public abstract class DownloadService extends Service { public abstract class DownloadService extends Service {
/** Starts a download service without adding a new {@link DownloadAction}. */ /**
* Starts a download service without adding a new {@link DownloadAction}. Extras:
*
* <ul>
* <li>{@link #KEY_FOREGROUND} - See {@link #KEY_FOREGROUND}.
* </ul>
*/
public static final String ACTION_INIT = public static final String ACTION_INIT =
"com.google.android.exoplayer.downloadService.action.INIT"; "com.google.android.exoplayer.downloadService.action.INIT";
/** Starts a download service, adding a new {@link DownloadAction} to be executed. */ /** Like {@link #ACTION_INIT}, but with {@link #KEY_FOREGROUND} implicitly set to true. */
public static final String ACTION_ADD = "com.google.android.exoplayer.downloadService.action.ADD"; private static final String ACTION_RESTART =
"com.google.android.exoplayer.downloadService.action.RESTART";
/** Stops one or all downloads. */ /**
public static final String ACTION_STOP = * Adds a new download. Extras:
"com.google.android.exoplayer.downloadService.action.STOP"; *
* <ul>
* <li>{@link #KEY_DOWNLOAD_ACTION} - The {@code byte[]} representation of the {@link
* DownloadAction} that defines the download to be added. The required representation can be
* obtained by calling {@link DownloadAction#toByteArray()}.
* <li>{@link #KEY_FOREGROUND} - See {@link #KEY_FOREGROUND}.
* </ul>
*/
public static final String ACTION_ADD = "com.google.android.exoplayer.downloadService.action.ADD";
/** Starts one or all downloads. */ /**
* Starts one or all of the current downloads. Extras:
*
* <ul>
* <li>{@link #KEY_CONTENT_ID} - The content id of a single download to start. If omitted, all
* of the current downloads will be started.
* <li>{@link #KEY_FOREGROUND} - See {@link #KEY_FOREGROUND}.
* </ul>
*/
public static final String ACTION_START = public static final String ACTION_START =
"com.google.android.exoplayer.downloadService.action.START"; "com.google.android.exoplayer.downloadService.action.START";
/** Removes one download. */ /**
* Stops one or all of the current downloads. Extras:
*
* <ul>
* <li>{@link #KEY_CONTENT_ID} - The content id of a single download to stop. If omitted, all of
* the current downloads will be stopped.
* <li>{@link #KEY_STOP_REASON} - An application provided reason for stopping the download or
* downloads. Must not be {@link DownloadState#MANUAL_STOP_REASON_NONE}. If omitted, the
* stop reason will be {@link DownloadState#MANUAL_STOP_REASON_UNDEFINED}.
* <li>{@link #KEY_FOREGROUND} - See {@link #KEY_FOREGROUND}.
* </ul>
*/
public static final String ACTION_STOP =
"com.google.android.exoplayer.downloadService.action.STOP";
/**
* Removes an existing download. Extras:
*
* <ul>
* <li>{@link #KEY_CONTENT_ID} - The content id of a download to remove.
* <li>{@link #KEY_FOREGROUND} - See {@link #KEY_FOREGROUND}.
* </ul>
*/
public static final String ACTION_REMOVE = public static final String ACTION_REMOVE =
"com.google.android.exoplayer.downloadService.action.REMOVE"; "com.google.android.exoplayer.downloadService.action.REMOVE";
/** Like {@link #ACTION_INIT}, but with {@link #KEY_FOREGROUND} implicitly set to true. */ /**
private static final String ACTION_RESTART = * Key for the {@code byte[]} representation of the {@link DownloadAction} in {@link #ACTION_ADD}
"com.google.android.exoplayer.downloadService.action.RESTART"; * intents.
*/
/** Key for the {@link DownloadAction} in an {@link #ACTION_ADD} intent. */
public static final String KEY_DOWNLOAD_ACTION = "download_action"; public static final String KEY_DOWNLOAD_ACTION = "download_action";
/** /**
* Key for content id in an {@link #ACTION_STOP}, {@link #ACTION_START} or {@link #ACTION_REMOVE} * Key for the content id in {@link #ACTION_START}, {@link #ACTION_STOP} and {@link
* intent. * #ACTION_REMOVE} intents.
*/ */
public static final String KEY_CONTENT_ID = "content_id"; public static final String KEY_CONTENT_ID = "content_id";
/** Key for manual stop reason in an {@link #ACTION_STOP} intent. */ /** Key for the stop reason in {@link #ACTION_STOP} intents. */
public static final String KEY_STOP_REASON = "stop_reason"; public static final String KEY_STOP_REASON = "stop_reason";
/** Invalid foreground notification id which can be used to run the service in the background. */
public static final int FOREGROUND_NOTIFICATION_ID_NONE = 0;
/** /**
* Key for a boolean flag in any intent to indicate whether the service was started in the * Key for a boolean extra that can be set on any intent to indicate whether the service was
* foreground. If set, the service is guaranteed to call {@link #startForeground(int, * started in the foreground. If set, the service is guaranteed to call {@link
* Notification)}. * #startForeground(int, Notification)}.
*/ */
public static final String KEY_FOREGROUND = "foreground"; public static final String KEY_FOREGROUND = "foreground";
/** Invalid foreground notification id that can be used to run the service in the background. */
public static final int FOREGROUND_NOTIFICATION_ID_NONE = 0;
/** Default foreground notification update interval in milliseconds. */ /** Default foreground notification update interval in milliseconds. */
public static final long DEFAULT_FOREGROUND_NOTIFICATION_UPDATE_INTERVAL = 1000; public static final long DEFAULT_FOREGROUND_NOTIFICATION_UPDATE_INTERVAL = 1000;
...@@ -121,7 +165,7 @@ public abstract class DownloadService extends Service { ...@@ -121,7 +165,7 @@ public abstract class DownloadService extends Service {
} }
/** /**
* Creates a DownloadService which will run in the foreground. {@link * Creates a DownloadService that will run in the foreground. {@link
* #getForegroundNotification(DownloadState[])} should be overridden in the subclass. * #getForegroundNotification(DownloadState[])} should be overridden in the subclass.
* *
* @param foregroundNotificationId The notification id for the foreground notification, must not * @param foregroundNotificationId The notification id for the foreground notification, must not
...@@ -139,7 +183,7 @@ public abstract class DownloadService extends Service { ...@@ -139,7 +183,7 @@ public abstract class DownloadService extends Service {
} }
/** /**
* Creates a DownloadService which will run in the foreground. {@link * Creates a DownloadService that will run in the foreground. {@link
* #getForegroundNotification(DownloadState[])} should be overridden in the subclass. * #getForegroundNotification(DownloadState[])} should be overridden in the subclass.
* *
* @param foregroundNotificationId The notification id for the foreground notification. Must not * @param foregroundNotificationId The notification id for the foreground notification. Must not
...@@ -340,42 +384,47 @@ public abstract class DownloadService extends Service { ...@@ -340,42 +384,47 @@ public abstract class DownloadService extends Service {
case ACTION_ADD: case ACTION_ADD:
byte[] actionData = intent.getByteArrayExtra(KEY_DOWNLOAD_ACTION); byte[] actionData = intent.getByteArrayExtra(KEY_DOWNLOAD_ACTION);
if (actionData == null) { if (actionData == null) {
Log.e(TAG, "Ignoring ADD action with no action data"); Log.e(TAG, "Ignored ADD action: Missing download_action extra");
} else { } else {
DownloadAction downloadAction = null;
try { try {
downloadManager.handleAction(DownloadAction.fromByteArray(actionData)); downloadAction = DownloadAction.fromByteArray(actionData);
} catch (IOException e) { } catch (IOException e) {
Log.e(TAG, "Failed to handle ADD action", e); Log.e(TAG, "Ignored ADD action: Failed to deserialize download_action extra", e);
}
if (downloadAction != null) {
downloadManager.handleAction(downloadAction);
} }
} }
break; break;
case ACTION_STOP: case ACTION_START:
String stopDownloadId = intent.getStringExtra(KEY_CONTENT_ID); String contentId = intent.getStringExtra(KEY_CONTENT_ID);
int stopReason = intent.getIntExtra(KEY_STOP_REASON, 0); if (contentId == null) {
if (stopDownloadId == null) { downloadManager.startDownloads();
downloadManager.stopDownloads(stopReason);
} else { } else {
downloadManager.stopDownload(stopDownloadId, stopReason); downloadManager.startDownload(contentId);
} }
break; break;
case ACTION_START: case ACTION_STOP:
String startDownloadId = intent.getStringExtra(KEY_CONTENT_ID); contentId = intent.getStringExtra(KEY_CONTENT_ID);
if (startDownloadId == null) { int stopReason =
downloadManager.startDownloads(); intent.getIntExtra(KEY_STOP_REASON, DownloadState.MANUAL_STOP_REASON_UNDEFINED);
if (contentId == null) {
downloadManager.stopDownloads(stopReason);
} else { } else {
downloadManager.startDownload(startDownloadId); downloadManager.stopDownload(contentId, stopReason);
} }
break; break;
case ACTION_REMOVE: case ACTION_REMOVE:
String id3 = intent.getStringExtra(KEY_CONTENT_ID); contentId = intent.getStringExtra(KEY_CONTENT_ID);
if (id3 == null) { if (contentId == null) {
Log.e(TAG, "Ignoring REMOVE action with no id"); Log.e(TAG, "Ignored REMOVE action: Missing content_id extra");
} else { } else {
downloadManager.removeDownload(id3); downloadManager.removeDownload(contentId);
} }
break; break;
default: default:
Log.e(TAG, "Ignoring unrecognized action: " + intentAction); Log.e(TAG, "Ignored unrecognized action: " + intentAction);
break; break;
} }
...@@ -402,7 +451,9 @@ public abstract class DownloadService extends Service { ...@@ -402,7 +451,9 @@ public abstract class DownloadService extends Service {
} }
} }
/** DownloadService isn't designed to be bound. */ /**
* Throws {@link UnsupportedOperationException} because this service is not designed to be bound.
*/
@Nullable @Nullable
@Override @Override
public final IBinder onBind(Intent intent) { public final IBinder onBind(Intent intent) {
...@@ -445,9 +496,9 @@ public abstract class DownloadService extends Service { ...@@ -445,9 +496,9 @@ public abstract class DownloadService extends Service {
} }
/** /**
* Called when the state of a download changes. * Called when the state of a download changes. The default implementation is a no-op.
* *
* @param downloadState The state of the download. * @param downloadState The new state of the download.
*/ */
protected void onDownloadStateChanged(DownloadState downloadState) { protected void onDownloadStateChanged(DownloadState downloadState) {
// Do nothing. // Do nothing.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or sign in to comment