Merge "Make slight API and doc adjustments"

am: b7e10650d8

Change-Id: I96a361924ddff300eb36933bed67d30ec00e8f87

8 files changed, 66 insertions, 28 deletions

diff --git a/telephony/java/android/telephony/MbmsDownloadManager.java b/telephony/java/android/telephony/MbmsDownloadManager.java
index c747b8488634..4c3f7e7ab5a8 100644
--- a/telephony/java/android/telephony/MbmsDownloadManager.java
+++ b/telephony/java/android/telephony/MbmsDownloadManager.java
@@ -211,9 +211,9 @@ public class MbmsDownloadManager {
     private int mSubscriptionId = INVALID_SUBSCRIPTION_ID;
 
     private AtomicReference<IMbmsDownloadService> mService = new AtomicReference<>(null);
-    private final IMbmsDownloadManagerCallback mCallback;
+    private final MbmsDownloadManagerCallback mCallback;
 
-    private MbmsDownloadManager(Context context, IMbmsDownloadManagerCallback callback, int subId) {
+    private MbmsDownloadManager(Context context, MbmsDownloadManagerCallback callback, int subId) {
         mContext = context;
         mCallback = callback;
         mSubscriptionId = subId;
@@ -221,12 +221,12 @@ public class MbmsDownloadManager {
 
     /**
      * Create a new MbmsDownloadManager using the system default data subscription ID.
-     * See {@link #create(Context, IMbmsDownloadManagerCallback, int)}
+     * See {@link #create(Context, MbmsDownloadManagerCallback, int)}
      *
      * @hide
      */
     public static MbmsDownloadManager create(Context context,
-            IMbmsDownloadManagerCallback listener)
+            MbmsDownloadManagerCallback listener)
             throws MbmsException {
         return create(context, listener, SubscriptionManager.getDefaultSubscriptionId());
     }
@@ -247,7 +247,7 @@ public class MbmsDownloadManager {
      * @hide
      */
     public static MbmsDownloadManager create(Context context,
-            IMbmsDownloadManagerCallback listener, int subscriptionId)
+            MbmsDownloadManagerCallback listener, int subscriptionId)
             throws MbmsException {
         MbmsDownloadManager mdm = new MbmsDownloadManager(context, listener, subscriptionId);
         mdm.bindAndInitialize();
@@ -261,11 +261,22 @@ public class MbmsDownloadManager {
                     public void onServiceConnected(ComponentName name, IBinder service) {
                         IMbmsDownloadService downloadService =
                                 IMbmsDownloadService.Stub.asInterface(service);
+                        int result;
                         try {
-                            downloadService.initialize(mSubscriptionId, mCallback);
+                            result = downloadService.initialize(mSubscriptionId, mCallback);
                         } catch (RemoteException e) {
                             Log.e(LOG_TAG, "Service died before initialization");
                             return;
+                        } catch (RuntimeException e) {
+                            Log.e(LOG_TAG, "Runtime exception during initialization");
+                            mCallback.error(
+                                    MbmsException.InitializationErrors.ERROR_UNABLE_TO_INITIALIZE,
+                                    e.toString());
+                            return;
+                        }
+                        if (result != MbmsException.SUCCESS) {
+                            mCallback.error(result, "Error returned during initialization");
+                            return;
                         }
                         mService.set(downloadService);
                     }
diff --git a/telephony/java/android/telephony/MbmsStreamingManager.java b/telephony/java/android/telephony/MbmsStreamingManager.java
index 5b3503a1b163..911f83f0d8f1 100644
--- a/telephony/java/android/telephony/MbmsStreamingManager.java
+++ b/telephony/java/android/telephony/MbmsStreamingManager.java
@@ -51,10 +51,10 @@ public class MbmsStreamingManager {
     private int mSubscriptionId = INVALID_SUBSCRIPTION_ID;
 
     /** @hide */
-    private MbmsStreamingManager(Context context, MbmsStreamingManagerCallback listener,
+    private MbmsStreamingManager(Context context, MbmsStreamingManagerCallback callback,
                     int subscriptionId) {
         mContext = context;
-        mCallbackToApp = listener;
+        mCallbackToApp = callback;
         mSubscriptionId = subscriptionId;
     }
 
@@ -66,14 +66,14 @@ public class MbmsStreamingManager {
      * during the initialization or binding process.
      *
      * @param context The {@link Context} to use.
-     * @param listener A callback object on which you wish to receive results of asynchronous
+     * @param callback A callback object on which you wish to receive results of asynchronous
      *                 operations.
      * @param subscriptionId The subscription ID to use.
      */
     public static MbmsStreamingManager create(Context context,
-            MbmsStreamingManagerCallback listener, int subscriptionId)
+            MbmsStreamingManagerCallback callback, int subscriptionId)
             throws MbmsException {
-        MbmsStreamingManager manager = new MbmsStreamingManager(context, listener, subscriptionId);
+        MbmsStreamingManager manager = new MbmsStreamingManager(context, callback, subscriptionId);
         manager.bindAndInitialize();
         return manager;
     }
@@ -83,9 +83,9 @@ public class MbmsStreamingManager {
      * See {@link #create(Context, MbmsStreamingManagerCallback, int)}.
      */
     public static MbmsStreamingManager create(Context context,
-            MbmsStreamingManagerCallback listener)
+            MbmsStreamingManagerCallback callback)
             throws MbmsException {
-        return create(context, listener, SubscriptionManager.getDefaultSubscriptionId());
+        return create(context, callback, SubscriptionManager.getDefaultSubscriptionId());
     }
 
     /**
@@ -195,11 +195,22 @@ public class MbmsStreamingManager {
                     public void onServiceConnected(ComponentName name, IBinder service) {
                         IMbmsStreamingService streamingService =
                                 IMbmsStreamingService.Stub.asInterface(service);
+                        int result;
                         try {
-                            streamingService.initialize(mCallbackToApp, mSubscriptionId);
+                            result = streamingService.initialize(mCallbackToApp, mSubscriptionId);
                         } catch (RemoteException e) {
                             Log.e(LOG_TAG, "Service died before initialization");
                             return;
+                        } catch (RuntimeException e) {
+                            Log.e(LOG_TAG, "Runtime exception during initialization");
+                            mCallbackToApp.error(
+                                    MbmsException.InitializationErrors.ERROR_UNABLE_TO_INITIALIZE,
+                                    e.toString());
+                            return;
+                        }
+                        if (result != MbmsException.SUCCESS) {
+                            mCallbackToApp.error(result, "Error returned during initialization");
+                            return;
                         }
                         mService.set(streamingService);
                     }
diff --git a/telephony/java/android/telephony/mbms/MbmsDownloadReceiver.java b/telephony/java/android/telephony/mbms/MbmsDownloadReceiver.java
index 361716546fb9..339ff3985bff 100644
--- a/telephony/java/android/telephony/mbms/MbmsDownloadReceiver.java
+++ b/telephony/java/android/telephony/mbms/MbmsDownloadReceiver.java
@@ -356,7 +356,7 @@ public class MbmsDownloadReceiver extends BroadcastReceiver {
                 intent.getParcelableExtra(MbmsDownloadManager.EXTRA_SERVICE_INFO);
         File tempFileDir = MbmsUtils.getEmbmsTempFileDirForService(context,
                 serviceInfo.getServiceId());
-        List<Uri> filesInUse =
+        final List<Uri> filesInUse =
                 intent.getParcelableArrayListExtra(MbmsDownloadManager.EXTRA_TEMP_FILES_IN_USE);
         File[] filesToDelete = tempFileDir.listFiles(new FileFilter() {
             @Override
diff --git a/telephony/java/android/telephony/mbms/StreamingService.java b/telephony/java/android/telephony/mbms/StreamingService.java
index 1a6418969a90..c49f8a980cbb 100644
--- a/telephony/java/android/telephony/mbms/StreamingService.java
+++ b/telephony/java/android/telephony/mbms/StreamingService.java
@@ -50,10 +50,15 @@ 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_LEFT_MBMS_BROADCAST_AREA})
+            REASON_LEFT_MBMS_BROADCAST_AREA, REASON_NONE})
     public @interface StreamingStateChangeReason {}
 
     /**
+     * Indicates that the middleware does not have a reason to provide for the state change.
+     */
+    public static final int REASON_NONE = 0;
+
+    /**
      * State changed due to a call to {@link #stopStreaming()} or
      * {@link android.telephony.MbmsStreamingManager#startStreaming(StreamingServiceInfo, StreamingServiceCallback)}
      */
@@ -167,7 +172,7 @@ public class StreamingService {
      *
      * 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}
+     * May also throw an {@link IllegalStateException}
      */
     public void dispose() throws MbmsException {
         if (mService == null) {
@@ -179,6 +184,8 @@ public class StreamingService {
         } catch (RemoteException e) {
             Log.w(LOG_TAG, "Remote process died");
             throw new MbmsException(MbmsException.ERROR_MIDDLEWARE_LOST);
+        } catch (IllegalArgumentException e) {
+            throw new IllegalStateException("StreamingService state inconsistent with middleware");
         } finally {
             mService = null;
         }
diff --git a/telephony/java/android/telephony/mbms/vendor/IMbmsDownloadService.aidl b/telephony/java/android/telephony/mbms/vendor/IMbmsDownloadService.aidl
index 0a76f322bbbb..dfcc5f7c8793 100755
--- a/telephony/java/android/telephony/mbms/vendor/IMbmsDownloadService.aidl
+++ b/telephony/java/android/telephony/mbms/vendor/IMbmsDownloadService.aidl
@@ -28,7 +28,7 @@ import android.telephony.mbms.IDownloadProgressListener;
  */
 interface IMbmsDownloadService
 {
-    void initialize(int subId, IMbmsDownloadManagerCallback listener);
+    int initialize(int subId, IMbmsDownloadManagerCallback listener);
 
     int getFileServices(int subId, in List<String> serviceClasses);
 
diff --git a/telephony/java/android/telephony/mbms/vendor/IMbmsStreamingService.aidl b/telephony/java/android/telephony/mbms/vendor/IMbmsStreamingService.aidl
index 04a53cbe0d00..4dd42924ab05 100755
--- a/telephony/java/android/telephony/mbms/vendor/IMbmsStreamingService.aidl
+++ b/telephony/java/android/telephony/mbms/vendor/IMbmsStreamingService.aidl
@@ -26,7 +26,7 @@ import android.telephony.mbms.StreamingServiceInfo;
  */
 interface IMbmsStreamingService
 {
-    void initialize(IMbmsStreamingManagerCallback listener, int subId);
+    int 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 d725d9f633ce..edd585808580 100644
--- a/telephony/java/android/telephony/mbms/vendor/MbmsDownloadServiceBase.java
+++ b/telephony/java/android/telephony/mbms/vendor/MbmsDownloadServiceBase.java
@@ -36,16 +36,21 @@ public class MbmsDownloadServiceBase extends IMbmsDownloadService.Stub {
     /**
      * Initialize the download service for this app and subId, registering the listener.
      *
-     * 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.
+     * May throw an {@link IllegalArgumentException} or an {@link IllegalStateException}, which
+     * will be intercepted and passed to the app as
+     * {@link android.telephony.mbms.MbmsException.InitializationErrors#ERROR_UNABLE_TO_INITIALIZE}
+     *
+     * May return any value from {@link android.telephony.mbms.MbmsException.InitializationErrors}
+     * or {@link MbmsException#SUCCESS}. Non-successful error codes will be passed to the app via
+     * {@link IMbmsDownloadManagerCallback#error(int, String)}.
      *
      * @param listener The callback to use to communicate with the app.
      * @param subscriptionId The subscription ID to use.
      */
     @Override
-    public void initialize(int subscriptionId,
+    public int initialize(int subscriptionId,
             IMbmsDownloadManagerCallback listener) 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 f072c46171d6..585d5b9610b7 100644
--- a/telephony/java/android/telephony/mbms/vendor/MbmsStreamingServiceBase.java
+++ b/telephony/java/android/telephony/mbms/vendor/MbmsStreamingServiceBase.java
@@ -33,17 +33,21 @@ public class MbmsStreamingServiceBase extends IMbmsStreamingService.Stub {
     /**
      * Initialize streaming service for this app and subId, registering the listener.
      *
-     * 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.
+     * May throw an {@link IllegalArgumentException} or an {@link IllegalStateException}, which
+     * will be intercepted and passed to the app as
+     * {@link android.telephony.mbms.MbmsException.InitializationErrors#ERROR_UNABLE_TO_INITIALIZE}
+     *
+     * May return any value from {@link android.telephony.mbms.MbmsException.InitializationErrors}
+     * or {@link MbmsException#SUCCESS}. Non-successful error codes will be passed to the app via
+     * {@link IMbmsStreamingManagerCallback#error(int, String)}.
      *
      * @param listener The callback to use to communicate with the app.
      * @param subscriptionId The subscription ID to use.
      */
     @Override
-    public void initialize(IMbmsStreamingManagerCallback listener, int subscriptionId)
+    public int initialize(IMbmsStreamingManagerCallback listener, int subscriptionId)
             throws RemoteException {
-        return;
+        return 0;
     }
 
     /**