whiteoutlib 0.1.2

// SPDX-License-Identifier: BSD-3-Clause
// Copyright (c) 2026 Fernando Sahmkow
// AUTOGENERATED by tools/codegen/emit_rust.py — do not edit.
// Regenerate via:  python -m tools.codegen.codegen host --backend rust

#![allow(clippy::too_many_arguments)]

// Which of these a module needs depends on its shapes; the modules that
// have no span accessors would otherwise trip the unused-import lint.
#[allow(unused_imports)]
use crate::support::{BorrowedSlice, Bytes};

/// Known Blizzard game identifiers.
///
/// The `Unknown` value is used for games discovered via generic heuristics (e.g. the Windows Uninstall registry scan) that don't match a known title. In that case, inspect the `name` field of the result for the display name.
#[repr(i32)]
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub enum BlizzardGame {
    Unknown = 0,
    WorldOfWarcraft = 1,
    WorldOfWarcraftClassic = 2,
    WorldOfWarcraftClassicEra = 3,
    WarcraftIIBattleNetEdition = 4,
    WarcraftIIRemastered = 5,
    WarcraftIII = 6,
    WarcraftIIIReforged = 7,
    StarCraft = 8,
    StarCraftRemastered = 9,
    StarCraftII = 10,
    Diablo = 11,
    DiabloII = 12,
    DiabloIIResurrected = 13,
    DiabloIII = 14,
    DiabloIV = 15,
    DiabloImmortal = 16,
    HeroesOfTheStorm = 17,
    Overwatch2 = 18,
    Hearthstone = 19,
    BlizzardArcadeCollection = 20,
    BattleNet = 21,
}

impl TryFrom<i32> for BlizzardGame {
    type Error = crate::Error;
    fn try_from(v: i32) -> Result<Self, crate::Error> {
        match v {
            0 => Ok(BlizzardGame::Unknown),
            1 => Ok(BlizzardGame::WorldOfWarcraft),
            2 => Ok(BlizzardGame::WorldOfWarcraftClassic),
            3 => Ok(BlizzardGame::WorldOfWarcraftClassicEra),
            4 => Ok(BlizzardGame::WarcraftIIBattleNetEdition),
            5 => Ok(BlizzardGame::WarcraftIIRemastered),
            6 => Ok(BlizzardGame::WarcraftIII),
            7 => Ok(BlizzardGame::WarcraftIIIReforged),
            8 => Ok(BlizzardGame::StarCraft),
            9 => Ok(BlizzardGame::StarCraftRemastered),
            10 => Ok(BlizzardGame::StarCraftII),
            11 => Ok(BlizzardGame::Diablo),
            12 => Ok(BlizzardGame::DiabloII),
            13 => Ok(BlizzardGame::DiabloIIResurrected),
            14 => Ok(BlizzardGame::DiabloIII),
            15 => Ok(BlizzardGame::DiabloIV),
            16 => Ok(BlizzardGame::DiabloImmortal),
            17 => Ok(BlizzardGame::HeroesOfTheStorm),
            18 => Ok(BlizzardGame::Overwatch2),
            19 => Ok(BlizzardGame::Hearthstone),
            20 => Ok(BlizzardGame::BlizzardArcadeCollection),
            21 => Ok(BlizzardGame::BattleNet),
            other => Err(crate::Error::UnknownEnum {
                name: "BlizzardGame",
                value: other,
            }),
        }
    }
}

/// java_package=whiteout.utils — abstract opaque base. Concrete impl: utils::SimpleThreadPool.
pub struct WorkerPool {
    pub(crate) raw: core::ptr::NonNull<ffi::whiteout_WorkerPool>,
}

impl Drop for WorkerPool {
    fn drop(&mut self) {
        // SAFETY: `raw` came from a native constructor and Drop runs once.
        unsafe { ffi::whiteout_host_WorkerPool_delete(self.raw.as_ptr()) }
    }
}

impl WorkerPool {
    /// # Safety
    /// `raw` must be a live handle this value takes ownership of.
    #[allow(dead_code)] // used by whichever methods return this type
    pub(crate) unsafe fn from_raw(raw: *mut ffi::whiteout_WorkerPool) -> Option<Self> {
        core::ptr::NonNull::new(raw).map(|raw| WorkerPool { raw })
    }
}

// SAFETY: handles are plain heap pointers with no thread affinity. `Sync`
// is deliberately NOT implemented — the C++ types make no documented
// guarantee about concurrent use, and claiming one we haven't verified
// would be unsound. See `@bind thread_safe` in the plan.
unsafe impl Send for WorkerPool {}

impl core::fmt::Debug for WorkerPool {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        f.debug_struct("WorkerPool").finish_non_exhaustive()
    }
}

impl WorkerPool {
    /// Block until every submitted task has completed.
    pub fn wait_idle(&mut self) {
        // SAFETY: handle is live for the duration of the call.
        unsafe {
            ffi::whiteout_host_WorkerPool_waitIdle(self.raw.as_ptr());
        }
    }

    /// Number of worker threads in this pool.
    pub fn thread_count(&self) -> usize {
        // SAFETY: handle is live for the duration of the call.
        unsafe { ffi::whiteout_host_WorkerPool_threadCount(self.raw.as_ptr()) }
    }
}

/// java_package=whiteout.utils — abstract file system that resolves files by numeric data ID (e.g. CASC).
pub struct CascFileSystem {
    pub(crate) raw: core::ptr::NonNull<ffi::whiteout_CascFileSystem>,
}

impl Drop for CascFileSystem {
    fn drop(&mut self) {
        // SAFETY: `raw` came from a native constructor and Drop runs once.
        unsafe { ffi::whiteout_host_CascFileSystem_delete(self.raw.as_ptr()) }
    }
}

