Trait AndroidFs

pub trait AndroidFs {
    // Required methods
    fn get_file_name(&self, path: &FilePath) -> Result<String>;
    fn get_mime_type(&self, path: &FilePath) -> Result<Option<String>>;
    fn open_file(&self, path: &FilePath) -> Result<File>;
    fn create_file(&self, path: &FilePath) -> Result<File>;
    fn show_open_file_dialog(
        &self,
        mime_types: &[&str],
        multiple: bool,
    ) -> Result<Vec<FilePath>>;
    fn show_open_visual_media_dialog(
        &self,
        target: VisualMediaTarget,
        multiple: bool,
    ) -> Result<Vec<FilePath>>;
    fn show_save_file_dialog(
        &self,
        default_file_name: impl AsRef<str>,
        mime_type: Option<&str>,
    ) -> Result<Option<FilePath>>;
    fn take_persistable_read_permission(&self, path: &FilePath) -> Result<()>;
    fn take_persistable_write_permission(&self, path: &FilePath) -> Result<()>;
    fn is_visual_media_dialog_available(&self) -> Result<bool>;
    fn public_storage(&self) -> &impl PublicStorage;
    fn private_storage(&self) -> &impl PrivateStorage;

    // Provided methods
    fn is_available(&self) -> bool { ... }
    fn open_file_writable(&self, path: &FilePath) -> Result<File> { ... }
    fn read(&self, path: &FilePath) -> Result<Vec<u8>> { ... }
    fn read_to_string(&self, path: &FilePath) -> Result<String> { ... }
    fn write(&self, path: &FilePath, contetns: impl AsRef<[u8]>) -> Result<()> { ... }
    fn show_save_file_dialog_with_contents(
        &self,
        default_file_name: impl AsRef<str>,
        mime_type: Option<&str>,
        contents: impl AsRef<[u8]>,
    ) -> Result<Option<FilePath>> { ... }
    fn pubic_storage(&self) -> &impl PublicStorage { ... }
}

API

Required Methods

fn get_file_name(&self, path: &FilePath) -> Result<String>

Get the file name.

FilePath can be obtained from functions such as AndroidFs::show_open_file_dialog, AndroidFs::show_open_visual_media_dialog, or AndroidFs::show_save_file_dialog.

Support

All Android version.

fn get_mime_type(&self, path: &FilePath) -> Result<Option<String>>

Get the mime type.
If the type is unknown, this returns None. And this mime type might differ from the file name extension.

FilePath can be obtained from functions such as AndroidFs::show_open_file_dialog, AndroidFs::show_open_visual_media_dialog, or AndroidFs::show_save_file_dialog.

Support

All Android version.

fn open_file(&self, path: &FilePath) -> Result<File>

Open a file in read-only mode.

If you only need to read the entire file contents, consider using AndroidFs::read or AndroidFs::read_to_string instead.

FilePath can be obtained from functions such as AndroidFs::show_open_file_dialog or AndroidFs::show_open_visual_media_dialog.

Support

All Android version.

fn create_file(&self, path: &FilePath) -> Result<File>

Opens a file in write-only mode from writable FilePath.
This function will create a file if it does not exist, and will truncate it if it does.

If you only need to write the contents, consider using AndroidFs::write instead.

Note

A writable FilePath can be obtained from AndroidFs::show_save_file_dialog, but NOT from AndroidFs::show_open_file_dialog or AndroidFs::show_open_visual_media_dialog.

Support

All Android version.

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

Open a dialog for file selection.
This returns a readonly FilePath vec. If no file is selected or canceled by user, it is an empty vec.

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

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, this FilePath is valid until the app is terminated. If you want to persist it across app restarts, use AndroidFs::take_persistable_read_permission.

Support

All Android version.

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

Opens a dialog for media file selection, such as images and videos.
This returns a readonly FilePath vec. If no file is selected or canceled by user, it is an empty vec.

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

Note

