New external storage APIs.

This implements the spec for external storage organization, and
properly reflects how the media scanner organizes the files it finds.

Also includes package manager support for removing app private
files from external storage when the application is uninstalled.

For the new APIs and paths, the main place to look is Environment
and Context.

1 files changed, 81 insertions, 5 deletions

diff --git a/media/java/android/media/MediaScannerConnection.java b/media/java/android/media/MediaScannerConnection.java
index d2596b8..65b67a1 100644
--- a/media/java/android/media/MediaScannerConnection.java
+++ b/media/java/android/media/MediaScannerConnection.java
@@ -57,17 +57,32 @@ public class MediaScannerConnection implements ServiceConnection {
     };
 
     /**
+     * Interface for notifying clients of the result of scanning a
+     * requested media file.
+     */
+    public interface ScanResultListener {
+        /**
+         * Called to notify the client when the media scanner has finished
+         * scanning a file.
+         * @param path the path to the file that has been scanned.
+         * @param uri the Uri for the file if the scanning operation succeeded 
+         * and the file was added to the media database, or null if scanning failed. 
+         */    
+        public void onScanCompleted(String path, Uri uri);
+    }
+    
+    /**
      * An interface for notifying clients of MediaScannerConnection
      * when a connection to the MediaScanner service has been established
      * and when the scanning of a file has completed.
      */
-    public interface MediaScannerConnectionClient {
+    public interface MediaScannerConnectionClient extends ScanResultListener {
         /**
          * Called to notify the client when a connection to the 
          * MediaScanner service has been established.
          */    
         public void onMediaScannerConnected();
-
+        
         /**
          * Called to notify the client when the media scanner has finished
          * scanning a file.
@@ -136,11 +151,12 @@ public class MediaScannerConnection implements ServiceConnection {
 
     /**
      * Requests the media scanner to scan a file.
+     * Success or failure of the scanning operation cannot be determined until 
+     * {@link MediaScannerConnectionClient#onScanCompleted(String, Uri)} is called.
+     * 
      * @param path the path to the file to be scanned.
      * @param mimeType  an optional mimeType for the file.
      * If mimeType is null, then the mimeType will be inferred from the file extension.
-     * Success or failure of the scanning operation cannot be determined until 
-     * {@link MediaScannerConnectionClient#onScanCompleted(String, Uri)} is called.
      */
      public void scanFile(String path, String mimeType) {
         synchronized (this) {
@@ -159,7 +175,67 @@ public class MediaScannerConnection implements ServiceConnection {
             }
         }
     }
-
+    
+    static class ClientProxy implements MediaScannerConnectionClient {
+        final String[] mPaths;
+        final String[] mMimeTypes;
+        final ScanResultListener mClient;
+        MediaScannerConnection mConnection;
+        int mNextPath;
+        
+        ClientProxy(String[] paths, String[] mimeTypes, ScanResultListener client) {
+            mPaths = paths;
+            mMimeTypes = mimeTypes;
+            mClient = client;
+        }
+        
+        public void onMediaScannerConnected() {
+            scanNextPath();
+        }
+        
+        public void onScanCompleted(String path, Uri uri) {
+            if (mClient != null) {
+                mClient.onScanCompleted(path, uri);
+            }
+            scanNextPath();
+        }
+        
+        void scanNextPath() {
+            if (mNextPath >= mPaths.length) {
+                mConnection.disconnect();
+                return;
+            }
+            String mimeType = mMimeTypes != null ? mMimeTypes[mNextPath] : null;
+            mConnection.scanFile(mPaths[mNextPath], mimeType);
+            mNextPath++;
+        }
+    }
+    
+    /**
+     * Convenience for constructing a {@link MediaScannerConnection}, calling
+     * {@link #connect} on it, and calling {@link #scanFile} with the given
+     * <var>path</var> and <var>mimeType</var> when the connection is
+     * established.
+     * @param context The caller's Context, required for establishing a connection to
+     * the media scanner service.
+     * Success or failure of the scanning operation cannot be determined until 
+     * {@link MediaScannerConnectionClient#onScanCompleted(String, Uri)} is called.
+     * @param paths Array of paths to be scanned.
+     * @param mimeTypes Optional array of MIME types for each path.
+     * If mimeType is null, then the mimeType will be inferred from the file extension.
+     * @param callback Optional callback through which you can receive the
+     * scanned URI and MIME type; If null, the file will be scanned but
+     * you will not get a result back.
+     * @see scanFile(String, String)
+     */
+    public static void scanFile(Context context, String[] paths, String[] mimeTypes,
+            ScanResultListener callback) {
+        ClientProxy client = new ClientProxy(paths, mimeTypes, callback);
+        MediaScannerConnection connection = new MediaScannerConnection(context, client);
+        client.mConnection = connection;
+        connection.connect();
+    }
+     
     /**
      * Part of the ServiceConnection interface.  Do not call.
      */