Merge "Add Error specifiers to the API."

am: 4c4a55a67b

Change-Id: Ia720a230e0f7f7070ca7194dbcfce294a66a3574

telephony/java/android/telephony/MbmsDownloadManager.java

@@ -35,35 +35,29 @@ public class MbmsDownloadManager {
     private int mSubId = INVALID_SUBSCRIPTION_ID;
 
     /**
-     * should use createManager to create/initialize a copy
+     * Create a new MbmsDownloadManager using the system default data subscription ID.
+     *
+     * Note that this call will bind a remote service and that may take a bit.  This
+     * may throw an Illegal ArgumentException or RemoteException.
+     *
      * @hide
      */
-    public MbmsDownloadManager(Context context) {
+    public MbmsDownloadManager(Context context, IMbmsDownloadManagerListener listener,
+            String downloadAppName) {
         mContext = context;
     }
 
-    public static MbmsDownloadManager createManager(Context context,
-            IMbmsDownloadManagerListener listener, String downloadAppName) {
-//        MbmsDownloadManager mdm = context.getSystemService(Context.MBMS_DOWNLOAD_SERVICE);
-//        if (mdm == null) return mdm;
-//        mdm.initialize(listener, downloadAppName,
-//                SubscriptionManager.getDefaultSubscriptionId());
-//        return mdm;
-        return null;
-    }
-
-    public static MbmsDownloadManager createManager(Context context,
-            IMbmsDownloadManagerListener listener, String downloadAppName, int subId) {
-//        MbmsDownloadManager mdm = context.getSystemService(Context.MBMS_DOWNLOAD_SERVICE);
-//        if (mdm == null) return mdm;
-//        mdm.initialize(listener, downloadAppName, subId);
-//        return mdm;
-        return null;
-    }
-
-    private void initialize(IMbmsDownloadManagerListener listener, String downloadAppName,
-            int subId) {
-        // assert all empty and set
+    /**
+     * Create a new MbmsDownloadManager using the given subscription ID.
+     *
+     * Note that this call will bind a remote service and that may take a bit.  This
+     * may throw an Illegal ArgumentException or RemoteException.
+     *
+     * @hide
+     */
+    public MbmsDownloadManager(Context context, IMbmsDownloadManagerListener listener,
+            String downloadAppName, int subId) {
+        mContext = context;
     }
 
     /**
@@ -71,6 +65,19 @@ public class MbmsDownloadManager {
      * They may occur at times far in the future.
      * servicesClasses lets the app filter on types of files and is opaque data between
      *     the app and the carrier
+     *
+     * Multiple calls replace trhe list of serviceClasses of interest.
+     *
+     * May throw an IllegalArgumentException or RemoteException.
+     *
+     * Synchronous responses include
+     * <li>SUCCESS</li>
+     * <li>ERROR_MSDC_CONCURRENT_SERVICE_LIMIT_REACHED</li>
+     *
+     * Asynchronous errors through the listener include any of the errors except
+     * <li>ERROR_MSDC_UNABLE_TO_)START_SERVICE</li>
+     * <li>ERROR_MSDC_INVALID_SERVICE_ID</li>
+     * <li>ERROR_MSDC_END_OF_SESSION</li>
      */
     public int getFileServices(List<String> serviceClasses) {
         return 0;
@@ -106,15 +113,39 @@ public class MbmsDownloadManager {
      *     of a currently occuring download.  Note this can only run while the calling app
      *     is running, so future downloads will simply result in resultIntents being sent
      *     for completed or errored-out downloads.  A NULL indicates no callbacks are needed.
+     *
+     * May throw an IllegalArgumentException or RemoteExcpetion.
+     *
+     * Asynchronous errors through the listener include any of the errors
      */
     public DownloadRequest download(DownloadRequest downloadRequest, DownloadListener listener) {
         return null;
     }
 
+    /**
+     * 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>
+     */
     public List<DownloadRequest> listPendingDownloads() {
         return null;
     }
 
+    /**
+     * Attempts to cancel the specified DownloadRequest.
+     *
+     * May throw a RemoteException.
+     *
+     * Synchronous responses may include
+     * <li>SUCCESS</li>
+     * <li>ERROR_MSDC_CONCURRENT_SERVICE_LIMIT_REACHED</li>
+     * <li>ERROR_MSDC_UNKNOWN_REQUEST</li>
+     */
     public int cancelDownload(DownloadRequest downloadRequest) {
         return 0;
     }
@@ -127,6 +158,10 @@ public class MbmsDownloadManager {
      * Future downloads include counts of files with pending repair operations, counts of
      * files with future downloads and indication of scheduled download times with unknown
      * file details.
+     *
+     * May throw an IllegalArgumentException or RemoteException.
+     *
+     * If the DownloadRequest is unknown the results will be null.
      */
     public DownloadStatus getDownloadStatus(DownloadRequest downloadRequest) {
         return null;
@@ -140,8 +175,15 @@ public class MbmsDownloadManager {
      * 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.
+     *
+     * May throw an IllegalArgumentException or RemoteException.
+     *
+     * <li>SUCCESS</li>
+     * <li>ERROR_MSDC_CONCURRENT_SERVICE_LIMIT_REACHED</li>
+     * <li>ERROR_MSDC_UNKNOWN_REQUEST</li>
      */
-    public void resetDownloadKnowledge(DownloadRequest downloadRequest) {
+    public int resetDownloadKnowledge(DownloadRequest downloadRequest) {
+        return 0;
     }
 
     public void dispose() {

telephony/java/android/telephony/MbmsStreamingManager.java

@@ -39,7 +39,7 @@ public class MbmsStreamingManager {
      * Create a new MbmsStreamingManager using the system default data subscription ID.
      *
      * Note that this call will bind a remote service and that may take a bit.  This
-     * may throw an IllegalArgumentException.
+     * may throw an IllegalArgumentException or RemoteException.
      */
     public MbmsStreamingManager(Context context, IMbmsStreamingManagerListener listener,
             String streamingAppName) {
@@ -47,10 +47,10 @@ public class MbmsStreamingManager {
     }
 
     /**
-     * Create a new MbmsStreamingManager using the give subscription ID.
+     * Create a new MbmsStreamingManager using the given subscription ID.
      *
      * Note that this call will bind a remote service and that may take a bit.  This
-     * may throw an IllegalArgumentException.
+     * may throw an IllegalArgumentException or RemoteException.
      */
     public MbmsStreamingManager(Context context, IMbmsStreamingManagerListener listener,
                     String streamingAppName, int subId) {
@@ -72,10 +72,17 @@ public class MbmsStreamingManager {
      * the app and the carrier.
      *
      * Multiple calls replace the list of serviceClasses of interest.
-     * The return value is a success/error-code with the following possible values:
+     *
+     * May throw an IllegalArgumentException or RemoteException.
+     *
+     * Synchronous responses include
      * <li>SUCCESS</li>
-     * <li>NO_MIDDLEWARE</li>
-     * <li>QUEUE_LIMIT</li>
+     * <li>ERROR_MSDC_CONCURRENT_SERVICE_LIMIT_REACHED</li>
+     *
+     * Asynchronous errors through the listener include any of the errors except
+     * <li>ERROR_MSDC_UNABLE_TO_)START_SERVICE</li>
+     * <li>ERROR_MSDC_INVALID_SERVICE_ID</li>
+     * <li>ERROR_MSDC_END_OF_SESSION</li>
      */
     public int getStreamingServices(List<String> classList) {
         return 0;
@@ -85,6 +92,9 @@ public class MbmsStreamingManager {
      * Starts streaming a requested service, reporting status to the indicated listener.
      * Returns an object used to control that stream.
      *
+     * May throw an IllegalArgumentException or RemoteException.
+     *
+     * Asynchronous errors through the listener include any of the errors
      */
     public StreamingService startStreaming(StreamingServiceInfo serviceInfo,
             IStreamingServiceListener listener) {
@@ -96,10 +106,17 @@ public class MbmsStreamingManager {
      * on this given subId.  Results are returned asynchronously through the previously
      * registered callback.
      *
+     * May throw a RemoteException.
+     *
      * The return value is a success/error-code with the following possible values:
      * <li>SUCCESS</li>
-     * <li>NO_MIDDLEWARE</li>
-     * <li>QUEU_LIMIT</li>
+     * <li>ERROR_MSDC_CONCURRENT_SERVICE_LIMIT_REACHED</li>
+     *
+     * 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>
+     *
      */
     public int getActiveStreamingServices() {
         return 0;

telephony/java/android/telephony/mbms/StreamingService.java

@@ -37,7 +37,9 @@ public class StreamingService {
     }
 
     /**
-     * Retreive the Uri used to play this stream
+     * Retreive the Uri used to play this stream.
+     *
+     * This may throw a RemoteException.
      */
     public Uri getPlaybackUri() {
         return null;
@@ -52,6 +54,8 @@ public class StreamingService {
 
     /**
      * Retreive the current state of this stream.
+     *
+     * This may throw a RemoteException.
      */
     public int getState() {
         return STATE_STOPPED;
@@ -59,12 +63,19 @@ public class StreamingService {
 
     /**
      * Stop streaming this service.  Terminal.
+     *
+     * This may throw a RemoteException.
      */
     public void stopStreaming() {
     }
 
     /**
      * Switch this stream to a different service.  Used for smooth transitions.
+     *
+     * This may throw a RemoteException.
+     *
+     * Asynchronous errors through the listener include any of the errors except
+     * <li>ERROR_MSDC_UNABLE_TO_INITIALIZE</li>
      */
     public void switchStream(StreamingServiceInfo streamingServiceInfo) {
     }