錯誤

  • 發行項

本節概述因為無法執行命令而造成 Windows Web 服務函式發生問題的錯誤。

Out 參數

一般規則是，如果函式失敗，則不會修改 out 參數的值。

如果函式失敗，有幾個實例會修改 out 參數。 每個參數的文件會明確指出這些案例。 如果檔未提及在失敗時修改參數的任何專案，您可以放心地假設函式不會修改它們。

錯誤代碼

所有錯誤傳回碼都是 HRESULT。 此 API 會在FACILITY_WEBSERVICES範圍中定義一組 HRESULT，但也會傳回 Windows API 中其他地方定義的錯誤。

請參閱特定 API 的檔，以了解傳回的錯誤碼。 此清單並非針對每個 API 完整，而是明確處理常見案例的錯誤碼清單。 呼叫端應該一律假設可從任何 API 取得其他錯誤碼。

此 API 會定義相對較少的錯誤碼，其對應到程式會根據錯誤採取動作的案例。 僅錯誤碼可能不足以判斷發生錯誤，或為使用者提供問題的良好描述。 對問題的最佳瞭解來自於使用豐富錯誤，如下所述。

豐富錯誤

除了傳回錯誤碼，呼叫端也可以藉由傳遞非 NULLWS_ERROR 對象，選擇性地要求任何 API 呼叫的豐富錯誤資訊。 若要建立錯誤物件，請使用 WsCreateError。 如果發生錯誤，造成錯誤的 API 會填入錯誤物件，並包含錯誤狀況的其他內容。 如果沒有錯誤，則錯誤物件不會修改。 傳遞 NULL 錯誤物件表示呼叫端對豐富的錯誤資訊不感興趣。 被呼叫者（包括回呼）必須準備好處理 NULL 錯誤物件。

請注意，相同的錯誤物件可用於多個 API 呼叫，但一次只能用於一個 API 呼叫（因為它是單個線程）。 每次發生錯誤時，錯誤資訊都會附加至錯誤物件。 當呼叫鏈結回溯時，多個函式可能會將資訊新增至錯誤物件，以提供有關錯誤的其他內容。 若要在重複使用錯誤之前清除錯誤對象的內容（發生錯誤之後），請使用 WsResetError。 如果沒有發生錯誤，就不需要在重複使用錯誤物件之前重設錯誤物件。

豐富的錯誤資訊包含下列各項：

錯誤和錯誤

如需錯誤和錯誤關聯方式的相關信息，請參閱 錯誤 。

語言敏感性錯誤資訊

建立錯誤物件時，會指定所需語言翻譯的 LANGID 以取得錯誤資訊。 將錯誤資訊新增至錯誤物件時，會使用此方式。

您可以使用 WS_ERROR_PROPERTY_LANGID來擷取或設定此語言值。

標準錯誤碼

此 API 提供一組標準的錯誤碼（WS_E_*），允許使用不同的通訊技術，而不需要依賴特定基礎實作的特定錯誤碼。 如需這些錯誤碼的完整清單，請參閱 Windows Web 服務傳回值。

例如，這可讓程式檢查錯誤碼 WS_E_ENDPOINT_NOT_FOUND 是否使用 TCP、UDP 或 HTTP，並採取一些動作（例如嘗試使用不同的端點）。

當實作特定的錯誤碼對應至標準錯誤時，原始錯誤碼會儲存在錯誤物件中，而且可能仍可進行診斷。 如需詳細資訊，請參閱 WS_ERROR_PROPERTY_ORIGINAL_ERROR_CODE 。

無效的 API 使用方式

下列錯誤碼會保留給無效的 API 使用方式，而且在其他情況下不會傳回。 如果傳回這些錯誤中的任何一個，可能是應用程式 Bug 的指示。

  • WS_E_INVALID_OPERATION
  • E_INVALIDARG

下列列舉是追蹤的一部分：

下列錯誤碼是追蹤的一部分：

  • CERT_E_CN_NO_MATCH
  • CERT_E_EXPIRED
  • CERT_E_UNTRUSTEDROOT
  • CERT_E_WRONG_USAGE
  • CRYPT_E_REVOCATION_OFFLINE
  • E_INVALIDARG
  • E_OUTOFMEMORY
  • WS_E_ADDRESS_IN_USE
  • WS_E_ADDRESS_NOT_AVAILABLE
  • WS_E_ENDPOINT_ACCESS_DENIED
  • WS_E_ENDPOINT_ACTION_NOT_SUPPORTED
  • WS_E_ENDPOINT_DISCONNECTED
  • WS_E_ENDPOINT_FAILURE
  • WS_E_ENDPOINT_FAULT_RECEIVED
  • WS_E_ENDPOINT_NOT_AVAILABLE
  • WS_E_ENDPOINT_NOT_FOUND
  • WS_E_ENDPOINT_TOO_BUSY
  • WS_E_ENDPOINT_UNREACHABLE
  • WS_E_INVALID_ENDPOINT_URL
  • WS_E_INVALID_FORMAT
  • WS_E_INVALID_OPERATION
  • WS_E_NOT_SUPPORTED
  • WS_E_NO_TRANSLATION_AVAILABLE
  • WS_E_NUMERIC_OVERFLOW
  • WS_E_OBJECT_FAULTED
  • WS_E_OPERATION_ABANDONED
  • WS_E_OPERATION_ABORTED
  • WS_E_OPERATION_TIMED_OUT
  • WS_E_OTHER
  • WS_E_PROXY_ACCESS_DENIED
  • WS_E_PROXY_FAILURE
  • WS_E_PROXY_REQUIRES_BASIC_AUTH
  • WS_E_PROXY_REQUIRES_DIGEST_AUTH
  • WS_E_PROXY_REQUIRES_NEGOTIATE_AUTH
  • WS_E_PROXY_REQUIRES_NTLM_AUTH
  • WS_E_QUOTA_EXCEEDED
  • WS_E_SECURITY_SYSTEM_FAILURE
  • WS_E_SECURITY_TOKEN_EXPIRED
  • WS_E_SECURITY_VERIFICATION_FAILURE
  • WS_E_SERVER_REQUIRES_BASIC_AUTH
  • WS_E_SERVER_REQUIRES_DIGEST_AUTH
  • WS_E_SERVER_REQUIRES_NEGOTIATE_AUTH
  • WS_E_SERVER_REQUIRES_NTLM_AUTH
  • WS_S_ASYNC
  • WS_S_END

下列函式是追蹤的一部分：

下列控制碼是追蹤的一部分：

下列結構是追蹤的一部分：

安全性

有一些安全性考慮，錯誤物件的使用者應該注意：

  • 錯誤物件可能包含不受信任的資料。 例如：WS_FAULT和錯誤字串，這兩者都可以根據透過不受信任的通道接收的資訊，儲存在錯誤物件中。 檢查錯誤物件中的資訊，並根據其值做出決策時，應該小心錯誤物件的使用者。
  • 錯誤物件的使用者應該在檢查錯誤的相關資訊之後呼叫 WsResetError 。 若無法這麼做，可能會導致記憶體累積。
  • 使用WS_FAULT_DISCLOSURE 列舉的WS_FULL_FAULT_DISCLOSURE值 時，錯誤物件的使用者應該非常小心，因為產生的錯誤可能包含在錯誤記錄過程中累積的私人資訊。