use handle.is_invalid() instead of comparison

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "haxor"
-version = "0.2.0"
+version = "0.3.0"
 edition = "2024"
 readme = "README.md"
 license = "Apache-2.0"
@@ -9,15 +9,19 @@ repository = "https://github.com/elituf/haxor"
 keywords = ["memory", "game", "hacking", "process"]
 
 [dependencies]
-derive_more = { version = "2", features = ["display"] }
+derive_more = { version = "2", features = [
+    "debug",
+    "deref",
+    "display",
+    "from",
+] }
 log = "0.4"
 thiserror = "2"
-
+windows = { version = "0.62", features = [
-[dependencies.windows]
-version = "0.62"
-features = [
-    "Win32_Foundation",
     "Win32_System_Threading",
     "Win32_System_Diagnostics_ToolHelp",
     "Win32_System_Diagnostics_Debug",
-]
+] }
+
+[lib]
+doctest = false

README.md

@@ -1,14 +1,14 @@
 ## haxor
-memory hacking library
+windows external memory hacking library
 
 ## using
 ```rust
-let proc = Process::from("notepad.exe")?;
+let proc = Process::find("notepad.exe")?;
 let some_val = proc.read_mem::<i32>(0xDEADBEEF)?;
 ```
 
 ```rust
-let proc = Process::from(1337)?;
+let proc = Process::find(1337)?;
 let chain: Vec<usize> = vec![proc.base_address, 0x4B1D, 0x8, 0x12];
 let some_addr: usize = proc.resolve_pointer_chain(&chain)?;
 let some_val = proc.read_mem::<u8>(some_addr)?;

src/error.rs

@@ -9,12 +9,15 @@ pub enum Error {
     /// there was a failure when reading or writing the process's memory
     #[error("failed to access process memory")]
     AccessMemoryError(String),
-    /// there was a failure in building the Process or Module struct
-    #[error("failed to create process")]
-    CreateProcessError(String),
     /// there was a failure in creating a snapshot of processes or modules
     #[error("failed to create snapshot")]
     CreateSnapshotError(String),
+    /// there was a failure in building the Process or Module struct
+    #[error("failed to get process/module")]
+    ProcessError(String),
+    /// there was a failure in resolving a pointer chain
+    #[error("failed to resolve pointer chain")]
+    ResolvePointerChainError(String),
     /// there was a failure in conversion between integers
     #[error("failed to convert integer")]
     ConvertIntegerError(#[from] std::num::TryFromIntError),

src/lib.rs

@@ -5,5 +5,6 @@ mod error;
 /// types and methods to ease the r/w of a process's memory
 pub mod process;
 mod sys;
+mod tests;
 
 pub use error::Error;

src/process.rs

@@ -1,29 +1,8 @@
 use crate::{
-    Error,
+    error::Error,
     sys::{handle::Handle, memory, snapshot},
 };
-use derive_more::derive::Display;
+use derive_more::{Debug, Display, From};
-
-#[derive(Display)]
-/// an identifier for searching for a process
-pub enum Identifier {
-    /// process id to search for
-    Pid(u32),
-    /// process name to search for
-    Name(String),
-}
-
-impl From<u32> for Identifier {
-    fn from(value: u32) -> Self {
-        Self::Pid(value)
-    }
-}
-
-impl From<&str> for Identifier {
-    fn from(value: &str) -> Self {
-        Self::Name(value.to_string())
-    }
-}
 
 #[derive(Debug, Default, Clone)]
 /// a process running on the system
@@ -32,18 +11,26 @@ pub struct Process {
     pub name: String,
     /// the process id  (th32ProcessID)
     pub id: u32,
-    /// the base address of the module with the same name as `name` (modBaseAddr)
+    /// the base address of the module with the name `name` (modBaseAddr)
+    #[debug("0x{base_address:X}")]
     pub base_address: usize,
     /// the process handle (HANDLE)
     pub handle: Handle,
 }
 
-unsafe impl Send for Process {}
-unsafe impl Sync for Process {}
-
 impl Process {
     /// initialize a `Process` from a pid or a process name
-    pub fn from<T: Into<Identifier>>(identifier: T) -> Result<Self, Error> {
+    ///
+    /// ### examples
+    ///
+    /// ```rust
+    /// let proc = Process::find(1337)?;
+    /// ```
+    ///
+    /// ```rust
+    /// let proc = Process::find("notepad.exe")?;
+    /// ```
+    pub fn find<T: Into<Identifier>>(identifier: T) -> Result<Self, Error> {
         let identifier = identifier.into();
         let snapshot = snapshot::ProcessSnapshot::get_processes()?
             .into_iter()
@@ -52,7 +39,7 @@ impl Process {
                 Identifier::Name(ref name) => snapshot.name == *name,
             })
             .ok_or_else(|| {
-                Error::CreateProcessError(format!(
+                Error::ProcessError(format!(
                     "failed to find a process with identifier `{identifier}`",
                 ))
             })?;
@@ -66,13 +53,14 @@ impl Process {
         Ok(process)
     }
 
-    /// get a `Module` of a `Process` by name
+    /// get a `Module` of a `Process` by name (case-insensitive)
-    pub fn module(&self, name: &str) -> Result<Module, Error> {
+    pub fn module<T: AsRef<str>>(&self, name: T) -> Result<Module, Error> {
+        let name = name.as_ref();
         let Some(snapshot) = snapshot::ModuleSnapshot::get_modules(self.id)?
             .into_iter()
-            .find(|snapshot| snapshot.name == name)
+            .find(|snapshot| name.eq_ignore_ascii_case(&snapshot.name))
         else {
-            return Err(Error::CreateProcessError(format!(
+            return Err(Error::ProcessError(format!(
                 "failed to find a module with identifier `{name}`",
             )));
         };
@@ -86,15 +74,36 @@ impl Process {
         Ok(module)
     }
 
+    /// get all `Module`s of a `Process`
+    pub fn modules(&self) -> Result<Vec<Module>, Error> {
+        Ok(snapshot::ModuleSnapshot::get_modules(self.id)?
+            .iter()
+            .cloned()
+            .map(|snapshot| Module {
+                process_id: self.id,
+                name: snapshot.name,
+                path: snapshot.path,
+                base_address: snapshot.base_address,
+                base_size: snapshot.base_size,
+            })
+            .collect())
+    }
+
     /// follow a pointer chain to the end and return an address
-    pub fn resolve_pointer_chain(&self, chain: &[usize]) -> Result<usize, Error> {
+    pub fn resolve_pointer_chain<T: AsRef<[usize]>>(&self, chain: T) -> Result<usize, Error> {
-        let mut chain = chain.to_vec();
+        let chain = chain.as_ref();
-        let mut address = chain.remove(0);
+        if chain.is_empty() {
-        while chain.len() > 1 {
+            return Err(Error::ResolvePointerChainError("chain was empty".into()));
-            address += chain.remove(0);
+        }
+        if chain.len() == 1 {
+            return Ok(chain[0]);
+        }
+        let mut address = chain[0];
+        for &offset in &chain[1..(chain.len() - 1)] {
+            address += offset;
             address = self.read_mem(address)?;
         }
-        Ok(address + chain.remove(0))
+        Ok(address + chain.last().expect("chain should have a last element"))
     }
 
     /// read a given `address` of process's memory
@@ -105,7 +114,7 @@ impl Process {
     }
 
     /// write a `value` at given `address` of process's memory
-    pub fn write_mem<T: Default>(&self, address: usize, mut value: T) -> Result<(), Error> {
+    pub fn write_mem<T>(&self, address: usize, mut value: T) -> Result<(), Error> {
         memory::write(&self.handle, address, &mut value)?;
         Ok(())
     }
@@ -121,7 +130,20 @@ pub struct Module {
     /// the module executable path (szExePath)
     pub path: String,
     /// the module base address (modBaseAddr)
+    #[debug("0x{base_address:X}")]
     pub base_address: usize,
     /// the module base size (modBaseSize)
+    #[debug("0x{base_size:X}")]
     pub base_size: usize,
 }
+
+#[derive(Display, From)]
+/// an identifier for searching for a process
+pub enum Identifier {
+    /// process id to search for
+    #[from(u32)]
+    Pid(u32),
+    /// process name to search for
+    #[from(&str, String)]
+    Name(String),
+}

src/sys/handle.rs

@@ -1,24 +1,16 @@
-use crate::Error;
+use crate::error::Error;
-use std::ops::Deref;
+use derive_more::Deref;
 use windows::Win32::{
-    Foundation::{CloseHandle, HANDLE, INVALID_HANDLE_VALUE},
+    Foundation::{CloseHandle, HANDLE},
     System::Threading::{OpenProcess, PROCESS_ALL_ACCESS, PROCESS_VM_READ, PROCESS_VM_WRITE},
 };
 
-#[derive(Debug, Default, Clone)]
+#[derive(Debug, Default, Deref, Clone)]
 pub struct Handle(pub HANDLE);
 
 unsafe impl Send for Handle {}
 unsafe impl Sync for Handle {}
 
-impl Deref for Handle {
-    type Target = HANDLE;
-
-    fn deref(&self) -> &Self::Target {
-        &self.0
-    }
-}
-
 impl Drop for Handle {
     fn drop(&mut self) {
         if let Err(why) = unsafe { CloseHandle(**self) } {
@@ -36,7 +28,7 @@ impl Handle {
                     "failed to open process with needed access: {why}",
                 ))
             })?;
-        if handle == INVALID_HANDLE_VALUE {
+        if handle.is_invalid() {
             return Err(Error::ObtainHandleError(
                 "failed to get a valid handle".to_string(),
             ));

src/sys/memory.rs

@@ -1,4 +1,4 @@
-use crate::{sys::handle::Handle, Error};
+use crate::{error::Error, sys::handle::Handle};
 use std::{ffi::c_void, ptr};
 use windows::Win32::System::Diagnostics::Debug::{ReadProcessMemory, WriteProcessMemory};
 

src/sys/snapshot.rs

@@ -1,4 +1,4 @@
-use crate::Error;
+use crate::error::Error;
 use windows::Win32::System::Diagnostics::ToolHelp::{
     CreateToolhelp32Snapshot, MODULEENTRY32W, Module32FirstW, Module32NextW, PROCESSENTRY32W,
     Process32FirstW, Process32NextW, TH32CS_SNAPMODULE, TH32CS_SNAPMODULE32, TH32CS_SNAPPROCESS,
@@ -41,7 +41,7 @@ impl ProcessSnapshot {
     }
 }
 
-#[derive(Debug)]
+#[derive(Clone, Debug)]
 pub struct ModuleSnapshot {
     pub name: String,
     pub path: String,

src/tests.rs

@@ -0,0 +1,29 @@
+#![cfg(test)]
+
+use super::process::*;
+
+#[test]
+fn resolve_pointer_chain_empty() {
+    let myself = Process::find(std::process::id()).unwrap();
+    let result = myself.resolve_pointer_chain(&[]);
+    assert!(result.is_err());
+}
+
+#[test]
+fn resolve_pointer_chain_single() {
+    let myself = Process::find(std::process::id()).unwrap();
+    let result = myself.resolve_pointer_chain(&[myself.base_address]);
+    assert_eq!(result.unwrap(), myself.base_address);
+}
+
+#[test]
+fn resolve_pointer_chain_multiple() {
+    let myself = Process::find(std::process::id()).unwrap();
+    let target_value = 1337;
+    let target_ptr = &target_value as *const i32 as usize;
+    let base_ptr = &target_ptr as *const usize as usize;
+    let address = myself.resolve_pointer_chain(&[base_ptr, 0x0, 0x0]).unwrap();
+    assert_eq!(address, target_ptr);
+    let value = myself.read_mem::<i32>(address).unwrap();
+    assert_eq!(value, target_value);
+}