From e51e9454006f19d15495ec4946455f5b8f7c1acc Mon Sep 17 00:00:00 2001
From: farfromrefuge <martin.guillon@akylas.fr>
Date: Fri, 22 Jul 2022 17:14:15 +0200
Subject: [PATCH] feat(files): knownFolders.externalDocuments for android ease
 of use (#9966)

---
 .../core/file-system/file-system-access.android.ts   |  5 +++++
 packages/core/file-system/file-system-access.d.ts    |  6 ++++++
 packages/core/file-system/file-system-access.ios.ts  |  3 +++
 packages/core/file-system/index.d.ts                 |  7 +++++++
 packages/core/file-system/index.ts                   | 12 ++++++++++++
 5 files changed, 33 insertions(+)

diff --git a/packages/core/file-system/file-system-access.android.ts b/packages/core/file-system/file-system-access.android.ts
index d0d6d9bd1..d0eed3c0e 100644
--- a/packages/core/file-system/file-system-access.android.ts
+++ b/packages/core/file-system/file-system-access.android.ts
@@ -224,6 +224,11 @@ export class FileSystemAccess implements IFileSystemAccess {
 
 		return dir.getAbsolutePath();
 	}
+	public getExternalDocumentsFolderPath(): string {
+		const dir = getApplicationContext().getExternalFilesDir(null);
+
+		return dir.getAbsolutePath();
+	}
 
 	public getLogicalRootPath(): string {
 		const dir = getApplicationContext().getFilesDir();
diff --git a/packages/core/file-system/file-system-access.d.ts b/packages/core/file-system/file-system-access.d.ts
index 3f69fbde2..4ffcd6923 100644
--- a/packages/core/file-system/file-system-access.d.ts
+++ b/packages/core/file-system/file-system-access.d.ts
@@ -100,6 +100,12 @@ export interface IFileSystemAccess {
 	 */
 	getDocumentsFolderPath(): string;
 
+	/**
+	 * Gets the special documents folder on external storage.
+	 * As there is no external storage on iOS it is the same as getDocumentsFolderPath
+	 */
+	getExternalDocumentsFolderPath(): string;
+
 	/**
 	 * Gets the special temp folder.
 	 * Returns for Android: "/data/data/applicationPackageName/cache", iOS: "/var/mobile/Applications/appID/Library/Caches"
diff --git a/packages/core/file-system/file-system-access.ios.ts b/packages/core/file-system/file-system-access.ios.ts
index 06130b1f4..c7b0cc0e7 100644
--- a/packages/core/file-system/file-system-access.ios.ts
+++ b/packages/core/file-system/file-system-access.ios.ts
@@ -248,6 +248,9 @@ export class FileSystemAccess {
 	public getDocumentsFolderPath(): string {
 		return this.getKnownPath(NSSearchPathDirectory.DocumentDirectory);
 	}
+	public getExternalDocumentsFolderPath(): string {
+		return this.getDocumentsFolderPath();
+	}
 
 	public getTempFolderPath(): string {
 		return this.getKnownPath(NSSearchPathDirectory.CachesDirectory);
diff --git a/packages/core/file-system/index.d.ts b/packages/core/file-system/index.d.ts
index 572c19bd8..80c1a55e1 100644
--- a/packages/core/file-system/index.d.ts
+++ b/packages/core/file-system/index.d.ts
@@ -217,6 +217,13 @@ export module knownFolders {
 	 */
 	export function documents(): Folder;
 
+	/**
+	 * Gets the Documents folder available for the current application on an external storage. This Folder is private for the application and not accessible from Users/External apps.
+	 * On android this requires READ_EXTERNAL_STORAGE/WRITE_EXTERNAL_STORAGE permissions
+	 * There is no external storage on iOS os it is the same as `documents()`
+	 */
+	export function externalDocuments(): Folder;
+
 	/**
 	 * Gets the Temporary (Caches) folder available for the current application. This Folder is private for the application and not accessible from Users/External apps.
 	 */
diff --git a/packages/core/file-system/index.ts b/packages/core/file-system/index.ts
index 6a694fddc..6dac9e918 100644
--- a/packages/core/file-system/index.ts
+++ b/packages/core/file-system/index.ts
@@ -548,6 +548,7 @@ export class Folder extends FileSystemEntity {
 
 export namespace knownFolders {
 	let _documents: Folder;
+	let _externalDocuments: Folder;
 	let _temp: Folder;
 	let _app: Folder;
 
@@ -562,6 +563,17 @@ export namespace knownFolders {
 		return _documents;
 	}
 
+	export function externalDocuments(): Folder {
+		if (!_externalDocuments) {
+			const path = getFileAccess().getExternalDocumentsFolderPath();
+			_externalDocuments = new Folder();
+			_externalDocuments._path = path;
+			_externalDocuments._isKnown = true;
+		}
+
+		return _externalDocuments;
+	}
+
 	export function temp(): Folder {
 		if (!_temp) {
 			const path = getFileAccess().getTempFolderPath();