wdext 0.1.0

// SPDX-FileCopyrightText: 2026 takubokudori
// SPDX-License-Identifier: MIT OR Apache-2.0
//! IDebugDataSpaces
use crate::dbgeng::*;
use bitflags::bitflags;
use std::{ffi::c_void, mem::MaybeUninit};
use windows::{
    Win32::{
        Foundation::E_UNEXPECTED, System::Memory::MEMORY_BASIC_INFORMATION64,
    },
    core::{GUID, PSTR, PWSTR},
};
use windy::{ACPString, WString};

impl_debug_interface!(
    DebugDataSpaces,
    DebugDataSpacesRef,
    IDebugDataSpaces4,
    IDebugDataSpaces
);

/// This handle is not released automatically. Release it explicitly with [`DebugDataSpaces::end_enum_tagged`].
#[derive(Debug, Eq, PartialEq)]
pub struct EnumTaggedHandle(u64);

impl EnumTaggedHandle {
    /// Returns the wrapped raw value.
    pub fn as_raw(&self) -> u64 { self.0 }
}

bitflags! {
    pub struct DebugVSearchFlags: u32 {
        const Default = DEBUG_VSEARCH_DEFAULT;
        const WritableOnly = DEBUG_VSEARCH_WRITABLE_ONLY;
    }
}

/// IDebugDataSpaces
impl DebugDataSpaces {
    pub fn read_virtual(
        &self,
        offset: DebuggeeOffset,
        buffer: &mut [u8],
    ) -> WinResult<u32> {
        let buffer = to_uninit_u8_slice(buffer);
        self._read_virtual_uninit(offset, buffer)
    }

    pub fn _read_virtual_uninit(
        &self,
        offset: DebuggeeOffset,
        buffer: &mut [MaybeUninit<u8>],
    ) -> WinResult<u32> {
        let mut bytes_read = 0;
        unsafe {
            self.0.ReadVirtual(
                offset,
                buffer.as_mut_ptr() as *mut c_void,
                buffer.len().try_into()?,
                Some(&mut bytes_read),
            )?;
            assert!(
                bytes_read as usize <= buffer.len(),
                "DbgEng returned a read count larger than the supplied buffer"
            );
            Ok(bytes_read)
        }
    }

    pub fn write_virtual(
        &self,
        offset: DebuggeeOffset,
        buffer: &[u8],
    ) -> WinResult<u32> {
        let mut bytes_written = 0;
        unsafe {
            self.0.WriteVirtual(
                offset,
                buffer.as_ptr() as *const c_void,
                buffer.len().try_into()?,
                Some(&mut bytes_written),
            )?;
            Ok(bytes_written)
        }
    }

    pub fn search_virtual(
        &self,
        offset: DebuggeeOffset,
        length: u64,
        pattern: &[u8],
        pattern_granularity: u32,
    ) -> WinResult<u64> {
        unsafe {
            self.0.SearchVirtual(
                offset,
                length,
                pattern.as_ptr() as *const c_void,
                pattern.len().try_into()?,
                pattern_granularity,
            )
        }
    }

    pub fn read_virtual_uncached(
        &self,
        offset: DebuggeeOffset,
        buffer: &mut [u8],
    ) -> WinResult<u32> {
        let buffer = to_uninit_u8_slice(buffer);
        self._read_virtual_uncached_uninit(offset, buffer)
    }

    pub fn _read_virtual_uncached_uninit(
        &self,
        offset: DebuggeeOffset,
        buffer: &mut [MaybeUninit<u8>],
    ) -> WinResult<u32> {
        let mut bytes_read = 0;
        unsafe {
            self.0.ReadVirtualUncached(
                offset,
                buffer.as_mut_ptr() as *mut c_void,
                buffer.len().try_into()?,
                Some(&mut bytes_read),
            )?;
            assert!(
                bytes_read as usize <= buffer.len(),
                "DbgEng returned a read count larger than the supplied buffer"
            );
            Ok(bytes_read)
        }
    }

    pub fn write_virtual_uncached(
        &self,
        offset: DebuggeeOffset,
        buffer: &[u8],
    ) -> WinResult<u32> {
        let mut bytes_written = 0;
        unsafe {
            self.0.WriteVirtualUncached(
                offset,
                buffer.as_ptr() as *const c_void,
                buffer.len().try_into()?,
                Some(&mut bytes_written),
            )?;
            Ok(bytes_written)
        }
    }