impl CascFileSystem {
    /// # Safety
    /// `raw` must be a live handle this value takes ownership of.
    #[allow(dead_code)] // used by whichever methods return this type
    pub(crate) unsafe fn from_raw(raw: *mut ffi::whiteout_CascFileSystem) -> Option<Self> {
        core::ptr::NonNull::new(raw).map(|raw| CascFileSystem { raw })
    }
}

// SAFETY: handles are plain heap pointers with no thread affinity. `Sync`
// is deliberately NOT implemented — the C++ types make no documented
// guarantee about concurrent use, and claiming one we haven't verified
// would be unsound. See `@bind thread_safe` in the plan.
unsafe impl Send for CascFileSystem {}

impl core::fmt::Debug for CascFileSystem {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        f.debug_struct("CascFileSystem").finish_non_exhaustive()
    }
}

impl CascFileSystem {
    /// Read the entire contents of a file by its numeric data ID.
    pub fn read_file(&self, file_id: u32) -> Bytes {
        // SAFETY: handle is live for the duration of the call.
        unsafe {
            Bytes::from_raw(ffi::whiteout_host_CascFileSystem_readFile(
                self.raw.as_ptr(),
                file_id,
            ))
            .unwrap_or_else(Bytes::empty)
        }
    }

    /// Resolve a path to a numeric file ID (nullable).
    pub fn reserve_file_id(&mut self, path: &str) -> Option<u32> {
        let path_cstr = std::ffi::CString::new(path).unwrap_or_default();
        let mut __v: u32 = 0;
        // SAFETY: `__v` is a live local, written by the
        // native side only when it returns 1.
        let __has = unsafe {
            ffi::whiteout_host_CascFileSystem_reserveFileId(
                self.raw.as_ptr(),
                path_cstr.as_ptr(),
                &mut __v,
            )
        };
        (__has != 0).then_some(__v)
    }

    /// Write a file by its numeric data ID. Returns true on success.
    pub fn write_file(&mut self, file_id: u32, data: &[u8]) -> bool {
        // SAFETY: handle is live for the duration of the call.
        unsafe {
            ffi::whiteout_host_CascFileSystem_writeFile(
                self.raw.as_ptr(),
                file_id,
                data.as_ptr(),
                data.len(),
            ) != 0
        }
    }

    /// Check if a file with the given data ID exists.
    pub fn file_exists(&self, file_id: u32) -> bool {
        // SAFETY: handle is live for the duration of the call.
        unsafe { ffi::whiteout_host_CascFileSystem_fileExists(self.raw.as_ptr(), file_id) != 0 }
    }
}

/// java_package=whiteout.utils — abstract base. Concrete impl: utils::OsFileSystem.
pub struct VirtualPathFileSystem {
    pub(crate) raw: core::ptr::NonNull<ffi::whiteout_VirtualPathFileSystem>,
}

impl Drop for VirtualPathFileSystem {
    fn drop(&mut self) {
        // SAFETY: `raw` came from a native constructor and Drop runs once.
        unsafe { ffi::whiteout_host_VirtualPathFileSystem_delete(self.raw.as_ptr()) }
    }
}

impl VirtualPathFileSystem {
    /// # Safety
    /// `raw` must be a live handle this value takes ownership of.
    #[allow(dead_code)] // used by whichever methods return this type
    pub(crate) unsafe fn from_raw(raw: *mut ffi::whiteout_VirtualPathFileSystem) -> Option<Self> {
        core::ptr::NonNull::new(raw).map(|raw| VirtualPathFileSystem { raw })
    }
}

// SAFETY: handles are plain heap pointers with no thread affinity. `Sync`
// is deliberately NOT implemented — the C++ types make no documented
// guarantee about concurrent use, and claiming one we haven't verified
// would be unsound. See `@bind thread_safe` in the plan.
unsafe impl Send for VirtualPathFileSystem {}

impl core::fmt::Debug for VirtualPathFileSystem {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        f.debug_struct("VirtualPathFileSystem")
            .finish_non_exhaustive()
    }
}

impl VirtualPathFileSystem {
    /// Read the entire contents of a file into a byte vector.
    pub fn read_file(&self, path: &str) -> Bytes {
        let path_cstr = std::ffi::CString::new(path).unwrap_or_default();
        // SAFETY: handle is live for the duration of the call.
        unsafe {
            Bytes::from_raw(ffi::whiteout_host_VirtualPathFileSystem_readFile(
                self.raw.as_ptr(),
                path_cstr.as_ptr(),
            ))
            .unwrap_or_else(Bytes::empty)
        }
    }

    /// Write a file. Returns true on success.
    pub fn write_file(&mut self, path: &str, data: &[u8]) -> bool {
        let path_cstr = std::ffi::CString::new(path).unwrap_or_default();
        // SAFETY: handle is live for the duration of the call.
        unsafe {
            ffi::whiteout_host_VirtualPathFileSystem_writeFile(
                self.raw.as_ptr(),
                path_cstr.as_ptr(),
                data.as_ptr(),
                data.len(),
            ) != 0
        }
    }

    /// Check if a file exists at the given path.
    pub fn file_exists(&self, path: &str) -> bool {
        let path_cstr = std::ffi::CString::new(path).unwrap_or_default();
        // SAFETY: handle is live for the duration of the call.
        unsafe {
            ffi::whiteout_host_VirtualPathFileSystem_fileExists(
                self.raw.as_ptr(),
                path_cstr.as_ptr(),
            ) != 0
        }
    }
}

/// HTTP GET result handed to user callbacks.
pub struct HttpResponse {
    pub(crate) raw: core::ptr::NonNull<ffi::whiteout_HttpResponse>,
}

impl Drop for HttpResponse {
    fn drop(&mut self) {
        // SAFETY: `raw` came from a native constructor and Drop runs once.
        unsafe { ffi::whiteout_host_HttpResponse_delete(self.raw.as_ptr()) }
    }
}

