wintoast 0.1.0

data/ext/wintoast/wintoast.cpp

@@ -0,0 +1,501 @@
+/*
+ * wintoast — fire-and-forget Windows toast notifications + taskbar/terminal
+ * progress, on the inbox WinRT and shell APIs that ship with Windows.
+ *
+ * Stateless module functions (the phylax/winclip shape, NOT the windraw Surface
+ * shape): every native operation is complete within one call and owns no
+ * resources across calls. WinRT/COM is initialized and uninitialized per call
+ * (balanced; RPC_E_CHANGED_MODE => proceed unowned — the toast classes are
+ * agile). No TypedData, no allocator, no finalizer, no leak class.
+ *
+ * Build notes (verified on Ruby 3.4 x64-mswin64_140, MSVC cl 19.x; arch-neutral
+ * — gates on _WIN64, uses ULONG_PTR, no _M_X64, no inline asm, no /MACHINE):
+ *   - <ruby.h> MUST come before the Windows headers (macro/winsock hygiene).
+ *   - Never name an identifier IN/OUT (<windows.h> uses them as SAL markers).
+ *   - -EHsc is on (std::wstring + COM). Therefore NO rb_raise longjmp may ever
+ *     cross a frame holding a live C++ object, un-released COM state, or an
+ *     active try — on MSVC that longjmp is UB. So each bridge is shaped as an
+ *     outer wrapper frame (no C++ objects, no try) that reads VALUE args and
+ *     copies scalars; an inner C++ scope that does all std::wstring + COM work
+ *     in status-code helpers (which release every interface and delete every
+ *     HSTRING before returning HRESULT + the failing API name) and flags OOM in
+ *     a catch(...) WITHOUT calling Ruby; then, ONLY after the scope closes (all
+ *     destructors run, COM balanced, no try active), the wrapper raises.
+ *   - String conversion is infallible on the C side: UTF-8 validity is enforced
+ *     in the Ruby facade before any bridge runs, so MultiByteToWideChar(CP_UTF8,
+ *     0, ...) (no MB_ERR_INVALID_CHARS) cannot fail short of OOM.
+ */
+
+#include <ruby.h>
+#include <ruby/encoding.h>
+#include <ruby/thread.h>
+
+#define WIN32_LEAN_AND_MEAN
+#include <windows.h>
+#include <roapi.h>
+#include <winstring.h>
+#include <windows.ui.notifications.h>
+#include <windows.data.xml.dom.h>
+#include <windows.foundation.h>
+#include <shobjidl_core.h>
+
+#include <string>
+
+/* ABI namespace aliases (the raw WinRT interfaces live under ABI::Windows::*). */
+namespace WF  = ABI::Windows::Foundation;
+namespace WUX = ABI::Windows::Data::Xml::Dom;
+namespace WUN = ABI::Windows::UI::Notifications;
+
+using WF::IPropertyValueStatics;
+using WF::DateTime;
+using WUX::IXmlDocument;
+using WUX::IXmlDocumentIO;
+using WUN::IToastNotificationManagerStatics;
+using WUN::IToastNotifier;
+using WUN::IToastNotification;
+using WUN::IToastNotification2;
+using WUN::IToastNotificationFactory;
+
+static VALUE mWintoast;
+static VALUE eError;
+static VALUE eOSError;
+
+/* ---- small helpers ------------------------------------------------------- */
+
+template <class T>
+static void SafeRelease(T** pp) {
+    if (*pp) { (*pp)->Release(); *pp = nullptr; }
+}
+
+/* UTF-8 (pre-validated in Ruby) -> std::wstring. Non-raising: without
+ * MB_ERR_INVALID_CHARS the call cannot fail on any byte sequence (it returns an
+ * empty string for empty input or — only — under OOM, which the caller's
+ * catch(...) flags). Never call this where an rb_raise could be needed. */
+static std::wstring to_utf16(VALUE str) {
+    long bytelen = RSTRING_LEN(str);
+    if (bytelen <= 0) return std::wstring();
+    const char* p = RSTRING_PTR(str);
+    int need = MultiByteToWideChar(CP_UTF8, 0, p, static_cast<int>(bytelen), nullptr, 0);
+    if (need <= 0) return std::wstring();
+    std::wstring w(static_cast<size_t>(need), L'\0');
+    MultiByteToWideChar(CP_UTF8, 0, p, static_cast<int>(bytelen), &w[0], need);
+    return w;
+}
+
+/* Raise Wintoast::OSError with the failing API name and an HRESULT/Win32 code,
+ * attaching @code. Called ONLY from a wrapper frame holding no live C++ object
+ * or COM state. `is_hr` picks the message format. */
+static void raise_os(const char* what, long code, bool is_hr) {
+    VALUE msg = is_hr
+        ? rb_sprintf("wintoast: %s failed (hr=0x%08lX)", what, static_cast<unsigned long>(code))
+        : rb_sprintf("wintoast: %s failed (error %lu)", what, static_cast<unsigned long>(code));
+    VALUE exc = rb_exc_new_str(eOSError, msg);
+    rb_iv_set(exc, "@code", LONG2NUM(code));
+    rb_exc_raise(exc);
+}
+
+/* =========================================================================
+ *  toast — _show(aumid_u8, xml_u8, expire_unix_ms_or_nil, tag_or_nil, group_or_nil)
+ * ========================================================================= */
+
+/* All COM/WinRT work for Show(). Releases every interface and deletes every
+ * created HSTRING before returning; records the failing API name in *what.
+ * Never calls into Ruby. The aumid/xml/tag/group wstrings outlive every
+ * HSTRING reference by construction (they are function parameters). */
+static HRESULT show_toast(const std::wstring& aumid, const std::wstring& xml,
+                          bool has_expire, long long expire_ms,
+                          bool has_tag, const std::wstring& tag,
+                          bool has_group, const std::wstring& group,
+                          const char** what) {
+    HRESULT hr = S_OK;
+    bool ro_owned = false;
+
+    hr = RoInitialize(RO_INIT_MULTITHREADED);
+    if (hr == RPC_E_CHANGED_MODE) {
+        hr = S_OK;            /* already in an apartment; usable, not ours */
+    } else if (SUCCEEDED(hr)) {
+        ro_owned = true;      /* we incremented the init count; balance it */
+    } else {
+        *what = "RoInitialize";
+        return hr;
+    }
+
+    IToastNotificationManagerStatics* mgr      = nullptr;
+    IToastNotifier*                   notifier = nullptr;
+    IInspectable*                     xmlInsp  = nullptr;
+    IXmlDocumentIO*                   xmlIO    = nullptr;
+    IXmlDocument*                     xmlDoc   = nullptr;
+    IToastNotificationFactory*        tf       = nullptr;
+    IToastNotification*               toast    = nullptr;
+    IToastNotification2*              toast2   = nullptr;
+    IPropertyValueStatics*            pvs      = nullptr;
+    IInspectable*                     dtInsp   = nullptr;
+    WF::IReference<DateTime>*         dtRef    = nullptr;
+
+    HSTRING_HEADER hMgrHdr, hAumidHdr, hXmlHdr, hTagHdr, hGroupHdr;
+    HSTRING hMgr = nullptr, hAumid = nullptr, hXml = nullptr, hTag = nullptr, hGroup = nullptr;
+
+    /* Activation-class name: a fast-pass string reference (no allocation). */
+    hr = WindowsCreateStringReference(
+            RuntimeClass_Windows_UI_Notifications_ToastNotificationManager,
+            static_cast<UINT32>(wcslen(RuntimeClass_Windows_UI_Notifications_ToastNotificationManager)),
+            &hMgrHdr, &hMgr);
+    if (SUCCEEDED(hr))
+        hr = WindowsCreateStringReference(aumid.c_str(), static_cast<UINT32>(aumid.size()),
+                                          &hAumidHdr, &hAumid);
+    if (SUCCEEDED(hr))
+        hr = WindowsCreateStringReference(xml.c_str(), static_cast<UINT32>(xml.size()),
+                                          &hXmlHdr, &hXml);
+    if (FAILED(hr)) { *what = "WindowsCreateStringReference"; goto cleanup; }
+
+    hr = RoGetActivationFactory(hMgr, __uuidof(IToastNotificationManagerStatics),
+                                reinterpret_cast<void**>(&mgr));
+    if (FAILED(hr)) { *what = "RoGetActivationFactory(ToastNotificationManager)"; goto cleanup; }
+
+    /* ALWAYS the WithId overload — the parameterless one throws 0x80070490 for
+     * identity-less processes. */
+    hr = mgr->CreateToastNotifierWithId(hAumid, &notifier);
+    if (FAILED(hr)) { *what = "CreateToastNotifierWithId"; goto cleanup; }
+
+    /* XmlDocument: activate -> QI IXmlDocumentIO -> LoadXml -> QI IXmlDocument. */
+    {
+        HSTRING_HEADER hDocHdr; HSTRING hDoc = nullptr;
+        hr = WindowsCreateStringReference(
+                RuntimeClass_Windows_Data_Xml_Dom_XmlDocument,
+                static_cast<UINT32>(wcslen(RuntimeClass_Windows_Data_Xml_Dom_XmlDocument)),
+                &hDocHdr, &hDoc);
+        if (SUCCEEDED(hr)) {
+            IInspectable* tmp = nullptr;
+            hr = RoActivateInstance(hDoc, &tmp);
+            if (SUCCEEDED(hr)) { xmlInsp = tmp; }
+        }
+    }
+    if (FAILED(hr)) { *what = "RoActivateInstance(XmlDocument)"; goto cleanup; }
+
+    hr = xmlInsp->QueryInterface(__uuidof(IXmlDocumentIO), reinterpret_cast<void**>(&xmlIO));
+    if (FAILED(hr)) { *what = "QueryInterface(IXmlDocumentIO)"; goto cleanup; }
+
+    hr = xmlIO->LoadXml(hXml);
+    if (FAILED(hr)) { *what = "LoadXml"; goto cleanup; }
+
+    hr = xmlInsp->QueryInterface(__uuidof(IXmlDocument), reinterpret_cast<void**>(&xmlDoc));
+    if (FAILED(hr)) { *what = "QueryInterface(IXmlDocument)"; goto cleanup; }
+
+    {
+        HSTRING_HEADER hTNHdr; HSTRING hTN = nullptr;
+        hr = WindowsCreateStringReference(
+                RuntimeClass_Windows_UI_Notifications_ToastNotification,
+                static_cast<UINT32>(wcslen(RuntimeClass_Windows_UI_Notifications_ToastNotification)),
+                &hTNHdr, &hTN);
+        if (SUCCEEDED(hr))
+            hr = RoGetActivationFactory(hTN, __uuidof(IToastNotificationFactory),
+                                        reinterpret_cast<void**>(&tf));
+        if (FAILED(hr)) { *what = "RoGetActivationFactory(ToastNotification)"; goto cleanup; }
+    }
+
+    hr = tf->CreateToastNotification(xmlDoc, &toast);
+    if (FAILED(hr)) { *what = "CreateToastNotification"; goto cleanup; }
+
+    /* Tag/group (1607+): QI IToastNotification2; skipped entirely when absent. */
+    if (has_tag || has_group) {
+        hr = toast->QueryInterface(__uuidof(IToastNotification2), reinterpret_cast<void**>(&toast2));
+        if (FAILED(hr)) { *what = "QueryInterface(IToastNotification2)"; goto cleanup; }
+        if (has_tag) {
+            hr = WindowsCreateStringReference(tag.c_str(), static_cast<UINT32>(tag.size()),
+                                              &hTagHdr, &hTag);
+            if (SUCCEEDED(hr)) hr = toast2->put_Tag(hTag);
+            if (FAILED(hr)) { *what = "put_Tag"; goto cleanup; }
+        }
+        if (has_group) {
+            hr = WindowsCreateStringReference(group.c_str(), static_cast<UINT32>(group.size()),
+                                              &hGroupHdr, &hGroup);
+            if (SUCCEEDED(hr)) hr = toast2->put_Group(hGroup);
+            if (FAILED(hr)) { *what = "put_Group"; goto cleanup; }
+        }
+    }
+
+    /* Expiration: PropertyValue.CreateDateTime -> QI IReference<DateTime> ->
+     * put_ExpirationTime. DateTime is 100-ns ticks since 1601-01-01 UTC. */
+    if (has_expire) {
+        HSTRING_HEADER hPvHdr; HSTRING hPv = nullptr;
+        hr = WindowsCreateStringReference(
+                RuntimeClass_Windows_Foundation_PropertyValue,
+                static_cast<UINT32>(wcslen(RuntimeClass_Windows_Foundation_PropertyValue)),
+                &hPvHdr, &hPv);
+        if (SUCCEEDED(hr))
+            hr = RoGetActivationFactory(hPv, __uuidof(IPropertyValueStatics),
+                                        reinterpret_cast<void**>(&pvs));
+        if (FAILED(hr)) { *what = "RoGetActivationFactory(PropertyValue)"; goto cleanup; }
+
+        DateTime dt;
+        /* DateTime is 100-ns ticks since 1601: (epoch_ms + 11644473600000) * 10000.
+         * Ruby's validate_expiry already clamps expire_ms to a value whose tick fits
+         * int64, but a direct _show bypasses that — so saturate here too. Without
+         * this, a large expire_ms makes the multiply overflow int64 (UB) and hands
+         * the OS a garbage UniversalTime. INT64_MAX/10000 - 11644473600000 is the
+         * largest epoch_ms whose tick is representable. */
+        const long long kMaxExpireMs = (9223372036854775807LL / 10000LL) - 11644473600000LL;
+        long long ms = expire_ms;
+        if (ms > kMaxExpireMs) ms = kMaxExpireMs;
+        else if (ms < 0)       ms = 0;
+        dt.UniversalTime = (ms + 11644473600000LL) * 10000LL;
+        hr = pvs->CreateDateTime(dt, &dtInsp);
+        if (FAILED(hr)) { *what = "CreateDateTime"; goto cleanup; }
+        hr = dtInsp->QueryInterface(__uuidof(WF::IReference<DateTime>),
+                                    reinterpret_cast<void**>(&dtRef));
+        if (FAILED(hr)) { *what = "QueryInterface(IReference<DateTime>)"; goto cleanup; }
+        hr = toast->put_ExpirationTime(dtRef);
+        if (FAILED(hr)) { *what = "put_ExpirationTime"; goto cleanup; }
+    }
+
+    hr = notifier->Show(toast);
+    if (FAILED(hr)) { *what = "Show"; goto cleanup; }
+
+cleanup:
+    /* String references over header/headerless buffers need no WindowsDeleteString
+     * (fast-pass references are not owned HSTRINGs). Release interfaces in reverse. */
+    SafeRelease(&dtRef);
+    SafeRelease(&dtInsp);
+    SafeRelease(&pvs);
+    SafeRelease(&toast2);
+    SafeRelease(&toast);
+    SafeRelease(&tf);
+    SafeRelease(&xmlDoc);
+    SafeRelease(&xmlIO);
+    SafeRelease(&xmlInsp);
+    SafeRelease(&notifier);
+    SafeRelease(&mgr);
+    if (ro_owned) RoUninitialize();
+    return hr;
+}
+
+static VALUE wintoast_show(VALUE self, VALUE vaumid, VALUE vxml, VALUE vexpire,
+                           VALUE vtag, VALUE vgroup) {
+    (void)self;
+    /* Outer frame: no C++ objects, no try. Read scalars only. */
+    bool has_expire = !NIL_P(vexpire);
+    long long expire_ms = has_expire ? NUM2LL(vexpire) : 0;
+    bool has_tag   = !NIL_P(vtag);
+    bool has_group = !NIL_P(vgroup);
+
+    HRESULT hr = S_OK;
+    const char* what = NULL;
+    bool oom = false;
+
+    {   /* inner C++ scope: every std::wstring + interface pointer lives here */
+        try {
+            std::wstring aumid = to_utf16(vaumid);
+            std::wstring xml   = to_utf16(vxml);
+            std::wstring tag   = has_tag   ? to_utf16(vtag)   : std::wstring();
+            std::wstring group = has_group ? to_utf16(vgroup) : std::wstring();
+            hr = show_toast(aumid, xml, has_expire, expire_ms,
+                            has_tag, tag, has_group, group, &what);
+        } catch (...) {
+            oom = true;     /* std::bad_alloc from a wstring: flag only */
+        }
+    }   /* scope closes: destructors run, COM balanced, try no longer active */
+
+    if (oom) rb_raise(rb_eNoMemError, "wintoast: out of memory building toast");
+    if (FAILED(hr)) raise_os(what ? what : "Show", static_cast<long>(hr), /*is_hr*/ true);
+    return Qnil;
+}
+
+/* =========================================================================
+ *  register! / unregister! — HKCU\Software\Classes\AppUserModelId\<aumid>
+ * ========================================================================= */
+
+static LSTATUS do_register(const std::wstring& aumid, const std::wstring& dn,
+                           bool has_icon, const std::wstring& icon, const char** what) {
+    std::wstring path = L"Software\\Classes\\AppUserModelId\\" + aumid;
+    HKEY hkey = nullptr;
+    LSTATUS st = RegCreateKeyExW(HKEY_CURRENT_USER, path.c_str(), 0, nullptr,
+                                 REG_OPTION_NON_VOLATILE, KEY_SET_VALUE, nullptr, &hkey, nullptr);
+    if (st != ERROR_SUCCESS) { *what = "RegCreateKeyEx"; return st; }
+
+    /* REG_SZ byte length includes the terminating NUL. */
+    st = RegSetValueExW(hkey, L"DisplayName", 0, REG_SZ,
+                        reinterpret_cast<const BYTE*>(dn.c_str()),
+                        static_cast<DWORD>((dn.size() + 1) * sizeof(WCHAR)));
+    if (st != ERROR_SUCCESS) { *what = "RegSetValueEx(DisplayName)"; RegCloseKey(hkey); return st; }
+
+    if (has_icon) {
+        st = RegSetValueExW(hkey, L"IconUri", 0, REG_SZ,
+                            reinterpret_cast<const BYTE*>(icon.c_str()),
+                            static_cast<DWORD>((icon.size() + 1) * sizeof(WCHAR)));
+        if (st != ERROR_SUCCESS) { *what = "RegSetValueEx(IconUri)"; RegCloseKey(hkey); return st; }
+    }
+
+    RegCloseKey(hkey);
+    return ERROR_SUCCESS;
+}
+
+static VALUE wintoast_register(VALUE self, VALUE vaumid, VALUE vdn, VALUE vicon) {
+    (void)self;
+    bool has_icon = !NIL_P(vicon);
+    LSTATUS st = ERROR_SUCCESS;
+    const char* what = NULL;
+    bool oom = false;
+
+    {
+        try {
+            std::wstring aumid = to_utf16(vaumid);
+            std::wstring dn    = to_utf16(vdn);
+            std::wstring icon  = has_icon ? to_utf16(vicon) : std::wstring();
+            st = do_register(aumid, dn, has_icon, icon, &what);
+        } catch (...) {
+            oom = true;
+        }
+    }
+
+    if (oom) rb_raise(rb_eNoMemError, "wintoast: out of memory in register!");
+    if (st != ERROR_SUCCESS) raise_os(what ? what : "RegCreateKeyEx", static_cast<long>(st), /*is_hr*/ false);
+    return Qtrue;
+}
+
+static VALUE wintoast_unregister(VALUE self, VALUE vaumid) {
+    (void)self;
+    LSTATUS st = ERROR_SUCCESS;
+    bool oom = false;
+
+    {
+        try {
+            std::wstring path = L"Software\\Classes\\AppUserModelId\\" + to_utf16(vaumid);
+            st = RegDeleteTreeW(HKEY_CURRENT_USER, path.c_str());
+        } catch (...) {
+            oom = true;
+        }
+    }
+
+    if (oom) rb_raise(rb_eNoMemError, "wintoast: out of memory in unregister!");
+    if (st == ERROR_SUCCESS)         return Qtrue;
+    if (st == ERROR_FILE_NOT_FOUND)  return Qfalse;
+    raise_os("RegDeleteTree", static_cast<long>(st), /*is_hr*/ false);
+    return Qnil; /* unreachable */
+}
+
+/* =========================================================================
+ *  progress — _progress(state_int, percent_int)
+ *  state_int uses OSC wire values directly: 0 clear, 1 normal, 2 error,
+ *  3 indeterminate, 4 paused. percent_int 0..100 (pre-clamped in Ruby).
+ * ========================================================================= */
+
+/* No-GVL console write. Touches only this stack struct (built entirely in C from
+ * two ints BEFORE the GVL is released) — never reads a VALUE or RSTRING_PTR, so
+ * GC compaction cannot bite. The classic-conhost select-mode freeze can park
+ * WriteConsoleW indefinitely; releasing the GVL keeps every OTHER Ruby thread
+ * running. The ubf (RUBY_UBF_IO) does NOT cancel a select-mode-parked write —
+ * exact Kernel#puts parity; documented, not worse. */
+typedef struct {
+    HANDLE h;
+    WCHAR  buf[64];
+    DWORD  len;
+    DWORD  written;
+    BOOL   ok;
+} osc_write_t;
+
+static void* osc_write_fn(void* p) {
+    osc_write_t* w = static_cast<osc_write_t*>(p);
+    w->ok = WriteConsoleW(w->h, w->buf, w->len, &w->written, nullptr);
+    return nullptr;
+}
+
+/* Returns true iff the OSC bytes were written to a real console. */
+static bool console_leg(unsigned state, unsigned percent) {
+    HANDLE h = GetStdHandle(STD_OUTPUT_HANDLE);
+    if (h == INVALID_HANDLE_VALUE || h == nullptr) return false;
+
+    DWORD mode = 0;
+    if (!GetConsoleMode(h, &mode)) return false;   /* redirected/absent: never pollute pipes */
+
+    if (!(mode & ENABLE_VIRTUAL_TERMINAL_PROCESSING)) {
+        if (!SetConsoleMode(h, mode | ENABLE_VIRTUAL_TERMINAL_PROCESSING))
+            return false;                          /* no VT support: skip OSC, no raise */
+    }
+
+    osc_write_t w;
+    w.h = h;
+    w.ok = FALSE;
+    w.written = 0;
+    /* ESC ] 9 ; 4 ; <state> ; <pct> BEL — bounded; %u of two small ints. */
+    int n = swprintf(w.buf, sizeof(w.buf) / sizeof(WCHAR), L"\x1b]9;4;%u;%u\x07", state, percent);
+    if (n <= 0) return false;
+    w.len = static_cast<DWORD>(n);
+
+    rb_thread_call_without_gvl(osc_write_fn, &w, RUBY_UBF_IO, nullptr);
+    return w.ok && w.written == w.len;
+}
+
+/* Returns true iff every ITaskbarList3 call succeeded against a non-NULL console
+ * window. No raise on any failure (no shell / hidden ConPTY window / hung
+ * explorer all contribute a false). */
+static bool taskbar_leg(unsigned state, unsigned percent) {
+    HWND hwnd = GetConsoleWindow();
+    if (!hwnd) return false;
+
+    bool co_owned = false;
+    HRESULT hr = CoInitializeEx(nullptr, COINIT_MULTITHREADED);
+    if (hr == RPC_E_CHANGED_MODE) {
+        /* already in an apartment; usable, not ours */
+    } else if (SUCCEEDED(hr)) {
+        co_owned = true;
+    } else {
+        return false;
+    }
+
+    ITaskbarList3* tbl = nullptr;
+    bool ok = false;
+    hr = CoCreateInstance(CLSID_TaskbarList, nullptr, CLSCTX_INPROC_SERVER, IID_PPV_ARGS(&tbl));
+    if (SUCCEEDED(hr)) hr = tbl->HrInit();
+    if (SUCCEEDED(hr)) {
+        switch (state) {
+        case 1: /* normal  */
+        case 2: /* error   */
+        case 4: /* paused  */
+            /* value before state — SetProgressValue forces NORMAL and would
+             * clobber a just-set ERROR/PAUSED. */
+            hr = tbl->SetProgressValue(hwnd, percent, 100);
+            if (SUCCEEDED(hr)) {
+                TBPFLAG f = (state == 2) ? TBPF_ERROR : (state == 4) ? TBPF_PAUSED : TBPF_NORMAL;
+                hr = tbl->SetProgressState(hwnd, f);
+            }
+            break;
+        case 3: /* indeterminate */
+            hr = tbl->SetProgressState(hwnd, TBPF_INDETERMINATE);
+            break;
+        default: /* 0 = clear */
+            hr = tbl->SetProgressState(hwnd, TBPF_NOPROGRESS);
+            break;
+        }
+        ok = SUCCEEDED(hr);
+    }
+
+    SafeRelease(&tbl);
+    if (co_owned) CoUninitialize();
+    return ok;
+}
+
+static VALUE wintoast_progress(VALUE self, VALUE vstate, VALUE vpercent) {
+    (void)self;
+    unsigned state   = static_cast<unsigned>(NUM2UINT(vstate));
+    unsigned percent = static_cast<unsigned>(NUM2UINT(vpercent));
+
+    /* Both legs always run; exactly one is visible per host (or neither). The
+     * console leg releases the GVL for the WriteConsoleW; the taskbar leg holds
+     * it (quick COM work). Neither raises on environmental failure. */
+    bool did_console = console_leg(state, percent);
+    bool did_taskbar = taskbar_leg(state, percent);
+    return (did_console || did_taskbar) ? Qtrue : Qfalse;
+}
+
+/* ------------------------------------------------------------------------- */
+
+extern "C" void Init_wintoast(void) {
+    mWintoast = rb_define_module("Wintoast");
+    eError    = rb_define_class_under(mWintoast, "Error", rb_eStandardError);
+    eOSError  = rb_define_class_under(mWintoast, "OSError", eError);
+
+    rb_define_module_function(mWintoast, "_show",       RUBY_METHOD_FUNC(wintoast_show),       5);
+    rb_define_module_function(mWintoast, "_register",   RUBY_METHOD_FUNC(wintoast_register),   3);
+    rb_define_module_function(mWintoast, "_unregister", RUBY_METHOD_FUNC(wintoast_unregister), 1);
+    rb_define_module_function(mWintoast, "_progress",   RUBY_METHOD_FUNC(wintoast_progress),   2);
+}