Merge "Clean up streaming API docs and organize errors" (d2c8dcfc) · Commits · e / os / android_frameworks_base

telephony/java/android/telephony/MbmsDownloadManager.java

+54 −33

Original line number	Diff line number	Diff line
		@@ -288,13 +288,11 @@ public class MbmsDownloadManager {
		*
		* This may throw an {@link MbmsException} containing one of the following errors:
		* {@link MbmsException#ERROR_MIDDLEWARE_NOT_BOUND}
		* {@link MbmsException#ERROR_CONCURRENT_SERVICE_LIMIT_REACHED}
		* {@link MbmsException#ERROR_SERVICE_LOST}
		* {@link MbmsException#ERROR_MIDDLEWARE_LOST}
		*
		* Asynchronous error codes via the {@link MbmsDownloadManagerCallback#error(int, String)}
		* callback can include any of the errors except:
		* {@link MbmsException#ERROR_UNABLE_TO_START_SERVICE}
		* {@link MbmsException#ERROR_END_OF_SESSION}
		* {@link MbmsException.StreamingErrors#ERROR_UNABLE_TO_START_SERVICE}
		*
		* @param classList A list of service classes which the app wishes to receive
		* {@link IMbmsDownloadManagerCallback#fileServicesUpdated(List)} callbacks
		@@ -315,7 +313,7 @@ public class MbmsDownloadManager {
		} catch (RemoteException e) {
		Log.w(LOG_TAG, "Remote process died");
		mService.set(null);
		throw new MbmsException(MbmsException.ERROR_SERVICE_LOST);
		throw new MbmsException(MbmsException.ERROR_MIDDLEWARE_LOST);
		}
		}

		@@ -334,7 +332,7 @@ public class MbmsDownloadManager {
		* Before calling this method, the app must cancel all of its pending
		* {@link DownloadRequest}s via {@link #cancelDownload(DownloadRequest)}. If this is not done,
		* an {@link MbmsException} will be thrown with code
		* {@link MbmsException#ERROR_CANNOT_CHANGE_TEMP_FILE_ROOT}
		* {@link MbmsException.DownloadErrors#ERROR_CANNOT_CHANGE_TEMP_FILE_ROOT}
		*
		* The {@link File} supplied as a root temp file directory must already exist. If not, an
		* {@link IllegalArgumentException} will be thrown.
		@@ -366,7 +364,7 @@ public class MbmsDownloadManager {
		}
		} catch (RemoteException e) {
		mService.set(null);
		throw new MbmsException(MbmsException.ERROR_SERVICE_LOST);
		throw new MbmsException(MbmsException.ERROR_MIDDLEWARE_LOST);
		}

		SharedPreferences prefs = mContext.getSharedPreferences(
		@@ -417,29 +415,36 @@ public class MbmsDownloadManager {
		downloadService.download(request, callback);
		} catch (RemoteException e) {
		mService.set(null);
		throw new MbmsException(MbmsException.ERROR_SERVICE_LOST);
		throw new MbmsException(MbmsException.ERROR_MIDDLEWARE_LOST);
		}
		}

		/**
		* Returns a list DownloadRequests that originated from this application (UID).
		*
		* May throw a RemoteException.
		*
		* Asynchronous errors through the listener include any of the errors except
		* <li>ERROR_UNABLED_TO_START_SERVICE</li>
		* <li>ERROR_MSDC_INVALID_SERVICE_ID</li>
		* <li>ERROR_MSDC_END_OF_SESSION</li>
		* Returns a list of pending {@link DownloadRequest}s that originated from this application.
		* A pending request is one that was issued via
		* {@link #download(DownloadRequest, IDownloadCallback)} but not cancelled through
		* {@link #cancelDownload(DownloadRequest)}.
		* @return A list, possibly empty, of {@link DownloadRequest}s
		*/
		public List<DownloadRequest> listPendingDownloads() {
		return null;
		public @NonNull List<DownloadRequest> listPendingDownloads() throws MbmsException {
		IMbmsDownloadService downloadService = mService.get();
		if (downloadService == null) {
		throw new MbmsException(MbmsException.ERROR_MIDDLEWARE_NOT_BOUND);
		}

		try {
		return downloadService.listPendingDownloads(mSubscriptionId);
		} catch (RemoteException e) {
		mService.set(null);
		throw new MbmsException(MbmsException.ERROR_MIDDLEWARE_LOST);
		}
		}

		/**
		* Attempts to cancel the specified {@link DownloadRequest}.
		*
		* If the middleware is not aware of the specified download request, an MbmsException will be
		* thrown with error code {@link MbmsException#ERROR_UNKNOWN_DOWNLOAD_REQUEST}.
		* thrown with error code {@link MbmsException.DownloadErrors#ERROR_UNKNOWN_DOWNLOAD_REQUEST}.
		*
		* If this method returns without throwing an exception, you may assume that cancellation
		* was successful.
		@@ -458,7 +463,7 @@ public class MbmsDownloadManager {
		}
		} catch (RemoteException e) {
		mService.set(null);
		throw new MbmsException(MbmsException.ERROR_SERVICE_LOST);
		throw new MbmsException(MbmsException.ERROR_MIDDLEWARE_LOST);
		}
		deleteDownloadRequestToken(downloadRequest);
		}
		@@ -486,27 +491,43 @@ public class MbmsDownloadManager {
		return downloadService.getDownloadStatus(downloadRequest, fileInfo);
		} catch (RemoteException e) {
		mService.set(null);
		throw new MbmsException(MbmsException.ERROR_SERVICE_LOST);
		throw new MbmsException(MbmsException.ERROR_MIDDLEWARE_LOST);
		}
		}

		/**
		* Resets middleware knowledge regarding this download request.
		* Resets the middleware's knowledge of previously-downloaded files in this download request.
		*
		* This state consists of knowledge of what files have already been downloaded.
		* Normally the middleware won't download files who's hash matches previously downloaded
		* content, even if that content has since been deleted. If this function is called
		* repeated content will be downloaded again when available. This does not interrupt
		* in-progress downloads.
		* Normally, the middleware keeps track of the hashes of downloaded files and won't re-download
		* files whose server-reported hash matches one of the already-downloaded files. This means
		* that if the file is accidentally deleted by the user or by the app, the middleware will
		* not try to download it again.
		* This method will reset the middleware's cache of hashes for the provided
		* {@link DownloadRequest}, so that previously downloaded content will be downloaded again
		* when available.
		* This will not interrupt in-progress downloads.
		*
		* May throw an IllegalArgumentException or RemoteException.
		* If the middleware is not aware of the specified download request, an MbmsException will be
		* thrown with error code {@link MbmsException.DownloadErrors#ERROR_UNKNOWN_DOWNLOAD_REQUEST}.
		*
		* <li>SUCCESS</li>
		* <li>ERROR_MSDC_CONCURRENT_SERVICE_LIMIT_REACHED</li>
		* <li>ERROR_MSDC_UNKNOWN_REQUEST</li>
		* May throw a {@link MbmsException} with error code
		* @param downloadRequest The request to re-download files for.
		*/
		public int resetDownloadKnowledge(DownloadRequest downloadRequest) {
		return 0;
		public void resetDownloadKnowledge(DownloadRequest downloadRequest) throws MbmsException {
		IMbmsDownloadService downloadService = mService.get();
		if (downloadService == null) {
		throw new MbmsException(MbmsException.ERROR_MIDDLEWARE_NOT_BOUND);
		}

		try {
		int result = downloadService.resetDownloadKnowledge(downloadRequest);
		if (result != MbmsException.SUCCESS) {
		throw new MbmsException(result);
		}
		} catch (RemoteException e) {
		mService.set(null);
		throw new MbmsException(MbmsException.ERROR_MIDDLEWARE_LOST);
		}
		}

		public void dispose() {

telephony/java/android/telephony/MbmsStreamingManager.java

+28 −16

Original line number	Diff line number	Diff line
		@@ -35,7 +35,10 @@ import java.util.concurrent.atomic.AtomicReference;

		import static android.telephony.SubscriptionManager.INVALID_SUBSCRIPTION_ID;

		/** @hide */
		/**
		* This class provides functionality for streaming media over MBMS.
		* @hide
		*/
		public class MbmsStreamingManager {
		private static final String LOG_TAG = "MbmsStreamingManager";
		public static final String MBMS_STREAMING_SERVICE_ACTION =
		@@ -88,6 +91,8 @@ public class MbmsStreamingManager {
		/**
		* Terminates this instance, ending calls to the registered listener. Also terminates
		* any streaming services spawned from this instance.
		*
		* May throw an {@link IllegalStateException}
		*/
		public void dispose() {
		IMbmsStreamingService streamingService = mService.get();
		@@ -111,15 +116,15 @@ public class MbmsStreamingManager {
		*
		* Multiple calls replace the list of serviceClasses of interest.
		*
		* This may throw an {@link MbmsException} containing one of the following errors:
		* {@link MbmsException#ERROR_MIDDLEWARE_NOT_BOUND}
		* {@link MbmsException#ERROR_CONCURRENT_SERVICE_LIMIT_REACHED}
		* {@link MbmsException#ERROR_SERVICE_LOST}
		* This may throw an {@link MbmsException} containing any error in
		* {@link android.telephony.mbms.MbmsException.GeneralErrors},
		* {@link MbmsException#ERROR_MIDDLEWARE_NOT_BOUND}, or
		* {@link MbmsException#ERROR_MIDDLEWARE_LOST}.
		*
		* May also throw an unchecked {@link IllegalArgumentException} or an
		* {@link IllegalStateException}
		*
		* Asynchronous error codes via the {@link MbmsStreamingManagerCallback#error(int, String)}
		* callback can include any of the errors except:
		* {@link MbmsException#ERROR_UNABLE_TO_START_SERVICE}
		* {@link MbmsException#ERROR_END_OF_SESSION}
		* @param classList A list of streaming service classes that the app would like updates on.
		*/
		public void getStreamingServices(List<String> classList) throws MbmsException {
		IMbmsStreamingService streamingService = mService.get();
		@@ -134,7 +139,7 @@ public class MbmsStreamingManager {
		} catch (RemoteException e) {
		Log.w(LOG_TAG, "Remote process died");
		mService.set(null);
		throw new MbmsException(MbmsException.ERROR_SERVICE_LOST);
		throw new MbmsException(MbmsException.ERROR_MIDDLEWARE_LOST);
		}
		}

		@@ -145,14 +150,21 @@ public class MbmsStreamingManager {
		* reported via
		* {@link android.telephony.mbms.StreamingServiceCallback#streamStateUpdated(int, int)}
		*
		* May throw an {@link MbmsException} containing any of the following error codes:
		* {@link MbmsException#ERROR_MIDDLEWARE_NOT_BOUND}
		* {@link MbmsException#ERROR_CONCURRENT_SERVICE_LIMIT_REACHED}
		* {@link MbmsException#ERROR_SERVICE_LOST}
		* May throw an
		* {@link MbmsException} containing any of the error codes in
		* {@link android.telephony.mbms.MbmsException.GeneralErrors},
		* {@link MbmsException#ERROR_MIDDLEWARE_NOT_BOUND}, or
		* {@link MbmsException#ERROR_MIDDLEWARE_LOST}.
		*
		* May also throw an {@link IllegalArgumentException} or an {@link IllegalStateException}
		*
		* Asynchronous errors through the listener include any of the errors
		* Asynchronous errors through the listener include any of the errors in
		* {@link android.telephony.mbms.MbmsException.GeneralErrors} or
		* {@link android.telephony.mbms.MbmsException.StreamingErrors}.
		*
		* @param serviceInfo The information about the service to stream.
		* @param listener A listener that'll be called when something about the stream changes.
		* @return An instance of {@link StreamingService} through which the stream can be controlled.
		*/
		public StreamingService startStreaming(StreamingServiceInfo serviceInfo,
		StreamingServiceCallback listener) throws MbmsException {
		@@ -170,7 +182,7 @@ public class MbmsStreamingManager {
		} catch (RemoteException e) {
		Log.w(LOG_TAG, "Remote process died");
		mService.set(null);
		throw new MbmsException(MbmsException.ERROR_SERVICE_LOST);
		throw new MbmsException(MbmsException.ERROR_MIDDLEWARE_LOST);
		}

		return new StreamingService(mSubscriptionId, streamingService, serviceInfo, listener);

telephony/java/android/telephony/mbms/IMbmsStreamingManagerCallback.aidl

+0 −2

Original line number	Diff line number	Diff line
		@@ -30,7 +30,5 @@ oneway interface IMbmsStreamingManagerCallback

		void streamingServicesUpdated(in List<StreamingServiceInfo> services);

		void activeStreamingServicesUpdated(in List<StreamingServiceInfo> services);

		void middlewareReady();
		}

telephony/java/android/telephony/mbms/MbmsDownloadManagerCallback.java

+1 −1

Original line number	Diff line number	Diff line
		@@ -55,7 +55,7 @@ public class MbmsDownloadManagerCallback extends IMbmsDownloadManagerCallback.St
		* Before this method is called, calling any method on an instance of
		* {@link android.telephony.MbmsDownloadManager} will result in an {@link MbmsException}
		* being thrown with error code {@link MbmsException#ERROR_MIDDLEWARE_NOT_BOUND}
		* or {@link MbmsException#ERROR_MIDDLEWARE_NOT_YET_READY}
		* or {@link MbmsException.GeneralErrors#ERROR_MIDDLEWARE_NOT_YET_READY}
		*/
		@Override
		public void middlewareReady() {

telephony/java/android/telephony/mbms/MbmsException.java

+105 −20

Original line number	Diff line number	Diff line
		@@ -18,27 +18,112 @@ package android.telephony.mbms;

		/** @hide */
		public class MbmsException extends Exception {
		/** Indicates that the operation was successful. */
		public static final int SUCCESS = 0;
		public static final int ERROR_NO_SERVICE_INSTALLED = 1;
		public static final int ERROR_MULTIPLE_SERVICES_INSTALLED = 2;
		public static final int ERROR_BIND_TIMEOUT_OR_FAILURE = 3;
		public static final int ERROR_MIDDLEWARE_NOT_YET_READY = 4;
		public static final int ERROR_ALREADY_INITIALIZED = 5;
		public static final int ERROR_CONCURRENT_SERVICE_LIMIT_REACHED = 6;
		public static final int ERROR_MIDDLEWARE_NOT_BOUND = 7;
		public static final int ERROR_UNABLE_TO_START_SERVICE = 8;
		public static final int ERROR_STREAM_ALREADY_STARTED = 9;
		public static final int ERROR_END_OF_SESSION = 10;
		public static final int ERROR_SERVICE_LOST = 11;
		public static final int ERROR_APP_PERMISSIONS_NOT_GRANTED = 12;
		public static final int ERROR_IN_E911 = 13;
		public static final int ERROR_OUT_OF_MEMORY = 14;
		public static final int ERROR_NOT_CONNECTED_TO_HOME_CARRIER_LTE = 15;
		public static final int ERROR_UNABLE_TO_READ_SIM = 16;
		public static final int ERROR_CARRIER_CHANGE_NOT_ALLOWED = 17;
		public static final int ERROR_CANNOT_CHANGE_TEMP_FILE_ROOT = 18;
		public static final int ERROR_UNKNOWN_DOWNLOAD_REQUEST = 19;
		public static final int ERROR_UNABLE_TO_INITIALIZE = 20;

		// Following errors are generated in the manager and should not be returned from the
		// middleware
		/**
		* Indicates that either no MBMS middleware app is installed on the device or multiple
		* middleware apps are installed on the device.
		*/
		public static final int ERROR_NO_UNIQUE_MIDDLEWARE = 1;

		/**
		* Indicates that the app attempted to perform an operation on an instance of
		* {@link android.telephony.MbmsDownloadManager} or
		* {@link android.telephony.MbmsStreamingManager} without being bound to the middleware.
		*/
		public static final int ERROR_MIDDLEWARE_NOT_BOUND = 2;

		/** Indicates that the middleware has died and the requested operation was not completed.*/
		public static final int ERROR_MIDDLEWARE_LOST = 3;

		/**
		* Indicates errors that may be generated during initialization by the
		* middleware. They are applicable to both streaming and file-download use-cases.
		*/
		public static class InitializationErrors {
		/**
		* Indicates that the app tried to create more than one instance each of
		* {@link android.telephony.MbmsStreamingManager} or
		* {@link android.telephony.MbmsDownloadManager}.
		*/
		public static final int ERROR_DUPLICATE_INITIALIZE = 101;
		/** Indicates that the app is not authorized to access media via MBMS.*/
		public static final int ERROR_APP_PERMISSIONS_NOT_GRANTED = 102;
		/** Indicates that the middleware was unable to initialize for this app. */
		public static final int ERROR_UNABLE_TO_INITIALIZE = 103;
		}

		/**
		* Indicates the errors that may occur at any point and are applicable to both
		* streaming and file-download.
		*/
		public static class GeneralErrors {
		/**
		* Indicates that the app attempted to perform an operation before receiving notification
		* that the middleware is ready via {@link MbmsStreamingManagerCallback#middlewareReady()}
		* or {@link MbmsDownloadManagerCallback#middlewareReady()}.
		*/
		public static final int ERROR_MIDDLEWARE_NOT_YET_READY = 201;
		/**
		* Indicates that the middleware ran out of memory and was unable to complete the requested
		* operation.
		*/
		public static final int ERROR_OUT_OF_MEMORY = 202;
		/**
		* Indicates that the requested operation failed due to the middleware being unavailable due
		* to a transient condition. The app may retry the operation at a later time.
		*/
		public static final int ERROR_MIDDLEWARE_TEMPORARILY_UNAVAILABLE = 203;
		/**
		* Indicates that the requested operation was not performed due to being in emergency
		* callback mode.
		*/
		public static final int ERROR_IN_E911 = 204;
		/** Indicates that MBMS is not available due to the device being in roaming. */
		public static final int ERROR_NOT_CONNECTED_TO_HOME_CARRIER_LTE = 205;
		/** Indicates that MBMS is not available due to a SIM read error. */
		public static final int ERROR_UNABLE_TO_READ_SIM = 206;
		/**
		* Indicates that MBMS is not available due to the inserted SIM being from an unsupported
		* carrier.
		*/
		public static final int ERROR_CARRIER_CHANGE_NOT_ALLOWED = 207;
		}

		/**
		* Indicates the errors that are applicable only to the streaming use-case
		*/
		public static class StreamingErrors {
		/** Indicates that the middleware cannot start a stream due to too many ongoing streams */
		public static final int ERROR_CONCURRENT_SERVICE_LIMIT_REACHED = 301;

		/** Indicates that the middleware was unable to start the streaming service */
		public static final int ERROR_UNABLE_TO_START_SERVICE = 302;

		/**
		* Indicates that the app called
		* {@link android.telephony.MbmsStreamingManager#startStreaming(StreamingServiceInfo, StreamingServiceCallback)}
		* more than once for the same {@link StreamingServiceInfo}.
		*/
		public static final int ERROR_DUPLICATE_START_STREAM = 303;
		}

		/**
		* Indicates the errors that are applicable only to the file-download use-case
		*/
		public static class DownloadErrors {
		/**
		* Indicates that the app is not allowed to change the temp file root at this time due to
		* outstanding download requests.
		*/
		public static final int ERROR_CANNOT_CHANGE_TEMP_FILE_ROOT = 401;

		/** Indicates that the middleware has no record of the supplied {@link DownloadRequest}. */
		public static final int ERROR_UNKNOWN_DOWNLOAD_REQUEST = 402;
		}

		private final int mErrorCode;