impl HttpResponse {
    /// # Safety
    /// `raw` must be a live handle this value takes ownership of.
    #[allow(dead_code)] // used by whichever methods return this type
    pub(crate) unsafe fn from_raw(raw: *mut ffi::whiteout_HttpResponse) -> Option<Self> {
        core::ptr::NonNull::new(raw).map(|raw| HttpResponse { raw })
    }
}

// SAFETY: handles are plain heap pointers with no thread affinity. `Sync`
// is deliberately NOT implemented — the C++ types make no documented
// guarantee about concurrent use, and claiming one we haven't verified
// would be unsound. See `@bind thread_safe` in the plan.
unsafe impl Send for HttpResponse {}

impl core::fmt::Debug for HttpResponse {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        f.debug_struct("HttpResponse").finish_non_exhaustive()
    }
}

impl HttpResponse {
    /// # Panics
    /// Panics if the native allocation fails.
    pub fn new() -> Self {
        // SAFETY: the native constructor returns a live handle; a null here
        // means the library is unusable.
        unsafe {
            let raw = ffi::whiteout_host_HttpResponse_new();
            Self::from_raw(raw).expect("native HttpResponse allocation failed")
        }
    }

    /// HTTP status code (200, 206, 404, …).
    pub fn status_code(&self) -> i32 {
        // SAFETY: plain scalar read through a live handle.
        unsafe { ffi::whiteout_host_HttpResponse_get_statusCode(self.raw.as_ptr()) }
    }

    pub fn set_status_code(&mut self, value: i32) {
        // SAFETY: plain scalar write through a live handle.
        unsafe { ffi::whiteout_host_HttpResponse_set_statusCode(self.raw.as_ptr(), value) }
    }

    /// Response body.
    /// Zero-copy view of the underlying `std::vector`.
    pub fn body(&self) -> &[u8] {
        // SAFETY: `_data`/`_count` describe one contiguous C++
        // allocation, borrowed for as long as `self` is.
        unsafe {
            let n = ffi::whiteout_host_HttpResponse_get_body_count(self.raw.as_ptr());
            let p = ffi::whiteout_host_HttpResponse_get_body_data(self.raw.as_ptr());
            if p.is_null() || n == 0 {
                &[]
            } else {
                core::slice::from_raw_parts(p, n)
            }
        }
    }

    /// Zero-copy mutable view. Resize first — the borrow forbids it after.
    pub fn body_mut(&mut self) -> &mut [u8] {
        // SAFETY: as above; `&mut self` rules out aliasing and resizing.
        unsafe {
            let n = ffi::whiteout_host_HttpResponse_get_body_count(self.raw.as_ptr());
            let p = ffi::whiteout_host_HttpResponse_get_body_data(self.raw.as_ptr()) as *mut u8;
            if p.is_null() || n == 0 {
                &mut []
            } else {
                core::slice::from_raw_parts_mut(p, n)
            }
        }
    }

    pub fn set_body(&mut self, values: &[u8]) {
        // SAFETY: the native side copies `values` before returning.
        unsafe {
            ffi::whiteout_host_HttpResponse_assign_body(
                self.raw.as_ptr(),
                values.as_ptr() as *const _,
                values.len(),
            )
        }
    }

    pub fn resize_body(&mut self, count: usize) {
        // SAFETY: reallocation is safe here precisely because
        // `&mut self` means no slice borrow is outstanding.
        unsafe { ffi::whiteout_host_HttpResponse_resize_body(self.raw.as_ptr(), count) }
    }

    /// Transport-level error (empty on success).
    pub fn error(&self) -> String {
        // SAFETY: the native side hands over an owned CString.
        unsafe {
            crate::support::take_string(ffi::whiteout_host_HttpResponse_get_error(
                self.raw.as_ptr(),
            ))
        }
    }

    pub fn set_error(&mut self, value: &str) {
        let value = std::ffi::CString::new(value).unwrap_or_default();
        // SAFETY: the pointer outlives the call.
        unsafe { ffi::whiteout_host_HttpResponse_set_error(self.raw.as_ptr(), value.as_ptr()) }
    }
}

impl Default for HttpResponse {
    fn default() -> Self {
        Self::new()
    }
}

/// Abstract HTTP handler.  The library calls these methods to fetch CDN data. Users must provide a concrete implementation.
///
/// Both methods are pure virtual — async support is mandatory. The handler invokes @p callback exactly once when the request completes (or fails). The callback may be invoked from any thread.
///
/// Thread safety: methods may be called concurrently from multiple WorkerPool threads.  The implementation must be thread-safe.
///
/// java_package=whiteout.utils — abstract opaque base. Concrete impl: utils::SimpleHttpHandler.
pub struct HttpHandler {
    pub(crate) raw: core::ptr::NonNull<ffi::whiteout_HttpHandler>,
}

impl Drop for HttpHandler {
    fn drop(&mut self) {
        // SAFETY: `raw` came from a native constructor and Drop runs once.
        unsafe { ffi::whiteout_host_HttpHandler_delete(self.raw.as_ptr()) }
    }
}

impl HttpHandler {
    /// # Safety
    /// `raw` must be a live handle this value takes ownership of.
    #[allow(dead_code)] // used by whichever methods return this type
    pub(crate) unsafe fn from_raw(raw: *mut ffi::whiteout_HttpHandler) -> Option<Self> {
        core::ptr::NonNull::new(raw).map(|raw| HttpHandler { raw })
    }
}

// SAFETY: handles are plain heap pointers with no thread affinity. `Sync`
// is deliberately NOT implemented — the C++ types make no documented
// guarantee about concurrent use, and claiming one we haven't verified
// would be unsound. See `@bind thread_safe` in the plan.
unsafe impl Send for HttpHandler {}

impl core::fmt::Debug for HttpHandler {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        f.debug_struct("HttpHandler").finish_non_exhaustive()
    }
}

impl HttpHandler {
    /// Reported handler capability flags.
    pub fn capabilities(&self) -> u32 {
        // SAFETY: handle is live for the duration of the call.
        unsafe { ffi::whiteout_host_HttpHandler_capabilities(self.raw.as_ptr()) }
    }
}

