Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "winsafe"
-version = "0.0.11"
+version = "0.0.12"
 authors = ["Rodrigo Cesar de Freitas Dias <rcesar@gmail.com>"]
 description = "Windows API and GUI in safe, idiomatic Rust."
 categories = ["api-bindings", "gui", "os::windows-apis"]
@@ -25,12 +25,13 @@ dshow = ["oleaut"]
 gdi = ["user"]
 gui = ["gdi", "comctl", "shell", "uxtheme"]
 kernel = []
+ktm = ["kernel"]
 msimg = ["user"]
-ole = ["kernel"]
-oleaut = ["shell"]
-shell = ["ole", "user"]
+ole = ["kernel", "user"]
+oleaut = ["ole"]
+shell = ["ole"]
 user = ["kernel"]
-uxtheme = ["ole", "user"]
+uxtheme = ["ole"]
 version = ["kernel"]
 
 # Generate docs locally:

README.md

@@ -15,27 +15,47 @@ WinSafe has:
 If you're looking for a comprehensive Win32 coverage, take a look at [winapi](https://crates.io/crates/winapi) or [windows](https://crates.io/crates/windows) crates, which are *unsafe*, but have everything.
 
 WinSafe documentation:
-* stable release: [docs.rs/winsafe](https://docs.rs/winsafe)
-* master branch: [rodrigocfd.github.io/winsafe/winsafe](https://rodrigocfd.github.io/winsafe/winsafe/)
+
+| Branch | Docs |
+| - | - |
+| Stable | [docs.rs/winsafe](https://docs.rs/winsafe) |
+| Nightly (master) | [rodrigocfd.github.io/winsafe/winsafe](https://rodrigocfd.github.io/winsafe/winsafe/) |
 
 ## Current status
 
-This crate is still in alpha stage. Below is an estimated progress of feature groups:
+These are the estimated progresses of the GUI features:
+
+| GUI feature | Estimated progress |
+| - | - |
+| User window/dialogs (main, modal and control) | 100% |
+| Native controls | 85% |
+
+Plus, below are the numbers of native FFI items implemented:
 
-| Feature group | Estimated progress |
+| Native FFI item | Count |
 | - | - |
-| User windows (main, modal and control) | ![Progress](https://progress-bar.dev/100/) |
-| Native controls | ![Progress](https://progress-bar.dev/85/) |
-| Window messages | ![Progress](https://progress-bar.dev/75/) |
-| Overall Win32 APIs | ![Progress](https://progress-bar.dev/35/) | |
+| Functions | 555 |
+| Structs | 153 |
+| Constants | 11,877 |
+| Window messages | 630 |
+| Handles | 36 |
+| COM interfaces| 36 |
+| COM methods | 172 |
 
 ## Usage
 
 Add the dependency in your `Cargo.toml`:
 
 ```toml
 [dependencies]
-winsafe = { version = "0.0.11", features = [] }
+winsafe = { version = "0.0.12", features = [] }
+```
+
+You can, alternatively, use the Nightly (master) branch [directly](https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#specifying-dependencies-from-git-repositories), to get the latest features right away:
+
+```toml
+[dependencies]
+winsafe = { git = "https://github.com/rodrigocfd/winsafe", features = [] }
 ```
 
 Then you must enable the [Cargo features](https://doc.rust-lang.org/cargo/reference/features.html#the-features-section) you want to be included – these modules are named after native Windows DLL and library names, mostly.
@@ -44,17 +64,18 @@ The following Cargo features are available so far:
 
 | Feature | Description |
 | - | - |
-| `advapi` | Advapi32.dll, for Windows Registry |
-| `comctl` | ComCtl32.dll, for [Common Controls](https://docs.microsoft.com/en-us/windows/win32/api/_controls/) |
-| `comdlg` | ComDlg32.dll, for the old [Common Dialogs](https://docs.microsoft.com/en-us/windows/win32/uxguide/win-common-dlg) |
-| `dshow` | [DirectShow](https://docs.microsoft.com/en-us/windows/win32/directshow/directshow) |
-| `gdi` | Gdi32.dll, the [Windows GDI](https://docs.microsoft.com/en-us/windows/win32/gdi/windows-gdi) |
-| **`gui`** | **The WinSafe high-level GUI structs** |
+| `advapi` | Advapi32.dll, for [Windows Registry](https://learn.microsoft.com/en-us/windows/win32/sysinfo/registry) |
+| `comctl` | ComCtl32.dll, for [Common Controls](https://learn.microsoft.com/en-us/windows/win32/api/_controls/) |
+| `comdlg` | ComDlg32.dll, for the old [Common Dialogs](https://learn.microsoft.com/en-us/windows/win32/uxguide/win-common-dlg) |
+| `dshow` | [DirectShow](https://learn.microsoft.com/en-us/windows/win32/directshow/directshow) |
+| `gdi` | Gdi32.dll, the [Windows GDI](https://learn.microsoft.com/en-us/windows/win32/gdi/windows-gdi) |
+| **`gui`** | **The WinSafe high-level GUI abstractions** |
 | `kernel` | Kernel32.dll, all others will include it |
+| `ktm` | Ktmw32.dll, the [Kernel Transaction Manager](https://learn.microsoft.com/en-us/windows/win32/ktm/ktm-security-and-access-rights) |
 | `msimg` | Msimg32.dll |
 | `ole` | OLE and basic COM support |
-| `oleaut` | [OLE Automation](https://docs.microsoft.com/en-us/windows/win32/api/_automat/) |
-| `shell` | Shell32.dll and Shlwapi.dll, the COM-based [Windows Shell](https://docs.microsoft.com/en-us/windows/win32/shell/shell-entry) |
+| `oleaut` | [OLE Automation](https://learn.microsoft.com/en-us/windows/win32/api/_automat/) |
+| `shell` | Shell32.dll and Shlwapi.dll, the COM-based [Windows Shell](https://learn.microsoft.com/en-us/windows/win32/shell/shell-entry) |
 | `user` | User32.dll, the basic Windows GUI support |
 | `uxtheme` | UxTheme.dll, extended window theming |
 | `version` | Version.dll, to manipulate *.exe version info |
@@ -77,7 +98,7 @@ The [example below](https://github.com/rodrigocfd/winsafe-examples/tree/master/0
 
 ```toml
 [dependencies]
-winsafe = { version = "0.0.11", features = ["gui"] }
+winsafe = { version = "0.0.12", features = ["gui"] }
 ```
 
 ```rust
@@ -125,12 +146,10 @@ impl MyWindow {
     }
 
     fn events(&self) {
-        self.btn_hello.on().bn_clicked({
-            let wnd = self.wnd.clone(); // clone so it can be passed into the closure
-            move || {
-                wnd.hwnd().SetWindowText("Hello, world!")?;
-                Ok(())
-            }
+        let wnd = self.wnd.clone(); // clone so it can be passed into the closure
+        self.btn_hello.on().bn_clicked(move || {
+            wnd.hwnd().SetWindowText("Hello, world!")?;
+            Ok(())
         });
     }
 }

src/advapi/co.rs

@@ -2,9 +2,9 @@
 
 use crate::co::{ACCESS_RIGHTS, STANDARD_RIGHTS};
 
-const_bitflag! { KEY: u32: "advapi";
-	/// [`HKEY::OpenKeyEx`](crate::prelude::advapi_Hkey::OpenKeyEx)
-	/// `access_rights` (`u32`).
+const_bitflag! { KEY: u32;
+	/// [Registry access rights](https://learn.microsoft.com/en-us/windows/win32/sysinfo/registry-key-security-and-access-rights)
+	/// (`u32`).
 	=>
 	=>
 	QUERY_VALUE 0x0001
@@ -22,9 +22,9 @@ const_bitflag! { KEY: u32: "advapi";
 	ALL_ACCESS (STANDARD_RIGHTS::ALL.0 | Self::QUERY_VALUE.0 | Self::SET_VALUE.0 | Self::CREATE_SUB_KEY.0 | Self::ENUMERATE_SUB_KEYS.0 | Self::NOTIFY.0 | Self::CREATE_LINK.0) & !ACCESS_RIGHTS::SYNCHRONIZE.0
 }
 
-const_ordinary! { REG: u32: "advapi";
+const_ordinary! { REG: u32;
 	/// Registry
-	/// [value types](https://docs.microsoft.com/en-us/windows/win32/sysinfo/registry-value-types)
+	/// [value types](https://learn.microsoft.com/en-us/windows/win32/sysinfo/registry-value-types)
 	/// (`u32`).
 	=>
 	=>
@@ -44,9 +44,22 @@ const_ordinary! { REG: u32: "advapi";
 	QWORD_LITTLE_ENDIAN 11
 }
 
-const_bitflag! { REG_OPTION: u32: "advapi";
-	/// [`HKEY::OpenKeyEx`](crate::prelude::advapi_Hkey::OpenKeyEx) `options`
-	/// (`u32`).
+const_ordinary! { REG_DISPOSITION: u32;
+	/// [`HKEY::RegCreateKeyEx`](crate::prelude::advapi_Hkey::RegCreateKeyEx)
+	/// creation disposition (`u32`).
+	=>
+	=>
+	/// None of the actual values (zero).
+	NoValue 0
+	/// The key did not exist and was created.
+	CREATED_NEW_KEY 0x0000_0001
+	/// The key existed and was simply opened without being changed.
+	OPENED_EXISTING_KEY 0x0000_0002
+}
+
+const_bitflag! { REG_OPTION: u32;
+	/// [`HKEY::RegOpenKeyEx`](crate::prelude::advapi_Hkey::RegOpenKeyEx)
+	/// `options` (`u32`).
 	=>
 	=>
 	/// None of the actual values (zero).
@@ -59,8 +72,8 @@ const_bitflag! { REG_OPTION: u32: "advapi";
 	OPEN_LINK 0x0000_0008
 }
 
-const_bitflag! { RRF: u32: "advapi";
-	/// [`HKEY::GetValue`](crate::prelude::advapi_Hkey::GetValue) `dwFlags`
+const_bitflag! { RRF: u32;
+	/// [`HKEY::GetValue`](crate::prelude::advapi_Hkey::RegGetValue) `dwFlags`
 	/// (`u32`).
 	=>
 	=>

src/advapi/enums.rs

@@ -1,8 +1,8 @@
 use crate::co;
 use crate::kernel::decl::WString;
+use crate::kernel::privs::parse_multi_z_str;
 
 /// Registry value types.
-#[cfg_attr(docsrs, doc(cfg(feature = "advapi")))]
 #[derive(Clone)]
 pub enum RegistryValue {
 	/// Binary value, defined as [`REG::BINARY`](crate::co::REG::BINARY).
@@ -12,51 +12,89 @@ pub enum RegistryValue {
 	/// An `u64` integer value, defined as [`REG::QWORD`](crate::co::REG::QWORD).
 	Qword(u64),
 	/// String value, defined as [`REG::SZ`](crate::co::REG::SZ).
-	Sz(WString),
+	Sz(String),
+	/// Multiple strings, defined as [`REG::MULTI_SZ`](crate::co::REG::MULTI_SZ).
+	MultiSz(Vec<String>),
 	/// No value, defined as [`REG::NONE`](crate::co::REG::NONE). Also used for
 	/// non-implemented value types.
 	None,
 }
 
 impl RegistryValue {
-	/// Creates a new `RegistryValue::Sz` value from a `&str`.
+	/// Parses a binary data block as a `RegistryValue`.
+	///
+	/// # Safety
+	///
+	/// Assumes the binary data block has the correct content, according to the
+	/// informed [`co::REG`](crate::co::REG).
+	///
+	/// This method is used internally by the library, and not intended to be
+	/// used externally.
 	#[must_use]
-	pub fn new_sz(s: &str) -> RegistryValue {
-		Self::Sz(WString::from_str(s))
+	pub unsafe fn from_raw(buf: Vec<u8>, reg_type: co::REG) -> RegistryValue {
+		match reg_type {
+			co::REG::NONE => RegistryValue::None,
+			co::REG::DWORD => RegistryValue::Dword(
+				u32::from_ne_bytes(unsafe {
+					*std::mem::transmute::<_, *const [u8; 4]>(buf.as_ptr())
+				})
+			),
+			co::REG::QWORD => RegistryValue::Qword(
+				u64::from_ne_bytes(unsafe {
+					*std::mem::transmute::<_, *const [u8; 8]>(buf.as_ptr())
+				})
+			),
+			co::REG::SZ => {
+				let (_, vec16, _) = unsafe { buf.align_to::<u16>() };
+				RegistryValue::Sz(WString::from_wchars_slice(&vec16).to_string())
+			},
+			co::REG::MULTI_SZ => {
+				let (_, vec16, _) = unsafe { buf.align_to::<u16>() };
+				RegistryValue::MultiSz(parse_multi_z_str(vec16.as_ptr()))
+			},
+			co::REG::BINARY => RegistryValue::Binary(buf),
+			_ => RegistryValue::None, // other types not implemented yet
+		}
 	}
 
+	/// Returns a pointer to the raw data, along with the raw data length.
 	#[must_use]
-	pub fn as_ptr(&self) -> *const std::ffi::c_void {
+	pub fn as_ptr_with_len(&self,
+		str_buf: &mut WString) -> (*const std::ffi::c_void, u32)
+	{
 		match self {
-			Self::Binary(b) => b.as_ptr() as _,
-			Self::Dword(n) => *n as _,
-			Self::Qword(n) => *n as _,
-			Self::Sz(ws) => unsafe { ws.as_ptr() as _ },
-			Self::None => std::ptr::null(),
+			Self::Binary(b) => (b.as_ptr() as _, b.len() as _),
+			Self::Dword(n) => (n as *const _ as _, std::mem::size_of::<u32>() as _),
+			Self::Qword(n) => (n as *const _ as _, std::mem::size_of::<u64>() as _),
+			Self::Sz(s) => {
+				*str_buf = WString::from_str(s);
+				Self::as_ptr_with_len_str(&str_buf)
+			},
+			Self::MultiSz(v) => {
+				*str_buf = WString::from_str_vec(v);
+				Self::as_ptr_with_len_str(&str_buf)
+			},
+			Self::None => (std::ptr::null(), 0),
 		}
 	}
 
+	fn as_ptr_with_len_str(str_buf: &WString) -> (*const std::ffi::c_void, u32) {
+		(
+			unsafe { str_buf.as_ptr() as *const std::ffi::c_void },
+			(str_buf.buf_len() * std::mem::size_of::<u16>()) as _, // will include terminating null
+		)
+	}
+
 	/// Returns the correspondent [`co::REG`](crate::co::REG) constant.
 	#[must_use]
-	pub fn reg_type(&self) -> co::REG {
+	pub const fn reg_type(&self) -> co::REG {
 		match self {
 			Self::Binary(_) => co::REG::BINARY,
 			Self::Dword(_) => co::REG::DWORD,
 			Self::Qword(_) => co::REG::QWORD,
 			Self::Sz(_) => co::REG::SZ,
+			Self::MultiSz(_) => co::REG::MULTI_SZ,
 			Self::None => co::REG::NONE,
 		}
 	}
-
-	/// Returns the length of the stored data.
-	#[must_use]
-	pub fn len(&self) -> usize {
-		match self {
-			Self::Binary(b) => b.len(),
-			Self::Dword(_) => std::mem::size_of::<u32>(),
-			Self::Qword(_) => std::mem::size_of::<u64>(),
-			Self::Sz(ws) => (ws.buf_len() + 1) * std::mem::size_of::<u16>(), // including terminating null
-			Self::None => 0,
-		}
-	}
 }

src/advapi/ffi.rs

@@ -5,12 +5,23 @@ extern_sys! { "advapi32";
 	EncryptFileW(PCSTR) -> BOOL
 	EncryptionDisable(PCSTR, BOOL) -> BOOL
 	GetUserNameW(PSTR, *mut u32) -> BOOL
+	InitializeSecurityDescriptor(PVOID, u32) -> BOOL
+	IsValidSecurityDescriptor(PCVOID) -> BOOL
 	RegCloseKey(HANDLE) -> i32
+	RegConnectRegistryW(PCSTR, HANDLE, *mut HANDLE) -> i32
+	RegCopyTreeW(HANDLE, PCSTR, HANDLE) -> i32
+	RegCreateKeyExW(HANDLE, PCSTR, u32, PCSTR, u32, u32, PCVOID, *mut HANDLE, *mut u32) -> i32
+	RegDeleteKeyExW(HANDLE, PCSTR, u32, u32) -> i32
+	RegDeleteKeyW(HANDLE, PCSTR) -> i32
+	RegDeleteTreeW(HANDLE, PCSTR) -> i32
+	RegDeleteValueW(HANDLE, PCSTR) -> i32
 	RegEnumKeyExW(HANDLE, u32, PSTR, *mut u32, *mut u32, PSTR, *mut u32, PVOID) -> i32
 	RegEnumValueW(HANDLE, u32, PSTR, *mut u32, *mut u32, *mut u32, *mut u8, *mut u32) -> i32
+	RegFlushKey(HANDLE) -> i32
 	RegGetValueW(HANDLE, PCSTR, PCSTR, u32, *mut u32, PVOID, *mut u32) -> i32
 	RegOpenKeyExW(HANDLE, PCSTR, u32, u32, *mut HANDLE) -> i32
 	RegQueryInfoKeyW(HANDLE, PSTR, *mut u32, *mut u32, *mut u32, *mut u32, *mut u32, *mut u32, *mut u32, *mut u32, *mut u32, PVOID) -> i32
+	RegQueryMultipleValuesW(HANDLE, PVOID, u32, PSTR, *mut u32) -> i32
 	RegQueryValueExW(HANDLE, PCSTR, *mut u32, *mut u32, *mut u8, *mut u32) -> i32
 	RegSetKeyValueW(HANDLE, PCSTR, PCSTR, u32, PCVOID, u32) -> i32
 	RegSetValueExW(HANDLE, PCSTR, u32, u32, *const u8, u32) -> i32