Trait HomeDirsExt 

pub trait HomeDirsExt: Sized {
    // Required methods
    fn appdata_env() -> Result<Self>;
    fn known_folders() -> Result<Self>;
}

ⓘ This trait cannot be implemented outside std.

🔬This is a nightly-only experimental API. (fs_home_dirs #162082)

Available on Windows only.

Windows-specific extensions to fs::HomeDirs.

Required Methods

fn appdata_env() -> Result<Self>

🔬This is a nightly-only experimental API. (fs_home_dirs #162082)

Load the known user folder paths from environment variables.

The loaded known folders are:

HomeDirs	Environment Variable
cache_home	%LOCALAPPDATA% (%USERPROFILE%\AppData\Local)
config_home	%APPDATA% (%USERPROFILE%\AppData\Roaming)
data_home	%APPDATA% (%USERPROFILE%\AppData\Roaming)
state_home	%LOCALAPPDATA% (%USERPROFILE%\AppData\Local)

Note that caches/state are both put in AppData\Local, and config/data in AppData\Roaming. It is always possible for multiple user directories to be configured to the same path, but this is the common configuration on Windows platforms, making it even more important to not assume files in different user directories cannot alias each other.

Errors

Errors if %APPDATA% or %LOCALAPPDATA% are not set to absolute paths.

Implementation-specific behavior

Windows keeps these environment variables updated to contain the paths to the configured folder path, but it is possible for the environment variables to not match the underlying system, such as when the user or a program modifies the environment directly, or if the configuration changed after the environment block was copied from the system.

Unlike known_folders, this does not require Shell32.dll and thus does not require the overhead of linking in DLLs that may result in Windows considering the application as a graphical application.

This behavior may change in the future. One example change that we explicitly reserve the right to make is to load additional common directories not currently in this list.

fn known_folders() -> Result<Self>

🔬This is a nightly-only experimental API. (fs_home_dirs #162082)

Load the known user folder paths using the Known Folders API.

The loaded known folders are:

HomeDirs	KNOWNFOLDERID
cache_home	FOLDERID_LocalAppData (%LOCALAPPDATA%)
config_home	FOLDERID_RoamingAppData (%APPDATA%)
data_home	FOLDERID_RoamingAppData (%APPDATA%)
state_home	FOLDERID_LocalAppData (%LOCALAPPDATA%)

Note that caches/state are both put in LocalAppData, and config/data in RoamingAppData. It is always possible for multiple user directories to be configured to the same path, but this is the common configuration on Windows platforms, making it even more important to not assume files in different user directories cannot alias each other.

Errors

Errors if the underlying system discovery API returns an error. The lack of a configured path is not considered an error and results in a None value.

Implementation-specific behavior

Calls SHGetKnownFolderPath for the current user once for each known folder. Does not create the folder if missing.

COM should be initialized on the thread that calls this function or else it may return unexpected errors.

This behavior may change in the future. One example change that we explicitly reserve the right to make is to load additional common directories not currently in this list.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors