Trait AndroidFs

pub trait AndroidFs {
    // Required methods
    fn get_file_name(&self, path: &FilePath) -> Result<String>;
    fn get_dir_name(&self, path: &DirPath) -> 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 new_file(
        &self,
        base_dir: &DirPath,
        relative_path: impl AsRef<str>,
        mime_type: Option<&str>,
    ) -> Result<FilePath>;
    fn remove_file(&self, path: &FilePath) -> Result<()>;
    fn read_dir(&self, path: &DirPath) -> Result<Vec<(String, EntryPath)>>;
    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_open_dir_dialog(&self) -> Result<Option<DirPath>>;
    fn show_save_file_dialog(
        &self,
        default_file_name: impl AsRef<str>,
        mime_type: Option<&str>,
    ) -> Result<Option<FilePath>>;
    fn grant_persistable_file_access(
        &self,
        path: &FilePath,
        mode: PersistableAccessMode,
    ) -> Result<()>;
    fn grant_persistable_dir_access(
        &self,
        path: &DirPath,
        mode: PersistableAccessMode,
    ) -> 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 read(&self, path: &FilePath) -> Result<Vec<u8>> { ... }
    fn new_file_with_contents(
        &self,
        base_dir: &DirPath,
        relative_path: impl AsRef<str>,
        mime_type: Option<&str>,
        contents: impl AsRef<[u8]>,
    ) -> Result<FilePath> { ... }
    fn read_to_string(&self, path: &FilePath) -> Result<String> { ... }
    fn write(&self, path: &FilePath, contents: 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 take_persistable_read_permission(&self, path: &FilePath) -> Result<()> { ... }
    fn take_persistable_write_permission(&self, path: &FilePath) -> Result<()> { ... }
}

API

Required Methods

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

Get the file name.

Note

This is a little slow.

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

Support

All Android version.

fn get_dir_name(&self, path: &DirPath) -> Result<String>

Get the directory name.

Note

This is a little slow.

DirPath can be obtained from functions such as AndroidFs::show_open_dir_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.

Note

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.

Note

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.
If you want to create a new file with DirPath, use AndroidFs::new_file.
If you want to create a new file, use PublicStorage::write, PrivateStorage::write.

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 new_file( &self, base_dir: &DirPath, relative_path: impl AsRef<str>, mime_type: Option<&str>, ) -> Result<FilePath>

Creates a new file at the specified location, and return writable FilePath.
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 only need to write the contents, consider using AndroidFs::new_file_with_contents instead.

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

Remove the file from the writable FilePath.

Support

All Android version.

fn read_dir(&self, path: &DirPath) -> Result<Vec<(String, EntryPath)>>

Returns the names and paths of the entries within the specified directory.
The paths are writable FilePath or DirPath.

Note

It also retrieves hidden files and directories, such as the system-generated cache folder .thumbnails. Filter these if necessary.

DirPath can be obtained from functions such as AndroidFs::show_open_dir_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 read-only 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::grant_persistable_file_access.

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 read-only 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::grant_persistable_file_access.

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_open_dir_dialog(&self) -> Result<Option<DirPath>>

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.

Note

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

Support

All Android version.

Related functions

• AndroidFs::new_file
• AndroidFs::new_file_with_contents
• AndroidFs::read_dir
• AndroidFs::get_dir_name
• AndroidFs::grant_persistable_dir_access
• etc…

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

Support

All Android version.

fn grant_persistable_file_access( &self, path: &FilePath, mode: PersistableAccessMode, ) -> Result<()>

Take persistent permission to access the file.

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

PersistableAccessMode::WriteOnly and PersistableAccessMode::ReadAndWrite are only for writable FilePath.

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.

Support

All Android version.

fn grant_persistable_dir_access( &self, path: &DirPath, mode: PersistableAccessMode, ) -> Result<()>

Take persistent permission to access the directory and its entries.

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 directory if the directory is moved or deleted.

Helper

There are helper functions, such as convert_dir_path_to_string and convert_string_to_dir_path, for storing DirPath.

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

Note

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 new_file_with_contents( &self, base_dir: &DirPath, relative_path: impl AsRef<str>, mime_type: Option<&str>, contents: impl AsRef<[u8]>, ) -> Result<FilePath>

Creates a new file at the specified location, and write the entire contents, then return writable FilePath.
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_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, contents: 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::grant_persistable_file_access.

Support

All Android version.

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

👎Deprecated: Use AndroidFs::grant_persistable_file_access instead.

Use AndroidFs::grant_persistable_file_access instead.

This is same as following.

self.grant_persistable_file_access(path, PersistableAccessMode::ReadOnly)

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

👎Deprecated: Use AndroidFs::grant_persistable_file_access instead.

Use AndroidFs::grant_persistable_file_access instead.

This is same as following.

self.grant_persistable_file_access(path, PersistableAccessMode::WriteOnly)

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