エラー

  • [アーティクル]

このセクションでは、コマンド実行失敗の結果として、Windows Web サービスの関数によって発行される可能性があるエラーの概要について説明します。

out パラメーター

一般的なルールとして、関数が失敗した場合、out パラメーターの値は変更されません。

関数が失敗しても out パラメーターが変更される場合がいくつかあります。 このようなケースは、各パラメーターのドキュメントに明確に書かれています。 失敗した場合の out パラメーターの変更についてドキュメントで言及されていない場合は、関数によってそれが変更されないと想定しても安全です。

エラー コード

すべてのエラーのリターン コードは HRESULT です。 この API の一連の HRESULT は FACILITY_WEBSERVICES の範囲で定義されていますが、Windows API の他の場所で定義されているエラーも返されます。

返されるエラー コードについては、特定の API のドキュメントをご覧ください。 この一覧は、各 API について網羅することを意図したものではなく、明示的な処理のための一般的なシナリオがあるエラー コードの一覧です。 呼び出し元は常に、どの API からも他のエラー コードが返される可能性があることを想定する必要があります。

この API で定義されているエラー コードは比較的少く、プログラムでエラーに基づくアクションを実行する必要があるシナリオに対応しています。 何が間違っていたのかを特定したり、問題の適切な説明をユーザーに提供したりするには、エラー コードだけでは不十分な場合があります。 以下で説明するように、リッチ エラーを使うと問題を最もよく理解できます。

リッチ エラー

呼び出し元は、エラー コードを受け取るだけでなく、必要に応じて NULL ではない WS_ERROR オブジェクトを渡すことにより、API 呼び出しに関する詳細なエラー情報を要求できます。 エラー オブジェクトを作成するには、WsCreateError を使います。 エラーがある場合、エラーの原因となった API によって、エラー状況に関する追加のコンテキストがエラー オブジェクトに設定されます。 エラーがない場合、エラー オブジェクトは変更されません。 NULL エラー オブジェクトを渡すと、呼び出し元が詳細なエラー情報に関心がないことを示します。 呼び出し先 (コールバックを含む) は、NULL エラー オブジェクトを処理できるようにしておく必要があります。

同じエラー オブジェクトを複数の API 呼び出しに使用できますが、使用できる API 呼び出しは一度に 1 つのみであることに注意する必要があります (シングル スレッドであるため)。 エラーが発生するたびに、エラー情報がエラー オブジェクトに追加されます。 呼び出しチェーンがアンワインドする際、複数の関数が、エラーに関する追加コンテキストを提供するため、エラー オブジェクトに情報を追加する場合があります。 (エラーが発生した後で) エラー オブジェクトを再利用する前にその内容をクリアするには、WsResetError を使います。 エラーが発生していない場合は、エラー オブジェクトを再利用する前にリセットする必要はありません。

リッチ エラー情報は次のもので構成されます。

  • エラーが存在する場合にそれに関する追加情報を提供する一連のプロパティ値。 WS_ERROR_PROPERTY に関する記事をご覧ください。
  • 0 個以上のエラー文字列。 文字列は WsAddErrorString を使って追加され、WsGetErrorString を使ってそのクエリを実行できます。 文字列の数のクエリは、WS_ERROR_PROPERTY_STRING_COUNT を使って実行できます。

障害とエラー

エラーと障害の関係については、「障害」をご覧ください。

言語に依存するエラー情報

エラー オブジェクトを作成するときに、エラー情報を翻訳する言語の LANGID を指定します。 エラー情報をエラー オブジェクトに追加するときに、これが使われます。

この言語値は、WS_ERROR_PROPERTY_LANGID を使って取得または設定できます。

正規エラー コード

この API では、基になる特定の実装の特定のエラー コードに依存することなく、さまざまな通信テクノロジを使用できるようにする、正規のエラー コード セット (WS_E_*) が提供されます。 これらのエラー コードの完全な一覧については、「Windows Web サービスの戻り値」をご覧ください。

これにより、たとえば、TCP、UDP、または HTTP のいずれが使われていても、プログラムでエラー コード WS_E_ENDPOINT_NOT_FOUND を調べて、何らかのアクション (別のエンドポイントの使用を試みる、など) を実行できます。

実装固有のエラー コードが正規エラーにマップされている場合、元のエラー コードがエラー オブジェクトに保存され、診断のために引き続きアクセスできます。 詳しくは、WS_ERROR_PROPERTY_ORIGINAL_ERROR_CODE に関する記事をご覧ください。

無効な API の使用

次のエラー コードは無効な API の使用のために予約されており、他の状況では返されません。 これらのエラーのいずれかが返された場合は、アプリケーションのバグを示している可能性があります。

  • 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 値を使うときは、エラー記録プロセスの一部として蓄積された個人情報が生成されたエラーに含まれる可能性があるため、十分に注意する必要があります。