[path_provider] Android: Support multiple external storage options

packages/path_provider/CHANGELOG.md

@@ -1,3 +1,10 @@
+## 1.4.0
+
+* Support retrieving storage paths on Android devices with multiple external
+  storage options. This adds a new class `AndroidEnvironment` that shadows the
+  directory names from Androids `android.os.Environment` class.
+* Fixes `getLibraryDirectory` semantics & tests.
+
 ## 1.3.1
 
 * Define clang module for iOS.

packages/path_provider/android/build.gradle

@@ -45,3 +45,8 @@ android {
         disable 'InvalidPackage'
     }
 }
+
+dependencies {
+    implementation 'androidx.annotation:annotation:1.1.0'
+    testImplementation 'junit:junit:4.12'
+}

packages/path_provider/android/src/main/java/io/flutter/plugins/pathprovider/PathProviderPlugin.java

@@ -4,15 +4,21 @@
 
 package io.flutter.plugins.pathprovider;
 
+import android.os.Build.VERSION;
+import android.os.Build.VERSION_CODES;
+import androidx.annotation.NonNull;
 import io.flutter.plugin.common.MethodCall;
 import io.flutter.plugin.common.MethodChannel;
 import io.flutter.plugin.common.MethodChannel.MethodCallHandler;
 import io.flutter.plugin.common.MethodChannel.Result;
 import io.flutter.plugin.common.PluginRegistry.Registrar;
 import io.flutter.util.PathUtils;
 import java.io.File;