/// VirtualPathFileSystem implementation backed by the OS filesystem.
///
/// All paths passed to readFile() / fileExists() are resolved relative to the root directory supplied at construction time.
///
/// Example: utils::OsFileSystem fs("C:/Games/Warcraft III/Data"); auto data = fs.readFile("units/human/arthas/arthas.mdx");
///
/// java_package=whiteout.utils
pub struct OsFileSystem {
    pub(crate) raw: core::ptr::NonNull<ffi::whiteout_OsFileSystem>,
}

impl Drop for OsFileSystem {
    fn drop(&mut self) {
        // SAFETY: `raw` came from a native constructor and Drop runs once.
        unsafe { ffi::whiteout_host_OsFileSystem_delete(self.raw.as_ptr()) }
    }
}

impl OsFileSystem {
    /// # Safety
    /// `raw` must be a live handle this value takes ownership of.
    #[allow(dead_code)] // used by whichever methods return this type
    pub(crate) unsafe fn from_raw(raw: *mut ffi::whiteout_OsFileSystem) -> Option<Self> {
        core::ptr::NonNull::new(raw).map(|raw| OsFileSystem { raw })
    }
}

// SAFETY: handles are plain heap pointers with no thread affinity. `Sync`
// is deliberately NOT implemented — the C++ types make no documented
// guarantee about concurrent use, and claiming one we haven't verified
// would be unsound. See `@bind thread_safe` in the plan.
unsafe impl Send for OsFileSystem {}

impl core::fmt::Debug for OsFileSystem {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        f.debug_struct("OsFileSystem").finish_non_exhaustive()
    }
}

impl OsFileSystem {
    /// Read a file at `rootPath / path`. Returns an empty vector if not found.
    pub fn read_file(&self, path: &str) -> Bytes {
        let path_cstr = std::ffi::CString::new(path).unwrap_or_default();
        // SAFETY: handle is live for the duration of the call.
        unsafe {
            Bytes::from_raw(ffi::whiteout_host_OsFileSystem_readFile(
                self.raw.as_ptr(),
                path_cstr.as_ptr(),
            ))
            .unwrap_or_else(Bytes::empty)
        }
    }

    pub fn write_file(&mut self, path: &str, data: &[u8]) -> bool {
        let path_cstr = std::ffi::CString::new(path).unwrap_or_default();
        // SAFETY: handle is live for the duration of the call.
        unsafe {
            ffi::whiteout_host_OsFileSystem_writeFile(
                self.raw.as_ptr(),
                path_cstr.as_ptr(),
                data.as_ptr(),
                data.len(),
            ) != 0
        }
    }

    pub fn file_exists(&self, path: &str) -> bool {
        let path_cstr = std::ffi::CString::new(path).unwrap_or_default();
        // SAFETY: handle is live for the duration of the call.
        unsafe {
            ffi::whiteout_host_OsFileSystem_fileExists(self.raw.as_ptr(), path_cstr.as_ptr()) != 0
        }
    }
}

/// Basic CPU worker pool implementation of interfaces::WorkerPool.
///
/// Tasks are executed by a fixed number of worker threads created at construction time.
pub struct SimpleThreadPool {
    pub(crate) raw: core::ptr::NonNull<ffi::whiteout_SimpleThreadPool>,
}

impl Drop for SimpleThreadPool {
    fn drop(&mut self) {
        // SAFETY: `raw` came from a native constructor and Drop runs once.
        unsafe { ffi::whiteout_host_SimpleThreadPool_delete(self.raw.as_ptr()) }
    }
}

impl SimpleThreadPool {
    /// # Safety
    /// `raw` must be a live handle this value takes ownership of.
    #[allow(dead_code)] // used by whichever methods return this type
    pub(crate) unsafe fn from_raw(raw: *mut ffi::whiteout_SimpleThreadPool) -> Option<Self> {
        core::ptr::NonNull::new(raw).map(|raw| SimpleThreadPool { raw })
    }
}

// SAFETY: handles are plain heap pointers with no thread affinity. `Sync`
// is deliberately NOT implemented — the C++ types make no documented
// guarantee about concurrent use, and claiming one we haven't verified
// would be unsound. See `@bind thread_safe` in the plan.
unsafe impl Send for SimpleThreadPool {}

impl core::fmt::Debug for SimpleThreadPool {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        f.debug_struct("SimpleThreadPool").finish_non_exhaustive()
    }
}

impl SimpleThreadPool {
    /// Block until the pool has no pending or running tasks.
    pub fn wait_idle(&mut self) {
        // SAFETY: handle is live for the duration of the call.
        unsafe {
            ffi::whiteout_host_SimpleThreadPool_waitIdle(self.raw.as_ptr());
        }
    }

    /// Number of worker threads in this pool.
    pub fn thread_count(&self) -> usize {
        // SAFETY: handle is live for the duration of the call.
        unsafe { ffi::whiteout_host_SimpleThreadPool_threadCount(self.raw.as_ptr()) }
    }
}

/// Basic HTTP handler with two platform backends: * Windows  — WinHTTP * Other    — libcurl (linked at build time)
///
/// Requests are dispatched asynchronously onto an internal thread pool; each worker owns one backend handle and keeps its connection cache warm. Thread-safe: multiple threads may call getAsync / getRangeAsync concurrently.
pub struct SimpleHttpHandler {
    pub(crate) raw: core::ptr::NonNull<ffi::whiteout_SimpleHttpHandler>,
}

impl Drop for SimpleHttpHandler {
    fn drop(&mut self) {
        // SAFETY: `raw` came from a native constructor and Drop runs once.
        unsafe { ffi::whiteout_host_SimpleHttpHandler_delete(self.raw.as_ptr()) }
    }
}

impl SimpleHttpHandler {
    /// # Safety
    /// `raw` must be a live handle this value takes ownership of.
    #[allow(dead_code)] // used by whichever methods return this type
    pub(crate) unsafe fn from_raw(raw: *mut ffi::whiteout_SimpleHttpHandler) -> Option<Self> {
        core::ptr::NonNull::new(raw).map(|raw| SimpleHttpHandler { raw })
    }
}

// SAFETY: handles are plain heap pointers with no thread affinity. `Sync`
// is deliberately NOT implemented — the C++ types make no documented
// guarantee about concurrent use, and claiming one we haven't verified
// would be unsound. See `@bind thread_safe` in the plan.
unsafe impl Send for SimpleHttpHandler {}

impl core::fmt::Debug for SimpleHttpHandler {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        f.debug_struct("SimpleHttpHandler").finish_non_exhaustive()
    }
}

impl SimpleHttpHandler {
    /// # Panics
    /// Panics if the native allocation fails.
    pub fn new() -> Self {
        // SAFETY: the native constructor returns a live handle; a null here
        // means the library is unusable.
        unsafe {
            let raw = ffi::whiteout_host_SimpleHttpHandler_new();
            Self::from_raw(raw).expect("native SimpleHttpHandler allocation failed")
        }
    }

    /// Reported handler capability flags.
    pub fn capabilities(&self) -> u32 {
        // SAFETY: handle is live for the duration of the call.
        unsafe { ffi::whiteout_host_SimpleHttpHandler_capabilities(self.raw.as_ptr()) }
    }
}

impl Default for SimpleHttpHandler {
    fn default() -> Self {
        Self::new()
    }
}

/// Thread-safe counter-based completion primitive for grouped jobs.
///
/// A JobGroup starts with zero pending jobs. Call add() before submitting work, then call done() once per completed job. wait() blocks until the pending count reaches zero.
///
/// Typical usage pattern: 1. add(N) 2. submit N tasks 3. each task calls done() on completion 4. wait() to join the group
pub struct JobGroup {
    pub(crate) raw: core::ptr::NonNull<ffi::whiteout_JobGroup>,
}

impl Drop for JobGroup {
    fn drop(&mut self) {
        // SAFETY: `raw` came from a native constructor and Drop runs once.
        unsafe { ffi::whiteout_host_JobGroup_delete(self.raw.as_ptr()) }
    }
}

impl JobGroup {
    /// # Safety
    /// `raw` must be a live handle this value takes ownership of.
    #[allow(dead_code)] // used by whichever methods return this type
    pub(crate) unsafe fn from_raw(raw: *mut ffi::whiteout_JobGroup) -> Option<Self> {
        core::ptr::NonNull::new(raw).map(|raw| JobGroup { raw })
    }
}

// SAFETY: handles are plain heap pointers with no thread affinity. `Sync`
// is deliberately NOT implemented — the C++ types make no documented
// guarantee about concurrent use, and claiming one we haven't verified
// would be unsound. See `@bind thread_safe` in the plan.
unsafe impl Send for JobGroup {}

impl core::fmt::Debug for JobGroup {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        f.debug_struct("JobGroup").finish_non_exhaustive()
    }
}

impl JobGroup {
    /// # Panics
    /// Panics if the native allocation fails.
    pub fn new() -> Self {
        // SAFETY: the native constructor returns a live handle; a null here
        // means the library is unusable.
        unsafe {
            let raw = ffi::whiteout_host_JobGroup_new();
            Self::from_raw(raw).expect("native JobGroup allocation failed")
        }
    }

    /// Increment the number of pending jobs.
    ///
    /// @param n Number of jobs to add to the group.
    pub fn add(&mut self, n: usize) {
        // SAFETY: handle is live for the duration of the call.
        unsafe {
            ffi::whiteout_host_JobGroup_add(self.raw.as_ptr(), n);
        }
    }

    /// Mark one pending job as completed.
    ///
    /// When the pending count reaches zero, all waiters are notified.
    ///
    /// @note done() calls must be balanced with prior add() calls.
    pub fn done(&mut self) {
        // SAFETY: handle is live for the duration of the call.
        unsafe {
            ffi::whiteout_host_JobGroup_done(self.raw.as_ptr());
        }
    }

    /// Java's Object.wait() is final so the generated wrapper would fail to compile; expose as await(). Block until all pending jobs in the group are completed.
    pub fn await_(&mut self) {
        // SAFETY: handle is live for the duration of the call.
        unsafe {
            ffi::whiteout_host_JobGroup_await(self.raw.as_ptr());
        }
    }

    /// Check whether the group has no pending jobs.
    ///
    /// @return true if pending count is zero, false otherwise.
    pub fn is_ready(&self) -> bool {
        // SAFETY: handle is live for the duration of the call.
        unsafe { ffi::whiteout_host_JobGroup_isReady(self.raw.as_ptr()) != 0 }
    }
}

impl Default for JobGroup {
    fn default() -> Self {
        Self::new()
    }
}

/// Result entry from findBlizzardGames().
pub struct BlizzardGameInfo {
    pub(crate) raw: core::ptr::NonNull<ffi::whiteout_BlizzardGameInfo>,
}

impl Drop for BlizzardGameInfo {
    fn drop(&mut self) {
        // SAFETY: `raw` came from a native constructor and Drop runs once.
        unsafe { ffi::whiteout_host_BlizzardGameInfo_delete(self.raw.as_ptr()) }
    }
}

impl BlizzardGameInfo {
    /// # Safety
    /// `raw` must be a live handle this value takes ownership of.
    #[allow(dead_code)] // used by whichever methods return this type
    pub(crate) unsafe fn from_raw(raw: *mut ffi::whiteout_BlizzardGameInfo) -> Option<Self> {
        core::ptr::NonNull::new(raw).map(|raw| BlizzardGameInfo { raw })
    }
}

