SAF: App Inventor implementation of Storage Access Framework

vknow360 · September 17, 2021, 4:05pm

1.Introduction

Description: Basically AI2 wrapper of Storage Access Framework. Using this extension, you can get read and/or write access to a single document or tree document (and all of its children recursively).
Latest Version: 1.3
Released: 2021-09-16T18:30:00Z
Last Updated: 2023-11-15T18:30:00Z

2.Blocks

3.Documentation

Events

ErrorOccurred	Event indicating error/exception has occurred and returns origin method and error message. _{methodName \| text errorMessage \| text}
DocumentCreated	Event invoked after creating document.Returns document's uri if operation was successful else returns error message _{uriString \| text}
GotWriteResult	Event invoked after writing to document.Returns document's uri if operation was successful else returns error message _{response \| text}
GotReadResult	Event invoked after reading from document.Returns content if operation was successful else returns error message _{result \| any}
GotUri	Event invoked when user selects a document or tree from SAF file picker _{uri \| any uriString \| text}
GotFilesList	Event invoked after getting files list _{filesList \| list}
GotCopyResult	Event invoked after getting copy document result.Response will be target document's uri if operation was successful else returns error message _{successful \| boolean response \| text}
GotMoveResult	Event invoked after getting move document result.Response will be target document's uri if operation was successful else returns error message _{successful \| boolean response \| text}
DocumentCopiedToFile	Event raised after getting 'CopyDocumentToFile' result _{successful \| boolean response \| text}
DocumentCopiedFromFile	Event raised after getting 'CopyDocumentFromFile' result _{successful \| boolean response \| text}

Methods

CreateFlags	Combines two flags and returns resulting flag _{f1 \| number f2 \| number}
StringFromUriObject	Convert uri to string _{uri \| any}
StringToUriObject	Converts string to uri _{uriString \| text}
InitialDir	Returns uri which can be used as Initial Dir in SAF picker _{dir \| text}
OpenDocumentTree	Prompts user to select a document tree _{title \| text initialDir \| text}
OpenSingleDocument	Prompts user to select a single file _{title \| text initialDir \| text type \| text extraMimeTypes \| list}
TakePersistableUriPermission	Take a persistable URI permission grant that has been offered. Once taken, the permission grant will be remembered across device reboots. _{uri \| any flags \| number}
IsTreeUri	Returns whether given uri is a tree uri _{uriString \| text}
IsDocumentUri	Returns whether given uri is a document uri _{uriString \| text}
IsChildDocumentUri	Returns whether second uri is child of first uri _{parentUri \| text childUri \| text}
GetTreeDocumentId	Returns document id of tree uri (should be either tree uri itself or a direct child uri) _{uriString \| text}
GetDocumentId	Returns document id of an uri (should only be grand child) _{uriString \| text}
BuildDocumentUriUsingTree	Builds document uri using tree uri and document id _{treeUri \| text documentId \| text}
BuildChildDocumentsUriUsingTree	Builds child documents id using tree (documents which is child of parent document) uri and its parent document id _{treeUri \| text parentDocumentId \| text}
GetDisplayName	Returns display name of given document uri _{documentUri \| text}
GetSize	Returns size (in bytes) of given document uri _{documentUri \| text}
GetLastModifiedTime	Returns last modified time (epoch) of given document uri _{documentUri \| text}
GetMimeType	Returns mime type of given document uri _{documentUri \| text}
IsCopySupported	Returns whether document can be copied or not _{documentUri \| text}
IsMoveSupported	Returns whether document is movable or not _{documentUri \| text}
IsDeleteSupported	Returns whether document is deletable or not _{documentUri \| text}
IsRenameSupported	Returns whether document is deletable or not _{documentUri \| text}
CreateDocument	Creates a new and empty document.If document already exists then an incremental value will be suffixed. _{parentDocumentUri \| text fileName \| text mimeType \| text}
WriteToFile	Writes content as text to given uri _{uriString \| text content \| text}
WriteAsHexString	Writes content as HEX to given uri _{uriString \| text content \| text}
WriteAsByteArray	Writes byte array to given document _{uriString \| text byteArray \| any}
DeleteDocument	Tries to delete document from given uri and returns result _{uriString \| text}
ReadFromFile	Reads from given document as text _{uriString \| text}
ReadAsByteArray	Reads content of document as byte array _{uriString \| text}
ReadAsHexString	Reads content of document as HEX string _{uriString \| text}
IsReadGranted	Returns whether read is available for given uri _{uri \| text}
ReleasePermission	Relinquish a persisted URI permission grant _{uri \| text flags \| number}
IsWriteGranted	Returns whether write is available for given uri _{uri \| text}
ListFiles	Tries to list files from given dir _{dirUri \| text dirDocumentId \| text}
CopyDocument	Tries to copy document from source uri to target dir _{sourceUri \| text targetParentUri \| text}
MoveDocument	Tries to move document from source uri to target dir _{sourceUri \| text sourceParentUri \| text targetParentUri \| text}
RenameDocument	Tries to rename a document and returns updated uri _{documentUri \| text displayName \| text}
CopyDocumentToFile	Tries to copy document from source uri to specified folder _{sourceUri \| text dirPath \| text}
CopyDocumentFromFile	_{filePath \| text targetParentUri \| text}
ConvertStringToBytes	Converts text to bytes and return Byte Array object. It can be used with 'WriteAsByteArray' method. _{byteString \| text}
CreateDocumentSync	Creates document on main thread and returns its uri immediately if operation was successful otherwise empty string is returned _{parentDocumentUri \| text fileName \| text mimeType \| text}

