python

关注公众号 jb51net

关闭
首页 > 脚本专栏 > python > Python ctypes调用Windows API

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

作者：张赐荣

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

引言

很多朋友刚接触 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)

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

在这里

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() 函数，返回所有驱动器回收站里的文件总数。

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)

聪明的你一定想到了：如果用户在确认对话框点了“否”，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 把系统底层能力融入到自己的程序中，其实也没有想象中的那么难。

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

您可能感兴趣的文章:
阅读全文