跳至內容

HRESULT

維基百科，自由的百科全書

在計算機編程領域中，HRESULT是一種在 Windows 作業系統中使用的資料類型，並且曾更早在 IBM/Microsoft OS/2 作業系統中使用。用來表示錯誤和警告的情況。

HRESULT的最初目的是為了防止OS/2作業系統的不同子系統中的錯誤代碼之間的衝突，正式地規定第三方和微軟內部使用的錯誤代碼範圍。它是基於數字的錯誤代碼，HRESULT中的各個位編碼包含有關錯誤代碼的性質及其來源的信息。

HRESULT 錯誤碼在COM編程領域很常見，它們構成了標準化的COM錯誤處理約定的基礎。

HRESULT 格式

HRESULT值有32位，分為三個字段：嚴重性代碼、設施代碼和錯誤代碼。嚴重性代碼指示返回值是表示信息、警告還是錯誤。設施代碼標識負責錯誤的系統區域。錯誤代碼是分配用於表示異常的唯一編號。 每個異常映射到不同的HRESULT。

HRESULT的結構如下：[1]

Bit 31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
Field S R C N X Facility Code

格式細節

  • S - 嚴重性 - 表示成功或失敗
    • 0 - 成功
    • 1 - 失敗
  • R - 設施代碼的保留部分，對應於NT的第二嚴重性位。
    • 1 - 嚴重故障
  • C - 第三方。 此位指定值是第三方定義還是Microsoft定義的。
    • 0 - Microsoft-定義
    • 1 - 第三方定義
  • N - 保留部分設施代碼。 用於指示映射的NT狀態值。
  • X - 保留部分設施代碼。 保留供內部使用。 用於指示不是狀態值的HRESULT值，而是用於顯示字符串的消息標識。
  • 設施 - 表示引發錯誤的系統服務. 示例設施代碼如下所示（完整列表請參見 ).
    • 1 - RPC
    • 2 - 調度（COM調度）
    • 3 - 存儲 (OLE 存儲)
    • 4 - ITF (COM/OLE 接口管理)
    • 7 - Win32 (原始 Win32 錯誤代碼)
    • 8 - Windows
    • 9 - SSPI
    • 10 - 控制
    • 11 - CERT (客戶端或伺服器認證)
    • ...
  • Code - 設施的狀態代碼

ITF設施代碼隨後被再次用作COM組件可以定義自己的組件特定錯誤代碼的範圍。

HRESULT 是如何工作的

HRESULT是一個不透明的結果句柄，定義為從函數成功返回為0或正值，對失敗為負值。一般的, 成功的函數返回 S_OK HRESULT 值 (這個HRESULT等於0)。但在極少數情況下，函數可能返回成功代碼與附加信息，例如S_FALSE=0x01。

當顯示HRESULT時，它們通常呈現為 無符號十六進制值, 通常用 0x 做前綴。在這種情況下，可以通過以十六進制數字8或更高開始來標識指示故障的數字。

HRESULT最初在IBM/Microsoft OS/2作業系統中作為一般目的的錯誤返回代碼，隨後在Windows NT中使用。 Microsoft Visual Basic 的大幅度增加HRESULT錯誤報告機制，通過關聯的一個 IErrorInfo 對象錯誤代碼，通過存儲指向一個IErrorInfoCOM對象的線程本地存儲。 IErrorInfo機制允許程序將各種信息與特定的HRESULT錯誤相關聯：引發錯誤的對象的類，引發錯誤的對象的接口，錯誤文本; 以及幫助文件中幫助主題的連結。 此外，HRESULT錯誤的接收器可以根據需要獲得錯誤消息的本地化文本。

隨後，HRESULT和相關聯的 IErrorInfo 機制用作COM中的默認錯誤報告機制。

在Windows中支持IErrorInfo機制是非常不一致的。 較舊的Windows API往往不支持它，返回HRESULTS沒有任何 IErrorInfo 數據。 更多的現代Windows COM子系統通常會在IErrorInfo對象的消息描述中提供大量的錯誤信息。 IErrorInfo錯誤機制的更高級功能——幫助連結和按需定位，很少使用。

在.NET Framework中，從本機代碼轉換為託管代碼時，HRESULT / IErrorInfo錯誤代碼將轉換為CLR異常; 當從託管轉換為本機COM代碼時，CLR異常將轉換為HRESULT / IErrorInfo錯誤代碼。

使用 HRESULT

winerror.h文件定義了一些通用的HRESULT值。 有些HRESULT值被硬編碼在給定子系統的關聯頭文件（.h文件）中。 這些值也使用Microsoft Windows平台SDK或DDK在相應的標題（.h）文件中定義。

要檢查返回HRESULT的調用是否成功，請確保S字段為0（即數字為非負數）或使用FAILED()。要獲取HRESULT的代碼部分，請使用HRESULT_CODE()。您還可以使用名為ERR.EXE的工具獲取值，並將其轉換為相應的錯誤字符串。 另一個名為ERRLOOK.EXE的工具也可用於顯示與給定HRESULT值相關聯的錯誤字符串。 可以在Visual Studio命令提示符下運行ERRLOOK.EXE。

Windows 原生的 SetErrorInfo 和 GetErrorInfo API 用於將 HRESULT 返回碼與對應的IErrorInfo對象相關聯。

FormatMessage API函數可用於將一些非IErrorInfo HRESULT轉換為用戶可讀的字符串。

示例

  • 0x80070005
    • 8 - 錯誤
    • 7 - Win32
    • 5 - "E_FAULT"
  • 0x80090032
    • 8 - 錯誤
    • 9 - SSPI
    • 32 - "此請求不被支持"[2]

引用

  1. ^ MSDN Windows Error Code reference （頁面存檔備份，存於互聯網檔案館）.
  2. ^ Win32 錯誤代碼

擴展連結

取自 "https://zh.wikipedia.org/w/index.php?title=HRESULT&oldid=82657778"