Trait AndroidFs

pub trait AndroidFs {
    // Required methods
    fn get_name(&self, uri: &FileUri) -> Result<String>;
    fn get_mime_type(&self, uri: &FileUri) -> Result<Option<String>>;
    fn open_file(&self, uri: &FileUri, mode: FileAccessMode) -> Result<File>;
    fn remove_file(&self, uri: &FileUri) -> Result<()>;
    fn remove_dir(&self, uri: &FileUri) -> Result<()>;
    fn create_file(
        &self,
        dir: &FileUri,
        relative_path: impl AsRef<str>,
        mime_type: Option<&str>,
    ) -> Result<FileUri>;
    fn create_file_in_public_location(
        &self,
        dir: impl Into<PublicDir>,
        relative_path: impl AsRef<str>,
        mime_type: Option<&str>,
    ) -> Result<FileUri>;
    fn read_dir(&self, uri: &FileUri) -> Result<impl Iterator<Item = Entry>>;
    fn take_persistable_uri_permission(
        &self,
        uri: FileUri,
        mode: PersistableAccessMode,
    ) -> Result<()>;
    fn show_open_file_dialog(
        &self,
        mime_types: &[&str],
        multiple: bool,
    ) -> Result<Vec<FileUri>>;
    fn show_open_visual_media_dialog(
        &self,
        target: VisualMediaTarget,
        multiple: bool,
    ) -> Result<Vec<FileUri>>;
    fn show_open_dir_dialog(&self) -> Result<Option<FileUri>>;
    fn show_save_file_dialog(
        &self,
        default_file_name: impl AsRef<str>,
        mime_type: Option<&str>,
    ) -> Result<Option<FileUri>>;
    fn is_visual_media_dialog_available(&self) -> Result<bool>;
    fn is_public_audiobooks_dir_available(&self) -> Result<bool>;
    fn is_public_recordings_dir_available(&self) -> Result<bool>;
    fn private_storage(&self) -> &impl PrivateStorage;

    // Provided methods
    fn is_available(&self) -> bool { ... }
    fn get_metadata(&self, uri: &FileUri) -> Result<Metadata> { ... }
    fn read(&self, uri: &FileUri) -> Result<Vec<u8>> { ... }
    fn read_to_string(&self, uri: &FileUri) -> Result<String> { ... }
    fn write(&self, uri: &FileUri, contents: impl AsRef<[u8]>) -> Result<()> { ... }
}

API

Required Methods

fn get_name(&self, uri: &FileUri) -> Result<String>

Get the file or directory name.

Support

All Android version.

fn get_mime_type(&self, uri: &FileUri) -> Result<Option<String>>

Query the provider to get mime type.
If the directory, this returns None.
If the file, this returns no None.
If the file type is unknown or unset, this returns Some("application/octet-stream").

Support

All Android version.

fn open_file(&self, uri: &FileUri, mode: FileAccessMode) -> Result<File>

Open a file in the specified mode.

Note

Other than FileAccessMode::Read is only for writable uri.

Support

All Android version.

fn remove_file(&self, uri: &FileUri) -> Result<()>

Remove the file.

Note

This is only for removeable uri.

Support

All Android version.

fn remove_dir(&self, uri: &FileUri) -> Result<()>

Remove the empty file.

Note

This is only for removeable uri.

Support

All Android version.

fn create_file( &self, dir: &FileUri, relative_path: impl AsRef<str>, mime_type: Option<&str>, ) -> Result<FileUri>

Creates a new file at the specified directory, and returns read-write-removeable uri.
If the same file name already exists, a sequential number is added to the name. And recursively create sub directories if they are missing.

If you want to create a new file without a FileUri, use AndroidFs::create_file_in_public_location.

Note

mime_type specify the type of the file to be created. It should be provided whenever possible. If not specified, application/octet-stream is used, as generic, unknown, or undefined file types.

Support

All Android version.

fn create_file_in_public_location( &self, dir: impl Into<PublicDir>, relative_path: impl AsRef<str>, mime_type: Option<&str>, ) -> Result<FileUri>

Creates a new file at the specified public location, and returns read-write-removeable uri.
If the same file name already exists, a sequential number is added to the name. And recursively create sub directories if they are missing.

Note

mime_type specify the type of the file to be created. It should be provided whenever possible. If not specified, application/octet-stream is used, as generic, unknown, or undefined file types.

Support

All Android version.

fn read_dir(&self, uri: &FileUri) -> Result<impl Iterator<Item = Entry>>

Returns the unordered child entries of the specified directory.
Returned Entry contains file or directory uri.

Note

By default, children are valid until the app is terminated.
To persist it across app restarts, use AndroidFs::take_persistable_uri_permission. However, if you have obtained persistent permissions for the origin directory (e.g. parent, grand parents), it is unnecessary.

The returned type is an iterator because of the data formatting and the file system call is not executed lazily.

Support

All Android version.

fn take_persistable_uri_permission( &self, uri: FileUri, mode: PersistableAccessMode, ) -> Result<()>

Take persistent permission to access the file, directory and its descendants.

Preserve access across app and device restarts. If you only need it until the end of the app session, you do not need to use this.

This works by just calling, without displaying any confirmation to the user.