// SAFETY: handles are plain heap pointers with no thread affinity. `Sync`
// is deliberately NOT implemented — the C++ types make no documented
// guarantee about concurrent use, and claiming one we haven't verified
// would be unsound. See `@bind thread_safe` in the plan.
unsafe impl Send for BlizzardGameInfo {}

impl core::fmt::Debug for BlizzardGameInfo {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        f.debug_struct("BlizzardGameInfo").finish_non_exhaustive()
    }
}

impl BlizzardGameInfo {
    /// # Panics
    /// Panics if the native allocation fails.
    pub fn new() -> Self {
        // SAFETY: the native constructor returns a live handle; a null here
        // means the library is unusable.
        unsafe {
            let raw = ffi::whiteout_host_BlizzardGameInfo_new();
            Self::from_raw(raw).expect("native BlizzardGameInfo allocation failed")
        }
    }

    /// Identified game. `Unknown` if not recognized.
    pub fn game(&self) -> BlizzardGame {
        // SAFETY: scalar read; the discriminant is validated below.
        unsafe { ffi::whiteout_host_BlizzardGameInfo_get_game(self.raw.as_ptr()) }
            .try_into()
            .expect("unknown enum discriminant from the native library")
    }

    pub fn set_game(&mut self, value: BlizzardGame) {
        // SAFETY: scalar write through a live handle.
        unsafe { ffi::whiteout_host_BlizzardGameInfo_set_game(self.raw.as_ptr(), value as i32) }
    }

    /// Human-readable display name.
    pub fn name(&self) -> String {
        // SAFETY: the native side hands over an owned CString.
        unsafe {
            crate::support::take_string(ffi::whiteout_host_BlizzardGameInfo_get_name(
                self.raw.as_ptr(),
            ))
        }
    }

    pub fn set_name(&mut self, value: &str) {
        let value = std::ffi::CString::new(value).unwrap_or_default();
        // SAFETY: the pointer outlives the call.
        unsafe { ffi::whiteout_host_BlizzardGameInfo_set_name(self.raw.as_ptr(), value.as_ptr()) }
    }

    /// Install directory path.
    pub fn path(&self) -> String {
        // SAFETY: the native side hands over an owned CString.
        unsafe {
            crate::support::take_string(ffi::whiteout_host_BlizzardGameInfo_get_path(
                self.raw.as_ptr(),
            ))
        }
    }

    pub fn set_path(&mut self, value: &str) {
        let value = std::ffi::CString::new(value).unwrap_or_default();
        // SAFETY: the pointer outlives the call.
        unsafe { ffi::whiteout_host_BlizzardGameInfo_set_path(self.raw.as_ptr(), value.as_ptr()) }
    }
}

impl Default for BlizzardGameInfo {
    fn default() -> Self {
        Self::new()
    }
}

/// Opaque handle around `std::vector<BlizzardGameInfo>` returned by `BlizzardGameFinder::findAll()`. Iterate via size() + at(index).
pub struct BlizzardGameInfoList {
    pub(crate) raw: core::ptr::NonNull<ffi::whiteout_BlizzardGameInfoList>,
}

impl Drop for BlizzardGameInfoList {
    fn drop(&mut self) {
        // SAFETY: `raw` came from a native constructor and Drop runs once.
        unsafe { ffi::whiteout_host_BlizzardGameInfoList_delete(self.raw.as_ptr()) }
    }
}

impl BlizzardGameInfoList {
    /// # Safety
    /// `raw` must be a live handle this value takes ownership of.
    #[allow(dead_code)] // used by whichever methods return this type
    pub(crate) unsafe fn from_raw(raw: *mut ffi::whiteout_BlizzardGameInfoList) -> Option<Self> {
        core::ptr::NonNull::new(raw).map(|raw| BlizzardGameInfoList { raw })
    }
}

// SAFETY: handles are plain heap pointers with no thread affinity. `Sync`
// is deliberately NOT implemented — the C++ types make no documented
// guarantee about concurrent use, and claiming one we haven't verified
// would be unsound. See `@bind thread_safe` in the plan.
unsafe impl Send for BlizzardGameInfoList {}

impl core::fmt::Debug for BlizzardGameInfoList {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        f.debug_struct("BlizzardGameInfoList")
            .finish_non_exhaustive()
    }
}

impl BlizzardGameInfoList {
    /// Number of game entries in the list.
    pub fn size(&self) -> usize {
        // SAFETY: handle is live for the duration of the call.
        unsafe { ffi::whiteout_host_BlizzardGameInfoList_size(self.raw.as_ptr()) }
    }

    /// Borrowed reference to entry at @p index. Valid until this list is destroyed.
    pub fn at(&self, index: usize) -> Option<BlizzardGameInfo> {
        // SAFETY: handle is live for the duration of the call.
        unsafe {
            BlizzardGameInfo::from_raw(ffi::whiteout_host_BlizzardGameInfoList_at(
                self.raw.as_ptr(),
                index,
            ))
        }
    }
}

/// Static-method facade around the free functions above so they bind through the class-method codegen path.
pub struct BlizzardGameFinder {
    pub(crate) raw: core::ptr::NonNull<ffi::whiteout_BlizzardGameFinder>,
}

impl Drop for BlizzardGameFinder {
    fn drop(&mut self) {
        // SAFETY: `raw` came from a native constructor and Drop runs once.
        unsafe { ffi::whiteout_host_BlizzardGameFinder_delete(self.raw.as_ptr()) }
    }
}

impl BlizzardGameFinder {
    /// # Safety
    /// `raw` must be a live handle this value takes ownership of.
    #[allow(dead_code)] // used by whichever methods return this type
    pub(crate) unsafe fn from_raw(raw: *mut ffi::whiteout_BlizzardGameFinder) -> Option<Self> {
        core::ptr::NonNull::new(raw).map(|raw| BlizzardGameFinder { raw })
    }
}

// SAFETY: handles are plain heap pointers with no thread affinity. `Sync`
// is deliberately NOT implemented — the C++ types make no documented
// guarantee about concurrent use, and claiming one we haven't verified
// would be unsound. See `@bind thread_safe` in the plan.
unsafe impl Send for BlizzardGameFinder {}

