Windows 中的 HRESULT

2021-06-16 02:51

Windows 协议文档中所描述的协议规范中，错误码使用 HRESULT、Win32 错误码和 NTSTATUS 来描述。本文科普一下 HRESULT。

一个简单的例子

我们先举一个大家可能常用的 HRESULT 例子，这样后面的介绍能更简单一点。

0x80070070

将它改写成二进制：

1000 0000 0000 0111 0000 0000 0111 0000

它的意思是“There is not enough space on the disk.”即“磁盘空间不足。”

规范中的 HRESULT

按照规范，HRESULT 的格式如下，其中首行的数字代表第几位（bit）：

• S: 1 位，表示严重性。为 1 表示此结果为失败，为 0 表示此结果为成功。
• R: 1 位，保留位。如果 N 位是 0，那么此位必须也是 0。如果 N 位是 1，那么此位由 NTSTATUS 定义的数字范围决定。
• C: 1 位，自定义位。为 1 表示由微软定义，为 0 表示由其他厂商定义。
• N: 1 位。为 1 表示此结果为 NTSTATUS 错误码。
• X: 1 位。保留位，应设为 0。
• Facility: 11 位。设施代码。指定错误来源。后面的列表中有已定义的错误源，微软偶尔会添加新的种类。
• Code: 16 位（2 字节）。错误码的其他部分，指定错误的具体细节。

其中，Facility 设施代码的详细列表可以参见这里：[MS-ERREF]: HRESULT - Microsoft Docs。对 Win32 开发来说，0x7 是很常见的，表示 FACILITY_WIN32。

Win32 错误码

现在再来看我们前面的例子：

1000 0000 0000 0111 0000 0000 0111 0000

• 严重性：1，表示失败
• 设施代码：0x7，表示 FACILITY_WIN32
• 错误码：0x70，表示 ERROR_DISK_FULL

所有的 Win32 错误码应该仅使用 16 位来表示，即范围从 0x0000 到 0xFFFF。关于 Win32 错误码的详细列表可以参见这里：[MS-ERREF]: Win32 Error Codes - Microsoft Docs

微软错误查询工具

如果你遇到了某个 Win32 错误码，或者 HRESULT 值，那么可以使用微软错误查询工具（The Microsoft Error Lookup Tool）查询其含义。

下载地址：Download Microsoft Error Lookup Tool from Official Microsoft Download Center

在 .NET/C# 代码中的使用

例如，我们可能需要在一些 IO 操作中处理好磁盘空间已满的情况：

try
{
    SaveFile(fileContent, filePath);
}
catch (IOException ex)
{
    if (ex.IsDiskFullException())
    {
        // 磁盘空间已满。
        break;
    }
}

由于磁盘空间已满没有对应的 .NET Exception，所以我们只能通过提取 IOException 中的 HResult 属性来判断操作的 HRESULT 值。

我们定义了一个扩展方法 IsDiskFullException，实现如下：

/// <summary>
/// There is not enough space on the disk.
/// 磁盘空间不足。
/// </summary>
private static readonly int ERROR_DISK_FULL = 0x0070;

/// <summary>
/// 判断某个 <see cref="IOException"/> 是否是“磁盘空间不足”的异常。
/// </summary>
/// <param name="ex">IO 异常。</param>
/// <returns></returns>
public static bool IsDiskFullException(this IOException ex)
{
    var errorCode = ex.HResult & 0xFFFF;
    return errorCode == ERROR_DISK_FULL;
}

参考资料

• MS-ERREF: HRESULT - Microsoft Docs
• HRESULT - 维基百科，自由的百科全书
• The Microsoft Error Lookup Tool - Win32 apps - Microsoft Docs

本文会经常更新，请阅读原文： https://blog.walterlv.com/post/hresult-in-windows.html ，以避免陈旧错误知识的误导，同时有更好的阅读体验。

如果你想持续阅读我的最新博客，请点击 RSS 订阅，或者前往 CSDN 关注我的主页。

本作品采用 知识共享署名-非商业性使用-相同方式共享 4.0 国际许可协议 进行许可。欢迎转载、使用、重新发布，但务必保留文章署名 吕毅 （包含链接： https://blog.walterlv.com ），不得用于商业目的，基于本文修改后的作品务必以相同的许可发布。如有任何疑问，请 与我联系 (walter.lv@qq.com) 。