The process_context class maintains the complete state of an emulated Windows process, including threads, handles, memory structures, and Windows-specific objects.
Overview
This class serves as the central hub for process-level resources in the Windows emulator. It manages:
- Process Environment Block (PEB) and process parameters
- Thread lifecycle and synchronization
- Handle tables for kernel objects (files, events, sections, etc.)
- User-mode objects (windows, desktops)
- Atoms and window classes
- WOW64 support for 32-bit applications
Constructor
process_context(
x86_64_emulator& emu,
memory_manager& memory,
utils::clock& clock,
callbacks& cb
)
Reference to the CPU emulator instance
Reference to the memory manager for allocations
System clock for time-related operations
Callback functions for thread lifecycle events
Methods
setup
Initializes the process context with all necessary Windows structures.
void setup(
x86_64_emulator& emu,
memory_manager& memory,
registry_manager& registry,
file_system& file_system,
windows_version_manager& version,
const application_settings& app_settings,
const mapped_module& executable,
const mapped_module& ntdll,
const apiset::container& apiset_container,
const mapped_module* ntdll32 = nullptr
)
Memory manager for virtual address space
Windows registry emulation
Virtual file system for path translation
Windows version information provider
app_settings
const application_settings&
Application-specific configuration
The main executable module
API set schema container for module redirection
ntdll32
const mapped_module*
default:"nullptr"
Optional 32-bit ntdll for WOW64 processes
create_thread
Creates a new emulated thread in the process.
handle create_thread(
memory_manager& memory,
uint64_t start_address,
uint64_t argument,
uint64_t stack_size,
uint32_t create_flags,
bool initial_thread = false
)
Memory manager for thread stack allocation
Entry point address for the thread
Parameter passed to the thread function
Size of the thread stack in bytes
Thread creation flags (e.g., CREATE_SUSPENDED)
Whether this is the process’s initial thread
Atom Management
Atoms are globally unique string identifiers used by Windows for window classes and other purposes.
find_atom
std::optional<uint16_t> find_atom(std::u16string_view name)
The atom name to search for
std::nullopt otherwise.
add_or_find_atom
uint16_t add_or_find_atom(std::u16string name)
The atom name to add or find
delete_atom
bool delete_atom(const std::u16string& name)
bool delete_atom(uint16_t atom_id)
The atom name to delete (first overload)
The atom ID to delete (second overload)
true if the atom was deleted, false otherwise.
get_atom_name
const std::u16string* get_atom_name(uint16_t atom_id) const
nullptr if not found.
KnownDLLs Management
KnownDLLs are preloaded system DLLs cached as section objects.
build_knowndlls_section_table
template <typename T>
void build_knowndlls_section_table(
registry_manager& registry,
const file_system& file_system,
const apiset_map& apiset,
const windows_path& system_root,
bool is_32bit
)
Registry manager to read KnownDLLs list
File system for resolving DLL paths
API set schema for module redirection
Windows system directory path
Whether to build 32-bit or 64-bit KnownDLLs table
get_knowndll_section_by_name
std::optional<section> get_knowndll_section_by_name(
const std::u16string& name,
bool is_32bit
) const
DLL name (e.g., “kernel32.dll”)
Whether to search in 32-bit or 64-bit table
add_knowndll_section
void add_knowndll_section(
const std::u16string& name,
const section& section,
bool is_32bit
)
has_knowndll_section
bool has_knowndll_section(
const std::u16string& name,
bool is_32bit
) const
get_handle_store
generic_handle_store* get_handle_store(handle handle)
nullptr if not found.
get_live_thread_count
size_t get_live_thread_count() const
Serialization
void serialize(utils::buffer_serializer& buffer) const
void deserialize(utils::buffer_deserializer& buffer)
Public Members
WOW64 Support
Flag indicating if this is a 32-bit process running under WOW64
Process State
Process exit status code (set when process terminates)
Memory Structures
64-bit Process Environment Block
process_params64
emulator_object<RTL_USER_PROCESS_PARAMETERS64>
64-bit process parameters (command line, environment, etc.)
peb32
std::optional<emulator_object<PEB32>>
32-bit PEB for WOW64 processes
process_params32
std::optional<emulator_object<RTL_USER_PROCESS_PARAMETERS32>>
32-bit process parameters for WOW64
Critical Addresses
Base address of ntdll.dll
Address of LdrInitializeThunk (thread entry point)
Address of RtlUserThreadStart
Address of KiUserApcDispatcher
ki_user_exception_dispatcher
Address of KiUserExceptionDispatcher
Handle Stores
events
handle_store<handle_types::event, event>
Event object handle store
files
handle_store<handle_types::file, file>
File handle store
sections
handle_store<handle_types::section, section>
Section object handle store
devices
handle_store<handle_types::device, io_device_container>
Device handle store
semaphores
handle_store<handle_types::semaphore, semaphore>
Semaphore handle store
threads
handle_store<handle_types::thread, emulator_thread>
Thread handle store
windows
user_handle_store<handle_types::window, window>
Window handle store (user-mode handles)
desktops
handle_store<handle_types::desktop, desktop>
Desktop handle store
Thread Management
Pointer to the currently executing thread
Total number of threads created
Usage Example
// Create process context
process_context::callbacks callbacks;
callbacks.on_thread_create = [](handle h, emulator_thread& thr) {
printf("Thread created: %p\n", h.value);
};
process_context context(emu, memory, clock, callbacks);
// Setup the process
context.setup(emu, memory, registry, fs, version, settings,
executable_module, ntdll_module, apiset);
// Create a thread
auto thread_handle = context.create_thread(
memory,
0x140001000, // entry point
0, // argument
0x40000, // 256KB stack
0, // no special flags
true // initial thread
);
// Add an atom
auto atom_id = context.add_or_find_atom(u"MyWindowClass");
// Look up a handle store
if (auto* store = context.get_handle_store(some_handle)) {
// Work with the handle store
}
See Also