+import java.util.ArrayList;
+import java.util.List;
 
 public class PathProviderPlugin implements MethodCallHandler {
+
   private final Registrar mRegistrar;
 
   public static void registerWith(Registrar registrar) {
@@ -27,7 +33,7 @@ private PathProviderPlugin(Registrar registrar) {
   }
 
   @Override
-  public void onMethodCall(MethodCall call, Result result) {
+  public void onMethodCall(MethodCall call, @NonNull Result result) {
     switch (call.method) {
       case "getTemporaryDirectory":
         result.success(getPathProviderTemporaryDirectory());
@@ -38,6 +44,14 @@ public void onMethodCall(MethodCall call, Result result) {
       case "getStorageDirectory":
         result.success(getPathProviderStorageDirectory());
         break;
+      case "getExternalCacheDirectories":
+        result.success(getPathProviderExternalCacheDirectories());
+        break;
+      case "getExternalStorageDirectories":
+        final Integer type = call.argument("type");
+        final String directoryName = StorageDirectoryMapper.androidType(type);
+        result.success(getPathProviderExternalStorageDirectories(directoryName));
+        break;
       case "getApplicationSupportDirectory":
         result.success(getApplicationSupportDirectory());
         break;
@@ -65,4 +79,42 @@ private String getPathProviderStorageDirectory() {
     }
     return dir.getAbsolutePath();
   }
+
+  private List<String> getPathProviderExternalCacheDirectories() {
+    final List<String> paths = new ArrayList<>();
+
+    if (VERSION.SDK_INT >= VERSION_CODES.KITKAT) {
+      for (File dir : mRegistrar.context().getExternalCacheDirs()) {
+        if (dir != null) {
+          paths.add(dir.getAbsolutePath());
+        }
+      }
+    } else {
+      File dir = mRegistrar.context().getExternalCacheDir();
+      if (dir != null) {
+        paths.add(dir.getAbsolutePath());
+      }
+    }
+
+    return paths;
+  }
+
+  private List<String> getPathProviderExternalStorageDirectories(String type) {
+    final List<String> paths = new ArrayList<>();
+
+    if (VERSION.SDK_INT >= VERSION_CODES.KITKAT) {
+      for (File dir : mRegistrar.context().getExternalFilesDirs(type)) {
+        if (dir != null) {
+          paths.add(dir.getAbsolutePath());
+        }
+      }
+    } else {
+      File dir = mRegistrar.context().getExternalFilesDir(type);
+      if (dir != null) {
+        paths.add(dir.getAbsolutePath());
+      }
+    }
+
+    return paths;
+  }
 }

packages/path_provider/android/src/main/java/io/flutter/plugins/pathprovider/StorageDirectoryMapper.java

@@ -0,0 +1,51 @@
+package io.flutter.plugins.pathprovider;
+
+import android.os.Build.VERSION;
+import android.os.Build.VERSION_CODES;
+import android.os.Environment;
+
+/** Helps to map the Dart `StorageDirectory` enum to a Android system constant. */
+class StorageDirectoryMapper {
+
+  /**
+   * Return a Android Environment constant for a Dart Index.
+   *
+   * @return The correct Android Environment constant or null, if the index is null.
+   * @throws IllegalArgumentException If `dartIndex` is not null but also not matches any known
+   *     index.
+   */
+  static String androidType(Integer dartIndex) throws IllegalArgumentException {
+    if (dartIndex == null) {
+      return null;
+    }
+
+    switch (dartIndex) {
+      case 0:
+        return Environment.DIRECTORY_MUSIC;
+      case 1:
+        return Environment.DIRECTORY_PODCASTS;
+      case 2:
+        return Environment.DIRECTORY_RINGTONES;
+      case 3:
+        return Environment.DIRECTORY_ALARMS;
+      case 4:
+        return Environment.DIRECTORY_NOTIFICATIONS;
+      case 5:
+        return Environment.DIRECTORY_PICTURES;
+      case 6:
+        return Environment.DIRECTORY_MOVIES;
+      case 7:
+        return Environment.DIRECTORY_DOWNLOADS;
+      case 8:
+        return Environment.DIRECTORY_DCIM;
+      case 9:
+        if (VERSION.SDK_INT >= VERSION_CODES.KITKAT) {
+          return Environment.DIRECTORY_DOCUMENTS;
+        } else {
+          throw new IllegalArgumentException("Documents directory is unsupported.");
+        }
+      default:
+        throw new IllegalArgumentException("Unknown index: " + dartIndex);
+    }
+  }
+}

packages/path_provider/android/src/test/java/io/flutter/plugins/pathprovider/StorageDirectoryMapperTest.java

@@ -0,0 +1,40 @@
+package io.flutter.plugins.pathprovider;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertNull;
+import static org.junit.Assert.fail;
+
+import android.os.Environment;
+import org.junit.Test;
+
+public class StorageDirectoryMapperTest {
+
+  @org.junit.Test
+  public void testAndroidType_null() {
+    assertNull(StorageDirectoryMapper.androidType(null));
+  }
+
+  @org.junit.Test
+  public void testAndroidType_valid() {
+    assertEquals(Environment.DIRECTORY_MUSIC, StorageDirectoryMapper.androidType(0));
+    assertEquals(Environment.DIRECTORY_PODCASTS, StorageDirectoryMapper.androidType(1));
+    assertEquals(Environment.DIRECTORY_MUSIC, StorageDirectoryMapper.androidType(2));
+    assertEquals(Environment.DIRECTORY_RINGTONES, StorageDirectoryMapper.androidType(3));
+    assertEquals(Environment.DIRECTORY_ALARMS, StorageDirectoryMapper.androidType(4));
+    assertEquals(Environment.DIRECTORY_NOTIFICATIONS, StorageDirectoryMapper.androidType(5));
+    assertEquals(Environment.DIRECTORY_PICTURES, StorageDirectoryMapper.androidType(6));
+    assertEquals(Environment.DIRECTORY_MOVIES, StorageDirectoryMapper.androidType(7));
+    assertEquals(Environment.DIRECTORY_DOWNLOADS, StorageDirectoryMapper.androidType(8));
+    assertEquals(Environment.DIRECTORY_DCIM, StorageDirectoryMapper.androidType(9));
+  }
+
+  @Test
+  public void testAndroidType_invalid() {
+    try {
+      assertEquals(Environment.DIRECTORY_DCIM, StorageDirectoryMapper.androidType(10));
+      fail();
+    } catch (IllegalArgumentException e) {
+      assertEquals("Unknown index: " + 10, e.getMessage());
+    }
+  }
+}

packages/path_provider/example/android/gradle.properties

@@ -1 +1,2 @@
 org.gradle.jvmargs=-Xmx1536M
+android.enableR8=true

packages/path_provider/example/lib/main.dart

@@ -39,6 +39,8 @@ class _MyHomePageState extends State<MyHomePage> {
   Future<Directory> _appLibraryDirectory;
   Future<Directory> _appDocumentsDirectory;
   Future<Directory> _externalDocumentsDirectory;
+  Future<List<Directory>> _externalStorageDirectories;
+  Future<List<Directory>> _externalCacheDirectories;
 
   void _requestTempDirectory() {
     setState(() {
@@ -61,6 +63,23 @@ class _MyHomePageState extends State<MyHomePage> {
     return Padding(padding: const EdgeInsets.all(16.0), child: text);
   }
 
+  Widget _buildDirectories(
+      BuildContext context, AsyncSnapshot<List<Directory>> snapshot) {
+    Text text = const Text('');
+    if (snapshot.connectionState == ConnectionState.done) {
+      if (snapshot.hasError) {
+        text = Text('Error: ${snapshot.error}');
+      } else if (snapshot.hasData) {
+        final String combined =
+            snapshot.data.map((Directory d) => d.path).join(', ');
+        text = Text('paths: $combined');
+      } else {
+        text = const Text('path unavailable');
+      }
+    }
+    return Padding(padding: const EdgeInsets.all(16.0), child: text);
+  }
+
   void _requestAppDocumentsDirectory() {
     setState(() {
       _appDocumentsDirectory = getApplicationDocumentsDirectory();
@@ -85,6 +104,18 @@ class _MyHomePageState extends State<MyHomePage> {
     });
   }
 
+  void _requestExternalStorageDirectories(StorageDirectory type) {
+    setState(() {
+      _externalStorageDirectories = getExternalStorageDirectories(type: type);
+    });
+  }
+
+  void _requestExternalCacheDirectories() {
+    setState(() {
+      _externalCacheDirectories = getExternalCacheDirectories();
+    });
+  }
+
   @override
   Widget build(BuildContext context) {
     return Scaffold(
@@ -140,7 +171,39 @@ class _MyHomePageState extends State<MyHomePage> {
               ),
             ),
             FutureBuilder<Directory>(
-                future: _externalDocumentsDirectory, builder: _buildDirectory)
+                future: _externalDocumentsDirectory, builder: _buildDirectory),
+            Column(children: <Widget>[
+              Padding(
+                padding: const EdgeInsets.all(16.0),
+                child: RaisedButton(
+                  child: Text(
+                      '${Platform.isIOS ? "External directories are unavailable " "on iOS" : "Get External Storage Directories"}'),
+                  onPressed: Platform.isIOS
+                      ? null
+                      : () {
+                          _requestExternalStorageDirectories(
+                            StorageDirectory.music,
+                          );
+                        },
+                ),
+              ),
+            ]),
+            FutureBuilder<List<Directory>>(
+                future: _externalStorageDirectories,
+                builder: _buildDirectories),
+            Column(children: <Widget>[
+              Padding(
+                padding: const EdgeInsets.all(16.0),
+                child: RaisedButton(
+                  child: Text(
+                      '${Platform.isIOS ? "External directories are unavailable " "on iOS" : "Get External Cache Directories"}'),
+                  onPressed:
+                      Platform.isIOS ? null : _requestExternalCacheDirectories,
+                ),
+              ),
+            ]),
+            FutureBuilder<List<Directory>>(
+                future: _externalCacheDirectories, builder: _buildDirectories),
           ],
         ),
       ),

packages/path_provider/example/pubspec.yaml

@@ -6,7 +6,6 @@ dependencies:
     sdk: flutter
   path_provider:
     path: ../
-  uuid: "^1.0.0"
 
 dev_dependencies:
   flutter_driver: