{"componentChunkName":"component---src-templates-post-template-js","path":"/rust-winapi-usermode-apc-en","result":{"data":{"markdownRemark":{"id":"d51e07c0-21ba-558a-af53-c18253eb1e17","html":"
\n

This page has been machine-translated from the original page.

\n
\n

Continuing from the previous articles, I wanted to keep trying out various programs that call the Windows API from Rust.

\n

This time, I wrote a program in Rust that creates a thread and triggers an APC function registered to that thread.

\n\n

Table of contents

\n\n

About Windows Asynchronous Procedure Calls (APC)

\n

Windows Asynchronous Procedure Calls (APC) are one of the mechanisms that can execute work asynchronously on a specific thread.

\n

APCs are a mechanism that can run user-mode programs and system code in the context of a specific user thread (that is, within the execution address space of a particular process).

\n

Reference: Asynchronous Procedure Calls - Win32 apps | Microsoft Learn

\n

APCs are represented by kernel objects called APC objects, which are registered in one of the two APC queues that exist for each thread and wait there to be executed.

\n

Of the two APC queues that each thread maintains, one is a queue for kernel APCs and the other is a queue for user APCs.

\n

The APC objects registered in these queues wait to be executed via a software interrupt.

\n

Types of APCs

\n

Broadly speaking, APCs come in two modes: user-mode APCs and kernel-mode APCs.

\n

A user-mode APC is an APC generated by an application, while a kernel-mode APC is an APC generated by the system.

\n

In addition, each mode has both Normal and Special APCs.

\n

The differences in behavior between each mode are described in considerable detail on pp. 67-69 of Inside Windows, 7th Edition, Part 2, but that is not the point I want to focus on here, so I will omit it.

\n

When APCs run

\n

APCs are usually executed when a thread enters an Alertable state.

\n

In particular, for user-mode APCs, as described in the documentation below, the APC function runs when a call such as SleepEx moves the thread into an Alertable state.

\n

Reference: Asynchronous Procedure Calls - Win32 apps | Microsoft Learn

\n

This time, I will aim to implement a program in Rust that uses this user-mode APC mechanism.

\n

How to register a user-mode APC

\n

Registering a user-mode APC is very simple: just call the QueueUserAPC API with a PAPCFUNC, which is a pointer to the APC function you want to execute, and a handle to the thread where you want to register the APC.

\n

Reference: QueueUserAPC function (processthreadsapi.h) - Win32 apps | Microsoft Learn

\n

This makes the APC function execute when the target thread changes to an Alertable state.

\n

Code for registering the user-mode APC I created

\n

To verify the behavior of a user-mode APC, I wrote the following code in Rust.

\n
// cargo run --bin UserModeApc\n\nuse std::{thread, time};\nuse windows::Win32::System::Threading::{GetCurrentThread, GetCurrentThreadId, QueueUserAPC, SleepEx};\n\nextern \"system\" fn apc_func(_: usize)  {\n    println!(\"User mode APC triggered !!\");\n    return;\n}\n\nfn non_alertable_func() {\n\n    let sleep_time: time::Duration = time::Duration::from_millis(5000);\n    let now = time::Instant::now();\n    \n    println!(\"Non alertable sleep started.\");\n    thread::sleep(sleep_time);\n    assert!(now.elapsed() >= sleep_time);\n    println!(\"Non alertable sleep started.\");\n\n    return;\n}\n\nfn alertable_func() {\n\n    let now = time::Instant::now();\n    \n    // SleepEx による Alertable な Sleep\n    println!(\"Alertable sleep started.\");\n    unsafe {\n        SleepEx(9999999, true);\n    }\n    // APC がコールさ SleepEx が中断されるので実際には長時間の Sleep は発生しない\n    println!(\"Alertable sleep fineshed in {} nanos.\", now.elapsed().as_nanos());\n\n    return;\n}\n\n\nfn main() {\n\n    let non_alertable_thread_handle = thread::spawn(|| {\n\n        unsafe {\n            let h_spawned_thread = GetCurrentThread();\n            let spawned_thread_id = GetCurrentThreadId();\n            println!(\"Thread id {} started.\", spawned_thread_id);\n\n            // Add User APC into queue\n            if QueueUserAPC(Some(apc_func), h_spawned_thread, 0) != 0 {\n                println!(\"Add User mode APC into non alertable thread id {}.\", spawned_thread_id);\n            }\n        }\n\n        // Non alertable なスレッドを作成\n        non_alertable_func();\n    });\n\n    non_alertable_thread_handle.join().unwrap();\n\n\n    let alertable_thread_handle = thread::spawn(|| {\n\n        unsafe {\n            let h_spawned_thread = GetCurrentThread();\n            let spawned_thread_id = GetCurrentThreadId();\n            println!(\"Thread id {} started.\", spawned_thread_id);\n\n            // Add User APC into queue\n            if QueueUserAPC(Some(apc_func), h_spawned_thread, 0) != 0 {\n                println!(\"Add User mode APC into alertable thread id {}.\", spawned_thread_id);\n            }\n        }\n\n        // Alertable なスレッドを作成\n        alertable_func();\n    });\n\n    alertable_thread_handle.join().unwrap();\n    \n    return;\n\n}
\n

Loading modules

\n

This time I wanted to use the four API functions GetCurrentThread, GetCurrentThreadId, QueueUserAPC, and SleepEx, so I added windows::Win32::System::Threading, which includes all of them, as a dependency.

\n
windows = { version = \"0.60.0\", features = [\n    \"Win32_System_Threading\"\n] }
\n

Reference: windows::Win32::System::Threading - Rust

\n

Also, because I use thread and time from Rust’s standard library, I load the following modules.

\n
use std::{thread, time};\nuse windows::Win32::System::Threading::{GetCurrentThread, GetCurrentThreadId, QueueUserAPC, SleepEx};
\n

Implementing alertable functions

\n

Next, I define two functions: non_alertable_func and alertable_func.

\n

Each of these functions is executed on a separate thread via thread::spawn.

\n
fn non_alertable_func() {\n\n    let sleep_time: time::Duration = time::Duration::from_millis(5000);\n    let now = time::Instant::now();\n    \n    println!(\"Non alertable sleep started.\");\n    thread::sleep(sleep_time);\n    assert!(now.elapsed() >= sleep_time);\n    println!(\"Non alertable sleep started.\");\n\n    return;\n}\n\n\nfn alertable_func() {\n\n    let now = time::Instant::now();\n    \n    // SleepEx による Alertable な Sleep\n    println!(\"Alertable sleep started.\");\n    unsafe {\n        SleepEx(9999999, true);\n    }\n    // APC がコールされて SleepEx が中断されるので実際には長時間の Sleep は発生しない\n    println!(\"Alertable sleep fineshed in {} nanos.\", now.elapsed().as_nanos());\n\n    return;\n}
\n

non_alertable_func uses the standard library’s thread::sleep(sleep_time); to sleep in a non-alertable way.

\n

By contrast, alertable_func performs its sleep with the Windows API SleepEx, which causes the thread to transition into an Alertable state.

\n

Defining the APC function

\n

The following is the definition of the APC function that I want to execute via an APC.

\n

Because it is used as an argument to the Windows API, I use extern \"system\".

\n
extern \"system\" fn apc_func(_: usize)  {\n    println!(\"User mode APC triggered !!\");\n    return;\n}
\n

I also set the argument to match the definition of the PAPCFUNC type used as an argument to QueueUserAPC.

\n

\n \n \n \n \n \n \n \n \n

\n

Reference: QueueUserAPC in windows::Win32::System::Threading - Rust

\n

Analyzing the Rust binary

\n

I had intended to analyze the binary I built at the same time as implementing the Windows API in Rust, but I completely forgot, so I will start doing that from this article onward.

\n

Finding the main function

\n

For now, when I decompiled without a PDB, the main function was output as follows (it clearly is not the actual implementation of main…).

\n

\n \n \n \n \n \n \n \n \n

\n

In reality, the function loaded into rcx by lea seems to be the actual main function, and the function called with that as an argument (0x2a90) appears to be the lang_start function.

\n

Reference: Who calls lang_start? - community - The Rust Programming Language Forum

\n

When I actually checked that function, there were places that looked like they used conditional branches and the unwrap function, so it seems reasonable to treat it as the main function.

\n

\n \n \n \n \n \n \n \n \n

\n

By the way, Binary Ninja has a pseudo-Rust decompiler mode, so I used it this time, but aside from replacing every variable declaration with let, I did not really feel much difference from the pseudo-C output.

\n

Creating the thread

\n

If you check the function executed at the very beginning of the decompiled result, you notice that the text failed to spawn thread is embedded in it.

\n

\n \n \n \n \n \n \n \n \n

\n

This text is likely part of the implementation of the spawn function used to create the thread.

\n

\n \n \n \n \n \n \n \n \n

\n

Reference: mod.rs - source

\n

Honestly, it seemed impossible to determine from any other information that this function was thread::spawn. (Even looking at the disassembly results and the decompiled output, I could not make sense of it.)

\n

If I assume that up front, then if this function is thread::spawn, I can conclude that var_90 stores a JoinHandle.

\n

\n \n \n \n \n \n \n \n \n

\n

That means this function, which takes a JoinHandle as an argument, is probably non_alertable_thread_handle.join().unwrap() here.

\n

More precisely, because the string embedded when this function’s return value is not 0 is the error text used when panic! is called inside unwrap—called Result::unwrap() on an Err—it seems likely that the function above corresponds to join() up to that point, and that the contents of the following branch are unwrap().

\n

\n \n \n \n \n \n \n \n \n

\n

However, understanding the details around this area was still difficult even when checking a binary with symbols, so I gave up for the time being.

\n

It probably means I need to read the implementation of Rust’s modules themselves.

\n

Summary

\n

This time, I wrote code in Rust that creates a thread and executes an arbitrary function with QueueUserAPC.

\n

I also tried analyzing the Rust binary with a decompiler, but even with symbols there were many parts that I could not make sense of, so my reaction was basically, “How are you supposed to analyze this?”

\n

I suspect that if I were more familiar with the implementation of Rust’s modules themselves, there would be a bit more room for informed guessing.

\n

Going forward, I would like to build up more know-how for analyzing Rust.

","fields":{"slug":"/rust-winapi-usermode-apc-en","tagSlugs":["/tag/rust/","/tag/windows/","/tag/rust-win-api/","/tag/english/"]},"frontmatter":{"date":"2025-04-09","description":"Using User-Mode APCs with the Windows API in Rust","tags":["Rust","Windows","Rust-WinAPI","English"],"title":"Using User-Mode APCs with the Windows API in Rust","socialImage":{"publicURL":"/static/ad0e43ca3b66023e796da62e26b76d4d/rust-winapi-usermode-apc.png"}}}},"pageContext":{"slug":"/rust-winapi-usermode-apc-en"}},"staticQueryHashes":["251939775","401334301","825871152"]}