Implement directory picking and related functions

[amake]

Note: This PR includes the changes in #19, so you might want to review that one first.

This PR addresses #16 by adding the following functions:

• FilePickerWritable.openDirectory
• FilePickerWritable.getDirectory
• FilePickerWritable.resolveRelativePath
• FilePickerWritable.isDirectoryAccessSupported

Please see the dartdoc comments of each for details.

To represent the result of picking a directory or resolving a relative path to a directory, I have introduced the DirectoryInfo class. Because the result of resolveRelativePath could be either a file or a directory, I have moved the bulk of FileInfo into a new abstract class EntityInfo from which both FileInfo and DirectoryInfo inherit (both classes have the same properties for now). See #16 (comment) for additional discussion of this design decision.

Android details

Android only supports obtaining persistable directory access on API 21 (Android 5 "Lollipop") and later, but this plugin supports back to API 19. I have maintained compatibility with this PR; users are expected to use isDirectoryAccessSupported to check if directory access is supported before calling any of the other new functions.

Another wrinkle is that one of the core primitives required to implement getDirectory (and resolve .. in resolveRelativePath), DocumentsContract#findDocumentPath, is only available on API 26 (Android 8 "Oreo"). To support getDirectory on prior OSes I implemented a potentially very costly breadth-first recursive search through the filesystem. It works, but the experience could be quite poor if the user has a lot of files, or if the root is far removed from the target file.

(On Android 7 and earlier you currently can't resolve .. above your start point. This could be improved, but I'm not sure how to make the API clear enough to be usable.)

Android URIs

To make sense of the Android implementation you need to know the following about Android Storage Access Framework URIs.

There are three kinds of URI that we care about:

• "Document" URIs like content://com.android.externalstorage.documents/document/primary%3ADocuments%2Ffoo%bar.txt
  • This points at the document with ID Documents/foo/bar.txt in primary storage
  • This is what you get from the file picker if you pick the file Documents/foo/bar.txt
• "Tree" URIs like content://com.android.externalstorage.documents/tree/primary%3ADocuments
  • This points at the directory tree with ID Documents in primary storage
  • This is what you get from the directory picker if you pick Documents
• "Tree+Document" URIs like content://com.android.externalstorage.documents/tree/primary%3ADocuments/document/primary%3ADocuments%2Ffoo%bar.txt
  • This points to the document with ID Documents/foo/bar.txt under the directory tree Documents, both in primary storage
  • This kind of URI needs to be built via methods in DocumentsContract
  • This kind of URI is what you need to supply when accessing documents for which you don't have explicit permission, when they are children in a tree for which you do have permission: the tree part represents your access grant

Much of the code in the Android implementation concerns itself with the manipulation such URIs:

• Ensuring we have the right kind of URI for a given query
• Ensuring we return the right kind of URI from a query
• Discovering the document ID for a given file

The above example URIs are taken from the local storage provider. While you can dissect and make sense of the parts of these URIs, so you might be tempted to try parsing them for easier manipulation, please note that there are various exhortations against doing so in the Android documentation:

Each document has a unique identifier within that provider. This identifier is an opaque implementation detail of the provider, and as such it must not be parsed.

(source)

Compatibility

Unfortunately directory access is not widely supported by third-party apps. The only sources that work are:

• Android
  • Local storage
  • Seafile (not tested)
  • Termux (not tested)
• iOS
  • Local storage
  • iCloud Drive

Apps confirmed to not support directory access include Dropbox, Google Drive, and FileBrowser.

Intended use case

I have implemented these features for use in my app, Orgro, which is a viewer for Org Mode files. My use case is:

1. User selects a file with the existing file picker
2. The file is analyzed to see if it has relative references to other files (images or links)
3. If isDirectoryAccessSupported returns false then we quit here
4. Otherwise, if the file does have relative links, the app checks to see if it already has persistent access to a directory that contains the opened file
   1. If the app already has access to an appropriate directory, then getDirectory is called to get an identifier for the directory containing the opened file
      1. Relative links are resolved against the directory identifier with resolveRelativePath
      2. The resulting file identifiers are opened with the existing readFile method
   2. If the app does not have access to an appropriate directory, then the user is prompted to select one with openDirectory
      • Go to (4) above

I have this implemented and tested on iOS 14, Android 11, and Android 6.

[amake]

@hpoul Would it help if I broke this PR up into smaller ones?

[amake]

I have been actively using this branch in my app for years now. I will continue to maintain it. I just mention this to note that I am merging other, smaller PRs into it so if you ever do feel like looking at this one, I suggest you merge the others first.

• Do long-running tasks off of UI thread on iOS #43
• Specify Kotlin JVM target #45