Merge branch 'release' of https://github.com/LaksCastro/shared-storage into release

Author: LaksCastro

.github/workflows/publish.yaml

@@ -12,4 +12,4 @@ jobs:
       - uses: dart-lang/setup-dart@v1
 
       - name: Run Pub Publish
-        run: dart pub publish --dry-run --force
+        run: dart pub publish --dry-run --force

.gitignore

@@ -9,6 +9,8 @@
 .history
 .svn/
 
+*/**/pubspec.lock
+
 # IntelliJ related
 *.iml
 *.ipr

CHANGELOG.md

@@ -1,3 +1,10 @@
+## 0.2.0
+
+Add basic support for `Storage Access Framework` and `targetSdk 31`
+
+- The package now supports basic intents from `Storage Access Framework`
+- Your App needs update the `build.gradle` by targeting the current sdk to `31`
+
 ## 0.1.1
 
 Minor improvements on `pub.dev` documentation

README.md

@@ -9,6 +9,7 @@ Plugin to fetch Android shared storage/folders info
 - _**Android Only**_
 - _**Alpha version**_
 - _**Supports Android 4.1+ (API Level 16+)**_
+- _**The `targetSdk` should be set to `31`**_
 
 ### Features
 
@@ -19,8 +20,8 @@ This plugin allow us to get path of top-level shared folder (Downloads, DCIM, Vi
 ```dart
 /// Get Android [downloads] top-level shared folder
 /// You can also create a reference to a custom directory as: `EnvironmentDirectory.custom('Custom Folder')`
-final sharedDirectory = 
-    await getExternalStoragePublicDirectory(EnvironmentDirectory.downloads); 
+final sharedDirectory =
+    await getExternalStoragePublicDirectory(EnvironmentDirectory.downloads);
 
 print(sharedDirectory.path); /// `/storage/emulated/0/Download`
 ```
@@ -29,26 +30,70 @@ print(sharedDirectory.path); /// `/storage/emulated/0/Download`
 
 ```dart
 /// Get Android [downloads] shared folder for Android 9+
-final sharedDirectory = 
+final sharedDirectory =
     await getMediaStoreContentDirectory(MediaStoreCollection.downloads);
 
 print(sharedDirectory.path); /// `/external/downloads`
 ```
 
-- Get root Android path, note that is a read-only folder
+- Start `OPEN_DOCUMENT_TREE` activity to prompt user to select an folder to enable write and read access to be used by the `Storage Access Framework` API
 
 ```dart
-/// Get Android root folder
-final sharedDirectory = await getRootDirectory();
+/// Get permissions to manage an Android directory
+final selectedUriDir = await openDocumentTree();
 
-print(sharedDirectory.path); /// `/system`
+print(selectedUriDir);
+```
+
+- Create a new file using the `SAF` API
+
+```dart
+/// Create a new file using the `SAF` API
+final newDocumentFile = await createDocumentFile(
+  mimeType: '	text/plain',
+  content: 'My Plain Text Comment Created by shared_storage plugin',
+  displayName: 'CreatedBySharedStorageFlutterPlugin',
+  directory: anySelectedUriByTheOpenDocumentTreeAPI,
+);
+
+print(newDocumentFile);
+```
+
+- Get all persisted [URI]s by the `openDocumentTree` API, from `SAF` API
+
+```dart
+/// You have [write] and [read] access to all persisted [URI]s
+final listOfPersistedUris = await persistedUriPermissions();
+
+print(listOfPersistedUris);
+```
+
+- Revoke a current persisted [URI], from `SAF` API
+
+```dart
+/// Can be any [URI] returned by the `persistedUriPermissions`
+final uri = ...;
+
+/// After calling this, you no longer has access to the [uri]
+await releasePersistableUriPermission(uri);
+```
+
+- Convenient method to know if a given [uri] is a persisted `uri` ("persisted uri" means that you have `write` and `read` access to the `uri` even if devices reboot)
+
+```dart
+/// Can be any [URI], but the method will only return [true] if the [uri]
+/// is also present in the list returned by `persistedUriPermissions`
+final uri = ...;
+
+/// Verify if you have [write] and [read] access to a given [uri]
+final isPersisted = await isPersistedUri(uri);
 ```
 
 ### Android API's
 
 Most Flutter plugins uses Android API's under the hood. So this plugin do the same, and to retrieve Android shared folder paths the following API's are being used:
 
-[`🔗 android.os.Environment`](https://developer.android.com/reference/android/os/Environment#summary) [`🔗 android.provider.MediaStore`](https://developer.android.com/reference/android/provider/MediaStore#summary)
+[`🔗android.os.Environment`](https://developer.android.com/reference/android/os/Environment#summary) [`🔗android.provider.MediaStore`](https://developer.android.com/reference/android/provider/MediaStore#summary) [`🔗android.provider.DocumentsProvider`](https://developer.android.com/guide/topics/providers/document-provider)
 
 <br>
 

android/build.gradle

@@ -1,4 +1,4 @@
-group 'com.pinciat.external_path'
+group 'io.lakscastro.sharedstorage'
 version '1.0-SNAPSHOT'
 
 buildscript {
@@ -37,4 +37,5 @@ android {
 
 dependencies {
     implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk7:$kotlin_version"
+    implementation "androidx.documentfile:documentfile:1.0.1"
 }

android/settings.gradle

@@ -1 +1 @@
-rootProject.name = 'external_path'
+rootProject.name = 'sharedstorage'

android/src/main/AndroidManifest.xml

@@ -1,3 +1,3 @@
 <manifest xmlns:android="http://schemas.android.com/apk/res/android"
-  package="com.pinciat.external_path">
+  package="io.lakscastro.sharedstorage">
 </manifest>

android/src/main/kotlin/io/lakscastro/sharedstorage/EnvironmentDirectoryOf.kt

@@ -1,8 +1,9 @@
 package io.lakscastro.sharedstorage
 
 import android.os.Environment
+import java.io.File
 
-fun environmentDirectoryOf(directory: String): String {
+fun environmentDirectoryOf(directory: String): File {
   val mapper = mapOf(
     "EnvironmentDirectory.Alarms" to Environment.DIRECTORY_ALARMS,
     "EnvironmentDirectory.DCIM" to Environment.DIRECTORY_DCIM,
@@ -15,5 +16,5 @@ fun environmentDirectoryOf(directory: String): String {
     "EnvironmentDirectory.Ringtones" to Environment.DIRECTORY_RINGTONES
   )
 
-  return mapper[directory] ?: directory
+  return Environment.getExternalStoragePublicDirectory(mapper[directory] ?: directory)
 }