    pub fn read_pointers_virtual(
        &self,
        offset: DebuggeeOffset,
        ptrs: &mut [DebuggeeOffset],
    ) -> WinResult<()> {
        unsafe { self.0.ReadPointersVirtual(offset, ptrs) }
    }

    pub fn write_pointers_virtual(
        &self,
        offset: DebuggeeOffset,
        ptrs: &[DebuggeeOffset],
    ) -> WinResult<()> {
        unsafe { self.0.WritePointersVirtual(offset, ptrs) }
    }

    pub fn read_physical(
        &self,
        offset: DebuggeeOffset,
        buffer: &mut [u8],
    ) -> WinResult<u32> {
        let mut bytes_read = 0;
        unsafe {
            self.0.ReadPhysical(
                offset,
                buffer.as_mut_ptr() as *mut c_void,
                buffer.len().try_into()?,
                Some(&mut bytes_read),
            )?;
            assert!(
                bytes_read as usize <= buffer.len(),
                "DbgEng returned a read count larger than the supplied buffer"
            );
            Ok(bytes_read)
        }
    }

    pub fn write_physical(
        &self,
        offset: DebuggeeOffset,
        buffer: &[u8],
    ) -> WinResult<u32> {
        let mut bytes_written = 0;
        unsafe {
            self.0.WritePhysical(
                offset,
                buffer.as_ptr() as *const c_void,
                buffer.len().try_into()?,
                Some(&mut bytes_written),
            )?;
            Ok(bytes_written)
        }
    }

    pub fn read_control(
        &self,
        processor: u32,
        offset: u64,
        buffer: &mut [u8],
    ) -> WinResult<u32> {
        let buffer = to_uninit_u8_slice(buffer);
        self._read_control_uninit(processor, offset, buffer)
    }

    pub(crate) fn _read_control_uninit(
        &self,
        processor: u32,
        offset: u64,
        buffer: &mut [MaybeUninit<u8>],
    ) -> WinResult<u32> {
        let mut bytes_read = 0;
        unsafe {
            self.0.ReadControl(
                processor,
                offset,
                buffer.as_mut_ptr() as *mut c_void,
                buffer.len().try_into()?,
                Some(&mut bytes_read),
            )?;
            assert!(
                bytes_read as usize <= buffer.len(),
                "DbgEng returned a read count larger than the supplied buffer"
            );
            Ok(bytes_read)
        }
    }

    pub fn write_control(
        &self,
        processor: u32,
        offset: u64,
        buffer: &[u8],
    ) -> WinResult<u32> {
        let mut bytes_written = 0;
        unsafe {
            self.0.WriteControl(
                processor,
                offset,
                buffer.as_ptr() as *const c_void,
                buffer.len().try_into()?,
                Some(&mut bytes_written),
            )?;
            Ok(bytes_written)
        }
    }

    pub fn read_io(
        &self,
        interface_type: InterfaceType,
        bus_number: u32,
        address_space: u32, // is always 1
        offset: DebuggeeOffset,
        buffer: &mut [u8],
    ) -> WinResult<u32> {
        let buffer = to_uninit_u8_slice(buffer);
        self._read_io_uninit(
            interface_type,
            bus_number,
            address_space,
            offset,
            buffer,
        )
    }

    pub fn _read_io_uninit(
        &self,
        interface_type: InterfaceType,
        bus_number: u32,
        address_space: u32, // is always 1
        offset: DebuggeeOffset,
        buffer: &mut [MaybeUninit<u8>],
    ) -> WinResult<u32> {
        let mut bytes_read = 0;
        unsafe {
            self.0.ReadIo(
                interface_type.into(),
                bus_number,
                address_space,
                offset,
                buffer.as_mut_ptr() as *mut c_void,
                buffer.len().try_into()?,
                Some(&mut bytes_read),
            )?;
            assert!(
                bytes_read as usize <= buffer.len(),
                "DbgEng returned a read count larger than the supplied buffer"
            );
            Ok(bytes_read)
        }
    }

