v0.3.0

Major release focused on support for Storage Access Framework.

Breaking Changes

• minSdkVersion set to 19.
• getMediaStoreContentDirectory return type changed to Uri.
• Import package directive path is now modular. Which means you need to import the modules you are using:
  • import 'package:shared_storage/saf.dart' as saf; to enable Storage Access Framework API.
  • import 'package:shared_storage/environment.dart' as environment; to enable Environment API.
  • import 'package:shared_storage/media_store.dart' as mediastore; to enable Media Store API.
  • import 'package:shared_storage/shared_storage' as sharedstorage; if you want to import all above and as a single module (Not recommended because can conflict/override names/methods).

New Features

See the label reference here.

• Original listFiles. This API does the same thing as DocumentFile.listFiles but through Android queries and not calling directly the DocumentFile.listFiles API for performance reasons.

• Internal DocumentFile from DocumentFile SAF class.

• Internal QueryMetadata metadata of the queries used by listFiles API.

• Internal PartialDocumentFile. Represents a partial document file returned by listFiles API.

• openDocumentTree now accepts grantWritePermission and initialUri params which, respectively, sets whether or not grant write permission level and the initial uri location of the folder authorization picker.

• Mirror DocumentFileColumn from DocumentsContract.Document.<Column> SAF class.

• Mirror canRead from DocumentFile.canRead. Returns true if the caller can read the given uri.

• Mirror canWrite from DocumentFile.canWrite. Returns true if the caller can write to the given uri.

• Mirror getDocumentThumbnail from DocumentsContract.getDocumentThumbnail. Returns the image thumbnail of a given uri, if any (e.g documents that can show a preview, like image or pdf, otherwise null).

• Mirror exists from DocumentsContract.exists. Returns true if a given uri exists.

• Mirror buildDocumentUriUsingTree from DocumentsContract.buildDocumentUriUsingTree.

• Mirror buildDocumentUri from DocumentsContract.buildDocumentUri.

• Mirror buildTreeDocumentUri from DocumentsContract.buildTreeDocumentUri.

• Mirror delete from DocumentFile.delete. Self explanatory.

• Mirror createDirectory from DocumentFile.createDirectory. Creates a new child document file that represents a directory given the displayName (folder name).

• Alias createFile. Alias for createFileAsBytes or createFileAsString depending which params are provided.

• Mirror createFileAsBytes from DocumentFile.createFile. Given the parent uri, creates a new child document file that represents a single file given the displayName, mimeType and its content in bytes (file name, file type and file content in raw bytes, respectively).

• Alias createFileAsString. Alias for createFileAsBytes(bytes: Uint8List.fromList('file content...'.codeUnits)).

• Mirror documentLength from DocumentFile.length. Returns the length of the given file (uri) in bytes. Returns 0 if the file does not exist, or if the length is unknown.

• Mirror lastModified from DocumentFile.lastModified. Returns the time when the given file (uri) was last modified, measured in milliseconds since January 1st, 1970, midnight. Returns 0 if the file does not exist, or if the modified time is unknown.

• Mirror findFile from DocumentFile.findFile. Search through listFiles() for the first document matching the given display name, this method has a really poor performance for large data sets, prefer using child instead.

• Mirror fromTreeUri from DocumentFile.fromTreeUri.

• Mirror renameTo from DocumentFile.renameTo. Rename a document file given its uri to the given displayName.

• Mirror parentFile from DocumentFile.parentFile. Get the parent document of the given document file from its uri.

• Mirror copy from DocumentsContract.copyDocument. Copies the given document to the given destination.

• Original getDocumentContent. Read a document file from its uri by opening a input stream and returning its bytes.

• External child from com.anggrayudi.storage.file.DocumentFile.child. Find the child file of a given parent uri and child name, null if doesn't exists (faster than findFile).

• Original UNSTABLE openDocumentFile. Open a file uri in a external app, by starting a new activity with ACTION_VIEW Intent.

• Original UNSTABLE getRealPathFromUri. Return the real path to work with native old File API instead Uris, be aware this approach is no longer supported on Android 10+ (API 29+) and though new, this API is marked as deprecated and should be migrated to a scoped-storage approach.

• Alias getDocumentContentAsString. Alias for getDocumentContent. Convert all bytes returned by the original method into a String.

• Internal DocumentBitmap class added. Commonly used as thumbnail image/bitmap of a DocumentFile.

• Extension UriDocumentFileUtils on Uri (Accesible by uri.extensionMethod(...)).

  • Alias toDocumentFile. Alias for DocumentFile.fromTreeUri(this) which is an alias for fromTreeUri. method: convert this to the respective DocumentFile (if exists, otherwise null).
  • Alias openDocumentFile. Alias for openDocumentFile.

• Mirror getDownloadCacheDirectory from Environment.getDataDirectory.

• Mirror getStorageDirectory from Environment.getStorageDirectory.

Deprecation Notices

• getExternalStoragePublicDirectory was marked as deprecated and should be replaced with an equivalent API depending on your use-case, see how to migrate getExternalStoragePublicDirectory. This deprecation is originated from official Android documentation and not by the plugin itself.