取消

Windows 中的 HRESULT

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


一个简单的例子

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

1
0x80070070

将它改写成二进制:

1
1000 0000 0000 0111 0000 0000 0111 0000

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

规范中的 HRESULT

按照规范,HRESULT 的格式如下,其中首行的数字代表第几位(bit):

012345~1516~31
SRCNXFacilityCode
  • 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 错误码

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

1
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 操作中处理好磁盘空间已满的情况:

1
2
3
4
5
6
7
8
9
10
11
12
try
{
    SaveFile(fileContent, filePath);
}
catch (IOException ex)
{
    if (ex.IsDiskFullException())
    {
        // 磁盘空间已满。
        break;
    }
}

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
/// <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;
}

参考资料

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

知识共享许可协议

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

登录 GitHub 账号进行评论