訓練
錯誤
本節概述因為無法執行命令而造成 Windows Web 服務函式發生問題的錯誤。
一般規則是,如果函式失敗,則不會修改 out 參數的值。
如果函式失敗,有幾個實例會修改 out 參數。 每個參數的文件會明確指出這些案例。 如果檔未提及在失敗時修改參數的任何專案,您可以放心地假設函式不會修改它們。
所有錯誤傳回碼都是 HRESULT。 此 API 會在FACILITY_WEBSERVICES範圍中定義一組 HRESULT,但也會傳回 Windows API 中其他地方定義的錯誤。
請參閱特定 API 的檔,以了解傳回的錯誤碼。 此清單並非針對每個 API 完整,而是明確處理常見案例的錯誤碼清單。 呼叫端應該一律假設可從任何 API 取得其他錯誤碼。
此 API 會定義相對較少的錯誤碼,其對應到程式會根據錯誤採取動作的案例。 僅錯誤碼可能不足以判斷發生錯誤,或為使用者提供問題的良好描述。 對問題的最佳瞭解來自於使用豐富錯誤,如下所述。
除了傳回錯誤碼,呼叫端也可以藉由傳遞非 NULLWS_ERROR 對象,選擇性地要求任何 API 呼叫的豐富錯誤資訊。 若要建立錯誤物件,請使用 WsCreateError。 如果發生錯誤,造成錯誤的 API 會填入錯誤物件,並包含錯誤狀況的其他內容。 如果沒有錯誤,則錯誤物件不會修改。 傳遞 NULL 錯誤物件表示呼叫端對豐富的錯誤資訊不感興趣。 被呼叫者(包括回呼)必須準備好處理 NULL 錯誤物件。
請注意,相同的錯誤物件可用於多個 API 呼叫,但一次只能用於一個 API 呼叫(因為它是單個線程)。 每次發生錯誤時,錯誤資訊都會附加至錯誤物件。 當呼叫鏈結回溯時,多個函式可能會將資訊新增至錯誤物件,以提供有關錯誤的其他內容。 若要在重複使用錯誤之前清除錯誤對象的內容(發生錯誤之後),請使用 WsResetError。 如果沒有發生錯誤,就不需要在重複使用錯誤物件之前重設錯誤物件。
豐富的錯誤資訊包含下列各項:
- 一組屬性值,提供錯誤的其他資訊。 請參閱 WS_ERROR_PROPERTY。
- 零個或多個錯誤字串。 字串會使用 WsAddErrorString 新增,而且可以使用 WsGetErrorString 來查詢。 您可以使用 WS_ERROR_PROPERTY_STRING_COUNT來查詢字串數目。
如需錯誤和錯誤關聯方式的相關信息,請參閱 錯誤 。
建立錯誤物件時,會指定所需語言翻譯的 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 使用方式,而且在其他情況下不會傳回。 如果傳回這些錯誤中的任何一個,可能是應用程式 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值 時,錯誤物件的使用者應該非常小心,因為產生的錯誤可能包含在錯誤記錄過程中累積的私人資訊。