hwnd 0.0.0-2024-01-05

Well documented, safe-leaning, sound, low-level API bindings to `HWND`-adjacent APIs
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126

use crate::*;
use winapi::um::winuser::*;



/// \[[learn.microsoft.com](https://learn.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-dispatchmessagea)\]
/// DispatchMessageA
///
/// Dispatches a message to a window procedure. It is typically used to dispatch a message retrieved by the [get_message](get_message_a) function.
///
/// ### Safety
/// *   `msg.wparam` and `msg.lparam` may need to be valid pointers, depending on the value of `msg.message` and the wndproc of `msg.hwnd`.
/// *   `msg.hwnd` should perhaps be a unicode window?
///
/// ### Returns
/// The return value specifies the value returned by the window procedure.
/// Although its meaning depends on the message being dispatched, the return value generally is ignored.
///
/// ### Errors
/// These are typically ignored!
/// *   [ERROR::INVALID_WINDOW_HANDLE]  if `msg.hwnd` was invalid, **or if the wndproc destroyed the window.**<br>
///     Common for WM::SYSCOMMAND (Alt+F4), WM::NCLBUTTONDOWN (clicked X), etc.
/// *   [ERROR::ACCESS_DENIED]  if `msg.hwnd` belongs to another process.
/// *   [ERROR::MESSAGE_SYNC_ONLY]  if `msg.message` is a system message to be handled syncronously.<br>
///     Common for messages w/ pointers.  This occurs even if `hwnd` belongs to the current thread.
///
/// ### Example
/// ```
/// use hwnd::*;
///
/// fn main() {
/// #   post_quit_message(0); // don't hang test
///     // ...
///
///     loop {
///         let mut msg = Msg::zeroed();
///         get_message_a(&mut msg, HWnd::NULL, 0, 0).unwrap();
///
///         if msg.message == WM::QUIT { std::process::exit(msg.wparam as _) }
///
///         translate_message(&msg);
///         let _ = unsafe { dispatch_message_a(&msg) };
///     }
/// }
/// ```
pub unsafe fn dispatch_message_a(msg: &impl AsRef<Msg>) -> Result<LRESULT, Error> {
    fn_context!(dispatch_message_a => DispatchMessageA);
    let msg = msg.as_ref().as_ref();
    clear_last_error();
    let lr = unsafe { DispatchMessageA(msg) };
    if lr == 0 { fn_error_gle_nz!()? }
    Ok(lr)
}

/// \[[learn.microsoft.com](https://learn.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-dispatchmessagew)\]
/// DispatchMessageW
///
/// Dispatches a message to a window procedure. It is typically used to dispatch a message retrieved by the [get_message](get_message_w) function.
///
/// ### Safety
/// *   `msg.wparam` and `msg.lparam` may need to be valid pointers, depending on the value of `msg.message` and the wndproc of `msg.hwnd`.
/// *   `msg.hwnd` should perhaps be a unicode window?
///
/// ### Returns
/// The return value specifies the value returned by the window procedure.
/// Although its meaning depends on the message being dispatched, the return value generally is ignored.
///
/// ### Errors
/// These are typically ignored!
/// *   [ERROR::INVALID_WINDOW_HANDLE]  if `msg.hwnd` was invalid, **or if the wndproc destroyed the window.**<br>
///     Common for WM::SYSCOMMAND (Alt+F4), WM::NCLBUTTONDOWN (clicked X), etc.
/// *   [ERROR::ACCESS_DENIED]  if `msg.hwnd` belongs to another process.
/// *   [ERROR::MESSAGE_SYNC_ONLY]  if `msg.message` is a system message to be handled syncronously.<br>
///     Common for messages w/ pointers.  This occurs even if `hwnd` belongs to the current thread.
///
/// ### Example
/// ```
/// use hwnd::*;
///
/// fn main() {
/// #   post_quit_message(0); // don't hang test
///     // ...
///
///     loop {
///         let mut msg = Msg::zeroed();
///         get_message_w(&mut msg, HWnd::NULL, 0, 0).unwrap();
///
///         if msg.message == WM::QUIT { std::process::exit(msg.wparam as _) }
///
///         translate_message(&msg);
///         let _ = unsafe { dispatch_message_w(&msg) };
///     }
/// }
/// ```
pub unsafe fn dispatch_message_w(msg: &impl AsRef<Msg>) -> Result<LRESULT, Error> {
    fn_context!(dispatch_message_w => DispatchMessageW);
    let msg = msg.as_ref().as_ref();
    clear_last_error();
    let lr = unsafe { DispatchMessageW(msg) };
    if lr == 0 { fn_error_gle_nz!()? }
    Ok(lr)
}

#[test] fn cross_thread_dispatch() {
    // perhaps despite expectations, this succeeds!
    use std::ptr::*;
    let hwnd = unsafe { create_window_a(abistr::cstr!("Message"), (), 0, 0, 0, 0, 0, HWnd::MESSAGE, null_mut(), None, null_mut()).unwrap() };
    let _ : LRESULT = std::thread::spawn(move || unsafe {
        dispatch_message_w(&Msg {
            hwnd,
            message: WM::NULL,
            ..Default::default()
        })
    }).join().unwrap().unwrap();
}

#[test] fn cross_process_dispatch() {
    assert_eq!(
        ERROR::ACCESS_DENIED,
        unsafe{dispatch_message_w(&Msg {
            hwnd: get_desktop_window(),
            message: WM::NULL,
            ..Default::default()
        })}.unwrap_err()
    );
}