    pub fn write_io(
        &self,
        interface_type: InterfaceType,
        bus_number: u32,
        address_space: u32, // is always 1
        offset: DebuggeeOffset,
        buffer: &[u8],
    ) -> WinResult<u32> {
        let mut bytes_written = 0;
        unsafe {
            self.0.WriteIo(
                interface_type.into(),
                bus_number,
                address_space,
                offset,
                buffer.as_ptr() as *const c_void,
                buffer.len().try_into()?,
                Some(&mut bytes_written),
            )?;
        }
        Ok(bytes_written)
    }

    pub fn read_msr(&self, msr: u32) -> WinResult<u64> {
        unsafe { self.0.ReadMsr(msr) }
    }

    pub fn write_msr(&self, msr: u32, value: u64) -> WinResult<()> {
        unsafe { self.0.WriteMsr(msr, value) }
    }

    pub fn read_bus_data(
        &self,
        bus_data_type: BusDataType,
        bus_number: u32,
        slot_number: u32,
        offset: u32,
        buffer: &mut [u8],
    ) -> WinResult<u32> {
        let buffer = to_uninit_u8_slice(buffer);
        self._read_bus_data_uninit(
            bus_data_type,
            bus_number,
            slot_number,
            offset,
            buffer,
        )
    }

    pub fn _read_bus_data_uninit(
        &self,
        bus_data_type: BusDataType,
        bus_number: u32,
        slot_number: u32,
        offset: u32,
        buffer: &mut [MaybeUninit<u8>],
    ) -> WinResult<u32> {
        let mut bytes_read = 0;
        unsafe {
            self.0.ReadBusData(
                bus_data_type as u32,
                bus_number,
                slot_number,
                offset,
                buffer.as_mut_ptr() as *mut c_void,
                buffer.len().try_into()?,
                Some(&mut bytes_read),
            )?;
            assert!(
                bytes_read as usize <= buffer.len(),
                "DbgEng returned a read count larger than the supplied buffer"
            );
            Ok(bytes_read)
        }
    }

    pub fn write_bus_data(
        &self,
        bus_data_type: BusDataType,
        bus_number: u32,
        slot_number: u32,
        offset: u32,
        buffer: &[u8],
    ) -> WinResult<u32> {
        let mut bytes_written = 0;
        unsafe {
            self.0.WriteBusData(
                bus_data_type as u32,
                bus_number,
                slot_number,
                offset,
                buffer.as_ptr() as *const c_void,
                buffer.len().try_into()?,
                Some(&mut bytes_written),
            )?;
            Ok(bytes_written)
        }
    }

    pub fn check_low_memory(&self) -> WinResult<()> {
        unsafe { self.0.CheckLowMemory() }
    }

    pub fn read_debugger_data(&self, index: u32) -> WinResult<u64> {
        let mut buffer: u64 = 0;
        let mut data_size = 0;
        unsafe {
            self.0.ReadDebuggerData(
                index,
                &mut buffer as *mut u64 as *mut _,
                size_of_val(&buffer) as u32,
                Some(&mut data_size),
            )?;

            match data_size {
                1 => Ok((buffer as u8) as u64),
                2 => Ok((buffer as u16) as u64),
                4 => Ok((buffer as u32) as u64),
                8 => Ok(buffer),
                _ => Err(E_UNEXPECTED.into()),
            }
        }
    }

    pub fn read_processor_system_data(
        &self,
        processor: u32,
        index: DebugDataType,
        buffer: &mut [u8],
    ) -> WinResult<u32> {
        let mut bytes_read = 0;
        unsafe {
            self.0.ReadProcessorSystemData(
                processor,
                index as u32,
                buffer.as_mut_ptr() as *mut c_void,
                buffer.len().try_into()?,
                Some(&mut bytes_read),
            )?;
            assert!(
                bytes_read as usize <= buffer.len(),
                "DbgEng returned a read count larger than the supplied buffer"
            );
            Ok(bytes_read)
        }
    }
}

/// IDebugDataSpaces2
impl DebugDataSpaces {
    pub fn virtual_to_physical(
        &self,
        virtual_address: DebuggeeOffset,
    ) -> WinResult<DebuggeeOffset> {
        unsafe { self.0.VirtualToPhysical(virtual_address) }
    }

    pub fn get_virtual_translation_physical_offsets(
        &self,
        virtual_address: DebuggeeOffset,
        offsets: &mut [DebuggeeOffset],
    ) -> WinResult<u32> {
        let mut levels = 0;
        unsafe {
            self.0.GetVirtualTranslationPhysicalOffsets(
                virtual_address,
                Some(offsets),
                Some(&mut levels),
            )?;
            Ok(levels)
        }
    }

    // ReadHandleData

    pub fn fill_virtual(
        &self,
        start: DebuggeeOffset,
        size: u32,
        pattern: &[u8],
    ) -> WinResult<u32> {
        let mut sz = 0;
        unsafe {
            self.0.FillVirtual(
                start,
                size,
                pattern.as_ptr() as *mut c_void,
                pattern.len().try_into()?,
                Some(&mut sz),
            )?;
            Ok(sz)
        }
    }

    pub fn fill_physical(
        &self,
        start: DebuggeeOffset,
        size: u32,
        pattern: &[u8],
    ) -> WinResult<u32> {
        let mut filled = 0;
        unsafe {
            self.0.FillPhysical(
                start,
                size,
                pattern.as_ptr() as *mut c_void,
                pattern.len().try_into()?,
                Some(&mut filled),
            )?;
            Ok(filled)
        }
    }

    // QueryVirtual
    pub fn query_virtual(
        &self,
        offset: DebuggeeOffset,
    ) -> WinResult<MEMORY_BASIC_INFORMATION64> {
        unsafe {
            let mut info = MaybeUninit::<MEMORY_BASIC_INFORMATION64>::uninit();
            self.0.QueryVirtual(offset, info.as_mut_ptr())?;
            Ok(info.assume_init())
        }
    }
}

/// IDebugDataSpaces3
impl DebugDataSpaces {
    // ReadImageNtHeaders

    pub fn read_tagged(
        &self,
        tag: &GUID,
        offset: u32,
        buffer: &mut [u8],
    ) -> WinResult<u32> {
        let mut size = 0;
        unsafe {
            self.0.ReadTagged(
                tag as *const _,
                offset,
                Some(buffer.as_mut_ptr() as *mut c_void),
                buffer.len().try_into()?,
                Some(&mut size),
            )?;
            Ok(size)
        }
    }

    pub fn start_enum_tagged(&self) -> WinResult<EnumTaggedHandle> {
        unsafe { Ok(EnumTaggedHandle(self.0.StartEnumTagged()?)) }
    }

    pub fn get_next_tagged(
        &self,
        handle: &EnumTaggedHandle,
    ) -> WinResult<Option<(GUID, u32)>> {
        let mut guid = GUID::zeroed();
        let mut size = 0;
        unsafe {
            if hr!(vcall!(self, GetNextTagged, handle.0, &mut guid, &mut size))?
            {
                Ok(Some((guid, size)))
            } else {
                Ok(None)
            }
        }
    }

    pub fn end_enum_tagged(&self, handle: EnumTaggedHandle) -> WinResult<()> {
        unsafe { self.0.EndEnumTagged(handle.0) }
    }
}

// IDebugDataSpaces4
impl DebugDataSpaces {
    // GetOffsetInformation

    pub fn get_next_differently_valid_offset_virtual(
        &self,
        offset: DebuggeeOffset,
    ) -> WinResult<DebuggeeOffset> {
        unsafe { self.0.GetNextDifferentlyValidOffsetVirtual(offset) }
    }

    pub fn get_valid_region_virtual(
        &self,
        base: u64,
        size: u32,
    ) -> WinResult<(DebuggeeOffset, u32)> {
        let mut valid_base = 0;
        let mut valid_size = 0;
        unsafe {
            self.0.GetValidRegionVirtual(
                base,
                size,
                &mut valid_base,
                &mut valid_size,
            )?;
            Ok((valid_base, valid_size))
        }
    }

    pub fn search_virtual2(
        &self,
        offset: DebuggeeOffset,
        length: u64,
        flags: DebugVSearchFlags,
        pattern: &[u8],
        pattern_granularity: u32,
    ) -> WinResult<u64> {
        unsafe {
            self.0.SearchVirtual2(
                offset,
                length,
                flags.bits(),
                pattern.as_ptr() as *const c_void,
                pattern.len().try_into()?,
                pattern_granularity,
            )
        }
    }

