Merge "Clean up streaming API docs and organize errors"

am: d2c8dcfcfe

Change-Id: I9d77d7dbc3c53baaa0ce4928de3bcbe353c1f6ab

12 files changed, 293 insertions, 127 deletions

diff --git a/telephony/java/android/telephony/MbmsDownloadManager.java b/telephony/java/android/telephony/MbmsDownloadManager.java
index 5fa6a952d709..4eeabb078a64 100644
--- a/telephony/java/android/telephony/MbmsDownloadManager.java
+++ b/telephony/java/android/telephony/MbmsDownloadManager.java
@@ -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() {
diff --git a/telephony/java/android/telephony/MbmsStreamingManager.java b/telephony/java/android/telephony/MbmsStreamingManager.java
index 8cc447e4db7a..5b3503a1b163 100644
--- a/telephony/java/android/telephony/MbmsStreamingManager.java
+++ b/telephony/java/android/telephony/MbmsStreamingManager.java
@@ -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}.
      *
-     * 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}
+     * May also throw an unchecked {@link IllegalArgumentException} or an
+     * {@link IllegalStateException}
+     *
+     * @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);
diff --git a/telephony/java/android/telephony/mbms/IMbmsStreamingManagerCallback.aidl b/telephony/java/android/telephony/mbms/IMbmsStreamingManagerCallback.aidl
index 8116a7f0b7c4..007aee7cf3f2 100755
--- a/telephony/java/android/telephony/mbms/IMbmsStreamingManagerCallback.aidl
+++ b/telephony/java/android/telephony/mbms/IMbmsStreamingManagerCallback.aidl
@@ -30,7 +30,5 @@ oneway interface IMbmsStreamingManagerCallback
 
     void streamingServicesUpdated(in List<StreamingServiceInfo> services);
 
-    void activeStreamingServicesUpdated(in List<StreamingServiceInfo> services);
-
     void middlewareReady();
 }
diff --git a/telephony/java/android/telephony/mbms/MbmsDownloadManagerCallback.java b/telephony/java/android/telephony/mbms/MbmsDownloadManagerCallback.java
index 5b22199bea1c..ba25f663ffb4 100644
--- a/telephony/java/android/telephony/mbms/MbmsDownloadManagerCallback.java
+++ b/telephony/java/android/telephony/mbms/MbmsDownloadManagerCallback.java
@@ -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() {
diff --git a/telephony/java/android/telephony/mbms/MbmsException.java b/telephony/java/android/telephony/mbms/MbmsException.java
index e190623f5529..8888119f90e6 100644
--- a/telephony/java/android/telephony/mbms/MbmsException.java
+++ b/telephony/java/android/telephony/mbms/MbmsException.java
@@ -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;
 
diff --git a/telephony/java/android/telephony/mbms/MbmsStreamingManagerCallback.java b/telephony/java/android/telephony/mbms/MbmsStreamingManagerCallback.java
index 27d9878a1966..2e91be9acaf7 100644
--- a/telephony/java/android/telephony/mbms/MbmsStreamingManagerCallback.java
+++ b/telephony/java/android/telephony/mbms/MbmsStreamingManagerCallback.java
@@ -50,25 +50,12 @@ public class MbmsStreamingManagerCallback extends IMbmsStreamingManagerCallback.
     }
 
     /**
-     * Called to indicate the active Streaming Services have changed.
-     *
-     * This will be caused whenever a new service starts streaming or whenever
-     * MbmsStreamServiceManager.getActiveStreamingServices is called.
-     *
-     * @param services a list of StreamingServiceInfos.  May be empty if
-     *                 there are no active StreamingServices
-     */
-    public void activeStreamingServicesUpdated(List<StreamingServiceInfo> services) {
-        // default implementation empty
-    }
-
-    /**
      * Called to indicate that the middleware has been initialized and is ready.
      *
      * Before this method is called, calling any method on an instance of
      * {@link android.telephony.MbmsStreamingManager} 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() {
diff --git a/telephony/java/android/telephony/mbms/MbmsUtils.java b/telephony/java/android/telephony/mbms/MbmsUtils.java
index 1e03fb9584b4..4b913f825231 100644
--- a/telephony/java/android/telephony/mbms/MbmsUtils.java
+++ b/telephony/java/android/telephony/mbms/MbmsUtils.java
@@ -22,14 +22,11 @@ import android.content.Intent;
 import android.content.ServiceConnection;
 import android.content.pm.*;
 import android.content.pm.ServiceInfo;
-import android.telephony.MbmsDownloadManager;
 import android.util.Log;
 
 import java.io.File;
 import java.io.IOException;
 import java.util.List;
-import java.util.concurrent.CountDownLatch;
-import java.util.concurrent.TimeUnit;
 
 /**
  * @hide
@@ -78,7 +75,7 @@ public class MbmsUtils {
                 MbmsUtils.getMiddlewareServiceInfo(context, serviceAction);
 
         if (mbmsServiceInfo == null) {
-            throw new MbmsException(MbmsException.ERROR_NO_SERVICE_INSTALLED);
+            throw new MbmsException(MbmsException.ERROR_NO_UNIQUE_MIDDLEWARE);
         }
 
         bindIntent.setComponent(MbmsUtils.toComponentName(mbmsServiceInfo));
diff --git a/telephony/java/android/telephony/mbms/StreamingService.java b/telephony/java/android/telephony/mbms/StreamingService.java
index 475c93aa0eb5..1a6418969a90 100644
--- a/telephony/java/android/telephony/mbms/StreamingService.java
+++ b/telephony/java/android/telephony/mbms/StreamingService.java
@@ -18,7 +18,6 @@ package android.telephony.mbms;
 
 import android.annotation.IntDef;
 import android.net.Uri;
-import android.os.DeadObjectException;
 import android.os.RemoteException;
 import android.telephony.mbms.vendor.IMbmsStreamingService;
 import android.util.Log;
@@ -50,15 +49,42 @@ public class StreamingService {
      */
     @Retention(RetentionPolicy.SOURCE)
     @IntDef({REASON_BY_USER_REQUEST, REASON_END_OF_SESSION, REASON_FREQUENCY_CONFLICT,
-            REASON_OUT_OF_MEMORY, REASON_NOT_CONNECTED_TO_HOMECARRIER_LTE})
+            REASON_OUT_OF_MEMORY, REASON_NOT_CONNECTED_TO_HOMECARRIER_LTE,
+            REASON_LEFT_MBMS_BROADCAST_AREA})
     public @interface StreamingStateChangeReason {}
