Crate windows_safe_handle

source ·
Expand description

Generate smart pointers for windows raw handles with ergonomic APIs.

This crate doesn’t offer pre-defined smart pointers. Instead, it provides a single safe_handle! macro for generation:

Simple Smart Pointer, calling an unsafe Function on Drop

use windows_safe_handle::safe_handle;
use windows::Win32::Foundation::{HANDLE, CloseHandle};

safe_handle!(pub Handle(HANDLE), CloseHandle);

If you do not need to export the Handle type, simply omit the pub keyword.

Smart Pointer with additional Drop logic

You can use a closure-based syntax:

use windows_safe_handle::safe_handle;
use windows::Win32::Foundation::{HANDLE, CloseHandle};

safe_handle!(pub Handle(HANDLE), |h| {
    // Place your code here
    unsafe { CloseHandle(h) }
});

Note that in this case you have to explicitly use unsafe block.

Example

Refer to tests/bcrypt_hash.rs to see how to safely wrap Windows Cryptography Next Generation (CNG) APIs for calculating MD5 hashes.

Strict handles

All windows handle types are defined to be mutually exclusive; you will not be able to pass an HWND where an HDC type argument is required. However, there are situations when you need to pass, for example, HBITMAP or HPEN to a function expecting HGDIOBJ (like SelectObject). To do this, you have to specify the additional handle type:

safe_handle!(pub Handle(HBITMAP as HGDIOBJ), DeleteObject);
//                              ^^^^^^^^^^ that's the trick
let mut bitmap = create_new_bitmap();

SelectObject(hdc, &bitmap); // works as expected

Macros