Merge "Unhide Content{Resolver,Provider}.call()" into honeycomb

4 files changed, 104 insertions, 28 deletions

diff --git a/api/current.xml b/api/current.xml
index df9f8518ebab..6053e1b3ddd0 100644
--- a/api/current.xml
+++ b/api/current.xml
@@ -44998,6 +44998,23 @@
 <parameter name="values" type="android.content.ContentValues[]">
 </parameter>
 </method>
+<method name="call"
+ return="android.os.Bundle"
+ abstract="false"
+ native="false"
+ synchronized="false"
+ static="false"
+ final="false"
+ deprecated="not deprecated"
+ visibility="public"
+>
+<parameter name="method" type="java.lang.String">
+</parameter>
+<parameter name="arg" type="java.lang.String">
+</parameter>
+<parameter name="extras" type="android.os.Bundle">
+</parameter>
+</method>
 <method name="delete"
  return="int"
  abstract="true"
@@ -46214,6 +46231,25 @@
 <parameter name="values" type="android.content.ContentValues[]">
 </parameter>
 </method>
+<method name="call"
+ return="android.os.Bundle"
+ abstract="false"
+ native="false"
+ synchronized="false"
+ static="false"
+ final="true"
+ deprecated="not deprecated"
+ visibility="public"
+>
+<parameter name="uri" type="android.net.Uri">
+</parameter>
+<parameter name="method" type="java.lang.String">
+</parameter>
+<parameter name="arg" type="java.lang.String">
+</parameter>
+<parameter name="extras" type="android.os.Bundle">
+</parameter>
+</method>
 <method name="cancelSync"
  return="void"
  abstract="false"
diff --git a/core/java/android/content/ContentProvider.java b/core/java/android/content/ContentProvider.java
index 6bb32c1c943b..5467a30bb135 100644
--- a/core/java/android/content/ContentProvider.java
+++ b/core/java/android/content/ContentProvider.java
@@ -247,11 +247,8 @@ public abstract class ContentProvider implements ComponentCallbacks {
             return ContentProvider.this.openAssetFile(uri, mode);
         }
 
