fenestroj/

lib.rs

#![cfg(windows)]
#![cfg_attr(not(test), no_std)]
#![cfg_attr(test, allow(dead_code))]
#![warn(missing_docs)]
#![warn(missing_debug_implementations)]
#![allow(unused_imports)]
#![allow(unused_macros)]
// Note(Lokathor): Please always sort return expressions so that the success
// case is given first, and then the error case second. Use whatever type of
// conditional expression is required to ensure this.
#![allow(clippy::if_not_else)]
// You generally need to have read MSDN to make sense of the unsafe here.
#![allow(clippy::missing_safety_doc)]

//! Easier wrappers for Win32 API stuff, safe when possible.
//!
//! # Cargo Features
//!
//! Essentially all content in this library is feature gated. Each module below
//! is named after the related module in `winapi`, and has its own feature gate.
//!
//! These docs are generated with all features active, but in your projects
//! you'll need to activate the features you want.

extern crate alloc;
use alloc::{string::String, vec, vec::Vec};

use core::{
  convert::TryFrom,
  ffi::c_void,
  marker::PhantomData,
  mem::size_of,
  ops::Deref,
  ptr::{null, null_mut, NonNull},
};

use chlorine::pick;

macro_rules! mk_newtype_bitflag32 {
  ($mask:ident, $getter:ident, $wither:ident, $setter:ident) => {
    #[allow(missing_docs)]
    #[inline]
    pub const fn $getter(self) -> bool {
      (self.0) & $mask > 0
    }
    #[allow(missing_docs)]
    #[inline]
    pub const fn $wither(self, new_val: bool) -> Self {
      Self(self.0 ^ (((new_val as u32).wrapping_neg() ^ self.0) & $mask))
    }
    #[allow(missing_docs)]
    #[inline]
    pub fn $setter(&mut self, new_val: bool) {
      *self = self.$wither(new_val);
    }
  };
}

/// Cast an optional shared ref to a raw const pointer.
#[inline]
#[allow(dead_code)]
pub(crate) fn opt_to_ptr<T>(opt: Option<&T>) -> *const T {
  unsafe { core::mem::transmute(opt) }
}

/// Cast an optional unique ref to a raw mut pointer.
#[inline]
#[allow(dead_code)]
pub(crate) fn opt_to_mut_ptr<T>(opt: Option<&mut T>) -> *mut T {
  unsafe { core::mem::transmute(opt) }
}

/// Allocates a utf-16 version of the `&str` given.
///
/// **Note:** This will not filter any null characters (`'\0'`) that are in the
/// string. If you have an internal null Windows might think it means the end of
/// the string and not see your full string, which will probably make it do
/// something you don't want.
#[inline]
pub fn wide(s: &str) -> Vec<u16> {
  s.encode_utf16().collect()
}

/// Allocates a utf-16, null-terminated version of the `&str` given.
///
/// **Note:** This will not filter any null characters (`'\0'`) that are in the
/// string. If you have an internal null Windows will think it means the end of
/// the string and not see your full string, which will probably make it do
/// something you don't want.
#[inline]
pub fn wide_null(s: &str) -> Vec<u16> {
  s.encode_utf16().chain(Some(0)).collect()
}

//

pick! {
  if #[cfg(feature = "consoleapi")] {
    pub mod consoleapi;
    pub use consoleapi::*;
  }
}

pick! {
  if #[cfg(feature = "errhandlingapi")] {
    pub mod errhandlingapi;
    pub use errhandlingapi::*;
  }
}

pick! {
  if #[cfg(feature = "handleapi")] {
    pub mod handleapi;
    pub use handleapi::*;
  }
}

pick! {
  if #[cfg(feature = "libloaderapi")] {
    pub mod libloaderapi;
    pub use libloaderapi::*;
  }
}

pick! {
  if #[cfg(feature = "minwinbase")] {
    pub mod minwinbase;
    pub use minwinbase::*;
  }
}

pick! {
  if #[cfg(feature = "minwindef")] {
    pub mod minwindef;
    pub use minwindef::*;
  }
}

pick! {
  if #[cfg(feature = "processenv")] {
    pub mod processenv;
    pub use processenv::*;
  }
}

pick! {
  if #[cfg(feature = "processthreadsapi")] {
    pub mod processthreadsapi;
    pub(crate) use processthreadsapi::*;
  }
}

pick! {
  if #[cfg(feature = "profileapi")] {
    pub mod profileapi;
    pub use profileapi::*;
  }
}

pick! {
  if #[cfg(feature = "winbase")] {
    pub mod winbase;
    pub use winbase::*;
  }
}

pick! {
  if #[cfg(feature = "wincon")] {
    pub mod wincon;
    pub use wincon::*;
  }
}

pick! {
  if #[cfg(feature = "wincontypes")] {
    pub mod wincontypes;
    pub use wincontypes::*;
  }
}

pick! {
  if #[cfg(feature = "windef")] {
    pub mod windef;
    pub use windef::*;
  }
}

pick! {
  if #[cfg(feature = "winerror")] {
    pub mod winerror;
    pub use winerror::*;
  }
}

pick! {
  if #[cfg(feature = "wingdi")] {
    pub mod wingdi;
    pub use wingdi::*;
  }
}

pick! {
  if #[cfg(feature = "winnt")] {
    pub mod winnt;
    pub use winnt::*;
  }
}

pick! {
  if #[cfg(feature = "winuser")] {
    pub mod winuser;
    pub use winuser::*;
  }
}