Trait winsafe::prelude::Handle

pub trait Handle: Sized + PartialEq + Eq + Send + Hash + Debug + Display + LowerHex + UpperHex {
    const NULL: Self;
    const INVALID: Self;

    // Required methods
    unsafe fn from_ptr(p: *mut c_void) -> Self;
    unsafe fn as_mut(&mut self) -> &mut *mut c_void;
    fn ptr(&self) -> *mut c_void;

    // Provided methods
    unsafe fn raw_copy(&self) -> Self { ... }
    fn as_opt(&self) -> Option<&Self> { ... }
}

Available on crate feature kernel only.

A native handle, implemented by all handle types.

Prefer importing this trait through the prelude:

use winsafe::prelude::*;

Required Associated Constants

const NULL: Self

The null, uninitialized handle; equals to 0.

const INVALID: Self

The invalid handle; equals to -1.

Operations upon this handle will fail with ERROR::INVALID_HANDLE error code.

Required Methods

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

Creates 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.

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.

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.

Provided Methods

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.

fn as_opt(&self) -> Option<&Self>

Returns None if the handle is null or invalid, otherwise returns Some(&self).

Examples

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

let hfile = w::HFILE::NULL;

match hfile.as_opt() {
    Some(hfile) => println!("Never prints"),
    None => println!("The handle is null"),
}

Object Safety

This trait is not object safe.

Implementors

impl Handle for HACCEL

Available on crate feature user only.

const NULL: Self = _

const INVALID: Self = _

impl Handle for HACCESSTOKEN

const NULL: Self = _

const INVALID: Self = _

impl Handle for HBITMAP

Available on crate feature user only.

const NULL: Self = _

const INVALID: Self = _

impl Handle for HBRUSH

Available on crate feature user only.

const NULL: Self = _

const INVALID: Self = _

impl Handle for HCURSOR

Available on crate feature user only.

const NULL: Self = _

const INVALID: Self = _

impl Handle for HDC

Available on crate feature user only.

const NULL: Self = _

const INVALID: Self = _

impl Handle for HDESK

Available on crate feature user only.

const NULL: Self = _

const INVALID: Self = _

impl Handle for HDROP

Available on crate feature shell only.

const NULL: Self = _

const INVALID: Self = _

impl Handle for HDWP

Available on crate feature user only.

const NULL: Self = _

const INVALID: Self = _

impl Handle for HEVENT

const NULL: Self = _

const INVALID: Self = _

impl Handle for HEVENTLOG

const NULL: Self = _

const INVALID: Self = _

impl Handle for HFILE

const NULL: Self = _

const INVALID: Self = _

impl Handle for HFILEMAP

const NULL: Self = _

const INVALID: Self = _

impl Handle for HFILEMAPVIEW

const NULL: Self = _

const INVALID: Self = _

impl Handle for HFINDFILE

const NULL: Self = _

const INVALID: Self = _

impl Handle for HFONT

Available on crate feature gdi only.

const NULL: Self = _

const INVALID: Self = _

impl Handle for HGLOBAL

const NULL: Self = _

const INVALID: Self = _

impl Handle for HHEAP

const NULL: Self = _

const INVALID: Self = _

impl Handle for HHOOK

Available on crate feature user only.

const NULL: Self = _

const INVALID: Self = _

impl Handle for HICON

Available on crate feature user only.

const NULL: Self = _

const INVALID: Self = _

impl Handle for HIMAGELIST

Available on crate feature comctl only.

const NULL: Self = _

const INVALID: Self = _

impl Handle for HINSTANCE

const NULL: Self = _

const INVALID: Self = _

impl Handle for HKEY

const NULL: Self = _

const INVALID: Self = _

impl Handle for HLOCAL

const NULL: Self = _

const INVALID: Self = _

impl Handle for HMENU

Available on crate feature user only.

const NULL: Self = _

const INVALID: Self = _

impl Handle for HMONITOR

Available on crate feature user only.

const NULL: Self = _

const INVALID: Self = _

impl Handle for HPALETTE

Available on crate feature gdi only.

const NULL: Self = _

const INVALID: Self = _

impl Handle for HPEN

Available on crate feature gdi only.

const NULL: Self = _

const INVALID: Self = _

impl Handle for HPIPE

const NULL: Self = _

const INVALID: Self = _

impl Handle for HPROCESS

const NULL: Self = _

const INVALID: Self = _

impl Handle for HPROCESSLIST

const NULL: Self = _

const INVALID: Self = _

impl Handle for HRGN

Available on crate feature user only.

const NULL: Self = _

const INVALID: Self = _

impl Handle for HRSRC

const NULL: Self = _

const INVALID: Self = _

impl Handle for HRSRCMEM

const NULL: Self = _

const INVALID: Self = _

impl Handle for HSC

const NULL: Self = _

const INVALID: Self = _

impl Handle for HSERVICE

const NULL: Self = _

const INVALID: Self = _

impl Handle for HSERVICESTATUS

const NULL: Self = _

const INVALID: Self = _

impl Handle for HSTD

const NULL: Self = _

const INVALID: Self = _

impl Handle for HTHEME

Available on crate feature uxtheme only.

const NULL: Self = _

const INVALID: Self = _

impl Handle for HTHREAD

const NULL: Self = _

const INVALID: Self = _

impl Handle for HTRANSACTION

const NULL: Self = _

const INVALID: Self = _

impl Handle for HTREEITEM

Available on crate feature comctl only.

const NULL: Self = _

const INVALID: Self = _

impl Handle for HUPDATERSRC

const NULL: Self = _

const INVALID: Self = _

impl Handle for HVERSIONINFO

Available on crate feature version only.

const NULL: Self = _

const INVALID: Self = _

impl Handle for HWND

Available on crate feature user only.

const NULL: Self = _

const INVALID: Self = _