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
 ## 10.4.1
 
 
 * Updates AndroidManifest documentation in the example application with regards
 * 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.  
 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.
 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
 ## 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.
 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.
 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`.
 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
 ## 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).
 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.
 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
 repository: https://github.com/baseflow/flutter-permission-handler
 issue_tracker: https://github.com/Baseflow/flutter-permission-handler/issues
 issue_tracker: https://github.com/Baseflow/flutter-permission-handler/issues
-version: 10.4.1
+version: 10.4.2
 
 
 environment:
 environment:
   sdk: ">=2.15.0 <4.0.0"
   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
 ## 3.11.0+1
 
 
 * **HOTFIX**: Fixes misalignment in the `Permission` enum after adding the new BODY_SENSORS_BACKGROUND permission.
 * **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
   /// iOS: Nothing
   static const phone = PermissionWithService._(8);
   static const phone = PermissionWithService._(8);
 
 
+  /// Android:
   ///   When running on Android TIRAMISU and above: Read image files from external storage
   ///   When running on Android TIRAMISU and above: Read image files from external storage
   ///   When running on Android < TIRAMISU: Nothing
   ///   When running on Android < TIRAMISU: Nothing
-  /// iOS: Photos
-  /// iOS 14+ read & write access level
+  /// iOS: Photos (iOS 14+ read & write access level).
   static const photos = Permission._(9);
   static const photos = Permission._(9);
 
 
   /// Android: Nothing
   /// Android: Nothing
@@ -94,7 +94,14 @@ class Permission {
   /// iOS: Speech
   /// iOS: Speech
   static const speech = Permission._(14);
   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
   /// iOS: Access to folders like `Documents` or `Downloads`. Implicitly
   /// granted.
   /// granted.
   static const storage = Permission._(15);
   static const storage = Permission._(15);
@@ -181,11 +188,13 @@ class Permission {
   ///iOS: Nothing
   ///iOS: Nothing
   static const nearbyWifiDevices = Permission._(31);
   static const nearbyWifiDevices = Permission._(31);
 
 
+  /// Android:
   ///   When running on Android TIRAMISU and above: Read video files from external storage
   ///   When running on Android TIRAMISU and above: Read video files from external storage
   ///   When running on Android < TIRAMISU: Nothing
   ///   When running on Android < TIRAMISU: Nothing
   /// iOS: Nothing
   /// iOS: Nothing
   static const videos = Permission._(32);
   static const videos = Permission._(32);
 
 
+  /// Android:
   ///   When running on Android TIRAMISU and above: Read audio files from external storage
   ///   When running on Android TIRAMISU and above: Read audio files from external storage
   ///   When running on Android < TIRAMISU: Nothing
   ///   When running on Android < TIRAMISU: Nothing
   /// iOS: Nothing
   /// iOS: Nothing

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
 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
 # 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
 # less-clean API. See https://flutter.dev/go/platform-interface-breaking-changes
-version: 3.11.0+1
+version: 3.11.1
 
 
 dependencies:
 dependencies:
   flutter:
   flutter: