Struct windows_permissions::localheap::LocalBox

pub struct LocalBox<T> { /* fields omitted */ }

A smart pointer to an object on the local heap.

Windows has several different options for allocation, and the local heap is no longer recommended. However, several of the WinAPI calls in this crate use the local heap, allocating with LocalAlloc and freeing with LocalFree. This type encapsulates that behavior, representing objects that reside on the local heap.

It is primarily created using unsafe code in the wrappers crate when the WinAPI allocates a data structure for the program (using from_raw).

However, allocations can be manually made with allocate or try_allocate. For example:

use std::mem::size_of;
use windows_permissions::LocalBox;

let mut local_ptr1: LocalBox<u32> = unsafe { LocalBox::allocate() };

let mut local_ptr2: LocalBox<u32> = unsafe {
    LocalBox::try_allocate(true, size_of::<u32>()).unwrap()
};

*local_ptr1 = 5u32;
*local_ptr2 = 5u32;
assert_eq!(local_ptr1, local_ptr2);

For details, see MSDN.

Exotically-sized types

This struct has not been tested with exotically-sized types. Use with extreme caution.

Implementations

impl<T> LocalBox<T>

pub unsafe fn from_raw(ptr: NonNull<T>) -> Self

Get a LocalBox from a NonNull

Requirements

• The NonNull pointer must have been allocated with a Windows API call. When the resulting NonNull<T> is dropped, it will be dropped with LocalFree
• The buffer pointed to by the pointer must be a valid T

pub unsafe fn allocate() -> Self

Allocate enough zeroed memory to hold a T with LocalAlloc

The memory will always come back zeroed, which has a modest performance penalty but can reduce the impact of buffer overruns.

Panics

Panics if the underlying LocalAlloc call fails.

Safety

The allocated memory is zeroed, which may not be a valid representation of a T.

pub unsafe fn try_allocate(zeroed: bool, size: usize) -> Result<Self>

Allocate memory with LocalAlloc

If the allocation fails, returns the error code.

Safety

The contents of the memory are not guaranteed to be a valid T. The contents will either be zeroed or uninitialized depending on the zeroed parameter.

Additionally, size should be large enough to contain a T.

pub fn as_ptr(&self) -> *mut T

Get a pointer to the underlying data structure

Use this when interacting with FFI libraries that want pointers.

Trait Implementations

impl<T> AsRef<T> for LocalBox<T>

fn as_ref(&self) -> &T

Performs the conversion.

impl<T: Debug> Debug for LocalBox<T>

fn fmt(&self, fmt: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T> Deref for LocalBox<T>

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<T> DerefMut for LocalBox<T>

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl<T: Display> Display for LocalBox<T>

fn fmt(&self, fmt: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T> Drop for LocalBox<T>

fn drop(&mut self)

Executes the destructor for this type.

impl FromStr for LocalBox<SecurityDescriptor>

type Err = Error

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.

impl FromStr for LocalBox<Sid>

type Err = Error

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.

impl<T, U> PartialEq<LocalBox<U>> for LocalBox<T> where
    T: PartialEq<U>, 

fn eq(&self, other: &LocalBox<U>) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]

pub fn ne(&self, other: &Rhs) -> bool

This method tests for !=.