nstd_sys/os/windows/
shared_lib.rs

1//! Shared library/module access for Windows.
2use crate::{
3    core::optional::NSTDOptional, os::windows::NSTDWindowsHandle, NSTDAny, NSTDAnyMut, NSTDChar,
4    NSTDChar16,
5};
6use nstdapi::nstdapi;
7use windows_sys::Win32::System::LibraryLoader::{FreeLibrary, GetProcAddress, LoadLibraryW};
8
9/// A handle to a loaded library.
10#[nstdapi]
11pub struct NSTDWindowsSharedLib {
12    /// A raw handle to the module.
13    handle: NSTDWindowsHandle,
14}
15impl Drop for NSTDWindowsSharedLib {
16    /// [`NSTDWindowsSharedLib`]'s destructor.
17    #[inline]
18    fn drop(&mut self) {
19        // SAFETY: `handle` is non-null.
20        unsafe { FreeLibrary(self.handle) };
21    }
22}
23// SAFETY: `NSTDWindowsSharedLib` owns a handle to the dynamically loaded library.
24unsafe impl Send for NSTDWindowsSharedLib {}
25// SAFETY: `NSTDWindowsSharedLib` does not undergo interior mutability.
26unsafe impl Sync for NSTDWindowsSharedLib {}
27
28/// An optional (possibly null) shared Windows library handle.
29pub type NSTDWindowsOptionalSharedLib = NSTDOptional<NSTDWindowsSharedLib>;
30
31/// Loads a shared library/module by name.
32///
33/// # Parameters:
34///
35/// - `const NSTDChar16 *name` - The name of the module to load.
36///
37/// # Returns
38///
39/// `NSTDWindowsOptionalSharedLib lib` - A handle to the shared library.
40///
41/// # Safety
42///
43/// See
44/// <https://docs.microsoft.com/en-us/windows/win32/api/libloaderapi/nf-libloaderapi-loadlibraryw>.
45#[inline]
46#[nstdapi]
47pub unsafe fn nstd_os_windows_shared_lib_load(
48    name: *const NSTDChar16,
49) -> NSTDWindowsOptionalSharedLib {
50    match LoadLibraryW(name) {
51        0 => NSTDOptional::None,
52        handle => NSTDOptional::Some(NSTDWindowsSharedLib { handle }),
53    }
54}
55
56/// Returns a raw handle to a dynamically loaded library.
57///
58/// # Parameters:
59///
60/// - `const NSTDWindowsSharedLib *lib` - The loaded library.
61///
62/// # Returns
63///
64/// `NSTDWindowsHandle handle` - A native handle to the dynamically loaded library.
65#[inline]
66#[nstdapi]
67pub const fn nstd_os_windows_shared_lib_handle(lib: &NSTDWindowsSharedLib) -> NSTDWindowsHandle {
68    lib.handle
69}
70
71/// Gets a pointer to a function or static variable in a dynamically loaded library by symbol name.
72///
73/// # Parameters
74///
75/// - `const NSTDWindowsSharedLib *lib` - The loaded library.
76///
77/// - `const NSTDChar *symbol` - The name of the function or variable to get a pointer to.
78///
79/// # Returns
80///
81/// `NSTDAny ptr` - A pointer to the function or variable.
82///
83/// # Safety
84///
85/// See <https://docs.microsoft.com/en-us/windows/win32/api/libloaderapi/nf-libloaderapi-getprocaddress>.
86#[inline]
87#[nstdapi]
88pub unsafe fn nstd_os_windows_shared_lib_get(
89    lib: &NSTDWindowsSharedLib,
90    symbol: *const NSTDChar,
91) -> NSTDAny {
92    core::mem::transmute(GetProcAddress(lib.handle, symbol.cast()))
93}
94
95/// Gets a mutable pointer to a function or static variable in a dynamically loaded library by
96/// symbol name.
97///
98/// # Parameters
99///
100/// - `NSTDWindowsSharedLib *lib` - The loaded library.
101///
102/// - `const NSTDChar *symbol` - The name of the function or variable to get a pointer to.
103///
104/// # Returns
105///
106/// `NSTDAnyMut ptr` - A pointer to the function or variable.
107///
108/// # Safety
109///
110/// See <https://docs.microsoft.com/en-us/windows/win32/api/libloaderapi/nf-libloaderapi-getprocaddress>.
111#[inline]
112#[nstdapi]
113pub unsafe fn nstd_os_windows_shared_lib_get_mut(
114    lib: &mut NSTDWindowsSharedLib,
115    symbol: *const NSTDChar,
116) -> NSTDAnyMut {
117    core::mem::transmute(GetProcAddress(lib.handle, symbol.cast()))
118}
119
120/// Unloads and frees a dynamically loaded shared library.
121///
122/// # Parameters:
123///
124/// - `NSTDWindowsSharedLib lib` - The library handle.
125///
126/// # Safety
127///
128/// See
129/// <https://docs.microsoft.com/en-us/windows/win32/api/libloaderapi/nf-libloaderapi-freelibrary>.
130#[inline]
131#[nstdapi]
132#[allow(
133    unused_variables,
134    clippy::missing_const_for_fn,
135    clippy::needless_pass_by_value
136)]
137pub unsafe fn nstd_os_windows_shared_lib_free(lib: NSTDWindowsSharedLib) {}
nstd_sys/os/windows/shared_lib.rs

nstd_sys/os/windows/
shared_lib.rs