Note

Even after calling this, the app doesn’t retain access to the entry if it is moved or deleted.

Support

All Android version.

fn show_open_file_dialog( &self, mime_types: &[&str], multiple: bool, ) -> Result<Vec<FileUri>>

Open a dialog for file selection.
This returns a read-only uris. If no file is selected or canceled by user, it is an empty.

For images and videos, consider using AndroidFs::show_open_visual_media_dialog instead.

Issue

Dialog has an issue. Details and resolution are following.
https://github.com/aiueo13/tauri-plugin-android-fs/issues/1

Note

mime_types represents the types of files that should be selected. However, there is no guarantee that the returned file will match the specified types.
If this is empty, all file types will be available for selection. This is equivalent to ["*/*"], and it will invoke the standard file picker in most cases.

By default, returned uri is valid until the app is terminated. If you want to persist it across app restarts, use AndroidFs::take_persistable_uri_permission.

Support

All Android version.

fn show_open_visual_media_dialog( &self, target: VisualMediaTarget, multiple: bool, ) -> Result<Vec<FileUri>>

Opens a dialog for media file selection, such as images and videos.
This returns a read-only uris. If no file is selected or canceled by user, it is an empty.

This is more user-friendly than AndroidFs::show_open_file_dialog.

Issue

Dialog has an issue. Details and resolution are following.
https://github.com/aiueo13/tauri-plugin-android-fs/issues/1

Note

By default, returned uri is valid until the app is terminated. If you want to persist it across app restarts, use AndroidFs::take_persistable_uri_permission.

The file obtained from this function cannot retrieve the correct file name using AndroidFs::get_name. Instead, it will be assigned a sequential number, such as 1000091523.png.
https://issuetracker.google.com/issues/268079113

Support

This is available on devices that meet the following criteria:

• Run Android 11 (API level 30) or higher
• Receive changes to Modular System Components through Google System Updates

Availability on a given device can be verified by calling AndroidFs::is_visual_media_dialog_available.
If not supported, this functions the same as AndroidFs::show_open_file_dialog.

fn show_open_dir_dialog(&self) -> Result<Option<FileUri>>

Open a dialog for directory selection, allowing the app to read and write any file in the selected directory and its subdirectories.
If canceled by the user, return None.

Issue

Dialog has an issue. Details and resolution are following.
https://github.com/aiueo13/tauri-plugin-android-fs/issues/1

Note

By default, retruned uri is valid until the app is terminated. If you want to persist it across app restarts, use AndroidFs::take_persistable_uri_permission. If you take permission for a directory, you can recursively obtain it for its descendants.

Support

All Android version.

fn show_save_file_dialog( &self, default_file_name: impl AsRef<str>, mime_type: Option<&str>, ) -> Result<Option<FileUri>>

Open a dialog for file saving, and return the selected path.
This returns a read-write-removeable uri. If canceled by the user, return None.

When storing media files such as images, videos, and audio, consider using AndroidFs::create_file_in_public_location.
When a file does not need to be accessed by other applications and users, consider using PrivateStorage::write.
These are easier because the destination does not need to be selected in a dialog.

Issue

Dialog has an issue. Details and resolution are following.
https://github.com/aiueo13/tauri-plugin-android-fs/issues/1

Note

mime_type specify the type of the target file to be saved. It should be provided whenever possible. If not specified, application/octet-stream is used, as generic, unknown, or undefined file types.

By default, returned uri is valid until the app is terminated. If you want to persist it across app restarts, use AndroidFs::take_persistable_uri_permission.

Support

All Android version.

fn is_visual_media_dialog_available(&self) -> Result<bool>

Verify whether AndroidFs::show_open_visual_media_dialog is available on a given device.

Support

All Android version.

fn is_public_audiobooks_dir_available(&self) -> Result<bool>

Verify whether PublicAudioDir::Audiobooks is available on a given device.

Support

All Android version.

fn is_public_recordings_dir_available(&self) -> Result<bool>

Verify whether PublicAudioDir::Recordings is available on a given device.

Support

All Android version.

fn private_storage(&self) -> &impl PrivateStorage

File storage API intended for the app’s use only.

Provided Methods

fn is_available(&self) -> bool

Verify whether this plugin is available.

On Android, this returns true.
On other platforms, this returns false.

fn get_metadata(&self, uri: &FileUri) -> Result<Metadata>

Queries the file system to get information about a file, directory.

Note

This uses AndroidFs::open_file internally.

Support

All Android version.

fn read(&self, uri: &FileUri) -> Result<Vec<u8>>

Reads the entire contents of a file into a bytes vector.

If you need to operate the file, use AndroidFs::open_file instead.

Support

All Android version.

fn read_to_string(&self, uri: &FileUri) -> Result<String>

Reads the entire contents of a file into a string.

If you need to operate the file, use AndroidFs::open_file instead.

Support

All Android version.

fn write(&self, uri: &FileUri, contents: impl AsRef<[u8]>) -> Result<()>

Writes a slice as the entire contents of a file.
This function will entirely replace its contents if it does exist.

If you want to operate the file, use AndroidFs::open_file instead.

Note

This is only for writable file uri.

Support

All Android version.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors