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 = {}
)
emu
std::unique_ptr<x86_64_emulator>
required
The underlying x86-64 CPU emulator instance
settings
const emulator_settings&
default:"{}"
Configuration settings for the emulator
callbacks
emulator_callbacks
default:"{}"
Event callbacks for monitoring emulation events
interfaces
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 = {}
)
app_settings
application_settings
required
Application configuration including path, working directory, and arguments
Public Members
The windows_emulator class exposes several public components:
Event callbacks for monitoring emulation behavior
Logging interface for emulation events
Virtual file system manager
Memory management interface
Windows version information manager
Module/DLL loading and management
Process and thread context information
Methods
emu()
x86_64_emulator& emu()
const x86_64_emulator& emu() const
clock()
utils::clock& clock()
const utils::clock& clock() const
socket_factory()
network::socket_factory& socket_factory()
const network::socket_factory& socket_factory() const
current_thread()
emulator_thread& current_thread() const
std::runtime_error if no active thread exists
Source: windows_emulator.hpp:146
get_executed_instructions()
uint64_t get_executed_instructions() const
setup_process_if_necessary()
void setup_process_if_necessary()
start()
void start(size_t count = 0)
Number of instructions to execute. 0 means run indefinitely until stopped.
stop()
Stops the emulation.
Source: windows_emulator.hpp:164
serialize() / deserialize()
void serialize(utils::buffer_serializer& buffer) const
void deserialize(utils::buffer_deserializer& buffer)
buffer
utils::buffer_serializer&
required
Buffer to serialize to or deserialize from
save_snapshot() / restore_snapshot()
void save_snapshot()
void restore_snapshot()
Port Mapping Methods
get_host_port()
uint16_t get_host_port(const uint16_t emulator_port) const
The port number in the emulator
get_emulator_port()
uint16_t get_emulator_port(const uint16_t host_port) const
The port number on the host
map_port()
void map_port(const uint16_t emulator_port, const uint16_t host_port)
The port number in the emulator
The port number on the host
Thread Management
yield_thread()
void yield_thread(bool alertable = false)
Whether the thread should be alertable during yield
bool perform_thread_switch()
true if a thread switch occurred, false otherwise
Source: windows_emulator.hpp:212
activate_thread()
bool activate_thread(uint32_t id)
The thread ID to activate
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{};
};
Use relative time instead of system time
emulation_root
std::filesystem::path
default:""
Root directory for emulation environment
registry_directory
std::filesystem::path
default:"./registry"
Directory containing registry hives
port_mappings
std::unordered_map<uint16_t, uint16_t>
default:"{}"
Port number mappings between emulator and host
path_mappings
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{};
};
Path to the executable to run
Working directory for the application
arguments
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{};
};
clock
std::unique_ptr<utils::clock>
Custom clock implementation (defaults to system clock)
socket_factory
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