-        /**
-         * @hide
-         */
-        public Bundle call(String method, String request, Bundle args) {
-            return ContentProvider.this.call(method, request, args);
+        public Bundle call(String method, String arg, Bundle extras) {
+            return ContentProvider.this.call(method, arg, extras);
         }
 
         @Override
@@ -987,16 +984,17 @@ public abstract class ContentProvider implements ComponentCallbacks {
     }
 
     /**
-     * @hide -- until interface has proven itself
-     *
      * Call a provider-defined method.  This can be used to implement
-     * interfaces that are cheaper than using a Cursor.
+     * interfaces that are cheaper and/or unnatural for a table-like
+     * model.
      *
-     * @param method Method name to call.  Opaque to framework.
-     * @param request Nullable String argument passed to method.
-     * @param args Nullable Bundle argument passed to method.
+     * @param method method name to call.  Opaque to framework, but should not be null.
+     * @param arg provider-defined String argument.  May be null.
+     * @param extras provider-defined Bundle argument.  May be null.
+     * @return provider-defined return value.  May be null.  Null is also
+     *   the default for providers which don't implement any call methods.
      */
-    public Bundle call(String method, String request, Bundle args) {
+    public Bundle call(String method, String arg, Bundle extras) {
         return null;
     }
 
diff --git a/core/java/android/content/ContentResolver.java b/core/java/android/content/ContentResolver.java
index d03422922bc9..da518c29501d 100644
--- a/core/java/android/content/ContentResolver.java
+++ b/core/java/android/content/ContentResolver.java
@@ -216,6 +216,8 @@ public abstract class ContentResolver {
             String type = ActivityManagerNative.getDefault().getProviderMimeType(url);
             return type;
         } catch (RemoteException e) {
+            // Arbitrary and not worth documenting, as Activity
+            // Manager will kill this process shortly anyway.
             return null;
         } catch (java.lang.Exception e) {
             Log.w(TAG, "Failed to get type for: " + url + " (" + e.getMessage() + ")");
@@ -249,10 +251,12 @@ public abstract class ContentResolver {
         try {
             return provider.getStreamTypes(url, mimeTypeFilter);
         } catch (RemoteException e) {
+            // Arbitrary and not worth documenting, as Activity
+            // Manager will kill this process shortly anyway.
             return null;
         } finally {
-			releaseProvider(provider);
-		}
+            releaseProvider(provider);
+        }
     }
 
     /**
@@ -308,8 +312,11 @@ public abstract class ContentResolver {
             return new CursorWrapperInner(qCursor, provider);
         } catch (RemoteException e) {
             releaseProvider(provider);
+
+            // Arbitrary and not worth documenting, as Activity
+            // Manager will kill this process shortly anyway.
             return null;
-        } catch(RuntimeException e) {
+        } catch (RuntimeException e) {
             releaseProvider(provider);
             throw e;
         }
@@ -539,6 +546,8 @@ public abstract class ContentResolver {
                     return new AssetFileDescriptor(pfd, fd.getStartOffset(),
                             fd.getDeclaredLength());
                 } catch (RemoteException e) {
+                    // Somewhat pointless, as Activity Manager will kill this
+                    // process shortly anyway if the depdendent ContentProvider dies.
                     throw new FileNotFoundException("Dead content provider: " + uri);
                 } catch (FileNotFoundException e) {
                     throw e;
@@ -714,6 +723,8 @@ public abstract class ContentResolver {
             maybeLogUpdateToEventLog(durationMillis, url, "insert", null /* where */);
             return createdRow;
         } catch (RemoteException e) {
+            // Arbitrary and not worth documenting, as Activity
+            // Manager will kill this process shortly anyway.
             return null;
         } finally {
             releaseProvider(provider);
@@ -773,6 +784,8 @@ public abstract class ContentResolver {
             maybeLogUpdateToEventLog(durationMillis, url, "bulkinsert", null /* where */);
             return rowsCreated;
         } catch (RemoteException e) {
+            // Arbitrary and not worth documenting, as Activity
+            // Manager will kill this process shortly anyway.
             return 0;
         } finally {
             releaseProvider(provider);
@@ -802,6 +815,8 @@ public abstract class ContentResolver {
             maybeLogUpdateToEventLog(durationMillis, url, "delete", where);
             return rowsDeleted;
         } catch (RemoteException e) {
+            // Arbitrary and not worth documenting, as Activity
+            // Manager will kill this process shortly anyway.
             return -1;
         } finally {
             releaseProvider(provider);
@@ -818,7 +833,7 @@ public abstract class ContentResolver {
                      A null value will remove an existing field value.
      * @param where A filter to apply to rows before updating, formatted as an SQL WHERE clause
                     (excluding the WHERE itself).
-     * @return The number of rows updated.
+     * @return the number of rows updated.
      * @throws NullPointerException if uri or values are null
      */
     public final int update(Uri uri, ContentValues values, String where,
@@ -834,6 +849,8 @@ public abstract class ContentResolver {
             maybeLogUpdateToEventLog(durationMillis, uri, "update", where);
             return rowsUpdated;
         } catch (RemoteException e) {
+            // Arbitrary and not worth documenting, as Activity
+            // Manager will kill this process shortly anyway.
             return -1;
         } finally {
             releaseProvider(provider);
@@ -841,6 +858,42 @@ public abstract class ContentResolver {
     }
 
     /**
+     * Call an provider-defined method.  This can be used to implement
+     * read or write interfaces which are cheaper than using a Cursor and/or
+     * do not fit into the traditional table model.
+     *
+     * @param method provider-defined method name to call.  Opaque to
+     *   framework, but must be non-null.
+     * @param arg provider-defined String argument.  May be null.
+     * @param extras provider-defined Bundle argument.  May be null.
+     * @return a result Bundle, possibly null.  Will be null if the ContentProvider
+     *   does not implement call.
+     * @throws NullPointerException if uri or method is null
+     * @throws IllegalArgumentException if uri is not known
+     */
+    public final Bundle call(Uri uri, String method, String arg, Bundle extras) {
+        if (uri == null) {
+            throw new NullPointerException("uri == null");
+        }
+        if (method == null) {
+            throw new NullPointerException("method == null");
+        }
+        IContentProvider provider = acquireProvider(uri);
+        if (provider == null) {
+            throw new IllegalArgumentException("Unknown URI " + uri);
+        }
+        try {
+            return provider.call(method, arg, extras);
+        } catch (RemoteException e) {
+            // Arbitrary and not worth documenting, as Activity
+            // Manager will kill this process shortly anyway.
+            return null;
+        } finally {
+            releaseProvider(provider);
+        }
+    }
+
+    /**
      * Returns the content provider for the given content URI.
      *
      * @param uri The URI to a content provider
diff --git a/core/java/android/content/IContentProvider.java b/core/java/android/content/IContentProvider.java
index 8f122ce8f39d..72bc9c2f69f9 100644
--- a/core/java/android/content/IContentProvider.java
+++ b/core/java/android/content/IContentProvider.java
@@ -59,18 +59,7 @@ public interface IContentProvider extends IInterface {
             throws RemoteException, FileNotFoundException;
     public ContentProviderResult[] applyBatch(ArrayList<ContentProviderOperation> operations)
             throws RemoteException, OperationApplicationException;
-
-    /**
-     * @hide -- until interface has proven itself
-     *
-     * Call an provider-defined method.  This can be used to implement
-     * interfaces that are cheaper than using a Cursor.
-     *
-     * @param method Method name to call.  Opaque to framework.
-     * @param request Nullable String argument passed to method.
-     * @param args Nullable Bundle argument passed to method.
-     */
-    public Bundle call(String method, String request, Bundle args) throws RemoteException;
+    public Bundle call(String method, String arg, Bundle extras) throws RemoteException;
 
     // Data interchange.
     public String[] getStreamTypes(Uri url, String mimeTypeFilter) throws RemoteException;