By default, this FilePath is valid until the app is terminated. If you want to persist it across app restarts, use AndroidFs::take_persistable_read_permission.

The file obtained from this function cannot retrieve the correct file name using AndroidFs::get_file_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_save_file_dialog( &self, default_file_name: impl AsRef<str>, mime_type: Option<&str>, ) -> Result<Option<FilePath>>

Open a dialog for file saving, and return the selected path.
This returns a writable FilePath . If canceled by the user, return None.

If you only need to write contents, use AndroidFs::show_save_file_dialog_with_contents instead.

When storing media files such as images, videos, and audio, consider using PublicStorage::write_image or a similar method.
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.

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, this FilePath is valid until the app is terminated. If you want to persist it across app restarts, use AndroidFs::take_persistable_read_permission or AndroidFs::take_persistable_write_permission.

Support

All Android version.

fn take_persistable_read_permission(&self, path: &FilePath) -> Result<()>

Take persistent permission to read the file.

To preserve access to files across app restarts and improve the user experience. If you only need it until the end of the app session, you do not need to use this.

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

Note

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

Helper

There are helper functions, such as convert_file_path_to_string and convert_string_to_file_path, for storing FilePath.

fn take_persistable_write_permission(&self, path: &FilePath) -> Result<()>

Take persistent permission to write the file.
This is only for writable FilePath.

To preserve access to files across app restarts and improve the user experience. If you only need it until the end of the app session, you do not need to use this.

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

Note

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

Helper

There are helper functions, such as convert_file_path_to_string and convert_string_to_file_path, for storing FilePath.

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 public_storage(&self) -> &impl PublicStorage

File storage API intended to be shared with other apps.

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 open_file_writable(&self, path: &FilePath) -> Result<File>

👎Deprecated: Because inappropriate fn name. Use AndroidFs::create_file insted.

This is deprecated. Because inappropriate fn name.
Use AndroidFs::create_file insted.

fn read(&self, path: &FilePath) -> Result<Vec<u8>>

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

If you need to operate on a readable file, use AndroidFs::open_file instead.

FilePath can be obtained from functions such as AndroidFs::show_open_file_dialog or AndroidFs::show_open_visual_media_dialog.

Support

All Android version.

fn read_to_string(&self, path: &FilePath) -> Result<String>

Reads the entire contents of a file into a string.

If you need to operate on a readable file, use AndroidFs::open_file instead.

FilePath can be obtained from functions such as AndroidFs::show_open_file_dialog or AndroidFs::show_open_visual_media_dialog.

Support

All Android version.

fn write(&self, path: &FilePath, contetns: impl AsRef<[u8]>) -> Result<()>

Writes a slice as the entire contents of a file in a writable FilePath.
This function will create a file if it does not exist, and will entirely replace its contents if it does.

If you want to write to a file, use AndroidFs::create_file instead.

Note

A writable FilePath can be obtained from AndroidFs::show_save_file_dialog, but not from AndroidFs::show_open_file_dialog or AndroidFs::show_open_visual_media_dialog.

Support

All Android version.

fn show_save_file_dialog_with_contents( &self, default_file_name: impl AsRef<str>, mime_type: Option<&str>, contents: impl AsRef<[u8]>, ) -> Result<Option<FilePath>>

Open a dialog for file saving, and write contents to the selected file, then return that path.
This returns a writable FilePath . If canceled by the user, return None, and do not write it.

If you want to write to a file, use AndroidFs::show_save_file_dialog then AndroidFs::create_file insted.

When storing media files such as images, videos, and audio, consider using PublicStorage::write_image or a similar method.
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.

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, this FilePath is valid until the app is terminated. If you want to persist it across app restarts, use AndroidFs::take_persistable_read_permission or AndroidFs::take_persistable_write_permission.

Support

All Android version.

fn pubic_storage(&self) -> &impl PublicStorage

👎Deprecated: This is typo. Use AndroidFs::public_storage instead.

This is typo and deprecated.
Use AndroidFs::public_storage instead.

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