Struct wnf::StateCreation

pub struct StateCreation<L, S, SD> { /* private fields */ }

A builder type for creating states

You can use this type to create a state by applying the following steps:

1. Create a new builder using StateCreation::new
2. Configure options using the appropriate methods on StateCreation
3. Call StateCreation::create_owned or StateCreation::create_static to create the state

The following options can be configured:

• lifetime: Mandatory
• scope: Mandatory
• maximum_state_size: Optional, default: 0x1000
• security_descriptor: Optional, default: see BoxedSecurityDescriptor::create_everyone_generic_all
• type_id: Optional, default: none

Note that the StateCreation::create_owned and StateCreation::create_static methods are only available once the mandatory options have been configured.

Example

use wnf::{CreatableStateLifetime, DataScope, OwnedState, StateCreation};

let state: OwnedState<u32> = StateCreation::new()
    .lifetime(CreatableStateLifetime::Temporary)
    .scope(DataScope::Machine)
    .create_owned()?;

If you want to create multiple states from a single builder, clone the builder first:

use wnf::{CreatableStateLifetime, DataScope, OwnedState, StateCreation};

let template = StateCreation::new()
    .lifetime(CreatableStateLifetime::Temporary)
    .scope(DataScope::Machine);

let large_state: OwnedState<u32> = template.clone().maximum_state_size(0x800).create_owned()?;

let small_state: OwnedState<u32> = template.maximum_state_size(0x400).create_owned()?;

In order to quickly create a temporary machine-scoped state (e.g. for testing purposes), consider using the OwnedState::create_temporary or BorrowedState::create_temporary methods.

Note that a newly created state is initialized with data of size zero. This means that unless the data type T is zero-sized or a slice type, you need to update the state data with a value of type T before querying it for the first time.

Implementations

impl StateCreation<UnspecifiedLifetime, UnspecifiedScope, UnspecifiedSecurityDescriptor>

pub const fn new() -> Self

Creates a new StateCreation builder with no configured options

impl<L, S, SD> StateCreation<L, S, SD>

pub fn lifetime( self, lifetime: CreatableStateLifetime ) -> StateCreation<CreatableStateLifetime, S, SD>

Configures the lifetime of a StateCreation builder

This is a mandatory option and must be configured before a state can be created.

pub fn scope(self, scope: DataScope) -> StateCreation<L, DataScope, SD>

Configures the scope of a StateCreation builder

This is a mandatory option and must be configured before a state can be created.

pub fn maximum_state_size( self, maximum_state_size: usize ) -> StateCreation<L, S, SD>

Configures the maximum state size of a StateCreation builder

If this is not configured, it defaults to 0x1000 (4 KB), which is the absolute maximum size of a state.

pub fn security_descriptor<NewSD>( self, security_descriptor: NewSD ) -> StateCreation<L, S, NewSD>

where NewSD: Borrow<SecurityDescriptor>,

Configures the security descriptor of a StateCreation builder

If this is not configured, it defaults to BoxedSecurityDescriptor::create_everyone_generic_all.

pub fn type_id(self, type_id: impl Into<GUID>) -> StateCreation<L, S, SD>

Configures the type id of a StateCreation builder

If this is not configured, it defaults to no type id.

impl<SD> StateCreation<CreatableStateLifetime, DataScope, SD>

where SD: TryIntoSecurityDescriptor,

pub fn create_owned<T>(self) -> Result<OwnedState<T>>

where T: ?Sized,

Creates an OwnedState<T> from this StateCreation

Note that the state will be deleted when the returned OwnedState<T> is dropped. You can avoid this by calling StateCreation::create_static instead, which returns a statically borrowed state.

This method is only available once StateCreation::lifetime and StateCreation::scope have been called.

Errors

Returns an error if creating the state fails

pub fn create_static<T>(self) -> Result<BorrowedState<'static, T>>

where T: ?Sized,

Creates a state from this StateCreation, returning a BorrowedState<'static, T>

This is equivalent to creating an owned state and immediately leaking it:

let state: BorrowedState<'static, u32> = StateCreation::new()
    .lifetime(CreatableStateLifetime::Temporary)
    .scope(DataScope::Machine)
    .create_owned()?
    .leak();

Note that since you only obtain a statically borrowed state, it will not be deleted automatically. If that is not the desired behavior, call StateCreation::create_owned instead, which returns an owned state.

This method is only available once StateCreation::lifetime and StateCreation::scope have been called.

Errors

Returns an error if creating the state fails

Trait Implementations

impl<L: Clone, S: Clone, SD: Clone> Clone for StateCreation<L, S, SD>

fn clone(&self) -> StateCreation<L, S, SD>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<L: Debug, S: Debug, SD: Debug> Debug for StateCreation<L, S, SD>

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

Formats the value using the given formatter.

impl Default for StateCreation<UnspecifiedLifetime, UnspecifiedScope, UnspecifiedSecurityDescriptor>

fn default() -> Self

Returns the “default value” for a type.

impl<L: Hash, S: Hash, SD: Hash> Hash for StateCreation<L, S, SD>

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<L: PartialEq, S: PartialEq, SD: PartialEq> PartialEq for StateCreation<L, S, SD>

fn eq(&self, other: &StateCreation<L, S, SD>) -> bool

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

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

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<L: Copy, S: Copy, SD: Copy> Copy for StateCreation<L, S, SD>

impl<L: Eq, S: Eq, SD: Eq> Eq for StateCreation<L, S, SD>

impl<L, S, SD> StructuralPartialEq for StateCreation<L, S, SD>