windows_emulator

Overview

The windows_emulator class is the primary interface for Windows user-space emulation. It manages the entire emulation environment including memory, processes, threads, file system, registry, and network operations.

Constructor

windows_emulator(
    std::unique_ptr<x86_64_emulator> emu,
    const emulator_settings& settings = {},
    emulator_callbacks callbacks = {},
    emulator_interfaces interfaces = {}
)

Creates a new Windows emulator instance.

std::unique_ptr<x86_64_emulator>

required

The underlying x86-64 CPU emulator instance

const emulator_settings&

default:"{}"

Configuration settings for the emulator

emulator_callbacks

default:"{}"

Event callbacks for monitoring emulation events

emulator_interfaces

default:"{}"

Optional custom implementations for clock and socket factory

Alternative Constructor with Application

windows_emulator(
    std::unique_ptr<x86_64_emulator> emu,
    application_settings app_settings,
    const emulator_settings& settings = {},
    emulator_callbacks callbacks = {},
    emulator_interfaces interfaces = {}
)

Creates a new Windows emulator with application settings.

application_settings

required

Application configuration including path, working directory, and arguments

Public Members

The windows_emulator class exposes several public components:

emulator_callbacks

Event callbacks for monitoring emulation behavior

logger

Logging interface for emulation events

file_system

Virtual file system manager

memory_manager

Memory management interface

registry_manager

Windows registry manager

windows_version_manager

Windows version information manager

module_manager

Module/DLL loading and management

process_context

Process and thread context information

syscall_dispatcher

System call dispatcher

Methods

emu()

x86_64_emulator& emu()
const x86_64_emulator& emu() const

Returns a reference to the underlying CPU emulator. Returns: Reference to the x86-64 emulator instance Source: windows_emulator.hpp:116

clock()

utils::clock& clock()
const utils::clock& clock() const

Returns a reference to the emulator’s clock. Returns: Reference to the clock interface Source: windows_emulator.hpp:126

socket_factory()

network::socket_factory& socket_factory()
const network::socket_factory& socket_factory() const

Returns a reference to the socket factory for network operations. Returns: Reference to the socket factory Source: windows_emulator.hpp:136

current_thread()

emulator_thread& current_thread() const

Returns the currently active emulator thread. Returns: Reference to the active thread Throws: std::runtime_error if no active thread exists Source: windows_emulator.hpp:146

get_executed_instructions()

uint64_t get_executed_instructions() const

Returns the total number of instructions executed. Returns: Count of executed instructions Source: windows_emulator.hpp:156

setup_process_if_necessary()

void setup_process_if_necessary()

Initializes the process environment if not already set up. Source: windows_emulator.hpp:161

start()

void start(size_t count = 0)

Starts or resumes emulation.

size_t

default:"0"

Number of instructions to execute. 0 means run indefinitely until stopped.

Source: windows_emulator.hpp:163

stop()

void stop()

Stops the emulation. Source: windows_emulator.hpp:164

serialize() / deserialize()

void serialize(utils::buffer_serializer& buffer) const
void deserialize(utils::buffer_deserializer& buffer)

Serializes or deserializes the emulator state.

utils::buffer_serializer&

required

Buffer to serialize to or deserialize from

Source: windows_emulator.hpp:166

save_snapshot() / restore_snapshot()

void save_snapshot()
void restore_snapshot()

Saves or restores a snapshot of the emulator state for quick rollback. Source: windows_emulator.hpp:169

Port Mapping Methods

get_host_port()

uint16_t get_host_port(const uint16_t emulator_port) const

Returns the host port mapped to an emulator port.

uint16_t

required

The port number in the emulator

Returns: The mapped host port, or the emulator port if no mapping exists Source: windows_emulator.hpp:172

get_emulator_port()

uint16_t get_emulator_port(const uint16_t host_port) const

Returns the emulator port mapped to a host port.

uint16_t

required

The port number on the host

Returns: The mapped emulator port, or the host port if no mapping exists Source: windows_emulator.hpp:183

map_port()

void map_port(const uint16_t emulator_port, const uint16_t host_port)

Creates a port mapping between emulator and host.

uint16_t

required

The port number in the emulator

uint16_t

required

The port number on the host

Source: windows_emulator.hpp:196

Thread Management

yield_thread()

void yield_thread(bool alertable = false)

Yields execution of the current thread.

bool

default:"false"

Whether the thread should be alertable during yield

Source: windows_emulator.hpp:211

perform_thread_switch()

bool perform_thread_switch()

