Trait PublicStorage

pub trait PublicStorage {
    // Required methods
    fn write_with_contents_writer(
        &self,
        base_dir: PublicGeneralPurposeDir,
        relative_path_with_sub_dir: impl AsRef<str>,
        mime_type: Option<&str>,
        contents_writer: impl FnOnce(&mut File) -> Result<()>,
    ) -> Result<FilePath>;
    fn write_image_with_contents_writer(
        &self,
        base_dir: PublicImageDir,
        relative_path_with_sub_dir: impl AsRef<str>,
        mime_type: Option<&str>,
        contents_writer: impl FnOnce(&mut File) -> Result<()>,
    ) -> Result<FilePath>;
    fn write_video_with_contents_writer(
        &self,
        base_dir: PublicVideoDir,
        relative_path_with_sub_dir: impl AsRef<str>,
        mime_type: Option<&str>,
        contents_writer: impl FnOnce(&mut File) -> Result<()>,
    ) -> Result<FilePath>;
    fn write_audio_with_contents_writer(
        &self,
        base_dir: PublicAudioDir,
        relative_path_with_sub_dir: impl AsRef<str>,
        mime_type: Option<&str>,
        contents_writer: impl FnOnce(&mut File) -> Result<()>,
    ) -> Result<FilePath>;
    fn is_audiobooks_dir_available(&self) -> Result<bool>;
    fn is_recordings_dir_available(&self) -> Result<bool>;

    // Provided methods
    fn write(
        &self,
        base_dir: PublicGeneralPurposeDir,
        relative_path_with_sub_dir: impl AsRef<str>,
        mime_type: Option<&str>,
        contents: impl AsRef<[u8]>,
    ) -> Result<FilePath> { ... }
    fn write_image(
        &self,
        base_dir: PublicImageDir,
        relative_path_with_sub_dir: impl AsRef<str>,
        mime_type: Option<&str>,
        contents: impl AsRef<[u8]>,
    ) -> Result<FilePath> { ... }
    fn write_video(
        &self,
        base_dir: PublicVideoDir,
        relative_path_with_sub_dir: impl AsRef<str>,
        mime_type: Option<&str>,
        contents: impl AsRef<[u8]>,
    ) -> Result<FilePath> { ... }
    fn write_audio(
        &self,
        base_dir: PublicAudioDir,
        relative_path_with_sub_dir: impl AsRef<str>,
        mime_type: Option<&str>,
        contents: impl AsRef<[u8]>,
    ) -> Result<FilePath> { ... }
}

File storage that is available to other applications and users.

Required Methods

fn write_with_contents_writer( &self, base_dir: PublicGeneralPurposeDir, relative_path_with_sub_dir: impl AsRef<str>, mime_type: Option<&str>, contents_writer: impl FnOnce(&mut File) -> Result<()>, ) -> Result<FilePath>

See PublicStorage::write for description.

Note

The file provided in contents_writer is write-only.

Examples

The following is equivalent to PublicStorage::write.

self.write_with_contents_writer(
    base_dir,
    relative_path_with_sub_dir, 
    mime_type,
    |file| file.write_all(contents)
)

fn write_image_with_contents_writer( &self, base_dir: PublicImageDir, relative_path_with_sub_dir: impl AsRef<str>, mime_type: Option<&str>, contents_writer: impl FnOnce(&mut File) -> Result<()>, ) -> Result<FilePath>

See PublicStorage::write_image for description.

Note

The file provided in contents_writer is write-only.

Examples

The following is equivalent to PublicStorage::write_image.

self.write_image_with_contents_writer(
    base_dir,
    relative_path_with_sub_dir, 
    mime_type,
    |file| file.write_all(contents)
)

fn write_video_with_contents_writer( &self, base_dir: PublicVideoDir, relative_path_with_sub_dir: impl AsRef<str>, mime_type: Option<&str>, contents_writer: impl FnOnce(&mut File) -> Result<()>, ) -> Result<FilePath>

See PublicStorage::write_video for description.

Note

The file provided in contents_writer is write-only.

Examples

The following is equivalent to PublicStorage::write_video.

self.write_video_with_contents_writer(
    base_dir,
    relative_path_with_sub_dir, 
    mime_type,
    |file| file.write_all(contents)
)

