Struct HHEAP

Source

pub struct HHEAP(/* private fields */);

Available on crate feature kernel only.

Expand description

Handle to a heap object. Originally just a HANDLE.

Implementations§

Source §

impl HHEAP

Source

pub const unsafe fn from_ptr(p: *mut c_void) -> Self

Constructs a new handle object by wrapping a pointer.

This method can be used as an escape hatch to interoperate with other libraries.

§Safety

Be sure the pointer has the correct type and isn’t owned by anyone else, otherwise you may cause memory access violations.

Source

pub const unsafe fn raw_copy(&self) -> Self

Returns a raw copy of the underlying handle pointer.

§Safety

As the name implies, raw_copy returns a raw copy of the handle, so closing one of the copies won’t close the others. This means a handle can be used after it has been closed, what can lead to errors and undefined behavior. Even worse: sometimes Windows reuses handle values, so you can call a method on a completely different handle type, what can be catastrophic.

However, in some cases the Windows API demands a copy of the handle – raw_copy is an escape hatch to fill this gap.

Source

pub const unsafe fn as_mut(&mut self) -> &mut *mut c_void

Returns a mutable reference to the underlying raw pointer.

This method can be used as an escape hatch to interoperate with other libraries.

§Safety

This method exposes the raw pointer used by raw Windows calls. It’s an opaque pointer to an internal Windows structure, and no dereferencings should be attempted.

Source

pub const fn ptr(&self) -> *mut c_void

Returns the underlying raw pointer.

This method exposes the raw pointer used by raw Windows calls. It’s an opaque pointer to an internal Windows structure, and no dereferencings should be attempted.

This method can be used as an escape hatch to interoperate with other libraries.

Source §

pub fn HeapCreate( options: Option<HEAP_CREATE>, initial_size: usize, maximum_size: usize, ) -> SysResult<HeapDestroyGuard>

HeapCreate function.

Source

pub fn HeapAlloc( &self, flags: Option<HEAP_ALLOC>, num_bytes: usize, ) -> SysResult<HeapFreeGuard<'_>>

HeapAlloc function.

§Examples

use winsafe::{self as w, prelude::*, co};

let heap = w::HHEAP::GetProcessHeap()?;

let mut block = heap.HeapAlloc(Some(co::HEAP_ALLOC::ZERO_MEMORY), 40)?;
block.as_mut_slice()[0] = 10;
block.as_mut_slice()[1] = 12;

for byte in block.as_slice().iter() {
    println!("{} ", byte);
}

// HeapFree() automatically called

Source

pub fn HeapCompact(&self, flags: Option<HEAP_SIZE>) -> SysResult<usize>

HeapCompact function.

Source

pub fn HeapLock(&self) -> SysResult<HeapUnlockGuard<'_>>

HeapLock function.

You only need to call this method if the HHEAP was created with co::HEAP_CREATE::NO_SERIALIZE. Otherwise, the heap is already protected against concurrent thread access.

In the original C implementation, you must call HeapUnlock as a cleanup operation; here, the cleanup is performed automatically, because HeapLock returns a HeapUnlockGuard, which automatically calls HeapUnlock when the guard goes out of scope. You must, however, keep the guard alive, otherwise the cleanup will be performed right away.

§Examples

use winsafe::{self as w, prelude::*, co};

let heap = w::HHEAP::HeapCreate(
    Some(co::HEAP_CREATE::NO_SERIALIZE), 0, 0)?;

let _lock = heap.HeapLock()?;

// heap operations...

// HeapUnlock() automatically called

// HeapDestroy() automatically called

Source

pub fn HeapReAlloc<'a>( &'a self, flags: Option<HEAP_REALLOC>, mem: &mut HeapFreeGuard<'a>, num_bytes: usize, ) -> SysResult<()>

HeapReAlloc function.

Originally this method returns the handle to the reallocated memory object; here the original handle, present inside HeapFreeGuard, is automatically updated.

§Examples

use winsafe::{self as w, prelude::*, co};

let heap = w::HHEAP::GetProcessHeap()?;
let mut array = heap.HeapAlloc(Some(co::HEAP_ALLOC::ZERO_MEMORY), 40)?;

heap.HeapReAlloc(Some(co::HEAP_REALLOC::ZERO_MEMORY), &mut array, 65)?;

// HeapFree() automatically called

Source

pub fn HeapSetInformation( &self, information_class: HEAP_INFORMATION, information: &[u8], ) -> SysResult<()>

HeapSetInformation function.

Source

pub fn HeapSize( &self, flags: Option<HEAP_SIZE>, mem: &HeapFreeGuard<'_>, ) -> SysResult<usize>

HeapSize function.

Source

pub fn HeapValidate( &self, flags: Option<HEAP_SIZE>, mem: Option<&HeapFreeGuard<'_>>, ) -> bool

HeapValidate function.

§Examples

use winsafe::{self as w, prelude::*, co};

let heap = w::HHEAP::GetProcessHeap()?;
let mut array = heap.HeapAlloc(Some(co::HEAP_ALLOC::ZERO_MEMORY), 40)?;

let is_ok = heap.HeapValidate(None, Some(&array));

// HeapFree() automatically called

Source

pub fn HeapWalk( &self, ) -> impl Iterator<Item = SysResult<&PROCESS_HEAP_ENTRY>> + '_

HeapWalk function.

Returns an iterator over the heap memory blocks, exposing PROCESS_HEAP_ENTRY structs.

§Examples

use winsafe::{self as w, prelude::*, co};

let heap = w::HHEAP::GetProcessHeap()?;

for block in heap.HeapWalk() {
    let block = block?;
    println!("Size: {}, overhead? {}",
        block.cbData, block.cbOverhead);
}