Merge branch 'master' into allowed-app-dirs-external-sdcards

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": "cordova-plugin-file",
-  "version": "8.0.1-dev",
+  "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;
 
@@ -137,7 +136,7 @@ private long getAssetSize(String assetPath) throws FileNotFoundException {
     public AssetFilesystem(AssetManager assetManager, CordovaResourceApi resourceApi, CordovaPreferences preferences) {
         super(Uri.parse("file:///android_asset/"), "assets", resourceApi, preferences);
         this.assetManager = assetManager;
-	}
+    }
 
     @Override
     public Uri toNativeUri(LocalFilesystemURL inputURL) {
@@ -204,7 +203,7 @@ public LocalFilesystemURL[] listChildren(LocalFilesystemURL inputURL) throws Fil
             entries[i] = localUrlforFullPath(new File(inputURL.path, files[i]).getPath());
         }
         return entries;
-	}
+    }
 
     @Override
     public JSONObject getFileForLocalURL(LocalFilesystemURL inputURL,
@@ -241,25 +240,25 @@ public JSONObject getFileForLocalURL(LocalFilesystemURL inputURL,
     }
 
     @Override
-	public JSONObject getFileMetadataForLocalURL(LocalFilesystemURL inputURL) throws FileNotFoundException {
+    public JSONObject getFileMetadataForLocalURL(LocalFilesystemURL inputURL) throws FileNotFoundException {
         JSONObject metadata = new JSONObject();
         long size = inputURL.isDirectory ? 0 : getAssetSize(inputURL.path);
         try {
-        	metadata.put("size", size);
-        	metadata.put("type", inputURL.isDirectory ? "text/directory" : resourceApi.getMimeType(toNativeUri(inputURL)));
-        	metadata.put("name", new File(inputURL.path).getName());
-        	metadata.put("fullPath", inputURL.path);
-        	metadata.put("lastModifiedDate", 0);
+            metadata.put("size", size);
+            metadata.put("type", inputURL.isDirectory ? "text/directory" : resourceApi.getMimeType(toNativeUri(inputURL)));
+            metadata.put("name", new File(inputURL.path).getName());
+            metadata.put("fullPath", inputURL.path);
+            metadata.put("lastModifiedDate", 0);
         } catch (JSONException e) {
             return null;
         }
         return metadata;
-	}
+    }
 
-	@Override
-	public boolean canRemoveFileAtLocalURL(LocalFilesystemURL inputURL) {
-		return false;
-	}
+    @Override
+    public boolean canRemoveFileAtLocalURL(LocalFilesystemURL inputURL) {
+        return false;
+    }
 
     @Override
     long writeToFileAtURL(LocalFilesystemURL inputURL, String data, int offset, boolean isBinary) throws NoModificationAllowedException, IOException {

src/android/AssetFilesystem.java

@@ -38,10 +38,10 @@ public class ContentFilesystem extends Filesystem {
 
     private final Context context;
 
-	public ContentFilesystem(Context context, CordovaResourceApi resourceApi, CordovaPreferences preferences) {
-		super(Uri.parse("content://"), "content", resourceApi, preferences);
+    public ContentFilesystem(Context context, CordovaResourceApi resourceApi, CordovaPreferences preferences) {
+        super(Uri.parse("content://"), "content", resourceApi, preferences);
         this.context = context;
-	}
+    }
 
     @Override
     public Uri toNativeUri(LocalFilesystemURL inputURL) {
@@ -84,41 +84,41 @@ public LocalFilesystemURL toLocalUri(Uri inputURL) {
     }
 
     @Override
-	public JSONObject getFileForLocalURL(LocalFilesystemURL inputURL,
-			String fileName, JSONObject options, boolean directory) throws IOException, TypeMismatchException, JSONException {
+    public JSONObject getFileForLocalURL(LocalFilesystemURL inputURL,
+            String fileName, JSONObject options, boolean directory) throws IOException, TypeMismatchException, JSONException {
         throw new UnsupportedOperationException("getFile() not supported for content:. Use resolveLocalFileSystemURL instead.");
-	}
+    }
 
-	@Override
-	public boolean removeFileAtLocalURL(LocalFilesystemURL inputURL)
-			throws NoModificationAllowedException {
+    @Override
+    public boolean removeFileAtLocalURL(LocalFilesystemURL inputURL)
+            throws NoModificationAllowedException {
         Uri contentUri = toNativeUri(inputURL);
-		try {
+        try {
             context.getContentResolver().delete(contentUri, null, null);
-		} catch (UnsupportedOperationException t) {
-			// Was seeing this on the File mobile-spec tests on 4.0.3 x86 emulator.
-			// The ContentResolver applies only when the file was registered in the
-			// first case, which is generally only the case with images.
+        } catch (UnsupportedOperationException t) {
+            // Was seeing this on the File mobile-spec tests on 4.0.3 x86 emulator.
+            // The ContentResolver applies only when the file was registered in the
+            // first case, which is generally only the case with images.
             NoModificationAllowedException nmae = new NoModificationAllowedException("Deleting not supported for content uri: " + contentUri);
             nmae.initCause(t);
             throw nmae;
-		}
+        }
         return true;
-	}
+    }
 
-	@Override
-	public boolean recursiveRemoveFileAtLocalURL(LocalFilesystemURL inputURL)
-			throws NoModificationAllowedException {
-		throw new NoModificationAllowedException("Cannot remove content url");
-	}
+    @Override
+    public boolean recursiveRemoveFileAtLocalURL(LocalFilesystemURL inputURL)
+            throws NoModificationAllowedException {
+        throw new NoModificationAllowedException("Cannot remove content url");
+    }
 
     @Override
     public LocalFilesystemURL[] listChildren(LocalFilesystemURL inputURL) throws FileNotFoundException {
         throw new UnsupportedOperationException("readEntriesAtLocalURL() not supported for content:. Use resolveLocalFileSystemURL instead.");
     }
 
-	@Override
-	public JSONObject getFileMetadataForLocalURL(LocalFilesystemURL inputURL) throws FileNotFoundException {
+    @Override
+    public JSONObject getFileMetadataForLocalURL(LocalFilesystemURL inputURL) throws FileNotFoundException {
         long size = -1;
         long lastModified = 0;
         Uri nativeUri = toNativeUri(inputURL);
@@ -143,55 +143,55 @@ public JSONObject getFileMetadataForLocalURL(LocalFilesystemURL inputURL) throws
             fnfe.initCause(e);
             throw fnfe;
         } finally {
-        	if (cursor != null)
-        		cursor.close();
+            if (cursor != null)
+                cursor.close();
         }
 
         JSONObject metadata = new JSONObject();
         try {
-        	metadata.put("size", size);
-        	metadata.put("type", mimeType);
-        	metadata.put("name", name);
-        	metadata.put("fullPath", inputURL.path);
-        	metadata.put("lastModifiedDate", lastModified);
+            metadata.put("size", size);
+            metadata.put("type", mimeType);
+            metadata.put("name", name);
+            metadata.put("fullPath", inputURL.path);
+            metadata.put("lastModifiedDate", lastModified);
         } catch (JSONException e) {
-        	return null;
+            return null;
         }
         return metadata;
-	}
+    }
 
-	@Override
-	public long writeToFileAtURL(LocalFilesystemURL inputURL, String data,
-			int offset, boolean isBinary) throws NoModificationAllowedException {
+    @Override
+    public long writeToFileAtURL(LocalFilesystemURL inputURL, String data,
+            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 {
+    @Override
+    public long truncateFileAtURL(LocalFilesystemURL inputURL, long size)
+            throws NoModificationAllowedException {
         throw new NoModificationAllowedException("Couldn't truncate file given its content URI");
-	}
+    }
 
-	protected Cursor openCursorForURL(Uri nativeUri) {
+    protected Cursor openCursorForURL(Uri nativeUri) {
         ContentResolver contentResolver = context.getContentResolver();
         try {
             return contentResolver.query(nativeUri, null, null, null, null);
         } catch (UnsupportedOperationException e) {
             return null;
         }
-	}
+    }
 
-	private Long resourceSizeForCursor(Cursor cursor) {
+    private Long resourceSizeForCursor(Cursor cursor) {
         int columnIndex = cursor.getColumnIndex(OpenableColumns.SIZE);
         if (columnIndex != -1) {
             String sizeStr = cursor.getString(columnIndex);
             if (sizeStr != null) {
-            	return Long.parseLong(sizeStr);
+                return Long.parseLong(sizeStr);
             }
         }
         return null;
-	}
-	
-	protected Long lastModifiedDateForCursor(Cursor cursor) {
+    }
+
+    protected Long lastModifiedDateForCursor(Cursor cursor) {
         int columnIndex = cursor.getColumnIndex(MediaStore.MediaColumns.DATE_MODIFIED);
         if (columnIndex == -1) {
             columnIndex = cursor.getColumnIndex(DocumentsContract.Document.COLUMN_LAST_MODIFIED);
@@ -203,22 +203,22 @@ protected Long lastModifiedDateForCursor(Cursor cursor) {
             }
         }
         return null;
-	}
+    }
 
     @Override
     public String filesystemPathForURL(LocalFilesystemURL url) {
         File f = resourceApi.mapUriToFile(toNativeUri(url));
         return f == null ? null : f.getAbsolutePath();
     }
 
-	@Override
-	public LocalFilesystemURL URLforFilesystemPath(String path) {
-		// Returns null as we don't support reverse mapping back to content:// URLs
-		return null;
-	}
+    @Override
+    public LocalFilesystemURL URLforFilesystemPath(String path) {
+        // Returns null as we don't support reverse mapping back to content:// URLs
+        return null;
+    }
 
-	@Override
-	public boolean canRemoveFileAtLocalURL(LocalFilesystemURL inputURL) {
-		return true;
-	}
+    @Override
+    public boolean canRemoveFileAtLocalURL(LocalFilesystemURL inputURL) {
+        return true;
+    }
 }