fn write_audio_with_contents_writer( &self, base_dir: PublicAudioDir, relative_path_with_sub_dir: impl AsRef<str>, mime_type: Option<&str>, contents_writer: impl FnOnce(&mut File) -> Result<()>, ) -> Result<FilePath>

See PublicStorage::write_audio for description.

Note

The file provided in contents_writer is write-only.

Examples

The following is equivalent to PublicStorage::write_audio.

self.write_audio_with_contents_writer(
    base_dir,
    relative_path_with_sub_dir, 
    mime_type,
    |file| file.write_all(contents)
)

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

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

Support

All Android version.

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

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

Support

All Android version.

Provided Methods

fn write( &self, base_dir: PublicGeneralPurposeDir, relative_path_with_sub_dir: impl AsRef<str>, mime_type: Option<&str>, contents: impl AsRef<[u8]>, ) -> Result<FilePath>

Save the contents to public storage, and return writable FilePath.
This is used when saving a file for access by other applications and users.

If the same file name already exists, a sequential number is added to the name and saved.

If you want to operate directly on a write-only file, use PublicStorage::write_with_contents_writer insted.

When storing media files such as images, videos, and audio, consider using PublicStorage::write_image or a similar method.
For saving a general-purpose file, it is often better to use AndroidFs::show_save_file_dialog.

Note

Do not save files directly in the base directory. Please specify a subdirectory in the relative_path_with_sub_dir, such as appName/file.txt or appName/2025-2-11/file.txt. Do not use file.txt.

Support

All Android version.

fn write_image( &self, base_dir: PublicImageDir, relative_path_with_sub_dir: impl AsRef<str>, mime_type: Option<&str>, contents: impl AsRef<[u8]>, ) -> Result<FilePath>

Save the contents as an image file to public storage, and return writable FilePath.
This is used when saving a file for access by other applications and users.

If the same file name already exists, a sequential number is added to the name and saved.

If you want to operate directly on a write-only file, use PublicStorage::write_image_with_contents_writer insted.

Note

Do not set a non-image type to mime_type, as it may result in an error. Even if the type is an image, an error will occur if the Android system does not recognize the type or contents as an image.

Do not save files directly in the base directory. Please specify a subdirectory in the relative_path_with_sub_dir, such as appName/file.png or appName/2025-2-11/file.png. Do not use file.png.

Support

All Android version.

fn write_video( &self, base_dir: PublicVideoDir, relative_path_with_sub_dir: impl AsRef<str>, mime_type: Option<&str>, contents: impl AsRef<[u8]>, ) -> Result<FilePath>

Save the contents as an video file to public storage, and return writable FilePath.
This is used when saving a file for access by other applications and users.

If the same file name already exists, a sequential number is added to the name and saved.

If you want to operate directly on a write-only file, use PublicStorage::write_video_with_contents_writer insted.

Note

Do not set a non-video type to mime_type, as it may result in an error. Even if the type is an video, an error will occur if the Android system does not recognize the type or contents as an video.

Do not save files directly in the base directory. Please specify a subdirectory in the relative_path_with_sub_dir, such as appName/file.mp4 or appName/2025-2-11/file.mp4. Do not use file.mp4.

Support

All Android version.

fn write_audio( &self, base_dir: PublicAudioDir, relative_path_with_sub_dir: impl AsRef<str>, mime_type: Option<&str>, contents: impl AsRef<[u8]>, ) -> Result<FilePath>

Save the contents as an audio file to public storage, and return writable FilePath.
This is used when saving a file for access by other applications and users.

If the same file name already exists, a sequential number is added to the name and saved.

If you want to operate directly on a write-only file, use PublicStorage::write_audio_with_contents_writer insted.

Note

Do not set a non-audio type to mime_type, as it may result in an error. Even if the type is an audio, an error will occur if the Android system does not recognize the type or contents as an audio.

Do not save files directly in the base directory. Please specify a subdirectory in the relative_path_with_sub_dir, such as appName/file.mp3 or appName/2025-2-11/file.mp3. Do not use file.mp3.

Support

PublicAudioDir::Audiobooks is not available on Android 9 (API level 28) and lower.
Availability on a given device can be verified by calling PublicStorage::is_audiobooks_dir_available.

PublicAudioDir::Recordings is not available on Android 11 (API level 30) and lower.
Availability on a given device can be verified by calling PublicStorage::is_recordings_dir_available.

Others are available in all Android versions.

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