    pub fn read_multi_byte_string_virtual(
        &self,
        offset: DebuggeeOffset,
        max_bytes: u32,
    ) -> WinResult<(ACPString, bool)> {
        let mut v = Vec::with_capacity(max_bytes as usize);
        unsafe {
            let (hr, string_bytes) = self
                .__read_multi_byte_string_virtual_inner(
                    offset,
                    max_bytes,
                    v.spare_capacity_mut(),
                )?;
            match hr {
                S_OK => {
                    let string_bytes = string_bytes.unwrap();
                    // Successfully read including the null byte.
                    assert!(max_bytes >= string_bytes);
                    v.set_len(string_bytes as usize);
                    assert_eq!(v[v.len() - 1], 0);
                    Ok((
                        ACPString::new(v).map_err(|e| {
                            HRESULT::from_win32(e.as_error_code())
                        })?,
                        true,
                    ))
                }
                S_FALSE | E_INVALIDARG => Ok((
                    ACPString::new(v)
                        .map_err(|e| HRESULT::from_win32(e.as_error_code()))?,
                    false,
                )),
                _ => unreachable!(),
            }
        }
    }

    pub(crate) fn __read_multi_byte_string_virtual_inner(
        &self,
        offset: DebuggeeOffset,
        max_bytes: u32,
        buffer: &mut [MaybeUninit<u8>],
    ) -> WinResult<(HRESULT, Option<u32>)> {
        if max_bytes == 0 && buffer.is_empty() {
            // When MaxBytes == 0 && BufferSize == 0, ReadMultiByteStringVirtual returns `S_OK`
            // and stores the string length in bytes in StringBytes.
            // On the other hand, ReadUnicodeStringVirtual returns E_INVALIDARG
            // and does not store anything in StringBytes.
            // Since this behavior is inconsistent, treat this condition as `E_INVALIDARG`.
            return Ok((E_INVALIDARG, None));
        }
        let mut string_bytes = 0;
        unsafe {
            let hr = vcall!(
                self,
                ReadMultiByteStringVirtual,
                offset,
                max_bytes,
                PSTR(buffer.as_mut_ptr() as *mut u8),
                // MaxBytes and StringBytes is in bytes, but BufferSize is in characters.
                buffer.len().try_into()?,
                &mut string_bytes,
            );
            match hr {
                S_OK => {
                    // Successfully read including the null byte.
                    Ok((S_OK, Some(string_bytes)))
                }
                S_FALSE => {
                    // The BufferSize limit was reached before the MaxBytes limit.
                    // In this case, StringBytes contains the number of bytes required to store the string.
                    Ok((S_FALSE, Some(string_bytes)))
                }
                E_INVALIDARG => {
                    // The MaxBytes limit was reached before the BufferSize limit. Note that the MaxBytes limit is reached earlier.
                    // The string was too long and was truncated.
                    // In this case, `string_bytes` is 0, and the byte length of `v` is `max_bytes`.
                    Ok((E_INVALIDARG, None))
                }
                hr => Err(hr.into()),
            }
        }
    }

    //ReadMultiByteStringVirtualWide

    // ReadUnicodeStringVirtual

    pub fn read_unicode_string_virtual_wide(
        &self,
        offset: DebuggeeOffset,
        mut max_bytes: u32,
    ) -> WinResult<(WString, bool)> {
        if max_bytes & 1 == 1 {
            // If `max_bytes` is odd, it may try to read one extra byte.
            max_bytes = max_bytes
                .checked_add(1)
                .ok_or_else(|| windows::core::Error::from(E_INVALIDARG))?;
        }
        let max_cap = max_bytes / size_of::<u16>() as u32;
        let mut v = Vec::with_capacity(max_cap as usize);
        unsafe {
            let (hr, string_bytes) = self
                .__read_unicode_string_virtual_wide_inner(
                    offset,
                    max_bytes,
                    v.spare_capacity_mut(),
                )?;
            match hr {
                S_OK => {
                    let string_bytes = string_bytes.unwrap();
                    // Successfully read including the null byte.
                    assert!(max_bytes >= string_bytes);
                    v.set_len(string_bytes as usize / size_of::<u16>());
                    assert_eq!(v[v.len() - 1], 0);
                    Ok((
                        WString::new(v).map_err(|e| {
                            HRESULT::from_win32(e.as_error_code())
                        })?,
                        true,
                    ))
                }
                S_FALSE | E_INVALIDARG => Ok((
                    WString::new(v)
                        .map_err(|e| HRESULT::from_win32(e.as_error_code()))?,
                    false,
                )),
                _ => unreachable!(),
            }
        }
    }

