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 open_file_writable(&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 is_visual_media_dialog_available(&self) -> Result<bool>;
    fn public_storage(&self) -> &impl PublicStorage;
    fn pubic_storage(&self) -> &impl PublicStorage;
    fn private_storage(&self) -> &impl PrivateStorage;

    // Provided methods
    fn is_available(&self) -> bool { ... }
    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>> { ... }
}

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.

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

Open a file in writable mode from writable FilePath.

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_visiual_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.

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

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 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.

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.

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

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.

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

File storage API intended to be shared with other apps.

fn pubic_storage(&self) -> &impl PublicStorage

👎Deprecated: This is typo. Use public_storage instead.

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 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

If you need to operate on a writable file, use AndroidFs::open_file_writable 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_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.

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.

If you want to operate directly on writable files, use AndroidFs::show_save_file_dialog then AndroidFs::open_file_writable insted.

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.

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