Python使用ctypes调用WindowsAPI清空回收站

引言

很多朋友刚接触 Windows 编程时，总觉得调用系统底层 API 是一件很高深、非常复杂的事情，感到很害怕。其实 Python 自带的 ctypes 库就能让咱们轻松调用 C 语言导出的动态链接库函数，本文就以实现 Windows 上的 “清空回收站”功能为例，从零开始详解 Python 如何通过 ctypes 库跟 Windows API 进行交互调用。

一、整体思路

清空回收站，不能直接调用 SHEmptyRecycleBin 就完事了，我们要编写一个更智能更稳健的程序，能准确判断是否真正成功清空：

1. 清空前先查询回收站里有多少文件，就知道有没有必要清空了。
2. 调用 Windows 提供的清空回收站 API，执行清理。
3. 清空后再次查询文件数量，对比前后变化，判断用户是真的清空了，还是中途取消了（比如在系统弹出的确认对话框里点了“否”）。

这种执行后查询验证结果的思路，在实际开发中非常实用，我们不能盲目依赖 API 的返回值，比如 SHEmptyRecycleBin 的返回值，仅表示函数是不是成功调用了，不表示用户点击了确定清空，或执行过程中是否取消了操作，所以说，它的结果并不表示业务是否成功，也就是是否真正清空了回收站。

二、ctypes 是什么？怎么用？

ctypes 是 Python 内置的库，这个库能把 Python 的数据类型转换成 C 语言的数据类型，然后调用 DLL 或共享库中的函数。简单说就是让 Python 可以直接调用 Windows 系统底层函数。

2.1 加载 DLL

Windows API 大多存放在 kernel32.dll、user32.dll、shell32.dll 等系统核心动态链接库文件中。这里咱们要用的两个函数都在 shell32.dll 里。

import ctypes
shell32 = ctypes.WinDLL('shell32', use_last_error=True)

• WinDLL 表示加载一个 Windows DLL，默认使用 stdcall 调用约定（Windows API 的标准）。
• use_last_error=True 让 ctypes 在出错时保存 Windows 错误码，方便调试。

2.2 定义函数原型（参数类型和返回值类型）

这是新手最容易踩坑的地方。Windows API 函数是用 C 写的，Python 并不知道它接收什么参数，所以我们必须显式声明参数类型（argtypes）和返回值类型（restype）。

例如咱们用到的清空函数声明（来自 Win32 SDK）：

HRESULT SHEmptyRecycleBinW(HWND hwnd, LPCWSTR pszRootPath, DWORD dwFlags);

对应到 Python 就是：

shell32.SHEmptyRecycleBinW.argtypes = [wintypes.HWND, wintypes.LPCWSTR, wintypes.DWORD]
shell32.SHEmptyRecycleBinW.restype = ctypes.HRESULT

在这里

• HWND 是窗口句柄（可理解为窗口的身份证），传 None 表示没有父级窗口。
• LPCWSTR 是宽字符串指针，对应 Python 的 str （ctypes 会自动转成 wchar_t*）。
• DWORD 是 32 位无符号整数。
• HRESULT 是一个 32 位整数，一般来讲 0（即 S_OK）表示成功。

2.3 定义结构体

很多 Windows API 都要传结构体，比如我们这里用到的查询回收站信息函数要用到 SHQUERYRBINFO 结构体。在 ctypes 中定义C语言结构体还是相对比较容易的：只要继承 ctypes.Structure，然后写一个 _fields_ 列表，每个元素是 (字段名, 字段类型)。

class SHQUERYRBINFO(ctypes.Structure):
    _fields_ = [
        ("cbSize", wintypes.DWORD),       # 结构体自身大小
        ("i64Size", ctypes.c_longlong),   # 总大小（字节）
        ("i64NumItems", ctypes.c_longlong) # 项目总数
    ]

C 语言的 __int64 对应 Python 的 ctypes.c_longlong（8 字节有符号整数）。

另外，考虑到向后兼容，这个结构体的第一个成员 cbSize 必须在调用前赋值为结构体占用的字节数，很多 Windows API 都这样设计。

rb_info = SHQUERYRBINFO()
rb_info.cbSize = ctypes.sizeof(SHQUERYRBINFO)

三、查询回收站信息

封装一个 get_recycle_bin_count() 函数，返回所有驱动器回收站里的文件总数。

• 调用 SHQueryRecycleBinW(None, pointer_to_struct)，第一个参数传 None 表示“查询所有驱动器的总回收站”。也可以传 "C:\\" 这样的路径，查询指定盘。
• 第二个参数需要传结构体的指针，用 ctypes.byref() 获得。
• 函数执行后，结构体的 i64NumItems 字段就被填上了项目总数。

hr = shell32.SHQueryRecycleBinW(None, ctypes.byref(rb_info))
if hr == 0:   # 成功
    return rb_info.i64NumItems
else:
    return -1

为什么函数名最后总要带上 W 字母？那是因为 Windows API 有两套字符编码：A（ANSI）和 W（Unicode）。现代 Windows 内部完全使用 Unicode，所以咱们直接调用 W 版本，用 Python 的 str 传参即可。

四、调用函数清空回收站

hr = shell32.SHEmptyRecycleBinW(None, None, 0)

