Python使用ctypes调用Windows API清空回收站
本文详解如何利用Python内置的ctypes库调用Windows系统API实现清空回收站功能。通过对比清空前后的文件数量，有效区分“真正清空”与“用户取消”，解决仅依赖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的资料请关注本站其它相关文章！
免责声明：本文内容仅供参考，不代表本站观点。转载或引用请注明出处。
