Merge "Clean up streaming API docs and organize errors" am: d2c8dcfcfe am: d98024a1f9 (7b8d8578) · Commits · e / os / android_frameworks_base

telephony/java/android/telephony/MbmsDownloadManager.java

+54 −33

Original line number	Original line	Diff line number	Diff line
	@@ -288,13 +288,11 @@ public class MbmsDownloadManager {
	*		*
	* This may throw an {@link MbmsException} containing one of the following errors:		* This may throw an {@link MbmsException} containing one of the following errors:
	* {@link MbmsException#ERROR_MIDDLEWARE_NOT_BOUND}		* {@link MbmsException#ERROR_MIDDLEWARE_NOT_BOUND}
	* {@link MbmsException#ERROR_CONCURRENT_SERVICE_LIMIT_REACHED}		* {@link MbmsException#ERROR_MIDDLEWARE_LOST}
	* {@link MbmsException#ERROR_SERVICE_LOST}
	*		*
	* Asynchronous error codes via the {@link MbmsDownloadManagerCallback#error(int, String)}		* Asynchronous error codes via the {@link MbmsDownloadManagerCallback#error(int, String)}
	* callback can include any of the errors except:		* callback can include any of the errors except:
	* {@link MbmsException#ERROR_UNABLE_TO_START_SERVICE}		* {@link MbmsException.StreamingErrors#ERROR_UNABLE_TO_START_SERVICE}
	* {@link MbmsException#ERROR_END_OF_SESSION}
	*		*
	* @param classList A list of service classes which the app wishes to receive		* @param classList A list of service classes which the app wishes to receive
	* {@link IMbmsDownloadManagerCallback#fileServicesUpdated(List)} callbacks		* {@link IMbmsDownloadManagerCallback#fileServicesUpdated(List)} callbacks
	@@ -315,7 +313,7 @@ public class MbmsDownloadManager {
	} catch (RemoteException e) {		} catch (RemoteException e) {
	Log.w(LOG_TAG, "Remote process died");		Log.w(LOG_TAG, "Remote process died");
	mService.set(null);		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		* Before calling this method, the app must cancel all of its pending
	* {@link DownloadRequest}s via {@link #cancelDownload(DownloadRequest)}. If this is not done,		* {@link DownloadRequest}s via {@link #cancelDownload(DownloadRequest)}. If this is not done,
	* an {@link MbmsException} will be thrown with code		* 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		* The {@link File} supplied as a root temp file directory must already exist. If not, an
	* {@link IllegalArgumentException} will be thrown.		* {@link IllegalArgumentException} will be thrown.
	@@ -366,7 +364,7 @@ public class MbmsDownloadManager {
	}		}
	} catch (RemoteException e) {		} catch (RemoteException e) {
	mService.set(null);		mService.set(null);
	throw new MbmsException(MbmsException.ERROR_SERVICE_LOST);		throw new MbmsException(MbmsException.ERROR_MIDDLEWARE_LOST);
	}		}

	SharedPreferences prefs = mContext.getSharedPreferences(		SharedPreferences prefs = mContext.getSharedPreferences(
	@@ -417,29 +415,36 @@ public class MbmsDownloadManager {
	downloadService.download(request, callback);		downloadService.download(request, callback);
	} catch (RemoteException e) {		} catch (RemoteException e) {
	mService.set(null);		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).		* Returns a list of pending {@link DownloadRequest}s that originated from this application.
	*		* A pending request is one that was issued via
	* May throw a RemoteException.		* {@link #download(DownloadRequest, IDownloadCallback)} but not cancelled through
	*		* {@link #cancelDownload(DownloadRequest)}.
	* Asynchronous errors through the listener include any of the errors except		* @return A list, possibly empty, of {@link DownloadRequest}s
	* <li>ERROR_UNABLED_TO_START_SERVICE</li>
	* <li>ERROR_MSDC_INVALID_SERVICE_ID</li>
	* <li>ERROR_MSDC_END_OF_SESSION</li>
	*/		*/
	public List<DownloadRequest> listPendingDownloads() {		public @NonNull List<DownloadRequest> listPendingDownloads() throws MbmsException {
	return null;		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}.		* Attempts to cancel the specified {@link DownloadRequest}.
	*		*
	* If the middleware is not aware of the specified download request, an MbmsException will be		* 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		* If this method returns without throwing an exception, you may assume that cancellation
	* was successful.		* was successful.
	@@ -458,7 +463,7 @@ public class MbmsDownloadManager {
	}		}
	} catch (RemoteException e) {		} catch (RemoteException e) {
	mService.set(null);		mService.set(null);
	throw new MbmsException(MbmsException.ERROR_SERVICE_LOST);		throw new MbmsException(MbmsException.ERROR_MIDDLEWARE_LOST);
	}		}
	deleteDownloadRequestToken(downloadRequest);		deleteDownloadRequestToken(downloadRequest);
	}		}
	@@ -486,27 +491,43 @@ public class MbmsDownloadManager {
	return downloadService.getDownloadStatus(downloadRequest, fileInfo);		return downloadService.getDownloadStatus(downloadRequest, fileInfo);
	} catch (RemoteException e) {		} catch (RemoteException e) {
	mService.set(null);		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 keeps track of the hashes of downloaded files and won't re-download
	* Normally the middleware won't download files who's hash matches previously downloaded		* files whose server-reported hash matches one of the already-downloaded files. This means
	* content, even if that content has since been deleted. If this function is called		* that if the file is accidentally deleted by the user or by the app, the middleware will
	* repeated content will be downloaded again when available. This does not interrupt		* not try to download it again.
	* in-progress downloads.		* 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>		* May throw a {@link MbmsException} with error code
	* <li>ERROR_MSDC_CONCURRENT_SERVICE_LIMIT_REACHED</li>		* @param downloadRequest The request to re-download files for.
	* <li>ERROR_MSDC_UNKNOWN_REQUEST</li>
	*/		*/
	public int resetDownloadKnowledge(DownloadRequest downloadRequest) {		public void resetDownloadKnowledge(DownloadRequest downloadRequest) throws MbmsException {
	return 0;		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() {		public void dispose() {

telephony/java/android/telephony/MbmsStreamingManager.java

+28 −16

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

	import static android.telephony.SubscriptionManager.INVALID_SUBSCRIPTION_ID;		import static android.telephony.SubscriptionManager.INVALID_SUBSCRIPTION_ID;

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

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

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

+0 −2

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

	void streamingServicesUpdated(in List<StreamingServiceInfo> services);		void streamingServicesUpdated(in List<StreamingServiceInfo> services);

	void activeStreamingServicesUpdated(in List<StreamingServiceInfo> services);

	void middlewareReady();		void middlewareReady();
	}		}

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

+1 −1

Original line number	Original line	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		* Before this method is called, calling any method on an instance of
	* {@link android.telephony.MbmsDownloadManager} will result in an {@link MbmsException}		* {@link android.telephony.MbmsDownloadManager} will result in an {@link MbmsException}
	* being thrown with error code {@link MbmsException#ERROR_MIDDLEWARE_NOT_BOUND}		* 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		@Override
	public void middlewareReady() {		public void middlewareReady() {

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

+105 −20

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

	/** @hide */		/** @hide */
	public class MbmsException extends Exception {		public class MbmsException extends Exception {
			/** Indicates that the operation was successful. */
	public static final int SUCCESS = 0;		public static final int SUCCESS = 0;
	public static final int ERROR_NO_SERVICE_INSTALLED = 1;
	public static final int ERROR_MULTIPLE_SERVICES_INSTALLED = 2;		// Following errors are generated in the manager and should not be returned from the
	public static final int ERROR_BIND_TIMEOUT_OR_FAILURE = 3;		// middleware
	public static final int ERROR_MIDDLEWARE_NOT_YET_READY = 4;		/**
	public static final int ERROR_ALREADY_INITIALIZED = 5;		* Indicates that either no MBMS middleware app is installed on the device or multiple
	public static final int ERROR_CONCURRENT_SERVICE_LIMIT_REACHED = 6;		* middleware apps are installed on the device.
	public static final int ERROR_MIDDLEWARE_NOT_BOUND = 7;		*/
	public static final int ERROR_UNABLE_TO_START_SERVICE = 8;		public static final int ERROR_NO_UNIQUE_MIDDLEWARE = 1;
	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;		* Indicates that the app attempted to perform an operation on an instance of
	public static final int ERROR_APP_PERMISSIONS_NOT_GRANTED = 12;		* {@link android.telephony.MbmsDownloadManager} or
	public static final int ERROR_IN_E911 = 13;		* {@link android.telephony.MbmsStreamingManager} without being bound to the middleware.
	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_MIDDLEWARE_NOT_BOUND = 2;
	public static final int ERROR_UNABLE_TO_READ_SIM = 16;
	public static final int ERROR_CARRIER_CHANGE_NOT_ALLOWED = 17;		/** Indicates that the middleware has died and the requested operation was not completed.*/
	public static final int ERROR_CANNOT_CHANGE_TEMP_FILE_ROOT = 18;		public static final int ERROR_MIDDLEWARE_LOST = 3;
	public static final int ERROR_UNKNOWN_DOWNLOAD_REQUEST = 19;
	public static final int ERROR_UNABLE_TO_INITIALIZE = 20;		/**
			* 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;		private final int mErrorCode;