• 第一个参数 hwnd：None 表示没有父窗口。
• 第二个参数 pszRootPath：None 表示清空所有驱动器的回收站。
• 第三个参数 dwFlags：0 表示使用系统默认行为，也就是弹出确认对话框并显示进度。

聪明的你一定想到了：如果用户在确认对话框点了“否”，API 会返回什么？经过实测，SHEmptyRecycleBinW 在这种情况下依然返回 S_OK（成功）！所以仅靠返回值无法区分“用户取消了”和“真的清空了”。

因此我们的代码要做更严谨的判断：

1. 清空前记录文件数 count_before。
2. 调用清空 API。
3. 清空后再次查询文件数 count_after。
4. 综合判断：
   • 如果 hr == 0 且 count_after < count_before（文件数减少了），说明真的删除了，于是提示“清空成功”。
   • 如果 hr == 0 但 count_after == count_before，说明用户取消了确认对话框，所以提示“操作已取消”。
   • 如果 hr != 0，说明 API 调用失败（例如权限不足），应显示错误代码。

另，如果清空前文件数就是 0，直接弹窗告知“无需操作”。

五、完整代码

可以直接把下面的代码复制保存为 empty_recycle_bin.pyw 双击运行，需要安装 Python3。

empty_recycle_bin.pyw:

import ctypes
from ctypes import wintypes

# <-定义结构体 ->
# SHQUERYRBINFO 结构体用于接收回收站信息
class SHQUERYRBINFO(ctypes.Structure):
    _fields_ = [
        ("cbSize", wintypes.DWORD),      # 结构体大小
        ("i64Size", ctypes.c_longlong),  # 回收站内文件总大小 (字节)
        ("i64NumItems", ctypes.c_longlong) # 回收站内项目总数
    ]

# <- 定义常量 ->
MB_OK = 0x00000000
MB_ICONINFORMATION = 0x00000040
MB_ICONWARNING = 0x00000030
MB_ICONERROR = 0x00000010

def get_recycle_bin_count():
    """获取所有驱动器回收站的文件总数"""
    shell32 = ctypes.WinDLL('shell32', use_last_error=True)
    # 定义 SHQueryRecycleBinW
    # HRESULT SHQueryRecycleBinW(LPCWSTR pszRootPath, LPSHQUERYRBINFO pSHQueryRBINFO);
    shell32.SHQueryRecycleBinW.argtypes = [wintypes.LPCWSTR, ctypes.POINTER(SHQUERYRBINFO)]
    shell32.SHQueryRecycleBinW.restype = ctypes.HRESULT

    rb_info = SHQUERYRBINFO()
    rb_info.cbSize = ctypes.sizeof(SHQUERYRBINFO)

    # pszRootPath 为 None 表示查询所有驱动器
    hr = shell32.SHQueryRecycleBinW(None, ctypes.byref(rb_info))
    if hr == 0:
        return rb_info.i64NumItems
    return -1

def empty_recycle_bin():
    shell32 = ctypes.WinDLL('shell32', use_last_error=True)
    user32 = ctypes.WinDLL('user32', use_last_error=True)

    # 定义 SHEmptyRecycleBinW
    shell32.SHEmptyRecycleBinW.argtypes = [wintypes.HWND, wintypes.LPCWSTR, wintypes.DWORD]
    shell32.SHEmptyRecycleBinW.restype = ctypes.HRESULT

    # 记录执行前的项目数
    count_before = get_recycle_bin_count()
    if count_before == 0:
        user32.MessageBoxW(None, "回收站已经是空的，无需操作。", "提示", MB_OK | MB_ICONINFORMATION)
        return

    # 调用 API 执行清空 (dwFlags=0, 显示系统确认对话框)
    hr = shell32.SHEmptyRecycleBinW(None, None, 0)

    # 记录执行后的项目数
    count_after = get_recycle_bin_count()

    # 综合判断
    # 逻辑：API必须成功 AND (文件数减少了 OR 文件数变为了0)
    if hr == 0:
        if count_after < count_before and count_after >= 0:
            user32.MessageBoxW(None, f"清空成功！\n文件数从 {count_before} 降至 {count_after}。", "成功", MB_OK | MB_ICONINFORMATION)
        elif count_before != -1 and count_after == count_before:
            # API 返回了成功，但数量没变，说明用户在系统对话框点了“否”
            user32.MessageBoxW(None, "操作已取消或未执行删除。", "提示", MB_OK | MB_ICONWARNING)
        else:
            user32.MessageBoxW(None, "回收站状态未发生显著变化。", "提示", MB_OK | MB_ICONWARNING)
    else:
        # 如果返回了非 0 的 HRESULT
        err_hex = hex(hr & 0xFFFFFFFF)
        user32.MessageBoxW(None, f"操作失败。错误代码: {err_hex}", "错误", MB_OK | MB_ICONERROR)

if __name__ == "__main__":
    empty_recycle_bin()

注：执行脚本的 “python.exe” 要和调用的 DLL 位数相同，比如都是64位的。

通过上面这个例子，就应该意识到了，Python + ctypes 和 comtypes 几乎可以调用所有 Windows API，借助Python 调用 C dll 把系统底层能力融入到自己的程序中，其实也没有想象中的那么难。