Merge remote-tracking branch 'upstream/master'

Author: ath0mas

.asf.yaml

@@ -15,6 +15,32 @@
 # specific language governing permissions and limitations
 # under the License.
 
+github:
+  description: Apache Cordova File Plugin
+  homepage: https://cordova.apache.org/
+
+  labels:
+    - android
+    - cordova
+    - hacktoberfest
+    - ios
+    - java
+    - javascript
+    - library
+    - mobile
+    - nodejs
+    - objective-c
+
+  features:
+    wiki: false
+    issues: true
+    projects: true
+
+  enabled_merge_buttons:
+    squash: true
+    merge: false
+    rebase: false
+
 notifications:
   commits:              commits@cordova.apache.org
   issues:               issues@cordova.apache.org

README.md

@@ -95,17 +95,17 @@ Each URL is in the form _file:///path/to/spot/_, and can be converted to a
   in here. (_iOS_, _Android_, _BlackBerry 10_, _OSX_, _windows_)
 
 * `cordova.file.externalApplicationStorageDirectory` - Application space on
-  external storage. (_Android_)
+  external storage. (_Android_). See [Quirks](#androids-external-storage-quirks).
 
 * `cordova.file.externalDataDirectory` - Where to put app-specific data files on
-  external storage. (_Android_)
+  external storage. (_Android_). See [Quirks](#androids-external-storage-quirks).
 
 * `cordova.file.externalCacheDirectory` - Application cache on external storage.
-  (_Android_)
+  (_Android_). See [Quirks](#androids-external-storage-quirks).
 
 * `cordova.file.externalMediaDirectory` - Application media directory on external storage. (_Android_)
 
-* `cordova.file.externalRootDirectory` - External storage (SD card) root. (_Android_, _BlackBerry 10_)
+* `cordova.file.externalRootDirectory` - External storage (SD card) root. (_Android_, _BlackBerry 10_). See [Quirks](#androids-external-storage-quirks).
 
 * `cordova.file.tempDirectory` - Temp directory that the OS can clear at will. Do not
   rely on the OS to clear this directory; your app should always remove files as
@@ -194,6 +194,26 @@ the `cordova.file.*` properties map to physical paths on a real device.
 **Note**: If external storage can't be mounted, the `cordova.file.external*`
 properties are `null`.
 
+#### Android's External Storage Quirks
+
+With the introduction of [Scoped Storage](https://source.android.com/docs/core/storage/scoped) access to External Storage is unreliable or limited via File APIs.
+Scoped Storage was introduced in API 29. While existing apps may have the ability to opt out, this option is not available for new apps. On Android API 30 and later, Scoped Storage is fully enforced.
+
+Additionally, Direct File Access **is not** supported on API 29. This means this plugin **cannot** access external storage mediums on API 29 devices.
+
+API 30 introduced [FUSE](https://source.android.com/docs/core/storage/scoped) which allowed limited access to external storage using File APIs, allowing this plugin to
+partially work again.
+
+Limited access includes but isn't limited to:
+- Read only access with appropriate `READ_EXTERNAL` or [READ_MEDIA_*](https://developer.android.com/training/data-storage/shared/media#access-other-apps-files) permissions.
+- Read only access is limited to media files, but not documents.
+- Writes are limited to only files owned by your app. Modifying files owned by a third-party app (including an image file created via the camera plugin for example) is not possible via the File API.
+- Not all paths in external storage is writable.
+
+These limitations only applies to external filesystems (e.g. `cordova.file.external*` paths). Internal filesystems such as `cordova.file.dataDirectory` path are not imposed by these limitations.
+
+If interfacing with the external file system is a requirement for your application, consider using a [MediaStore](https://www.npmjs.com/search?q=ecosystem%3Acordova%20storage%20access%20framework) plugin instead.
+
 ### OS X File System Layout
 
 | Device Path                                      | `cordova.file.*`            | `iosExtraFileSystems` | r/w? |  OS clears | private |

RELEASENOTES.md

@@ -20,6 +20,18 @@
 -->
 # Release Notes
 
+### 8.0.1 (Oct 27, 2023)
+
+**Fixes:**
+
+* [GH-608](https://github.com/apache/cordova-plugin-file/pull/608) fix(android): `hasWritePermission` for SDK 33
+
+**Others:**
+
+* [GH-609](https://github.com/apache/cordova-plugin-file/pull/609) chore: update asf config
+* [GH-607](https://github.com/apache/cordova-plugin-file/pull/607) refactor(android): various cleanup
+* [GH-593](https://github.com/apache/cordova-plugin-file/pull/593) doc(android): expanded on external filesystems limitations
+
 ### 8.0.0 (Jul 07, 2023)
 
 * [GH-534](https://github.com/apache/cordova-plugin-file/pull/534) fix(android): `FileError` on a content `resolveLocalFileSystemURL`

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@ns0m/cordova-plugin-file",
-  "version": "8.0.1-4",
+  "version": "8.0.2-dev",
   "description": "Cordova File Plugin",
   "types": "./types/index.d.ts",
   "cordova": {

package.json

@@ -21,7 +21,7 @@
 <plugin xmlns="http://apache.org/cordova/ns/plugins/1.0"
 xmlns:android="http://schemas.android.com/apk/res/android"
            id="cordova-plugin-file"
-      version="8.0.1-dev">
+      version="8.0.2-dev">
     <name>File</name>
     <description>Cordova File Plugin</description>
     <license>Apache 2.0</license>

plugin.xml

@@ -24,7 +24,6 @@ Licensed to the Apache Software Foundation (ASF) under one
 import org.apache.cordova.CordovaPreferences;
 import org.apache.cordova.CordovaResourceApi;
 import org.apache.cordova.LOG;
-import org.json.JSONArray;
 import org.json.JSONException;
 import org.json.JSONObject;
 

src/android/AssetFilesystem.java

@@ -86,7 +86,7 @@ public LocalFilesystemURL toLocalUri(Uri inputURL) {
 
     @Override
     public JSONObject getFileForLocalURL(LocalFilesystemURL inputURL,
-                                         String fileName, JSONObject options, boolean directory) throws IOException, TypeMismatchException, JSONException {
+            String fileName, JSONObject options, boolean directory) throws IOException, TypeMismatchException, JSONException {
         throw new UnsupportedOperationException("getFile() not supported for content:. Use resolveLocalFileSystemURL instead.");
     }
 
@@ -163,10 +163,9 @@ public JSONObject getFileMetadataForLocalURL(LocalFilesystemURL inputURL) throws
 
     @Override
     public long writeToFileAtURL(LocalFilesystemURL inputURL, String data,
-                                 int offset, boolean isBinary) throws NoModificationAllowedException {
+            int offset, boolean isBinary) throws NoModificationAllowedException {
         throw new NoModificationAllowedException("Couldn't write to file given its content URI");
     }
-
     @Override
     public long truncateFileAtURL(LocalFilesystemURL inputURL, long size)
             throws NoModificationAllowedException {

src/android/ContentFilesystem.java

@@ -39,7 +39,6 @@ Licensed to the Apache Software Foundation (ASF) under one
 import org.apache.cordova.LOG;
 import org.apache.cordova.PermissionHelper;
 import org.apache.cordova.PluginResult;
-
 import org.json.JSONArray;
 import org.json.JSONException;
 import org.json.JSONObject;
@@ -543,10 +542,21 @@ private void getReadPermission(String rawArgs, int action, CallbackContext callb
     }
 
     private void getWritePermission(String rawArgs, int action, CallbackContext callbackContext) {
-        int requestCode = pendingRequests.createRequest(rawArgs, action, callbackContext);
-        PermissionHelper.requestPermission(this, requestCode, Manifest.permission.WRITE_EXTERNAL_STORAGE);
+        if (android.os.Build.VERSION.SDK_INT < Build.VERSION_CODES.TIRAMISU) {
+            int requestCode = pendingRequests.createRequest(rawArgs, action, callbackContext);
+            PermissionHelper.requestPermission(this, requestCode, Manifest.permission.WRITE_EXTERNAL_STORAGE);
+        }
     }
 
+    /**
+     * If your app targets Android 13 (SDK 33) or higher and needs to access media files that other apps have created,
+     * you must request one or more of the following granular media permissions READ_MEDIA_*
+     * instead of the READ_EXTERNAL_STORAGE permission:
+     *
+     * Refer to: https://developer.android.com/about/versions/13/behavior-changes-13
+     *
+     * @return
+     */
     private boolean hasReadPermission() {
         if (android.os.Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
             return PermissionHelper.hasPermission(this, Manifest.permission.READ_MEDIA_IMAGES)
@@ -558,7 +568,10 @@ private boolean hasReadPermission() {
     }
 
     private boolean hasWritePermission() {
-        return PermissionHelper.hasPermission(this, Manifest.permission.WRITE_EXTERNAL_STORAGE);
+        // Starting with API 33, requesting WRITE_EXTERNAL_STORAGE is an auto permission rejection
+        return android.os.Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU
+                ? true
+                : PermissionHelper.hasPermission(this, Manifest.permission.WRITE_EXTERNAL_STORAGE);
     }
 
     private boolean needPermission(String nativeURL, int permissionType) throws JSONException {
@@ -685,8 +698,6 @@ public void run() {
                         callbackContext.error(FileUtils.ENCODING_ERR);
                     } else if (e instanceof IOException) {
                         callbackContext.error(FileUtils.INVALID_MODIFICATION_ERR);
-                    } else if (e instanceof EncodingException) {
-                        callbackContext.error(FileUtils.ENCODING_ERR);
                     } else if (e instanceof TypeMismatchException) {
                         callbackContext.error(FileUtils.TYPE_MISMATCH_ERR);
                     } else if (e instanceof JSONException) {
@@ -1001,56 +1012,16 @@ private JSONObject requestAllPaths() throws JSONException {
         ret.put("applicationStorageDirectory", toDirUrl(context.getFilesDir().getParentFile()));
         ret.put("dataDirectory", toDirUrl(context.getFilesDir()));
         ret.put("cacheDirectory", toDirUrl(context.getCacheDir()));
-        try {
-            if (Environment.getExternalStorageState().equals(Environment.MEDIA_MOUNTED)) {
+        if (Environment.getExternalStorageState().equals(Environment.MEDIA_MOUNTED)) {
+            try {
                 ret.put("externalApplicationStorageDirectory", toDirUrl(context.getExternalFilesDir(null).getParentFile()));
                 ret.put("externalDataDirectory", toDirUrl(context.getExternalFilesDir(null)));
                 ret.put("externalCacheDirectory", toDirUrl(context.getExternalCacheDir()));
                 ret.put("externalRootDirectory", toDirUrl(Environment.getExternalStorageDirectory()));
+            } catch (NullPointerException e) {
+                /* If external storage is unavailable, context.getExternal* returns null */
+                LOG.d(LOG_TAG, "Unable to access these paths, most liklely due to USB storage");
             }
-
-            JSONArray removableExternalApplicationStorageDirs = new JSONArray();
-            JSONArray removableExternalDataDirs = new JSONArray();
-            JSONArray removableExternalCacheDirs = new JSONArray();
-            JSONArray removableExternalMediaDirs = new JSONArray();
-            String externalMediaDir = null;
-            for (File filesDir : context.getExternalFilesDirs(null)) {
-                if (filesDir != null) {
-                    if (Environment.isExternalStorageRemovable(filesDir)) {
-                        removableExternalApplicationStorageDirs.put(toDirUrl(filesDir.getParentFile()));
-                        removableExternalDataDirs.put(toDirUrl(filesDir));
-                    }
-                }
-            }
-            for (File cacheDir : context.getExternalCacheDirs()) {
-                if (cacheDir != null) {
-                    if (Environment.isExternalStorageRemovable(cacheDir)) {
-                        removableExternalCacheDirs.put(toDirUrl(cacheDir));
-                    }
-                }
-            }
-            for (File mediaDir : context.getExternalMediaDirs()) {
-                if (mediaDir != null) {
-                    String dirUrl = toDirUrl(mediaDir);
-                    if (Environment.isExternalStorageRemovable(mediaDir)) {
-                        removableExternalMediaDirs.put(dirUrl);
-                    } else {
-                        if (externalMediaDir != null) {
-                            LOG.w(LOG_TAG, "External media directory already found ; skip other value " + dirUrl);
-                            continue;
-                        }
-                        externalMediaDir = dirUrl;
-                    }
-                }
-            }
-            ret.put("removableExternalApplicationStorageDirectories", removableExternalApplicationStorageDirs);
-            ret.put("removableExternalDataDirectories", removableExternalDataDirs);
-            ret.put("removableExternalCacheDirectories", removableExternalCacheDirs);
-            ret.put("removableExternalMediaDirectories", removableExternalMediaDirs);
-            ret.put("externalMediaDirectory", externalMediaDir);
-        } catch (NullPointerException e) {
-            /* If external storage is unavailable, context.getExternal* returns null */
-            LOG.d(LOG_TAG, "Unable to access these paths, most likely due to USB storage");
         }
         return ret;
     }

src/android/FileUtils.java

@@ -106,7 +106,7 @@ public JSONObject makeEntryForFile(File file) {
     }
 
     abstract JSONObject getFileForLocalURL(LocalFilesystemURL inputURL, String path,
-                                           JSONObject options, boolean directory) throws FileExistsException, IOException, TypeMismatchException, EncodingException, JSONException;
+            JSONObject options, boolean directory) throws FileExistsException, IOException, TypeMismatchException, EncodingException, JSONException;
 
     abstract boolean removeFileAtLocalURL(LocalFilesystemURL inputURL) throws InvalidModificationException, NoModificationAllowedException;
 
@@ -295,7 +295,7 @@ public void readFileAtURL(LocalFilesystemURL inputURL, long start, long end,
     }
 
     abstract long writeToFileAtURL(LocalFilesystemURL inputURL, String data, int offset,
-                                   boolean isBinary) throws NoModificationAllowedException, IOException;
+            boolean isBinary) throws NoModificationAllowedException, IOException;
 
     abstract long truncateFileAtURL(LocalFilesystemURL inputURL, long size)
             throws IOException, NoModificationAllowedException;