Performs a thread context switch if one is pending. Returns: true if a thread switch occurred, false otherwise Source: windows_emulator.hpp:212

activate_thread()

bool activate_thread(uint32_t id)

Activates a thread by its ID.

uint32_t

required

The thread ID to activate

Returns: true if activation succeeded, false otherwise Source: windows_emulator.hpp:213

Supporting Types

emulator_settings

struct emulator_settings {
    bool disable_logging{false};
    bool use_relative_time{false};
    std::filesystem::path emulation_root{};
    std::filesystem::path registry_directory{"./registry"};
    std::unordered_map<uint16_t, uint16_t> port_mappings{};
    std::unordered_map<windows_path, std::filesystem::path> path_mappings{};
};

Configuration settings for the emulator.

bool

default:"false"

Disable logging output

bool

default:"false"

Use relative time instead of system time

std::filesystem::path

default:""

Root directory for emulation environment

std::filesystem::path

default:"./registry"

Directory containing registry hives

std::unordered_map<uint16_t, uint16_t>

default:"{}"

Port number mappings between emulator and host

std::unordered_map<windows_path, std::filesystem::path>

default:"{}"

Path mappings between Windows and host paths

application_settings

struct application_settings {
    windows_path application{};
    windows_path working_directory{};
    std::vector<std::u16string> arguments{};
};

Settings for the application to run in the emulator.

windows_path

required

Path to the executable to run

windows_path

Working directory for the application

std::vector<std::u16string>

Command-line arguments for the application

emulator_interfaces

struct emulator_interfaces {
    std::unique_ptr<utils::clock> clock{};
    std::unique_ptr<network::socket_factory> socket_factory{};
};

Optional custom interface implementations.

std::unique_ptr<utils::clock>

Custom clock implementation (defaults to system clock)

std::unique_ptr<network::socket_factory>

Custom socket factory implementation

Usage Example

#include <windows-emulator/windows_emulator.hpp>

// Create emulator with application settings
application_settings app_settings{
    .application = L"C:\\Windows\\System32\\notepad.exe",
    .working_directory = L"C:\\Users\\User",
    .arguments = {L"notepad.exe", L"test.txt"}
};

emulator_settings settings{
    .disable_logging = false,
    .emulation_root = "./emulation",
    .registry_directory = "./registry"
};

emulator_callbacks callbacks;
callbacks.on_syscall = [](uint32_t id, std::string_view name) {
    printf("Syscall: %s (0x%x)\n", name.data(), id);
    return instruction_hook_continuation::run_instruction;
};

auto emu = std::make_unique<x86_64_emulator>();
windows_emulator win_emu(std::move(emu), app_settings, settings, callbacks);

// Start emulation
win_emu.start();

Notes

The windows_emulator class is non-copyable and non-movable
The destructor automatically cleans up all resources
Thread switching is managed automatically during emulation
Snapshots allow for quick state rollback without full serialization overhead

Core API

Components

windows_emulator

Overview

Constructor

Alternative Constructor with Application

Public Members

Methods

emu()

clock()

socket_factory()

current_thread()

get_executed_instructions()

setup_process_if_necessary()

start()

stop()

serialize() / deserialize()

save_snapshot() / restore_snapshot()

Port Mapping Methods

get_host_port()

get_emulator_port()

map_port()

Thread Management

yield_thread()

perform_thread_switch()

activate_thread()

Supporting Types

emulator_settings

application_settings

emulator_interfaces

Usage Example

Notes

​Overview

​Constructor

​Alternative Constructor with Application

​Public Members

​Methods

​emu()

​clock()

​socket_factory()

​current_thread()

​get_executed_instructions()

​setup_process_if_necessary()

​start()

​stop()

​serialize() / deserialize()

​save_snapshot() / restore_snapshot()

​Port Mapping Methods

​get_host_port()

​get_emulator_port()

​map_port()

​Thread Management

​yield_thread()

​perform_thread_switch()

​activate_thread()

​Supporting Types

​emulator_settings

​application_settings

​emulator_interfaces

​Usage Example

​Notes

Overview

Constructor

Alternative Constructor with Application

Public Members

Methods

emu()

clock()

socket_factory()

current_thread()

get_executed_instructions()

setup_process_if_necessary()

start()

stop()

serialize() / deserialize()

save_snapshot() / restore_snapshot()

Port Mapping Methods

get_host_port()

get_emulator_port()

map_port()

Thread Management

yield_thread()

perform_thread_switch()

activate_thread()

Supporting Types

emulator_settings

application_settings

emulator_interfaces

Usage Example

Notes