Properties

DocumentDirMimeType	Returns mime type of document dir Property Type : read-only Accepts : text
FlagGrantReadPermission	Flag to get write permission Property Type : read-only Accepts : number
FlagGrantWritePermission	Flag to get read permission Property Type : read-only Accepts : number

4.Usages

1.Open document tree

2.Get access (not necessary for one-time usage)

3.Build child document uri

if document is direct child

if document is grandchild

4.Read file/Set picture

Examples by Power Users
I am thankful to them for their efforts.

5.Download

Aix:
com.sunny.saf.aix (29.2 KB)

6.Open Source

7.Liked my work/Want to donate

Thank you

8. ChangeLog

ChangeLog Version 1.1

New Blocks

Changes

Removed category param from OpenSingleDocument method
GotCopyResult and GotMoveResult now return resulting/target document's uri

Bug Fixes

Fixed issue in write methods
Fixed null pointer exception when SAF picker was cancelled by user

ChangeLog Version 1.2

SAF: App Inventor implementation of Storage Access Framework - #331 by vknow360

ChangeLog Version 1.3

SAF: App Inventor implementation of Storage Access Framework - #360 by vknow360

Thank you.
Hope it helps!

Anke · September 17, 2021, 4:14pm

What an amazing extension ! Great job!
I’ve only done a few tests and it seems to be working so far.

And it's a shame that your extensions need approval in AI2.
We should change that as soon as possible!

ABG · September 17, 2021, 4:16pm

This looks important.

But I am not sure exactly what constitutes a document here.

Surely not a Microsoft .doc file?
A .html file with links to other .html files nearby?
an in-memory runtime structure ?

vknow360 · September 17, 2021, 4:21pm

We can consider document as strictive version of normal files, which are accessible only via URIs.
File class is part of java.io while Document/ Document File is implementation of Google for File System to give user more control over his device , files and privacy.

ABG · September 17, 2021, 4:25pm

That java.io link sent me into some kind of UAE discussion group.
I was expecting a documentation page for java, maybe under oracle.com?

Kumaraswamy · September 17, 2021, 4:31pm

I guess he did not mean to link any resource but just referring the java.io system.

Salman_Dev · September 17, 2021, 4:44pm

For Real

That is the Best Extension, Good Job

Know_About_IT · September 18, 2021, 6:25am

Epic work @vknow360

TIMAI2 · September 18, 2021, 11:16am

As @ABG says, this looks important, but I am guessing that most developers (which includes me) are not in the lucky 10,000 on this one, and therefore haven't got a clue as to what this is about our how they might use it in their apps. The example blocks give an inkling, but don't really help. Could a better description be provided, in layman's terms, of What this extension does, Why/When/Where one might use it, and How it works in more detail?

I am certain the work adds value to the AI2 development experience, especially in these times of Google privacy concerns and file location lockdown, but there is little point saying "great extension" in a post, if I have no understanding of what it does.

vknow360 · September 18, 2021, 11:52am

Yes, SAF is quite complicated to understand because Google had no time to explain why they decided to strict app's access to file system. Most developers felt homely by using legacy "File" approach, but launching of Android 10 started causing troubles for them and SAF is the solution to most of their problems.
Using this, you can-

access phone storage*
access SD card*
read from/write to files created by other apps
help user in protecting his/her data and restrict Storage consumed by apps
get access to files and folders which are important to your app.
In this way, you needn't ask for MANAGE_EXTERNAL_STORAGE permission.
work with non-media files too, such as creating a CSV file of user's data or accessing a PDF file

*: Android/data and Android/obb folders are exception

One major advantage I would like to emphasize is usage of URIs instead of paths.

vknow360 · September 18, 2021, 2:03pm

Example 2

Open document picker and create document

image1036×450 46.8 KB

(Since you now know how to take persistable permission, so I'll skip that part)
Read and write to document

image761×463 29.9 KB
List files

image973×435 44.6 KB

SteveJG · September 18, 2021, 2:13pm

Developers might also find these links about SAF useful in addition to your nice explanation.

TIMAI2 · September 18, 2021, 2:16pm

Thanks @vknow360 for your explanations, making more sense now as to what one can do with your extension.

TIMAI2 · September 18, 2021, 3:08pm

Well I have fallen at the first hurdle....

Following your first image, when I click the button I am taken to the device's default file manager (or what looks like it), I went to the root folder, the file manager asked me to give permission to this area (to MIT Companion App), then returns me to the project with this error:

vknow360 · September 18, 2021, 3:13pm

I forget to mention that direct child's id should be obtained using GetTreeDocumentId method.

TIMAI2 · September 18, 2021, 3:15pm

Sorry, I used the wrong block

TIMAI2 · September 18, 2021, 3:38pm

OK that all works.

Is there no way then, in order to get started, other than the user going into their file manager and granting a permission, to get the root or other folder (tree)? (Open Document Tree)

Perhaps a uri for the ASD ?

I can see how one can traverse through a file list to find sub (folders) trees, and then list files again and so on. An image component accepts a content uri to display an image. Is this going to be the same for other components needing a file?

vknow360 · September 18, 2021, 3:50pm

No, user must grant access through Documents Picker.

I am not sure about this.
Image component works fine.
Same should be correct for audio and video player.

TIMAI2 · September 18, 2021, 4:18pm

Understood

Anke · September 18, 2021, 4:25pm

SAF is only needed for → non-media files. Media files (jpg, png, mp3, m4a, mp4,...) can be accessed from all paths (outside of the ASD or privateDir) with READ permission.