Windows 中的 HRESULT

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):

0 1 2 3 4 5~15 16~31
S R C N X Facility Code

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

Win32 错误码

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

1000 0000 0000 0111 0000 0000 0111 0000

所有的 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;
}

参考资料

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

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

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