impl core::fmt::Debug for BlizzardGameFinder {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        f.debug_struct("BlizzardGameFinder").finish_non_exhaustive()
    }
}

impl BlizzardGameFinder {
    /// Discover installed Blizzard games. See `findBlizzardGames()`.
    pub fn find_all() -> Option<BlizzardGameInfoList> {
        // SAFETY: handle is live for the duration of the call.
        unsafe { BlizzardGameInfoList::from_raw(ffi::whiteout_host_BlizzardGameFinder_findAll()) }
    }

    /// Map a display name to a BlizzardGame enum. See `blizzardGameFromName()`.
    pub fn from_name(name: &str) -> BlizzardGame {
        let name_cstr = std::ffi::CString::new(name).unwrap_or_default();
        // SAFETY: handle is live for the duration of the call.
        unsafe {
            BlizzardGame::try_from(ffi::whiteout_host_BlizzardGameFinder_fromName(
                name_cstr.as_ptr(),
            ))
            .expect("unknown enum discriminant from the native library (ABI version skew)")
        }
    }

    /// Get the canonical display name for a known game. See `blizzardGameToName()`. Returns empty string for Unknown.
    pub fn to_name(game: BlizzardGame) -> String {
        // SAFETY: handle is live for the duration of the call.
        unsafe {
            crate::support::take_string(ffi::whiteout_host_BlizzardGameFinder_toName(game as i32))
        }
    }
}

#[doc(hidden)]
pub mod ffi {
    #![allow(missing_debug_implementations)]

    #[allow(unused_imports)]
    use crate::support::{RawBytes, RawCString};

    #[repr(C)]
    pub struct whiteout_WorkerPool {
        _private: [u8; 0],
    }
    #[repr(C)]
    pub struct whiteout_CascFileSystem {
        _private: [u8; 0],
    }
    #[repr(C)]
    pub struct whiteout_VirtualPathFileSystem {
        _private: [u8; 0],
    }
    #[repr(C)]
    pub struct whiteout_HttpResponse {
        _private: [u8; 0],
    }
    #[repr(C)]
    pub struct whiteout_HttpHandler {
        _private: [u8; 0],
    }
    #[repr(C)]
    pub struct whiteout_OsFileSystem {
        _private: [u8; 0],
    }
    #[repr(C)]
    pub struct whiteout_SimpleThreadPool {
        _private: [u8; 0],
    }
    #[repr(C)]
    pub struct whiteout_SimpleHttpHandler {
        _private: [u8; 0],
    }
    #[repr(C)]
    pub struct whiteout_JobGroup {
        _private: [u8; 0],
    }
    #[repr(C)]
    pub struct whiteout_BlizzardGameInfo {
        _private: [u8; 0],
    }
    #[repr(C)]
    pub struct whiteout_BlizzardGameInfoList {
        _private: [u8; 0],
    }
    #[repr(C)]
    pub struct whiteout_BlizzardGameFinder {
        _private: [u8; 0],
    }

