[path_provider] Android: Support multiple external storage options

packages/path_provider/CHANGELOG.md

@@ -1,3 +1,10 @@
+## 1.3.1
+
+* 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.0
 
 * Added iOS-only support for `getLibraryDirectory`.

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

@@ -4,15 +4,20 @@
 
 package io.flutter.plugins.pathprovider;
 
+import android.os.Build.VERSION;
+import android.os.Build.VERSION_CODES;
 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) {
@@ -38,6 +43,13 @@ public void onMethodCall(MethodCall call, Result result) {
       case "getStorageDirectory":
         result.success(getPathProviderStorageDirectory());
         break;
+      case "getExternalCacheDirectories":
+        result.success(getPathProviderExternalCacheDirectories());
+        break;
+      case "getExternalStorageDirectories":
+        final String type = call.argument("type");
+        result.success(getPathProviderExternalStorageDirectories(type));
+        break;
       case "getApplicationSupportDirectory":
         result.success(getApplicationSupportDirectory());
         break;
@@ -65,4 +77,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/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(String type) {
+    setState(() {
+      _externalStorageDirectories = getExternalStorageDirectories(type);
+    });
+  }
+
+  void _requestExternalCacheDirectories() {
+    setState(() {
+      _externalCacheDirectories = getExternalCacheDirectories();
+    });
+  }
+
   @override
   Widget build(BuildContext context) {
     return Scaffold(
@@ -140,7 +171,38 @@ 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(
+                              AndroidEnvironment.DIRECTORY_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/test_driver/path_provider.dart

@@ -74,4 +74,52 @@ void main() {
       file.deleteSync();
     }
   });
+
+  test('getExternalCacheDirectories', () async {
+    if (Platform.isIOS) {
+      final Future<List<Directory>> result = getExternalCacheDirectories();
+      expect(result, throwsA(isInstanceOf<UnsupportedError>()));
+    } else if (Platform.isAndroid) {
+      final List<Directory> directories = await getExternalCacheDirectories();
+      for (Directory result in directories) {
+        final String uuid = Uuid().v1();
+        final File file = File('${result.path}/$uuid.txt');
+        file.writeAsStringSync('Hello world!');
+        expect(file.readAsStringSync(), 'Hello world!');
+        expect(result.listSync(), isNotEmpty);
+        file.deleteSync();
+      }
+    }
+  });
+
+  test('getExternalStorageDirectories', () async {
+    if (Platform.isIOS) {
+      final Future<List<Directory>> result =
+          getExternalStorageDirectories(null);
+      expect(result, throwsA(isInstanceOf<UnsupportedError>()));
+    } else if (Platform.isAndroid) {
+      final List<String> allDirs = <String>[
+        null,
+        AndroidEnvironment.DIRECTORY_MUSIC,
+        AndroidEnvironment.DIRECTORY_PODCASTS,
+        AndroidEnvironment.DIRECTORY_RINGTONES,
+        AndroidEnvironment.DIRECTORY_ALARMS,
+        AndroidEnvironment.DIRECTORY_NOTIFICATIONS,
+        AndroidEnvironment.DIRECTORY_PICTURES,
+        AndroidEnvironment.DIRECTORY_MOVIES,
+      ];
+      for (String type in allDirs) {
+        final List<Directory> directories =
+            await getExternalStorageDirectories(type);
+        for (Directory result in directories) {
+          final String uuid = Uuid().v1();
+          final File file = File('${result.path}/$uuid.txt');
+          file.writeAsStringSync('Hello world!');
+          expect(file.readAsStringSync(), 'Hello world!');
+          expect(result.listSync(), isNotEmpty);
+          file.deleteSync();
+        }
+      }
+    }
+  });
 }

packages/path_provider/lib/path_provider.dart

@@ -61,7 +61,12 @@ Future<Directory> getApplicationSupportDirectory() async {
 
 /// Path to the directory where application can store files that are persistent,
 /// backed up, and not visible to the user, such as sqlite.db.
+///
+/// On Android, this function throws an [UnsupportedError] as no equivalent
+/// folder exists.
 Future<Directory> getLibraryDirectory() async {
+  if (_platform.isAndroid)
+    throw UnsupportedError("Functionality not available on Android");
   final String path =
       await _channel.invokeMethod<String>('getLibraryDirectory');
   if (path == null) {
@@ -106,3 +111,64 @@ Future<Directory> getExternalStorageDirectory() async {
   }
   return Directory(path);
 }
+
+/// Paths to directories where application specific cache data can be stored.
+/// These paths typically reside on external storage like separate partitions
+/// or SD cards. Phones may have multiple storage directories available.
+///
+/// The current operating system should be determined before issuing this
+/// function call, as this functionality is only available on Android.
+///
+/// On iOS, this function throws an UnsupportedError as it is not possible
+/// to access outside the app's sandbox.
+///
+/// On Android this returns Context.getExternalCacheDirs() or
+/// Context.getExternalCacheDir() on API levels below 19.
+Future<List<Directory>> getExternalCacheDirectories() async {
+  if (_platform.isIOS)
+    throw UnsupportedError("Functionality not available on iOS");
+  final List<String> paths =
+      await _channel.invokeListMethod<String>('getExternalCacheDirectories');
+
+  return paths.map((String path) => Directory(path)).toList();
+}
+
+/// Shadows directory values from Androids `android.os.Environment` class.
+///
+/// https://developer.android.com/reference/android/os/Environment.html#fields_1
+class AndroidEnvironment {
+  static const String DIRECTORY_MUSIC = 'Music';
+  static const String DIRECTORY_PODCASTS = 'Podcasts';
+  static const String DIRECTORY_RINGTONES = 'Ringtones';
+  static const String DIRECTORY_ALARMS = 'Alarms';
+  static const String DIRECTORY_NOTIFICATIONS = 'Notifications';
+  static const String DIRECTORY_PICTURES = 'Pictures';
+  static const String DIRECTORY_MOVIES = 'Movies';
+}
+
+/// Paths to directories where application specific data can be stored.
+/// These paths typically reside on external storage like separate partitions
+/// or SD cards. Phones may have multiple storage directories available.
+///
+/// The current operating system should be determined before issuing this
+/// function call, as this functionality is only available on Android.
+///
+/// On iOS, this function throws an UnsupportedError as it is not possible
+/// to access outside the app's sandbox.
+///
+/// On Android this returns Context.getExternalFilesDirs(String type) or
+/// Context.getExternalFilesDir(String type) on API levels below 19.
+///
+/// The parameter [type] is optional. If it is set, it *must* be one of the
+/// constants defined in [AndroidEnvironment]. See [AndroidEnvironment] for
+/// more information.
+Future<List<Directory>> getExternalStorageDirectories(String type) async {
+  if (_platform.isIOS)
+    throw UnsupportedError("Functionality not available on iOS");
+  final List<String> paths = await _channel.invokeListMethod<String>(
+    'getExternalStorageDirectories',
+    <String, String>{"type": type},
+  );
+
+  return paths.map((String path) => Directory(path)).toList();
+}

packages/path_provider/pubspec.yaml

@@ -3,7 +3,7 @@ description: Flutter plugin for getting commonly used locations on the Android &
   iOS file systems, such as the temp and app data directories.
 author: Flutter Team <flutter-dev@googlegroups.com>
 homepage: https://github.com/flutter/plugins/tree/master/packages/path_provider
-version: 1.3.0
+version: 1.3.1
 
 flutter:
   plugin: