错误

本部分概述了 Windows Web 服务函数因执行命令失败而可能出现问题的错误。

• Out 参数
• 错误代码
• Rich 错误
• 故障和错误
• 语言敏感错误信息
• 规范错误代码
• API 用法无效
• 安全性

Out 参数

一般情况下，如果函数失败，则不修改 out 参数的值。

少数几个示例存在函数失败时修改 out 参数的情况。 每个参数的文档中已显示标注这些情况。 如果文档未提及在发生故障时修改 out 参数的任何内容，则可以安全地假定该函数不会修改这些参数。

错误代码

所有错误返回代码都是 HRESULT。 此 API 在 FACILITY_WEBSERVICES 范围内定义了一组 HRESULT，但也会返回在 Windows API 中其他位置定义的错误。

请参阅特定 API 的文档，以了解返回的错误代码。 该列表并非针对每个 API 详尽列出，而是面向要进行显式处理的常见方案的错误代码列表。 调用方应始终假定可以从任何 API 获取其他错误代码。

此 API 定义的错误代码数量相对较少，这些错误代码对应于程序希望根据错误执行操作的方案。 仅有错误代码可能不足以确定出了什么问题，或不足以向用户提供问题的详细说明。 对问题的最佳理解来自使用 Rich 错误，如下所述。

Rich 错误

除了返回错误代码，调用方还可以选择通过传递非“NULL”WS_ERROR 对象来请求任何 API 调用的 rich 错误信息。 要创建错误对象，请使用“WsCreateError”。 如果出现错误，则导致错误的 API 将使用有关错误情况的其他上下文填充错误对象。 如果未出现错误，则错误对象会处于未修改状态。 传递“NULL”错误对象指示调用方对 rich 错误信息不感兴趣。 调用方（包括回调）必须准备好处理“NULL”错误对象。

请注意，相同的错误对象可用于多个 API 调用，但可能一次只能用于一个 API 调用（因为它是单线程的）。 每次发生错误时，错误信息都会追加到错误对象。 当调用链展开时，多个函数可能会向错误对象添加信息，以提供有关错误的附加上下文。 要在重用错误对象之前清除错误对象的内容（发生错误后），请使用“WsResetError”。 如果未发生错误，则不需要在重用错误对象之前重置它。

Rich 错误信息包括以下内容：

• 一组属性值，可提供有关错误的其他信息（如果存在）。 请参阅“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 用法

以下错误代码保留为无效的 API 用法，并且在其他情况下不会返回。 如果返回这些错误中的任何一个，则可能表示应用程序存在 bug。

• “WS_E_INVALID_OPERATION”
• E_INVALIDARG

以下枚举是跟踪的一部分：

• “WS_ERROR_PROPERTY_ID”
• “WS_EXCEPTION_CODE”

以下错误代码是跟踪的一部分：

• “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_ERROR_PROPERTY_ID”
• “WS_EXCEPTION_CODE”

以下句柄是跟踪的一部分：

• “WS_ERROR”

以下结构是跟踪的一部分：

• “WS_ERROR_PROPERTY”

安全性

错误对象的用户应当了解许多安全注意事项：

• 错误对象可能包含不受信任的数据。 例如：WS_FAULT 和错误字符串，这两个字符串都可以根据通过不受信任的通道接收的信息存储在错误对象中。 检查错误对象中的信息并根据错误对象的值做出决策时，错误对象的用户应谨慎操作。
• 在检查有关错误的信息后，错误对象的用户应调用“WsResetError”。 如果未能执行此操作，可能会导致内存堆积。
• 使用“WS_FAULT_DISCLOSURE”枚举的WS_FULL_FAULT_DISCLOSURE 值时，错误对象的用户应谨慎操作，因为生成的错误可能包含在错误记录过程中累积的私密信息。