pub struct AndroidFs<R: Runtime> { /* private fields */ }
Expand description
Root API
§Examples
fn example(app: &tauri::AppHandle) {
use tauri_plugin_android_fs::AndroidFsExt;
let api = app.android_fs();
}
Implementations§
Source§impl<R: Runtime> AndroidFs<R>
impl<R: Runtime> AndroidFs<R>
Sourcepub fn is_available(&self) -> bool
pub fn is_available(&self) -> bool
Verify whether this plugin is available.
On Android, this returns true.
On other platforms, this returns false.
Sourcepub fn get_metadata(&self, uri: &FileUri) -> Result<Metadata>
pub fn get_metadata(&self, uri: &FileUri) -> Result<Metadata>
Queries the file system to get information about a file, directory.
§Args
- uri :
Target URI.
This needs to be readable.
§Note
This uses AndroidFs::open_file
internally.
§Support
All.
Sourcepub fn open_file(&self, uri: &FileUri, mode: FileAccessMode) -> Result<File>
pub fn open_file(&self, uri: &FileUri, mode: FileAccessMode) -> Result<File>
Open a file in the specified mode.
§Args
-
uri :
Target file URI.
This must have corresponding permissions (read, write, or both) for the specified mode. -
mode :
Indicates how the file is opened and the permissions granted.
Note that files provided by third-party apps may not supportFileAccessMode::WriteAppend
. (ex: Files on GoogleDrive)
§Note
This method uses a FileDescriptor internally. However, if the target file does not physically exist on the device, such as cloud-based files, the write operation using a FileDescriptor may not be reflected properly. In such cases, consider using AndroidFs::write_via_kotlin, which writes using a standard method, or AndroidFs::write, which automatically falls back to that approach when necessary. If you specifically need to write using std::fs::File not entire contents, see AndroidFs::write_via_kotlin_in or AndroidFs::copy_via_kotlin.
It seems that the issue does not occur on all cloud storage platforms. At least, files on Google Drive have issues,
but files on Dropbox can be written to correctly using a FileDescriptor.
If you encounter issues with cloud storage other than Google Drive, please let me know on Github.
This information will be used in AndroidFs::need_write_via_kotlin used by AndroidFs::write
.
There are no problems with file reading.
§Support
All.
Sourcepub fn read(&self, uri: &FileUri) -> Result<Vec<u8>>
pub 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.
§Args
- uri :
Target file URI.
This needs to be readable.
§Support
All.
Sourcepub fn read_to_string(&self, uri: &FileUri) -> Result<String>
pub 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.
§Args
- uri :
Target file URI.
This needs to be readable.
§Support
All.
Sourcepub fn write(&self, uri: &FileUri, contents: impl AsRef<[u8]>) -> Result<()>
pub 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.
§Args
- uri :
Target file URI.
This needs to be writable.
§Support
All.
Sourcepub fn write_via_kotlin(
&self,
uri: &FileUri,
contents: impl AsRef<[u8]>,
) -> Result<()>
pub fn write_via_kotlin( &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.
Differences from std::fs::File::write_all
is the process is done on Kotlin side.
See AndroidFs::open_file
for why this function exists.
If AndroidFs::write
is used, it automatically fall back to this by AndroidFs::need_write_via_kotlin
,
so there should be few opportunities to use this.
If you want to write using std::fs::File
, not entire contents, use AndroidFs::write_via_kotlin_in
.
§Inner process
The contents is written to a temporary file by Rust side
and then copied to the specified file on Kotlin side by AndroidFs::copy_via_kotlin
.
§Support
All.
Sourcepub fn write_via_kotlin_in<T>(
&self,
uri: &FileUri,
contents_writer: impl FnOnce(&mut File) -> Result<T>,
) -> Result<T>
pub fn write_via_kotlin_in<T>( &self, uri: &FileUri, contents_writer: impl FnOnce(&mut File) -> Result<T>, ) -> Result<T>
See AndroidFs::write_via_kotlin
for information.
Use this if you want to write using std::fs::File
, not entire contents.
If you want to retain the file outside the closure,
you can perform the same operation using AndroidFs::copy_via_kotlin
and PrivateStorage
.
For details, please refer to the internal implementation of this function.
§Args
-
uri :
Target file URI to write. -
contetns_writer :
A closure that accepts a mutable reference to astd::fs::File
and performs the actual write operations. Note that this represents a temporary file.
Sourcepub fn need_write_via_kotlin(&self, uri: &FileUri) -> Result<bool>
pub fn need_write_via_kotlin(&self, uri: &FileUri) -> Result<bool>
Determines if the file needs to be written via Kotlin side instead of Rust side.
Currently, this returns true only if the file is on GoogleDrive.
§Support
All.
Sourcepub fn copy_via_kotlin(&self, src: &FileUri, dest: &FileUri) -> Result<()>
pub fn copy_via_kotlin(&self, src: &FileUri, dest: &FileUri) -> Result<()>
Copies the contents of src file to dest.
This copy process is done on Kotlin side, not on Rust.
Large files in GB units are also supported.
See AndroidFs::write_via_kotlin
for why this function exists.
§Args
-
src :
The URI of source file.
This needs to be readable. -
dest :
The URI of destination file.
This needs to be writable.
§Support
All.
Sourcepub fn remove_file(&self, uri: &FileUri) -> Result<()>
pub fn remove_file(&self, uri: &FileUri) -> Result<()>
Sourcepub fn remove_dir(&self, uri: &FileUri) -> Result<()>
pub fn remove_dir(&self, uri: &FileUri) -> Result<()>
Sourcepub fn remove_dir_all(&self, uri: &FileUri) -> Result<()>
pub fn remove_dir_all(&self, uri: &FileUri) -> Result<()>
Sourcepub fn get_thumbnail_to(
&self,
src: &FileUri,
dest: &FileUri,
preferred_size: Size,
decode: DecodeOption,
) -> Result<bool>
pub fn get_thumbnail_to( &self, src: &FileUri, dest: &FileUri, preferred_size: Size, decode: DecodeOption, ) -> Result<bool>
See AndroidFs::get_thumbnail_to
for descriptions.
If thumbnail does not wrote to dest, return false.
Sourcepub fn get_thumbnail(
&self,
uri: &FileUri,
preferred_size: Size,
decode: DecodeOption,
) -> Result<Option<Vec<u8>>>
pub fn get_thumbnail( &self, uri: &FileUri, preferred_size: Size, decode: DecodeOption, ) -> Result<Option<Vec<u8>>>
Query the provider to get a file thumbnail.
If thumbnail does not exist it, return None.
Note this does not cache. Please do it in your part if need.
§Args
-
uri :
Targe file uri.
Thumbnail availablty depends on the file provider.
In general, images and videos are available.
For files inPrivateStorage
, the file type must match the filename extension. -
preferred_size :
Optimal thumbnail size desired.
This may return a thumbnail of a different size, but never more than double the requested size. In any case, the aspect ratio is maintained. -
decode :
Thumbnail image format.
DecodeOption::Jpeg
is recommended. If you need transparency, use others.
§Support
All.
Sourcepub fn create_file(
&self,
dir: &FileUri,
relative_path: impl AsRef<str>,
mime_type: Option<&str>,
) -> Result<FileUri>
pub fn create_file( &self, dir: &FileUri, relative_path: impl AsRef<str>, mime_type: Option<&str>, ) -> Result<FileUri>
Creates a new empty file in the specified location and returns a URI.
The permissions and validity period of the returned URIs depend on the origin directory
(e.g., the top directory selected by AndroidFs::show_open_dir_dialog
)
§Args
-
dir :
The URI of the base directory.
This needs to be read-write. -
relative_path :
The file path relative to the base directory.
If a file with the same name already exists, a sequential number will be appended to ensure uniqueness.
Any missing subdirectories in the specified path will be created automatically. -
mime_type :
The MIME type of the file to be created.
If this is None, MIME type is inferred from the extension of relative_path and if that fails,application/octet-stream
is used.
§Support
All.
Sourcepub fn read_dir(&self, uri: &FileUri) -> Result<impl Iterator<Item = Entry>>
pub fn read_dir(&self, uri: &FileUri) -> Result<impl Iterator<Item = Entry>>
Returns the child files and directories of the specified directory.
The order of the entries is not guaranteed.
The permissions and validity period of the returned URIs depend on the origin directory
(e.g., the top directory selected by AndroidFs::show_open_dir_dialog
)
§Args
- uri :
Target directory URI.
This needs to be readable.
§Note
The returned type is an iterator because of the data formatting and the file system call is not executed lazily. Thus, for directories with thousands or tens of thousands of elements, it may take several seconds.
§Support
All.
Sourcepub fn show_open_file_dialog(
&self,
initial_location: Option<&FileUri>,
mime_types: &[&str],
multiple: bool,
) -> Result<Vec<FileUri>>
pub fn show_open_file_dialog( &self, initial_location: Option<&FileUri>, mime_types: &[&str], multiple: bool, ) -> Result<Vec<FileUri>>
Opens a system file picker and returns a read-write URIs.
If no file is selected or the user cancels, an empty vec is returned.
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
.
This provides a standardized file explorer-style interface, and also allows file selection from part of third-party apps or cloud storage.
Removing the returned files is also supported in most cases, but note that files provided by third-party apps may not be removable.
§Args
-
initial_location :
Indicate the initial location of dialog.
System will do its best to launch the dialog in the specified entry if it’s a directory, or the directory that contains the specified file if not.
If this is missing or failed to resolve the desired initial location, the initial location is system specific.
This must be a URI taken from following :AndroidFs::resolve_initial_location
AndroidFs::show_open_file_dialog
AndroidFs::show_save_file_dialog
AndroidFs::show_manage_dir_dialog
AndroidFs::read_dir
(withAndroidFs::show_manage_dir_dialog
)
-
mime_types :
The MIME types of the file to be selected.
However, there is no guarantee that the returned file will match the specified types.
If left empty, all file types will be available (equivalent to["*/*"]
). -
multiple :
Indicates whether multiple file selection is allowed.
§Support
All.
§References
https://developer.android.com/reference/android/content/Intent#ACTION_OPEN_DOCUMENT
Sourcepub fn show_open_content_dialog(
&self,
mime_types: &[&str],
multiple: bool,
) -> Result<Vec<FileUri>>
pub fn show_open_content_dialog( &self, mime_types: &[&str], multiple: bool, ) -> Result<Vec<FileUri>>
Opens a file picker and returns a readonly URIs.
If no file is selected or the user cancels, an empty vec is returned.
Returned URI is valid until the app is terminated. Can not persist it.
This works differently depending on the model and version.
But recent devices often have the similar behaviour as AndroidFs::show_open_visual_media_dialog
or AndroidFs::show_open_file_dialog
.
Use this, if you want your app to simply read/import data.
§Args
-
mime_types :
The MIME types of the file to be selected.
However, there is no guarantee that the returned file will match the specified types.
If left empty, all file types will be available (equivalent to["*/*"]
). -
multiple :
Indicates whether multiple file selection is allowed.
§Support
All.
§References
https://developer.android.com/reference/android/content/Intent#ACTION_GET_CONTENT
Sourcepub fn show_open_visual_media_dialog(
&self,
target: VisualMediaTarget,
multiple: bool,
) -> Result<Vec<FileUri>>
pub fn show_open_visual_media_dialog( &self, target: VisualMediaTarget, multiple: bool, ) -> Result<Vec<FileUri>>
Opens a media picker and returns a readonly URIs.
If no file is selected or the user cancels, an empty vec is returned.
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
.
This media picker provides a browsable interface that presents the user with their media library, sorted by date from newest to oldest.
§Args
-
target :
The media type of the file to be selected.
Images or videos, or both. -
multiple :
Indicates whether multiple file selection is allowed.
§Note
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
.
And this is marked intended behavior, not a bug.
§Support
This feature is available on devices that meet the following criteria:
- Running 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 function behaves the same as AndroidFs::show_open_file_dialog
.
§References
https://developer.android.com/training/data-storage/shared/photopicker
Sourcepub fn show_manage_dir_dialog(
&self,
initial_location: Option<&FileUri>,
) -> Result<Option<FileUri>>
pub fn show_manage_dir_dialog( &self, initial_location: Option<&FileUri>, ) -> Result<Option<FileUri>>
Opens a system directory picker, allowing the creation of a new directory or the selection of an existing one,
and returns a read-write directory URI.
App can fully manage entries within the returned directory.
If no directory is selected or the user cancels, None
is returned.
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
.
This provides a standardized file explorer-style interface.
§Args
- initial_location :
Indicate the initial location of dialog.
System will do its best to launch the dialog in the specified entry if it’s a directory, or the directory that contains the specified file if not.
If this is missing or failed to resolve the desired initial location, the initial location is system specific.
This must be a URI taken from following :AndroidFs::resolve_initial_location
AndroidFs::show_open_file_dialog
AndroidFs::show_save_file_dialog
AndroidFs::show_manage_dir_dialog
AndroidFs::read_dir
(withAndroidFs::show_manage_dir_dialog
)
§Support
All.
§References
https://developer.android.com/reference/android/content/Intent#ACTION_OPEN_DOCUMENT_TREE
Sourcepub fn show_open_dir_dialog(&self) -> Result<Option<FileUri>>
👎Deprecated: Confusing name. Please use show_manage_dir_dialog instead.
pub fn show_open_dir_dialog(&self) -> Result<Option<FileUri>>
Please use AndroidFs::show_manage_dir_dialog
instead.
Sourcepub fn show_save_file_dialog(
&self,
initial_location: Option<&FileUri>,
initial_file_name: impl AsRef<str>,
mime_type: Option<&str>,
) -> Result<Option<FileUri>>
pub fn show_save_file_dialog( &self, initial_location: Option<&FileUri>, initial_file_name: impl AsRef<str>, mime_type: Option<&str>, ) -> Result<Option<FileUri>>
Opens a dialog to save a file and returns a writeonly URI.
The returned file may be a newly created file with no content,
or it may be an existing file with the requested MIME type.
If the user cancels, None
is returned.
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
.
This provides a standardized file explorer-style interface, and also allows file selection from part of third-party apps or cloud storage.
Removing and reading the returned files is also supported in most cases, but note that files provided by third-party apps may not.
§Args
-
initial_location :
Indicate the initial location of dialog.
System will do its best to launch the dialog in the specified entry if it’s a directory, or the directory that contains the specified file if not.
If this is missing or failed to resolve the desired initial location, the initial location is system specific.
This must be a URI taken from following :AndroidFs::resolve_initial_location
AndroidFs::show_open_file_dialog
AndroidFs::show_save_file_dialog
AndroidFs::show_manage_dir_dialog
AndroidFs::read_dir
(withAndroidFs::show_manage_dir_dialog
)
-
initial_file_name :
An initial file name, but the user may change this value before creating the file. -
mime_type :
The MIME type of the file to be saved.
If this is None, MIME type is inferred from the extension of initial_file_name (not file name by user input) and if that fails,application/octet-stream
is used.
§Support
All.
§References
https://developer.android.com/reference/android/content/Intent#ACTION_CREATE_DOCUMENT
Sourcepub fn resolve_initial_location<'a>(
&self,
dir: impl Into<InitialLocation<'a>>,
create_dirs: bool,
) -> Result<FileUri>
pub fn resolve_initial_location<'a>( &self, dir: impl Into<InitialLocation<'a>>, create_dirs: bool, ) -> Result<FileUri>
Create an restricted URI for the specified directory.
This should only be used as initial_location
in the dialog.
It must not be used for any other purpose.
And this is an informal method and is not guaranteed to work reliably.
But this URI does not cause the dialog to error.
So please use this with the mindset that it’s better than doing nothing.
§Examples
use tauri_plugin_android_fs::{AndroidFs, AndroidFsExt, InitialLocation, PublicGeneralPurposeDir, PublicImageDir};
fn sample(app: tauri::AppHandle) {
let api = app.android_fs();
// Get URI of the top directory
let initial_location = api.resolve_initial_location(
InitialLocation::TopPublicDir,
false,
).expect("Should be on Android");
// Get URI of ~/Pictures/
let initial_location = api.resolve_initial_location(
PublicImageDir::Pictures,
false
).expect("Should be on Android");
// Get URI of ~/Documents/sub_dir1/sub_dir2/
let initial_location = api.resolve_initial_location(
InitialLocation::DirInPublicDir {
base_dir: PublicGeneralPurposeDir::Documents.into(),
relative_path: "sub_dir1/sub_dir2"
},
true // Create dirs of 'sub_dir1' and 'sub_dir2', if not exists
).expect("Should be on Android");
// Open dialog with initial_location
let _ = api.show_save_file_dialog(Some(&initial_location), "", None);
let _ = api.show_open_file_dialog(Some(&initial_location), &[], true);
let _ = api.show_manage_dir_dialog(Some(&initial_location));
}
§Support
All.
Opens a dialog for sharing file to other apps.
An error will occur if there is no app that can handle the request.
Please use AndroidFs::can_share_file
to confirm.
§Args
- uri :
Target file uri to share.
This needs to be readable.
This given fromPrivateStorage
orAndroidFs::show_open_visual_media_dialog
cannot be used.
§Support
All.
Sourcepub fn show_view_file_dialog(&self, uri: &FileUri) -> Result<()>
pub fn show_view_file_dialog(&self, uri: &FileUri) -> Result<()>
Opens a dialog for viewing file on other apps.
This performs the general “open file” action.
An error will occur if there is no app that can handle the request.
Please use AndroidFs::can_view_file
to confirm.
§Args
- uri :
Target file uri to view.
This needs to be readable.
This given fromPrivateStorage
orAndroidFs::show_open_visual_media_dialog
cannot be used.
§Support
All.
Determines whether the specified file can be used with AndroidFs::show_share_file_dialog
.
§Args
- uri :
Target file uri.
This needs to be readable.
§Support
All.
Sourcepub fn can_view_file(&self, uri: &FileUri) -> Result<bool>
pub fn can_view_file(&self, uri: &FileUri) -> Result<bool>
Determines whether the specified file can be used with AndroidFs::show_view_file_dialog
.
§Args
- uri :
Target file uri.
This needs to be readable.
§Support
All.
Sourcepub fn take_persistable_uri_permission(&self, uri: &FileUri) -> Result<()>
pub fn take_persistable_uri_permission(&self, uri: &FileUri) -> Result<()>
Take persistent permission to access the file, directory and its descendants.
This is a prolongation of an already acquired permission, not the acquisition of a new one.
This works by just calling, without displaying any confirmation to the user.
Note that there is a limit to the total number of URI that can be made persistent by this function.
Therefore, it is recommended to relinquish the unnecessary persisted URI by AndroidFs::release_persisted_uri_permission
or AndroidFs::release_all_persisted_uri_permissions
.
Persisted permissions may be relinquished by other apps, user, or by moving/removing entries.
So check by AndroidFs::check_persisted_uri_permission
.
And you can retrieve the list of persisted uris using AndroidFs::get_all_persisted_uri_permissions
.
§Args
- uri :
URI of the target file or directory. This must be a URI taken from following :AndroidFs::show_open_file_dialog
AndroidFs::show_open_visual_media_dialog
AndroidFs::show_save_file_dialog
AndroidFs::show_manage_dir_dialog
AndroidFs::read_dir
:
If this, the permissions of the origin directory URI is persisted, not a entry iteself. Because the permissions and validity period of the entry URIs depend on the origin directory.
§Support
All.
Sourcepub fn check_persisted_uri_permission(
&self,
uri: &FileUri,
mode: PersistableAccessMode,
) -> Result<bool>
pub fn check_persisted_uri_permission( &self, uri: &FileUri, mode: PersistableAccessMode, ) -> Result<bool>
Check a persisted URI permission grant by AndroidFs::take_persistable_uri_permission
.
Returns false if there are only non-persistent permissions or no permissions.
§Args
-
uri :
URI of the target file or directory.
If this is viaAndroidFs::read_dir
, the permissions of the origin directory URI is checked, not a entry iteself. Because the permissions and validity period of the entry URIs depend on the origin directory. -
mode :
The mode of permission you want to check.
§Support
All.
Sourcepub fn get_all_persisted_uri_permissions(
&self,
) -> Result<impl Iterator<Item = PersistedUriPermission>>
pub fn get_all_persisted_uri_permissions( &self, ) -> Result<impl Iterator<Item = PersistedUriPermission>>
Return list of all persisted URIs that have been persisted by AndroidFs::take_persistable_uri_permission
and currently valid.
§Support
All.
Sourcepub fn release_persisted_uri_permission(&self, uri: &FileUri) -> Result<()>
pub fn release_persisted_uri_permission(&self, uri: &FileUri) -> Result<()>
Relinquish a persisted URI permission grant by AndroidFs::take_persistable_uri_permission
.
§Args
- uri :
URI of the target file or directory.
§Support
All.
Sourcepub fn release_all_persisted_uri_permissions(&self) -> Result<()>
pub fn release_all_persisted_uri_permissions(&self) -> Result<()>
Relinquish a all persisted uri permission grants by AndroidFs::take_persistable_uri_permission
.
§Support
All.
Sourcepub fn is_visual_media_dialog_available(&self) -> Result<bool>
pub 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.
Sourcepub fn private_storage(&self) -> PrivateStorage<'_, R>
pub fn private_storage(&self) -> PrivateStorage<'_, R>
File storage intended for the app’s use only.
Sourcepub fn public_storage(&self) -> PublicStorage<'_, R>
pub fn public_storage(&self) -> PublicStorage<'_, R>
File storage that is available to other applications and users.