+
+    /**
+     * State changed due to a call to {@link #stopStreaming()} or
+     * {@link android.telephony.MbmsStreamingManager#startStreaming(StreamingServiceInfo, StreamingServiceCallback)}
+     */
     public static final int REASON_BY_USER_REQUEST = 1;
+
+    /**
+     * State changed due to the streaming session ending at the carrier.
+     */
     public static final int REASON_END_OF_SESSION = 2;
+
+    /**
+     * State changed due to a frequency conflict with another requested stream.
+     */
     public static final int REASON_FREQUENCY_CONFLICT = 3;
+
+    /**
+     * State changed due to the middleware running out of memory
+     */
     public static final int REASON_OUT_OF_MEMORY = 4;
+
+    /**
+     * State changed due to the device leaving the home carrier's LTE network.
+     */
     public static final int REASON_NOT_CONNECTED_TO_HOMECARRIER_LTE = 5;
 
     /**
+     * State changed due to the device leaving the where this stream is being broadcast.
+     */
+    public static final int REASON_LEFT_MBMS_BROADCAST_AREA = 5;
+
+    /**
      * The method of transmission currently used for a stream,
      * reported via {@link StreamingServiceCallback#streamMethodUpdated}
      */
@@ -87,7 +113,9 @@ public class StreamingService {
      * Retreive the Uri used to play this stream.
      *
      * This may throw a {@link MbmsException} with the error code
-     * {@link MbmsException#ERROR_SERVICE_LOST}
+     * {@link MbmsException#ERROR_MIDDLEWARE_LOST}
+     *
+     * May also throw an {@link IllegalArgumentException} or an {@link IllegalStateException}
      *
      * @return The {@link Uri} to pass to the streaming client.
      */
@@ -101,7 +129,7 @@ public class StreamingService {
         } catch (RemoteException e) {
             Log.w(LOG_TAG, "Remote process died");
             mService = null;
-            throw new MbmsException(MbmsException.ERROR_SERVICE_LOST);
+            throw new MbmsException(MbmsException.ERROR_MIDDLEWARE_LOST);
         }
     }
 
@@ -115,7 +143,9 @@ public class StreamingService {
     /**
      * Stop streaming this service.
      * This may throw a {@link MbmsException} with the error code
-     * {@link MbmsException#ERROR_SERVICE_LOST}
+     * {@link MbmsException#ERROR_MIDDLEWARE_LOST}
+     *
+     * May also throw an {@link IllegalArgumentException} or an {@link IllegalStateException}
      */
     public void stopStreaming() throws MbmsException {
         if (mService == null) {
@@ -127,10 +157,18 @@ public class StreamingService {
         } catch (RemoteException e) {
             Log.w(LOG_TAG, "Remote process died");
             mService = null;
-            throw new MbmsException(MbmsException.ERROR_SERVICE_LOST);
+            throw new MbmsException(MbmsException.ERROR_MIDDLEWARE_LOST);
         }
     }
 
+    /**
+     * Disposes of this stream. Further operations on this object will fail with an
+     * {@link IllegalStateException}.
+     *
+     * This may throw a {@link MbmsException} with the error code
+     * {@link MbmsException#ERROR_MIDDLEWARE_LOST}
+     * May also throw an {@link IllegalArgumentException} or an {@link IllegalStateException}
+     */
     public void dispose() throws MbmsException {
         if (mService == null) {
             throw new IllegalStateException("No streaming service attached");
@@ -140,8 +178,9 @@ public class StreamingService {
             mService.disposeStream(mSubscriptionId, mServiceInfo.getServiceId());
         } catch (RemoteException e) {
             Log.w(LOG_TAG, "Remote process died");
+            throw new MbmsException(MbmsException.ERROR_MIDDLEWARE_LOST);
+        } finally {
             mService = null;
-            throw new MbmsException(MbmsException.ERROR_SERVICE_LOST);
         }
     }
 }
diff --git a/telephony/java/android/telephony/mbms/vendor/IMbmsDownloadService.aidl b/telephony/java/android/telephony/mbms/vendor/IMbmsDownloadService.aidl
index 06be8a011203..725d11c880b2 100755
--- a/telephony/java/android/telephony/mbms/vendor/IMbmsDownloadService.aidl
+++ b/telephony/java/android/telephony/mbms/vendor/IMbmsDownloadService.aidl
@@ -24,7 +24,6 @@ import android.telephony.mbms.IMbmsDownloadManagerCallback;
 import android.telephony.mbms.IDownloadCallback;
 
 /**
- * The interface the opaque MbmsStreamingService will satisfy.
  * @hide
  */
 interface IMbmsDownloadService
@@ -43,12 +42,7 @@ interface IMbmsDownloadService
 
     int getDownloadStatus(in DownloadRequest downloadRequest, in FileInfo fileInfo);
 
-    /*
-     * named this for 2 reasons:
-     *  1 don't want 'State' here as it conflicts with 'Status' of the previous function
-     *  2 want to perfect typing 'Knowledge'
-     */
-    void resetDownloadKnowledge(in DownloadRequest downloadRequest);
+    int resetDownloadKnowledge(in DownloadRequest downloadRequest);
 
     void dispose(int subId);
 }
diff --git a/telephony/java/android/telephony/mbms/vendor/IMbmsStreamingService.aidl b/telephony/java/android/telephony/mbms/vendor/IMbmsStreamingService.aidl
index 1370b83857ec..04a53cbe0d00 100755
--- a/telephony/java/android/telephony/mbms/vendor/IMbmsStreamingService.aidl
+++ b/telephony/java/android/telephony/mbms/vendor/IMbmsStreamingService.aidl
@@ -22,12 +22,11 @@ import android.telephony.mbms.IStreamingServiceCallback;
 import android.telephony.mbms.StreamingServiceInfo;
 
 /**
- * The interface the opaque MbmsStreamingService will satisfy.
  * @hide
  */
 interface IMbmsStreamingService
 {
-    int initialize(IMbmsStreamingManagerCallback listener, int subId);
+    void initialize(IMbmsStreamingManagerCallback listener, int subId);
 
     int getStreamingServices(int subId, in List<String> serviceClasses);
 
diff --git a/telephony/java/android/telephony/mbms/vendor/MbmsDownloadServiceBase.java b/telephony/java/android/telephony/mbms/vendor/MbmsDownloadServiceBase.java
index 305d38780ffc..8fbd4481cfc2 100644
--- a/telephony/java/android/telephony/mbms/vendor/MbmsDownloadServiceBase.java
+++ b/telephony/java/android/telephony/mbms/vendor/MbmsDownloadServiceBase.java
@@ -16,6 +16,7 @@
 
 package android.telephony.mbms.vendor;
 
+import android.annotation.NonNull;
 import android.os.RemoteException;
 import android.telephony.mbms.DownloadRequest;
 import android.telephony.mbms.FileInfo;
@@ -35,7 +36,9 @@ public class MbmsDownloadServiceBase extends IMbmsDownloadService.Stub {
     /**
      * Initialize the download service for this app and subId, registering the listener.
      *
-     * May throw an {@link IllegalArgumentException} or a {@link SecurityException}
+     * Exceptions should not be thrown through this method -- this method is called from within a
+     * {@link android.content.ServiceConnection} defined by the framework, so apps have no way of
+     * catching them. Call {@link IMbmsDownloadManagerCallback#error(int, String)} instead.
      *
      * @param listener The callback to use to communicate with the app.
      * @param subscriptionId The subscription ID to use.
@@ -59,9 +62,8 @@ public class MbmsDownloadServiceBase extends IMbmsDownloadService.Stub {
      * @param serviceClasses The service classes that the app wishes to get info on. The strings
      *                       may contain arbitrary data as negotiated between the app and the
      *                       carrier.
-     * @return One of {@link MbmsException#SUCCESS},
-     *         {@link MbmsException#ERROR_MIDDLEWARE_NOT_YET_READY},
-     *         {@link MbmsException#ERROR_CONCURRENT_SERVICE_LIMIT_REACHED}
+     * @return One of {@link MbmsException#SUCCESS} or
+     *         {@link MbmsException.GeneralErrors#ERROR_MIDDLEWARE_NOT_YET_READY},
      */
     @Override
     public int getFileServices(int subscriptionId, List<String> serviceClasses)
@@ -76,14 +78,13 @@ public class MbmsDownloadServiceBase extends IMbmsDownloadService.Stub {
      *
      * If the calling app (as identified by the calling UID) currently has any pending download
      * requests that have not been canceled, the middleware must return
-     * {@link MbmsException#ERROR_CANNOT_CHANGE_TEMP_FILE_ROOT} here.
+     * {@link MbmsException.DownloadErrors#ERROR_CANNOT_CHANGE_TEMP_FILE_ROOT} here.
      *
      * @param subscriptionId The subscription id the download is operating under.
      * @param rootDirectoryPath The path to the app's temp file root directory.
      * @return {@link MbmsException#SUCCESS},
-     *         {@link MbmsException#ERROR_MIDDLEWARE_NOT_YET_READY},
-     *         {@link MbmsException#ERROR_CANNOT_CHANGE_TEMP_FILE_ROOT},
-     *         or {@link MbmsException#ERROR_CONCURRENT_SERVICE_LIMIT_REACHED}
+     *         {@link MbmsException.GeneralErrors#ERROR_MIDDLEWARE_NOT_YET_READY} or
+     *         {@link MbmsException.DownloadErrors#ERROR_CANNOT_CHANGE_TEMP_FILE_ROOT}
      */
     @Override
     public int setTempFileRootDirectory(int subscriptionId,
@@ -109,8 +110,18 @@ public class MbmsDownloadServiceBase extends IMbmsDownloadService.Stub {
         return 0;
     }
 
+
+    /**
+     * Returns a list of pending {@link DownloadRequest}s that originated from the calling
+     * application, identified by its uid. A pending request is one that was issued via
+     * {@link #download(DownloadRequest, IDownloadCallback)} but not cancelled through
+     * {@link #cancelDownload(DownloadRequest)}.
+     * The middleware must return a non-null result synchronously or throw an exception
+     * inheriting from {@link RuntimeException}.
+     * @return A list, possibly empty, of {@link DownloadRequest}s
+     */
     @Override
-    public List<DownloadRequest> listPendingDownloads(int subscriptionId)
+    public @NonNull List<DownloadRequest> listPendingDownloads(int subscriptionId)
             throws RemoteException {
         return null;
     }
@@ -124,23 +135,47 @@ public class MbmsDownloadServiceBase extends IMbmsDownloadService.Stub {
      * {@link DownloadRequest}.
      * @param downloadRequest The request to cancel
      * @return {@link MbmsException#SUCCESS},
-     *         {@link MbmsException#ERROR_UNKNOWN_DOWNLOAD_REQUEST},
-     *         {@link MbmsException#ERROR_MIDDLEWARE_NOT_YET_READY}
+     *         {@link MbmsException.DownloadErrors#ERROR_UNKNOWN_DOWNLOAD_REQUEST},
+     *         {@link MbmsException.GeneralErrors#ERROR_MIDDLEWARE_NOT_YET_READY}
      */
     @Override
     public int cancelDownload(DownloadRequest downloadRequest) throws RemoteException {
         return 0;
     }
 
+    /**
+     * Gets information about the status of a file pending download.
+     *
+     * If the middleware has not yet been properly initialized or if it has no records of the
+     * file indicated by {@code fileInfo} being associated with {@code downloadRequest},
+     * {@link android.telephony.MbmsDownloadManager#STATUS_UNKNOWN} must be returned.
+     *
+     * @param downloadRequest The download request to query.
+     * @param fileInfo The particular file within the request to get information on.
+     * @return The status of the download.
+     */
     @Override
     public int getDownloadStatus(DownloadRequest downloadRequest, FileInfo fileInfo)
             throws RemoteException {
         return 0;
     }
 
+    /**
+     * Resets the middleware's knowledge of previously-downloaded files in this download request.
+     *
+     * When this method is called, the middleware must attempt to re-download all the files
+     * specified by the {@link DownloadRequest}, even if the files have not changed on the server.
+     * In addition, current in-progress downloads must not be interrupted.
+     *
+     * If the middleware is not aware of the specified download request, return
+     * {@link MbmsException.DownloadErrors#ERROR_UNKNOWN_DOWNLOAD_REQUEST}.
+     *
+     * @param downloadRequest The request to re-download files for.
+     */
     @Override
-    public void resetDownloadKnowledge(DownloadRequest downloadRequest)
+    public int resetDownloadKnowledge(DownloadRequest downloadRequest)
             throws RemoteException {
+        return 0;
     }
 
     /**
diff --git a/telephony/java/android/telephony/mbms/vendor/MbmsStreamingServiceBase.java b/telephony/java/android/telephony/mbms/vendor/MbmsStreamingServiceBase.java
index c97e754d1dd5..f072c46171d6 100644
--- a/telephony/java/android/telephony/mbms/vendor/MbmsStreamingServiceBase.java
+++ b/telephony/java/android/telephony/mbms/vendor/MbmsStreamingServiceBase.java
@@ -33,16 +33,17 @@ public class MbmsStreamingServiceBase extends IMbmsStreamingService.Stub {
     /**
      * Initialize streaming service for this app and subId, registering the listener.
      *
-     * May throw an {@link IllegalArgumentException} or a {@link SecurityException}
+     * Exceptions should not be thrown through this method -- this method is called from within a
+     * {@link android.content.ServiceConnection} defined by the framework, so apps have no way of
+     * catching them. Call {@link IMbmsStreamingManagerCallback#error(int, String)} instead.
      *
      * @param listener The callback to use to communicate with the app.
      * @param subscriptionId The subscription ID to use.
-     * @return {@link MbmsException#SUCCESS} or {@link MbmsException#ERROR_ALREADY_INITIALIZED}
      */
     @Override
-    public int initialize(IMbmsStreamingManagerCallback listener, int subscriptionId)
+    public void initialize(IMbmsStreamingManagerCallback listener, int subscriptionId)
             throws RemoteException {
-        return 0;
+        return;
     }
 
     /**
@@ -59,9 +60,8 @@ public class MbmsStreamingServiceBase extends IMbmsStreamingService.Stub {
      * @param serviceClasses The service classes that the app wishes to get info on. The strings
      *                       may contain arbitrary data as negotiated between the app and the
      *                       carrier.
-     * @return One of {@link MbmsException#SUCCESS},
-     *         {@link MbmsException#ERROR_MIDDLEWARE_NOT_YET_READY},
-     *         {@link MbmsException#ERROR_CONCURRENT_SERVICE_LIMIT_REACHED}
+     * @return {@link MbmsException#SUCCESS} or any of the errors in
+     * {@link android.telephony.mbms.MbmsException.GeneralErrors}
      */
     @Override
     public int getStreamingServices(int subscriptionId,
@@ -79,8 +79,7 @@ public class MbmsStreamingServiceBase extends IMbmsStreamingService.Stub {
      * @param subscriptionId The subscription id to use.
      * @param serviceId The ID of the streaming service that the app has requested.
      * @param listener The listener object on which the app wishes to receive updates.
-     * @return {@link MbmsException#SUCCESS}, {@link MbmsException#ERROR_STREAM_ALREADY_STARTED},
-     *         or {@link MbmsException#ERROR_UNABLE_TO_START_SERVICE}.
+     * @return Any error in {@link android.telephony.mbms.MbmsException.GeneralErrors}
      */
     @Override
     public int startStreaming(int subscriptionId, String serviceId,