    pub(crate) fn __read_unicode_string_virtual_wide_inner(
        &self,
        offset: DebuggeeOffset,
        max_bytes: u32,
        buffer: &mut [MaybeUninit<u16>],
    ) -> WinResult<(HRESULT, Option<u32>)> {
        if max_bytes == 1 {
            // An infinite loop occurs when max_bytes is 1. Is this DbgEng's bug?
            return Ok((E_INVALIDARG, None));
        }
        if max_bytes == 0 && buffer.is_empty() {
            // When MaxBytes == 0 && BufferSize == 0, ReadMultiByteStringVirtual returns `S_OK`
            // and stores the string length in bytes in StringBytes.
            // On the other hand, ReadUnicodeStringVirtual returns E_INVALIDARG
            // and does not store anything in StringBytes.
            // Since this behavior is inconsistent, treat this condition as `E_INVALIDARG`.
            return Ok((E_INVALIDARG, None));
        }

        let mut string_bytes = 0;
        unsafe {
            // SAFETY: When `max_bytes` is odd, up to `max_bytes + 1` bytes may be read.
            // However, `buffer` is 2 * N bytes, and if the buffer is too small,
            // DbgEng handles it, so this is not an issue.
            // For surrogate pairs, data is read 2 bytes at a time;
            // it is not read as 4 bytes at once.
            let hr = vcall!(
                self,
                ReadUnicodeStringVirtualWide,
                offset,
                max_bytes,
                PWSTR(buffer.as_mut_ptr() as *mut u16),
                // MaxBytes and StringBytes is in bytes, but BufferSize is in characters.
                buffer.len().try_into()?,
                &mut string_bytes,
            );
            match hr {
                S_OK => {
                    // Successfully read including the null byte.
                    Ok((S_OK, Some(string_bytes)))
                }
                S_FALSE => {
                    // The BufferSize limit was reached before the MaxBytes limit.
                    // In this case, StringBytes contains the number of bytes required to store the string.
                    // When the `BufferSize` limit is reached before the `MaxBytes` limit,
                    // `StringBytes` contains the number of bytes required to store the string.
                    Ok((S_FALSE, Some(string_bytes)))
                }
                E_INVALIDARG => {
                    // The MaxBytes limit was reached before the BufferSize limit.
                    // Note that the MaxBytes limit is reached earlier.
                    // The string was too long and was truncated.
                    // In this case, `string_bytes` is 0, and the byte length of `v` is `max_bytes`.
                    Ok((E_INVALIDARG, None))
                }
                hr => Err(hr.into()),
            }
        }
    }

    pub fn read_physical2(
        &self,
        offset: DebuggeeOffset,
        flags: DebugPhysicalFlags,
        buffer: &mut [u8],
    ) -> WinResult<u32> {
        let buffer = to_uninit_u8_slice(buffer);
        self._read_physical2_uninit(offset, flags, buffer)
    }

    pub fn _read_physical2_uninit(
        &self,
        offset: DebuggeeOffset,
        flags: DebugPhysicalFlags,
        buffer: &mut [MaybeUninit<u8>],
    ) -> WinResult<u32> {
        let mut bytes_read = 0;
        unsafe {
            self.0.ReadPhysical2(
                offset,
                flags as u32,
                buffer.as_mut_ptr() as *mut c_void,
                buffer.len().try_into()?,
                Some(&mut bytes_read),
            )?;
            assert!(
                bytes_read as usize <= buffer.len(),
                "DbgEng returned a read count larger than the supplied buffer"
            );
            Ok(bytes_read)
        }
    }

    pub fn write_physical2(
        &self,
        offset: DebuggeeOffset,
        flags: DebugPhysicalFlags,
        buffer: &[u8],
    ) -> WinResult<u32> {
        let mut sz = 0;
        unsafe {
            self.0.WritePhysical2(
                offset,
                flags as u32,
                buffer.as_ptr() as *const c_void,
                buffer.len().try_into()?,
                Some(&mut sz),
            )?;
            Ok(sz)
        }
    }
}