Python使用ctypes调用Windows API清空回收站

更新时间：2026年04月28日 09:33:15 作者：张赐荣

很多朋友刚接触 Windows 编程时,总觉得调用系统底层 API 是一件很高深、非常复杂的事情,感到很害怕,本文就以实现 Windows 上的清空回收站功能为例,从零开始详解 Python 如何通过 ctypes 库跟 Windows API 进行交互调用,需要的朋友可以参考下

引言

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

一、整体思路

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

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

这种执行后查询验证结果的思路，在实际开发中非常实用，我们不能盲目依赖 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（成功）！所以仅靠返回值无法区分“用户取消了”和“真的清空了”。

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

清空前记录文件数 count_before。
调用清空 API。
清空后再次查询文件数 count_after。
综合判断：
- 如果 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 把系统底层能力融入到自己的程序中，其实也没有想象中的那么难。

以上就是Python使用ctypes调用Windows API清空回收站的详细内容，更多关于Python ctypes调用Windows API的资料请关注脚本之家其它相关文章！

您可能感兴趣的文章:

15行Python代码实现免费发送手机短信推送消息功能
这篇文章主要介绍了通过15行Python代码实现免费发送手机短信推送消息功能,通过实例代码截图的形式给大家介绍的非常详细，具有一定的参考借鉴价值，需要的朋友可以参考下
2020-02-02
Python中的装饰器链(decorator chain)详解
在Python中,装饰器是一种高级功能,它允许你在不修改函数或类代码的情况下,为它们添加额外的功能,装饰器通常用于日志记录、性能测量、权限检查等场景,当多个装饰器应用于同一个函数或类时,形成装饰器链,这篇文章主要介绍了Python中的装饰器链详解,需要的朋友可以参考下
2024-06-06
python结合opencv实现人脸检测与跟踪
在Python下用起来OpenCV很爽，代码很简洁，很清晰易懂。使用的是Haar特征的分类器，训练之后得到的数据存在一个xml中。下面我们就来详细谈谈。
2015-06-06
Python中的迭代器你了解吗
迭代器是一种特殊的对象，它实现了迭代协议，允许按照一定的顺序逐个访问元素，本文就来带大家深入了解一下Python中迭代器的使用，需要的可以参考下
2023-05-05
python 使用pandas读取csv文件的方法
这篇文章主要介绍了python 使用pandas读取csv文件的方法,本文结合示例代码给大家介绍的非常详细，对大家的学习或工作具有一定的参考借鉴价值，需要的朋友可以参考下
2022-12-12
Python脚本轻松实现检测麦克风功能
在进行音频处理或开发需要使用麦克风的应用程序时,确保麦克风功能正常是非常重要的,本文将介绍一个简单的Python脚本,能够帮助我们检测本地麦克风的功能,需要的可以参考下
2025-08-08
Python类的专用方法实例分析
这篇文章主要介绍了Python类的专用方法,实例分析了__init__、__del__、__repr__等专用方法的应用技巧,需要的朋友可以参考下
2015-01-01
Python一行代码识别发票并保存Excel示例详解
这篇文章主要为大家介绍了Python一行代码识别发票并保存Excel示例详解，有需要的朋友可以借鉴参考下，希望能够有所帮助，祝大家多多进步，早日升职加薪
2023-03-03
解决Python调用df.to_csv()出现中文乱码的问题
在Python使用df.to_csv()时,若出现中文乱码,可通过加入参数encoding="utf_8_sig"解决,"utf-8"编码不包含BOM,直接处理文件时会将BOM误读为内容；而"utf_8_sig"会识别并处理BOM,避免乱码,此方法为实践经验,供参考
2024-09-09
Python求均值,方差,标准差的实例
今天小编就为大家分享一篇Python求均值,方差,标准差的实例，具有很好的参考价值，希望对大家有所帮助。一起跟随小编过来看看吧
2019-06-06