known_folders/
win.rs

1// src/win.rs
2//
3// Copyright (c) 2023 Ryan Lopopolo <rjl@hyperbo.la>
4//
5// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE> or
6// <http://www.apache.org/licenses/LICENSE-2.0> or the MIT license <LICENSE-MIT>
7// or <http://opensource.org/licenses/MIT>, at your option. All files in the
8// project carrying such notice may not be copied, modified, or distributed
9// except according to those terms.
10
11use core::mem::size_of;
12use core::ptr;
13use core::slice;
14use std::ffi::OsString;
15use std::os::windows::ffi::OsStringExt;
16use std::path::PathBuf;
17
18use windows_sys::Win32::{
19    Foundation::{E_FAIL, E_INVALIDARG, S_OK},
20    Globalization::lstrlenW,
21    UI::Shell::{SHGetKnownFolderPath, KF_FLAG_DEFAULT},
22};
23
24mod ffi;
25mod known_folder;
26
27pub use known_folder::KnownFolder;
28
29/// Retrieve the full path of a known folder identified by the folder's
30/// [`KNOWNFOLDERID`].
31///
32/// A safe wrapper around the [`SHGetKnownFolderPath`] Win32 API function on
33/// Windows.
34///
35/// See [`KnownFolder`] for the types of known folders this function can
36/// retrieve.
37///
38/// # Errors
39///
40/// If an error occurs when calling the underlying Windows APIs or the given
41/// Known Folder ID is not present on the system (for example, if the ID was
42/// introduced in a newer OS version), [`None`] is returned.
43///
44/// # Examples
45///
46/// ```
47/// use known_folders::{get_known_folder_path, KnownFolder};
48///
49/// let profile_dir = get_known_folder_path(KnownFolder::Profile);
50/// ```
51///
52/// [`KNOWNFOLDERID`]: KnownFolder
53/// [`SHGetKnownFolderPath`]: https://learn.microsoft.com/en-us/windows/win32/api/shlobj_core/nf-shlobj_core-shgetknownfolderpath
54#[must_use]
55#[allow(clippy::match_same_arms)]
56#[allow(clippy::cast_possible_wrap)]
57pub fn get_known_folder_path(known_folder: KnownFolder) -> Option<PathBuf> {
58    // This guard ensures `CoTaskMemFree` is always called after invoking
59    // `SHGetKnownFolderPath`, which is required regardless of the return
60    // value.
61    //
62    // See `ppszPath` out parameter description:
63    //
64    // https://learn.microsoft.com/en-us/windows/win32/api/shlobj_core/nf-shlobj_core-shgetknownfolderpath#parameters
65    let mut guard = ffi::Guard::default();
66
67    // Upstream docs:
68    // https://learn.microsoft.com/en-us/windows/win32/api/shlobj_core/nf-shlobj_core-shgetknownfolderpath
69    //
70    // `SHGetKnownFolderPath` replaces `SHGetFolderPathW` as of Windows Vista:
71    //
72    // https://learn.microsoft.com/en-us/windows/win32/api/shlobj_core/nf-shlobj_core-shgetfolderpathw
73    //
74    // SAFETY: this invocation meets the preconditions defined in the API
75    // documentation:
76    //
77    // - `rfid` is a reference to a known folder ID, provided by `windows-sys`.
78    // - `dwFlags` can be `0` per the documentation, we have no special retrieval
79    //   requirements, so use the default defined in `windows-sys`.
80    //   The `KNOWN_FOLDER_FLAG` enum is documented here:
81    //   https://learn.microsoft.com/en-us/windows/win32/api/shlobj_core/ne-shlobj_core-known_folder_flag
82    // - `hToken` is "an access token that represents a particular user. If this
83    //   parameter is `NULL`, which is the most common usage, the function
84    //   requests the known folder for the current user. We want the known folder
85    //   for the current user, so use `ptr::null_mut()`.
86    // - `ppszPath` is an out parameter and should be a NULL pointer to a PWSTR.
87    //
88    // https://learn.microsoft.com/en-us/windows/win32/api/shlobj_core/nf-shlobj_core-shgetknownfolderpath#parameters
89    match unsafe {
90        SHGetKnownFolderPath(
91            known_folder.to_guid(),
92            KF_FLAG_DEFAULT as _,
93            ptr::null_mut(),
94            guard.as_out_ppszPath(),
95        )
96    } {
97        S_OK => {
98            let path_ptr = guard.as_pcwstr();
99
100            // SAFETY: on success, the out pointer is guaranteed to be a valid,
101            // NUL-terminated wide string.
102            //
103            // > When `SHGetKnownFolderPath` returns, contains the address of a
104            // > pointer to a null-terminated Unicode string that specifies the
105            // > path of the known folder
106            let len = unsafe {
107                let len = lstrlenW(path_ptr);
108                usize::try_from(len).ok()?
109            };
110
111            // SAFETY: `path_ptr` is valid for `len` "characters" in a single
112            // string allocation, per windows-sys APIs. "Characters" are `WCHAR`
113            // values. Additionally, `lstrlenW` returns `i32` on 64-bit
114            // platforms. The `match` below guarantees the size of the
115            // allocation is no larger than `isize::MAX`.
116            let path = unsafe {
117                match isize::try_from(len) {
118                    Ok(len) if len < 0 => return None,
119                    Ok(len) if len.checked_mul(size_of::<u16>() as isize).is_some() => {}
120                    Ok(_) | Err(_) => return None,
121                };
122
123                // NOTE: this slice must go out of scope before `guard` above is
124                // dropped. This invariant holds since the guard is constructed
125                // outside the scope of this `match` block.
126                slice::from_raw_parts(path_ptr, len)
127            };
128
129            let os_str = OsString::from_wide(path);
130            Some(os_str.into())
131        }
132        // Expected return codes. See:
133        //
134        // https://learn.microsoft.com/en-us/windows/win32/api/shlobj_core/nf-shlobj_core-shgetknownfolderpath#return-value
135        E_FAIL | E_INVALIDARG => None,
136        // Unexpected return code.
137        _ => None,
138    }
139}
known_folders/win.rs

known_folders/
win.rs
