Updates documentation on using the "Permission.storage" (#1090)

* Updates documentation on Permission.storage

* Add reference to FAQ section

permission_handler/CHANGELOG.md

+## 10.4.2
+
+* Adds a [FAQ](https://pub.dev/packages/permission_handler#faq) section to the README.md file.
+
 ## 10.4.1
 
 * Updates AndroidManifest documentation in the example application with regards

permission_handler/README.md

@@ -7,6 +7,8 @@ This plugin provides a cross-platform (iOS, Android) API to request permissions
 You can also open the device's app settings so users can grant a permission.  
 On Android, you can show a rationale for requesting a permission.
 
+See the [FAQ](#faq) section for more information on common questions when using the permission_handler plugin.
+
 ## Setup
 
 While the permissions are being requested during runtime, you'll still need to tell the OS which permissions your app might potentially use. That requires adding permission configuration to Android- and iOS-specific files.
@@ -240,6 +242,17 @@ The `locationAlways` permission can not be requested directly, the user has to r
 Accepting this permission by clicking on the 'Allow While Using App' gives the user the possibility to request the `locationAlways` permission.
 This will then bring up another permission popup asking you to `Keep Only While Using` or to `Change To Always Allow`.
 
+## FAQ
+
+### Requesting "storage" permissions always returns "denied" on Android 13, what can I do?
+
+On Android the `Permission.storage` permission is linked to the Android `READ_EXTERNAL_STORAGE` and `WRITE_EXTERNAL_STORAGE` permissions. Starting from Android SDK 29 (Android 10) the `READ_EXTERNAL_STORAGE` and `WRITE_EXTERNAL_STORAGE` permissions have been marked deprecated and have been fully removed/ disabled since Android SDK 33 (Android 13). 
+
+If your application needs access to media files Google recommends using the `READ_MEDIA_IMAGES`, `READ_MEDIA_VIDEOS` or `READ_MEDIA_AUDIO` permissions instead. These can be requested using the `Permission.photos`, `Permission.videos` and `Permission.audio` respectively. To request these permissions make sure the `compileSdkVersion` in the `android/app/build.gradle` file is set to `33`.
+
+If your application needs access to Androids file system it is possible to request the `MANAGE_EXTERNAL_STORAGE` permission (using `Permission.manageExternalStorage`). As of Android SDK 30 (Android 11) the `MANAGE_EXTERNAL_STORAGE` permission is considered a high-risk or sensitive permission. There for it is required to [declare the use of these permissions](https://support.google.com/googleplay/android-developer/answer/9214102) if you intend to release the application via the Google Play Store. 
+
+
 ## Issues
 
 Please file any issues, bugs or feature request as an issue on our [GitHub](https://github.com/Baseflow/flutter-permission-handler/issues) page. Commercial support is available if you need help with integration with your app or services. You can contact us at [hello@baseflow.com](mailto:hello@baseflow.com).

permission_handler/pubspec.yaml

@@ -2,7 +2,7 @@ name: permission_handler
 description: Permission plugin for Flutter. This plugin provides a cross-platform (iOS, Android) API to request and check permissions.
 repository: https://github.com/baseflow/flutter-permission-handler
 issue_tracker: https://github.com/Baseflow/flutter-permission-handler/issues
-version: 10.4.1
+version: 10.4.2
 
 environment:
   sdk: ">=2.15.0 <4.0.0"

permission_handler_platform_interface/CHANGELOG.md

+## 3.11.1
+
+* Updates the documentation for the `Permission.storage` permission regarding its use on Android.
+
 ## 3.11.0+1
 
 * **HOTFIX**: Fixes misalignment in the `Permission` enum after adding the new BODY_SENSORS_BACKGROUND permission.

permission_handler_platform_interface/lib/src/permissions.dart

@@ -67,10 +67,10 @@ class Permission {
   /// iOS: Nothing
   static const phone = PermissionWithService._(8);
 
-  /// When running on Android TIRAMISU and above: Read image files from external storage
-  /// When running on Android < TIRAMISU: Nothing
-  /// iOS: Photos
-  /// iOS 14+ read & write access level
+  /// Android:
+  ///   When running on Android TIRAMISU and above: Read image files from external storage
+  ///   When running on Android < TIRAMISU: Nothing
+  /// iOS: Photos (iOS 14+ read & write access level).
   static const photos = Permission._(9);
 
   /// Android: Nothing
@@ -94,7 +94,14 @@ class Permission {
   /// iOS: Speech
   static const speech = Permission._(14);
 
-  /// Android: External Storage
+  /// Android:
+  ///   On Android < TIRAMISU the `READ_EXTERNAL_STORAGE` and
+  ///   `WRITE_EXTERNAL_STORAGE` permissions are requested (depending on the
+  ///   definitions in the AndroidManifest.xml) file.
+  ///   On Android TIRAMISU and higher this permission is deprecrated and
+  ///   always returns `PermissionStatus.denied`, instead use
+  ///   `Permission.photos`, `Permission.video`, `Permission.audio` or
+  ///   `Permission.manageExternalStorage`. For more information see our [FAQ](https://pub.dev/packages/permission_handler#faq).
   /// iOS: Access to folders like `Documents` or `Downloads`. Implicitly
   /// granted.
   static const storage = Permission._(15);
@@ -181,13 +188,15 @@ class Permission {
   ///iOS: Nothing
   static const nearbyWifiDevices = Permission._(31);
 
-  /// When running on Android TIRAMISU and above: Read video files from external storage
-  /// When running on Android < TIRAMISU: Nothing
+  /// Android:
+  ///   When running on Android TIRAMISU and above: Read video files from external storage
+  ///   When running on Android < TIRAMISU: Nothing
   /// iOS: Nothing
   static const videos = Permission._(32);
 
-  /// When running on Android TIRAMISU and above: Read audio files from external storage
-  /// When running on Android < TIRAMISU: Nothing
+  /// Android:
+  ///   When running on Android TIRAMISU and above: Read audio files from external storage
+  ///   When running on Android < TIRAMISU: Nothing
   /// iOS: Nothing
   static const audio = Permission._(33);
 

permission_handler_platform_interface/pubspec.yaml

@@ -3,7 +3,7 @@ description: A common platform interface for the permission_handler plugin.
 homepage: https://github.com/baseflow/flutter-permission-handler/tree/master/permission_handler_platform_interface
 # NOTE: We strongly prefer non-breaking changes, even at the expense of a
 # less-clean API. See https://flutter.dev/go/platform-interface-breaking-changes
-version: 3.11.0+1
+version: 3.11.1
 
 dependencies:
   flutter: