深入详解在 Python 中用 ctypes 调用 Windows API 清空回收站

全面详解在 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 里。

python 复制代码

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）：

c 复制代码

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

对应到 Python 就是：

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_ 列表，每个元素是 (字段名, 字段类型)。

python 复制代码

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 都这样设计。

python 复制代码

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

三、查询回收站信息

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

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

python 复制代码

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 传参即可。

四、调用函数清空回收站

python 复制代码

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:

python 复制代码

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 把系统底层能力融入到自己的程序中，其实也没有想象中的那么难。

附录一： "SHEmptyRecycleBinW" 函数 (shellapi.h) - Win32 Apps 参考

功能：清空指定驱动器的回收站。

语法

cpp 复制代码

SHSTDAPI SHEmptyRecycleBinW(
  [in, optional] HWND    hwnd,
  [in, optional] LPCWSTR pszRootPath,
                 DWORD   dwFlags
);

参数

[in, optional] hwnd

类型：HWND

操作期间可能弹出的任何对话框的父窗口句柄。该参数可以为 NULL。

[in, optional] pszRootPath

类型：LPCTSTR

指向以空字符结尾的字符串的指针，长度不超过 MAX_PATH，包含回收站所在根驱动器的路径。该参数可以包含一个格式为驱动器、文件夹和子文件夹名称的字符串地址，例如 c:\windows\system。也可以是空字符串或 NULL 。如果此值为空字符串或 NULL，将清空所有驱动器上的回收站。

dwFlags

类型：DWORD

以下值中的一个或多个。

SHERB_NOCONFIRMATION

不显示确认删除对象的对话框。

SHERB_NOPROGRESSUI

不显示进度对话框。

SHERB_NOSOUND

操作完成后不播放清空回收站音效。

返回值

类型：HRESULT

如果函数成功，则返回 S_OK 。否则返回 HRESULT 错误代码。

备注

注意

shellapi.h 头文件将 SHEmptyRecycleBin 定义为一个别名，该别名会根据 UNICODE 预处理常量的定义自动选择此函数的 ANSI 或 Unicode 版本。将编码中立的别名与非编码中立的代码混用，可能导致不匹配，从而引发编译错误或运行时错误。更多信息，请参阅函数原型约定。

要求

要求	值
最低受支持的客户端	Windows 2000 Professional、Windows XP [仅限桌面应用]
最低受支持的服务器	Windows 2000 Server [仅限桌面应用]
目标平台	Windows
标头	shellapi.h
库	Shell32.lib
DLL	Shell32.dll（4.71 或更高版本）
API 集	ext-ms-win-shell-shell32-l1-2-2（在 Windows 10 版本 10.0.14393 中引入）

附录二： "SHQueryRecycleBinW" 函数 (shellapi.h) - Win32 Apps 参考

功能：检索指定驱动器上回收站的总大小及其中的项目数量。

语法

cpp 复制代码

SHSTDAPI SHQueryRecycleBinW(
  [in, optional] LPCWSTR         pszRootPath,
  [in, out]      LPSHQUERYRBINFO pSHQueryRBInfo
);

参数

[in, optional] pszRootPath

类型：LPCTSTR

指向以空字符结尾的字符串的指针，长度不超过 MAX_PATH，包含回收站所在根驱动器的路径。该参数可以包含格式为驱动器、文件夹和子文件夹名称的字符串地址（例如 C:\Windows\System...）。

[in, out] pSHQueryRBInfo

类型：LPSHQUERYRBINFO

指向接收回收站信息的 SHQUERYRBINFO 结构的指针。在调用此 API 之前，该结构的 cbSize 成员必须设置为结构的大小。

返回值

类型：HRESULT

如果函数成功，则返回 S_OK 。否则返回 HRESULT 错误代码。

备注

在 Windows 2000 中，如果 pszRootPath 参数传入 NULL ，函数将失败并返回 E_INVALIDARG 错误代码。在早期版本的操作系统中，可以传入空字符串或 NULL 。如果 pszRootPath 包含空字符串或 NULL，则检索所有驱动器上所有回收站的信息。

注意

shellapi.h 头文件将 SHQueryRecycleBin 定义为一个别名，该别名会根据 UNICODE 预处理常量的定义自动选择此函数的 ANSI 或 Unicode 版本。将编码中立的别名与非编码中立的代码混用，可能导致不匹配，从而引发编译错误或运行时错误。更多信息，请参阅函数原型约定。

要求

要求	值
最低受支持的客户端	Windows 2000 Professional、Windows XP [仅限桌面应用]
最低受支持的服务器	Windows 2000 Server [仅限桌面应用]
目标平台	Windows
标头	shellapi.h
库	Shell32.lib
DLL	Shell32.dll（4.71 或更高版本）

附录三： "SHQUERYRBINFO" 数据类型 (shellapi.h) - Win32 Apps 参考

描述：包含由 SHQueryRecycleBin 函数查询到的大小和项目计数等信息。

语法

cpp 复制代码

typedef struct _SHQUERYRBINFO {
  DWORD     cbSize;
#if ...
  __int64   i64Size;
#if ...
  __int64   i64NumItems;
#else
  DWORDLONG i64Size;
#endif
#else
  DWORDLONG i64NumItems;
#endif
} SHQUERYRBINFO, *LPSHQUERYRBINFO;

成员

cbSize

类型：DWORD

结构的大小（以字节为单位）。在调用函数之前，必须填充此成员。

i64Size

类型：__int64

指定回收站中所有对象的总大小（以字节为单位）。

i64NumItems

类型：__int64

指定回收站中的项目总数。

要求

要求	值
最低受支持的客户端	Windows XP [仅限桌面应用]
最低受支持的服务器	Windows 2000 Server [仅限桌面应用]
标头	shellapi.h

参考资料

ctypes | Python 文档

作者

张赐荣，视障者，Windows 资深开发、信息无障碍解决方案研发专家。

多年来，深耕于Web/PC/移动端可访问性优化工作，对跨平台无障碍解决方案拥有深刻的理论研究和丰富的实战经验。

精通障碍用户软件交互体验设计，致力于用专业的能力改善、提升产品可可及性。