    extern "C" {
        // WorkerPool
        pub fn whiteout_host_WorkerPool_delete(self_: *mut whiteout_WorkerPool);
        pub fn whiteout_host_WorkerPool_waitIdle(self_: *mut whiteout_WorkerPool);
        pub fn whiteout_host_WorkerPool_threadCount(self_: *mut whiteout_WorkerPool) -> usize;
        // CascFileSystem
        pub fn whiteout_host_CascFileSystem_delete(self_: *mut whiteout_CascFileSystem);
        pub fn whiteout_host_CascFileSystem_readFile(
            self_: *mut whiteout_CascFileSystem,
            file_id: u32,
        ) -> RawBytes;
        pub fn whiteout_host_CascFileSystem_reserveFileId(
            self_: *mut whiteout_CascFileSystem,
            path: *const core::ffi::c_char,
            out_value: *mut u32,
        ) -> i32;
        pub fn whiteout_host_CascFileSystem_writeFile(
            self_: *mut whiteout_CascFileSystem,
            file_id: u32,
            data: *const u8,
            data_size: usize,
        ) -> i32;
        pub fn whiteout_host_CascFileSystem_fileExists(
            self_: *mut whiteout_CascFileSystem,
            file_id: u32,
        ) -> i32;
        // VirtualPathFileSystem
        pub fn whiteout_host_VirtualPathFileSystem_delete(
            self_: *mut whiteout_VirtualPathFileSystem,
        );
        pub fn whiteout_host_VirtualPathFileSystem_readFile(
            self_: *mut whiteout_VirtualPathFileSystem,
            path: *const core::ffi::c_char,
        ) -> RawBytes;
        pub fn whiteout_host_VirtualPathFileSystem_writeFile(
            self_: *mut whiteout_VirtualPathFileSystem,
            path: *const core::ffi::c_char,
            data: *const u8,
            data_size: usize,
        ) -> i32;
        pub fn whiteout_host_VirtualPathFileSystem_fileExists(
            self_: *mut whiteout_VirtualPathFileSystem,
            path: *const core::ffi::c_char,
        ) -> i32;
        // HttpResponse
        pub fn whiteout_host_HttpResponse_new() -> *mut whiteout_HttpResponse;
        pub fn whiteout_host_HttpResponse_delete(self_: *mut whiteout_HttpResponse);
        pub fn whiteout_host_HttpResponse_get_statusCode(self_: *mut whiteout_HttpResponse) -> i32;
        pub fn whiteout_host_HttpResponse_set_statusCode(
            self_: *mut whiteout_HttpResponse,
            value: i32,
        );
        pub fn whiteout_host_HttpResponse_get_body_count(
            self_: *mut whiteout_HttpResponse,
        ) -> usize;
        pub fn whiteout_host_HttpResponse_resize_body(
            self_: *mut whiteout_HttpResponse,
            count: usize,
        );
        pub fn whiteout_host_HttpResponse_get_body_data(
            self_: *mut whiteout_HttpResponse,
        ) -> *const u8;
        pub fn whiteout_host_HttpResponse_assign_body(
            self_: *mut whiteout_HttpResponse,
            data: *const u8,
            count: usize,
        );
        pub fn whiteout_host_HttpResponse_get_error(
            self_: *mut whiteout_HttpResponse,
        ) -> RawCString;
        pub fn whiteout_host_HttpResponse_set_error(
            self_: *mut whiteout_HttpResponse,
            value: *const core::ffi::c_char,
        );
        // HttpHandler
        pub fn whiteout_host_HttpHandler_delete(self_: *mut whiteout_HttpHandler);
        pub fn whiteout_host_HttpHandler_capabilities(self_: *mut whiteout_HttpHandler) -> u32;
        // OsFileSystem
        pub fn whiteout_host_OsFileSystem_new_rootPath(
            _0: *mut core::ffi::c_void,
        ) -> *mut whiteout_OsFileSystem;
        pub fn whiteout_host_OsFileSystem_delete(self_: *mut whiteout_OsFileSystem);
        pub fn whiteout_host_OsFileSystem_readFile(
            self_: *mut whiteout_OsFileSystem,
            path: *const core::ffi::c_char,
        ) -> RawBytes;
        pub fn whiteout_host_OsFileSystem_writeFile(
            self_: *mut whiteout_OsFileSystem,
            path: *const core::ffi::c_char,
            data: *const u8,
            data_size: usize,
        ) -> i32;
        pub fn whiteout_host_OsFileSystem_fileExists(
            self_: *mut whiteout_OsFileSystem,
            path: *const core::ffi::c_char,
        ) -> i32;
        // SimpleThreadPool
        pub fn whiteout_host_SimpleThreadPool_new_nThreads(
            _0: *mut core::ffi::c_void,
        ) -> *mut whiteout_SimpleThreadPool;
        pub fn whiteout_host_SimpleThreadPool_delete(self_: *mut whiteout_SimpleThreadPool);
        pub fn whiteout_host_SimpleThreadPool_waitIdle(self_: *mut whiteout_SimpleThreadPool);
        pub fn whiteout_host_SimpleThreadPool_threadCount(
            self_: *mut whiteout_SimpleThreadPool,
        ) -> usize;
        // SimpleHttpHandler
        pub fn whiteout_host_SimpleHttpHandler_new() -> *mut whiteout_SimpleHttpHandler;
        pub fn whiteout_host_SimpleHttpHandler_new_nThreads(
            _0: *mut core::ffi::c_void,
        ) -> *mut whiteout_SimpleHttpHandler;
        pub fn whiteout_host_SimpleHttpHandler_delete(self_: *mut whiteout_SimpleHttpHandler);
        pub fn whiteout_host_SimpleHttpHandler_capabilities(
            self_: *mut whiteout_SimpleHttpHandler,
        ) -> u32;
        // JobGroup
        pub fn whiteout_host_JobGroup_new() -> *mut whiteout_JobGroup;
        pub fn whiteout_host_JobGroup_delete(self_: *mut whiteout_JobGroup);
        pub fn whiteout_host_JobGroup_add(self_: *mut whiteout_JobGroup, n: usize);
        pub fn whiteout_host_JobGroup_done(self_: *mut whiteout_JobGroup);
        pub fn whiteout_host_JobGroup_await(self_: *mut whiteout_JobGroup);
        pub fn whiteout_host_JobGroup_isReady(self_: *mut whiteout_JobGroup) -> i32;
        // BlizzardGameInfo
        pub fn whiteout_host_BlizzardGameInfo_new() -> *mut whiteout_BlizzardGameInfo;
        pub fn whiteout_host_BlizzardGameInfo_delete(self_: *mut whiteout_BlizzardGameInfo);
        pub fn whiteout_host_BlizzardGameInfo_get_game(
            self_: *mut whiteout_BlizzardGameInfo,
        ) -> i32;
        pub fn whiteout_host_BlizzardGameInfo_set_game(
            self_: *mut whiteout_BlizzardGameInfo,
            value: i32,
        );
        pub fn whiteout_host_BlizzardGameInfo_get_name(
            self_: *mut whiteout_BlizzardGameInfo,
        ) -> RawCString;
        pub fn whiteout_host_BlizzardGameInfo_set_name(
            self_: *mut whiteout_BlizzardGameInfo,
            value: *const core::ffi::c_char,
        );
        pub fn whiteout_host_BlizzardGameInfo_get_path(
            self_: *mut whiteout_BlizzardGameInfo,
        ) -> RawCString;
        pub fn whiteout_host_BlizzardGameInfo_set_path(
            self_: *mut whiteout_BlizzardGameInfo,
            value: *const core::ffi::c_char,
        );
        // BlizzardGameInfoList
        pub fn whiteout_host_BlizzardGameInfoList_delete(self_: *mut whiteout_BlizzardGameInfoList);
        pub fn whiteout_host_BlizzardGameInfoList_size(
            self_: *mut whiteout_BlizzardGameInfoList,
        ) -> usize;
        pub fn whiteout_host_BlizzardGameInfoList_at(
            self_: *mut whiteout_BlizzardGameInfoList,
            index: usize,
        ) -> *mut whiteout_BlizzardGameInfo;
        // BlizzardGameFinder
        pub fn whiteout_host_BlizzardGameFinder_delete(self_: *mut whiteout_BlizzardGameFinder);
        pub fn whiteout_host_BlizzardGameFinder_findAll() -> *mut whiteout_BlizzardGameInfoList;
        pub fn whiteout_host_BlizzardGameFinder_fromName(name: *const core::ffi::c_char) -> i32;
        pub fn whiteout_host_BlizzardGameFinder_toName(game: i32) -> RawCString;
    }
}